@orbinum/sdk 0.4.1 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 Official TypeScript SDK for Orbinum — a privacy-focused blockchain built on Substrate with an EVM compatibility layer.
 
-The SDK provides typed modules for interacting with the Orbinum protocol: Substrate RPC, EVM JSON-RPC, shielded pool operations, account identity and mapping, `rpc-v2`, ZK verifier, precompiles, and the indexer REST API.
+The SDK provides typed modules for interacting with the Orbinum protocol: Substrate RPC, EVM JSON-RPC, shielded pool operations, ZK proof generation, encrypted note vault, account identity and mapping, relayer status, `rpc-v2`, ZK verifier, precompiles, and the indexer REST API.
 
 ## Installation
 
@@ -14,9 +14,9 @@ pnpm add @orbinum/sdk
 
 ## Requirements
 
-- Node.js 18 or later
+- Node.js 18 or later (WebCrypto API required for vault operations)
 - A running Orbinum node (Substrate WebSocket endpoint)
-- An EVM JSON-RPC endpoint (optional, required for EVM and precompile operations)
+- An EVM JSON-RPC endpoint (optional — required for EVM and precompile operations)
 
 ## Quick Start
 
@@ -29,8 +29,8 @@ const client = await OrbinumClient.connect({
 });
 
 const chainInfo = await client.substrate.getChainInfo();
-const root = await client.rpcV2.privacy.getMerkleRoot();
-const events = await client.substrate.queryBlockEvents('0xabc...');
+const root      = await client.rpcV2.privacy.getMerkleRoot();
+const events    = await client.substrate.queryBlockEvents('0xabc...');
 ```
 
 `OrbinumClient` wires together the SDK surface under a single interface.
@@ -64,42 +64,6 @@ await provider.connect();
 const client = provider.client; // OrbinumClient once connected
 ```
 
-## rpc-v2
-
-Orbinum's `rpc-v2` is organized by namespace.
-
-- Standard Frontier namespaces: `eth_*`, `net_*`, `web3_*`, `txpool_*`, `debug_*`
-- Orbinum-specific namespace: `privacy_*`
-
-In the SDK, `rpc-v2` is modeled as a dedicated top-level module, exposed through `client.rpcV2`. Each namespace lives under `src/rpc-v2/`.
-
-Current typed coverage:
-
-- `client.rpcV2.privacy.getMerkleRoot()`
-- `client.rpcV2.privacy.getMerkleProof(leafIndex)`
-- `client.rpcV2.privacy.getNullifierStatus(nullifier)`
-- `client.rpcV2.privacy.getPoolStats()`
-
-Example:
-
-```ts
-const root = await client.rpcV2.privacy.getMerkleRoot();
-
-const proof = await client.rpcV2.privacy.getMerkleProof(12);
-// { path: string[]; leafIndex: number; treeDepth: number; }
-
-const status = await client.rpcV2.privacy.getNullifierStatus('0x...');
-// { nullifier: string; isSpent: boolean; }
-
-const stats = await client.rpcV2.privacy.getPoolStats();
-// { merkleRoot: string; commitmentCount: number; totalBalance: string; ... }
-```
-
-Notes:
-
-- `rpc-v2` responses use `snake_case` from the node; the SDK normalizes them to `camelCase`.
-- `u128` values are exposed as decimal strings to avoid precision loss.
-
 ## Modules
 
 ### SubstrateClient
@@ -131,8 +95,8 @@ substrate.blocks$.subscribe(block => console.log(block.number));
 const result = await substrate.request('system_name', []);
 
 // Transaction helpers
-const tx        = await substrate.txFromCallData(callBytes);
-const finalized = await tx.signAndSubmit(signer);
+const tx         = await substrate.txFromCallData(callBytes);
+const finalized  = await tx.signAndSubmit(signer);
 const finalized2 = await substrate.submit(signedHex);
 substrate.submitAndWatch(signedHex).subscribe(event => console.log(event));
 ```
@@ -173,6 +137,26 @@ const logs  = await explorer.getLogs({ fromBlock: 100, toBlock: 200, address: '0
 
 Types: `EvmBlock`, `EvmTransaction`, `EvmAddressInfo`, `EvmTxSummary`, `EvmLog`, `TokenInfo`, `TokenTransfer`.
 
+### rpc-v2 / PrivacyModule
+
+Orbinum's `rpc-v2` is organized by namespace. In the SDK, it is exposed through `client.rpcV2`.
+
+```ts
+const root   = await client.rpcV2.privacy.getMerkleRoot();
+const proof  = await client.rpcV2.privacy.getMerkleProof(12);
+// { path: string[]; leafIndex: number; treeDepth: number; }
+
+const status = await client.rpcV2.privacy.getNullifierStatus('0x...');
+// { nullifier: string; isSpent: boolean; }
+
+const stats  = await client.rpcV2.privacy.getPoolStats();
+// { merkleRoot: string; commitmentCount: number; totalBalance: string; ... }
+```
+
+Notes:
+- `rpc-v2` responses use `snake_case` from the node; the SDK normalizes them to `camelCase`.
+- `u128` values are exposed as decimal strings to avoid precision loss.
+
 ### ZkVerifierModule
 
 Typed access to the on-chain ZK verifier — circuit version info, VK hashes, and version history.
@@ -180,8 +164,7 @@ Typed access to the on-chain ZK verifier — circuit version info, VK hashes, an
 ```ts
 import { ZkVerifierModule } from '@orbinum/sdk';
 
