Merge pull request #5 from PolyhedraZK/fix/sdk-v2

Fix/sdk v2

Author: niconiconi

.prettierrc

@@ -0,0 +1,10 @@
+{
+  "singleQuote": true,
+  "jsxSingleQuote": false,
+  "trailingComma": "es5",
+  "printWidth": 200,
+  "proseWrap": "never",
+  "useTabs": false,
+  "tabWidth": 2,
+  "semi": true
+}

AGENTS.md

@@ -13,7 +13,6 @@ The repository is a single-package layout. The root `package.json` is the only d
 - SDK source: `src/`
 - Build output: `dist/` (publish includes only `dist/` and `assets/`)
 - Demos: `demos/` (for showcase/debug only; not published with the SDK)
-- Asset build: `pnpm run build:assets` outputs to `assets/`
 - Browser demo: `pnpm run dev`
 - Node demo: `pnpm run demo:node -- <command>`
 
@@ -25,6 +24,7 @@ src/                          # SDK source (~60 files, ~8400 lines)
   index.browser.ts            # Browser entry: + IndexedDbStore
   index.node.ts               # Node entry: + FileStore
   types.ts                    # All type definitions (~850 lines)
+  errors.ts                   # Error codes and SdkError
   core/                       # SdkCore: event bus, init orchestration
   crypto/                     # Poseidon2, BabyJubjub, key derivation, commitments
   wallet/                     # WalletService: session, UTXO, balance, memo decrypt
@@ -38,6 +38,10 @@ src/                          # SDK source (~60 files, ~8400 lines)
   memo/                       # MemoKit: ECDH + NaCl secretbox encrypt/decrypt
   abi/                        # Contract ABIs (Ocash.json compiled ABI, ERC20)
   runtime/                    # WasmBridge: WASM loading, runtime detect, asset cache
+  ledger/                     # Chain/token/relayer configuration
+  assets/                     # Default assets metadata
+  abi/                        # Contract ABIs
+  dummy/                      # Test data helpers
   utils/                      # Shared utilities (random, signal, url, bigint)
 tests/                        # Vitest tests (~38 files)
 demos/browser/                # React + Vite + wagmi browser demo
@@ -55,8 +59,6 @@ pnpm run dev                  # Browser demo (Vite, port 5173)
 pnpm run dev:sdk              # SDK watch mode (tsup --watch)
 pnpm run demo:node -- <cmd>   # Run Node demo (requires build)
 pnpm run demo:node:tsx -- <cmd> # Run Node demo via tsx
-pnpm run build:assets         # Build WASM/circuit assets
-pnpm run build:assets:local   # Build assets including wasm_exec.js
 ```
 
 ## Tech Stack
@@ -100,33 +102,6 @@ The ABI JSON is extracted from the Foundry compiled output (`Ocash.sol/Ocash.jso
 - `core.ready()` must be called before any proof/witness operations (loads WASM lazily)
 - StorageAdapter is an interface — default MemoryStore is non-persistent
 
-## SDK Modules (Public API)
-
-```
-sdk.core      — ready(), reset(), on(), off()
-sdk.keys      — deriveKeyPair(seed, nonce), userPkToAddress(), addressToUserPk()
-sdk.crypto    — commitment(), nullifier(), createRecordOpening(), memo.createMemo()
-sdk.assets    — getChains(), getTokens(), syncRelayerConfig()
-sdk.storage   — getAdapter()
-sdk.wallet    — open(), close(), getUtxos(), getBalance(), markSpent()
-sdk.sync      — start(), stop(), syncOnce(), getStatus()
-sdk.merkle    — getProofByCids(), buildInputSecretsFromUtxos()
-sdk.planner   — estimate(), estimateMax(), plan()
-sdk.zkp       — proveTransfer(), proveWithdraw()
-sdk.tx        — buildTransferCalldata(), buildWithdrawCalldata()
-sdk.ops       — prepareTransfer(), prepareWithdraw(), prepareDeposit(), submitRelayerRequest()
-```
-
-## Cryptography
-
-- Curve: BabyJubjub (twisted Edwards over BN254 scalar field) — pure JS
-- Hash: Poseidon2 (commitments, nullifiers, Merkle nodes) — pure JS
-- Encryption: ECDH + NaCl XSalsa20-Poly1305 (memo encryption) — tweetnacl
-- Key derivation: HKDF-SHA256 — @noble/hashes
-- Proofs: Groth16 zk-SNARK — Go WASM (fetched at runtime, not bundled)
-- commitment = Poseidon2(asset_id, amount, pk.x, pk.y, blinding_factor)
-- nullifier = Poseidon2(commitment, secret_key, merkle_index)
-
 ## Testing
 
 - All tests in `tests/` directory, file pattern `{module}.test.ts`
