@effectstream/midnight-contracts 0.100.14 → 0.100.16

package/README.md

@@ -1,73 +1,53 @@
-# @effectstream/midnight
+# @effectstream/midnight-contracts
 
-Utilities for working with Midnight contracts in EffectStream.
+Utilities for reading and deploying Midnight contracts from inside an Effectstream node or test. Two functions: `readMidnightContract` to load contract metadata + ABI by name, and `deployMidnightContract` to deploy and persist the resulting address.
 
-## read-contract
+- Reads contract files by name, searching from the current working directory upward.
+- Supports per-network files (`contract-counter.undeployed.json`, `contract-counter.testnet.json`) without hardcoded paths.
+- Deploys against the local Midnight stack by default; pass `NetworkUrls` to point at another environment.
+- Persists the deployed address to a JSON file so subsequent reads pick it up automatically.
 
-Provides a context-aware function to read Midnight contract information from JSON files.
+## Install
 
-### 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" },
-);
+```bash
+bun add @effectstream/midnight-contracts
+# or
+npm install @effectstream/midnight-contracts
 ```
 
-### Features
+Requires a reachable Midnight node, proof server, and indexer. The defaults match what `@effectstream/orchestrator`'s Midnight step boots locally.
 
-- **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/`
+## Standalone usage
 
-### Function Signature
+### Read a contract
 
 ```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`).
+import { readMidnightContract } from "@effectstream/midnight-contracts/read-contract";
 
-### Returns
+// Defaults to contract-counter.<networkId>.json, where networkId is "undeployed".
+const local = readMidnightContract("contract-counter");
 
-`MidnightContractInfo` object containing:
-- `contractAddress`: The deployed contract address
-- `contractInfo`: Compiler-generated contract information (circuits, certificates, contracts)
-- `zkConfigPath`: Path to the zk configuration directory
+// Read the same contract on a different network.
+const preview = readMidnightContract("contract-counter", { networkId: "preview" });
 
-## deploy
+// Override the search base if your contracts live outside the CWD tree.
+const custom = readMidnightContract("contract-counter", {
+  baseDir: "/path/to/contracts",
+  networkId: "undeployed",
+});
+```
 
-Deploys a Midnight contract using the provided configuration. This function is context-aware and automatically finds the contract directory and zkConfigPath.
+Returns `{ contractAddress, contractInfo, zkConfigPath }`. Results are cached per `(location, name, filename)` tuple so repeated reads in the same process are free.
 
-### Usage
+### Deploy a contract
 
 ```typescript
-import { deployMidnightContract, type DeployConfig, type NetworkUrls } from "@effectstream/midnight-contracts/deploy";
+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",
@@ -77,58 +57,48 @@ const config: DeployConfig = {
   initialPrivateState: { privateCounter: 0 },
 };
 
-const contractAddress = await deployMidnightContract(config);
+const address = await deployMidnightContract(config);
+```
+
+To deploy against a non-default stack, pass `NetworkUrls`:
 
-// Deploy with custom network URLs
-const networkUrls: NetworkUrls = {
+```typescript
+const network: 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);
+const address = await deployMidnightContract(config, network);
 ```
 
-### Function Signature
+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.
 
-```typescript
-function deployMidnightContract(
-  config: DeployConfig,
-  networkUrls?: NetworkUrls
-): Promise<string>
-```
+## 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.
+
+## Key exports
+
+`@effectstream/midnight-contracts/read-contract`:
 
-### Parameters
+- `readMidnightContract(name, options?)`: returns `{ contractAddress, contractInfo, zkConfigPath }`. `options.networkId` selects per-network files; `options.baseDir` overrides the search base.
 
-- `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)
+`@effectstream/midnight-contracts/deploy`:
 
-- `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")
+- `deployMidnightContract(config, networkUrls?)`: deploys and returns the address. Persists the address to a JSON file.
+- `DeployConfig`, `NetworkUrls`: input types.
 
-### Returns
+## Examples
 
-A Promise that resolves to the deployed contract address as a string.
+End-to-end usage in templates:
 
-### Features
+- [`templates/evm-midnight-v2/`](https://github.com/effectstream/effectstream/tree/main/templates/evm-midnight-v2)
+- [`templates/zswap-da/`](https://github.com/effectstream/effectstream/tree/main/templates/zswap-da)
 
-- **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
+## Links
 
+- Docs: https://effectstream.github.io/docs/packages/chains/midnight-contracts
+- Source: https://github.com/effectstream/effectstream/tree/main/packages/chains/midnight-contracts
+- Midnight: https://midnight.network

package/package.json

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