-const zkv = new ZkVerifierModule(substrate);
-
+const zkv     = new ZkVerifierModule(substrate);
 const info    = await zkv.getCircuitVersionInfo('circuit-id');
 const vkHash  = await zkv.getVkHash('circuit-id', 1);
 const stats   = await zkv.getVersionStats('circuit-id');
@@ -190,401 +173,198 @@ const history = await zkv.getHistoricalVersions('circuit-id');
 
 ### ShieldedPoolModule
 
-High-level interface for shielded pool extrinsics and note workflows. Requires a loaded `PrivacyKeyManager` and ZK proofs for unshield and private transfer.
+High-level interface for shielded pool extrinsics. Transactions are built via polkadot-api's UnsafeApi (metadata-driven). Unshield and private transfer are submitted as **unsigned (gasless)** transactions by default — the fee is embedded in the ZK proof.
 
 ```ts
-// Shield (deposit) tokens into the shielded pool
-const { txResult, note } = await client.shieldedPool.buildAndShield({
-    amount: 1_000_000n,
-    assetId: 1,
-    tokenAddress: '0xTokenAddress',
-}, signer);
+import { ShieldedPoolModule } from '@orbinum/sdk';
 
-// Private transfer between notes
-await client.shieldedPool.privateTransfer({ ...params }, signer);
+const pool = new ShieldedPoolModule(substrate);
 
-// Unshield (withdraw) tokens to a public address
-await client.shieldedPool.unshield({ ...params }, signer);
-```
+// Deposit tokens into the shielded pool (signed)
+await pool.shield(params, signer);
 
-### PrivacyModule (`rpc-v2`)
+// Withdraw tokens via ZK proof (unsigned, gasless)
+await pool.unshield(params);
 
-Typed wrapper for Orbinum `privacy_*` endpoints from `rpc-v2`.
+// Private transfer between shielded addresses (unsigned, gasless)
+await pool.privateTransfer(params);
 
-```ts
-import { PrivacyModule } from '@orbinum/sdk';
+// Batch shield
+await pool.shieldBatch(params, signer);
 
-const privacy = new PrivacyModule(substrate);
+// Claim accumulated relayer fees
+await pool.claimShieldedFees(params, signer);
 
-const merkleRoot  = await privacy.getMerkleRoot();
-const merkleProof = await privacy.getMerkleProof(4);
-const nullifier   = await privacy.getNullifierStatus('0xNullifier');
-const stats       = await privacy.getPoolStats();
+// Selective disclosure
+await pool.requestDisclosure(args, signer);
+await pool.disclose(args, signer);
+await pool.rejectDisclosure(args, signer);
 ```
 
-### Privacy Keys
-
-Key derivation follows a deterministic chain from the user's wallet signature. No key material is ever stored by the SDK.
-
-```ts
-import {
-    PrivacyKeyManager,
-    deriveOwnerPk,
-    deriveSpendingKeyFromSignature,
-    deriveSpendingKeyMessage,
-    deriveViewingKey,
-} from '@orbinum/sdk';
-
-const message    = deriveSpendingKeyMessage(chainId, evmAddress);
-const spendingKey = deriveSpendingKeyFromSignature(sigHex, chainId, evmAddress);
+### NoteBuilder
 
-const keyManager = new PrivacyKeyManager();
-keyManager.load(spendingKey);
+Builds ZK notes (commitment + nullifier + encrypted memo) off-chain, with optional stealth address support. No network calls are made.
 
-const viewingKey = deriveViewingKey(spendingKey);
-const ownerPk    = deriveOwnerPk(spendingKey);
+Hash scheme:
 ```
-
-### AccountMappingModule
-
-Manage on-chain identity by linking Substrate and EVM accounts, registering aliases, and interacting with the alias marketplace.
-
-```ts
-await client.accountMapping.registerAlias({ alias: 'myalias' }, signer);
-await client.accountMapping.addChainLink({ chainId: 1, address: '0xEvmAddr' }, signer);
-
-const alias  = await client.accountMapping.getAliasOf(substrateHex);
-const linked = await client.accountMapping.getChainLinks(substrateHex);
+commitment = Poseidon4(value, assetId, ownerPk, blinding)
+nullifier  = Poseidon2(commitment, spendingKey)
 ```
 
