code/yieldomega
Watch
4
0
Fork
You've already forked yieldomega
 0
Code Issues 1 Pull requests 1 Projects Releases Packages Wiki Activity

Kumbaya: docs cross-links, env deployments, integrator-kit contracts, TimeCurve purchase path (ETH/USDM → CHARM/CL8Y) #46

New issue
Closed
opened 2026-04-23 03:12:31 +00:00 by PlasticDigits · 8 comments
PlasticDigits commented 2026-04-23 03:12:31 +00:00 (Migrated from gitlab.com)

Summary

Improve how we document, deploy, and integrate Kumbaya so Yieldomega stays aligned with upstream guidance and gives users a clearer path to acquire CHARM (including CL8Y / TimeCurve-relevant flows) using ETH and USDM where the protocol allows.

Documentation & cross-linking

  • Audit all in-repo references to Kumbaya (README, ops/runbooks, contract comments, frontend copy, env examples).
  • Add explicit cross-links to Kumbaya’s official documentation wherever we describe behavior, addresses, or integration steps (avoid stale or implicit assumptions).
  • Ensure contributors can trace: what we call things ↔ what Kumbaya’s docs call things ↔ on-chain contracts we rely on.

Deployment process by environment

Define and document a repeatable process for:

Environment Expectations
Localnet How to stand up or point at Kumbaya-related contracts locally; what is mocked vs real; how to verify.
Testnet How we deploy/configure; which addresses and ABIs we use; smoke checks.
Mainnet Same as testnet, with production safeguards and address verification.

For testnet and mainnet, use Kumbaya’s official contract references and artifacts from their integrator kit rather than ad-hoc copies:

Deliverables should include where in our repo we pin or reference those addresses/ABIs (or a single source of truth doc) so drift is obvious.

Product / integration refactor (where possible)

  • Refactor the Kumbaya integration so that, where the stack supports it, users can use ETH and USDM to buy CHARM with flows that surface cleanly in TimeCurve (including CL8Y-relevant purchase paths—directly in TimeCurve UX/flow where “directly” is feasible without breaking protocol assumptions).
  • Call out any hard protocol limits (e.g. tokens/routes not supported by Kumbaya or our contracts) so scope stays honest.

Acceptance criteria

  • Docs cross-linked to Kumbaya’s official docs for every user-facing or operator-facing Kumbaya mention that needs it.
  • Documented localnet, testnet, and mainnet deployment/runbook steps for Kumbaya-related configuration.
  • Testnet and mainnet contract usage aligned with integrator-kit (addresses/ABIs/version notes).
  • Clear plan or implementation for ETH/USDM → CHARM (incl. CL8Y / TimeCurve) where possible, with gaps explicitly listed.

Notes

  • Issue scope is planning + docs + integration design; link child issues/PRs as implementation work is split out.

Assignee note: Requested assignee plasticdigtis was not found on GitLab; assigned @PlasticDigits instead (project namespace owner). If a different username was intended, please reassign.

## Summary Improve how we document, deploy, and integrate **Kumbaya** so Yieldomega stays aligned with upstream guidance and gives users a clearer path to acquire **CHARM** (including **CL8Y** / TimeCurve-relevant flows) using **ETH** and **USDM** where the protocol allows. ## Documentation & cross-linking - Audit all in-repo references to Kumbaya (README, ops/runbooks, contract comments, frontend copy, env examples). - Add explicit cross-links to **Kumbaya’s official documentation** wherever we describe behavior, addresses, or integration steps (avoid stale or implicit assumptions). - Ensure contributors can trace: *what we call things* ↔ *what Kumbaya’s docs call things* ↔ *on-chain contracts we rely on*. ## Deployment process by environment Define and document a repeatable process for: | Environment | Expectations | |-------------|--------------| | **Localnet** | How to stand up or point at Kumbaya-related contracts locally; what is mocked vs real; how to verify. | | **Testnet** | How we deploy/configure; which addresses and ABIs we use; smoke checks. | | **Mainnet** | Same as testnet, with production safeguards and address verification. | For **testnet** and **mainnet**, **use Kumbaya’s official contract references and artifacts from their integrator kit** rather than ad-hoc copies: - **Upstream:** [Kumbaya-xyz/integrator-kit](https://github.com/Kumbaya-xyz/integrator-kit) Deliverables should include where in our repo we pin or reference those addresses/ABIs (or a single source of truth doc) so drift is obvious. ## Product / integration refactor (where possible) - Refactor the Kumbaya integration so that, **where the stack supports it**, users can **use ETH and USDM to buy CHARM** with flows that surface cleanly in **TimeCurve** (including **CL8Y**-relevant purchase paths—directly in TimeCurve UX/flow where “directly” is feasible without breaking protocol assumptions). - Call out any **hard protocol limits** (e.g. tokens/routes not supported by Kumbaya or our contracts) so scope stays honest. ## Acceptance criteria - [ ] Docs cross-linked to Kumbaya’s official docs for every user-facing or operator-facing Kumbaya mention that needs it. - [ ] Documented **localnet**, **testnet**, and **mainnet** deployment/runbook steps for Kumbaya-related configuration. - [ ] **Testnet** and **mainnet** contract usage aligned with [integrator-kit](https://github.com/Kumbaya-xyz/integrator-kit) (addresses/ABIs/version notes). - [ ] Clear plan or implementation for **ETH/USDM → CHARM** (incl. **CL8Y** / TimeCurve) where possible, with gaps explicitly listed. ## Notes - Issue scope is **planning + docs + integration design**; link child issues/PRs as implementation work is split out. --- **Assignee note:** Requested assignee `plasticdigtis` was not found on GitLab; assigned **@PlasticDigits** instead (project namespace owner). If a different username was intended, please reassign.
PlasticDigits commented 2026-04-23 03:12:31 +00:00 (Migrated from gitlab.com)

