Stablecoin escrow

The stablecoin mode (funding: "usdc") funds the same budget object from the contract version 2 vault: opening the budget deposits its cap into the vault, streams settle by voucher against that deposit, and closing the budget releases the unspent remainder back to the owner on-chain. The contracts hold escrow that only the rules can move; see the non-custodial posture. Status: Live on a local chain and on a testnet. Nothing on this page involves real money.

Try it on a local chain

make dev-chain starts a local Anvil with a one-second block time, deploys a test stable with contract version 2, mints the test stable to the budget owner (Anvil dev account 1) and the adopt user (account 4), and prints the settings to add to the boot command. It stays in the foreground; Ctrl-C stops Anvil. It needs Foundry (anvil, forge) and a built engine.

cd "$DYNAMO_REPO"
pwd
pnpm --filter @dynamo/engine... -r build
make dev-chain

In a second terminal, boot the core as in Control Mode with the printed block: CORE_ALLOWED_MODES=none,usdc, CORE_ESCROW_SETTLEMENT=payee-kit, CORE_ESCROW_RPC_URL, CORE_ESCROW_V2_VAULT, CORE_ESCROW_V2_ASSET, CORE_ESCROW_V2_ASSET_REGISTRY, CORE_ESCROW_OWNER_KEY and CORE_ESCROW_V2_RELAYER_KEY. The stablecoin rail runs on contract version 2 alone; adding contract version 1 settings (CORE_ESCROW_VAULT, CORE_ESCROW_ASSET) makes the core refuse to boot with contract_versions_mixed. Every key it prints is a public Anvil dev key; never use them anywhere else. The payee keys it prints are for the payees only: never give them to the core. Use a fresh CORE_DB each time you restart make dev-chain, because the new chain does not have the old budgets.

What changes when the stablecoin mode is on

deposits the cap into the vault from the core's owner key (with a 6-decimal stable, exactly the cap: one base unit is one micro-USD). A budget funded from a user's own wallet is opened by the user on the vault and adopted (user-owned budgets).

default: each stream open carries the delegator's signed hop intent (signHopIntent in the SDK) and the payee's signed offer (signPayeeOffer). An unsigned open is refused with reason hop_unsigned (HTTP 409). The operator can relax this with CORE_OWN_HOPS=optional.

CORE_ESCROW_SETTLEMENT=payee-kit and CORE_ESCROW_V2_RELAYER_KEY, the core's gas-only relayer submits each payee's signed vouchers to the vault, and the contract pays the payee's own address. Without a relayer key, a payee reads its signed vouchers from /payee/v1/vouchers and submits them itself.

transaction has CORE_ESCROW_CONFIRMATIONS confirmations (one on a local node; required off a local chain), and checkpointed before that. Settled value is first held in the vault and the settlement stays checkpointed until the core's scheduler releases it to the payee. When to credit a settlement is covered in the acceptance checklist.

silently ends allowances (fail closed).

Anvil must run with a block time. With a block only when a transaction arrives, the latest block can be older than a voucher's signing time and the vault refuses the settle. make dev-chain passes --block-time 1.

On a testnet

The same settings point the core at a testnet RPC endpoint and a contract version 2 vault you deploy and can verify yourself; no testnet deployment ships with the repository. In test mode (CORE_ESCROW_RAIL_MODE=test, the default) the rail boots on a built-in testnet: Ethereum Sepolia, Holesky, Hoodi, Base Sepolia, Avalanche Fuji, Arbitrum Sepolia, Optimism Sepolia, Polygon Amoy, BNB Smart Chain testnet, Linea Sepolia, Scroll Sepolia and zkSync Era Sepolia. CORE_ESCROW_EXTRA_TESTNETS adds other testnet chain ids; a known mainnet refuses boot. The core reads the chain id from every RPC endpoint at boot and refuses a mismatch. Off a local chain, CORE_ESCROW_CONFIRMATIONS must be set, and CORE_ESCROW_DEPLOYMENT_BLOCK names where log scans start; CORE_ESCROW_LOG_RANGE bounds each log request (default 2,000 blocks) for providers that limit ranges. Outside local development chains the core starts the stablecoin mode only when the vault's owner and fee collector are Safe multisig contracts with a threshold of 2 or more; anything else refuses boot, named. The contract version 2 deploy script (packages/contracts-v2/script/DeployV2.s.sol) applies the same check before it broadcasts anything, and broadcasts nothing unless EXPECTED_CHAIN_ID names the chain its RPC URL serves. While a vault's fee differs from the core's configured fee, the core opens no new budget or stream on it. Your client needs nothing new: the same DYNAMO_CORE_URL and OWNER_API_TOKEN, a different funding tag, and signed hops. Next: the credit card sandbox.