-### IndexerClient
-
-HTTP client for the Orbinum indexer REST API. All list endpoints are paginated.
-
 ```ts
-import { IndexerClient } from '@orbinum/sdk';
-
-const indexer = new IndexerClient({ baseUrl: 'https://indexer.orbinum.io' });
-
-const blocks      = await indexer.getBlocks({ page: 1, limit: 20 });
-const extrinsics  = await indexer.getExtrinsics({ address: '5F...' });
-const commitments = await indexer.getCommitments({ page: 1, limit: 20 });
-const nullifier   = await indexer.getNullifierStatus('0xNullifier');
-const roots       = await indexer.getMerkleRoots({ limit: 10 });
-const evmTxs      = await indexer.getEvmTransactions({ address: '0xabc...' });
-const stats       = await indexer.getStats();
+import { NoteBuilder } from '@orbinum/sdk';
+
+const note = await NoteBuilder.build({
+    value:   1_000_000n,
+    assetId: 0n,
+    ownerPk: myOwnerPk,
+    viewingPublicKey: recipientViewingPk,
+    // Optional: provide recipientOwnerPk to derive a per-note stealthOwnerPk
+    recipientOwnerPk: recipientOwnerPk,
+});
+// note.commitmentHex, note.nullifierHex, note.encryptedMemo
 ```
 
-### Precompiles
+When `recipientOwnerPk` is provided, the commitment uses a fresh `stealthOwnerPk` derived from an ephemeral ECDH key, making each transfer unlinkable even when the same privacy address is reused.
 
-Typed wrappers for Orbinum's EVM precompile contracts.
+### NoteDecryptor
 
-| Precompile | Address | Description |
-|---|---|---|
-| `ShieldedPoolPrecompile` | `0x0801` | Shield, unshield, and private transfer from EVM |
-| `AccountMappingPrecompile` | `0x0800` | Identity and alias operations from EVM |
-| `CryptoPrecompiles` | `0x0400–0x0403` | Frontier crypto utilities |
+Scans on-chain commitments and attempts to decrypt them using the viewer's viewing key.
 
 ```ts
-import { ShieldedPoolPrecompile, decodePrecompileCalldata } from '@orbinum/sdk';
-
-const precompile = new ShieldedPoolPrecompile(evmClient);
-await precompile.shield(amount, tokenAddress, commitment, walletSigner);
-
-// Decode raw EVM calldata for a known precompile
-const decoded = decodePrecompileCalldata('0x0800', calldata);
-```
-
-## Extrinsic & Event Decoders
-
-The `mapExtrinsicArgs` and `mapZkEventData` helpers decode raw pallet call data from the indexer or block scanner into typed objects.
+import { tryDecryptNote, tryDecryptNoteVerbose, computeNullifier } from '@orbinum/sdk';
 
-```ts
-import { mapExtrinsicArgs, mapZkEventData } from '@orbinum/sdk';
+// Returns a ZkNote on success, null on key mismatch or commitment failure
+const note = tryDecryptNote(commitment, viewingSecretKey, spendingKey, ownOwnerPk);
 
-const decoded = mapExtrinsicArgs('shieldedPool', 'shield', rawArgs);
-// DecodedShieldArgs | DecodedUnshieldArgs | ...
+// Returns the note plus a human-readable failure reason (useful for debugging)
+const { note, reason } = tryDecryptNoteVerbose(commitment, viewingSecretKey, spendingKey, ownOwnerPk);
 
-const eventData = mapZkEventData('ProofVerified', rawEventData);
+// Compute nullifier directly
+const nullifier = computeNullifier(commitmentBigint, spendingKey);
 ```
 
-## Substrate SCALE Primitives
-
-SCALE codec primitives from `@polkadot-api/substrate-bindings` are re-exported directly from the SDK. There is no need to install that package separately.
+`ScanCommitment` shape: `{ commitmentHex: string; leafIndex: number; encryptedMemo: string | null }`.
 
