Skip to content

Latest commit

 

History

History
606 lines (532 loc) · 49.7 KB

deployment.md

File metadata and controls

606 lines (532 loc) · 49.7 KB

Earn deployment lifecycle

This runbook owns the shared deployment lifecycle: the pnpm earn commands, the generated record, verification, authority handoffs, and the hosted contract releases: Earn's shared factory releases, the Zone router releases, and the Bridge releases. The authored profile JSON is in deployment profiles, each capability's own steps in its module page, engine installation in yield engines, and package exports in the deployment package reference.

The current Foundry deployment scripts and this profile lifecycle tooling are outside audit scope (audits).

Commands

One profile JSON drives every command, and deploy is the only one an operator must run:

cp .env.example .env.e2e-moderato
pnpm earn plan profiles/e2e-moderato/profile.json
pnpm earn deploy profiles/e2e-moderato/profile.json
pnpm earn status profiles/e2e-moderato/profile.json
pnpm earn verify profiles/e2e-moderato/profile.json
Command What it does Flags
plan Prints the planned actions. With an RPC, it labels a privileged action authority only after read-only calls prove the configured signer holds it; otherwise handoff. --rpc-url, --json
deploy Reconciles the profile until it completes or reaches an external authority (lifecycle). --rpc-url, --json, --watch (rechecks every 15 seconds until the handoff completes), --resubmit-verification
status Reads the record or pending state without chain reads: not-started, in-progress, deployed, verification-pending, or complete. --json
verify Rechecks a completed record against the live chain without a signer; read-only unless verifier repair is requested (rechecking). --rpc-url, --json, --skip-zone, --resubmit-verification
deposit Quotes, and with --broadcast submits, a user deposit into the deployed stack. see below
access Reads or changes one member of a protected profile's TIP-403 whitelist (access). --earn-file <profile.json> <status|add|remove> <address>

plan, deploy, status, verify, and deposit also accept --trusted-identity <path> for an independently reviewed historical deployment identity (shared factory releases).