@@ -188,7 +163,7 @@ const sdk = createSdk({
 await sdk.core.ready();
 await sdk.wallet.open({ seed: 'seed phrase or bytes' });
 await sdk.sync.syncOnce();
-const balance = await sdk.wallet.getBalance({ chainId: 11155111 });
+const balance = await sdk.wallet.getBalance({ chainId, assetId });
 ```
 
 ### 2) Runtime Assets and `assetsOverride`
@@ -733,12 +708,7 @@ export interface MerkleApi {
   getProofByCids: (input: { chainId: number; cids: number[]; totalElements: bigint }) => Promise<RemoteMerkleProofResponse>;
   getProofByCid: (input: { chainId: number; cid: number; totalElements: bigint }) => Promise<RemoteMerkleProofResponse>;
   ingestEntryMemos?: (chainId: number, memos: Array<{ cid: number | null; commitment: Hex | string | bigint }>) => Promise<void> | void;
-  buildAccMemberWitnesses: (input: {
-    remote: RemoteMerkleProofResponse;
-    utxos: Array<{ commitment: Hex; mkIndex: number }>;
-    arrayHash: bigint;
-    totalElements: bigint;
-  }) => AccMemberWitness[];
+  buildAccMemberWitnesses: (input: { remote: RemoteMerkleProofResponse; utxos: Array<{ commitment: Hex; mkIndex: number }>; arrayHash: bigint; totalElements: bigint }) => AccMemberWitness[];
   buildInputSecretsFromUtxos: (input: {
     remote: RemoteMerkleProofResponse;
     utxos: Array<{ commitment: Hex; memo?: Hex; mkIndex: number }>;
@@ -757,7 +727,7 @@ export interface WalletApi {
   open(session: WalletSessionInput): Promise<void>;
   close(): Promise<void>;
   getUtxos(query?: ListUtxosQuery): Promise<ListUtxosResult>;
-  getBalance(query?: { chainId?: number; assetId?: string }): Promise<bigint>;
+  getBalance(query: { chainId: number; assetId: string }): Promise<bigint>;
   markSpent(input: { chainId: number; nullifiers: Hex[] }): Promise<void>;
 }
 ```
@@ -766,20 +736,9 @@ export interface WalletApi {
 
 ```ts
 export interface PlannerApi {
-  estimate(input: {
-    chainId: number;
-    assetId: string;
-    action: 'transfer' | 'withdraw';
-    amount: bigint;
-    payIncludesFee?: boolean;
-  }): Promise<PlannerEstimateResult>;
+  estimate(input: { chainId: number; assetId: string; action: 'transfer' | 'withdraw'; amount: bigint; payIncludesFee?: boolean }): Promise<PlannerEstimateResult>;
 
-  estimateMax(input: {
-    chainId: number;
-    assetId: string;
-    action: 'transfer' | 'withdraw';
-    payIncludesFee?: boolean;
-  }): Promise<PlannerMaxEstimateResult>;
+  estimateMax(input: { chainId: number; assetId: string; action: 'transfer' | 'withdraw'; payIncludesFee?: boolean }): Promise<PlannerMaxEstimateResult>;
 
   plan(input: Record<string, unknown>): Promise<PlannerPlanResult>;
 }
@@ -809,16 +768,7 @@ export interface TxBuilderApi {
 
 ```ts
 export interface OpsApi {
-  prepareTransfer(input: {
-    chainId: number;
-    assetId: string;
-    amount: bigint;
-    to: Hex;
-    ownerKeyPair: UserKeyPair;
-    publicClient: PublicClient;
-    relayerUrl?: string;
-    autoMerge?: boolean;
-  }): Promise<
+  prepareTransfer(input: { chainId: number; assetId: string; amount: bigint; to: Hex; ownerKeyPair: UserKeyPair; publicClient: PublicClient; relayerUrl?: string; autoMerge?: boolean }): Promise<
     | {
         kind: 'transfer';
         plan: TransferPlan;
@@ -858,14 +808,7 @@ export interface OpsApi {
     meta: { arrayHashIndex: number; merkleRootIndex: number; relayer: Address };
   }>;
 
-  prepareDeposit(input: {
-    chainId: number;
-    assetId: string;
-    amount: bigint;
-    ownerPublicKey: UserPublicKey;
-    account: Address;
-    publicClient: PublicClient;
-  }): Promise<{
+  prepareDeposit(input: { chainId: number; assetId: string; amount: bigint; ownerPublicKey: UserPublicKey; account: Address; publicClient: PublicClient }): Promise<{
     chainId: number;
     assetId: string;
     amount: bigint;
@@ -908,24 +851,9 @@ export interface OpsApi {
     operationId?: string;
   }>;
 
-  waitRelayerTxHash(input: {
-    relayerUrl: string;
-    relayerTxHash: Hex;
-    timeoutMs?: number;
-    intervalMs?: number;
-    signal?: AbortSignal;
-    operationId?: string;
-    requestUrl?: string;
-  }): Promise<Hex>;
+  waitRelayerTxHash(input: { relayerUrl: string; relayerTxHash: Hex; timeoutMs?: number; intervalMs?: number; signal?: AbortSignal; operationId?: string; requestUrl?: string }): Promise<Hex>;
 
-  waitForTransactionReceipt(input: {
-    publicClient: PublicClient;
-    txHash: Hex;
-    timeoutMs?: number;
-    pollIntervalMs?: number;
-    confirmations?: number;
-    operationId?: string;
-  }): Promise<TransactionReceipt>;
+  waitForTransactionReceipt(input: { publicClient: PublicClient; txHash: Hex; timeoutMs?: number; pollIntervalMs?: number; confirmations?: number; operationId?: string }): Promise<TransactionReceipt>;
 
   submitRelayerRequest<T = unknown>(input: {
     prepared: { plan: TransferPlan | WithdrawPlan; request: RelayerRequest; kind?: 'transfer' | 'merge' };

CLAUDE.md

@@ -62,17 +62,17 @@ The repository is a single-package layout. The root `package.json` is the only d
 
 ## Tech Stack
 
-| Layer | Tech |
-|---|---|
-| Language | TypeScript 5.8 (strict), ES2020 target |
-| Build | tsup (ESM + CJS dual format, 3 entry points) |
-| Tests | vitest 2.1 (Node env, globals) |
-| Crypto | @noble/curves + @noble/hashes + @noble/ciphers + tweetnacl |
-| Chain | viem 2.x |
-| ZK Proofs | Go WASM circuits (Groth16) via ProofBridge |
-| Events | eventemitter3 |
-| Package | pnpm 9.15+ |
-| Node | 20.19.0+ |
+| Layer     | Tech                                                       |
+| --------- | ---------------------------------------------------------- |
+| Language  | TypeScript 5.8 (strict), ES2020 target                     |
+| Build     | tsup (ESM + CJS dual format, 3 entry points)               |
+| Tests     | vitest 2.1 (Node env, globals)                             |
+| Crypto    | @noble/curves + @noble/hashes + @noble/ciphers + tweetnacl |
+| Chain     | viem 2.x                                                   |
+| ZK Proofs | Go WASM circuits (Groth16) via ProofBridge                 |
+| Events    | eventemitter3                                              |
+| Package   | pnpm 9.15+                                                 |
+| Node      | 20.19.0+                                                   |
 
 ## Project Structure
 
@@ -223,7 +223,7 @@ const sdk = createSdk({
 await sdk.core.ready();
 await sdk.wallet.open({ seed: 'seed phrase or bytes' });
 await sdk.sync.syncOnce();
-const balance = await sdk.wallet.getBalance({ chainId: 11155111 });
+const balance = await sdk.wallet.getBalance({ chainId, assetId });
 ```
 
 ### 2) Runtime Assets and `assetsOverride`
@@ -768,12 +768,7 @@ export interface MerkleApi {
   getProofByCids: (input: { chainId: number; cids: number[]; totalElements: bigint }) => Promise<RemoteMerkleProofResponse>;
   getProofByCid: (input: { chainId: number; cid: number; totalElements: bigint }) => Promise<RemoteMerkleProofResponse>;
   ingestEntryMemos?: (chainId: number, memos: Array<{ cid: number | null; commitment: Hex | string | bigint }>) => Promise<void> | void;
-  buildAccMemberWitnesses: (input: {
-    remote: RemoteMerkleProofResponse;
-    utxos: Array<{ commitment: Hex; mkIndex: number }>;
-    arrayHash: bigint;
-    totalElements: bigint;
-  }) => AccMemberWitness[];
+  buildAccMemberWitnesses: (input: { remote: RemoteMerkleProofResponse; utxos: Array<{ commitment: Hex; mkIndex: number }>; arrayHash: bigint; totalElements: bigint }) => AccMemberWitness[];
   buildInputSecretsFromUtxos: (input: {
     remote: RemoteMerkleProofResponse;
     utxos: Array<{ commitment: Hex; memo?: Hex; mkIndex: number }>;
@@ -792,7 +787,7 @@ export interface WalletApi {
   open(session: WalletSessionInput): Promise<void>;
   close(): Promise<void>;
   getUtxos(query?: ListUtxosQuery): Promise<ListUtxosResult>;
-  getBalance(query?: { chainId?: number; assetId?: string }): Promise<bigint>;
+  getBalance(query: { chainId: number; assetId: string }): Promise<bigint>;
   markSpent(input: { chainId: number; nullifiers: Hex[] }): Promise<void>;
 }
 ```
@@ -801,20 +796,9 @@ export interface WalletApi {
 
 ```ts
 export interface PlannerApi {
-  estimate(input: {
-    chainId: number;
-    assetId: string;
-    action: 'transfer' | 'withdraw';
-    amount: bigint;
-    payIncludesFee?: boolean;
-  }): Promise<PlannerEstimateResult>;
+  estimate(input: { chainId: number; assetId: string; action: 'transfer' | 'withdraw'; amount: bigint; payIncludesFee?: boolean }): Promise<PlannerEstimateResult>;
 
-  estimateMax(input: {
-    chainId: number;
-    assetId: string;
-    action: 'transfer' | 'withdraw';
-    payIncludesFee?: boolean;
-  }): Promise<PlannerMaxEstimateResult>;
+  estimateMax(input: { chainId: number; assetId: string; action: 'transfer' | 'withdraw'; payIncludesFee?: boolean }): Promise<PlannerMaxEstimateResult>;
 
   plan(input: Record<string, unknown>): Promise<PlannerPlanResult>;
 }
@@ -844,16 +828,7 @@ export interface TxBuilderApi {
 
 ```ts
 export interface OpsApi {
-  prepareTransfer(input: {
-    chainId: number;
-    assetId: string;
-    amount: bigint;
-    to: Hex;
-    ownerKeyPair: UserKeyPair;
-    publicClient: PublicClient;
-    relayerUrl?: string;
-    autoMerge?: boolean;
-  }): Promise<
+  prepareTransfer(input: { chainId: number; assetId: string; amount: bigint; to: Hex; ownerKeyPair: UserKeyPair; publicClient: PublicClient; relayerUrl?: string; autoMerge?: boolean }): Promise<
     | {
         kind: 'transfer';
         plan: TransferPlan;
@@ -893,14 +868,7 @@ export interface OpsApi {
     meta: { arrayHashIndex: number; merkleRootIndex: number; relayer: Address };
   }>;
 
-  prepareDeposit(input: {
-    chainId: number;
-    assetId: string;
-    amount: bigint;
-    ownerPublicKey: UserPublicKey;
-    account: Address;
-    publicClient: PublicClient;
-  }): Promise<{
+  prepareDeposit(input: { chainId: number; assetId: string; amount: bigint; ownerPublicKey: UserPublicKey; account: Address; publicClient: PublicClient }): Promise<{
     chainId: number;
     assetId: string;
     amount: bigint;
@@ -943,24 +911,9 @@ export interface OpsApi {
     operationId?: string;
   }>;
 
-  waitRelayerTxHash(input: {
-    relayerUrl: string;
-    relayerTxHash: Hex;
-    timeoutMs?: number;
-    intervalMs?: number;
-    signal?: AbortSignal;
-    operationId?: string;
-    requestUrl?: string;
-  }): Promise<Hex>;
+  waitRelayerTxHash(input: { relayerUrl: string; relayerTxHash: Hex; timeoutMs?: number; intervalMs?: number; signal?: AbortSignal; operationId?: string; requestUrl?: string }): Promise<Hex>;
 
-  waitForTransactionReceipt(input: {
-    publicClient: PublicClient;
-    txHash: Hex;
-    timeoutMs?: number;
-    pollIntervalMs?: number;
-    confirmations?: number;
-    operationId?: string;
-  }): Promise<TransactionReceipt>;
+  waitForTransactionReceipt(input: { publicClient: PublicClient; txHash: Hex; timeoutMs?: number; pollIntervalMs?: number; confirmations?: number; operationId?: string }): Promise<TransactionReceipt>;
 
   submitRelayerRequest<T = unknown>(input: {
     prepared: { plan: TransferPlan | WithdrawPlan; request: RelayerRequest; kind?: 'transfer' | 'merge' };