-```ts
-import { Blake2256, AccountId, u128, u64, Storage, Keccak256 } from '@orbinum/sdk';
-import { base58, getSs58AddressInfo } from '@orbinum/sdk';
-```
-
-## Key Derivation Chain
-
-```
-wallet.sign(message)
-        |
-        v
-deriveSpendingKeyFromSignature()   -- HKDF-SHA256 over signature bytes, mod BN254_R
-        |
-        +-- deriveViewingKey()     -- HKDF-SHA256 -> 32-byte ChaCha20 symmetric key
-        |                             (used to encrypt/decrypt note memos)
-        |
-        +-- deriveOwnerPk()        -- BabyJubJub scalar multiplication -> Ax
-                                      (embedded in shielded note commitments)
-```
-
-## Development
-
-### Typing Layout
-
-The SDK organizes types by feature ownership.
-
-- `types/index.ts`: public shared types of the feature
-- `types/pallet-events.ts`: event payloads and discriminated unions for that pallet
-- `types/pallet-extrinsics.ts`: extrinsic argument types and call unions for that pallet
-- `types/raw.ts`: internal node or RPC response shapes used only for transport mapping
-
-Examples:
-
-- `src/shielded-pool/types/index.ts`
-- `src/shielded-pool/types/pallet-events.ts`
-- `src/shielded-pool/types/pallet-extrinsics.ts`
-- `src/rpc-v2/types/raw.ts`
-- `src/indexer/types/index.ts`
-- `src/account-mapping/types/index.ts`
-
-Rules:
-
-1. If a type is part of the public API of a feature, keep it in that feature's `types/index.ts`.
-2. If a type only mirrors a transport payload from RPC, keep it in `types/raw.ts`.
-3. Do not reintroduce a global `src/types.ts` or `src/types/` directory.
-4. Export public types from `src/index.ts`, but keep ownership at the feature level.
-
-### Extending `rpc-v2`
-
-The intended extension pattern is namespace-oriented and centralized under `RpcV2Module`.
-
-For example, to add `net_*` support:
-
-1. Create `src/rpc-v2/NetModule.ts`
-2. Define raw response types that match the node's JSON exactly
-3. Map raw `snake_case` or hex-shaped values into stable SDK-facing TypeScript types
-4. Export the module from `src/rpc-v2/index.ts`
-5. Attach it in `RpcV2Module`, for example as `client.rpcV2.net`
-6. Add unit tests that verify RPC method names, params, and response mapping
-
-```ts
-export class NetModule {
-    constructor(private readonly substrate: SubstrateClient) {}
-
-    async version(): Promise<string> {
-        return this.substrate.request<string>('net_version', []);
-    }
-}
-```
+### EncryptedMemo
 
-### Commands
+All memos attached to shielded notes are exactly **168 bytes** (ChaCha20-Poly1305 with ECDH ephemeral key):
 
-```bash
-pnpm install
-pnpm build          # compile to dist/ (ESM + CJS + types)
-pnpm test           # run test suite (769 tests)
-pnpm typecheck:all  # typecheck src and tests
-pnpm lint           # eslint
-pnpm format         # prettier
 ```
-
-## License
-
-ISC
-
-
-## Installation
-
-```bash
-npm install @orbinum/sdk
-# or
-pnpm add @orbinum/sdk
+nonce(12) || ciphertext+MAC(124) || ephPk(32) = 168 bytes
 ```
 
-## Requirements
-
-- Node.js 18 or later
-- A running Orbinum node (Substrate WebSocket endpoint)
-- An EVM JSON-RPC endpoint (optional, required for EVM and precompile operations)
-
-## Quick Start
-
 ```ts
-import { OrbinumClient } from '@orbinum/sdk';
+import { EncryptedMemo, ENCRYPTED_MEMO_SIZE } from '@orbinum/sdk';
+// ENCRYPTED_MEMO_SIZE === 168
 
-const client = await OrbinumClient.connect({
-    substrateWs: 'ws://localhost:9944',
-    evmRpc: 'http://localhost:9933',
-});
+const memo      = await EncryptedMemo.encrypt(payload, recipientViewingPk, commitment);
+const decrypted = await EncryptedMemo.decrypt(memoBytes, viewingSecretKey, commitment);
 
-const chainInfo = await client.substrate.getChainInfo();
-const root = await client.rpcV2.privacy.getMerkleRoot();
-const tree = await client.shieldedPool.merkle.getTreeInfo();
+// Validation is called automatically inside ShieldedPoolModule and ShieldedPoolPrecompile.
+// It can also be called explicitly:
+EncryptedMemo.validate(memoBytes, 'my-context'); // throws if length !== 168
 ```
 
