Adopted 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.
Dynamo can put a budget's streams on payment rails built by others, so a payee already paid over one of them keeps it and Dynamo adds caps, revocation and the signed authority chain on top. In this release the rails are a library preview: @dynamo/rails 0.2.0, unpublished, exercised by its own tests on a local chain and an in-process simulator. A core does not select a rail by configuration: no environment variable wires one in.
The rails
| Rail | How Dynamo runs it in this release | Where the cap holds |
|---|---|---|
x402 batch-settlement | The upstream x402 contracts, vendored unchanged, on a local Anvil | On chain (the channel deposit) |
x402 upto | The upstream upto proxy, with a mocked Permit2 | The engine and the authority chain; on chain only the authorized maximum |
| MPP sessions | A mock of the session escrow interface (draft-tempo-session-00) | On chain (the channel deposit) |
MPP v2 (mpp-session-v2) | A mock of the TIP-1034 "TIP20 Channel Reserve" escrow, beside v1 | On chain (the channel reserve) |
| Circle Gateway and Nanopayments | A mock wallet contract and batcher | The engine and the authority chain |
Solana payment-channels (with x402 exact and upto) | A TypeScript simulator of the program; no cluster | On chain (the deposit); exact by the engine |
Pinned versions and the audit status of each upstream are listed in docs/audit/adopted-rails.md in the repository.
How a stream uses a rail
- Only a leaf stream opens a channel; the deposit is allocated against
every ancestor's remaining headroom before anything is deposited.
- Each stream gets its own session key; the rail sees that key as the
payer's signer. The payer supplies the signer for it (a key in its own process, a KMS handle or a wallet session); the rails never receive a private key. A session key with no supplied signer is refused (session_signer_missing) before anything is deposited.
- The deposit comes from the budget owner's own wallet. The contract
version 2 vault cannot fund a rail channel.
Proven work is not swept
Several rails let the payer withdraw a channel after a delay. Dynamo never starts or finishes such a withdrawal while value covered by a signed voucher is unclaimed; it is refused as unclaimed_voucher. As payee, the library stores every voucher and claims before each deadline with a margin, raising claim_deadline_at_risk when time is short.
Try it
cd "$DYNAMO_REPO"
pwd
make test-rails-x402
make test-rails-mpp
make test-rails-circle
make test-rails-solana-mock
node packages/rails/scripts/value-step4.mjs
The x402 suite needs Foundry (forge, anvil) on the PATH; none of the targets contacts a vendor or a public chain.
Limits in this release
- No payer-side refund on a rail (
refund_unsupported). uptosettles once per authorization.- An exit started out of band with the session key is outside Dynamo's
control.
- Solana runs on a simulator only.
- The core's scheduler runs a rail's claim and exit duties
(rails.payee-claims, rails.payer-exits) only when code that embeds the core passes a rail in; a core started from the environment has none.