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
| Area | Contract v1 | Contract v2 |
|---|---|---|
| Revoke cut-off | A voucher settles only if signed strictly before the revoke | A voucher signed at or before the cut-off settles, for a grace window of 7 days after it |
| Delegation depth | up to 8 | up to 16 |
| Fee ceiling | MAX_FEE_BPS = 1000 | MAX_FEE_BPS = 150, fixed per stream at open; a fee change never raises a running stream's fee |
| Who signs vouchers | the stream's session key, or the budget owner | the stream's session key only |
| Who submits a settle | the payee | anyone (relayed); the money still goes to the payee |
| When the payee is paid | at settle | settled value is held and released when its holdback matures (at most 90 days) |
| Refunds | after an oracle breakpoint, from the payee by allowance | from value still held, to the payer, on a report signed by a breach signer the payee accepted, or on the payee's own signature |
| Ownership | Ownable | Ownable2Step; renouncing reverts |
| Pause | none | blocks 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.
| Setting | Meaning |
|---|---|
CORE_ESCROW_V2_VAULT | the BudgetVaultV2 address (needs CORE_ESCROW_V2_ASSET) |
CORE_ESCROW_V2_ASSET | a stablecoin listed in the v2 asset registry |
CORE_ESCROW_V2_ASSET_REGISTRY | optional; checked against the vault's own registry |
CORE_ESCROW_V2_RELAYER_KEY | optional relayer that pays gas only and holds no payee key; unset, payees settle through the payee kit with their own key |
CORE_ESCROW_DEFAULT_VERSION | v2 (default when v2 is configured) or v1: the version new budgets use |
CORE_ESCROW_V1_STATUS | deprecated (default when v2 is configured) or active: deprecated v1 keeps serving its budgets and opens no new one |
CORE_ESCROW_RAIL_MODE | test (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
- Deploy contract v2 next to your v1 vault and list your stablecoin in its asset registry.
- Set
CORE_ESCROW_V2_VAULTandCORE_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.
- Restart the core and check it starts: it verifies each vault's domain on chain.
- 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.
- 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:
/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.
- The payer opens the budget and its root stream on chain from their own wallet.
/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
- Amounts on v2 are in the stablecoin's own base units, rounded up from the engine's micro-USD.
- A budget can carry an expiry; the engine signs no voucher after it.
- Refunds come from value still inside its holdback, and always go back to the payer.
- Unspent escrow comes back only once no signed voucher can still claim it.
What changes for payees
- You are paid when each held amount's holdback matures; anyone can trigger the release.
- A settle can be relayed, so you need not submit it yourself. Without a relayer you settle with
your own key through the payee kit.
- Work you signed for before a revoke or expiry stays settleable for
7days after the cut-off. - A v1 voucher does not settle on v2, and a v2 voucher does not settle on v1.
Compatibility guarantees
- Versions are never upgraded in place, and a budget never moves between versions.
- The invariant, mode-identity and evidence suites run against both versions.
- A new contract version may add features; where an outcome differs, the difference is named, as in
the table above.