-`OrbinumClient` wires together the current SDK surface under a single interface.
-
-- `client.substrate`: Substrate WebSocket RPC and transaction helpers
-- `client.evm`: EVM JSON-RPC client, or `null` if `evmRpc` was not configured
-- `client.rpcV2`: typed Orbinum `rpc-v2` namespaces
-- `client.shieldedPool`: shielded-pool extrinsics, note helpers, and Merkle queries
-- `client.accountMapping`: alias, chain-link, metadata, and marketplace operations
-- `client.precompiles`: EVM precompile wrappers, or `null` if `evmRpc` was not configured
-
-Each module can also be instantiated independently.
-
-## rpc-v2
-
-Orbinum's `rpc-v2` is organized by namespace.
-
-- Standard Frontier namespaces: `eth_*`, `net_*`, `web3_*`, `txpool_*`, `debug_*`
-- Orbinum-specific namespace: `privacy_*`
-
-In the SDK, `rpc-v2` is modeled as a dedicated top-level module, exposed through `client.rpcV2`. Each namespace lives under `src/rpc-v2/` and is grouped there instead of being mixed into legacy protocol modules.
-
-Current typed coverage:
-
-- `client.rpcV2.privacy.getMerkleRoot()`
-- `client.rpcV2.privacy.getMerkleProof(leafIndex)`
-- `client.rpcV2.privacy.getNullifierStatus(nullifier)`
-- `client.rpcV2.privacy.getPoolStats()`
-
-Example:
+### Coin Selection
 
 ```ts
-const root = await client.rpcV2.privacy.getMerkleRoot();
+import { selectNotes, buildDummyTransferInput } from '@orbinum/sdk';
 
-const proof = await client.rpcV2.privacy.getMerkleProof(12);
-// {
-//   path: string[];
-//   leafIndex: number;
-//   treeDepth: number;
-// }
+// Select up to 2 unspent notes covering `needed` planck.
+// Priority: single note first, then smallest qualifying pair.
+const selected = selectNotes(myNotes, needed);
+// [ZkNote, ZkNote | null] | null
 
-const status = await client.rpcV2.privacy.getNullifierStatus('0x...');
-// {
-//   nullifier: string;
-//   isSpent: boolean;
-// }
-
-const stats = await client.rpcV2.privacy.getPoolStats();
-// {
-//   merkleRoot: string;
-//   commitmentCount: number;
-//   totalBalance: string;
-//   assetBalances: { assetId: number; balance: string }[];
-//   treeDepth: number;
-// }
+// Build a zero-value dummy second input for single-note private transfers.
+// The circuit exempts inputs with value == 0 from Merkle membership and EdDSA checks.
+const dummy = buildDummyTransferInput(assetId);
 ```
 
-Notes:
+### Proof Generator
 
