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

RailRuns on today
x402 batch-settlementthe upstream x402 contracts, vendored, on a local Anvil chain
x402 uptothe vendored x402 contracts with a mocked Permit2
MPP sessions, version 1a 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 Nanopaymentsa 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 channel's state, and starts and finishes the payer's exit. It never holds a payee key.

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:

covered by a signed voucher is unclaimed;

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

funded from the budget owner's own wallet.

payee's own act on the rail.

Test suites

SuiteWhat it shows
make test-rails-x402x402 batch-settlement and upto: the known withdrawal sweep reproduced, then refused
make test-rails-mppMPP version 1: the grace-expiry sweep reproduced, then refused
make test-rails-mpp-v2MPP version 2 beside version 1
make test-rails-circleCircle: the withdrawal sweep reproduced, then refused; authorizations valid for at least three days
make test-rails-solana-mockthe three Solana rails on the simulator
make test-rails-signer-seamevery rail refuses a missing signer before any deposit
make test-p31proven work is never swept, on every funding mode and every adopted rail
make test-rail-verifya 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

  1. The rail's own suite green, including its sweep reproduced and refused.
  2. make test-rails-signer-seam green with the new rail added.
  3. make test-p31 green with the rail included.
  4. Every refusal named (unclaimed_voucher, session_signer_missing,

deposit_exceeds_headroom, exit_in_progress), never a silent pass.