Stablecoin issuers and payment rails
Not in the preview yet. This feature is built in the repository but is off in the v2.2.6 preview (test mode). Do not treat this page as available on a preview core. See ../preview.md and the release notes.
Status: Live on local chains and mocks. Real-money settlement is Release-gated.
An adopted rail lets a Dynamo stream pay through an existing payment channel or session protocol. One stream maps to one channel: the channel's deposit is the stream's cap, and the payee claims with its own key.
Rails built today
| Rail | Runs on today |
|---|---|
x402 batch-settlement | the upstream x402 contracts, vendored, on a local Anvil chain |
x402 upto | the vendored x402 contracts with a mocked Permit2 |
| MPP sessions, version 1 | a mock channel contract on a local chain |
| MPP sessions, version 2 (TIP-1034 channel reserve) | a mock of the reserve interface on a local chain, not a Tempo node |
| Circle Gateway and Nanopayments | a mock wallet contract and a batcher simulator; no Circle service is contacted |
Solana (x402 exact, x402 upto, payment channels) | an in-process simulator |
The interface
A rail adds two sides:
- The payer side opens a channel, signs a rail-native voucher, reads
the channel's state, and starts and finishes the payer's exit. It never holds a payee key.
- The payee side observes a voucher it was handed and claims it, in the
payee's own process, with the payee's own key.
Each rail declares whether caps are enforced on chain (the deposit is the cap) or by Dynamo (the rail bounds only a total, and per-stream caps hold through Dynamo's signed records).
The signer seam
The payer supplies its own signer: a key in its own process, a key held by a key-management service, or a session key that stays in the payer's wallet. The rail never receives a private key. A rail asked to open a channel with no signer supplied refuses session_signer_missing before anything is deposited, and a wallet that answers for another key, or with a non-canonical signature, refuses session_signer_mismatch.
Claims before deadlines
Several rails let a payer withdraw after a delay, which could sweep value the payee has earned but not yet claimed. Dynamo blocks that on both sides:
- the payer's exit is refused with
unclaimed_voucherwhile any value
covered by a signed voucher is unclaimed;
- the payee's claim duty stores every voucher it receives, claims before
each deadline, and raises an alert (claim_deadline_at_risk, claim_deadline_missed) when it cannot.
In a core, these duties run in the always-on scheduler every CORE_SCHEDULER_RAILS_SECONDS (default 30). A rail is wired in by the operator's host configuration; no environment switch selects one.
Limits
- The version 2 escrow contract cannot be a rail's payer. A rail channel is
funded from the budget owner's own wallet.
- Rails have no payer-side refund (
refund_unsupported); a refund is the
payee's own act on the rail.
Test suites
| Suite | What it shows |
|---|---|
make test-rails-x402 | x402 batch-settlement and upto: the known withdrawal sweep reproduced, then refused |
make test-rails-mpp | MPP version 1: the grace-expiry sweep reproduced, then refused |
make test-rails-mpp-v2 | MPP version 2 beside version 1 |
make test-rails-circle | Circle: the withdrawal sweep reproduced, then refused; authorizations valid for at least three days |
make test-rails-solana-mock | the three Solana rails on the simulator |
make test-rails-signer-seam | every rail refuses a missing signer before any deposit |
make test-p31 | proven work is never swept, on every funding mode and every adopted rail |
make test-rail-verify | a rail checks a Dynamo payment authorization offline before it pays |
make test-rails-solana-local runs the Solana exact leg on a local solana-test-validator when one is installed.
Mocks today, partner access later
Everything above runs locally. A leg on a partner's public test network or an issuer sandbox does not exist yet; it would need the partner's testnet contracts.
Certification steps
- The rail's own suite green, including its sweep reproduced and refused.
make test-rails-signer-seamgreen with the new rail added.make test-p31green with the rail included.- Every refusal named (
unclaimed_voucher,session_signer_missing,
deposit_exceeds_headroom, exit_in_progress), never a silent pass.