@effectstream/midnight-contracts 0.100.0

package/README.md

@@ -0,0 +1,134 @@
+# @effectstream/midnight
+
+Utilities for working with Midnight contracts in EffectStream.
+
+## read-contract
+
+Provides a context-aware function to read Midnight contract information from JSON files.
+
+### Usage
+
+```typescript
+import { readMidnightContract } from "@effectstream/midnight-contracts/read-contract";
+
+// Read contract for the current network (defaults to contract-counter.<networkId>.json)
+const contractInfo = readMidnightContract("contract-counter");
+
+// Read contract for another network (e.g., preview)
+const previewInfo = readMidnightContract(
+  "contract-counter",
+  { networkId: "preview" },
+);
+
+// With explicit base directory (still respects network-specific files)
+const customDirInfo = readMidnightContract(
+  "contract-counter",
+  { baseDir: "/path/to/contracts", networkId: "undeployed" },
+);
+```
+
+### Features
+
+- **Context-aware**: Automatically finds contract files by recursively searching from the current working directory upward through the directory tree
+- **Flexible directory structure**: Works with any directory structure - no hardcoded paths required
+- **Multiple contracts**: Supports reading multiple contracts with different filenames
+- **Caching**: Results are cached per contract location, name, and filename combination
+- **Dynamic compiler detection**: Automatically finds the compiler subdirectory in `src/managed/`
+
+### Function Signature
+
+```typescript
+function readMidnightContract(
+  contractName: string,
+  contractFileName?: string,
+  options?: { baseDir?: string; networkId?: string }
+): MidnightContractInfo
+```
+
+### Parameters
+
+- `contractName`: The name of the contract directory (e.g., 'contract-counter', 'contract-eip-20')
+- `contractFileName`: Optional override. Defaults to `${contractName}.${networkId}.json`, so you can keep per-network files.
+- `options`: Optional configuration object. `baseDir` overrides the search location, and `networkId` selects the file (default: `undeployed`).
+
+### Returns
+
+`MidnightContractInfo` object containing:
+- `contractAddress`: The deployed contract address
+- `contractInfo`: Compiler-generated contract information (circuits, certificates, contracts)
+- `zkConfigPath`: Path to the zk configuration directory
+
+## deploy
+
+Deploys a Midnight contract using the provided configuration. This function is context-aware and automatically finds the contract directory and zkConfigPath.
+
+### Usage
+
+```typescript
+import { deployMidnightContract, type DeployConfig, type NetworkUrls } from "@effectstream/midnight-contracts/deploy";
+
+// Deploy with default network URLs (local undeployed endpoints)
+const config: DeployConfig = {
+  contractName: "contract-counter",
+  contractFileName: "contract-counter.json",
+  contractClass: Counter.Contract,
+  witnesses,
+  privateStateId: "counterPrivateState",
+  initialPrivateState: { privateCounter: 0 },
+};
+
+const contractAddress = await deployMidnightContract(config);
+
+// Deploy with custom network URLs
+const networkUrls: NetworkUrls = {
+  indexer: "http://localhost:8088/api/v3/graphql",
+  indexerWS: "ws://localhost:8088/api/v3/graphql/ws",
+  node: "http://localhost:9944",
+  proofServer: "http://localhost:6300",
+};
+
+const contractAddress = await deployMidnightContract(config, networkUrls);
+```
+
+### Function Signature
+
+```typescript
+function deployMidnightContract(
+  config: DeployConfig,
+  networkUrls?: NetworkUrls
+): Promise<string>
+```
+
+### Parameters
+
+- `config`: Deployment configuration object containing:
+  - `contractName`: Name of the contract directory (e.g., "contract-counter", "contract-eip-20")
+  - `contractFileName`: Base filename for the contract address. The deployed file will append the network id (e.g., `contract-counter.undeployed.json`).
+  - `contractClass`: The Contract class to deploy
+  - `witnesses`: Witness definitions
+  - `privateStateId`: On-chain private state ID
+  - `initialPrivateState`: Initial private state object
+  - `deployArgs`: Optional deployment arguments array
+  - `privateStateStoreName`: Optional private state store name (defaults to contractName-based value)
+  - `baseDir`: Optional base directory override for finding contracts
+  - `logDir`: Optional log directory path
+  - `extractWalletAddress`: Optional flag to extract wallet address info (for contracts that need initialOwner)
+
+- `networkUrls`: Optional network endpoint URLs. If not provided, defaults to local undeployed endpoints:
+  - `indexer`: GraphQL indexer HTTP endpoint (default: "http://127.0.0.1:8088/api/v3/graphql")
+  - `indexerWS`: GraphQL indexer WebSocket endpoint (default: "ws://127.0.0.1:8088/api/v3/graphql/ws")
+  - `node`: Midnight node RPC endpoint (default: "http://127.0.0.1:9944")
+  - `proofServer`: Proof server HTTP endpoint (default: "http://127.0.0.1:6300")
+
+### Returns
+
+A Promise that resolves to the deployed contract address as a string.
+
+### Features
+
+- **Context-aware**: Automatically finds contract directory by recursively searching from the current working directory
+- **Flexible network configuration**: Use default local endpoints or provide custom network URLs
+- **Automatic wallet setup**: Creates and funds a wallet automatically using the genesis mint seed
+- **Dynamic compiler detection**: Automatically finds the compiler subdirectory in `src/managed/`
+- **Contract address persistence**: Saves the deployed contract address to a JSON file
+

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@effectstream/midnight-contracts",
+  "version": "0.100.0",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/mod.ts",
+    "./read-contract": "./src/read-contract.ts",
+    "./deploy": "./src/deploy.ts",
+    "./wallet-info": "./src/get-wallet-info.ts",
+    "./midnight-env": "./src/midnight-env.ts",
+    "./types": "./src/types.ts"
+  },
+  "dependencies": {
+    "@effectstream/utils": "0.100.0",
+    "@scure/bip39": "^2.0.1",
+    "dotenv": "^16.4.7",
+    "@midnight-ntwrk/wallet": "5.0.0",
+    "@midnight-ntwrk/wallet-api": "5.0.0",
+    "@midnight-ntwrk/zswap": "4.0.0",
+    "@midnight-ntwrk/ledger": "4.0.0",
+    "rxjs": "^7.8.2",
+    "@midnight-ntwrk/wallet-sdk-address-format": "3.1.0",
+    "@midnight-ntwrk/midnight-js-network-id": "4.0.2",
+    "@midnight-ntwrk/midnight-js-types": "4.0.2",
+    "@midnight-ntwrk/midnight-js-utils": "4.0.2",
+    "@midnight-ntwrk/onchain-runtime-v3": "3.0.0",
+    "@midnight-ntwrk/midnight-js-contracts": "4.0.2",
+    "@midnight-ntwrk/midnight-js-indexer-public-data-provider": "4.0.2",
+    "@midnight-ntwrk/midnight-js-http-client-proof-provider": "4.0.2",
+    "@midnight-ntwrk/midnight-js-node-zk-config-provider": "4.0.2",
+    "@midnight-ntwrk/midnight-js-level-private-state-provider": "4.0.2",
+    "@midnight-ntwrk/wallet-sdk-abstractions": "2.0.0",
+    "@midnight-ntwrk/wallet-sdk-facade": "3.0.0",
+    "@midnight-ntwrk/wallet-sdk-hd": "3.0.1",
+    "@midnight-ntwrk/wallet-sdk-shielded": "2.1.0",
+    "@midnight-ntwrk/wallet-sdk-dust-wallet": "3.0.0",
+    "@midnight-ntwrk/wallet-sdk-unshielded-wallet": "2.1.0",
+    "@midnight-ntwrk/ledger-v8": "8.0.3",
+    "@midnight-ntwrk/compact-js": "2.5.0",
+    "@midnight-ntwrk/wallet-sdk-capabilities": "3.2.0"
+  }
+}

