@claritydao/midnight-agora-sdk 0.1.0 → 1.2.0

package/README.md

@@ -18,7 +18,7 @@ The Agora DAO Midnight SDK provides a type-safe, professional-grade interface fo
 ## Installation
 
 ```bash
-pnpm add @agora-dao-midnight/sdk
+pnpm add @claritydao/midnight-agora-sdk
 ```
 
 ## Quick Start
@@ -26,7 +26,7 @@ pnpm add @agora-dao-midnight/sdk
 ### 1. Deploy a New Governor Contract
 
 ```typescript
-import { GovernorAPI, initializeProviders, ConfigPresets } from '@agora-dao-midnight/sdk';
+import { GovernorAPI, initializeProviders, ConfigPresets } from '@claritydao/midnight-agora-sdk';
 import { randomBytes } from '@midnight-ntwrk/midnight-js-utils';
 import pino from 'pino';
 
@@ -62,7 +62,7 @@ console.log('Contract deployed at:', api.deployedContractAddress);
 ### 2. Join an Existing Contract
 
 ```typescript
-import { GovernorAPI, initializeProviders } from '@agora-dao-midnight/sdk';
+import { GovernorAPI, initializeProviders } from '@claritydao/midnight-agora-sdk';
 import pino from 'pino';
 
 const logger = pino({ level: 'info' });
@@ -76,27 +76,25 @@ const api = await GovernorAPI.join(providers, contractAddress, logger);
 ### 3. Create a Proposal
 
 ```typescript
-import { VoteChoice } from '@agora-dao-midnight/sdk';
-import type { ProposalAction } from '@agora-dao-midnight/sdk';
-
-// Define proposal actions (what happens if proposal passes)
-const actions: ProposalAction[] = [
-  {
-    typ: 0, // Transfer type
-    token: tokenAddress,
-    amount: BigInt(10000),
-    to: recipientAddress,
-    configKey: new Uint8Array(32),
-    configValue: new Uint8Array(32),
-  },
-];
+import { VoteChoice } from '@claritydao/midnight-agora-sdk';
+import type { EffectAction } from '@claritydao/midnight-agora-sdk';
+
+// Define the proposal effect (what happens if proposal passes)
+const action: EffectAction = {
+  typ: 2, // Transfer type
+  token: tokenAddress,
+  amount: BigInt(10000),
+  to: recipientAddress,
+  configKey: new Uint8Array(32),
+  configValue: new Uint8Array(32),
+};
 
 // Create proposal (requires sufficient stake)
 const { txData, proposalId } = await api.createProposal(
   'Fund Community Initiative',
   'Transfer 10,000 tokens to community wallet for Q1 initiatives',
   creatorAddress,
-  actions
+  action
 );
 
 console.log('Proposal created with ID:', proposalId);
@@ -105,7 +103,7 @@ console.log('Proposal created with ID:', proposalId);
 ### 4. Cast a Vote
 
 ```typescript
