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

package/src/deploy/state.ts

@@ -0,0 +1,66 @@
+/**
+ * Resume state for {@link runDeployment}, persisted to `<stateDir>/state.json`.
+ *
+ * On-chain inventory makes contract deploys and actions idempotent on their own, but a
+ * bridge claim lives off-chain between "bridged on L1" and "claimed on L2". We persist
+ * pending claims here so a run that dies in that window resumes the claim instead of
+ * bridging again. Resolved addresses are stored too, as a human-readable record.
+ *
+ * The state file is keyed only by `stateDir`; point separate targets (local vs. a remote
+ * network) at separate `stateDir`s to keep their state apart.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+
+const deployStateSchema = z.object({
+  addresses: z.record(z.string(), z.string()).default({}),
+  pendingClaims: z
+    .record(z.string(), z.object({ claimAmount: z.string(), claimSecret: z.string(), messageLeafIndex: z.string() }))
+    .default({}),
+});
+
+export interface DeployState {
+  /** alias → resolved address (informational). */
+  addresses: Record<string, string>;
+  /** deployer address → a bridge claim that's been funded on L1 but not yet consumed. */
+  pendingClaims: Record<string, { claimAmount: string; claimSecret: string; messageLeafIndex: string }>;
+}
+
+function statePath(dir: string): string {
+  return join(dir, 'state.json');
+}
+
+/**
+ * Loads the persisted state, or an empty one when no file exists yet. A file that exists but can't
+ * be read or doesn't match the schema throws instead of being treated as empty: silently starting
+ * fresh would discard `pendingClaims`, and a lost claim secret strands the bridged funds forever.
+ */
+export function loadState(dir: string): DeployState {
+  let raw: string;
+  try {
+    raw = readFileSync(statePath(dir), 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return { addresses: {}, pendingClaims: {} };
+    }
+    throw new Error(`Failed to read deploy state at ${statePath(dir)}.`, { cause: error });
+  }
+  try {
+    return deployStateSchema.parse(JSON.parse(raw));
+  } catch (error) {
+    throw new Error(
+      `Corrupt deploy state at ${statePath(dir)}. Fix or remove it manually — removing abandons any pending ` +
+        `bridge claims recorded in it (their funds become unclaimable).`,
+      { cause: error },
+    );
+  }
+}
+
+/** Persists atomically (write + rename), so a crash mid-write can't truncate the previous state. */
+export function saveState(dir: string, state: DeployState): void {
+  mkdirSync(dir, { recursive: true });
+  const path = statePath(dir);
+  writeFileSync(`${path}.tmp`, JSON.stringify(state, null, 2));
+  renameSync(`${path}.tmp`, path);
+}

package/src/deploy/types.ts

