Skip to content

cogni-dao/cogni / .claude/skills/payments-expert

payments-expert

Verified

Use whenever working on Cogni USDC credit top-ups, payment intent creation, payment activation, operator wallet funding, 0xSplits allocations, x402 outbound provider payments, Hyperbolic, EIP-3009 signatures, retired OpenRouter/Coinbase top-ups, system-tenant revenue share, repo-spec payment config, live payment rail guards, payment CI failures, or debugging money-loop behavior. Trigger on phrases like payments, payment rail, credits top-up, USDC, Split, 0xSplits, splitHash, x402, Hyperbolic, facilitator, signX402Payment, EIP-3009, OpenRouter funding, Coinbase Commerce, operator wallet, Privy wallet, markup_factor, revenue_share, system bonus, provider top-up, settlement_skipped, SPLIT_CONFIG_MISMATCH, activate payments, node payments, or "is this payment behavior validated". This skill is the launching point for future payments work and debugging.

Payments Expert

Route the work through operator-architect first; this skill adds the payment rail rules on top of it.

Use this as the orientation layer before changing or validating Cogni payment rails. The core failure to avoid is calling a config/startup proof a money-loop proof. Payments are live only when the repo-spec economics, deployed Split, payment-intent guard, settlement path, and observed ledger/provider effects all agree.

First Rule

Do not claim payment behavior is validated from /readyz, startup guards, static config, or unit tests. Those prove boot/config/code paths. Live payment rail validation means:

  1. payment-intent creation fails closed when the configured Split is missing or mismatched;
  2. payment-intent creation succeeds only after repo-spec points at a matching deployed Split;
  3. one real purchase proves user credits, system bonus, provider top-up, DAO margin, and settlement logs.

Candidate/preview may prove the guard and inbound crediting, but may not prove outbound settlement if the operator wallet/provider funding credentials are absent. Watch for payments.settlement_skipped.

Current Foundation

The current inbound economics are repo-spec governed:

FieldDefaultMeaning
payments_in.credits_topup.markup_factor1.10803324099723purchase-side funding multiplier; with the current 5% provider fee, targets about 95% provider top-up
payments_in.credits_topup.revenue_share0no system-tenant bonus credits minted from user purchases
payments_in.credits_topup.receiving_addressSplit addressmust point at a deployed 0xSplits V2 Split whose splitHash() matches repo-spec economics

Economic formula:

provider_topup_share = (1 + revenue_share) / (markup_factor * (1 - provider_fee))

With provider fee 5%, markup_factor = 1 / (0.95 * 0.95) = 1.10803324099723, and revenue_share = 0, the target is about 95% provider top-up and 5% DAO Split margin.

The old dangerous state was markup_factor: 2.0 with revenue_share: 0: that implies about 52.63% provider top-up, not at-cost, and can silently mismatch the deployed Split. Treat stale comments/docs mentioning old ~92.1% / ~7.9% or 2.0 / 0.75 economics as suspect until reconciled with current code and specs.

Outbound Direction

As of 2026-06-25, treat the OpenRouter/Coinbase Commerce top-up path as legacy/dead outbound infrastructure. OpenRouter documents that POST /api/v1/credits/coinbase has been removed and returns 410 Gone because Coinbase deprecated the underlying APIs. Source: https://openrouter.ai/docs/cookbook/administration/crypto-api.

The current buildable direction from the x402 handoff is narrow:

Stays unchangedChanges outbound only
inbound user credit purchaseretire OpenRouter/Coinbase top-up
credits ledger and human pre-auth budgetadd x402 client shim for provider requests
0xSplits 95/5 receiving Splituse Privy named signX402Payment for EIP-3009 typed data
Split-hash guard on inbound railroute provider cost to Hyperbolic/x402
repo-spec inbound activationadd per-request spend-vs-credit guard from LiteLLM cost data

Important: this is not the old "delete credits, delete Splits, inbound x402 everywhere" direction. Credits remain the human pre-auth layer. Splits remain the inbound revenue rail. The operator wallet's inbound 95% becomes working capital for outbound x402 micro-payments. If any x402 note still says "no credit system, no Privy, no Splits", treat it as stale until the active x402 design PR lands.

Human prerequisite for live x402 proof: a Hyperbolic account, API key, and decision on hosted vs self-hosted x402 facilitator. The signer, shim, LiteLLM wiring, and spend guard can be built and CI-gated without that, but real USDC e2e cannot be proven until the vendor account exists.

Start By Reading

Read the nearest AGENTS.md before editing a directory. Then read only the surfaces relevant to the bug:

SurfaceFile
Payment setup guidehttps://node-template.cognidao.org/knowledge/set-up-usdc-topups
Operator wallet + Split spechttps://node-template.cognidao.org/knowledge/operator-wallet-custody-boundary
x402 direction (hub atom)node-service-usdc-northstar
Node formation payment invariantshttps://cognidao.org/knowledge/node-formation-contract
Root repo-spec payment config.cogni/repo-spec.yaml
Operator repo-spec payment confignodes/operator/.cogni/repo-spec.yaml
Repo-spec schema/accessorspackages/repo-spec/src/schema.ts, packages/repo-spec/src/accessors.ts
Split allocation mathpackages/operator-wallet/src/domain/split-allocation.ts
Operator wallet adapterpackages/operator-wallet/src/adapters/privy/privy-operator-wallet.adapter.ts
Payment rail guard portnodes/operator/app/src/ports/payment-rail-guard.port.ts
Split guard adapternodes/operator/app/src/adapters/server/payments/split-payment-rail-guard.adapter.ts
Payment intent routenodes/operator/app/src/app/api/v1/payments/intents/route.ts
Payment servicenodes/operator/app/src/features/payments/services/paymentService.ts
Credit settlementnodes/operator/app/src/features/payments/services/creditsConfirm.ts
Facade config bridgenodes/operator/app/src/app/_facades/payments/attempts.server.ts
Container wiringnodes/operator/app/src/bootstrap/container.ts
Activation UInodes/operator/app/src/app/(app)/nodes/payments/PaymentActivationPage.client.tsx
Payment feature rulesnodes/operator/app/src/features/payments/AGENTS.md
Operator-wallet package rulespackages/operator-wallet/AGENTS.md
Repo-spec package rulespackages/repo-spec/AGENTS.md

Recent refactor to understand: PR cogni-dao/cogni#1823, feat(payments): repo-spec at-cost economics plus Split guard, head adc2f8ff5b in the original workspace. Check GitHub for current merge state before relying on branch-local facts.

Current x402 follow-up to understand: the active plan keeps inbound credits and 0xSplits unchanged, then replaces only the outbound cost hop with x402-to-Hyperbolic. Check the active design/foundation PRs before editing docs that still describe a full credit/Split deletion.

Architecture Map

The inbound credit top-up flow is:

  1. Client calls POST /api/v1/payments/intents.
  2. Route validates auth/request and delegates to createPaymentIntentFacade.
  3. Facade resolves billing account, wallet, repo-spec payment config, and paymentRailGuard.
  4. createIntent() calls paymentRailGuard.assertReady(paymentConfig) before creating the payment attempt.
  5. SplitPaymentRailGuardAdapter reads splitHash() from the configured Split and compares it to the hash computed from repo-spec economics plus operator wallet plus DAO treasury.
  6. Client sends USDC to the returned to address.
  7. Submit/poll path verifies the on-chain transfer, credits the user, optionally credits system bonus, then runs post-credit funding.
  8. Legacy post-credit funding distributes the Split and attempted to top up OpenRouter through the Privy-backed operator wallet when configured.
  9. New outbound direction: after credits authorize the spend, the operator pays provider cost per request through an x402 client shim, with Privy signing the EIP-3009 payment authorization via a named signX402Payment method.

Layer boundaries matter:

  • packages/repo-spec is pure schema/accessor code. No env, file I/O, app imports, or chain clients.
  • packages/operator-wallet owns Split allocation math and Privy HSM transaction submission. No app/database orchestration.
  • src/ports defines interfaces and port-level errors. No adapter imports.
  • src/features/payments owns payment state transitions and settlement orchestration. No HTTP/session/database direct access.
  • src/adapters/server/payments can do EVM RPC reads and implement ports.
  • src/bootstrap/container.ts wires live/test behavior and optional funding dependencies.

Debugging Workflow

Start with the failure class, then inspect the matching layer.

SymptomFirst checks
503 from /api/v1/payments/intentsresponse code, PaymentRailNotReadyError, PaymentRailMisconfiguredPortError, repo-spec receiving_address, chain ID, operator wallet address, DAO treasury, Split bytecode, Split splitHash()
SPLIT_CONFIG_MISMATCHcompute expected allocations from current markup_factor, revenue_share, provider fee, operator wallet, treasury; compare against deployed Split recipients/allocations
PAYMENT_RAIL_UNCONFIGUREDrepo-spec has payments_in, operator_wallet.address, cogni_dao.dao_contract, runtime has non-test wiring
intent succeeds but no OpenRouter top-uplook for payments.settlement_skipped; check Privy env, operator_wallet, payments_in, EVM_RPC_URL, OPENROUTER_API_KEY, provider funding wiring
OpenRouter top-up returns 410 Gonethe Coinbase charge API is removed; do not repair around it. Move work to x402 outbound/Hyperbolic unless the user explicitly asks for a legacy fallback
x402 outbound cannot be e2e testedcheck for missing Hyperbolic account/API key/facilitator decision; this is a human/vendor prerequisite, not a code proof
spend-vs-credit uncertaintyuse LiteLLM cost callback/receipt data as the meter; add a per-request guard so outbound USDC spend cannot exceed the user's credit budget/margin policy
credits minted incorrectlyinspect creditsConfirm.ts, revenueShare source from repo-spec, platform_revenue_share ledger entries, idempotency reference ${chainId}:${txHash}
candidate differs from prodcandidate may lack wallet/provider credentials; prove guard there, but do not call outbound settlement validated without real wallet/top-up evidence
fresh nodes have old economicscheck repo-spec schema defaults, activation UI defaults, node-template and spawned-node copies; use node-sync-prs after merged operator changes

