Contract version 2

Contract version 2 (BudgetVaultV2) is the stablecoin escrow contract. A deployment runs exactly one contract version, and from v2.1.3 the stablecoin rail runs on contract version 2 alone: no version 1 backend, no version 1 entry in the deployment registry, and no version 1 vault in the vault guard. Contracts are never upgraded in place: each budget is opened on its deployment's version and stays on it for life. Version 2 has relayed settlement, held value released in tranches, refunds on attested breaches of objective terms, a grace window after revoke and expiry, and user-owned budgets opened from the user's own wallet.

In this release version 2 runs on a local chain (Anvil) and, in test mode, on public testnets (the built-in testnet list plus CORE_ESCROW_EXTRA_TESTNETS; known mainnets refuse boot). It has not been audited yet.

Status: Live on a local chain and on testnets in test mode. Real-money use on a mainnet is Release-gated.

How version 2 differs from version 1

Version 1 stays in the code for deployments configured with it alone; no version 2 deployment uses it. For reference:

AreaVersion 1Version 2
Voucher at the revoke instantRefused (only vouchers signed strictly before the revoke settle)Settles (signed at or before the cut-off)
Grace after the cut-offNone7 days to settle vouchers signed at or before it
Who submits a settleThe payeeAnyone (a relayer); the payee is still the one paid
When the payee is paidAt settleWhen each held tranche matures (holdback, at most 90 days)
RefundsNone in the contractFrom unmatured held value only, on a breach report by a breach signer the payee accepted, or on the payee's own signature
Fee capMAX_FEE_BPS = 1000MAX_FEE_BPS = 150; a stream never pays more than the vault fee at its open (a later lower fee applies)
Delegation depth816
Voucher signerSession key, or the budget ownerSession key only

A voucher signed for one version is refused by the other.

From Control to version 2

Nothing moves an existing budget to another version or out of Control Mode: a budget's funding and contract version are fixed when it opens, and the owner API has no field to choose a version. To use version 2, the operator configures the stablecoin rail on version 2 alone (below), and you open a new budget with "funding": "usdc" or adopt one the user opens from their own wallet. Existing Control budgets keep running as they are.

When the payee's balance moves

On version 2 a settle does not pay the payee. It moves the settled value from the budget's escrow into the stream's held balance, as a tranche that matures one holdback after the settle (rounded up to the next of the holdback's 16 buckets, so up to one bucket later). The holdback is fixed per stream at open and stored on chain (at most 90 days):

terms catalogue), the longest window of its terms plus 900 seconds of reporting time;

CORE_VERIFIED is set.

With a holdback of 0 the tranche matures at once, but it is still held until released.

Matured tranches are paid by releaseHeld(streamId) on the vault. Anyone may call it; it always pays the stream's serviceNode, minus the fee, and processes at most 64 tranches per call. The core's scheduler calls it for every version 2 stream that holds matured value (escrow.release-held.<mode>, every CORE_SCHEDULER_RELEASE_HELD_SECONDS, default 60), through the gas-only relayer when one is configured, else the core's owner key. A failed release raises an alert and is tried again on the next pass. The payee (or anyone) can also send it once the tranche has matured:

cd "$DYNAMO_REPO"
pwd
cast call "$V2_VAULT" "releasable(uint256)(uint256)" "$STREAM_REF" --rpc-url "$RPC_URL"
cast send "$V2_VAULT" "releaseHeld(uint256)" "$STREAM_REF" --private-key "$PAYEE_1_KEY" --rpc-url "$RPC_URL"

STREAM_REF is the stream's on-chain id. Inside the holdback, held value can be refunded to the payer on an accepted breach report; after release it cannot.

What stays in the vault after close. Closing a budget cuts it off (if it is still live) and returns to the payer everything no signed voucher can still claim. Two amounts stay: the held value not yet released, and, for the 7-day grace window after the cut-off, a reserve of each root stream's allocation minus what the budget has settled, so vouchers signed before the cut-off can still settle. For example, a budget of 5,000,000 base units with one 2,000,000 stream that settled 700,000 keeps 700,000 held plus 1,300,000 reserved, 2,000,000 in all. After the grace window, withdrawUnspent(budgetId) returns the reserve to the payer; anyone may call it, the payer always receives it, and the core calls it only at close.

Turn it on (operator)

The stablecoin set for version 2 alone:

VariableMeaning
CORE_ESCROW_RPC_URL or CORE_ESCROW_RPC_URLSThe chain's RPC endpoint, or an ordered comma list. At boot every endpoint is asked its chain id; one that cannot answer, or two that disagree, refuse boot (escrow_rail_chain_mismatch)
CORE_ESCROW_V2_VAULT, CORE_ESCROW_V2_ASSETThe version 2 vault and its asset; required together
CORE_ESCROW_V2_ASSET_REGISTRYOptional; checked against the registry the vault reads
CORE_ESCROW_OWNER_KEYThe operator's owner key; budgets opened with "funding": "usdc" are funded from it
CORE_ESCROW_V2_RELAYER_KEYOptional gas-only key that submits settles and releases held value. Unset, signed vouchers go to payees through /payee/v1/vouchers. A relayer equal to a stream's payee is refused
CORE_ESCROW_SETTLEMENTpayee-kit (the hosted image requires it when usdc is allowed)
CORE_ESCROW_DEPLOYMENT_BLOCKThe vault's deployment block, where log scans start
CORE_ESCROW_CONFIRMATIONSConfirmations that make a settlement final (1 to 1024); required off a local chain
CORE_ESCROW_LOG_RANGEOptional; the most blocks one log request spans (default 2,000, at most 100,000)
CORE_ESCROW_EXTRA_TESTNETSOptional; testnet chain ids beyond the built-in list (a known mainnet refuses boot)
CORE_ESCROW_RAIL_MODEtest (default): the rail boots on a local chain or an allowed testnet only. live needs the audit flag and stops at escrow_live_release_gated

The version 1 settings are refused beside this set: CORE_ESCROW_VAULT or CORE_ESCROW_ASSET, CORE_ESCROW_DEFAULT_VERSION=v1, or any CORE_ESCROW_V1_STATUS refuses boot with contract_versions_mixed, naming the variables. A store that still holds open version 1 budgets refuses to start on version 2 alone, naming them, so a version switch never strands money. Setting only one of CORE_ESCROW_V2_VAULT and CORE_ESCROW_V2_ASSET, or leaving out the RPC or the owner key, refuses boot.

At boot the core reads the vault's signing domain on chain and refuses a mismatch, and logs one line naming the single deployment (contract v2, its vault and chain) and one naming the chain it runs on and the allowed testnets. Off local chains, the vault's owner and fee collector must be a multisig with a threshold of at least two, or the core refuses to start; while the vault is paused, or its fee differs from the core's protocol fee, new budgets on it are refused (vault_paused, vault_owner_unqualified, fee_collector_unqualified, protocol_fee_mismatch).

On a local chain

make dev-chain starts Anvil with a one-second block time (needed: see the operator guide), deploys a test stable with contract version 2, mints the stable to the budget owner (Anvil dev account 1) and the adopt user (account 4), and prints a variable block for contract version 2 alone, including a gas-only relayer key (Anvil dev account 7). Add it to the boot command of deploy/image/entry.mjs with a fresh CORE_DB.

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

Confirm version 2 is on

The boot log names the single deployment: stablecoin rail on contract v2 alone — one deployment: contract v2, vault …, chain …. To confirm a budget is on version 2:

400 invalid_request "a contract v2 budget exports only as evidence 1.3.1; ask for ?schema=1.3.1 (fail closed)";

budget's deposit when it opens;

cd "$DYNAMO_REPO"
pwd
curl -s -H "Authorization: Bearer $DYNAMO_OWNER_TOKEN" "$DYNAMO_BASE_URL/owner/v1/budgets/$BUDGET_ID/evidence"
cast call "$V2_ASSET" "balanceOf(address)(uint256)" "$V2_VAULT" --rpc-url "$RPC_URL"

Evidence

Export a version 2 budget's evidence with GET /owner/v1/budgets/:id/evidence?schema=1.3.1, or ?schema=1.4.0 with Dynamo-Version: 1.8.0; older schemas are refused. See Verify an evidence file offline.

User-owned budgets (adopt)

A user who wants the budget in their own wallet opens it on chain themselves; the core then adopts it. This needs version 2 in the stablecoin mode: a single-tenant core, or a multi-tenant one with the adopt switch on (see below).

  1. POST /owner/v1/budgets/adopt-prepare with