@@ -0,0 +1,244 @@
+/**
+ * Declarative deployment spec — the "what", not the "how".
+ *
+ * A {@link DeploymentSpec} is one graph of {@link StepSpec | steps} — each either a `contract`
+ * (published on-chain, or registered privately in the PXE) or an `action` (a tx) — sent from named
+ * {@link AccountSpec | accounts}. {@link runDeployment} resolves deterministic addresses upfront,
+ * inventories what's on-chain, funds the accounts, and executes only what's missing in dependency
+ * order — idempotently and resumably.
+ */
+import type { ContractArtifact } from '@aztec/aztec.js/abi';
+import type { AztecAddress } from '@aztec/aztec.js/addresses';
+import type { ContractBase, ContractFunctionInteraction } from '@aztec/aztec.js/contracts';
+import type { Fr } from '@aztec/aztec.js/fields';
+import type { AztecNode } from '@aztec/aztec.js/node';
+import type { Wallet } from '@aztec/aztec.js/wallet';
+
+import type { DeployReporter } from './reporter.js';
+
+/**
+ * How txs are paid.
+ * - `sponsored`: a SponsoredFPC pays (the local-network default).
+ * - `fee-juice`: the account pays from its own Fee Juice; if below `threshold` with work to do,
+ *   bridge `fundAmount` from L1 and claim it on the first paying tx. `l1FunderKey`/`l1RpcUrl`/
+ *   `l1ChainId` are caller-supplied; omit `l1FunderKey` for the faucet + ephemeral key. On a
+ *   non-local network `l1RpcUrl` and `l1ChainId` are required (there are no hardcoded defaults);
+ *   on local they default to anvil (`127.0.0.1:8545`, chain `31337`).
+ */
+export type FeePolicy =
+  | { kind: 'sponsored' }
+  | {
+      kind: 'fee-juice';
+      threshold: bigint;
+      fundAmount: bigint;
+      l1FunderKey?: `0x${string}`;
+      l1RpcUrl?: string;
+      l1ChainId?: number;
+    };
+
+/** An account the deployment sends from: a v0 initializerless Schnorr account (no deploy tx). */
+export interface AccountSpec {
+  /**
+   * The account's privacy master secret — the seed its nullifier, viewing and tagging keys derive
+   * from. The signing key is derived from it too, separately (domain-separated as the master
+   * message-signing key), so this one value pins the account
+   */
+  secret: Fr;
+  /** Fee policy for this account's txs, overriding {@link DeploymentSpec.fees}. */
+  fees?: FeePolicy;
+  /** Salt for this account's derivation, overriding {@link DeploymentSpec.salt}. */
+  salt?: Fr;
+}
+
+/** Resolve addresses of accounts / contracts (for initializer args, action targets, the deployer). */
+export interface Resolver {
+  /** The resolved address of the account declared under `alias`. Throws on an unknown alias. */
+  account(alias: string): AztecAddress;
+  /** The resolved address of the contract step declared under `alias`. Throws on an unknown alias. */
+  contract(alias: string): AztecAddress;
+}
+
+/**
+ * The static side of a codegen'd contract class (e.g. `TokenContract`): the single source of both
+ * the artifact and a typed `.at`. Carries the instance type `T`, surfaced by {@link Ctx.instance}.
+ */
+export interface GeneratedContractClass<T extends ContractBase = ContractBase> {
+  artifact: ContractArtifact;
+  at(address: AztecAddress, wallet: Wallet): T;
+}
+
+/** What a contract step declares however its initializer args are produced. */
+interface ContractStepBase<T extends ContractBase = ContractBase> {
+  kind: 'contract';
+  /** The generated contract class — provides the artifact and the typed `.at`. */
+  contract: GeneratedContractClass<T>;
+  /** Account that salts + sends the deploy, e.g. `(r) => r.account("admin")`. */
+  deployer: (resolve: Resolver) => AztecAddress;
+  /** Per-contract salt, overriding {@link DeploymentSpec.salt}. */
+  salt?: Fr;
+  /**
+   * For contracts that own private notes (e.g. an FPC): the contract's privacy master secret. The
+   * framework derives its `PublicKeys` from it. Omit for ordinary contracts (default keys).
+   */
+  secret?: Fr;
+  /** Name of a non-default `#[initializer]` to call. Defaults to the contract's constructor. */
+  initializer?: string;
+}
+
+/**
+ * A step that puts a contract on-chain (or in the PXE):
+ * - `publish`  → register the class + deploy the instance + run its initializer (a tx).
+ * - `register` → private; only derive the deterministic address and register it in the PXE (no tx).
+ *
+ * The address is deterministic in (class id, deployer, salt, initializer + its args). The two ways
+ * to supply those args are the union's two variants, so a step can only pick one.
+ */
+export type ContractStep<C = Steps, T extends ContractBase = ContractBase> =
+  | (ContractStepBase<T> & {
+      mode: 'publish' | 'register';
+      /**
+       * Deterministic initializer args — a pure function of resolved addresses + static config. Its
+       * contract→contract dependencies are auto-derived and the address is resolved UPFRONT.
+       */
+      initializerArgs?: (resolve: Resolver) => unknown[];
+      deferredInitializerArgs?: never;
+      /** Steps that must complete first, on top of those auto-derived from {@link initializerArgs}. */
+      dependsOn?: string[];
+    })
+  | (ContractStepBase<T> & {
+      /** Deferred args resolve once the run is underway, so there has to be a tx to defer. */
+      mode: 'publish';
+      /**
+       * Runtime initializer args — may read live state (e.g. `ctx.instance(x).methods.f().simulate()`).
+       * Resolved at inventory time when the state it reads already exists (the re-run case, which is
+       * what makes re-runs no-ops), and otherwise AT EXECUTION TIME, once {@link dependsOn} has run.
+       */
+      deferredInitializerArgs: (ctx: Ctx<C>) => unknown[] | Promise<unknown[]>;
+      initializerArgs?: never;
+      /**
+       * The steps whose effects the args read.
+       * The initializer args resolve only once these are in place
+       */
+      dependsOn: string[];
+    });
+
+/** A step that sends a tx once its dependencies exist. */
+export interface ActionStep<C = Steps> {
+  kind: 'action';
+  /** Account that sends (and pays for) this tx, e.g. `(r) => r.account("admin")`. */
+  from: (resolve: Resolver) => AztecAddress;
+  /**
+   * Builds the interaction to send. May be async (e.g. to read state first). The EmbeddedWallet
+   * creates required authwits at send time, so the interaction usually needs no `.with(...)`.
+   */
+  call: (ctx: Ctx<C>) => ContractFunctionInteraction | Promise<ContractFunctionInteraction>;
+  /**
+   * Idempotency gate: if it resolves true, the action is skipped this run. Not consulted until the
+   * contracts in {@link dependsOn} are in place. Anything it throws aborts the run.
+   */
+  done: (ctx: Ctx<C>) => Promise<boolean>;
+  /**
+   * Steps that must complete first: every contract this action calls or its {@link done} gate
+   * reads, plus the actions it follows.
+   */
+  dependsOn?: string[];
+}
+
+/**
+ * A step that provisions an address — any address, not just a sending account — with bridged Fee
+ * Juice: bridge `amount` from L1, then send a `FeeJuice.claim` tx from {@link from} crediting
+ * {@link recipient}. Used to fund contracts that pay for others (e.g. an FPC). Idempotent on the
+ * recipient's public balance, and resumable: the bridge claim persists (see ./state.ts) as soon as
+ * it exists on L1, so a crash between bridge and claim resumes instead of stranding the funds.
+ */
+export interface FundStep {
+  kind: 'fund';
+  /** Recipient of the bridged Fee Juice, e.g. `(r) => r.contract("fpc")`. */
+  recipient: (resolve: Resolver) => AztecAddress;
+  /** Bridge + claim only when the recipient's public Fee Juice balance is below this (wei). */
+  threshold: bigint;
+  /**
+   * Amount to bridge (wei). On a network with a fee-asset faucet whose mint amount exceeds the L1
+   * funder's balance, the faucet's own mint amount is what arrives.
+   */
+  amount: bigint;
+  /** Account that sends (and pays for) the L2 claim tx, e.g. `(r) => r.account("admin")`. */
+  from: (resolve: Resolver) => AztecAddress;
+  /** L1 funder key signing the bridge tx; omit for the faucet + an ephemeral key (or anvil's dev key on local). */
+  l1FunderKey?: `0x${string}`;
+  /** L1 connection for the bridge; required on non-local networks, defaults to anvil on local. */
+  l1RpcUrl?: string;
+  l1ChainId?: number;
+  /** Steps that must complete first (e.g. the contract being funded). */
+  dependsOn?: string[];
+}
+
+export type StepSpec<C = Steps> = ContractStep<C> | ActionStep<C> | FundStep;
+/**
+ * A steps map: alias → step. The element generic is `any` so the alias isn't self-referential
+ * (`Steps → StepSpec<Steps> → …`); a concrete spec's `C` is inferred at the {@link runDeployment}
+ * call site, which is what types `ctx.instance`.
+ */
+
+export type Steps = Record<string, StepSpec<any>>;
+
+/** The concrete contract type a contract step produces (else the base type). */
+export type InstanceOf<S> = S extends { contract: GeneratedContractClass<infer T> } ? T : ContractBase;
+/** The aliases of the contract steps in C — so `ctx.instance` only accepts those. */
+export type ContractAlias<C> = {
+  [K in keyof C]: C[K] extends { kind: 'contract' } ? K : never;
+}[keyof C] &
+  string;
+
+/** Everything a step needs at build/idempotency time: typed resolution + bound instances + handles. */
+export interface Ctx<C = Steps> extends Resolver {
+  /** The contract bound to the wallet, typed from the step's class. */
+  instance<K extends ContractAlias<C>>(alias: K): InstanceOf<C[K]>;
+  /**
+   * Whether step `id` is already satisfied this run — it will NOT do work. Mode-aware: an action
+   * whose `done` gate passed, a published contract that's on-chain, or a registered (private)
+   * contract that's in the wallet. Can be true without {@link ran} (e.g. a published contract a
+   * prior run left on-chain). Lets a step defer to another's gate: `done: (ctx) => ctx.done("amm")`.
+   */
+  done(id: string): Promise<boolean>;
+  /**
+   * Whether step `id` did work *this run*: an action that sent its tx, a contract published this
+   * run (absent before), or a contract (re)registered this run. Use for "do B because A happened
+   * this run", e.g. a mint gated on a fresh token: `done: (ctx) => !ctx.ran("goCoin")`.
+   */
+  ran(id: string): Promise<boolean>;
+  wallet: Wallet;
+  node: AztecNode;
+}
+
+/** The full declarative input to {@link runDeployment}: target, accounts, steps, fees, and hooks. */
+export interface DeploymentSpec<C extends Steps = Steps> {
+  /**
+   * The node to deploy against: a JSON-RPC URL, or an already-connected node (e.g. an in-process
+   * `AztecNodeService` from a test fixture). Local time-warping while a bridge settles reaches the
+   * debug API through whichever is given — a URL builds a debug client, an in-process node serves
+   * it directly.
+   */
+  node: string | AztecNode;
+  /**
+   * Whether the target is a local (anvil) network. Local uses the deterministic sandbox defaults:
+   * sponsored fees, no real proofs, warp-based L1→L2 message advancement, and anvil's dev funder.
+   * Everything else (default) uses fee-juice, real proofs, and polling; L1 details for bridging must
+   * be supplied on the fee-juice {@link FeePolicy}.
+   */
+  local?: boolean;
+  /** Human label for logs + reporter; defaults to `local`/`network` based on {@link local}. */
+  label?: string;
+  /** Default salt for account + contract derivation; each can override. Defaults to Fr(0). */
+  salt?: Fr;
+  /** Directory for the resume-state file. Defaults to `<cwd>/.deploy-state`. */
+  stateDir?: string;
+  accounts: Record<string, AccountSpec>;
+  steps: C;
+  /** Default fee policy; per-account {@link AccountSpec.fees} overrides it. Defaults per {@link local}. */
+  fees?: FeePolicy;
+  /** Where lifecycle events go. Defaults to {@link consoleReporter} (stderr). `{}` silences them. */
+  reporter?: DeployReporter;
+  /** Hook to write app artifacts (e.g. a frontend manifest) from resolved state; runs after execution. */
+  output?: (ctx: Ctx<C>) => void | Promise<void>;
+}