assigned to @PlasticDigits

assigned to @PlasticDigits
PlasticDigits commented 2026-04-23 05:34:06 +00:00 (Migrated from gitlab.com)

mentioned in issue #41

mentioned in issue #41
PlasticDigits commented 2026-04-23 05:37:38 +00:00 (Migrated from gitlab.com)

mentioned in commit 94c990948a

mentioned in commit 94c990948a686ad9422a6184df4a34051e357c7d
PlasticDigits commented 2026-04-23 05:38:06 +00:00 (Migrated from gitlab.com)

@brouie Please verify the GitLab #46 deliverable merged to main (commit `93ad90f` on `main`).

What shipped

  • Single integration doc: docs/integrations/kumbaya.md — upstream Kumbaya-xyz/integrator-kit + default-token-list, localnet / testnet / mainnet runbooks, invariants, ETH·stable→CL8Y→CHARM flow, honest protocol limits.
  • MegaETH defaults in code: `frontend/src/lib/kumbayaRoutes.ts` now bakes 4326 (SwapRouter02, QuoterV2, WETH9, USDm) and 6343 (router/quoter/weth; stable requires `VITE_KUMBAYA_USDM` + pools) from integrator-kit JSON — re-diff upstream before prod if their `addresses/*.json` moves.
  • Cross-links: `docs/README.md`, `docs/testing/` (e2e-anvil, local-swap-testing, invariants-and-business-logic + test map), `.cursor/skills/`, `frontend/.env.example`, `DeployKumbayaAnvilFixtures` NatSpec, `anvil_deploy_dev.sh`.
  • Tests: `frontend/src/lib/kumbayaRoutes.test.ts` (Vitest) — `npm test -- --run src/lib/kumbayaRoutes.test.ts` (13 tests) after `npm ci`.

Checklist for you

  • Read `docs/integrations/kumbaya.md` and confirm terminology (USDm vs env key `USDM`) matches how you want operators briefed.
  • Spot-check 4326 / 6343 addresses against current integrator-kit `addresses/` `megaETH-*.json`.
  • Confirm USDm `0xFAfD…79E7` on mainnet still matches default-token-list `megaeth.json`.
  • On 6343, confirm expectation: USDM pay mode stays fail closed until `VITE_KUMBAYA_USDM` + real CL8Y/WETH/stable pools at configured fee tiers.
  • Run frontend unit slice above (or full `npm test` in `frontend/`) on your machine.
  • Optional: smoke quote → swap → buy on testnet per the runbook (small notional).

Worktree `fix/gitlab-46-kumbaya-docs` was merged and removed locally after push.

