@aztec/aztec 0.0.1-commit.3fd054f6 → 0.0.1-commit.431c48d

package/src/deploy/runner.ts

@@ -0,0 +1,936 @@
+/**
+ * The deployment engine: turns a declarative {@link DeploymentSpec} into one dependency graph of
+ * steps (contracts + actions), runs only what's missing, and is safe to re-run.
+ *
+ *   resolve accounts → resolve deterministic addresses → inventory → plan → fund → execute → output
+ *
+ * Each phase is a method on {@link DeploymentRun}, which holds the state the phases share;
+ * {@link runDeployment} strings them together in the order above.
+ *
+ * - Deterministic contracts (addresses are a pure function of class/deployer/salt/args) resolve
+ *   UPFRONT, so the plan knows their addresses before anything is sent.
+ * - Deferred contracts (args read runtime state) resolve at INVENTORY TIME when the state their
+ *   args read already exists (the re-run case, which is what makes re-runs no-ops), and otherwise
+ *   AT EXECUTION TIME, once their `dependsOn` has run.
+ * - Steps execute in topological layers over the single graph, so an action can precede a contract
+ *   it sets up. Within a layer, contract publishes are individual txs and same-account actions batch
+ *   into ≤{@link APP_MAX_CALLS}-call BatchCalls. The one-time fee-juice claim per account is
+ *   consumed + mined by that account's first tx before the rest fan out.
+ * - Fund steps provision arbitrary addresses (contracts or accounts that never send) with bridged
+ *   Fee Juice: bridge at execution time, then an L2 claim tx from the step's `from` account. Their
+ *   claims persist between bridge and claim, so a crashed run resumes instead of re-bridging.
+ */
+import type { ContractArtifact } from '@aztec/aztec.js/abi';
+import { AztecAddress } from '@aztec/aztec.js/addresses';
+import { BatchCall, type ContractBase, DeployMethod } from '@aztec/aztec.js/contracts';
+import { Fr } from '@aztec/aztec.js/fields';
+import { type AztecNode, createAztecNodeClient } from '@aztec/aztec.js/node';
+import { FeeJuiceContract } from '@aztec/aztec.js/protocol';
+import { APP_MAX_CALLS } from '@aztec/entrypoints/encoding';
+import { chunk, compactArray } from '@aztec/foundation/collection';
+import { getPXEConfig } from '@aztec/pxe/server';
+import { getContractClassFromArtifact, getContractInstanceFromInstantiationParams } from '@aztec/stdlib/contract';
+import { deriveKeys, deriveMasterMessageSigningSecretKey } from '@aztec/stdlib/keys';
+import type { TxReceipt } from '@aztec/stdlib/tx';
+import { EmbeddedWallet } from '@aztec/wallets/embedded';
+
+import { join } from 'node:path';
+
+import {
+  type FeeSession,
+  type SendFee,
+  accountFunding,
+  defaultFeePolicy,
+  obtainFeeJuiceClaim,
+  prepareFeeSession,
+  publicFeeJuiceBalance,
+} from './fees.js';
+import { scheduleLayers, topologicalLayers } from './graph.js';
+import {
+  type DeployPlan,
+  type DeployReporter,
+  type DeploySummary,
+  type DeployUnitKind,
+  consoleReporter,
+} from './reporter.js';
+import { type DeployState, loadState, saveState } from './state.js';
+import type {
+  ActionStep,
+  ContractStep,
+  Ctx,
+  DeploymentSpec,
+  FeePolicy,
+  FundStep,
+  Resolver,
+  StepSpec,
+  Steps,
+} from './types.js';
+
+/** A step's idempotency gate (transitively) depends on itself. */
+class GateCycleError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'GateCycleError';
+  }
+}
+
+function getOrThrow<Value>(map: Map<string, Value>, alias: string, kind: string): Value {
+  const value = map.get(alias);
+  if (value === undefined) {
+    throw new Error(`Unknown ${kind} "${alias}".`);
+  }
+  return value;
+}
+
+function isDeferred<C>(step: ContractStep<C>): boolean {
+  return step.deferredInitializerArgs != null;
+}
+
+/**
+ * The contract aliases a pure resolver callback looks up, extracted by dry-running it against a
+ * resolver that records each `contract(alias)` lookup instead of resolving it. The callback's return
+ * value is discarded and the ZERO addresses never leave this function — which is what requires such
+ * callbacks to be pure: they run here with fake addresses and again later with real ones.
+ */
+function referencedContracts(run: (resolve: Resolver) => unknown): string[] {
+  const references = new Set<string>();
+  run({
+    account: () => AztecAddress.ZERO,
+    contract: alias => {
+      references.add(alias);
+      return AztecAddress.ZERO;
+    },
+  });
+  return [...references];
+}
+
+/** One tx to send: a single contract publish, or a batch of same-account actions. */
+interface ExecutionUnit {
+  label: string;
+  kind: DeployUnitKind;
+  account: AztecAddress;
+  send: (fee: SendFee) => Promise<unknown>;
+}
+
+/**
+ * Runs a {@link DeploymentSpec}: resolves accounts and deterministic addresses, inventories what's
+ * already on-chain, reports the plan, funds the working accounts, and executes the missing steps in
+ * dependency layers. Idempotent — a re-run sends nothing when everything is already in place.
+ */
+export async function runDeployment<C extends Steps>(spec: DeploymentSpec<C>): Promise<void> {
+  const run = await DeploymentRun.create(spec);
+  await run.resolveDeterministicContracts();
+  await run.takeInventory();
+  const plan = await run.reportPlan();
+  if (run.hasNothingToDo()) {
+    run.reportNothingToDo();
+    await run.writeOutputs();
+    return;
+  }
+  const feeSession = await run.prepareFees(plan);
+  await run.executeLayers(feeSession);
+  await run.writeOutputs();
+  run.reportSummary();
+}
+
+/**
+ * One deployment run: the state shared across phases, with one method per phase. Build with
+ * {@link DeploymentRun.create}, then call the phase methods in the order {@link runDeployment}
+ * does — each phase reads state the earlier ones populated.
+ */
+class DeploymentRun<C extends Steps> {
+  private readonly local: boolean;
+  private readonly label: string;
+  private readonly reporter: DeployReporter;
+  private readonly stateDirectory: string;
+  private readonly state: DeployState;
+  private readonly defaultSalt: Fr;
+  private readonly globalPolicy: FeePolicy;
+
+  // The steps map partitioned by kind once, so lookups are typed without casts.
+  private readonly steps: Map<string, StepSpec<C>>;
+  private readonly contractSteps = new Map<string, ContractStep<C>>();
+  private readonly actionSteps = new Map<string, ActionStep<C>>();
+  private readonly fundSteps = new Map<string, FundStep>();
+  /** Contract→contract address deps, auto-derived from deterministic `initializerArgs`. */
+  private readonly contractRefs: Map<string, string[]>;
+
+  // Populated as accounts resolve, contracts resolve (upfront, at inventory, or deferred at
+  // execution), and txs land.
+  private readonly accountAddresses = new Map<string, AztecAddress>();
+  private readonly policyByAddress = new Map<string, FeePolicy>();
+  private readonly contractAddresses = new Map<string, AztecAddress>();
+  private readonly contractInstances = new Map<string, ContractBase>();
+  private readonly deployMethods = new Map<string, DeployMethod<ContractBase>>();
+  private readonly classIds = new Map<string, Fr>();
+  private readonly publishedThisRun = new Set<string>();
+  private readonly classesPublishedThisRun = new Set<string>();
+  private readonly publishedCache = new Map<string, Promise<boolean>>();
+  private readonly gateCache = new Map<string, Promise<boolean>>();
+  private readonly gateInProgress = new Set<string>();
+  private readonly fundGateCache = new Map<string, Promise<boolean>>();
+
+  // Populated by the resolve / inventory / plan phases.
+  private resolveOrder: string[] = [];
+  private readonly actionsToRun = new Set<string>();
+  private readonly fundsToRun = new Set<string>();
+  private execAliases: string[] = [];
+  private layers: string[][] = [];
+
+  private readonly resolver: Resolver;
+  private readonly ctx: Ctx<C>;
+  /** Set only when the spec gave a URL — a connected node serves the debug API for warping itself. */
+  private readonly nodeUrl: string | undefined;
+
+  private constructor(
+    private readonly spec: DeploymentSpec<C>,
+    private readonly node: AztecNode,
+    private readonly wallet: EmbeddedWallet,
+  ) {
+    this.nodeUrl = typeof spec.node === 'string' ? spec.node : undefined;
+    this.local = spec.local ?? false;
+    this.label = spec.label ?? (this.local ? 'local' : 'network');
+    this.reporter = spec.reporter ?? consoleReporter();
+    this.stateDirectory = spec.stateDir ?? join(process.cwd(), '.deploy-state');
+    this.state = loadState(this.stateDirectory);
+    this.defaultSalt = spec.salt ?? new Fr(0);
+    this.globalPolicy = spec.fees ?? defaultFeePolicy(this.local);
+
+    this.steps = new Map(Object.entries(spec.steps) as [string, StepSpec<C>][]);
+    for (const [alias, step] of this.steps) {
+      if (step.kind === 'contract') {
+        this.contractSteps.set(alias, step);
+      } else if (step.kind === 'action') {
+        this.actionSteps.set(alias, step);
+      } else {
+        this.fundSteps.set(alias, step);
+      }
+    }
+    this.contractRefs = this.recordContractRefs();
+
+    this.resolver = {
+      account: alias => getOrThrow(this.accountAddresses, alias, 'account'),
+      contract: alias => getOrThrow(this.contractAddresses, alias, 'contract'),
+    };
+    this.ctx = {
+      ...this.resolver,
+      instance: ((alias: string) =>
+        getOrThrow(this.contractInstances, alias, 'contract instance')) as Ctx<C>['instance'],
+      done: id => this.done(id),
+      ran: id => this.ran(id),
+      wallet,
+      node,
+    };
+  }
+
+  /** Validates the spec, connects the node + ephemeral wallet, then resolves accounts and class ids. */
+  public static async create<C extends Steps>(spec: DeploymentSpec<C>): Promise<DeploymentRun<C>> {
+    DeploymentRun.validateSpec(spec);
+    const node = typeof spec.node === 'string' ? createAztecNodeClient(spec.node) : spec.node;
+    const wallet = await EmbeddedWallet.create(node, {
+      ephemeral: true,
+      pxeConfig: { ...getPXEConfig(), proverEnabled: !(spec.local ?? false) },
+    });
+    const run = new DeploymentRun(spec, node, wallet);
+    await run.resolveAccounts();
+    await run.computeClassIds();
+    return run;
+  }
+
+  /** Static spec validation — everything that can be rejected before touching the network. */
+  private static validateSpec<C extends Steps>(spec: DeploymentSpec<C>): void {
+    if (!spec.node) {
+      throw new Error('runDeployment requires a `node` on the spec — a JSON-RPC URL or a connected node.');
+    }
+    const steps = Object.entries(spec.steps) as [string, StepSpec<C>][];
+    const aliases = new Set(steps.map(([alias]) => alias));
+    for (const [alias, step] of steps) {
+      for (const dependency of step.dependsOn ?? []) {
+        if (!aliases.has(dependency)) {
+          throw new Error(`Unknown step "${dependency}" in dependsOn of "${alias}".`);
+        }
+      }
+      if (step.kind === 'fund' && step.amount <= 0n) {
+        throw new Error(`Fund step "${alias}" must bridge a positive amount.`);
+      }
+      if (step.kind !== 'contract') {
+        continue;
+      }
+      if (step.initializerArgs && step.deferredInitializerArgs) {
+        throw new Error(`Contract "${alias}" declares both initializerArgs and deferredInitializerArgs — pick one.`);
+      }
+      if (!isDeferred(step)) {
+        continue;
+      }
+      if (step.mode === 'register') {
+        throw new Error(`Contract "${alias}" is register-mode with deferred args — registration has no tx to defer.`);
+      }
+      if (step.dependsOn == null) {
+        throw new Error(
+          `Contract "${alias}" has deferred args but no dependsOn. Declare the steps whose effects the args read,` +
+            ` or an explicit empty array if they only read pre-existing state.`,
+        );
+      }
+    }
+  }
+
+  /** Resolves every deterministic contract upfront, layer by layer in constructor-arg dependency order. */
+  public async resolveDeterministicContracts(): Promise<void> {
+    const deterministicAliases = [...this.contractSteps]
+      .filter(([, step]) => !isDeferred(step))
+      .map(([alias]) => alias);
+    const layers = topologicalLayers(deterministicAliases, this.contractRefs);
+    this.resolveOrder = layers.flat();
+    for (const layer of layers) {
+      await Promise.all(
+        layer.map(alias => {
+          const step = getOrThrow(this.contractSteps, alias, 'contract');
+          return this.resolveContract(alias, step, step.initializerArgs?.(this.resolver) ?? []);
+        }),
+      );
+    }
+  }
+
+  /** Inventory: which steps still need doing? */
+  public async takeInventory(): Promise<void> {
+    // Deterministic publishes missing on-chain. The checks are independent node reads, so they run
+    // concurrently.
+    const missing = await Promise.all(
+      this.resolveOrder.map(async alias => {
+        const step = getOrThrow(this.contractSteps, alias, 'contract');
+        return step.mode === 'publish' && !(await this.isPublished(alias)) ? alias : undefined;
+      }),
+    );
+    for (const alias of compactArray(missing)) {
+      this.publishedThisRun.add(alias);
+    }
+
+    // Deferred contracts: try to resolve now — on a re-run the state their args read is already
+    // on-chain, so the address derives and publication is checked like any other contract (which is
+    // what makes re-runs no-ops). When the args can't resolve yet, the contract publishes this run
+    // and re-resolves at execution time, after its `dependsOn` has run. Runs before the action
+    // gates, so `ran`/`done` on a deferred contract answer correctly inside them.
+    for (const [alias, step] of this.contractSteps) {
+      if (isDeferred(step) && !(await this.tryResolveDeferred(alias, step))) {
+        this.publishedThisRun.add(alias);
+      }
+    }
+
+    // Fund gates: recipients whose public Fee Juice balance is below the step's threshold. Runs
+    // before the action gates so `ctx.done`/`ctx.ran` on a fund step answer correctly inside them.
+    for (const alias of this.fundSteps.keys()) {
+      if (!(await this.fundGate(alias))) {
+        this.fundsToRun.add(alias);
+      }
+    }
+
+    // Action gates. Sequential on purpose: evaluating them concurrently would turn the cyclic-gate
+    // detection (gateInProgress) into a silent deadlock of promises awaiting each other.
+    for (const alias of this.actionSteps.keys()) {
+      if (!(await this.actionGate(alias))) {
+        this.actionsToRun.add(alias);
+      }
+    }
+
+    this.execAliases = [
+      ...[...this.contractSteps.keys()].filter(alias => this.publishedThisRun.has(alias)),
+      ...[...this.fundSteps.keys()].filter(alias => this.fundsToRun.has(alias)),
+      ...[...this.actionSteps.keys()].filter(alias => this.actionsToRun.has(alias)),
+    ];
+  }
+
+  /**
+   * Builds the plan — account funding postures, per-step statuses, and the execution layers — and
+   * reports it (the default reporter renders it to stderr). The fund phase consumes its accounts.
+   */
+  public async reportPlan(): Promise<DeployPlan> {
+    const accountUsedBy = new Set<string>();
+    for (const alias of this.execAliases) {
+      const step = getOrThrow(this.steps, alias, 'step');
+      const address = step.kind === 'contract' ? step.deployer(this.resolver) : step.from(this.resolver);
+      accountUsedBy.add(address.toString());
+    }
+    const stepStatus = (alias: string, step: StepSpec<C>): DeployPlan['steps'][number]['status'] => {
+      if (step.kind === 'action') {
+        return this.actionsToRun.has(alias) ? 'to run' : 'done';
+      }
+      if (step.kind === 'fund') {
+        return this.fundsToRun.has(alias) ? 'to fund' : 'funded';
+      }
+      if (step.mode === 'register') {
+        return 'registered';
+      }
+      return this.publishedThisRun.has(alias) ? 'to publish' : 'published';
+    };
+    this.layers = this.buildLayers();
+    const plan: DeployPlan = {
+      label: this.label,
+      accounts: await Promise.all(
+        Object.keys(this.spec.accounts).map(async alias => {
+          const address = getOrThrow(this.accountAddresses, alias, 'account');
+          const policy = getOrThrow(this.policyByAddress, address.toString(), 'policy');
+          return {
+            alias,
+            address,
+            funding: await accountFunding(policy, this.wallet, address, accountUsedBy.has(address.toString())),
+          };
+        }),
+      ),
+      steps: [...this.steps].map(([id, step]) => ({
+        id,
+        kind: step.kind,
+        status: stepStatus(id, step),
+        dependsOn: [...(this.contractRefs.get(id) ?? []), ...(step.dependsOn ?? [])],
+      })),
+      layers: this.layers,
+    };
+    this.reporter.onPlan?.(plan);
+    return plan;
+  }
+
+  public hasNothingToDo(): boolean {
+    return this.execAliases.length === 0;
+  }
+
+  public reportNothingToDo(): void {
+    this.reporter.onNothingToDo?.(this.label);
+  }
+
+  /**
+   * Fund phase: prepares each working account's fee session per its resolved policy + funding
+   * (bridging Fee Juice when needed). The session owns all claim state — see
+   * {@link FeeSession.hasPendingClaim}.
+   */
+  public prepareFees(plan: DeployPlan): Promise<FeeSession> {
+    return prepareFeeSession({
+      local: this.local,
+      node: this.node,
+      nodeUrl: this.nodeUrl,
+      wallet: this.wallet,
+      state: this.state,
+      persist: () => this.persist(),
+      reporter: this.reporter,
+      accounts: plan.accounts
+        .filter(a => a.funding.kind !== 'idle')
+        .map(a => ({
+          address: a.address,
+          policy: getOrThrow(this.policyByAddress, a.address.toString(), 'policy'),
+          funding: a.funding,
+        })),
+    });
+  }
+
+  /** Executes the layers in order: publishes as individual txs, same-account actions batched. */
+  public async executeLayers(feeSession: FeeSession): Promise<void> {
+    for (const layer of this.layers) {
+      await this.runLayer(
+        [...this.publishUnits(layer), ...this.fundUnits(layer), ...this.actionUnits(layer)],
+        feeSession,
+      );
+    }
+  }
+
+  /** Persists resolved addresses and runs the spec's `output` hook against the final ctx. */
+  public async writeOutputs(): Promise<void> {
+    for (const [alias, address] of this.contractAddresses) {
+      this.state.addresses[alias] = address.toString();
+    }
+    this.persist();
+    await this.spec.output?.(this.ctx);
+  }
+
+  public reportSummary(): void {
+    const summary: DeploySummary = {
+      label: this.label,
+      contracts: [...this.contractAddresses].map(([alias, address]) => ({
+        alias,
+        address,
+        status: getOrThrow(this.contractSteps, alias, 'contract').mode === 'register' ? 'registered' : 'published',
+      })),
+      accounts: [...this.accountAddresses].map(([alias, address]) => ({ alias, address })),
+    };
+    this.reporter.onComplete?.(summary);
+  }
+
+  /** Accounts are initializerless (no deploy tx). Per-account salt + fee policy override the spec. */
+  private async resolveAccounts(): Promise<void> {
+    await Promise.all(
+      Object.entries(this.spec.accounts).map(async ([alias, account]) => {
+        const derived = await this.wallet.createSchnorrInitializerlessAccount(
+          account.secret,
+          account.salt ?? this.defaultSalt,
+          deriveMasterMessageSigningSecretKey(account.secret),
+        );
+        this.accountAddresses.set(alias, derived.address);
+        this.policyByAddress.set(derived.address.toString(), account.fees ?? this.globalPolicy);
+      }),
+    );
+  }
+
+  /**
+   * Class ids come from the ARTIFACT (not the instance/args), so they're known upfront for every
+   * contract — deferred ones included. This lets class-publish ordering cover all same-class
+   * contracts, so exactly one publishes the class and the rest are ordered after it (no race).
+   * Steps sharing a generated contract class share the artifact object, so the id is computed once
+   * per artifact identity — hashing it is CPU-heavy.
+   */
+  private async computeClassIds(): Promise<void> {
+    const idByArtifact = new Map<ContractArtifact, Promise<Fr>>();
+    await Promise.all(
+      [...this.contractSteps].map(async ([alias, step]) => {
+        if (step.mode !== 'publish') {
+          return;
+        }
+        let id = idByArtifact.get(step.contract.artifact);
+        if (!id) {
+          id = getContractClassFromArtifact(step.contract.artifact).then(contractClass => contractClass.id);
+          idByArtifact.set(step.contract.artifact, id);
+        }
+        this.classIds.set(alias, await id);
+      }),
+    );
+  }
+
+  /** Contract→contract address deps, auto-derived from each deterministic `initializerArgs`. */
+  private recordContractRefs(): Map<string, string[]> {
+    const contractRefs = new Map<string, string[]>();
+    for (const [alias, step] of this.contractSteps) {
+      contractRefs.set(alias, step.initializerArgs ? referencedContracts(step.initializerArgs) : []);
+    }
+    return contractRefs;
+  }
+
+  /**
+   * Publishes/registers a contract from already-computed initializer args (used upfront for
+   * deterministic contracts, and at inventory or execution time for deferred ones). Both modes
+   * derive the address from the full instantiation params — deployer and secret-derived public
+   * keys included — so a registered contract lands on the same address publishing it would.
+   */
+  private async resolveContract(alias: string, step: ContractStep<C>, args: unknown[]): Promise<void> {
+    this.publishedCache.delete(alias); // re-resolution may change the address
+    const salt = step.salt ?? this.defaultSalt;
+    const deployer = step.deployer(this.resolver);
+    const publicKeys = step.secret ? (await deriveKeys(step.secret)).publicKeys : undefined;
+    if (step.mode === 'publish') {
+      const deployMethod = DeployMethod.create<ContractBase>(
+        this.wallet,
+        {
+          artifact: step.contract.artifact,
+          postDeployCtor: (instance, boundWallet) => step.contract.at(instance.address, boundWallet),
+          args,
+          ...(step.initializer ? { constructorNameOrArtifact: step.initializer } : {}),
+        },
+        { deployer, salt, ...(publicKeys ? { publicKeys } : {}) },
+      );
+      const instance = await deployMethod.getInstance();
+      this.contractAddresses.set(alias, instance.address);
+      this.contractInstances.set(alias, step.contract.at(instance.address, this.wallet));
+      this.deployMethods.set(alias, deployMethod);
+      await this.wallet.registerContract(instance, step.contract.artifact, step.secret);
+    } else {
+      const instance = await getContractInstanceFromInstantiationParams(step.contract.artifact, {
+        salt,
+        deployer,
+        ...(publicKeys ? { publicKeys } : {}),
+        ...(args.length ? { constructorArgs: args } : {}),
+        ...(step.initializer ? { constructorArtifact: step.initializer } : {}),
+      });
+      this.contractAddresses.set(alias, instance.address);
+      this.contractInstances.set(alias, step.contract.at(instance.address, this.wallet));
+      await this.wallet.registerContract(instance, step.contract.artifact, step.secret);
+    }
+  }
+
+  /**
+   * Attempts to resolve a deferred contract from current on-chain state, and reports whether there
+   * is no work left for it this run — the args resolved AND the instance is already published.
+   * Attempted only once every step it declares is in place, actions included: its args read their
+   * effects, so resolving earlier would derive the address from state that does not exist yet.
+   */
+  private async tryResolveDeferred(alias: string, step: ContractStep<C>): Promise<boolean> {
+    if (!(await this.dependenciesReady(alias, { contractsOnly: false }))) {
+      return false;
+    }
+    await this.runRecorded(alias, `Deferred initializer args for contract "${alias}"`, async ctx =>
+      this.resolveContract(alias, step, await step.deferredInitializerArgs!(ctx)),
+    );
+    return this.isPublished(alias);
+  }
+
+  /**
+   * Whether the steps `alias` declares as dependencies are all in place: a contract published or
+   * registered per its mode, a fund step above its threshold, an action already done. With
+   * `contractsOnly`, contracts alone — a gate exists to observe whether the actions and funds it
+   * follows landed, so it must still run once the contracts it reads are there.
+   */
+  private async dependenciesReady(alias: string, { contractsOnly }: { contractsOnly: boolean }): Promise<boolean> {
+    const step = getOrThrow(this.steps, alias, 'step');
+    for (const dependency of [...(this.contractRefs.get(alias) ?? []), ...(step.dependsOn ?? [])]) {
+      if (contractsOnly && getOrThrow(this.steps, dependency, 'step').kind !== 'contract') {
+        continue;
+      }
+      if (!(await this.done(dependency))) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Runs a user callback against a ctx that records every contract alias it looks up, then requires
+   * those to be declared in the step's `dependsOn` — an undeclared read is state nothing checked was
+   * in place. The check runs even when the callback throws, so a callback that catches its own
+   * errors (the usual shape for a getter that reverts when unset) can't hide one.
+   */
+  private async runRecorded<T>(alias: string, description: string, run: (ctx: Ctx<C>) => Promise<T>): Promise<T> {
+    const references = new Set<string>();
+    const ctx: Ctx<C> = {
+      ...this.ctx,
+      contract: reference => {
+        references.add(reference);
+        return this.resolver.contract(reference);
+      },
+      instance: ((reference: string) => {
+        references.add(reference);
+        return getOrThrow(this.contractInstances, reference, 'contract instance');
+      }) as Ctx<C>['instance'],
+    };
+    let result: T;
+    try {
+      result = await run(ctx);
+    } catch (error) {
+      this.assertReferencesDeclared(alias, description, references, error);
+      throw error;
+    }
+    this.assertReferencesDeclared(alias, description, references);
+    return result;
+  }
+
+  /**
+   * Rejects contract aliases the callback read but the step doesn't declare. `cause` carries the
+   * error the callback threw, since an undeclared read is the likeliest reason it did.
+   */
+  private assertReferencesDeclared(alias: string, description: string, references: Set<string>, cause?: unknown): void {
+    const step = getOrThrow(this.steps, alias, 'step');
+    const declared = new Set([...(this.contractRefs.get(alias) ?? []), ...(step.dependsOn ?? [])]);
+    const undeclared = [...references].filter(reference => !declared.has(reference));
+    if (undeclared.length > 0) {
+      throw new Error(
+        `${description} reads ${undeclared.map(reference => `"${reference}"`).join(', ')} but does not declare it in` +
+          ` dependsOn. Declare every step it reads, so it only runs once they are in place.`,
+        { cause },
+      );
+    }
+  }
+
+  /** Whether the alias's resolved instance is published on-chain. Memoized — one node read per address. */
+  private isPublished(alias: string): Promise<boolean> {
+    const address = this.contractAddresses.get(alias);
+    if (!address) {
+      return Promise.resolve(false); // deferred & not yet resolved
+    }
+    let cached = this.publishedCache.get(alias);
+    if (!cached) {
+      cached = this.wallet.getContractMetadata(address).then(metadata => metadata.isContractPublished);
+      this.publishedCache.set(alias, cached);
+    }
+    return cached;
+  }
+
+  /**
+   * A fund step's idempotency gate: whether the recipient's public Fee Juice balance already
+   * clears the step's threshold. A recipient this run has yet to put in place holds nothing, so the
+   * balance is read only once the contracts its selector references are there. Memoized per run.
+   */
+  private fundGate(alias: string): Promise<boolean> {
+    const step = getOrThrow(this.fundSteps, alias, 'fund step');
+    let cached = this.fundGateCache.get(alias);
+    if (!cached) {
+      cached = (async () => {
+        for (const reference of referencedContracts(step.recipient)) {
+          if (!(await this.done(reference))) {
+            return false;
+          }
+        }
+        const recipient = step.recipient(this.resolver);
+        return (await publicFeeJuiceBalance(this.wallet, recipient, step.from(this.resolver))) >= step.threshold;
+      })();
+      this.fundGateCache.set(alias, cached);
+    }
+    return cached;
+  }
+
+  /**
+   * An action's `done` gate, memoized per run. Invoked only once the contracts the action declares
+   * are in place: until then the action cannot have run, and the gate would read state that does not
+   * exist. Gates may consult other steps via `ctx.done`, so a gate that (transitively) depends on
+   * itself throws {@link GateCycleError}.
+   */
+  private actionGate(alias: string): Promise<boolean> {
+    const step = this.actionSteps.get(alias);
+    if (!step) {
+      throw new Error(`Unknown action "${alias}".`);
+    }
+    if (this.gateInProgress.has(alias)) {
+      return Promise.reject(new GateCycleError(`Cyclic idempotency gate at "${alias}".`));
+    }
+    const cached = this.gateCache.get(alias);
+    if (cached) {
+      return cached;
+    }
+    this.gateInProgress.add(alias);
+    const pending = (async () => {
+      if (!(await this.dependenciesReady(alias, { contractsOnly: true }))) {
+        return false;
+      }
+      return this.runRecorded(alias, `Idempotency gate for action "${alias}"`, ctx => step.done(ctx));
+    })().finally(() => this.gateInProgress.delete(alias));
+    this.gateCache.set(alias, pending);
+    return pending;
+  }
+
+  /** `ctx.done`: whether step `id` is already satisfied this run — mode-aware. */
+  private done(id: string): Promise<boolean> {
+    const step = this.steps.get(id);
+    if (!step) {
+      throw new Error(`Unknown step "${id}".`);
+    }
+    if (step.kind === 'action') {
+      return this.actionGate(id);
+    }
+    if (step.kind === 'fund') {
+      return this.fundGate(id);
+    }
+    if (step.mode === 'register') {
+      return Promise.resolve(this.contractAddresses.has(id)); // registered in the PXE
+    }
+    return this.isPublished(id);
+  }
+
+  /** `ctx.ran`: whether step `id` did (or will do) work this run — mode-aware. */
+  private async ran(id: string): Promise<boolean> {
+    const step = this.steps.get(id);
+    if (!step) {
+      throw new Error(`Unknown step "${id}".`);
+    }
+    if (step.kind === 'action') {
+      return !(await this.actionGate(id));
+    }
+    if (step.kind === 'fund') {
+      return this.fundsToRun.has(id);
+    }
+    if (step.mode === 'register') {
+      return this.contractAddresses.has(id); // (re)registered this run
+    }
+    return this.publishedThisRun.has(id);
+  }
+
+  /**
+   * Builds the execution graph over the steps that run and groups it into layers. Exactly one
+   * contract per class publishes it (the first in declaration order); every other same-class
+   * contract — deterministic or deferred — is ordered after it.
+   */
+  private buildLayers(): string[][] {
+    const publisherByClass = new Map<string, string>();
+    for (const [alias, step] of this.contractSteps) {
+      if (step.mode !== 'publish') {
+        continue;
+      }
+      const classId = getOrThrow(this.classIds, alias, 'class id').toString();
+      if (!publisherByClass.has(classId)) {
+        publisherByClass.set(classId, alias);
+      }
+    }
+    const execDeps = new Map<string, string[]>();
+    for (const alias of this.execAliases) {
+      const step = getOrThrow(this.steps, alias, 'step');
+      // Constructor address refs (contractRefs) do NOT order publishes — addresses are deterministic,
+      // so a contract can publish in parallel with the ones it references. Only `dependsOn` (an action
+      // it follows / runtime state a deferred contract reads) and shared-class publication order here.
+      const deps = new Set<string>(step.dependsOn ?? []);
+      if (step.kind === 'contract' && step.mode === 'publish') {
+        const classId = this.classIds.get(alias)?.toString();
+        const publisher = classId ? publisherByClass.get(classId) : undefined;
+        if (publisher && publisher !== alias) {
+          deps.add(publisher);
+        }
+      }
+      execDeps.set(alias, [...deps]);
+    }
+    // Actions float as late as their dependents allow, so same-account actions coalesce into one
+    // batched tx; contract publishes stay early (they unblock dependents and aren't batched).
+    return scheduleLayers(this.execAliases, execDeps, id => getOrThrow(this.steps, id, 'step').kind === 'action');
+  }
+
+  /** A layer's contract publishes — one tx each (deferred contracts resolve their address first). */
+  private publishUnits(layer: string[]): ExecutionUnit[] {
+    const units: ExecutionUnit[] = [];
+    for (const alias of layer.filter(a => this.contractSteps.has(a))) {
+      const step = getOrThrow(this.contractSteps, alias, 'contract');
+      const account = step.deployer(this.resolver);
+      units.push({
+        label: `publish ${alias}`,
+        kind: 'publish',
+        account,
+        send: async fee => {
+          if (isDeferred(step)) {
+            // Re-resolve with post-`dependsOn` state: the inventory attempt either failed or ran
+            // before this run's earlier layers landed.
+            await this.resolveContract(alias, step, await step.deferredInitializerArgs!(this.ctx));
+          }
+          const classId = getOrThrow(this.classIds, alias, 'class id');
+          const deployMethod = getOrThrow(this.deployMethods, alias, 'deploy method');
+          const classKey = classId.toString();
+          const alreadyRegistered =
+            this.classesPublishedThisRun.has(classKey) ||
+            (await this.wallet.getContractClassMetadata(classId)).isContractClassPubliclyRegistered;
+          this.classesPublishedThisRun.add(classKey);
+          const sent = await deployMethod.send({
+            from: account,
+            fee,
+            wait: { timeout: 120 },
+            skipClassPublication: alreadyRegistered,
+          });
+          this.publishedCache.set(alias, Promise.resolve(true));
+          return sent;
+        },
+      });
+    }
+    return units;
+  }
+
+  /**
+   * A layer's fund steps — one unit each: obtain the recipient's claim (resume the persisted one,
+   * or bridge from L1 and wait for the message), then send the L2 `FeeJuice.claim` tx from the
+   * step's `from` account.
+   */
+  private fundUnits(layer: string[]): ExecutionUnit[] {
+    const units: ExecutionUnit[] = [];
+    for (const alias of layer.filter(a => this.fundSteps.has(a))) {
+      const step = getOrThrow(this.fundSteps, alias, 'fund step');
+      const account = step.from(this.resolver);
+      units.push({
+        label: `fund ${alias}`,
+        kind: 'fund',
+        account,
+        send: async fee => {
+          const recipient = step.recipient(this.resolver);
+          const claim = await obtainFeeJuiceClaim({
+            local: this.local,
+            node: this.node,
+            nodeUrl: this.nodeUrl,
+            recipient,
+            amount: step.amount,
+            l1: { l1FunderKey: step.l1FunderKey, l1RpcUrl: step.l1RpcUrl, l1ChainId: step.l1ChainId },
+            state: this.state,
+            persist: () => this.persist(),
+            reporter: this.reporter,
+          });
+          const sent = await FeeJuiceContract.at(this.wallet)
+            .methods.claim(recipient, claim.claimAmount, claim.claimSecret, claim.messageLeafIndex)
+            .send({ from: account, fee, wait: { timeout: 120 } });
+          claim.onConsumed();
+          return sent;
+        },
+      });
+    }
+    return units;
+  }
+
+  /** A layer's actions, batching independent same-account actions into ≤{@link APP_MAX_CALLS}-call BatchCalls. */
+  private actionUnits(layer: string[]): ExecutionUnit[] {
+    const actionsByAccount = new Map<string, { account: AztecAddress; aliases: string[] }>();
+    for (const alias of layer.filter(a => this.actionSteps.has(a))) {
+      const account = getOrThrow(this.actionSteps, alias, 'action').from(this.resolver);
+      const group = actionsByAccount.get(account.toString());
+      if (group) {
+        group.aliases.push(alias);
+      } else {
+        actionsByAccount.set(account.toString(), { account, aliases: [alias] });
+      }
+    }
+    const units: ExecutionUnit[] = [];
+    for (const { account, aliases } of actionsByAccount.values()) {
+      for (const batch of chunk(aliases, APP_MAX_CALLS)) {
+        units.push({
+          label: batch.length === 1 ? `action ${batch[0]}` : `batch [${batch.join(', ')}]`,
+          kind: 'action',
+          account,
+          send: async fee => {
+            const interactions = await Promise.all(
+              batch.map(alias => getOrThrow(this.actionSteps, alias, 'action').call(this.ctx)),
+            );
+            const sendOptions = { from: account, fee, wait: { timeout: 120 } };
+            return interactions.length === 1
+              ? interactions[0].send(sendOptions)
+              : new BatchCall(this.wallet, interactions).send(sendOptions);
+          },
+        });
+      }
+    }
+    return units;
+  }
+
+  private async runLayer(units: ExecutionUnit[], feeSession: FeeSession): Promise<void> {
+    if (units.length === 0) {
+      return;
+    }
+    // Per-account claim serialization: the first paying tx of each claim-holding account must mine
+    // (consuming + spending the claim) before that account's balance-payers fan out. The fee
+    // session owns the claim state; consuming the claim flips `hasPendingClaim` for later layers.
+    const claimFirst: ExecutionUnit[] = [];
+    const rest: ExecutionUnit[] = [];
+    const seen = new Set<string>();
+    for (const unit of units) {
+      const key = unit.account.toString();
+      if (feeSession.hasPendingClaim(unit.account) && !seen.has(key)) {
+        seen.add(key);
+        claimFirst.push(unit);
+      } else {
+        rest.push(unit);
+      }
+    }
+    for (const unit of claimFirst) {
+      await this.runUnit(unit, feeSession);
+    }
+    // Fund units run sequentially relative to each other: their send closures submit L1 bridge
+    // txs, and two bridges signed by the same funder key would race on nonces.
+    const fundRest = rest.filter(unit => unit.kind === 'fund');
+    const parallelRest = rest.filter(unit => unit.kind !== 'fund');
+    await Promise.all([
+      Promise.all(parallelRest.map(unit => this.runUnit(unit, feeSession))),
+      (async () => {
+        for (const unit of fundRest) {
+          await this.runUnit(unit, feeSession);
+        }
+      })(),
+    ]);
+  }
+
+  private async runUnit(unit: ExecutionUnit, feeSession: FeeSession): Promise<void> {
+    const info = { label: unit.label, kind: unit.kind, account: unit.account };
+    this.reporter.onUnitStart?.(info);
+    const { fee, onConsumed } = feeSession.next(unit.account);
+    const startedAt = Date.now();
+    let result: unknown;
+    try {
+      result = await unit.send(fee);
+    } catch (error) {
+      this.reporter.onUnitError?.(info, error);
+      throw error;
+    }
+    const receipt = (result as { receipt?: TxReceipt } | undefined)?.receipt;
+    this.reporter.onUnitSettled?.(info, {
+      txHash: receipt?.txHash,
+      blockNumber: receipt?.blockNumber != null ? Number(receipt.blockNumber) : undefined,
+      feePaid: receipt?.transactionFee,
+      status: receipt?.status != null ? String(receipt.status) : undefined,
+      durationMs: Date.now() - startedAt,
+    });
+    onConsumed();
+  }
+
+  private persist(): void {
+    saveState(this.stateDirectory, this.state);
+  }
+}