@effectstream/midnight-contracts 0.100.17 → 0.100.19

package/README.md

@@ -41,6 +41,8 @@ Returns `{ contractAddress, contractInfo, zkConfigPath }`. Results are cached pe
 
 ### Deploy a contract
 
+Only `contractName` and `contractClass` are required — everything else has a sensible default, so a minimal deploy is just:
+
 ```typescript
 import {
   deployMidnightContract,
@@ -48,13 +50,24 @@ import {
   type NetworkUrls,
 } from "@effectstream/midnight-contracts/deploy";
 
+// contractName must match the directory that holds `src/managed`;
+// contractClass is the compiled Contract (e.g. `export * as Counter from "./managed/contract"`).
+const address = await deployMidnightContract({
+  contractName: "contract-counter",
+  contractClass: Counter.Contract,
+});
+```
+
+Supply the rest only when your contract needs it:
+
+```typescript
 const config: DeployConfig = {
   contractName: "contract-counter",
-  contractFileName: "contract-counter.json",
   contractClass: Counter.Contract,
-  witnesses,
-  privateStateId: "counterPrivateState",
-  initialPrivateState: { privateCounter: 0 },
+  witnesses,                              // default: {} (no witnesses)
+  privateStateId: "counterPrivateState",  // default: "privateState"
+  initialPrivateState: { privateCounter: 0 }, // default: {} (no private state)
+  contractFileName: "contract-counter.json",  // default: `${contractName}.json`
 };
 
 const address = await deployMidnightContract(config);
@@ -75,6 +88,25 @@ const address = await deployMidnightContract(config, network);
 
 The deploy helper creates and funds a wallet from the genesis mint seed, runs the deployment, and writes the resulting address to `${contractName}.${networkId}.json` so the next `readMidnightContract` call picks it up.
 
+### Contracts with many circuits (phased deployment)
+
+A standard deploy carries every circuit's verifier key in a single transaction. For contracts with enough circuits, that transaction exceeds the node's per-block limits and fails with `Transaction would exhaust block limits`. Set `phasedVerifierKeys: true` to instead deploy the contract with no verifier keys and then insert each circuit's key in its own transaction:
+
+```typescript
+const address = await deployMidnightContract({
+  ...config,
+  phasedVerifierKeys: true, // opt-in; default is a single-transaction deploy
+});
+```
+
+Phased mode writes progress to a resume-state file (`deployment-state.json` by default) and removes it on success, so an interrupted run can be re-run to continue from the last inserted circuit instead of redeploying. Tunables:
+
+- `phasedVerifierKeys?: boolean` — enable phased deployment (default `false`).
+- `vkInsertRetries?: number` — per-circuit retry count for key insertion (default `3`).
+- `phasedStateFile?: string` — resume-state file path (default `deployment-state.json` in the CWD).
+
+The circuit list is enumerated automatically from the contract's compiled `keys/` directory, so no per-contract configuration is required.
+
 ## Inside Effectstream
 
 `@effectstream/midnight-contracts` is the seam between Midnight contract artifacts on disk and the code that reads or deploys them. Templates that target Midnight call `readMidnightContract` from their node startup to resolve the on-chain address; the orchestrator's deploy step calls `deployMidnightContract` to put one there in the first place. On the sync side, `@effectstream/sync`'s `MidnightFetcher` consumes the node behind both calls.
@@ -87,7 +119,8 @@ The deploy helper creates and funds a wallet from the genesis mint seed, runs th
 
 `@effectstream/midnight-contracts/deploy`:
 
-- `deployMidnightContract(config, networkUrls?)`: deploys and returns the address. Persists the address to a JSON file.
+- `deployMidnightContract(config, networkUrls?)`: deploys and returns the address. Persists the address to a JSON file. Set `config.phasedVerifierKeys` for contracts whose circuits don't fit in a single deploy transaction.
+- `deployMidnightContractPhased(...)`: the phased deploy routine `deployMidnightContract` delegates to when `phasedVerifierKeys` is set. Exported for advanced callers that already have built providers and a wallet.
 - `DeployConfig`, `NetworkUrls`: input types.
 
 ## Examples

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/midnight-contracts",
-  "version": "0.100.17",
+  "version": "0.100.19",
   "license": "MIT",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -20,7 +20,7 @@
     "./types": "./src/types.ts"
   },
   "dependencies": {
-    "@effectstream/utils": "0.100.17",
+    "@effectstream/utils": "0.100.19",
     "@scure/bip39": "^2.0.1",
     "dotenv": "^16.4.7",
     "@midnight-ntwrk/wallet": "5.0.0",

package/src/deploy-phased.ts

@@ -0,0 +1,284 @@
+// ============================================================================
+// Phased Midnight contract deployment
+// ============================================================================
+//
+// Some contracts define so many circuits that a single deploy transaction —
+// which carries every circuit's verifier key (VK) — exceeds the node's
+// per-block transaction limits ("Transaction would exhaust block limits").
+//
+// This module deploys such contracts in phases:
+//   1. Deploy the contract with NO verifier keys (a "stripped" contract state
+//      that keeps only the initial data and maintenance authority).
+//   2. Insert each circuit's verifier key in its own transaction, using the
+//      official `submitInsertVerifierKeyTx` maintenance helper.
+//
+// Progress is tracked in a small resume-state file so an interrupted run can be
+// continued without redeploying or re-inserting already-applied keys.
+//
+// This path is opt-in via `DeployConfig.phasedVerifierKeys`; the default
+// single-transaction deploy in `deploy.ts` is unaffected.
+
+import { readFileSync, writeFileSync, rmSync, readdirSync } from "node:fs";
+import * as path from "node:path";
+import { getNetworkId } from "@midnight-ntwrk/midnight-js-network-id";
+import { ContractExecutable } from "@midnight-ntwrk/compact-js";
+import {
+  asContractAddress,
+  exitResultOrError,
+  makeContractExecutableRuntime,
+  SucceedEntirely,
+  type MidnightProviders,
+} from "@midnight-ntwrk/midnight-js-types";
+import { submitInsertVerifierKeyTx } from "@midnight-ntwrk/midnight-js-contracts";
+import {
+  ContractDeploy,
+  ContractState,
+  Intent,
+  sampleSigningKey,
+  Transaction,
+} from "@midnight-ntwrk/ledger-v8";
+
+import { CONSTANTS } from "./constants.ts";
+import type { DeployConfig, WalletResult } from "./types.ts";
+
+const log = console;
+
+const DEFAULT_VK_INSERT_RETRIES = 3;
+const DEFAULT_STATE_FILE = "deployment-state.json";
+
+interface PhasedDeploymentState {
+  contractAddress: string;
+  deployedCircuits: string[];
+}
+
+function createTtl(): Date {
+  return new Date(Date.now() + CONSTANTS.TTL_DURATION_MS);
+}
+
+/**
+ * Enumerate circuit IDs generically from the compiled `keys/` directory.
+ * Each circuit has a `<circuitId>.verifier` artifact; this avoids hardcoding a
+ * per-contract circuit list.
+ */
+function listCircuitIds(zkConfigPath: string): string[] {
+  const keysDir = path.join(zkConfigPath, "keys");
+  let entries: string[];
+  try {
+    entries = readdirSync(keysDir);
+  } catch (error) {
+    throw new Error(
+      `Could not read verifier keys directory '${keysDir}': ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+  const circuitIds = entries
+    .filter((name) => name.endsWith(".verifier"))
+    .map((name) => name.slice(0, -".verifier".length))
+    .sort();
+  if (circuitIds.length === 0) {
+    throw new Error(`No '*.verifier' artifacts found in '${keysDir}'.`);
+  }
+  return circuitIds;
+}
+
+function loadState(stateFilePath: string): PhasedDeploymentState {
+  try {
+    const parsed = JSON.parse(
+      readFileSync(stateFilePath, "utf8"),
+    ) as PhasedDeploymentState;
+    log.info(
+      `Found existing deployment state. Resuming deployment for contract: ${parsed.contractAddress}`,
+    );
+    return {
+      contractAddress: parsed.contractAddress ?? "",
+      deployedCircuits: parsed.deployedCircuits ?? [],
+    };
+  } catch {
+    return { contractAddress: "", deployedCircuits: [] };
+  }
+}
+
+function saveState(stateFilePath: string, state: PhasedDeploymentState): void {
+  writeFileSync(stateFilePath, JSON.stringify(state, null, 2));
+}
+
+/**
+ * Deploy a Midnight contract in phases: empty deploy, then per-circuit verifier
+ * key insertion. Returns the deployed contract address.
+ */
+export async function deployMidnightContractPhased(
+  providers: MidnightProviders,
+  // deno-lint-ignore no-explicit-any
+  compiledContract: any,
+  config: DeployConfig,
+  // deno-lint-ignore no-explicit-any
+  deployArgs: any[] | undefined,
+  walletResult: WalletResult,
+  zkConfigPath: string,
+): Promise<string> {
+  const stateFilePath = path.resolve(
+    config.phasedStateFile ?? path.join(process.cwd(), DEFAULT_STATE_FILE),
+  );
+  const maxRetries = config.vkInsertRetries ?? DEFAULT_VK_INSERT_RETRIES;
+
+  const state = loadState(stateFilePath);
+  let contractAddress = state.contractAddress;
+
+  log.info(
+    `Phased deploy: contract=${config.contractName} resuming=${Boolean(
+      contractAddress,
+    )}`,
+  );
+
+  // ── Phase 1: deploy the contract with no verifier keys ────────────────────
+  if (!contractAddress) {
+    const signingKey = sampleSigningKey();
+    const coinPublicKey = providers.walletProvider.getCoinPublicKey().toString();
+
+    const contractExec = ContractExecutable.make(compiledContract);
+    const contractRuntime = makeContractExecutableRuntime(
+      providers.zkConfigProvider,
+      { coinPublicKey, signingKey },
+    );
+
+    log.info("Running contract initialization to derive initial state...");
+    const exitResult = await contractRuntime.runPromiseExit(
+      (contractExec as any).initialize(
+        config.initialPrivateState ?? undefined,
+        ...(deployArgs ?? []),
+      ),
+    );
+    const initResult = exitResultOrError(exitResult as any) as any;
+
+    const privateState = initResult.private.privateState;
+    const derivedSigningKey = initResult.private.signingKey;
+    const fullContractState = initResult.public.contractState;
+
+    // Convert the compact-runtime contract state to a ledger-v8 contract state,
+    // then build a stripped copy that keeps the initial data + maintenance
+    // authority but drops every circuit operation (i.e. no verifier keys).
+    const fullLedgerState = ContractState.deserialize(
+      fullContractState.serialize(),
+    );
+    const strippedState = new ContractState();
+    strippedState.data = fullLedgerState.data;
+    strippedState.maintenanceAuthority = fullLedgerState.maintenanceAuthority;
+    log.info("Created stripped contract state (no verifier keys).");
+
+    const contractDeploy = new ContractDeploy(strippedState);
+    contractAddress = contractDeploy.address;
+
+    const unprovenTx = Transaction.fromParts(
+      getNetworkId(),
+      undefined,
+      undefined,
+      Intent.new(createTtl()).addDeploy(contractDeploy),
+    );
+    log.info(`Deploying empty contract at address: ${contractAddress}`);
+
+    const recipe = await walletResult.wallet.balanceUnprovenTransaction(
+      unprovenTx as any,
+      {
+        shieldedSecretKeys: walletResult.walletZswapSecretKeys as any,
+        dustSecretKey: walletResult.walletDustSecretKey as any,
+      },
+      { ttl: createTtl() },
+    );
+    const signedRecipe = await walletResult.wallet.signRecipe(
+      recipe,
+      (payload) => walletResult.unshieldedKeystore.signData(payload),
+    );
+    const finalizedTx = await walletResult.wallet.finalizeRecipe(signedRecipe);
+    const txId = await walletResult.wallet.submitTransaction(finalizedTx);
+
+    const txData = await providers.publicDataProvider.watchForTxData(txId);
+    if (txData.status !== SucceedEntirely) {
+      throw new Error(`Empty deploy failed with status ${txData.status}`);
+    }
+    log.info(
+      `Empty deploy succeeded: address=${contractAddress} (no verifier keys).`,
+    );
+
+    // Persist the contract address, private state and signing key so the VK
+    // insertion phase (and any resumed run) can find the maintenance authority.
+    state.contractAddress = contractAddress;
+    saveState(stateFilePath, state);
+
+    (providers.privateStateProvider as any).setContractAddress?.(contractAddress);
+    if (config.privateStateId) {
+      await providers.privateStateProvider.set(
+        config.privateStateId as any,
+        privateState,
+      );
+    }
+    await providers.privateStateProvider.setSigningKey(
+      contractAddress,
+      derivedSigningKey,
+    );
+  }
+
+  // ── Phase 2: insert each circuit's verifier key individually ──────────────
+  const circuitIds = listCircuitIds(zkConfigPath);
+  const verifierKeys = await providers.zkConfigProvider.getVerifierKeys(
+    circuitIds,
+  );
+  log.info(
+    `Inserting ${verifierKeys.length} verifier keys one-by-one: [${circuitIds.join(
+      ", ",
+    )}]`,
+  );
+
+  for (const [circuitId, verifierKey] of verifierKeys) {
+    if (state.deployedCircuits.includes(circuitId)) {
+      log.info(`Skipping already deployed circuit: ${circuitId}`);
+      continue;
+    }
+
+    log.info(`Inserting verifier key for circuit: ${circuitId}`);
+    for (let attempt = 1; ; attempt++) {
+      try {
+        const result = await submitInsertVerifierKeyTx(
+          providers,
+          compiledContract,
+          asContractAddress(contractAddress),
+          circuitId as any,
+          verifierKey,
+        );
+        if (result.status !== SucceedEntirely) {
+          throw new Error(
+            `Insert verifier key for ${circuitId} returned status ${result.status}`,
+          );
+        }
+        break;
+      } catch (error) {
+        if (attempt >= maxRetries) throw error;
+        log.warn(
+          `Retry inserting ${circuitId} (${attempt}/${maxRetries}) due to: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+        await new Promise((r) => setTimeout(r, 2000 * attempt));
+      }
+    }
+
+    state.deployedCircuits.push(circuitId);
+    saveState(stateFilePath, state);
+    log.info(
+      `Verifier key inserted: circuit=${circuitId} (${state.deployedCircuits.length}/${verifierKeys.length})`,
+    );
+  }
+
+  log.info(
+    `Phased deploy complete: address=${contractAddress} circuits=[${state.deployedCircuits.join(
+      ", ",
+    )}]`,
+  );
+  try {
+    rmSync(stateFilePath);
+  } catch {
+    // Resume-state file already gone — nothing to clean up.
+  }
+
+  return contractAddress;
+}

package/src/deploy.ts

@@ -19,6 +19,7 @@ import { mnemonicToSeed } from "./mnemonicToSeed.ts";
 import type { NetworkUrls, DeployConfig, WalletResult } from "./types.ts";
 import { buildWalletAndWaitForFunds, extractInitialOwnerFromWallet } from "./build-wallet.ts";
 import { configureMidnightNodeProviders } from "./providers.ts";
+import { deployMidnightContractPhased } from "./deploy-phased.ts";
 import { midnightNetworkConfig } from "./midnight-env.ts";
 
 function checkEnvVariables(): void {
@@ -209,45 +210,71 @@ export async function deployMidnightContract(
 
     log.info("Deploying contract...");
 
+    // Apply defaults so callers only pass what their contract needs. Only
+    // contractName and contractClass are truly required; everything else has a
+    // sensible default.
+    const resolvedConfig: DeployConfig = {
+      ...config,
+      contractFileName: config.contractFileName ?? `${config.contractName}.json`,
+      witnesses: config.witnesses ?? {},
+      privateStateId: config.privateStateId ?? "privateState",
+      initialPrivateState: config.initialPrivateState ?? {},
+    };
+
     // First, create the compiled contract
     const MyCompiledContract = CompiledContract.make(
-      config.contractName,
-      config.contractClass,
+      resolvedConfig.contractName,
+      resolvedConfig.contractClass,
     ).pipe(
-      CompiledContract.withWitnesses(config.witnesses as never),
+      CompiledContract.withWitnesses(resolvedConfig.witnesses as never),
       CompiledContract.withCompiledFileAssets(managedDir),
     );
 
-    const deployOptions: {
-      compiledContract: CompiledContract.CompiledContract<
-        Contract<undefined, Witnesses<undefined>>,
-        undefined,
-        never
-      >;
-      privateStateId: PrivateStateId;
-      initialPrivateState: Contract.PrivateState<any>;
-      signingKey?: SigningKey;
-      args: Contract.InitializeParameters<any>;
-    } = {
-      compiledContract: MyCompiledContract as any,
-      privateStateId: config.privateStateId as PrivateStateId,
-      initialPrivateState:
-        config.initialPrivateState as Contract.PrivateState<any>,
-      args: (deployArgs && deployArgs.length > 0
-        ? deployArgs
-        : []) as Contract.InitializeParameters<any>,
-      signingKey: undefined,
-    };
-
-    const deployedContract = await deployContract(providers, deployOptions);
-    log.info("Contract deployed.");
-
-    const contractAddress =
-      deployedContract.deployTxData.public.contractAddress;
+    let contractAddress: string;
+    if (resolvedConfig.phasedVerifierKeys) {
+      // Opt-in path for contracts with too many circuits to deploy in a single
+      // transaction: deploy with no verifier keys, then insert each circuit's
+      // key one transaction at a time.
+      log.info("Phased verifier-key deployment enabled.");
+      contractAddress = await deployMidnightContractPhased(
+        providers,
+        MyCompiledContract,
+        resolvedConfig,
+        deployArgs,
+        walletResult,
+        zkConfigPath,
+      );
+      log.info("Contract deployed (phased).");
+    } else {
+      const deployOptions: {
+        compiledContract: CompiledContract.CompiledContract<
+          Contract<undefined, Witnesses<undefined>>,
+          undefined,
+          never
+        >;
+        privateStateId: PrivateStateId;
+        initialPrivateState: Contract.PrivateState<any>;
+        signingKey?: SigningKey;
+        args: Contract.InitializeParameters<any>;
+      } = {
+        compiledContract: MyCompiledContract as any,
+        privateStateId: resolvedConfig.privateStateId as PrivateStateId,
+        initialPrivateState:
+          resolvedConfig.initialPrivateState as Contract.PrivateState<any>,
+        args: (deployArgs && deployArgs.length > 0
+          ? deployArgs
+          : []) as Contract.InitializeParameters<any>,
+        signingKey: undefined,
+      };
+
+      const deployedContract = await deployContract(providers, deployOptions);
+      log.info("Contract deployed.");
+      contractAddress = deployedContract.deployTxData.public.contractAddress;
+    }
     log.info(`Contract address: ${contractAddress}`);
 
     const baseContractFileName =
-      config.contractFileName ?? `${config.contractName}.json`;
+      resolvedConfig.contractFileName ?? `${config.contractName}.json`;
     const {
       dir: contractFileDir,
       name: contractFileBaseName,

package/src/mod.ts

@@ -1,4 +1,5 @@
 export { deployMidnightContract } from "./deploy.ts";
+export { deployMidnightContractPhased } from "./deploy-phased.ts";
 export type {
     DeployConfig,
     NetworkUrls,

package/src/types.ts

@@ -11,21 +11,21 @@ import type { UnshieldedKeystore } from "@midnight-ntwrk/wallet-sdk-unshielded-w
  * Configuration for deploying a Midnight contract
  */
 export interface DeployConfig {
-    /** Name of the contract directory (e.g., "contract-counter", "contract-eip-20") */
+    /** Name of the contract directory containing `src/managed` (e.g., "contract-counter", "contract-eip-20"). Required. */
     contractName: string;
-    /** Base filename for contract address (e.g., "contract-counter.json"); a network suffix is appended */
-    contractFileName: string;
-    /** The Contract class to deploy */
+    /** The compiled Contract class to deploy (e.g. `Foo.Contract`). Required. */
     // deno-lint-ignore no-explicit-any
     contractClass: any;
-    /** Witness definitions */
+    /** Base filename the deployed address is written to; a network suffix is appended. Defaults to `${contractName}.json`. */
+    contractFileName?: string;
+    /** Witness definitions. Defaults to `{}` (no witnesses). */
     // deno-lint-ignore no-explicit-any
-    witnesses: any;
-    /** On-chain private state ID */
-    privateStateId: string;
-    /** Initial private state object */
+    witnesses?: any;
+    /** On-chain private state ID. Defaults to `"privateState"`. */
+    privateStateId?: string;
+    /** Initial private state object. Defaults to `{}` (for contracts with no private state). */
     // deno-lint-ignore no-explicit-any
-    initialPrivateState: any;
+    initialPrivateState?: any;
     /** Optional deployment arguments array */
     // deno-lint-ignore no-explicit-any
     deployArgs?: any[];
@@ -35,6 +35,25 @@ export interface DeployConfig {
     baseDir?: string;
     /** Optional flag to extract wallet address info (for contracts that need initialOwner) */
     extractWalletAddress?: boolean;
+    /**
+     * Deploy in phases instead of a single transaction.
+     *
+     * When `true`, the contract is first deployed with NO verifier keys, then each
+     * circuit's verifier key is inserted in its own transaction. Use this for
+     * contracts with many circuits whose combined verifier keys would otherwise
+     * exceed the node's per-block transaction limits ("Transaction would exhaust
+     * block limits"). Defaults to `false` (single-transaction deploy).
+     */
+    phasedVerifierKeys?: boolean;
+    /** Per-circuit retry count when inserting verifier keys in phased mode (default 3). */
+    vkInsertRetries?: number;
+    /**
+     * Path to the resume-state file used by phased mode to track progress so an
+     * interrupted deployment can be resumed. Defaults to `deployment-state.json`
+     * in the current working directory. This file is removed once the phased
+     * deployment completes successfully.
+     */
+    phasedStateFile?: string;
 }
 
 /**