@aztec/aztec 0.0.1-commit.f2ce05ee → 0.0.1-commit.f5a9928

package/src/deploy/fees.ts

@@ -0,0 +1,322 @@
+/**
+ * Fee handling for the deploy framework. Each account pays per its own {@link FeePolicy} — which
+ * may override the spec-wide default:
+ *
+ * - `sponsored`  → a SponsoredFPC pays (the local-network default). All sponsored accounts share
+ *   one payment method.
+ * - `fee-juice`  → the account pays from its own Fee Juice; if below `threshold` with work to do,
+ *   bridge `fundAmount` from L1. The bridge claim is single-use: the first paying tx claims it
+ *   (`FeeJuicePaymentMethodWithClaim`) and the rest spend the balance. Pending claims are persisted
+ *   (see ./state.ts) so a crash between bridge and claim resumes.
+ */
+import type { AztecAddress } from '@aztec/aztec.js/addresses';
+import { FeeJuicePaymentMethodWithClaim, type FeePaymentMethod, SponsoredFeePaymentMethod } from '@aztec/aztec.js/fee';
+import { Fr } from '@aztec/aztec.js/fields';
+import type { AztecNode } from '@aztec/aztec.js/node';
+import { FeeJuiceContract } from '@aztec/aztec.js/protocol';
+import type { Wallet } from '@aztec/aztec.js/wallet';
+import type { GasFees } from '@aztec/stdlib/gas';
+
+import type { Hex } from 'viem';
+
+import { registerDeployedSponsoredFPCInWalletAndGetAddress } from '../local-network/sponsored_fpc.js';
+import { bridgeFeeJuice, waitForL1ToL2Message } from './bridging.js';
+import type { AccountFunding, DeployReporter } from './reporter.js';
+import type { DeployState } from './state.js';
+import type { FeePolicy } from './types.js';
+
+/** Anvil's first pre-funded dev key — used as the local-network L1 funder. Published, non-secret. */
+const ANVIL_DEV_KEY: Hex = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+const DEFAULT_LOCAL_L1_RPC_URL = 'http://localhost:8545';
+const DEFAULT_LOCAL_L1_CHAIN_ID = 31337;
+
+/** The `fee` field of a send-options object. */
+export interface SendFee {
+  paymentMethod?: FeePaymentMethod;
+  gasSettings?: { maxFeesPerGas: GasFees };
+}
+
+/**
+ * Sane fee defaults: local pays via SponsoredFPC; every other network pays from bridged Fee Juice.
+ * The threshold/fundAmount pair trades off L1 round-trips (too low → frequent re-bridges) against
+ * stranding Fee Juice, which is non-transferable, on the account (too high).
+ */
+export function defaultFeePolicy(local: boolean): FeePolicy {
+  if (local) {
+    return { kind: 'sponsored' };
+  }
+  return {
+    kind: 'fee-juice',
+    threshold: 100n * 10n ** 18n, // 100 FJ
+    fundAmount: 1000n * 10n ** 18n, // 1000 FJ (non-faucet fallback amount)
+  };
+}
+
+/** The public Fee Juice balance of `address` (any address — contract or account), read via `from`. */
+export async function publicFeeJuiceBalance(
+  wallet: Wallet,
+  address: AztecAddress,
+  from: AztecAddress,
+): Promise<bigint> {
+  const { result } = await FeeJuiceContract.at(wallet).methods.balance_of_public(address).simulate({ from });
+  return BigInt(result.toString());
+}
+
+/**
+ * Resolves an account's funding posture under `policy` — what the plan reports and what
+ * {@link prepareFeeSession} acts on. `idle` accounts (no pending work) are never funded; sponsored
+ * accounts never read a balance; fee-juice accounts are `funded` iff their balance clears the
+ * threshold, else `not-funded` (a bridge will top them up).
+ */
+export async function accountFunding(
+  policy: FeePolicy,
+  wallet: Wallet,
+  account: AztecAddress,
+  hasWork: boolean,
+): Promise<AccountFunding> {
+  if (!hasWork) {
+    return { kind: 'idle' };
+  }
+  if (policy.kind === 'sponsored') {
+    return { kind: 'sponsored' };
+  }
+  const balance = await publicFeeJuiceBalance(wallet, account, account);
+  return balance >= policy.threshold
+    ? { kind: 'funded', balance }
+    : { kind: 'not-funded', balance, fundAmount: policy.fundAmount };
+}
+
+/**
+ * Resolves the L1 connection + funder for a bridge from caller-supplied config, defaulting to anvil
+ * on local. The funder key falls back to anvil's dev key on local (its faucet `mint` is owner-gated,
+ * so an ephemeral key is rejected there); elsewhere an omitted key means an ephemeral key + the
+ * public faucet. Deliberately no env fallback — the framework never reads the environment.
+ */
+function resolveL1Config(
+  local: boolean,
+  cfg: { l1RpcUrl?: string; l1ChainId?: number; l1FunderKey?: Hex },
+): { l1RpcUrl: string; l1ChainId: number; l1PrivateKey?: Hex } {
+  const l1RpcUrl = cfg.l1RpcUrl ?? (local ? DEFAULT_LOCAL_L1_RPC_URL : undefined);
+  const l1ChainId = cfg.l1ChainId ?? (local ? DEFAULT_LOCAL_L1_CHAIN_ID : undefined);
+  if (l1RpcUrl === undefined || l1ChainId === undefined) {
+    throw new Error('Bridging on a non-local network requires `l1RpcUrl` and `l1ChainId` (no hardcoded defaults).');
+  }
+  return { l1RpcUrl, l1ChainId, l1PrivateKey: cfg.l1FunderKey ?? (local ? ANVIL_DEV_KEY : undefined) };
+}
+
+/** What {@link obtainFeeJuiceClaim} needs to produce a consumable claim for a recipient. */
+export interface ObtainFeeJuiceClaimOpts {
+  /** Whether the target is a local (anvil) network — drives warp-vs-poll + L1 defaults. */
+  local: boolean;
+  node: AztecNode;
+  /** The node's URL — reaches its debug API for local time-warping while the bridge settles. */
+  nodeUrl?: string;
+  recipient: AztecAddress;
+  /** Amount to bridge (wei). */
+  amount: bigint;
+  /** L1 connection + funder, defaulted per {@link resolveL1Config}. */
+  l1: { l1FunderKey?: Hex; l1RpcUrl?: string; l1ChainId?: number };
+  state: DeployState;
+  persist: () => void;
+  reporter: DeployReporter;
+}
+
+/**
+ * A single-use Fee Juice claim for `recipient` (used by `fund` steps): resumes the persisted claim
+ * when present, else bridges `amount` from L1 and waits for the L1→L2 message. The claim persists
+ * before the wait, so a crash mid-wait resumes it instead of stranding the bridged funds. The
+ * caller consumes it (e.g. via `FeeJuice.claim`) and calls `onConsumed` once that tx mines.
+ */
+export async function obtainFeeJuiceClaim(opts: ObtainFeeJuiceClaimOpts): Promise<{
+  claimAmount: bigint;
+  claimSecret: Fr;
+  messageLeafIndex: bigint;
+  /** Drops the persisted resume entry — call once the consuming tx mines. */
+  onConsumed: () => void;
+}> {
+  const { local, node, nodeUrl, recipient, state, persist, reporter } = opts;
+  // Prefixed so a recipient that is also an auto-funded sender doesn't collide with its account claim.
+  const key = `fund:${recipient.toString()}`;
+  let claim: { claimAmount: bigint; claimSecret: Fr; messageLeafIndex: bigint };
+  const stored = state.pendingClaims[key];
+  if (stored) {
+    reporter.onBridge?.({ recipient, amount: BigInt(stored.claimAmount), reused: true });
+    claim = {
+      claimAmount: BigInt(stored.claimAmount),
+      claimSecret: Fr.fromString(stored.claimSecret),
+      messageLeafIndex: BigInt(stored.messageLeafIndex),
+    };
+  } else {
+    reporter.onBridge?.({ recipient, amount: opts.amount, reused: false });
+    const { l1RpcUrl, l1ChainId, l1PrivateKey } = resolveL1Config(local, opts.l1);
+    const bridged = await bridgeFeeJuice({ node, recipient, l1RpcUrl, l1ChainId, amount: opts.amount, l1PrivateKey });
+    state.pendingClaims[key] = {
+      claimAmount: bridged.claimAmount.toString(),
+      claimSecret: bridged.claimSecret.toString(),
+      messageLeafIndex: bridged.messageLeafIndex.toString(),
+    };
+    persist();
+    await waitForL1ToL2Message({
+      node,
+      messageHash: Fr.fromHexString(bridged.messageHash),
+      mode: local ? 'warp' : 'poll',
+      ...(nodeUrl ? { warpOpts: { nodeUrl } } : {}),
+    });
+    claim = {
+      claimAmount: bridged.claimAmount,
+      claimSecret: bridged.claimSecret,
+      messageLeafIndex: bridged.messageLeafIndex,
+    };
+  }
+  return {
+    ...claim,
+    onConsumed: () => {
+      delete state.pendingClaims[key];
+      persist();
+    },
+  };
+}
+
+/** Per-account fee dispensing for one run, prepared by {@link prepareFeeSession}. */
+export interface FeeSession {
+  /**
+   * Fee options for the next tx from `account`, plus `onConsumed` to call after it lands (clears a
+   * one-time bridge claim from persisted state). Subsequent calls pay from balance.
+   */
+  next(account: AztecAddress): { fee: SendFee; onConsumed: () => void };
+  /**
+   * Whether `account`'s next tx will carry its one-time bridge claim. The runner serializes such an
+   * account's first tx: the claim must mine before its balance-paying txs fan out.
+   */
+  hasPendingClaim(account: AztecAddress): boolean;
+}
+
+/** What {@link prepareFeeSession} needs to fund a run's working accounts. */
+export interface PrepareFeeSessionOpts {
+  /** Whether the target is a local (anvil) network — drives warp-vs-poll + L1 defaults. */
+  local: boolean;
+  node: AztecNode;
+  /** The node's URL — reaches its debug API for local time-warping while a bridge settles. */
+  nodeUrl?: string;
+  wallet: Wallet;
+  /**
+   * Working accounts (those with pending work) with their resolved {@link FeePolicy} + funding (from
+   * {@link accountFunding}) — so this function doesn't re-read balances.
+   */
+  accounts: { address: AztecAddress; policy: FeePolicy; funding: AccountFunding }[];
+  state: DeployState;
+  persist: () => void;
+  reporter: DeployReporter;
+}
+
+/**
+ * Resolves fees ahead of execution, per account: registers the shared SponsoredFPC (for sponsored
+ * accounts), or tops up a fee-juice account via a bridge (reusing a persisted pending claim when
+ * present). Returns a {@link FeeSession} that dispenses the right fee per tx, by sending account.
+ */
+export async function prepareFeeSession(opts: PrepareFeeSessionOpts): Promise<FeeSession> {
+  const { local, node, nodeUrl, wallet, accounts, state, persist, reporter } = opts;
+
+  // Shared sponsored payment method: register the SponsoredFPC + read gas once, if anyone uses it.
+  let sponsoredFee: SendFee | undefined;
+  if (accounts.some(a => a.policy.kind === 'sponsored')) {
+    const sponsoredFPCAddress = await registerDeployedSponsoredFPCInWalletAndGetAddress(wallet);
+    sponsoredFee = {
+      paymentMethod: new SponsoredFeePaymentMethod(sponsoredFPCAddress),
+      // 10x headroom because this one quote is reused for every tx in the run (the wallet's default would re-quote
+      // per tx at 1.5x min): congestion pricing can push the min fee well past the starting quote over a run of
+      // parallel layers. Overstating the cap is free — txs pay the going rate, not the cap, and the FPC pays anyway.
+      gasSettings: { maxFeesPerGas: (await node.getCurrentMinFees()).mul(10) },
+    };
+  }
+
+  // Bridge fee-juice top-ups. The L1 sends stay sequential — a shared funder key would collide on
+  // nonces — but the L1→L2 availability waits (the minutes-long part on a real network) run
+  // concurrently afterwards. Warp-mode waits run inline instead: warping manipulates global time,
+  // so concurrent warps would fight. Each claim persists as soon as it exists on L1, so a crash
+  // mid-wait resumes it instead of stranding the bridged funds; a resumed claim skips the wait (by
+  // resume time the message is available on any live network).
+  const claims = new Map<string, FeeJuicePaymentMethodWithClaim>();
+  const messageWaits: Promise<void>[] = [];
+  for (const { address, policy, funding } of accounts) {
+    if (policy.kind !== 'fee-juice' || funding.kind === 'funded') {
+      continue;
+    }
+    const key = address.toString();
+    let stored = state.pendingClaims[key];
+    if (stored) {
+      reporter.onBridge?.({ recipient: address, amount: BigInt(stored.claimAmount), reused: true });
+    } else {
+      reporter.onBridge?.({ recipient: address, amount: policy.fundAmount, reused: false });
+      // Local defaults to anvil; a non-local network must supply L1 connection details.
+      const { l1ChainId, l1RpcUrl, l1PrivateKey } = resolveL1Config(local, policy);
+      const bridged = await bridgeFeeJuice({
+        node,
+        recipient: address,
+        l1RpcUrl,
+        l1ChainId,
+        amount: policy.fundAmount,
+        l1PrivateKey,
+      });
+      stored = {
+        claimAmount: bridged.claimAmount.toString(),
+        claimSecret: bridged.claimSecret.toString(),
+        messageLeafIndex: bridged.messageLeafIndex.toString(),
+      };
+      state.pendingClaims[key] = stored;
+      persist();
+      const wait = waitForL1ToL2Message({
+        node,
+        messageHash: Fr.fromHexString(bridged.messageHash),
+        mode: local ? 'warp' : 'poll',
+        ...(nodeUrl ? { warpOpts: { nodeUrl } } : {}),
+      });
+      if (local) {
+        await wait;
+      } else {
+        messageWaits.push(wait);
+      }
+    }
+    claims.set(
+      key,
+      new FeeJuicePaymentMethodWithClaim(address, {
+        claimAmount: BigInt(stored.claimAmount),
+        claimSecret: Fr.fromString(stored.claimSecret),
+        messageLeafIndex: BigInt(stored.messageLeafIndex),
+      }),
+    );
+  }
+  await Promise.all(messageWaits);
+
+  // Per-account dispenser state. A claim is single-use: the first `next()` for its account carries
+  // it, and `onConsumed` (invoked by the runner once that tx mines) drops the persisted resume entry.
+  const sessions = new Map<string, { sponsored: boolean; claim?: FeeJuicePaymentMethodWithClaim }>();
+  for (const { address, policy } of accounts) {
+    const key = address.toString();
+    sessions.set(key, { sponsored: policy.kind === 'sponsored', claim: claims.get(key) });
+  }
+
+  return {
+    next: account => {
+      const key = account.toString();
+      const session = sessions.get(key);
+      if (session?.sponsored) {
+        return { fee: sponsoredFee ?? {}, onConsumed: () => {} };
+      }
+      if (session?.claim) {
+        const claim = session.claim;
+        session.claim = undefined; // single-use: only this first tx carries it
+        return {
+          fee: { paymentMethod: claim },
+          onConsumed: () => {
+            // claim is now spent on-chain; drop its resume entry
+            delete state.pendingClaims[key];
+            persist();
+          },
+        };
+      }
+      return { fee: {}, onConsumed: () => {} }; // later txs (or already-funded): pay from the account's balance
+    },
+    hasPendingClaim: account => sessions.get(account.toString())?.claim !== undefined,
+  };
+}