{"owner", "capTotal", "serviceNode", "ratePerSecondUnits", "capUnits"} (optional category, mandate). The core generates the stream's session key and answers an adoptionId, the vault and asset, the session key's address, the mandate fingerprint and the exact on-chain values (in the asset's base units).

  1. The user opens the budget and its root stream on the version 2 vault

from their own wallet with exactly those values: approve the vault to take the deposit, then openBudget and openStream.

  1. POST /owner/v1/budgets/adopt with {"adoptionId", "budgetRef", "streamRef"}

(the on-chain budget and stream ids, as decimal strings). The core reads every fact back from the chain and records the budget only if all match. An adoption id is used once, and an on-chain budget can be adopted once.

Step 1, with the adopt user and a payee that make dev-chain printed:

cd "$DYNAMO_REPO"
pwd
curl -s -X POST "$DYNAMO_BASE_URL/owner/v1/budgets/adopt-prepare" \
  -H "Authorization: Bearer $DYNAMO_OWNER_TOKEN" -H "Content-Type: application/json" \
  -d "{\"owner\":\"$ADOPT_USER\",\"capTotal\":\"5000000\",\"serviceNode\":\"$PAYEE_2\",\"ratePerSecondUnits\":\"10\",\"capUnits\":\"100000\"}" \
  | tee prepared.json

Step 2, from the user's wallet (here the adopt user's Anvil dev key). Take vault, asset, sessionKey, mandateFingerprint and the three onChain values from prepared.json. openBudget takes one tuple (asset, amount, capTotal, expiresAt, mandateFingerprint, payees); the amount must cover capTotal (here it equals it), 0 means no expiry and an empty payee list means no allow-list. openStream takes (budgetId, parentStreamId, serviceNode, sessionKey, ratePerSecond, capUnits, holdbackSeconds, termsFingerprint, breachSigner, accountRef); a root stream has parent 0, the holdback is yours to choose, and adopt does not check it. The vault numbers budgets and streams from nextBudgetId() and nextStreamId(); read them first.

cd "$DYNAMO_REPO"
pwd
J() { node -pe "const p=JSON.parse(require('fs').readFileSync('prepared.json')); $1"; }
VAULT=$(J p.vault); ASSET=$(J p.asset); SESSION=$(J p.sessionKey); FP=$(J p.mandateFingerprint)
CAP=$(J p.onChain.capTotal); RATE=$(J p.onChain.ratePerSecond); CAPU=$(J p.onChain.capUnits)
ZERO32=0x0000000000000000000000000000000000000000000000000000000000000000
BUDGET_REF=$(cast call "$VAULT" "nextBudgetId()(uint256)" --rpc-url "$RPC_URL")
STREAM_REF=$(cast call "$VAULT" "nextStreamId()(uint256)" --rpc-url "$RPC_URL")
cast send "$ASSET" "approve(address,uint256)" "$VAULT" "$CAP" --private-key "$ADOPT_USER_KEY" --rpc-url "$RPC_URL"
cast send "$VAULT" "openBudget((address,uint256,uint256,uint64,bytes32,address[]))" \
  "($ASSET,$CAP,$CAP,0,$FP,[])" --private-key "$ADOPT_USER_KEY" --rpc-url "$RPC_URL"
cast send "$VAULT" "openStream((uint256,uint256,address,address,uint256,uint256,uint32,bytes32,address,bytes32))" \
  "($BUDGET_REF,0,$PAYEE_2,$SESSION,$RATE,$CAPU,0,$ZERO32,0x0000000000000000000000000000000000000000,$ZERO32)" \
  --private-key "$ADOPT_USER_KEY" --rpc-url "$RPC_URL"

Step 3:

cd "$DYNAMO_REPO"
pwd
curl -s -X POST "$DYNAMO_BASE_URL/owner/v1/budgets/adopt" \
  -H "Authorization: Bearer $DYNAMO_OWNER_TOKEN" -H "Content-Type: application/json" \
  -d "{\"adoptionId\":\"$(J p.adoptionId)\",\"budgetRef\":\"$BUDGET_REF\",\"streamRef\":\"$STREAM_REF\"}"

The answer names the budget and stream ids and contractVersion ({"version": "v2", "deployment": "v2:…"}).

The owner signs the root hop (Dynamo-Version 1.8.0)

Under required own hops (the default in the stablecoin mode), the root stream's hop must be signed by its delegator, the budget's owner, so that the budget's evidence verifies offline. At Dynamo-Version 1.8.0 the adopt-prepare answer also carries the budget and stream ids the core will record and a hopIntent: the root's dynamo-hop-intent-v2 and its typedData, an EIP-712 payload whose domain names this chain and the vault.