-- `rpc-v2` responses from the node use `snake_case`; the SDK maps them to `camelCase`.
-- `u128` values are exposed as decimal strings to avoid precision loss in JavaScript.
-- Privacy queries belong to `client.rpcV2.privacy.*`; they are no longer described as part of `ShieldedPoolModule`.
-
-## Modules
-
-### SubstrateClient
-
-Thin wrapper over [polkadot-api](https://github.com/polkadot-api/polkadot-api) (PAPI) for Substrate WebSocket communication.
+Wrappers around `@orbinum/proof-generator` for generating Groth16 ZK proofs. The `ArtifactProvider` controls where circuit `.wasm` and `.zkey` files are loaded from — use `WebArtifactProvider` in browser environments.
 
 ```ts
-import { SubstrateClient } from '@orbinum/sdk';
-
-const substrate = await SubstrateClient.connect('ws://localhost:9944');
-
-const info = await substrate.getChainInfo();
-const health = await substrate.getHealth();
-const version = await substrate.getNodeVersion();
-const genesis = await substrate.getGenesisHash();
+import {
+    generateUnshieldProof,
+    generateTransferProof,
+    generateFeeClaimProof,
+    WebArtifactProvider,
+} from '@orbinum/sdk';
 
-// Raw JSON-RPC call
-const result = await substrate.request('system_name', []);
+const provider = new WebArtifactProvider('/circuits');
 
-// Build a transaction from pre-encoded SCALE call bytes
-const tx = await substrate.txFromCallData(callBytes);
-const finalized = await tx.signAndSubmit(signer);
+// Unshield proof
+const result = await generateUnshieldProof({
+    merkleRoot, nullifier, amount, assetId, recipient,
+    blinding, spendingKey, pathSiblings, leafIndex,
+    fee: 0n,          // optional gasless fee
+    changeValue: 0n,  // optional change note value
+}, provider);
+// result.proof, result.publicSignals, result.changeCommitment
 
-// Submit a pre-signed extrinsic
-const finalized = await substrate.submit(signedHex);
+// Private transfer proof (exactly 2 inputs and 2 outputs)
+const txProof = await generateTransferProof({
+    merkleRoot,
+    inputs:  [inputNote1, inputNote2],   // use buildDummyTransferInput for single-note transfers
+    outputs: [outputNote1, outputNote2],
+    fee: 0n,
+}, provider);
 
-// Submit and observe lifecycle events
-substrate.submitAndWatch(signedHex).subscribe(event => console.log(event));
+// Fee-claim proof
+const feeProof = await generateFeeClaimProof({
+    amount, assetId, ownerPubkey, blinding, commitment,
+}, provider);
+// feeProof.proof (128-byte 0x-prefixed hex), feeProof.publicSignals (76-byte number[])
 ```
 
-### EvmClient
+### RelayerStatusModule
 
-Stateless HTTP client following the Ethereum JSON-RPC specification.
+Typed client for `relayer_*` JSON-RPC endpoints.
 
 ```ts
-import { EvmClient } from '@orbinum/sdk';
+import { RelayerStatusModule } from '@orbinum/sdk';
 
-const evm = new EvmClient('http://localhost:9933');
-
-const balance = await evm.getBalance('0xYourAddress');
-const chainId = await evm.getChainId();
-const txHash = await evm.sendRawTransaction(signedHex);
+const relayer = new RelayerStatusModule(substrate);
 
-// Batch multiple calls in a single HTTP request
-const [balance, nonce] = await evm.batchRequest([
-    { method: 'eth_getBalance', params: ['0xAddr', 'latest'] },
-    { method: 'eth_getTransactionCount', params: ['0xAddr', 'latest'] },
-]);
+const isRelayer  = await relayer.isRelayer(ss58Address);
+const pending    = await relayer.pendingFees(ss58Address, assetId); // bigint
+const evmAddress = await relayer.registeredEvmAddress(ss58Address); // string | null
+const info       = await relayer.getRelayerInfo(ss58Address);
+// { isRelayer: boolean; evmAddress: string | null }
 ```
 
-### RpcV2Module
+### Vault
 
-Top-level typed entry point for Orbinum `rpc-v2` namespaces.
+AES-GCM-256 encrypted local note storage. Works in browser (WebCrypto) and Node.js 18+.
 
-```ts
-const root = await client.rpcV2.privacy.getMerkleRoot();
-const proof = await client.rpcV2.privacy.getMerkleProof(4);
-const nullifier = await client.rpcV2.privacy.getNullifierStatus('0xNullifier');
-const stats = await client.rpcV2.privacy.getPoolStats();
-```
-
-### ShieldedPoolModule
-
-High-level interface for shielded pool extrinsics and note workflows. Requires a loaded `PrivacyKeyManager` and ZK proofs for unshield and private transfer.
+Key derivation uses HKDF-SHA-256 over 32-byte master material derived **before** modular reduction, so the vault key remains stable across circuit field changes.
 
 ```ts
-// Shield (deposit) tokens into the shielded pool
-const { txResult, note } = await client.shieldedPool.buildAndShield({
-    amount: 1_000_000n,
-    assetId: 1,
-    tokenAddress: '0xTokenAddress',
-}, signer);
+import {
+    deriveVaultKey,
+    encryptNote,
+    decryptNoteRecord,
+    applyNoteStatus,
+    VaultLockedError,
+} from '@orbinum/sdk';
 
-const treeInfo = await client.shieldedPool.merkle.getTreeInfo();
+// Derive the vault encryption key from master key bytes (pre-modulus)
+const vaultKey = await deriveVaultKey(masterBytes);
 
-// Private transfer between notes
-await client.shieldedPool.privateTransfer({ ...params }, signer);
+// Encrypt a ZkNote into an EncryptedNoteRecord
+const record = await encryptNote(vaultKey, zkNote);
+// { commitmentHex, iv, ciphertext, nullifierHex, assetId, spent?, updatedAt }
 
-// Unshield (withdraw) tokens to a public address
-await client.shieldedPool.unshield({ ...params }, signer);
+// Decrypt
+const note = await decryptNoteRecord(vaultKey, record); // ZkNote
 
+// Update spent status without re-encrypting the full ciphertext
+const updated = applyNoteStatus(record, { spent: true, spentAt: Date.now() });
 ```
 
-### PrivacyModule (`rpc-v2`)
-
-Typed wrapper for Orbinum `privacy_*` endpoints from `rpc-v2`.
-
-```ts
-import { PrivacyModule } from '@orbinum/sdk';
-
-const privacy = new PrivacyModule(client.substrate);
-
-const merkleRoot = await privacy.getMerkleRoot();
-const merkleProof = await privacy.getMerkleProof(4);
-const nullifier = await privacy.getNullifierStatus('0xNullifier');
-const stats = await privacy.getPoolStats();
-```
+The `nullifierHex` and `assetId` fields are stored unencrypted so the host application can perform spent-checks and asset filtering without unlocking the vault.
 
 ### Privacy Keys
 
@@ -599,20 +379,14 @@ import {
     deriveViewingKey,
 } from '@orbinum/sdk';
 
-// 1. Get the message the user must sign
-const message = deriveSpendingKeyMessage(chainId, evmAddress);
-
-// 2. Derive the spending key from the wallet signature
+const message     = deriveSpendingKeyMessage(chainId, evmAddress);
 const spendingKey = deriveSpendingKeyFromSignature(sigHex, chainId, evmAddress);
 
-// 3. Load into the key manager
 const keyManager = new PrivacyKeyManager();
 keyManager.load(spendingKey);
 
-// The manager derives the viewing key (ChaCha20 memo decryption)
-// and owner public key (BabyJubJub, used in note commitments)
 const viewingKey = deriveViewingKey(spendingKey);
-const ownerPk = deriveOwnerPk(spendingKey);
+const ownerPk    = deriveOwnerPk(spendingKey);
 ```
 
 ### AccountMappingModule
@@ -620,50 +394,67 @@ const ownerPk = deriveOwnerPk(spendingKey);
 Manage on-chain identity by linking Substrate and EVM accounts, registering aliases, and interacting with the alias marketplace.
 
 ```ts
-// Register an alias
 await client.accountMapping.registerAlias({ alias: 'myalias' }, signer);
-
-// Link an EVM address to a Substrate account
 await client.accountMapping.addChainLink({ chainId: 1, address: '0xEvmAddr' }, signer);
 
-// Query
-const alias = await client.accountMapping.getAliasOf(substrateHex);
+const alias  = await client.accountMapping.getAliasOf(substrateHex);
 const linked = await client.accountMapping.getChainLinks(substrateHex);
 ```
 
 ### IndexerClient
 
-HTTP client for the Orbinum indexer REST API. The indexer runs as a separate service indexed from node events.
+HTTP client for the Orbinum indexer REST API. All list endpoints are paginated.
 
 ```ts
 import { IndexerClient } from '@orbinum/sdk';
 
-const indexer = new IndexerClient({
-    baseUrl: 'https://indexer.orbinum.io',
-});
+const indexer = new IndexerClient({ baseUrl: 'https://indexer.orbinum.io' });
 
+const blocks      = await indexer.getBlocks({ page: 1, limit: 20 });
+const extrinsics  = await indexer.getExtrinsics({ address: '5F...' });
 const commitments = await indexer.getCommitments({ page: 1, limit: 20 });
-const status      = await indexer.getNullifierStatus('0xNullifier');
+const nullifier   = await indexer.getNullifierStatus('0xNullifier');
 const roots       = await indexer.getMerkleRoots({ limit: 10 });
-const extrinsics  = await indexer.getAddressExtrinsics('5F...');
 const evmTxs      = await indexer.getEvmTransactions({ address: '0xabc...' });
+const stats       = await indexer.getStats();
 ```
 
 ### Precompiles
 
-Typed wrappers for Orbinum's EVM precompile contracts, callable from any EVM wallet or signer.
+Typed wrappers for Orbinum's EVM precompile contracts.
 
 | Precompile | Address | Description |
 |---|---|---|
 | `ShieldedPoolPrecompile` | `0x0801` | Shield, unshield, and private transfer from EVM |
 | `AccountMappingPrecompile` | `0x0800` | Identity and alias operations from EVM |
-| `CryptoPrecompiles` | `0x0400–0x0403` | Frontier crypto utilities (SHA3, EC recover, Curve25519) |
+| `CryptoPrecompiles` | `0x0400–0x0403` | Frontier crypto utilities |
 
 ```ts
-import { ShieldedPoolPrecompile } from '@orbinum/sdk';
+import { ShieldedPoolPrecompile, decodePrecompileCalldata } from '@orbinum/sdk';
 
 const precompile = new ShieldedPoolPrecompile(evmClient);
 await precompile.shield(amount, tokenAddress, commitment, walletSigner);
+
+// Decode raw EVM calldata for a known precompile
+const decoded = decodePrecompileCalldata('0x0800', calldata);
+```
+
+### Extrinsic & Event Decoders
+
+```ts
+import { mapExtrinsicArgs, mapZkEventData } from '@orbinum/sdk';
+
+const decoded   = mapExtrinsicArgs('shieldedPool', 'shield', rawArgs);
+const eventData = mapZkEventData('ProofVerified', rawEventData);
+```
+
+### Substrate SCALE Primitives
+
+SCALE codec primitives from `@polkadot-api/substrate-bindings` are re-exported directly. There is no need to install that package separately.
+
+```ts
+import { Blake2256, AccountId, u128, u64, Storage, Keccak256 } from '@orbinum/sdk';
+import { base58, getSs58AddressInfo } from '@orbinum/sdk';
 ```
 
 ## Key Derivation Chain
@@ -672,76 +463,59 @@ await precompile.shield(amount, tokenAddress, commitment, walletSigner);
 wallet.sign(message)
         |
         v
-deriveSpendingKeyFromSignature()   -- HKDF-SHA256 over signature bytes, mod BN254_R
+deriveSpendingKeyFromSignature()     HKDF-SHA256 over signature bytes, mod BN254_R
+        |
+        +-- deriveViewingKey()       HKDF-SHA256 → 32-byte ChaCha20 symmetric key
+        |                            Used to encrypt/decrypt note memos (EncryptedMemo)
         |
-        +-- deriveViewingKey()     -- HKDF-SHA256 -> 32-byte ChaCha20 symmetric key
-        |                             (used to encrypt/decrypt note memos)
+        +-- deriveOwnerPk()          BabyJubJub scalar multiplication → Ax
+        |                            Embedded in note commitments: Poseidon4(v, a, ownerPk, b)
         |
-        +-- deriveOwnerPk()        -- BabyJubJub scalar multiplication -> Ax
-                                      (embedded in shielded note commitments)
+        +-- deriveVaultKey()         HKDF-SHA256 (pre-modulus bytes) → AES-GCM-256 key
+                                     Stable across circuit field changes
 ```
 
+### Stealth Addresses
+
+When a sender builds a note for a recipient, a per-note stealth `ownerPk` is derived:
+
+```
+ephSk          ← random scalar
+sharedSecret   ← ECDH(ephSk, recipientViewingPk)
+stealthScalar  ← HKDF-SHA256(sharedSecret, salt=ownerPk_LE, info="orbinum-stealth-v1") % suborder
+stealthOwnerPk ← stealthScalar × Base8 + ownerPkPoint
+```
+
+The recipient recovers the stealth spending key:
+
+```
+stealthSk ← (stealthScalar + spendingKey) % BABYJUB_SUBORDER
+```
+
+Each received note has a unique `stealthOwnerPk`, making transfers unlinkable even when the same privacy address is reused. The ZK circuit validates ownership without modification because `BabyPbk(stealthSk).Ax == stealthOwnerPk`.
+
 ## Development
 
-### Typing Layout
+### Type Layout
 
 The SDK organizes types by feature ownership.
 
 - `types/index.ts`: public shared types of the feature
-- `types/pallet-events.ts`: event payloads and discriminated unions for that pallet
-- `types/pallet-extrinsics.ts`: extrinsic argument types and call unions for that pallet
+- `types/pallet-events.ts`: event payloads and discriminated unions
+- `types/pallet-extrinsics.ts`: extrinsic argument types and call unions
 - `types/raw.ts`: internal node or RPC response shapes used only for transport mapping
 
-Examples:
-
-- `src/shielded-pool/types/index.ts`
-- `src/shielded-pool/types/pallet-events.ts`
-- `src/shielded-pool/types/pallet-extrinsics.ts`
-- `src/rpc-v2/types/raw.ts`
-- `src/indexer/types/index.ts`
-- `src/precompiles/types/index.ts`
-
 Rules:
-
-1. If a type is part of the public API of a feature, keep it in that feature's `types/index.ts`.
-2. If a type only mirrors a transport payload from RPC, keep it in `types/raw.ts`.
+1. Public types belong in the feature's `types/index.ts`.
+2. Transport-only types belong in `types/raw.ts`.
 3. Do not reintroduce a global `src/types.ts` or `src/types/` directory.
-4. Export public types from `src/index.ts`, but keep ownership at the feature level.
+4. Export public types from `src/index.ts`, keeping ownership at the feature level.
 
 ### Extending `rpc-v2`
 
-The intended extension pattern is namespace-oriented and centralized under `RpcV2Module`.
-
-For example, to add `net_*` support:
-
-1. Create `src/rpc-v2/NetModule.ts`
-2. Define raw response types that match the node's JSON exactly
-3. Map raw `snake_case` or hex-shaped values into stable SDK-facing TypeScript types
-4. Export the module from `src/rpc-v2/index.ts`
-5. Attach it in `RpcV2Module`, for example as `client.rpcV2.net`
-6. Add unit tests that verify RPC method names, params, and response mapping
+Add a new namespace by creating `src/rpc-v2/NetModule.ts`, defining raw response types, mapping them to SDK-facing types, and attaching the module in `RpcV2Module`. Add unit tests verifying RPC method names, params, and response mapping.
 
-Minimal shape example:
-
-```ts
-export class NetModule {
-    constructor(private readonly substrate: SubstrateClient) {}
-
-    async version(): Promise<string> {
-        return this.substrate.request<string>('net_version', []);
-    }
-
-    async peerCount(): Promise<string> {
-        return this.substrate.request<string>('net_peerCount', []);
-    }
-
-    async listening(): Promise<boolean> {
-        return this.substrate.request<boolean>('net_listening', []);
-    }
-}
-```
-
-The same approach applies to `web3_*`, `txpool_*`, `eth_*`, and any future Orbinum-specific namespaces.
+### Commands
 
 ```bash
 pnpm install