package/src/examples/token.ts

@@ -21,10 +21,18 @@ async function main() {
 
   const wallet = await EmbeddedWallet.create(node);
 
-  // During local network setup we deploy a few accounts. Below we add them to our wallet.
+  // During local network setup we create a few initializerless accounts. Below we add them to our wallet.
   const [aliceInitialAccountData, bobInitialAccountData] = await getInitialTestAccountsData();
-  await wallet.createSchnorrAccount(aliceInitialAccountData.secret, aliceInitialAccountData.salt);
-  await wallet.createSchnorrAccount(bobInitialAccountData.secret, bobInitialAccountData.salt);
+  await wallet.createSchnorrInitializerlessAccount(
+    aliceInitialAccountData.secret,
+    aliceInitialAccountData.salt,
+    aliceInitialAccountData.signingKey,
+  );
+  await wallet.createSchnorrInitializerlessAccount(
+    bobInitialAccountData.secret,
+    bobInitialAccountData.salt,
+    bobInitialAccountData.signingKey,
+  );
 
   const alice = aliceInitialAccountData.address;
   const bob = bobInitialAccountData.address;

package/src/local-network/auth_registry.ts

@@ -0,0 +1,19 @@
+import type { WaitOpts } from '@aztec/aztec.js/contracts';
+import { publishContractClass, publishInstance } from '@aztec/aztec.js/deployment';
+import type { Wallet } from '@aztec/aztec.js/wallet';
+import { AuthRegistryArtifact, getStandardAuthRegistry } from '@aztec/standard-contracts/auth-registry';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+
+export async function publishStandardAuthRegistry(
+  wallet: Wallet,
+  from: AztecAddress,
+  waitOpts?: WaitOpts,
+): Promise<void> {
+  const { instance, contractClass } = await getStandardAuthRegistry();
+  if (!(await wallet.getContractClassMetadata(contractClass.id)).isContractClassPubliclyRegistered) {
+    await (await publishContractClass(wallet, AuthRegistryArtifact)).send({ from, wait: waitOpts });
+  }
+  if (!(await wallet.getContractMetadata(instance.address)).isContractPublished) {
+    await publishInstance(wallet, instance).send({ from, wait: waitOpts });
+  }
+}

package/src/local-network/banana_fpc.ts

@@ -1,4 +1,5 @@
 import { type InitialAccountData, getInitialTestAccountsData } from '@aztec/accounts/testing';
+import type { WaitOpts } from '@aztec/aztec.js/contracts';
 import type { Wallet } from '@aztec/aztec.js/wallet';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import type { LogFn } from '@aztec/foundation/log';
@@ -45,19 +46,22 @@ export async function getBananaFPCAddress(initialAccounts: InitialAccountData[])
   return (await getBananaFPCInstance(initialAccounts)).address;
 }
 