-import { VoteChoice } from '@agora-dao-midnight/sdk';
+import { VoteChoice } from '@claritydao/midnight-agora-sdk';
 
 // Vote on proposal (type-safe!)
 await api.castVote(
@@ -126,7 +124,7 @@ The SDK provides two configuration presets:
 For development and testnet:
 
 ```typescript
-import { ConfigPresets } from '@agora-dao-midnight/sdk';
+import { ConfigPresets } from '@claritydao/midnight-agora-sdk';
 
 const governanceConfig = ConfigPresets.testing();
 // Returns:
@@ -147,7 +145,7 @@ const governanceConfig = ConfigPresets.testing();
 For mainnet:
 
 ```typescript
-import { ConfigPresets } from '@agora-dao-midnight/sdk';
+import { ConfigPresets } from '@claritydao/midnight-agora-sdk';
 
 const governanceConfig = ConfigPresets.production();
 // Returns:
@@ -224,13 +222,13 @@ interface TokenConfig {
 }
 ```
 
-#### ProposalAction
+#### EffectAction
 
-Actions to execute when proposal passes:
+The single action to execute when a proposal passes:
 
 ```typescript
-interface ProposalAction {
-  typ: number;              // Action type (0 = transfer)
+interface EffectAction {
+  typ: number;              // Action type (1 = mint, 2 = transfer, 3 = config update)
   token: Uint8Array;        // Token address (32 bytes)
   amount: bigint;           // Amount to transfer
   to: Uint8Array;           // Recipient address (32 bytes)
@@ -316,7 +314,7 @@ async createProposal(
   title: string,
   description: string,
   creator: Uint8Array,
-  actions: ProposalAction[]
+  action: EffectAction
 ): Promise<{ txData: FinalizedTxData; proposalId: bigint }>
 ```
 
@@ -326,7 +324,7 @@ Creates a new governance proposal.
 - `title`: Proposal title (max 256 chars)
 - `description`: Proposal description (max 10,000 chars)
 - `creator`: Creator address (32 bytes, must have sufficient stake)
-- `actions`: Array of actions to execute if proposal passes
+- `action`: Single effect action to execute if proposal passes
 
 **Returns:** Object with transaction data and proposal ID
 
@@ -540,14 +538,14 @@ import {
   DeploymentError,
   InvalidConfigurationError,
   NetworkNotConfiguredError,
-} from '@agora-dao-midnight/sdk';
+} from '@claritydao/midnight-agora-sdk';
 ```
 
 ### Error Handling Pattern
 
 ```typescript
 try {
-  await api.createProposal(title, description, creator, actions);
+  await api.createProposal(title, description, creator, action);
 } catch (error) {
   if (error instanceof InsufficientStakeError) {
     console.error('Need more stake:', error.message);
@@ -566,7 +564,7 @@ try {
 The SDK includes comprehensive input validation:
 
 ```typescript
-import { validators } from '@agora-dao-midnight/sdk';
+import { validators } from '@claritydao/midnight-agora-sdk';
 
 // Validate proposal parameters
 validators.validateProposal(title, description, creator);
@@ -606,6 +604,9 @@ import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
 import wasm from 'vite-plugin-wasm';
 import topLevelAwait from 'vite-plugin-top-level-await';
+import path from 'node:path';
+
+const onchainRuntimePackage = '@midnight-ntwrk/onchain-runtime-v3';
 
 export default defineConfig({
   cacheDir: './.vite',
@@ -616,7 +617,7 @@ export default defineConfig({
       output: {
         manualChunks: {
           // CRITICAL: Separate chunk for WASM modules
-          wasm: ['@midnight-ntwrk/onchain-runtime'],
+          wasm: [onchainRuntimePackage],
         },
       },
     },
@@ -639,7 +640,7 @@ export default defineConfig({
       name: 'wasm-module-resolver',
       resolveId(source, importer) {
         if (
-          source === '@midnight-ntwrk/onchain-runtime' &&
+          (source === '@midnight-ntwrk/onchain-runtime' || source === onchainRuntimePackage) &&
           importer &&
           importer.includes('@midnight-ntwrk/compact-runtime')
         ) {
@@ -665,14 +666,18 @@ export default defineConfig({
     include: ['@midnight-ntwrk/compact-runtime'],
     // CRITICAL: Exclude WASM from optimization
     exclude: [
-      '@midnight-ntwrk/onchain-runtime',
-      '@midnight-ntwrk/onchain-runtime/midnight_onchain_runtime_wasm_bg.wasm',
-      '@midnight-ntwrk/onchain-runtime/midnight_onchain_runtime_wasm.js',
+      onchainRuntimePackage,
+      `${onchainRuntimePackage}/midnight_onchain_runtime_wasm_bg.wasm`,
+      `${onchainRuntimePackage}/midnight_onchain_runtime_wasm.js`,
     ],
   },
   resolve: {
     extensions: ['.mjs', '.js', '.ts', '.jsx', '.tsx', '.json', '.wasm'],
     mainFields: ['browser', 'module', 'main'],
+    alias: {
+      '@midnight-ntwrk/onchain-runtime': onchainRuntimePackage,
+      'isomorphic-ws': path.resolve(__dirname, './src/shims/isomorphic-ws.ts'),
+    },
   },
 });
 ```
@@ -681,7 +686,7 @@ export default defineConfig({
 
 The SDK depends on `@midnight-ntwrk/compact-runtime`, which:
 1. Uses CommonJS (`require()`)
-2. Imports `@midnight-ntwrk/onchain-runtime` (WASM module with top-level await)
+2. Imports `@midnight-ntwrk/onchain-runtime-v3` (WASM module with top-level await)
 3. Executes `ocrt.maxField()` at the top level
 
 This creates a CJS/ESM/WASM incompatibility that requires the custom resolver plugin and specific optimization settings.
@@ -705,7 +710,7 @@ Even with the `--webpack` flag, the CJS/ESM/WASM interaction is too complex for
 ### React Example
 
 ```tsx
-import { GovernorManager, VoteChoice, ConfigPresets } from '@agora-dao-midnight/sdk';
+import { GovernorManager, VoteChoice, ConfigPresets } from '@claritydao/midnight-agora-sdk';
 import { randomBytes } from '@midnight-ntwrk/midnight-js-utils';
 import { useEffect, useState } from 'react';
 import pino from 'pino';
@@ -752,22 +757,20 @@ function GovernanceApp() {
 
   const handleCreateProposal = async () => {
     try {
-      const actions = [
-        {
-          typ: 0,
-          token: tokenAddress,
-          amount: BigInt(1000),
-          to: recipientAddress,
-          configKey: new Uint8Array(32),
-          configValue: new Uint8Array(32),
-        },
-      ];
+      const action = {
+        typ: 2,
+        token: tokenAddress,
+        amount: BigInt(1000),
+        to: recipientAddress,
+        configKey: new Uint8Array(32),
+        configValue: new Uint8Array(32),
+      };
 
       const { proposalId } = await api.createProposal(
         'My Proposal',
         'Description here',
         creatorAddress,
-        actions
+        action
       );
 
       alert(`Proposal created: ${proposalId}`);
@@ -827,14 +830,14 @@ const config = {
 ### 3. Validate User Inputs
 
 ```typescript
-import { validators } from '@agora-dao-midnight/sdk';
+import { validators } from '@claritydao/midnight-agora-sdk';
 
 // ✅ Good: Validate before submission
 validators.validateProposal(title, description, creator);
-await api.createProposal(title, description, creator, actions);
+await api.createProposal(title, description, creator, action);
 
 // ❌ Bad: No validation
-await api.createProposal(title, description, creator, actions);
+await api.createProposal(title, description, creator, action);
 ```
 
 ### 4. Handle Errors Gracefully
@@ -865,7 +868,7 @@ try {
 
 **Problem:** `TypeError: ocrt.maxField is not a function`
 
-**Root Cause:** CJS/ESM/WASM module incompatibility. The SDK depends on `@midnight-ntwrk/compact-runtime` (CommonJS) which requires `@midnight-ntwrk/onchain-runtime` (WASM with top-level await).
+**Root Cause:** CJS/ESM/WASM module incompatibility. The SDK depends on `@midnight-ntwrk/compact-runtime` (CommonJS) which requires `@midnight-ntwrk/onchain-runtime-v3` (WASM with top-level await).
 
 **Solutions:**
 
@@ -945,7 +948,7 @@ commonjsOptions: {
 rollupOptions: {
   output: {
     manualChunks: {
-      wasm: ['@midnight-ntwrk/onchain-runtime'],
+      wasm: ['@midnight-ntwrk/onchain-runtime-v3'],
     },
   },
 }
@@ -961,8 +964,8 @@ rollupOptions: {
 optimizeDeps: {
   include: ['@midnight-ntwrk/compact-runtime'],  // Pre-bundle for CJS→ESM
   exclude: [
-    '@midnight-ntwrk/onchain-runtime',           // Don't optimize WASM
-    '@agora-dao-midnight/contract',              // Don't optimize contract
+    '@midnight-ntwrk/onchain-runtime-v3',        // Don't optimize WASM
+    '@claritydao/midnight-agora-contracts',              // Don't optimize contract
   ],
 }
 ```

package/dist/browser-providers.d.ts

@@ -1,21 +1,26 @@
-import { type GovernorProviders } from "./common-types";
-import { type Logger } from "pino";
-import { type InitialAPI } from "@midnight-ntwrk/dapp-connector-api";
-/**
- * Initializes and returns the providers required for Governor contract interactions in a browser environment.
- *
- * @param logger The logger instance for logging.
- * @param networkId The network ID to connect to (e.g., 'testnet', 'mainnet').
- * @returns A promise that resolves to configured GovernorProviders.
- *
- * @remarks
- * This function connects to the Midnight Lace wallet extension and retrieves network configuration
- * from the wallet. The network ID is specified by the caller.
- */
-export declare const initializeProviders: (logger: Logger, networkId?: string) => Promise<GovernorProviders>;
-declare global {
-    interface Window {
-        midnight?: Record<string, InitialAPI>;
-    }
+import { type GovernorProviders } from './common-types';
+import type { Configuration, ConnectedAPI, InitialAPI } from '@midnight-ntwrk/dapp-connector-api';
+import { type Logger } from 'pino';
+export interface InitializeGovernorProvidersOptions {
+    accountId?: string;
+    contractAddress?: string;
+    proofServerUri?: string;
+    zkConfigBaseUrl?: string;
 }
+export interface InitializeProvidersOptions extends InitializeGovernorProvidersOptions {
+    initialAPI?: InitialAPI;
+    networkId?: string;
+    walletName?: string;
+}
+export declare function parseMidnightRecipientAddress(value: string, networkId?: string): Uint8Array;
+export declare function connectMidnightWallet(initialAPI: InitialAPI, networkId?: string): Promise<ConnectedAPI>;
+export declare function encodeWalletUserId(walletOrCoinPublicKey: ConnectedAPI | string, networkId?: string): Promise<Uint8Array>;
+export declare function initializeGovernorProviders(wallet: ConnectedAPI, options?: InitializeGovernorProvidersOptions): Promise<{
+    providers: GovernorProviders;
+    config: Configuration;
+    walletPublicKey: Uint8Array;
+    accountId: string;
+}>;
+export declare const initializeProviders: (logger: Logger, options?: InitializeProvidersOptions) => Promise<GovernorProviders>;
+export declare function stripHexPrefix(value: string): string;
 //# sourceMappingURL=browser-providers.d.ts.map

package/dist/browser-providers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-providers.d.ts","sourceRoot":"","sources":["../src/browser-providers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAyB,MAAM,gBAAgB,CAAC;AAe/E,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,EACL,KAAK,UAAU,EAGhB,MAAM,oCAAoC,CAAC;AAgC5C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,MAAM,EACd,YAAW,MAAkB,KAC5B,OAAO,CAAC,iBAAiB,CAoC3B,CAAC;AAuKF,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;KACvC;CACF"}
+{"version":3,"file":"browser-providers.d.ts","sourceRoot":"","sources":["../src/browser-providers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAI/E,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAsB,MAAM,oCAAoC,CAAC;AAatH,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,MAAM,CAAC;AAenC,MAAM,WAAW,kCAAkC;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,0BAA2B,SAAQ,kCAAkC;IACpF,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAydD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,CA8B3F;AA0HD,wBAAsB,qBAAqB,CAAC,UAAU,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAuC7G;AAED,wBAAsB,kBAAkB,CAAC,qBAAqB,EAAE,YAAY,GAAG,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAe9H;AAED,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,kCAAuC,GAC/C,OAAO,CAAC;IACT,SAAS,EAAE,iBAAiB,CAAC;IAC7B,MAAM,EAAE,aAAa,CAAC;IACtB,eAAe,EAAE,UAAU,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC,CAgHD;AAED,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,MAAM,EACd,UAAS,0BAA+B,KACvC,OAAO,CAAC,iBAAiB,CAa3B,CAAC;AAEF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD"}