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).
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-onlyplanandstatususe the identity indeployment.jsonordeployment.pending.jsonwithout a key;TEMPO_RPC_URL(or--rpc-url), fordeploy,verify, anddeposit.
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.
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.
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, andfactories, the resolved shared factory release;deploymentIntentHashandcomponentDeploymentIntentHashes, one hash per intent component (core,engine,zone,targetYield,boostRewards,zoneRouterFactory,zoneRouter,nullwhen 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, anddeploymentBlock, the earliest block of a deployment transaction;actions: each completed deployment step with its transaction hashes;runtimeCodeHashesfor 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.
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-verificationRepair 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.
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-onlyverify 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).
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.
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>.jsonThe 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 100DeployFactoryRelease 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.
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 --slowThe 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).
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.