package/src/build-wallet.ts

@@ -0,0 +1,101 @@
+const log = console;
+import { Buffer } from "node:buffer";
+
+import type { NetworkId } from "@midnight-ntwrk/wallet-sdk-abstractions";
+import { shieldedToken } from "@midnight-ntwrk/ledger-v8";
+import type { WalletFacade } from "@midnight-ntwrk/wallet-sdk-facade";
+
+import { 
+    buildWalletFacade,
+    getInitialShieldedState, 
+    resolveWalletSyncTimeoutMs, 
+    syncAndWaitForFunds, 
+    safeStringifyProgress
+} from "./get-wallet-info.ts";
+
+import type { WalletResult, NetworkUrls } from "./types.ts";
+import type { InitialOwner } from "./types.ts";
+import { getEnv } from "@effectstream/utils/runtime";
+
+// ============================================================================
+// Wallet Facade  
+// ============================================================================
+
+/**
+ * Build wallet and wait for funds
+ */
+export async function buildWalletAndWaitForFunds(
+    networkUrls: Required<NetworkUrls>,
+    seed: string,
+    networkId: NetworkId.NetworkId
+  ): Promise<WalletResult> {
+    log.info("Building wallet using modular SDK");
+    const result = await buildWalletFacade(networkUrls, seed, networkId);
+  
+    const initialState = await getInitialShieldedState(result.wallet.shielded);
+    const address = initialState.address.coinPublicKeyString();
+    log.info(`Wallet seed: ${seed}`);
+    log.info(`Wallet address: ${address}`);
+    log.info(`Dust address: ${result.dustAddress}`);
+  
+    let balance = initialState.balances[shieldedToken().tag] ?? 0n;
+    console.log("initialState", safeStringifyProgress(initialState));
+    const syncTimeoutMs = resolveWalletSyncTimeoutMs();
+    if (balance === 0n) {
+      const skipWait =
+        getEnv("MIDNIGHT_SKIP_WAIT_FOR_FUNDS")?.toLowerCase() === "true";
+      log.info("Wallet shielded balance: 0");
+      log.info(
+        `Waiting to receive tokens... (timeout ${syncTimeoutMs}ms${skipWait ? ", skip on timeout enabled" : ""})`
+      );
+      try {
+        const { shieldedBalance, unshieldedBalance } = await syncAndWaitForFunds(
+          result.wallet
+        );
+        balance = shieldedBalance;
+        if (unshieldedBalance > 0n) {
+          log.info(`Unshielded balance available: ${unshieldedBalance}`);
+        }
+      } catch (e) {
+        if (skipWait) {
+          log.warn(
+            `Skipping wait for shielded funds after timeout: ${(e as Error).message}`
+          );
+        } else {
+          throw e;
+        }
+      }
+    }
+    log.info(`Wallet balance: ${balance}`);
+  
+    // Dust syncing is handled by syncAndWaitForFunds above
+    return result;
+  }
+
+
+  
+// ============================================================================
+// Contract Deployment Helpers
+// ============================================================================
+
+/**
+ * Extract initial owner from wallet for contracts that need it (e.g., EIP-20)
+ */
+export async function extractInitialOwnerFromWallet(
+wallet: WalletFacade
+): Promise<InitialOwner> {
+const initialState = await getInitialShieldedState(wallet.shielded);
+const coinPubHex = initialState.address.coinPublicKeyString();
+const encPubHex = initialState.address.encryptionPublicKeyString();
+log.info(`Extracting initial owner from wallet keys (hex): coin=${coinPubHex}`);
+log.info(`Encryption key (hex): ${encPubHex}`);
+
+const coinBytes = Buffer.from(coinPubHex, "hex");
+const encBytes = Buffer.from(encPubHex, "hex");
+
+return {
+    is_left: true,
+    left: { bytes: coinBytes },
+    right: { bytes: encBytes.subarray(0, 32) },
+};
+}

