Adopting contract v2

Contract v2 (BudgetVaultV2) is a second escrow contract deployed beside the sealed contract v1, never as an upgrade of it. Each budget stays on the version it was opened on for its whole life.

Status: Live on a local test chain. Contract v2 has not been deployed to any public chain or testnet. Real-money stablecoin settlement is Release-gated: it is not offered in this release. The code does not refuse it outright. It is gated by the operator's configuration (a hosted core allows only the modes in CORE_ALLOWED_MODES, default none) and by a multisig check: a stablecoin deployment refuses to start unless each vault's owner and fee collector are Safes needing two or more signatures (local development chains are exempt).

Back to Changelog, versioning, deprecation and migration.

What is different in v2

AreaContract v1Contract v2
Revoke cut-offA voucher settles only if signed strictly before the revokeA voucher signed at or before the cut-off settles, for a grace window of 7 days after it
Delegation depthup to 8up to 16
Fee ceilingMAX_FEE_BPS = 1000MAX_FEE_BPS = 150, fixed per stream at open; a fee change never raises a running stream's fee
Who signs vouchersthe stream's session key, or the budget ownerthe stream's session key only
Who submits a settlethe payeeanyone (relayed); the money still goes to the payee
When the payee is paidat settlesettled value is held and released when its holdback matures (at most 90 days)
Refundsafter an oracle breakpoint, from the payee by allowancefrom value still held, to the payer, on a report signed by a breach signer the payee accepted, or on the payee's own signature
OwnershipOwnableOwnable2Step; renouncing reverts
Pausenoneblocks new opens and live settles only, at most 3 days, with a 1-day cooldown; never moves funds
Signing domain version"1""2": a voucher for one version is refused by the other

The repository runs the same scenarios against both versions and checks these differences explicitly:

cd "$DYNAMO_REPO"
pwd
make test-version-seam

The version seam (for operators)

A stablecoin deployment keeps a registry of its vault deployments, one entry per vault, each with a version and a status. At start-up the core reads each vault's signing domain on chain and refuses a mismatch, a duplicate entry or a deprecated default. A new budget uses the deployment named for it, else the default, else the single active one; with several active deployments and no default the open is refused, and a deprecated deployment opens no new budget.

Contract v2 is configured only when you set it. With none of these settings, the v1 vault serves every budget exactly as before.

SettingMeaning
CORE_ESCROW_V2_VAULTthe BudgetVaultV2 address (needs CORE_ESCROW_V2_ASSET)
CORE_ESCROW_V2_ASSETa stablecoin listed in the v2 asset registry
CORE_ESCROW_V2_ASSET_REGISTRYoptional; checked against the vault's own registry
CORE_ESCROW_V2_RELAYER_KEYoptional relayer that pays gas only and holds no payee key; unset, payees settle through the payee kit with their own key
CORE_ESCROW_DEFAULT_VERSIONv2 (default when v2 is configured) or v1: the version new budgets use
CORE_ESCROW_V1_STATUSdeprecated (default when v2 is configured) or active: deprecated v1 keeps serving its budgets and opens no new one
CORE_ESCROW_RAIL_MODEtest (default) or live: on the hosted service, test mode refuses a non-local chain; live needs CORE_ESCROW_LIVE_AUDIT_FLAG and stops at escrow_live_release_gated

The core refuses to start on a partial v2 configuration, when v2 is set without the v1 escrow settings, and when the default version is the deprecated one.

Steps for an operator

  1. Deploy contract v2 next to your v1 vault and list your stablecoin in its asset registry.
  2. Set CORE_ESCROW_V2_VAULT and CORE_ESCROW_V2_ASSET (and the optional settings you need).

New budgets default to v2; v1 opens none unless you set CORE_ESCROW_V1_STATUS=active for a side-by-side lab.

  1. Restart the core and check it starts: it verifies each vault's domain on chain.
  2. Existing v1 budgets keep running on v1. To open new v1 budgets beside v2, set

CORE_ESCROW_DEFAULT_VERSION=v1 and CORE_ESCROW_V1_STATUS=active explicitly.

  1. Hosted public-chain usdc stays off until the audit flag and founder release gate

(CORE_ESCROW_RAIL_MODE=live).

User-owned budgets: adopt-prepare and adopt (owner-api 1.7.0)

A payer can fund a v2 budget from their own wallet, so the core never holds the payer's key:

  1. /owner/v1/budgets/adopt-prepare: the core prepares the terms and a session key and answers an

adoption id, the session key, the mandate fingerprint and the on-chain amounts. For a client pinned at owner-api 1.8.0 it also answers the budget and stream ids and the root hop intent to sign with the wallet that opens the budget.

  1. The payer opens the budget and its root stream on chain from their own wallet.
  2. /owner/v1/budgets/adopt: the core checks every fact on chain (the budget exists, its owner,

asset and the asset's listing, cap, escrow, mandate fingerprint, not revoked, not expired; the root stream exists and is the budget's root, its session key, payee, rate and cap, not revoked, nothing settled yet) and records the budget only if all of them match; on a mismatch nothing is recorded. A client pinned at owner-api 1.8.0 gets 409 adopt_refused naming the failed check; earlier pins keep the earlier error answer.

Under required own hops, a client pinned at owner-api 1.8.0 must send the owner's signed hop intent and the payee's signed offer at adopt. A client pinned earlier can still adopt without them, but that budget's evidence then cannot be exported as 1.3.1 or 1.4.0. Owner-api 1.8.0 adds the same flow for a child stream at /owner/v1/streams/{id}/children/adopt-prepare and /owner/v1/streams/{id}/children/adopt.

What changes for payers

What changes for payees

your own key through the payee kit.

Compatibility guarantees

the table above.