@brouie Please verify the **GitLab #46** deliverable merged to `main` (commit \`93ad90f\` on \`main\`). ## What shipped - **Single integration doc:** [docs/integrations/kumbaya.md](https://gitlab.com/PlasticDigits/yieldomega/-/blob/main/docs/integrations/kumbaya.md) — upstream [Kumbaya-xyz/integrator-kit](https://github.com/Kumbaya-xyz/integrator-kit) + default-token-list, **localnet / testnet / mainnet** runbooks, **invariants**, ETH·stable→CL8Y→**CHARM** flow, honest protocol limits. - **MegaETH defaults in code:** \`frontend/src/lib/kumbayaRoutes.ts\` now bakes **4326** (SwapRouter02, QuoterV2, WETH9, **USDm**) and **6343** (router/quoter/weth; stable requires \`VITE_KUMBAYA_USDM\` + pools) from integrator-kit JSON — re-diff upstream before prod if their \`addresses/*.json\` moves. - **Cross-links:** \`docs/README.md\`, \`docs/testing/*\` (e2e-anvil, local-swap-testing, **invariants-and-business-logic** + test map), \`.cursor/skills/*\`, \`frontend/.env.example\`, \`DeployKumbayaAnvilFixtures\` NatSpec, \`anvil_deploy_dev.sh\`. - **Tests:** \`frontend/src/lib/kumbayaRoutes.test.ts\` (Vitest) — \`npm test -- --run src/lib/kumbayaRoutes.test.ts\` (13 tests) after \`npm ci\`. ## Checklist for you - [ ] Read \`docs/integrations/kumbaya.md\` and confirm terminology (**USDm** vs env key \`USDM\`) matches how you want operators briefed. - [ ] Spot-check **4326** / **6343** addresses against current [integrator-kit \`addresses/\`](https://github.com/Kumbaya-xyz/integrator-kit/tree/main/addresses) \`megaETH-*.json\`. - [ ] Confirm **USDm** \`0xFAfD…79E7\` on mainnet still matches [default-token-list \`megaeth.json\`](https://github.com/Kumbaya-xyz/default-token-list/blob/main/src/tokens/megaeth.json). - [ ] On **6343**, confirm expectation: **USDM pay mode** stays **fail closed** until \`VITE_KUMBAYA_USDM\` + real CL8Y/WETH/stable pools at configured fee tiers. - [ ] Run frontend unit slice above (or full \`npm test\` in \`frontend/\`) on your machine. - [ ] Optional: smoke **quote → swap → buy** on testnet per the runbook (small notional). Worktree \`fix/gitlab-46-kumbaya-docs\` was merged and removed locally after push.
Brouie commented 2026-04-24 06:28:15 +00:00 (Migrated from gitlab.com)

@PlasticDigits verified on dec166e / merge 93ad90f. All 5 required checklist items confirmed:

Item 1 — Terminology: PASS

Read docs/integrations/kumbaya.md (85 lines). The doc clearly distinguishes the code label usdm (lowercase, the PayWithAsset / VITE_KUMBAYA_USDM env key) from the actual token symbol USDm (MegaUSD per default-token-list on mainnet). Terminology section reads cleanly for an operator briefing.

Item 2 — Address parity: PASS

Spot-check against upstream integrator-kit addresses/megaETH-{mainnet,testnet}.json:

Mainnet 4326:

  • WETH9: 0x4200000000000000000000000000000000000006 ✅
  • SwapRouter02: 0xE5BbEF8De2DB447a7432A47EBa58924d94eE470e ✅
  • QuoterV2: 0x1F1a8dC7E138C34b503Ca080962aC10B75384a27 ✅

Testnet 6343:

  • WETH9: 0x4200000000000000000000000000000000000006 ✅
  • SwapRouter02: 0x8268DC930BA98759E916DEd4c9F367A844814023 ✅
  • QuoterV2: 0xfb230b93803F90238cB03f254452bA3a3b0Ec38d ✅

Item 3 — USDm match: PASS

default-token-list src/tokens/megaeth.json has USDm (MegaUSD) at 0xFAfDdbb3FC7688494971a79cc65DCa3EF82079E7 on chainId 4326 — exact match with kumbayaRoutes.ts line 85.

Item 4 — Testnet USDM fail-closed: PASS

Traced the path: on 6343, defaults.usdm is undefined (line 71-77 omits usdm key), usdm = envAddr('VITE_KUMBAYA_USDM') ?? defaults.usdm resolves to undefined, falls to ZERO at line 142. Then at line 203-209 the route builder for payWith='usdm' hits isZeroAddr(config.usdm) and returns { ok: false, reason: 'missing_usdm', message: 'USDM is not configured for this chain.' }. No silent fallback, no partial execution. Correct fail-closed.

Item 5 — Unit tests: PASS

cd frontend && npm test -- --run src/lib/kumbayaRoutes.test.ts → 13/13 passing, 975ms.

Item 6 — Optional testnet smoke: skipped

Not attempted this session. Can be added as a separate verification pass once real USDM pools are deployed and VITE_KUMBAYA_USDM is configured on a testnet build — at that point the full quote → swap → buy path becomes live-testable. For now the code + unit coverage + address parity is comprehensive.

Doc quality notes

  • docs/integrations/kumbaya.md sections on upstream refs, naming, product flow, invariants, and env runbooks are well-structured for future contributors.
  • 'Hard limits (honest scope)' section correctly calls out that UniversalRouter paths differ from Anvil fixture — worth preserving as it prevents integration-time surprises.
  • Integrator-kit drift note ('re-diff against main of integrator-kit repo before prod') is a good contributor guardrail.

Closing as verified.