package/src/constants.ts

@@ -0,0 +1,20 @@
+// ============================================================================
+// Constants
+// ============================================================================
+
+export const CONSTANTS = {
+    /** Transaction TTL duration in milliseconds (1 hour) */
+    TTL_DURATION_MS: 60 * 60 * 1000,
+
+    /** Wallet sync progress logging throttle interval */
+    WALLET_SYNC_THROTTLE_MS: 10_000,
+
+    /** Wallet sync timeout (10 minutes) */
+    WALLET_SYNC_TIMEOUT_MS: 600_000,
+
+    /** Additional fee overhead for dust transactions (in smallest unit) */
+    DUST_FEE_OVERHEAD: 300_000_000_000_000n,
+
+    /** Fee blocks margin for dust wallet */
+    DUST_FEE_BLOCKS_MARGIN: 5,
+} as const;

package/src/deploy.ts

@@ -0,0 +1,296 @@
+// TODO Remove references to "src/managed" as this is not standard.
+
+import { setNetworkId } from "@midnight-ntwrk/midnight-js-network-id";
+import { Buffer } from "node:buffer";
+import { statSync, readdirSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { getEnv, cwd } from "@effectstream/utils/runtime";
+import { deployContract } from "@midnight-ntwrk/midnight-js-contracts";
+import type { PrivateStateId } from "@midnight-ntwrk/midnight-js-types";
+import { CompiledContract, type Witnesses, type Contract } from "@midnight-ntwrk/compact-js";
+import type { SigningKey } from "@midnight-ntwrk/ledger-v8";
+import type { NetworkId } from "@midnight-ntwrk/wallet-sdk-abstractions";
+import * as path from "node:path";
+
+const log = console;
+
+import { findContractDirectoryForDeploy } from "./read-contract.ts";
+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 { midnightNetworkConfig } from "./midnight-env.ts";
+
+function checkEnvVariables(): void {
+  if (!getEnv("MIDNIGHT_STORAGE_PASSWORD")) {
+    throw new Error(
+      "MIDNIGHT_STORAGE_PASSWORD is not set (Use a 16 char string)",
+    );
+  }
+}
+
+/**
+ * Find the compiler subdirectory in the managed directory
+ */
+function hasManagedArtifacts(dir: string): boolean {
+  const requiredDirs = ["contract", "compiler"];
+  try {
+    return requiredDirs.every((name) => {
+      const stats = statSync(path.join(dir, name));
+      return stats.isDirectory();
+    });
+  } catch {
+    return false;
+  }
+}
+
+function findCompilerSubdirectory(managedDir: string): string {
+  // Check the managed directory itself first before looking at subdirectories.
+  // This prevents accidentally picking a nested sub-contract (e.g. counter/)
+  // that only contains a subset of the circuit keys.
+  if (hasManagedArtifacts(managedDir)) {
+    return "";
+  }
+
+  try {
+    for (const entry of readdirSync(managedDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const candidate = path.join(managedDir, entry.name);
+      if (hasManagedArtifacts(candidate)) {
+        return entry.name;
+      }
+    }
+  } catch (_error) {
+    throw new Error(`Managed directory not found: ${managedDir}`);
+  }
+
+  throw new Error(
+    `No compiler artifacts found in managed directory: ${managedDir}. ` +
+      `Ensure the directory contains compiler, contract, keys, and zkir assets.`,
+  );
+}
+
+// ============================================================================
+// Main Deployment Function
+// ============================================================================
+
+/**
+ * Deploys a Midnight contract using the provided configuration.
+ *
+ * This function is context-aware and will find the contract directory
+ * and zkConfigPath automatically using readMidnightContract.
+ *
+ * @param config - Deployment configuration
+ * @param networkUrls - Optional network endpoint URLs (defaults to local undeployed endpoints)
+ * @returns The deployed contract address
+ */
+export async function deployMidnightContract(
+  config: DeployConfig,
+  networkUrls?: NetworkUrls,
+  seedOrMnemonic?: { seed: string; mnemonic: string },
+): Promise<string> {
+  checkEnvVariables();
+
+  // Find the contract directory
+  const contractDir = findContractDirectoryForDeploy(
+    config.contractName,
+    config.baseDir,
+  );
+
+  if (!contractDir) {
+    throw new Error(
+      `Could not find Midnight contract directory for "${config.contractName}". ` +
+        `Searched starting from ${config.baseDir || cwd()}. ` +
+        `Please ensure you're running from a directory that contains or is a parent of the Midnight contract directory, ` +
+        `or provide an explicit baseDir parameter.`,
+    );
+  }
+
+  // Find the compiler subdirectory to determine zkConfigPath
+  const managedDir = path.join(contractDir, config.contractName, "src/managed");
+  const compilerSubdir = findCompilerSubdirectory(managedDir);
+
+  const zkConfigPath = path.resolve(
+    path.join(contractDir, config.contractName, "src/managed", compilerSubdir),
+  );
+
+  // Default private state store name if not provided
+  const privateStateStoreName =
+    config.privateStateStoreName ??
+    `${config.contractName.replace("contract-", "")}-private-state`;
+
+  // Merge network URLs with defaults
+  const { id: networkIdOverride, ...endpoints } = networkUrls ?? {};
+  const resolvedNetworkUrls: Required<NetworkUrls> = {
+    id: 'placeholder-value',
+    indexer: endpoints.indexer ?? midnightNetworkConfig.indexer,
+    indexerWS: endpoints.indexerWS ?? midnightNetworkConfig.indexerWS,
+    node: endpoints.node ?? midnightNetworkConfig.node,
+    proofServer: endpoints.proofServer ?? midnightNetworkConfig.proofServer,
+  };
+  const resolvedNetworkId = (networkIdOverride ??
+    midnightNetworkConfig.id) as NetworkId.NetworkId;
+
+  log.info(
+    `Preflight resolved endpoints -> indexerHttp=${resolvedNetworkUrls.indexer}, indexerWs=${resolvedNetworkUrls.indexerWS}, node=${resolvedNetworkUrls.node}, proofServer=${resolvedNetworkUrls.proofServer}, networkId=${resolvedNetworkId}`,
+  );
+
+  setNetworkId(resolvedNetworkId);
+
+  let walletResult: WalletResult | null = null;
+  let providers: ReturnType<typeof configureMidnightNodeProviders> | null = null;
+
+  try {
+    log.info("Building wallet...");
+    let seed;
+    if (seedOrMnemonic?.seed) {
+      seed = seedOrMnemonic.seed;
+    } else if (seedOrMnemonic?.mnemonic) {
+      seed = Buffer.from(
+        await mnemonicToSeed(seedOrMnemonic.mnemonic),
+      ).toString("hex");
+    } else {
+      seed = midnightNetworkConfig.walletSeed;
+    }
+    if (!seed) {
+      throw new Error("No seed or mnemonic provided");
+    }
+
+    walletResult = await buildWalletAndWaitForFunds(
+      resolvedNetworkUrls,
+      seed,
+      resolvedNetworkId,
+    );
+
+    const {
+      wallet,
+      zswapSecretKeys,
+      walletZswapSecretKeys,
+      dustSecretKey,
+      walletDustSecretKey,
+      dustAddress,
+      unshieldedKeystore,
+    } = walletResult;
+    const resolvedDustReceiverAddress =
+      getEnv("MIDNIGHT_DUST_RECEIVER_ADDRESS") ?? dustAddress;
+    if (resolvedDustReceiverAddress === dustAddress) {
+      log.info(`Using derived dust address: ${resolvedDustReceiverAddress}`);
+    } else {
+      log.info(
+        `Using dust receiver address from MIDNIGHT_DUST_RECEIVER_ADDRESS: ${resolvedDustReceiverAddress}`,
+      );
+    }
+
+    // Extract wallet address info if needed (for contracts like EIP-20)
+    let deployArgs = config.deployArgs;
+    if (config.extractWalletAddress && deployArgs && deployArgs.length > 0) {
+      const initialOwner = await extractInitialOwnerFromWallet(wallet);
+      deployArgs = [...deployArgs.slice(0, -1), initialOwner];
+    }
+
+    log.info("Wallet built successfully.");
+
+    log.info("Configuring providers...");
+    // Use a separate LevelDB directory for deployment to avoid lock conflicts with batcher
+    const deployPrivateStateStoreName = `${privateStateStoreName}-deploy`;
+
+    providers = configureMidnightNodeProviders(
+      wallet,
+      zswapSecretKeys,
+      walletZswapSecretKeys,
+      dustSecretKey,
+      walletDustSecretKey,
+      resolvedNetworkUrls,
+      deployPrivateStateStoreName,
+      zkConfigPath,
+      unshieldedKeystore,
+    );
+    log.info("Providers configured.");
+
+    log.info("Deploying contract...");
+
+    // First, create the compiled contract
+    const MyCompiledContract = CompiledContract.make(
+      config.contractName,
+      config.contractClass,
+    ).pipe(
+      CompiledContract.withWitnesses(config.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;
+    log.info(`Contract address: ${contractAddress}`);
+
+    const baseContractFileName =
+      config.contractFileName ?? `${config.contractName}.json`;
+    const {
+      dir: contractFileDir,
+      name: contractFileBaseName,
+      ext: contractFileExt,
+    } = path.parse(baseContractFileName);
+    const normalizedExt = contractFileExt || ".json";
+    const networkSuffix = `.${resolvedNetworkId}`;
+    const fileBaseWithNetwork = contractFileBaseName.endsWith(networkSuffix)
+      ? contractFileBaseName
+      : `${contractFileBaseName}${networkSuffix}`;
+    const outputFileName = `${fileBaseWithNetwork}${normalizedExt}`;
+    const outputPath = path.join(contractDir, contractFileDir, outputFileName);
+
+    await writeFile(outputPath, JSON.stringify({ contractAddress }, null, 2));
+    log.info(
+      `Contract address saved to ${outputPath} (network: ${resolvedNetworkId})`,
+    );
+
+    return contractAddress;
+  } catch (e) {
+    if (e instanceof Error) {
+      log.error(`Deployment failed: ${e.message}`);
+      log.error(e.stack);
+    } else {
+      log.error("An unknown error occurred during deployment.");
+    }
+    throw e;
+  } finally {
+    // Close wallet first
+    if (walletResult) {
+      log.info("Closing wallet...");
+      try {
+        await walletResult.wallet.stop();
+      } catch (_closeError) {
+        // Ignore close errors
+      }
+      log.info("Wallet closed.");
+    }
+
+    // Wait a moment for Level DB to finish any async close operations
+    // The levelPrivateStateProvider opens/closes DB for each operation in withSubLevel
+    // But there might be pending async operations
+    log.info("Waiting for Level DB cleanup...");
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+}