-export async function setupBananaFPC(initialAccounts: InitialAccountData[], wallet: Wallet, log: LogFn) {
+export async function setupBananaFPC(
+  initialAccounts: InitialAccountData[],
+  wallet: Wallet,
+  log: LogFn,
+  waitOpts?: WaitOpts,
+) {
   const bananaCoinAddress = await getBananaCoinAddress(initialAccounts);
   const admin = getBananaAdmin(initialAccounts);
   const [{ contract: bananaCoin }, { contract: fpc }] = await Promise.all([
-    TokenContract.deploy(wallet, admin, bananaCoinArgs.name, bananaCoinArgs.symbol, bananaCoinArgs.decimal).send({
-      from: admin,
-      contractAddressSalt: BANANA_COIN_SALT,
+    TokenContract.deploy(wallet, admin, bananaCoinArgs.name, bananaCoinArgs.symbol, bananaCoinArgs.decimal, {
+      salt: BANANA_COIN_SALT,
       universalDeploy: true,
-    }),
-    FPCContract.deploy(wallet, bananaCoinAddress, admin).send({
+    }).send({ from: admin, wait: waitOpts }),
+    FPCContract.deploy(wallet, bananaCoinAddress, admin, { salt: BANANA_FPC_SALT, universalDeploy: true }).send({
       from: admin,
-      contractAddressSalt: BANANA_FPC_SALT,
-      universalDeploy: true,
+      wait: waitOpts,
     }),
   ]);