When debugging live rails, prefer evidence in this order:

  1. current deployed SHA/ref (/version, workflow evidence, PR head);
  2. repo-spec values served by that build;
  3. HTTP response from the payment intent endpoint;
  4. chain reads of bytecode and splitHash();
  5. payment attempt and payment event rows;
  6. credit ledger and billing account deltas;
  7. operator wallet transaction hashes for Split distribute/legacy provider funding or x402 payment authorization/settlement evidence;
  8. provider-side evidence: Hyperbolic/x402 response and USDC settlement, or legacy OpenRouter credit delta only for old branches;
  9. Loki events, especially payments.confirmed, payments.funding_complete, and payments.settlement_skipped.

Activation Checklist

Use this when moving from config correctness to live payments:

  • Confirm the relevant payment PR is merged to main; record merge SHA.
  • Flight that SHA to candidate-a and verify /version matches.
  • Before updating the Split pointer, call payment intent creation and expect fail-closed 503 with a specific rail code, not transfer params.
  • Deploy a 0xSplits V2 Split whose recipients and allocations match repo-spec economics, operator wallet, and DAO treasury.
  • Update payments_in.credits_topup.receiving_address through the normal repo-spec activation/update path.
  • Reflight and verify payment intent creation passes the guard.
  • Promote only after guard proof is clean.
  • Run one small real USDC purchase on prod.
  • Verify: user credits minted, systemBonusCredits = 0, provider top-up about 95%, DAO margin about 5%, no silent settlement skip.
  • If shared substrate/defaults changed, run .agents/skills/node-sync-prs/SKILL.md after merge to sync node-template and relevant spawned nodes.

Validation Commands

Pick the smallest set that matches the change. Do not use these as a substitute for live payment proof.

pnpm --filter @cogni/repo-spec build
pnpm --filter @cogni/operator-wallet test
pnpm exec biome check <touched-files>
pnpm vitest run --config nodes/operator/app/vitest.config.mts \
  nodes/operator/app/tests/unit/adapters/server/payments/split-payment-rail-guard.adapter.test.ts \
  nodes/operator/app/tests/unit/features/payments/services/creditsConfirm.spec.ts \
  nodes/operator/app/tests/unit/packages/repo-spec/accessors.test.ts \
  nodes/operator/app/tests/unit/shared/config/repoSpec.server.test.ts
pnpm vitest run tests/unit/packages/repo-spec/accessors.test.ts
gh pr checks <pr> --repo cogni-dao/cogni

If a full typecheck fails on unrelated drift, isolate the payment/repo-spec tests and state the residual risk. CI static green at the final head is stronger than a stale local package-build failure.

PR And Review Discipline

For payment PRs, the body should state:

  • exact economics (markup_factor, revenue_share, provider fee assumption, expected provider/DAO split);
  • whether a smart contract deployment or repo-spec pointer update is required;
  • what fails closed before activation;
  • what was validated locally and in CI;
  • what has not been behaviorally validated until prod;
  • rollback plan if the first real payment proves wrong.

Do not merge or promote money-rail behavior on ambiguous validation language. Say precisely what is proved and what is not.

Knowledge Updates

When future payment work reveals durable new facts, use contribute-knowledge-to-cogni before writing to the hub. Recall first, refine existing entries when possible, and keep one inbox per work item — unrelated knowledge opens its own. As-built contracts belong in docs/spec/* shipped with code; atomic findings and operating rules can go to the knowledge hub.

Good candidates for knowledge contribution:

  • a newly proven live payment invariant;
  • a recurring production failure mode and its diagnostic signature;
  • a corrected economic formula or deployment dependency that future agents keep getting wrong;
  • a stable validation checklist that outlives the PR.

Bad candidates:

  • PR status, transient CI logs, or one-off branch state;
  • facts already present in specs or this skill;
  • unvalidated claims about live money behavior.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall