RFC: Funding Modality

[CoachCoe]

RFC: Funding Modality

Summary

Adds a Funding trait defining the runtime contract for a new funding modality: the one surface for moving value across the boundary between a user's Polkadot balance and everything outside it, in both directions, over the rails the product needs — a card or bank transfer, a swap from another chain, and cash traded in person with a peer.

Consumers (the host's balance card, or any product that hits an insufficient balance mid-flow) declare an intent and watch it to completion. Providers declare the modality in their manifest, receive intents addressed to them, and report progress. Four methods, wire ids 168–179.

The directions are deliberately asymmetric and the types say so. Inbound, the host proves the outcome and emits Delivered from its own on-chain observation. Outbound, it can prove only that funds left under the user's authorization and emits Released, because no host can verify that cash reached a hand or a bank account. Collapsing both into one "done" state would let the UI tell a user their money arrived when the protocol has no idea, so the protocol declines to offer it.

Checklist

• Added docs/rfcs/funding-modality.md (no number — CI assigns one on merge)
• Filled all RFC sections (Summary, Motivation, Detailed Design, Drawbacks, Alternatives, Unresolved Questions)
• Updated Rust traits in rust/crates/truapi/
• Added label: rfc

Motivation

Two gaps, one in each direction.

In: the only funding path is PaymentTopUpSource — ProductAccount and PrivateKey from RFC 0006, plus Coins from RFC 0021. All three mean the product already controls this money. None answer where money comes from, so a product reaching HostPaymentError::InsufficientBalance has nowhere to send the user.

Out: Payment::request sends to an account, which moves value sideways rather than out. A user wanting cash and a business wanting collected funds in a bank account are the same gap reversed.

Without a declared contract, each on-ramp arrives as bespoke host code with its own screens, credential handling, and idea of what "done" means — and three providers in, the host owns three fiat relationships it should never have touched.

Two routes need no partner at all (Friend, ExternalWallet), which is what makes the modality shippable and testable end to end before any partner terms exist. The other three rails are additive: one manifest declaration and one provider each, with no change to this contract.

What's in scope, and what the host owns

The modality is mostly host UI. A provider contributes at one of two levels — static manifest metadata for its row, or its own App executable framed in a surface the host can reclaim. Twelve of the design's fourteen states are host-owned; the RFC maps each one. A provider never draws the stamp bar, a terminal state, the rail list, the eligibility explanation, or the authorization to release funds.

There is deliberately no level where a provider supplies a UI fragment the host renders natively. That would need CustomRendererNode to flow product → host, and it currently flows only host → product. It is excluded for a substantive reason rather than a mechanical one: without a constrained renderer profile, a provider could render "Delivered" or "Verified" in host styling. See Out of Scope in the RFC.

Dependencies on in-flight work

• Secrets (RFC 0025: Secrets Management in TrUAPI #335) — this RFC assumes 166–167 are taken and starts at 168. Funding is that RFC's motivating example (a fiat-onramp API key), and the two compose deliberately: nothing here transports a credential, because secrets.request already covers it. Its personhood caller tier is also the mechanism I'd evaluate first for reusable verification. cc @BigTava
• Product Manifest Format (RFC: Product Manifest Format #206) — adds funding to a worker's includes, plus a funding.routes block declaring rail, directions, assets, latency, and whether an account is required. That RFC states per-modality runtime contracts belong in their own RFCs; this is that contract.
• Personhood as a Product (RCC 0024: Proof of Personhood as a Product — Explicit Ring VRF Key Management #324) — precedent for adding a modality to includes.

If either PR lands first and shifts ids, this block moves up rather than reusing anything.

Coinage steward

Per the TrUAPI Steward process, the surface for a component should not change without its steward in the loop. Funding settles through Coinage: inbound delivery targets are CoinPayment receivables, and the Friend route rests on create_receivable + listen_for_payment. cc @gui1117 — a review pass on whether FundingDelivery::Receivable and the friend route match what Coinage actually does would be valuable before this is discussed in the Monday sync.

Product SDK

Products consume the Product SDK rather than the host directly, so a new modality implies SDK work (cc @TarikGul) — at minimum a typed wrapper over funding.request / statusSubscribe, and for provider products the serve/report loop. Naming it here so it is tracked rather than discovered later.

Not yet implemented — expected, not broken

ProductRuntimeHost gains an empty impl Funding, matching the existing impl Chat / impl CoinPayment pattern. Every method defaults to CallError::unavailable(), so nothing is stubbed as working.

Consequently the four generated TypeScript examples (playground/test/generated/examples/funding-*.ts) assert isOk() and will fail against a live host until a host implements the modality. That is the same position #335 is in, and it is the codegen convention (64 methods, 64 executable examples) rather than a broken test.

Verification

• cargo build --workspace --all-targets --all-features — clean, no warnings
• cargo +nightly fmt --check — clean
• cargo clippy --workspace --all-targets --all-features -- -D warnings — clean
• cargo test --workspace --all-features — 609 passed, 0 failed
• npm run build (tsc) + npm test (bun) — clean; 215 passed, 0 failed
• ./scripts/codegen.sh re-run; dispatcher, wire table, TS client, and golden fixtures regenerated. Both golden updates are purely additive — zero removed lines.

Note: rust/crates/truapi-codegen/tests/golden/wire_table.rs is also touched by #335, so expect a trivial conflict there.

Open questions

Recorded in the RFC rather than answered; the types are neutral to each answer.

1. Who confirms an outbound off-chain leg, and what happens when it does not complete? The largest question here. Released is where this RFC stops. Closing it means escrow (making the host an adjudicator), a provider attestation surfaced as a claim, or a dispute path with a human — three different trust models with different liability. A decision about accountability before it is a protocol detail.
2. Is a privacy-preserving dollar a distinct asset or a mode of the ordinary one? Decides whether the sheet offers one dollar destination or two.
3. Can a user hold the centralized dollar used to settle between venues, or is it always passed through? Decides whether it is ever a FundingAsset.
4. Where does the operator's jurisdiction and amount matrix live, and how is it versioned? Required before the modality ships. Provider-declared routes do not cover it, since the operator does not own a provider's dotNS name.
5. Is verification host-held and reused across providers, or per-provider? Decides whether it is a first-run property or a mid-flow surprise.
6. What does a verified badge on a provider row assert, and who is liable for asserting it?
7. Who is accountable for a failed transfer or a stuck swap, and is there a human path? Needs a per-route matrix with named owners before any partner conversation.
8. Does the host's own balance card need a resolvable asset descriptor, and if so does FundingAsset opacity survive?

🤖 Generated with Claude Code

[gui1117]

claude I'm not reading that, if you want me to confirm the design works with coinage, give a list of concise requirements.