@PlasticDigits verified on `dec166e` / merge `93ad90f`. All 5 required checklist items confirmed: ## Item 1 — Terminology: PASS Read `docs/integrations/kumbaya.md` (85 lines). The doc clearly distinguishes the code label `usdm` (lowercase, the `PayWithAsset` / `VITE_KUMBAYA_USDM` env key) from the actual token symbol **USDm** (MegaUSD per default-token-list on mainnet). Terminology section reads cleanly for an operator briefing. ## Item 2 — Address parity: PASS Spot-check against upstream integrator-kit addresses/megaETH-{mainnet,testnet}.json: **Mainnet 4326:** - WETH9: `0x4200000000000000000000000000000000000006` ✅ - SwapRouter02: `0xE5BbEF8De2DB447a7432A47EBa58924d94eE470e` ✅ - QuoterV2: `0x1F1a8dC7E138C34b503Ca080962aC10B75384a27` ✅ **Testnet 6343:** - WETH9: `0x4200000000000000000000000000000000000006` ✅ - SwapRouter02: `0x8268DC930BA98759E916DEd4c9F367A844814023` ✅ - QuoterV2: `0xfb230b93803F90238cB03f254452bA3a3b0Ec38d` ✅ ## Item 3 — USDm match: PASS default-token-list src/tokens/megaeth.json has USDm (MegaUSD) at `0xFAfDdbb3FC7688494971a79cc65DCa3EF82079E7` on chainId 4326 — exact match with `kumbayaRoutes.ts` line 85. ## Item 4 — Testnet USDM fail-closed: PASS Traced the path: on 6343, `defaults.usdm` is undefined (line 71-77 omits usdm key), `usdm = envAddr('VITE_KUMBAYA_USDM') ?? defaults.usdm` resolves to undefined, falls to `ZERO` at line 142. Then at line 203-209 the route builder for payWith='usdm' hits `isZeroAddr(config.usdm)` and returns `{ ok: false, reason: 'missing_usdm', message: 'USDM is not configured for this chain.' }`. No silent fallback, no partial execution. Correct fail-closed. ## Item 5 — Unit tests: PASS `cd frontend && npm test -- --run src/lib/kumbayaRoutes.test.ts` → 13/13 passing, 975ms. ## Item 6 — Optional testnet smoke: skipped Not attempted this session. Can be added as a separate verification pass once real USDM pools are deployed and `VITE_KUMBAYA_USDM` is configured on a testnet build — at that point the full quote → swap → buy path becomes live-testable. For now the code + unit coverage + address parity is comprehensive. ## Doc quality notes - `docs/integrations/kumbaya.md` sections on upstream refs, naming, product flow, invariants, and env runbooks are well-structured for future contributors. - 'Hard limits (honest scope)' section correctly calls out that UniversalRouter paths differ from Anvil fixture — worth preserving as it prevents integration-time surprises. - Integrator-kit drift note ('re-diff against main of integrator-kit repo before prod') is a good contributor guardrail. Closing as verified.
Brouie (Migrated from gitlab.com) closed this issue 2026-04-24 06:28:16 +00:00
PlasticDigits commented 2026-04-26 05:28:28 +00:00 (Migrated from gitlab.com)

mentioned in issue #65

mentioned in issue #65
PlasticDigits commented 2026-05-13 16:03:46 +00:00 (Migrated from gitlab.com)

mentioned in issue #206

mentioned in issue #206
PlasticDigits commented 2026-05-13 16:07:17 +00:00 (Migrated from gitlab.com)

mentioned in issue #207

mentioned in issue #207
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
cac-design-issue-544
renovate/configure
No results found.
Labels
Clear labels   
agent:fix_bugfix

   
agent:fix_conflicts

   
agent:fix_security

   
agent:gap_analysis

   
agent:implement

   
agent:open_issues

   
agents

   
agent:security_audit

   
agent:verify
  
area
timecurve

  
arena

   
arena-v2

   
audit

   
block:feature_review

   
block:security

   
bug

   
contracts

   
design

   
devops

   
docs
Documentation

  
documentation

   
enhancement

   
epic
Epic / umbrella issue

  
feature

   
frontend

   
indexer

   
low priority
Low priority, investigate other issues first

  
megaeth

   
operations

   
ops
Deploy and operations

  
performance

   
QA

   
qa checklist

   
referrals

   
removal
Legacy removal

  
security

   
smart-contracts

   
tech-debt

   
testing

   
time-arena
TimeArena v2 revamp

  
timecurve

   
visual-qa
No labels
agent:fix_bugfix
agent:fix_conflicts
agent:fix_security
agent:gap_analysis
agent:implement
agent:open_issues
agents
agent:security_audit
agent:verify
area
timecurve
arena
arena-v2
audit
block:feature_review
block:security
bug
contracts
design
devops
docs
documentation
enhancement
epic
feature
frontend
indexer
low priority
megaeth
operations
ops
performance
QA
qa checklist
referrals
removal
security
smart-contracts
tech-debt
testing
time-arena
timecurve
visual-qa
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
code/yieldomega#46
No description provided.