package/src/deploy/graph.ts

@@ -0,0 +1,137 @@
+/**
+ * Dependency-graph utilities for the deploy framework: topological layering (which steps
+ * can run together) and a pretty-printer for the resulting plan.
+ */
+
+/**
+ * Group `nodes` into dependency layers (Kahn's algorithm). Each layer contains nodes whose
+ * dependencies all sit in earlier layers, so a layer's nodes are mutually independent and
+ * may run in parallel. Dependencies pointing outside `nodes` (e.g. already-satisfied work)
+ * are treated as satisfied. Throws on a cycle.
+ */
+export function topologicalLayers(nodes: string[], dependencies: Map<string, string[]>): string[][] {
+  const remaining = new Set(nodes);
+  const layers: string[][] = [];
+  while (remaining.size > 0) {
+    // A node is ready when every dependency already sits in an earlier layer (i.e. is no longer in `remaining`).
+    const layer = [...remaining].filter(node =>
+      (dependencies.get(node) ?? []).every(dependency => !remaining.has(dependency)),
+    );
+    if (layer.length === 0) {
+      throw new Error(`Dependency cycle among: ${[...remaining].join(', ')}`);
+    }
+    for (const node of layer) {
+      remaining.delete(node);
+    }
+    layers.push(layer);
+  }
+  return layers;
+}
+
+/**
+ * Like {@link topologicalLayers}, but nodes for which `floatLate(node)` is true are scheduled as
+ * LATE as their dependents allow (ALAP) instead of as early as possible. Used to push batchable
+ * actions into the latest layer they can share, so same-account actions in adjacent layers coalesce
+ * into one tx. Fixed nodes (e.g. contract publishes, which unblock dependents and don't batch) keep
+ * their earliest layer; the relative order — and so the critical-path length — is unchanged. Throws
+ * on a cycle (via {@link topologicalLayers}).
+ */
+export function scheduleLayers(
+  nodes: string[],
+  dependencies: Map<string, string[]>,
+  floatLate: (node: string) => boolean,
+): string[][] {
+  const asap = topologicalLayers(nodes, dependencies);
+  if (asap.length === 0) {
+    return [];
+  }
+  const lastLayer = asap.length - 1;
+
+  const nodeSet = new Set(nodes);
+  const layerOf = new Map<string, number>();
+  for (const [index, layer] of asap.entries()) {
+    for (const node of layer) {
+      layerOf.set(node, index);
+    }
+  }
+
+  // Reverse adjacency: which in-set nodes depend on each node.
+  const dependents = new Map<string, string[]>();
+  for (const node of nodes) {
+    for (const dependency of dependencies.get(node) ?? []) {
+      if (!nodeSet.has(dependency)) {
+        continue;
+      }
+      const list = dependents.get(dependency);
+      if (list) {
+        list.push(node);
+      } else {
+        dependents.set(dependency, [node]);
+      }
+    }
+  }
+
+  // Push floating nodes as late as possible, visiting in reverse topological order (the flattened
+  // ASAP order reversed) so every node is placed after all of its dependents are placed.
+  for (const node of asap.flat().reverse()) {
+    if (!floatLate(node)) {
+      continue;
+    }
+    const deps = dependents.get(node) ?? [];
+    const latest = deps.length === 0 ? lastLayer : Math.min(...deps.map(d => layerOf.get(d)!)) - 1;
+    layerOf.set(node, Math.max(layerOf.get(node)!, latest));
+  }
+
+  const layers: string[][] = Array.from({ length: asap.length }, () => []);
+  for (const node of nodes) {
+    layers[layerOf.get(node)!].push(node);
+  }
+  return layers.filter(layer => layer.length > 0);
+}
+
+/** One node in the printed plan. */
+export interface PlanRow {
+  /** e.g. "goCoin" */
+  name: string;
+  /** short tag, e.g. "Token · publishes class" */
+  tag?: string;
+  /** dependency names to show as `← a, b` */
+  dependencies?: string[];
+}
+
+/**
+ * Render a titled flat list of plan rows (no layer grouping). Use for the declared-contracts
+ * overview, whose `← ...` arrows are constructor-arg references — not an execution order.
+ */
+export function formatList(title: string, rows: PlanRow[]): string {
+  if (rows.length === 0) {
+    return `${title}: (none)`;
+  }
+  const lines = [`${title}:`];
+  for (const row of rows) {
+    const dependencies = row.dependencies && row.dependencies.length ? `  ← ${row.dependencies.join(', ')}` : '';
+    const tag = row.tag ? `  [${row.tag}]` : '';
+    lines.push(`  ${row.name}${tag}${dependencies}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Render a titled, layer-grouped section of the plan as an indented tree. Each layer's txs are
+ * submitted in parallel.
+ */
+export function formatLayers(title: string, layers: PlanRow[][]): string {
+  if (layers.length === 0) {
+    return `${title}: (none)`;
+  }
+  const lines = [`${title}:`];
+  for (const [index, layer] of layers.entries()) {
+    lines.push(`  layer ${index + 1}${layer.length > 1 ? '  (parallel)' : ''}`);
+    for (const row of layer) {
+      const dependencies = row.dependencies && row.dependencies.length ? `  ← ${row.dependencies.join(', ')}` : '';
+      const tag = row.tag ? `  [${row.tag}]` : '';
+      lines.push(`    ${row.name}${tag}${dependencies}`);
+    }
+  }
+  return lines.join('\n');
+}

package/src/deploy/index.ts

@@ -0,0 +1,41 @@
+/**
+ * A minimal, declarative deployment framework for Aztec.
+ *
+ * Describe the accounts you send from and a graph of steps — contracts that must end up on-chain
+ * (deterministic addresses, interdependencies via `initializerArgs`) and the txs to send — plus how
+ * fees are paid; then {@link runDeployment} resolves, takes an on-chain inventory, funds, and
+ * executes only what's missing in dependency order — idempotently and resumably. The framework
+ * never reads the environment; callers pipe in secrets and config.
+ *
+ * Node-only: pulls in the PXE-backed `EmbeddedWallet`, `@aztec/noir-contracts.js`, and (for the
+ * `fee-juice` policy) L1 bridging — none browser-safe. Lives under the `@aztec/aztec/deploy` subpath
+ * so it stays out of any browser bundle.
+ */
+export { runDeployment } from './runner.js';
+export { defaultFeePolicy } from './fees.js';
+export { consoleReporter } from './reporter.js';
+export type {
+  DeployReporter,
+  DeployPlan,
+  DeployPlanAccount,
+  DeployPlanStep,
+  AccountFunding,
+  DeploySummary,
+  DeployUnitInfo,
+  DeployUnitResult,
+  DeployUnitKind,
+  BridgeEvent,
+} from './reporter.js';
+export type {
+  DeploymentSpec,
+  AccountSpec,
+  ContractStep,
+  ActionStep,
+  FundStep,
+  StepSpec,
+  Steps,
+  GeneratedContractClass,
+  FeePolicy,
+  Resolver,
+  Ctx,
+} from './types.js';

package/src/deploy/reporter.ts

@@ -0,0 +1,184 @@
+/**
+ * Observability for the deploy framework. {@link runDeployment} emits structured lifecycle events
+ * to a {@link DeployReporter} instead of writing to the console directly, so callers control where
+ * the signal goes: the default ({@link consoleReporter}) renders human-readably to **stderr** —
+ * keeping stdout clear for the deploy scripts' `export KEY=VAL` lines, which an orchestrator evals —
+ * while e2e, a progress UI, or structured CI logging can inject their own reporter and consume the
+ * events as data. Every hook is optional; an empty `{}` is a valid (silent) reporter.
+ */
+import type { AztecAddress } from '@aztec/aztec.js/addresses';
+import type { TxHash } from '@aztec/stdlib/tx';
+
+import { formatLayers, formatList } from './graph.js';
+
+/** What a unit did: publish a contract, send an action's tx, or fund an address with Fee Juice. */
+export type DeployUnitKind = 'publish' | 'action' | 'fund';
+
+/** Identity of one execution unit (a single tx), as reported by the unit lifecycle hooks. */
+export interface DeployUnitInfo {
+  /** Human label, e.g. `publish goCoin`, `action mintGoCoin`. */
+  label: string;
+  kind: DeployUnitKind;
+  /** The account that sends and pays for this tx. */
+  account: AztecAddress;
+}
+
+/** What a unit produced once its tx settled. Fields beyond `durationMs` come from the receipt. */
+export interface DeployUnitResult {
+  txHash?: TxHash;
+  blockNumber?: number;
+  feePaid?: bigint;
+  status?: string;
+  durationMs: number;
+}
+
+/** An account's funding posture for this run, as resolved at planning time. */
+export type AccountFunding =
+  | { kind: 'idle' } // no pending work this run, so funding is moot
+  | { kind: 'sponsored' } // a SponsoredFPC pays
+  | { kind: 'funded'; balance: bigint } // pays from its own Fee Juice
+  | { kind: 'not-funded'; balance: bigint; fundAmount: bigint }; // will bridge before paying
+
+export interface DeployPlanAccount {
+  alias: string;
+  address: AztecAddress;
+  funding: AccountFunding;
+}
+
+export interface DeployPlanStep {
+  id: string;
+  kind: 'contract' | 'action' | 'fund';
+  /**
+   * Status at the start of the run: a contract is `published` / `to publish` (public) or
+   * `registered` (private); an action is `done` / `to run`; a fund step is `funded` / `to fund`.
+   */
+  status: 'published' | 'to publish' | 'registered' | 'done' | 'to run' | 'funded' | 'to fund';
+  /** Steps it depends on (constructor-arg refs and explicit `dependsOn`). */
+  dependsOn: string[];
+}
+
+export interface DeployPlan {
+  /** Human label for the target (e.g. `local`, or a caller-chosen name). */
+  label: string;
+  accounts: DeployPlanAccount[];
+  steps: DeployPlanStep[];
+  /** Execution layers (step ids) — what will actually run, in dependency order. A layer runs parallel. */
+  layers: string[][];
+}
+
+export interface DeploySummary {
+  label: string;
+  contracts: { alias: string; address: AztecAddress; status: 'published' | 'registered' }[];
+  accounts: { alias: string; address: AztecAddress }[];
+}
+
+export interface BridgeEvent {
+  recipient: AztecAddress;
+  amount: bigint;
+  /** True when resuming a persisted claim instead of bridging anew. */
+  reused: boolean;
+}
+
+/** Lifecycle hooks the framework emits during a run. All optional — implement only what you need. */
+export interface DeployReporter {
+  /** The resolved plan, before execution. */
+  onPlan?(plan: DeployPlan): void;
+  /** Everything is already on-chain; nothing will be sent. */
+  onNothingToDo?(label: string): void;
+  /** An account's Fee Juice is being topped up (or a persisted claim is being resumed). */
+  onBridge?(event: BridgeEvent): void;
+  /** A unit's tx is about to be sent. */
+  onUnitStart?(unit: DeployUnitInfo): void;
+  /** A unit's tx settled successfully. */
+  onUnitSettled?(unit: DeployUnitInfo, result: DeployUnitResult): void;
+  /** A unit's tx threw; the run will abort after this. */
+  onUnitError?(unit: DeployUnitInfo, error: unknown): void;
+  /** The run finished; `summary` holds the final resolved state. */
+  onComplete?(summary: DeploySummary): void;
+}
+
+const MS_PER_SECOND = 1000;
+const WEI_PER_FEE_JUICE = 10n ** 18n;
+const seconds = (ms: number): string => `${(ms / MS_PER_SECOND).toFixed(1)}s`;
+const feeJuice = (wei: bigint): string => `${wei / WEI_PER_FEE_JUICE} FJ`;
+
+function describeFunding(f: AccountFunding): string {
+  switch (f.kind) {
+    case 'idle':
+      return 'idle (no work)';
+    case 'sponsored':
+      return 'sponsored';
+    case 'funded':
+      return `funded (${feeJuice(f.balance)})`;
+    case 'not-funded':
+      return `not funded (${feeJuice(f.balance)}) → will bridge ${feeJuice(f.fundAmount)}`;
+  }
+}
+
+/**
+ * The default reporter: renders events human-readably to **stderr**. Stderr (not stdout) so the
+ * traces survive an orchestrator that captures stdout for the scripts' `export` lines.
+ */
+export function consoleReporter(): DeployReporter {
+  const log = (line: string): void => void process.stderr.write(`${line}\n`);
+  return {
+    onPlan(plan) {
+      log(`\n── Plan (${plan.label}) ──`);
+      log(
+        formatList(
+          'accounts',
+          plan.accounts.map(a => ({ name: a.alias, tag: describeFunding(a.funding) })),
+        ),
+      );
+      log(
+        formatList(
+          'steps',
+          plan.steps.map(s => ({
+            name: s.id,
+            tag: `${s.kind} · ${s.status}`,
+            dependencies: s.dependsOn,
+          })),
+        ),
+      );
+      log(
+        formatLayers(
+          'execution layers',
+          plan.layers.map(layer => layer.map(name => ({ name }))),
+        ),
+      );
+    },
+    onNothingToDo(label) {
+      log(`\nNothing to do on ${label} — everything is already on-chain.`);
+    },
+    onBridge({ recipient, amount, reused }) {
+      log(
+        reused
+          ? `Reusing a pending bridge claim for ${recipient} (resuming a top-up).`
+          : `Bridging ${amount} Fee Juice to ${recipient} (this can take a few minutes)...`,
+      );
+    },
+    onUnitStart(unit) {
+      log(`→ ${unit.label}...`);
+    },
+    onUnitSettled(unit, result) {
+      const bits = [
+        result.txHash ? `tx ${result.txHash.toString().slice(0, 10)}…` : undefined,
+        result.blockNumber != null ? `block ${result.blockNumber}` : undefined,
+        seconds(result.durationMs),
+      ].filter(Boolean);
+      log(`✓ ${unit.label}  ${bits.join('  ')}`);
+    },
+    onUnitError(unit, error) {
+      log(`✗ ${unit.label}  failed: ${error instanceof Error ? error.message : String(error)}`);
+    },
+    onComplete(summary) {
+      log(`\n── Deployed to ${summary.label} ──`);
+      for (const c of summary.contracts) {
+        log(`  ${c.alias.padEnd(16)} ${c.address}  (${c.status})`);
+      }
+      for (const a of summary.accounts) {
+        log(`  account ${a.alias}: ${a.address}`);
+      }
+    },
+  };
+}