that opens the budget. The core never sees that wallet's key.

{address, nonce, signature, mandateHash, scheme: "eip712", chainId, verifyingContract}, with nonce and mandateHash taken from hopIntent.intent, and payeeOffer is the payee's offer.

After the on-chain checks, adopt refuses with adopt_refused when the intent is missing (check hop_intent), is signed by a wallet other than the one that opened the budget (hop_signer), or comes without a valid payee offer (payee_offer). Nothing is recorded, and you can adopt again with the right signatures. A budget adopted without the intent (by a client pinned before 1.8.0) cannot export evidence 1.3.1 or 1.4.0 under required own hops: at Dynamo-Version 1.8.0 the export answers hop_unsigned; at an earlier pin it fails without that name.

Child streams opened by the parent agent (adopt a child)

Version 2 takes a child open only from the parent stream's serviceNode. When that serviceNode is another agent (an agent of another owner, or any agent whose key the core does not hold), a direct child open answers hop_parent_signer with nothing allocated. The parent agent then opens the child itself, from its own key, and the core adopts it (Dynamo-Version 1.8.0):

  1. POST /owner/v1/streams/:id/children/adopt-prepare on the parent stream

with {"requestRef", "serviceNode", "ratePerSecondUnits", "capUnits"} (optional category, mandate, delegation, payeeOffer, holdbackSeconds, ttlSeconds). The core runs every check a child open runs (mandate, own hops, the parent's headroom, depth, freezes, payee identity) and refuses the same way, with nothing prepared. It answers an adoptionId, the opener (the parent stream's serviceNode), the vault, the core-issued session key, expiresAt, the exact openStream arguments in the asset's base units and their calldata. The prepared cap holds the parent's headroom until expiresAt. The same requestRef answers the same preparation.

  1. The parent agent sends calldata to the vault from the opener address

(any EVM wallet; nothing is signed by the core).

  1. POST /owner/v1/streams/:id/children/adopt with

{"adoptionId", "txHash"} (or "streamRef", the on-chain stream id). The core reads the child back from the vault: its parent, sender, payee, session key, rate, cap and holdback must match, and it must be neither revoked nor settled. On any difference it answers child_adopt_refused, naming the check, and records nothing. On success the child is recorded exactly as a child open would record it (signed hop record, inherited mandate, depth). A retry answers the same stream with "replayed": true.

Adopt on the multi-tenant hosted tier (operator)

A multi-tenant deployment (CORE_TENANCY=multi) holds no payer key, so by default it has no stablecoin mode and both adopt routes answer 409. The switch CORE_TENANCY_USDC turns adopt on:

ValueEffect
off (default)No stablecoin mode on the hosted tier; nothing changes
adoptEach tenant's test-key core gets a stablecoin mode on version 2 that only adopts

With adopt, boot requires CORE_ESCROW_V2_VAULT, CORE_ESCROW_V2_ASSET, CORE_ESCROW_RPC_URL (or CORE_ESCROW_RPC_URLS) and CORE_ESCROW_V2_RELAYER_KEY, and usdc in CORE_ALLOWED_MODES on the hosted image. It refuses CORE_ESCROW_OWNER_KEY, any payee or oracle key, and the version 1 settings (CORE_ESCROW_VAULT, CORE_ESCROW_ASSET, CORE_ESCROW_DEFAULT_VERSION, CORE_ESCROW_V1_STATUS): version 1 is retired there. Any other value of the switch refuses boot. Each refusal names its variable and a code (tenancy_usdc_invalid, tenancy_usdc_single, tenancy_usdc_missing, tenancy_usdc_payer_key, tenancy_usdc_v1_retired), never a key value.

One relayer key serves every tenant. It pays gas only and moves no value, and it refuses to settle a stream whose payee is the relayer itself. A budget the core would fund itself (POST /owner/v1/budgets with "funding": "usdc") is refused with funding_adopt_only, nothing funded. Live keys stay Control Mode only. An adoption id, and the budget and stream it adopts, belong to the tenant that prepared it: another tenant gets 404 for the id and cannot adopt the same on-chain budget.

Known limits in this release

serviceNode (a payee's other address is recorded as pending_v2).

cut-off and the deadline); own-key settle through the kit is tested on version 1 only, so on version 2 settles go through the relayer.

Dynamo-Version 1.8.0) evidence/1.4.0.

contract version, version 2.

The full list for auditors is docs/audit/known-issues.md in the repository.