Every command loads only the ignored .env.<profile-id> beside the profiles/ directory that holds the profile (the repository root for this repository's own; profiles in another repository); values already in the process environment take precedence. A command fails, naming that file, when neither supplies a value it needs:

  • DEPLOYER_PRIVATE_KEY, to establish a fresh deterministic deployment identity; read-only plan and status use the identity in deployment.json or deployment.pending.json without a key;
  • TEMPO_RPC_URL (or --rpc-url), for deploy, verify, and deposit.

verify and deposit --broadcast of a Zone profile also need TEMPO_API_KEY or ZONE_RPC_URL unless --skip-zone is passed.

ZONE_ADMIN_PRIVATE_KEY is optional: when set, deploy performs the Zone administrator's steps (authority boundaries). Plans are derived and never checked in.

The deposit helper quotes through the engine's own module for any engine kind:

# Read-only quote plus deployment and wiring checks
pnpm earn deposit profiles/e2e-moderato/profile.json --assets 1

# Submit the atomic approval + deposit transaction
pnpm earn deposit profiles/e2e-moderato/profile.json --assets 1 --broadcast

--assets is a decimal amount of the vault asset. The helper signs with DEPLOYER_PRIVATE_KEY; --account <address> quotes for another account without that key, and --receiver <address> mints elsewhere. The minimum output defaults to 50 bps below the quote (--slippage-bps, 0 to 9999). The quote uses one block snapshot and includes pending fee dilution; a zero-share minimum is refused. With --broadcast, it first runs the same checks as verify (record provenance, source verification, and the stack the reviewed factories predict) and refuses to sign for a record that fails them; --skip-zone applies as it does for verify. It refuses an RPC whose chain or genesis differs from the record. Nothing is sent without --broadcast, and approval and deposit are one Tempo transaction. A hosted record with pending source verification may be quoted but cannot be funded until verification completes; local records whose verification is not applicable remain usable. The creation engine must match the profile’s authored venue. An operator-migrated engine uses its current venue only when both the profile and vault permit operator migration.

Lifecycle

profile.json + .env.<profile-id>
  -> refuse privileged roles held by a public fixture identity
  -> with a committed record: recheck its provenance and source verification onchain
     without one: match shared factories to the reviewed release and adopted engine runtime to this checkout
  -> discover L1 genesis and each capability's external identity (such as the Zone Portal)
  -> reconcile the deployment steps, stopping at an external authority it cannot act as
  -> verify deployed state and publish deployment.json with source verification pending
  -> attempt every activation step, reporting the first handoff afterward
  -> verify contract sources, then remove the pending state

Rerun the same command after an external authority acts; it resumes from chain state. Deployment steps must all complete before the record is published. Activation steps (pool admission, Zone token enablement, gateway registration) are mutable external readiness: each is attempted on every run, a handoff on one does not block the others or source verification, and none of them is recorded as a completed action. Forge writes only where its project's foundry.toml allows, so each Forge step writes its outputs to a staging copy under the ignored earn/.earn/external/<id>-<path-hash>/, which the tooling moves back into the profile's deployment.pending.json after the step or, if the run stopped, on the next run. A step whose contracts live in a sibling Foundry project, such as the Zone router's in zone-router/, names it as its project: Forge compiles, broadcasts and source-verifies from that project, and writes its outputs to the same place as Earn's steps. The hash identifies the canonical profile path, so profiles with the same ID in different repositories cannot share staging state or Forge receipts. Receipts live under <foundry-project>/broadcast/<id>-<path-hash>/. An unscoped staging journal at .earn/external/<id>/deployment.pending.json blocks resume: verify which canonical profile owns it, then move it to that profile's hashed staging path. The tool cannot safely assign a shared-ID journal automatically.

deploy holds an adjacent deployment.pending.json.lock directory for the run, refusing concurrent writers to the same profile. Normal completion or failure releases it. After a crash, verify that no deployment process is still active before manually removing a stale lock; never delete a live run's lock or its pending state to force another writer through.

The profile declares immutable creation intent and the external readiness it requires; the chain is authoritative, and later operator-authorized changes are operational state. The ignored deployment.pending.json beside the profile is the only private resume state. It records the profile ID, deployer, final owner, factory release, intent hash, pinned factory runtime hashes, discovered and deployed addresses, and each completed action's transactions. Consumers use the typed handoff or completed record and never parse it. Deleting it changes nothing onchain, but before the record is published it discards the transaction provenance a clean resume needs. Pending state resumes only under the identity that wrote it: a different deployer, factory release, or intent hash (including a checkout that hashes intent differently) is refused, so finish an unpublished deployment before moving to a newer checkout of this repository. Pinned factory hashes identify the selected shared release, not every local contract or the Git checkout. A resume does not recompile that release or enforce Git-commit equality. Hosted direct creations still require mined input matching the selected checkout before their completion is cached or published; incompatible earlier creations fail without replacing their transactions. The record's Git commit identifies the checkout capturing the record, not every step's original checkout; per-contract runtime, creation-transaction, and source-input evidence establish contract identity.

Deployment subprocesses use the repository's deploy Foundry profile, which compiles for Cancun like Tempo's deployment runtime and writes separate artifacts. A hosted broadcast requires the toolchain Foundry version on PATH, checked when reconciliation first reaches a broadcast. Foundry output files are not proof of deployment, because simulation can write them before broadcast: completion and crash recovery accept an output only after the expected code and immutable bindings are observed onchain. EarnFactory.deploy is permissionless and refuses an occupied EarnShare prediction, so when the profile's predicted EarnShare already exists and no Foundry output of this run explains it, deploy-core adopts that stack instead of retrying. It records the addresses DeployEarnCore would have written, including the engine and its asset, which a configured engine has no other step to record, and the factory transaction that created the stack: the predicted EarnShare and EarnFees cover every creation-time parameter, and inspection checks the adopted stack before any record is written. An interrupted run's own outputs are recovered first. Either way, deploy-core records the transaction named by the factory's EarnStackDeployed event for that EarnShare, never an unrelated hash from Forge's latest-broadcast file. Per-profile receipt isolation does not replace this event and onchain binding check. deploy-zone-router likewise adopts the router its permissionless ZoneRouterFactory already deployed for the profile's mode, such as one Spend's script created, recording the transaction its RouterDeployed event names. Factory-provisioned engines also adopt their exact creation event rather than an unrelated receipt. For other creating steps, an interrupted broadcast's saved transaction hashes are confirmed against RPC receipts when Forge has not saved successful receipts. For hosted deployments, every recovered creation hash must also prove the expected direct creation or factory event before it is saved, even when Forge has saved a successful receipt. Direct creation also requires the expected deployer and the complete transaction input to match the step's compiled creation bytecode and constructor arguments. A matching deployed runtime alone does not prove constructor execution. Rejected evidence leaves the action unchanged, so correcting the artifact or RPC evidence permits another retry without rebroadcasting. Resume can repair an empty pending action's transaction list without rebroadcasting, preserving its completion metadata and any later step's saved outputs. A missing receipt does not hide another confirmed transaction in the same broadcast artifact; transport failures remain retryable. If every candidate receipt is missing, the error names the artifact that needs the original or replacement transaction evidence. Already-satisfied steps that create no contracts do not require old broadcast receipts. For a published record still marked source-verification pending, recovered creation hashes replace empty action transaction lists before verification. An earlier successful receipt moves deploymentBlock back to the earliest recorded receipt, never forward, preserving a conservative claim-scan boundary. Target creation, runtime, receipt, and applicable archive checks run before publication; canonical source verification remains a separate requirement. Recovery never rewrites nonempty committed creation history or verified records. An invalid nonempty action from an earlier run requires reviewed record correction, not automatic replacement or an advanced claim-scan boundary. Missing or ambiguous creation evidence still fails source verification. Before binding, predicted core addresses and reciprocal asset, engine, and fee-module bindings must match; an engine already bound elsewhere stops rather than producing an impossible handoff.

Generated record

When the deployment steps complete, the command atomically publishes deployment.json beside profile.json, initially with source.contractVerification: "pending", then upgrades it in place to "verified" once source verification succeeds. Neither file contains secrets. Commit the profile and record together, but treat the record as complete only once contractVerification is verified. Never edit generated addresses into the profile or hand-copy them into E2E arguments.

The record (version: 4) contains:

  • deploymentId, deployer, owner, and factories, the resolved shared factory release;
  • deploymentIntentHash and componentDeploymentIntentHashes, one hash per intent component (core, engine, zone, targetYield, boostRewards, zoneRouterFactory, zoneRouter, null when not configured; a record written before a component existed omits it);
  • target: the chain ID, L1 genesis hash, and each capability's external identity, such as the Zone's ID, chain ID, Portal, and Messenger;
  • addresses, assetDecimals, and deploymentBlock, the earliest block of a deployment transaction;
  • actions: each completed deployment step with its transaction hashes;
  • runtimeCodeHashes for every recorded address with code;
  • source: the factory deployment ID, Git commit and dirty state, Foundry version, verifier URL, and per-contract source verification.

Changing intent, replacing code, or restoring state across a regenesis therefore cannot silently reuse stale addresses. Publication is strict: the record must contain exactly the addresses and completed deployment steps derived from the plan. Activation steps are not recorded; their state is always read from the pool and Portal. Changing an optional component (zone, targetYield, boostRewards, zoneRouterFactory, zoneRouter) redeploys only that component's contracts and republishes the record; core and engine creation intent never changes in place, so a record whose core or engine hash differs from the profile is refused. The deployment-fixed engine migration mode either permits the operator to move the whole pool to a replacement engine (OperatorEnabled) or permanently forbids that action (UserOnly). A permitted whole-pool migration does not rewrite creation provenance. Live inspection and the hosted stack projection resolve the vault's current engine, venue, kind, and exit capabilities, while contracts.creationEngine preserves the original address. Unknown or ambiguous replacement kinds, invalid reciprocal bindings, or migration under UserOnly (which permanently disables that operator action) are refused. The creation record's source verification does not verify a replacement engine; review its provenance separately.

The record does not choose its own trust roots. source.factoryDeploymentId must equal the keccak-256 hash of <profile-id>:v<version>, and the recorded verifier must be the trusted Tempo verifier the tooling hard-codes before it is contacted. Every ordinary Solidity source match must identify the expected fully qualified contract. Initial verification requires the exact complete Forge compiler-input source set and matching checkout contents, not a selected subset. A Solidity source match for a profile-deployed contract requires one recorded creation transaction. Its successful RPC receipt must identify the contract directly or through the expected factory's creation event, and the verifier must return the same hash. Missing, ambiguous, or unrelated receipt evidence fails before source submissions. Direct creation additionally compares the mined transaction input with the verifier's canonical-source-bound compiled creation bytecode and the declared constructor arguments, checking the transaction hash and expected deployer. A partial source match may differ only in the digests inside a recognized terminal chain of Solidity IPFS metadata trailers, including adjacent child-initcode metadata. Compiler versions, executable bytes, arguments, and input length still match exactly. Unsupported metadata formats or missing compiled creation bytecode fail closed. Fresh checkout proof before caching or publication remains byte-for-byte exact. Before an unpublished deployment can bind an engine selected by address, preflight also compares its runtime with the engine kind's local compilation. Every occurrence of one compiler-declared immutable must contain the same value before those slots are normalized on both sides. This runs again on resume even when factory hashes are pinned; mismatches fail before deployment or authority broadcasts. ERC-4626 inspection also requires deployed nonzero venue and asset addresses, agreement between the venue asset and the engine's asset and baseAsset, and shareScale() equal to 10 ** venue.decimals() with at most 77 decimals. Veda inspection likewise requires shareScale() equal to 10 ** vault.decimals() with at most 77 decimals, in both readiness and bindings-only rechecks. Grouped immutable consistency alone cannot authenticate this constructor-derived value. Address-selected profiles derive the venue from the authenticated engine; this is not an independently authored venue allowlist. A published hosted record without admitted engine source identity receives the same local runtime check before retrying any activation. Records retaining admitted engine identity, including partial pending records for unrelated component changes, keep their historical runtime and source evidence instead of requiring today's engine compilation. Adopted engines still require their separate source-only verifier check because the profile does not own their creation inputs. Historical rechecks of recorded source identities compare the source-input hash and contract name without requiring the original checkout or Git object. Direct-creation rechecks use that historical verifier compilation rather than today's local bytecode. This also applies before republishing unchanged, already-verified direct creations when another optional component changes. Source matches may strengthen from match to exact_match but never downgrade. The Git commit remains provenance, not a required local object. Changing the recorded deployment transaction or Zone Factory identity requires a fresh successful verification before promotion.

A profile-named Zone router factory must already have a source match against the canonical checkout before its event is trusted. The created contract records that factory's address, name, match strength and source-input hash. Historical rechecks use this independent factory identity, not the evolving checkout; changed verifier sources and weaker matches fail. A record without this factory evidence still requires the canonical factory checkout and is never silently rewritten.

Recorded source verification proves the originally admitted contract, not compatibility with the current router ABI. Unchanged release-1 profiles retain their factory and router addresses; a router with only settlers() and no readable spenders() is explicitly refused during inspection or resume, including Earn-only modes. Preserve recorded addresses, hashes, and source evidence; --resubmit-verification cannot upgrade an immutable contract. Inspect or manage that router with its original tooling, or review a separate migration to a source-verified compatible factory and new router, including pool and Portal admissions and caller updates. This command never automatically replaces the historical router to resolve an ABI mismatch.

On a fresh checkout, the command seeds pending state from the committed record only after revalidating its runtime provenance, derived contract identity, and each completed action onchain; a stale or edited record is rejected before it can drive an authority transaction. A record marked pending resumes without redeploying completed steps; activation state is read again before source verification completes.

When a record lacks a core-creation receipt, including one with receipts for other actions, its deploymentBlock needs archival evidence that the vault had no code immediately before that block. With no deployment receipts at all, the vault must also match its current runtime at the claimed block. Present-day code verification alone does not establish the creation boundary. This archival check does not replace the creation receipt required to complete hosted source verification; recover the original creation transaction before verifying an adopted record.

Source verification

For hosted deployments, pnpm earn deploy submits missing source to https://contracts.tempo.xyz, waits for a bytecode and source match, and saves the result in deployment.json. A verifier outage (unreachable, 429 or 5xx, on lookup or on forge's submission, a job that does not complete, or only transient compiler errors) leaves the record pending and the state verification-pending: rerunning resumes at verification after rechecking deployed state, and never rebroadcasts. When an optional component changes, an outage also leaves the replacement record published and allows activation. Unchanged contracts retain their admitted source identities in that pending record when their creating step's intent, action, and output address are unchanged; a changed consumer does not discard its factory's identity. Completion rechecks retained identities rather than replacing them with the current checkout. Any other failure, such as a new source that differs from the checkout, a wrong contract name or creation transaction, or a verifier refusal, fails the command with a nonzero exit; the record stays pending, and rerunning after the fix resumes the same way. Verification errors redact configured RPC URLs and credentials, including encoded forms, HTTP Basic authentication tokens, and the credential-stripped transport URL, so path and query tokens stay hidden. Repeated redaction keeps masks stable. Errors do not retain subprocess error causes or fields that could expose credentials. For an invalid existing verifier entry, explicitly request canonical re-verification:

# A pending record must finish through deploy; this resumes the existing deployment.
pnpm earn deploy profiles/<profile-id>/profile.json --resubmit-verification
# A completed record can repair verifier evidence without rewriting its recorded source identity.
pnpm earn verify profiles/<profile-id>/profile.json --resubmit-verification

Repair leaves valid entries unchanged. Completed records are checked against the hashes of source paths and contents saved at deployment, even when the selected checkout has changed. Before submitting any required repair, the command checks that each affected contract's complete compiler source list and local file contents reproduce its recorded hash. It repeats this check before every submission attempt. Incompatible inputs fail before submission: use the recorded source revision and its pinned dependencies.

For contracts created by the profile, repair submits the recorded creation transaction with those sources and the selected compiler settings. The returned address, contract, full source set, match strength, and creation hash must still satisfy the recorded evidence. Existing engines selected by address rather than deployed by this profile must already have matching source; the lifecycle does not own their creation inputs. New outputs in pending records must match the selected checkout. Retained identities from an earlier verified record keep their original source hashes and match strength through optional-component reconciliation and cache-free retries. verify without the flag never submits jobs; the flag authorizes verifier writes, not onchain writes. Only deploy upgrades a pending record to verified, so use it to finish an incomplete deployment.

The verifier rejects replacement of an exact match with 409 already_verified, even when its creation hash is absent. That response needs verifier-side repair; neither this flag nor repeated runs bypasses it. Partial entries can be resubmitted, but the verifier does not replace a conflicting non-null creation hash; that also requires verifier-side repair. Until the returned evidence passes, a pending record stays pending and funding stays blocked. Never edit the record to remove the creation transaction.

Source inputs are hashed in a fixed (en) collation, so the recorded hash does not depend on the operator's locale. Hosted completion cannot opt out of source verification. A contract from a sibling project, such as zone-router/'s ZoneRouterFactory and ZoneRouter, is submitted from that project with its own compiler settings; its sources may include Earn's through linked/earn/, and each must resolve inside the checkout and match it. The factory-created ZoneRouter records the factory.deploy transaction that emitted its RouterDeployed event as its creation transaction.

The record classifies actual code forms instead of treating every output as an ordinary Solidity deployment. Ordinary contracts keep the verifier's exact_match or normalized match; the canonical Zone Messenger is a functionally authenticated protocol precompile without a runtime-code hash; EarnVault records its ERC-1967 proxy plus the factory implementation's address and runtime-code hash; EarnFees records the canonical minimal proxy with the same implementation provenance; and EarnShare records its protocol-native TIP-20 factory. Shared implementation source verification belongs to the factory release, not to each profile.

Rechecking deployed profiles

pnpm check validates Earn's committed profiles and their records offline. To recheck a deployed profile against its live chain, run on demand, with no signer:

pnpm earn verify profiles/<profile-id>/profile.json
pnpm e2e:profile profiles/<profile-id>/profile.json --validate-only

verify checks the record's target, addresses, provenance, and recorded source verification, and reports engine and capability readiness, such as router conversion inventory. For a Zone profile it also requires TEMPO_API_KEY or ZONE_RPC_URL to confirm the live Zone; --skip-zone checks everything else and reports the Zone as not verified. --validate-only fails on what verify only reports: engine or capability readiness, custody, EarnShare issuer exclusivity, accounting alignment, and required TIP-403 members (profile acceptance). Nothing reruns these checks on a schedule, here or in a deployments repository that holds other stacks (profiles in another repository).

Authority boundaries

Steps run in the order of deploymentSteps; a profile's plan is the enabled subset. Each module page owns its steps' preconditions and results.

Before any step, pnpm earn deploy refuses a deployer or privileged role derived from a private key in the public .env.example, even when an explicit owner is safe. The guard covers core's roles (owner, including one defaulted from the deployer; emergency guardian; async janitor; every fee recipient; fee distributor) and every role a capability slice declares through privilegedPrincipals, such as the reward treasury.

Step Phase Authority (signer) Owner
deploy-engine deployment deployer (DEPLOYER_PRIVATE_KEY) Factory-provisioned engine
deploy-core deployment deployer EarnShare, EarnVault, and EarnFees with the exact configuration
bind-core deployment current engine owner (DEPLOYER_PRIVATE_KEY when it holds the role) Bind EarnVault and atomically transfer the engine to the configured final owner
deploy-router deployment deployer Zones
deploy-zone-router-factory deployment deployer Zone router
deploy-zone-router deployment deployer Zone router
deploy-merkle-distributor deployment deployer Rewards
validate-access deployment deployer Access policy
deploy-contribution-controller deployment deployer Rewards
authorize-router activation PropAMM pool owner (DEPLOYER_PRIVATE_KEY when it holds the role) Zones
enable-zone-tokens activation Zone Portal administrator (ZONE_ADMIN_PRIVATE_KEY) Zones
register-zone-gateway activation Zone Portal administrator (ZONE_ADMIN_PRIVATE_KEY) Zones
authorize-zone-router activation PropAMM pool owner (DEPLOYER_PRIVATE_KEY when it holds the role) Zone router
enable-zone-router-tokens activation Zone Portal administrator (ZONE_ADMIN_PRIVATE_KEY) Zone router
register-zone-router-gateway activation Zone Portal administrator (ZONE_ADMIN_PRIVATE_KEY) Zone router
admit-zone-router-account activation Zone Portal administrator (ZONE_ADMIN_PRIVATE_KEY) Zone router

Deployment scripts receive only DEPLOYER_PRIVATE_KEY; Forge never receives another authority key. Read-only version, build, provenance, source-verification, and formatting subprocesses receive no signing keys. A Foundry project's .env is refused, and its effective compiler configuration must match its tracked foundry.toml; keep credentials in the profile-specific environment file. Operational authority and deposit sends pin the final signed calls, chain, pending nonce in protocol nonce key 0, and a locally set 300-second expiry. Explicit fee tokens and chain-configured fee tokens stay pinned; otherwise authority sends retain the account or protocol fee preference. Deposits explicitly pay fees in the vault asset. Altered RPC-provided signing fields or a gas fee liability above $1 abort before signing. Each typed authority step first proves with read-only calls that its signer holds the exact authority (the Zone administrator key may also be the sole owner of a threshold-1 Safe that administers the Portal), batches its changes atomically, and continues. Authority signing is pinned to the profile's chain and the protocol nonce: the client refuses an RPC that reports another chain ID or fills a transaction under another nonce key, because viem would otherwise sign what the RPC fills. When no configured signer holds the authority, the command emits a handoff naming the exact call and addresses for its actual owner. Stale pending state or a plausible-looking transaction hash cannot bypass the onchain check.

The reconciler returns a typed complete or handoff result, the stable boundary for automation; an adapter may satisfy only authority it legitimately owns before invoking it again.

Shared factory releases

Production profiles consume a reviewed release from the per-chain release registry; they never deploy shared implementations. A release names the EarnFactory (earn) and, under each engine's factory.releaseKey, the engine factories it carries. Each chain has exactly one current release: an unpublished pending deployment must use it, and a committed record keeps the release it pinned. Finish or discard any pending deployment before replacing a chain's release. Before a fresh deployment's first broadcast, the deploy command compiles the current EarnFactory, EarnVault, EarnFees, and, for a profile that provisions its engine from a venue, that engine's factory, and compares their runtime code with the reviewed onchain release and its immutable implementation bindings, so a source change requires a fresh release. Pending deployments pin the resolved factory runtime hashes; completed records keep the release with their source provenance. Resuming a historical release requires the independently reviewed deployer and factory identity in the registry; a pending journal cannot authorize its own deployer, factory address, or runtime hash. An unknown hosted record must be enrolled through reviewed identity data or supplied with an independent trusted identity. The CLI accepts --trusted-identity <path>; deployment-package callers supply trustedIdentity. The separate JSON file must contain exactly deployer and factories, with the reviewed deployer address and factory-release object. A full deployment.json is rejected. Review this identity independently; copying the untrusted record into a new file does not establish trust. Importing a record never enrolls it automatically. A registry-known identity always uses its reviewed baseline, even when an explicit trusted identity is supplied.

pnpm earn verify ../deployments/profiles/<profile-id>/profile.json \
  --trusted-identity ../deployments/reviewed-identities/<profile-id>.json

The profile-index command also accepts these files: pnpm profiles --profiles <dir> --trusted-identity <path>. Repeat --trusted-identity for mixed-profile directories. It tries the built-in registry first; supplied independent identities can admit only otherwise unknown profiles. Without any flags, it takes one file from EARN_TRUSTED_DEPLOYMENT_IDENTITY. The same identity checks apply, with no automatic enrollment from records.

Releases create EarnShare with empty currency metadata ("") and the underlying asset as its quote token: an EarnShare is not a USD stablecoin or a 1:1 claim on another EarnShare. Shared factories are ownerless, and their constructors impose no PATHUSD transfer-policy ID. The deployer must be funded and authorized to pay fees under its chosen fee token's live policy; a custom PATHUSD policy does not by itself block a release.

Earn compiles with solar (earn/solar.lock). Tempo's source verifier rebuilds only the solar builds it pins in tempo-apps' solar-builds.json, so a new solar.lock revision must be added there and deployed before a hosted deployment built with it. Source verification passes Forge the solar build (--compiler-version, from earn/solar-solc --version, with --compilation-profile default); a manual forge verify-contract needs the same two flags. Deploy a core release with:

FOUNDRY_PROFILE=deploy forge script \
  script/deploy/DeployFactoryRelease.s.sol:DeployFactoryReleaseScript \
  --sig 'earnFactoryRelease(uint256)' 4217 \
  --network tempo --rpc-url https://rpc.tempo.xyz --broadcast --slow \
  --gas-estimate-multiplier 100

DeployFactoryRelease holds the core (earnFactoryRelease) and rewards (earnRewardsFactory) release entry points; each engine factory's entry point lives in that engine's deploy script. Every entry point takes the expected chain ID, refuses another chain or a Foundry profile other than deploy, and broadcasts with DEPLOYER_PRIVATE_KEY. Every release contract is created deterministically (DeterministicRelease): through the CREATE2 deployer 0x4e59b44847b379578588920cA78FbF26c0B4956C, present on every Tempo network and in localnet's genesis, with one fixed salt, so the same creation code and constructor arguments land at the same address on Moderato and mainnet, and an entry point reuses a contract that already exists there instead of creating it again. Changing the compiler, its settings, or a contract's source changes its address. Release contracts are ownerless, so anyone creating one first only pays its fee. earnFactoryRelease creates the EarnVault and EarnFees implementations and the immutable factory bound to them, and checks its code and bindings. Tempo's RPC must supply the creation estimate for the large EarnVault implementation; only this release pins Forge's multiplier to 100, because default padding can exceed Tempo's 30M gas cap. After a failed broadcast, rerunning the entry point creates only what is missing. Source-verify all three contracts before updating the registry. Localnet deploys the same release, at the same addresses and reusing contracts that already exist (a persistent devnet deployed before), through the single-creation entry points earnVaultImplementation, earnFeesImplementation, and earnFactory, plus every registered engine factory's entry point.

Releasing from CI

The Factory Release workflow (factory-release.yml) releases from main in one run. Choose the networks (both runs Moderato, then mainnet only after Moderato succeeds), the releases (all is the core release and every engine factory the registry names; core, rewards, or one engine factory's releaseKey, such as erc4626Engine, deploys just that one), and whether to broadcast. Each network's job runs pnpm factory-release <network> <release|all> [--broadcast] [--resubmit-verification] (core/factory-release.ts), which runs each release's entry point below with the deploy profile, checks that it created exactly the contracts missing from their deterministic addresses, each from the locally compiled creation code, and, after a broadcast, source-verifies every contract in the release on Tempo's verifier. A release whose contracts all exist is reconciled without running Forge, so rerunning all deploys only what changed. For invalid verifier entries, --resubmit-verification requires --broadcast and follows the same repair limits; it does not force redeployment. Without broadcast, Forge only simulates, at the same addresses a broadcast uses. Each job's summary and its factory-release-<network>-<attempt> artifact list the addresses, transactions, and source matches; a run that stops keeps the releases before it. The Zone router and Bridge releases share these environments and the hosted-contracts queue, and release separately (Zone router releases, Bridge releases); the command refuses them.

Registry inputs must contain the complete expected contract set at addresses independently derived from the local compile and CREATE2 parameters, with only match or exact_match source results. Every release validates the RPC chain. Existing selector-latest receipts are archived before a new attempt, so an old file cannot prove a new creation. Direct CREATE2 attribution requires the mined receipt and actual transaction calldata; a nested router requires its matching factory event. Already-present contracts without that creation proof are recorded as reused with no creator transaction. Reused routers still require each spender's router-factory binding to match.

After a broadcast, the last job records every release whose contracts all source verified, from every network that reached it, in releases.ts on a factory-release/<run>-<attempt> branch (pnpm factory-release registry) and links it in the job summary with the pull request description; a maintainer opens that pull request, so the registry changes only through its review.

Dispatching the workflow from main is the approval: each network's job runs in the factory-release-<network> environment, which has no required reviewer, accepts only main, and holds DEPLOYER_PRIVATE_KEY (and optional TEMPO_RPC_URL, TEMPO_RPC_USERNAME, TEMPO_RPC_PASSWORD). Both environments hold the same deployer key that local profile deployments use; releases are ownerless, so it only pays fees. Rotating it updates both environments. The network's hosted-contracts-<network> queue orders only CI jobs, so do not broadcast with that key locally while a release runs. The same command runs locally with DEPLOYER_PRIVATE_KEY exported, for example from a profile's .env.<id>; it does not load dotenv files itself.

An engine factory release is independent: the <releaseKey>Factory entry point of the engine's deploy script (for example erc4626EngineFactory in DeployERC4626Engine) deploys it. Deploy one when the engine creation bytecode changes, then source-verify it before updating the registry. A core already created against an old engine remains tied to that engine.

FOUNDRY_PROFILE=deploy forge script \
  script/deploy/DeployERC4626Engine.s.sol:DeployERC4626EngineScript \
  --sig 'erc4626EngineFactory(uint256)' 42431 \
  --network tempo --rpc-url https://rpc.moderato.tempo.xyz --broadcast --slow

Zone router releases

The Zone router's ownerless contracts release apart from Earn's, through the Zone Router Release workflow (zone-router-release.yml) and pnpm zone-router-release <network> <release> [--parameters <json>] [--broadcast] (core/zone-router-release.ts), which accepts only these releases. It runs the same release engine as factory releases, from zone-router/ with its own solar build and deploy profile: the same address, creation-code, and receipt checks, reconciling a release that already exists, and source verification after a broadcast. Its CLI also accepts --resubmit-verification with --broadcast, with the same repair limits. None has a registry entry, so there is no all and nothing is recorded afterwards. Pass a release's parameters as one JSON object (--parameters, or the workflow's parameters input, which reaches the command only through the environment); the command validates them before Forge runs, refuses parameters for the factory, and records them in the result and the job summary.

The workflow runs from main only. Choose the networks (both runs Moderato, then mainnet only after Moderato succeeds), one release and its parameters, and whether to broadcast. Each job's summary and its zone-router-release-<network>-<attempt> artifact list the addresses, transactions, source matches, and parameters, with zone-router/broadcast/. As with factory releases, the dispatch is the approval: each network's job runs in the same factory-release-<network> environment, with no required reviewer, main only, and the same deployer key; the contracts are ownerless, so the key only pays fees. It shares the network's hosted-contracts-<network> queue with the factory and Bridge releases.

Release Parameters Creates
zoneRouterFactory None The ZoneRouterFactory
sendSpender {}, or {"vault": <address>, "pool": <address>, "customerId": <bytes32>}; optional "factory" A SendSpender, never converting or converting vault's asset at par
zoneRouter {"factory": <address>, "mode": {...}} The router factory.deploy(mode) creates

A SendSpender accepts spends only from routers its factory deployed whose mode lists it. Without factory, the release binds the release ZoneRouterFactory (the zoneRouterFactory release's address) and deploys that factory first when it is missing, so operators pass no factory and the spender's address still follows from the build and settings alone. List it only in modes deployed through that factory.

A zoneRouter mode has ZoneRouter.Mode's fields: zoneId, enabledOps (deposit 1, redeem 2, spend 4), earnVault and privateAsset (exactly with deposit or redeem), pool and customerId (together, for a converting Earn mode), and spenders (exactly with spend; their order is part of the mode). Omitted fields are zero.

pnpm zone-router-release moderato zoneRouter \
  --parameters '{"factory": "<ZoneRouterFactory>", "mode": {"zoneId": 7, "enabledOps": 4, "spenders": ["<SendSpender>"]}}'

DeployRouterRelease holds their entry points, with the same chain, profile, and deployer checks as DeployFactoryRelease. The factory and each spender are created through the CREATE2 deployer with Earn's release salt (DeterministicRelease), and a router by its factory at predict(mode), salted by the mode's hash. So a ZoneRouterFactory or SendSpender of the same build and settings, and a ZoneRouter of the same factory and mode, lands at the same address whoever deploys it, on every network, and an entry point reuses one that exists (a router only if factory.isRouter says its factory made it). Forge records the router as a contract its factory call created; the command matches it by address and checks it like any other creation, then source-verifies it with abi.encode(mode) as its constructor arguments. A release deploys only: the pool owner still admits a converting spender or router, and the Zone's Portal administrator a router (Zone router deployment).

Bridge releases

The Bridge Release workflow (bridge-release.yml) deploys the card integration's "TS" handler (SpenderTempoSpend), or a Bridge card program (its BridgeProvider and CardSpender, through the CardFactory) for Bridge's SpenderFactory from main, at its deterministic address, with cards/' own build. It runs in the same factory-release-<network> environment and hosted-contracts-<network> queue, one network per dispatch, and lists in its summary the calls Bridge's admin and governance submit to register and gate the handler; it never submits them. A program also takes routerFactory, the Zone router release's ZoneRouterFactory: only its routers may call the program's spendFrom, and the release CardFactory and the program's address depend on it. Deploying from CI owns the details.