@orbinum/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,2397 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AccountMappingModule: () => AccountMappingModule,
+  AccountMappingPrecompile: () => AccountMappingPrecompile,
+  ChainModule: () => ChainModule,
+  CryptoPrecompiles: () => CryptoPrecompiles,
+  EncryptedMemo: () => EncryptedMemo,
+  EvmClient: () => EvmClient,
+  MerkleModule: () => MerkleModule,
+  NoteBuilder: () => NoteBuilder,
+  OrbinumClient: () => OrbinumClient,
+  PRECOMPILE_ADDR: () => PRECOMPILE_ADDR,
+  PrivacyKeyManager: () => PrivacyKeyManager,
+  SLIP0044_NAMESPACE: () => SLIP0044_NAMESPACE,
+  ShieldedPoolModule: () => ShieldedPoolModule,
+  ShieldedPoolPrecompile: () => ShieldedPoolPrecompile,
+  SubstrateClient: () => SubstrateClient,
+  accountIdHexToSs58: () => accountIdHexToSs58,
+  addressToAccountIdHex: () => addressToAccountIdHex,
+  bigintTo32Be: () => bigintTo32Be,
+  bigintTo32Le: () => bigintTo32Le,
+  bigintTo32LeArr: () => bigintTo32LeArr,
+  bytesToBigintLE: () => bytesToBigintLE,
+  computePathIndices: () => computePathIndices,
+  decryptJson: () => decryptJson,
+  deriveOwnerPk: () => deriveOwnerPk,
+  deriveSpendingKeyFromSignature: () => deriveSpendingKeyFromSignature,
+  deriveSpendingKeyMessage: () => deriveSpendingKeyMessage,
+  deriveVaultKey: () => deriveVaultKey,
+  deriveViewingKey: () => deriveViewingKey,
+  encryptJson: () => encryptJson,
+  ensureHexPrefix: () => ensureHexPrefix,
+  evmAddressToAccountId: () => evmAddressToAccountId,
+  evmToImplicitSubstrate: () => evmToImplicitSubstrate,
+  evmToSubstrate: () => evmToSubstrate,
+  fromHex: () => fromHex,
+  getPolkadotSigner: () => import_signer.getPolkadotSigner,
+  getPolkadotSignerFromPjs: () => import_pjs_signer.getPolkadotSignerFromPjs,
+  implicitSubstrateToEvm: () => implicitSubstrateToEvm,
+  isEvmAddress: () => isEvmAddress,
+  isImplicitEvmAccount: () => isImplicitEvmAccount,
+  isSs58: () => isSs58,
+  isSubstrateAddress: () => isSubstrateAddress,
+  isUnifiedAddress: () => isUnifiedAddress,
+  leHexToBigint: () => leHexToBigint,
+  normalizeEvmAddress: () => normalizeEvmAddress,
+  substrateSs58ToAccountIdHex: () => substrateSs58ToAccountIdHex,
+  substrateToEvm: () => substrateToEvm,
+  toHex: () => toHex,
+  tryDecryptNote: () => tryDecryptNote,
+  vaultReplacer: () => vaultReplacer,
+  vaultReviver: () => vaultReviver
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/substrate/SubstrateClient.ts
+var import_polkadot_api = require("polkadot-api");
+var import_ws_provider = require("polkadot-api/ws-provider");
+var SubstrateClient = class _SubstrateClient {
+  constructor(_papi) {
+    this._papi = _papi;
+  }
+  /**
+   * Connects to the Orbinum node via WebSocket.
+   * Throws if the node does not respond within `timeoutMs`.
+   */
+  static async connect(wsUrl, timeoutMs = 15e3) {
+    const provider = (0, import_ws_provider.getWsProvider)(wsUrl);
+    const papi = (0, import_polkadot_api.createClient)(provider);
+    await Promise.race([
+      papi._request("system_name", []),
+      new Promise(
+        (_, reject) => setTimeout(
+          () => reject(new Error(`Connection timeout (${timeoutMs}ms) to ${wsUrl}`)),
+          timeoutMs
+        )
+      )
+    ]);
+    return new _SubstrateClient(papi);
+  }
+  /**
+   * Performs a raw JSON-RPC request. Use this for custom Orbinum RPCs
+   * (shieldedPool_*, accountMapping_*, privacy_*, etc.).
+   */
+  async request(method, params = []) {
+    return this._papi._request(method, params);
+  }
+  /**
+   * Returns the underlying PolkadotClient instance.
+   * Use for block subscriptions (`blocks$`), raw metadata access, and advanced SCALE operations.
+   */
+  get polkadotClient() {
+    return this._papi;
+  }
+  /**
+   * Returns the PAPI UnsafeApi for dynamic, metadata-driven transaction building.
+   * The first access triggers a metadata fetch from the node.
+   *
+   * Usage:
+   * ```ts
+   * const tx = client.unsafe.tx.shieldedPool.shield(...);
+   * const result = await tx.signAndSubmit(signer);
+   * ```
+   */
+  get unsafe() {
+    return this._papi.getUnsafeApi();
+  }
+  /**
+   * Wraps pre-built SCALE call bytes (from protocol-core TransactionBuilder)
+   * into a PAPI UnsafeTransaction that can be signed and submitted.
+   */
+  async txFromCallData(callData) {
+    return this._papi.getUnsafeApi().txFromCallData(import_polkadot_api.Binary.fromBytes(callData));
+  }
+  /**
+   * Submits a pre-signed extrinsic (hex string) and waits for finalization.
+   */
+  async submit(signedHex) {
+    return this._papi.submit(signedHex);
+  }
+  /**
+   * Submits a pre-signed extrinsic and returns an Observable of tx lifecycle events.
+   * Events: TxSigned → TxBroadcasted → TxBestBlocksState → TxFinalized
+   */
+  submitAndWatch(signedHex) {
+    return this._papi.submitAndWatch(signedHex);
+  }
+  /**
+   * Convenience: wrap raw call bytes and sign+submit in one step.
+   */
+  async signAndSubmit(callData, signer) {
+    const tx = await this.txFromCallData(callData);
+    return tx.signAndSubmit(signer);
+  }
+  /** Closes the WebSocket connection. */
+  destroy() {
+    this._papi.destroy();
+  }
+};
+
+// src/utils/hex.ts
+function toHex(bytes) {
+  return "0x" + Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function fromHex(hex) {
+  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+  if (clean.length % 2 !== 0) {
+    throw new Error(`Invalid hex string \u2014 odd length: "${hex}"`);
+  }
+  const bytes = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    const byte = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+    if (isNaN(byte)) throw new Error(`Invalid hex character at position ${i * 2}`);
+    bytes[i] = byte;
+  }
+  return bytes;
+}
+function ensureHexPrefix(hex) {
+  return hex.startsWith("0x") ? hex : `0x${hex}`;
+}
+function hexToNumber(hex) {
+  return parseInt(hex, 16);
+}
+function hexToBigint(hex) {
+  return BigInt(hex);
+}
+
+// src/evm/EvmClient.ts
+var EvmClient = class {
+  constructor(rpcUrl) {
+    this.rpcUrl = rpcUrl;
+  }
+  /**
+   * Performs a single JSON-RPC call.
+   */
+  async request(method, params = []) {
+    const res = await fetch(this.rpcUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ id: 1, jsonrpc: "2.0", method, params })
+    });
+    if (!res.ok) throw new Error(`EVM HTTP ${res.status}: ${res.statusText}`);
+    const json = await res.json();
+    if (json.error) {
+      throw new Error(`EVM RPC [${json.error.code}]: ${json.error.message}`);
+    }
+    if (json.result === void 0 || json.result === null) {
+      throw new Error(`EVM RPC returned null result for method "${method}"`);
+    }
+    return json.result;
+  }
+  /**
+   * Performs multiple JSON-RPC calls in a single HTTP request (batch).
+   */
+  async batchRequest(calls) {
+    const body = calls.map((c, i) => ({
+      id: i + 1,
+      jsonrpc: "2.0",
+      method: c.method,
+      params: c.params ?? []
+    }));
+    const res = await fetch(this.rpcUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) throw new Error(`EVM HTTP ${res.status}: ${res.statusText}`);
+    const arr = await res.json();
+    arr.sort((a, b) => (a.id ?? 0) - (b.id ?? 0));
+    return arr.map((r) => r.result ?? null);
+  }
+  // ─── Convenience wrappers ─────────────────────────────────────────────────
+  /** Returns the native token balance (in wei) for an EVM address. */
+  async getBalance(address) {
+    const hex = await this.request("eth_getBalance", [address, "latest"]);
+    return hexToBigint(hex);
+  }
+  /** Returns the latest block number. */
+  async getBlockNumber() {
+    const hex = await this.request("eth_blockNumber", []);
+    return hexToNumber(hex);
+  }
+  /** Returns the current chain ID. */
+  async getChainId() {
+    const hex = await this.request("eth_chainId", []);
+    return hexToNumber(hex);
+  }
+  /** Returns the transaction count (nonce) for an EVM address. */
+  async getTransactionCount(address) {
+    const hex = await this.request("eth_getTransactionCount", [address, "latest"]);
+    return hexToNumber(hex);
+  }
+  /** Returns the current gas price in wei. */
+  async getGasPrice() {
+    const hex = await this.request("eth_gasPrice", []);
+    return hexToBigint(hex);
+  }
+  /**
+   * Submits a signed raw transaction. Returns the transaction hash.
+   */
+  async sendRawTransaction(signedHex) {
+    return this.request("eth_sendRawTransaction", [signedHex]);
+  }
+  /**
+   * Executes a read-only call without creating a transaction.
+   */
+  async call(to, data, from) {
+    const txObj = { to, data };
+    if (from) txObj["from"] = from;
+    return this.request("eth_call", [txObj, "latest"]);
+  }
+  /**
+   * Estimates the gas for a transaction.
+   */
+  async estimateGas(params) {
+    const hex = await this.request("eth_estimateGas", [params]);
+    return hexToBigint(hex);
+  }
+  /**
+   * Returns a transaction receipt by hash, or null if not yet mined.
+   */
+  async getTransactionReceipt(txHash) {
+    return this.request("eth_getTransactionReceipt", [txHash]);
+  }
+};
+
+// src/shielded-pool/MerkleModule.ts
+var MerkleModule = class {
+  constructor(substrate) {
+    this.substrate = substrate;
+  }
+  /**
+   * Returns the current Merkle tree state: root, number of leaves, and depth.
+   */
+  async getTreeInfo() {
+    const raw = await this.substrate.request(
+      "shieldedPool_getMerkleTreeInfo",
+      []
+    );
+    return {
+      root: raw.root,
+      treeSize: raw.tree_size,
+      depth: raw.depth
+    };
+  }
+  /**
+   * Returns the Merkle inclusion proof for a leaf at `leafIndex`.
+   */
+  async getProof(leafIndex) {
+    const raw = await this.substrate.request("shieldedPool_getMerkleProof", [
+      leafIndex
+    ]);
+    return {
+      root: raw.root,
+      leafIndex: raw.leaf_index,
+      siblings: raw.siblings
+    };
+  }
+  /**
+   * Returns the Merkle inclusion proof for a given commitment (0x-prefixed hex).
+   * Searches the tree for the commitment and returns its proof.
+   */
+  async getProofByCommitment(commitmentHex) {
+    const raw = await this.substrate.request("shieldedPool_getMerkleProof", [
+      commitmentHex
+    ]);
+    return {
+      root: raw.root,
+      leafIndex: raw.leaf_index,
+      siblings: raw.siblings
+    };
+  }
+  /**
+   * Returns the current Merkle root without fetching the full tree info.
+   */
+  async getRoot() {
+    const info = await this.getTreeInfo();
+    return info.root;
+  }
+  /**
+   * Returns an array of commitment leaves from index `from` to `to` (inclusive).
+   * Defaults to returning all leaves.
+   */
+  async getLeaves(from = 0, to) {
+    return this.substrate.request("shieldedPool_getMerkleLeaves", [from, to ?? null]);
+  }
+};
+
+// src/shielded-pool/ShieldedPoolModule.ts
+var import_polkadot_api2 = require("polkadot-api");
+
+// src/shielded-pool/EncryptedMemo.ts
+var import_sha2 = require("@noble/hashes/sha2.js");
+var import_chacha = require("@noble/ciphers/chacha.js");
+var import_utils = require("@noble/ciphers/utils.js");
+
+// src/utils/bytes.ts
+function bigintTo32Le(n) {
+  const buf = new Uint8Array(32);
+  let v = n;
+  for (let i = 0; i < 32; i++) {
+    buf[i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+  return buf;
+}
+function bytesToBigintLE(bytes) {
+  let result = 0n;
+  for (let i = bytes.length - 1; i >= 0; i--) {
+    result = result << 8n | BigInt(bytes[i] ?? 0);
+  }
+  return result;
+}
+function bigintTo32Be(n) {
+  const buf = new Uint8Array(32);
+  let v = n;
+  for (let i = 31; i >= 0 && v > 0n; i--) {
+    buf[i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+  return buf;
+}
+function bigintTo32LeArr(n) {
+  const out = new Array(32).fill(0);
+  let v = n;
+  for (let i = 0; i < 32; i++) {
+    out[i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+  return out;
+}
+function computePathIndices(leafIndex, depth) {
+  const indices = [];
+  let idx = leafIndex;
+  for (let i = 0; i < depth; i++) {
+    indices.push(idx & 1);
+    idx >>= 1;
+  }
+  return indices;
+}
+function leHexToBigint(hex) {
+  const h = hex.startsWith("0x") ? hex.slice(2) : hex;
+  const bytes = new Uint8Array(h.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(h.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytesToBigintLE(bytes);
+}
+
+// src/shielded-pool/EncryptedMemo.ts
+var KEY_DOMAIN = new TextEncoder().encode("orbinum-note-encryption-v1");
+var NONCE_SIZE = 12;
+var MEMO_PLAINTEXT_SIZE = 76;
+var ENCRYPTED_MEMO_SIZE = 104;
+function serializeMemo(value, ownerPk, blinding, assetId) {
+  const buf = new Uint8Array(MEMO_PLAINTEXT_SIZE);
+  const view = new DataView(buf.buffer);
+  view.setBigUint64(0, value & 0xffffffffffffffffn, true);
+  buf.set(ownerPk.slice(0, 32), 8);
+  buf.set(blinding.slice(0, 32), 40);
+  view.setUint32(72, assetId >>> 0, true);
+  return buf;
+}
+function deriveEncryptionKey(viewingKey, commitment) {
+  const h = import_sha2.sha256.create();
+  h.update(viewingKey);
+  h.update(commitment);
+  h.update(KEY_DOMAIN);
+  return h.digest();
+}
+var EncryptedMemo = {
+  /**
+   * Build and encrypt a memo for a note.
+   *
+   * @param value       Note value in planck.
+   * @param ownerPk     32-byte owner public key (little-endian).
+   * @param blinding    32-byte blinding scalar (little-endian).
+   * @param assetId     Asset identifier.
+   * @param commitment  32-byte commitment bytes (little-endian).
+   * @param recipientVk 32-byte recipient viewing key — pass `new Uint8Array(32)`
+   *                    for a publicly-readable (dummy) memo.
+   * @returns 104-byte encrypted memo (nonce || ciphertext).
+   */
+  encrypt(value, ownerPk, blinding, assetId, commitment, recipientVk) {
+    const nonce = (0, import_utils.randomBytes)(NONCE_SIZE);
+    const key = deriveEncryptionKey(recipientVk, commitment);
+    const plaintext = serializeMemo(value, ownerPk, blinding, assetId);
+    const cipher = (0, import_chacha.chacha20poly1305)(key, nonce);
+    const ciphertext = cipher.encrypt(plaintext);
+    const result = new Uint8Array(NONCE_SIZE + ciphertext.length);
+    result.set(nonce, 0);
+    result.set(ciphertext, NONCE_SIZE);
+    return result;
+  },
+  /**
+   * Returns a 104-byte public memo with a zero recipient viewing key.
+   * The memo is still readable by anyone who holds the viewing key (zeros).
+   */
+  encryptPublic(value, ownerPk, blinding, assetId, commitment) {
+    return EncryptedMemo.encrypt(
+      value,
+      ownerPk,
+      blinding,
+      assetId,
+      commitment,
+      new Uint8Array(32)
+    );
+  },
+  /**
+   * Returns a 104-byte zeroed dummy memo (no information, always valid on-chain).
+   */
+  dummy() {
+    return new Uint8Array(ENCRYPTED_MEMO_SIZE);
+  },
+  /**
+   * Decrypt an on-chain EncryptedMemo.
+   *
+   * Returns `null` if decryption fails — wrong key, bad MAC, or malformed memo.
+   * Never throws; safe for scan loops.
+   *
+   * @param memoBytes   104-byte encrypted memo.
+   * @param commitment  32-byte note commitment (little-endian).
+   * @param recipientVk 32-byte recipient viewing key.
+   */
+  decrypt(memoBytes, commitment, recipientVk) {
+    if (memoBytes.length !== ENCRYPTED_MEMO_SIZE) return null;
+    try {
+      const nonce = memoBytes.slice(0, NONCE_SIZE);
+      const ciphertext = memoBytes.slice(NONCE_SIZE);
+      const key = deriveEncryptionKey(recipientVk, commitment);
+      const cipher = (0, import_chacha.chacha20poly1305)(key, nonce);
+      const plaintext = cipher.decrypt(ciphertext);
+      const view = new DataView(plaintext.buffer, plaintext.byteOffset, plaintext.byteLength);
+      const value = view.getBigUint64(0, true);
+      const ownerPk = bytesToBigintLE(plaintext.slice(8, 40));
+      const blinding = bytesToBigintLE(plaintext.slice(40, 72));
+      const assetId = BigInt(view.getUint32(72, true));
+      return { value, ownerPk, blinding, assetId };
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/shielded-pool/NoteBuilder.ts
+var import_poseidon_lite = require("poseidon-lite");
+var NoteBuilder = class {
+  /**
+   * Build a ZkNote from the given inputs.
+   *
+   * @param input.value       Amount in planck (required).
+   * @param input.assetId     Asset ID — default 0n (native ORB-Privacy).
+   * @param input.ownerPk     BabyJubJub Ax — default 0n.
+   * @param input.blinding    Random scalar — defaults to BigInt(Date.now()).
+   * @param input.spendingKey Secret key for nullifier — default 0n.
+   */
+  static async build(input) {
+    const value = input.value;
+    const assetId = input.assetId ?? 0n;
+    const ownerPk = input.ownerPk ?? 0n;
+    const blinding = input.blinding ?? BigInt(Date.now());
+    const spendingKey = input.spendingKey ?? 0n;
+    const commitment = (0, import_poseidon_lite.poseidon4)([value, assetId, ownerPk, blinding]);
+    const nullifier = (0, import_poseidon_lite.poseidon2)([commitment, spendingKey]);
+    const commitmentBytes = bigintTo32Le(commitment);
+    const nullifierBytes = bigintTo32Le(nullifier);
+    const memo = input.viewingKey !== void 0 ? Array.from(
+      EncryptedMemo.encrypt(
+        value,
+        bigintTo32Le(ownerPk),
+        bigintTo32Le(blinding),
+        Number(assetId),
+        commitmentBytes,
+        input.viewingKey
+      )
+    ) : Array.from(EncryptedMemo.dummy());
+    const note = {
+      value,
+      assetId,
+      ownerPk,
+      blinding,
+      spendingKey,
+      spent: false,
+      spentAt: null,
+      commitment,
+      nullifier,
+      commitmentHex: toHex(commitmentBytes),
+      nullifierHex: toHex(nullifierBytes),
+      memo
+    };
+    return note;
+  }
+  /**
+   * Build the 104-byte encrypted memo for a note.
+   *
+   * Pure TypeScript implementation — no WASM dependency.
+   * Uses ChaCha20-Poly1305 with SHA-256 key derivation.
+   *
+   * @param note         The ZkNote whose fields populate the plaintext.
+   * @param recipientVk  32-byte recipient viewing key.
+   *                     Pass `new Uint8Array(32)` (default) for a public/dummy memo.
+   */
+  static buildMemo(note, recipientVk) {
+    return EncryptedMemo.encrypt(
+      note.value,
+      bigintTo32Le(note.ownerPk),
+      bigintTo32Le(note.blinding),
+      Number(note.assetId),
+      bigintTo32Le(note.commitment),
+      recipientVk ?? new Uint8Array(32)
+    );
+  }
+};
+
+// src/shielded-pool/ShieldedPoolModule.ts
+function toTxResult(payload) {
+  const base = {
+    txHash: payload.txHash,
+    blockHash: payload.block.hash,
+    blockNumber: payload.block.number,
+    ok: payload.ok
+  };
+  if (!payload.ok) {
+    return { ...base, error: payload.dispatchError.type };
+  }
+  return base;
+}
+function callUnsafeTx(txEntry, ...args) {
+  return txEntry(...args);
+}
+function resolveTx(unsafe, pallet, call) {
+  const u = unsafe;
+  const p = u["tx"]?.[pallet];
+  if (p === void 0) throw new Error(`Pallet "${pallet}" not found in runtime metadata`);
+  const entry = p[call];
+  if (entry === void 0)
+    throw new Error(`Call "${pallet}.${call}" not found in runtime metadata`);
+  return entry;
+}
+var ShieldedPoolModule = class {
+  constructor(substrate, merkle) {
+    this.substrate = substrate;
+    this.merkle = merkle;
+  }
+  // ─── Extrinsics ────────────────────────────────────────────────────────────
+  /**
+   * Deposits tokens into the shielded pool.
+   * Extrinsic: shieldedPool.shield(assetId, amount, commitment, encryptedMemo)
+   */
+  async shield(params, signer) {
+    const memo = params.encryptedMemo ?? EncryptedMemo.dummy();
+    const entry = resolveTx(this.substrate.unsafe, "shieldedPool", "shield");
+    const tx = callUnsafeTx(
+      entry,
+      params.assetId,
+      params.amount.toString(),
+      import_polkadot_api2.Binary.fromHex(params.commitment),
+      import_polkadot_api2.Binary.fromBytes(memo)
+    );
+    return toTxResult(await tx.signAndSubmit(signer));
+  }
+  /**
+   * Build a ZkNote locally and submit shieldedPool.shield in one call.
+   *
+   * Returns both the on-chain result and the note — **save the note locally**,
+   * it cannot be recovered after the fact.
+   *
+   * @param params.value       Amount in planck (required).
+   * @param params.assetId     Asset ID — default 0 (native ORB-Privacy).
+   * @param params.ownerPk     BabyJubJub Ax (default 0n).
+   * @param params.blinding    Random blinding scalar (default BigInt(Date.now())).
+   * @param params.spendingKey Secret spending key (default 0n).
+   */
+  async buildAndShield(params, signer) {
+    const noteInput = {
+      value: params.value,
+      ...params.assetId !== void 0 && { assetId: BigInt(params.assetId) },
+      ...params.ownerPk !== void 0 && { ownerPk: params.ownerPk },
+      ...params.blinding !== void 0 && { blinding: params.blinding },
+      ...params.spendingKey !== void 0 && { spendingKey: params.spendingKey }
+    };
+    const note = await NoteBuilder.build(noteInput);
+    const memo = NoteBuilder.buildMemo(note);
+    const txResult = await this.shield(
+      {
+        assetId: Number(note.assetId),
+        amount: note.value,
+        commitment: note.commitmentHex,
+        encryptedMemo: memo
+      },
+      signer
+    );
+    return { txResult, note };
+  }
+  /**
+   * Withdraws tokens from the shielded pool to a public address.
+   * Extrinsic: shieldedPool.unshield(proof, merkleRoot, nullifier, assetId, amount, recipient)
+   */
+  async unshield(params, signer) {
+    const entry = resolveTx(this.substrate.unsafe, "shieldedPool", "unshield");
+    const tx = callUnsafeTx(
+      entry,
+      import_polkadot_api2.Binary.fromBytes(params.proof),
+      import_polkadot_api2.Binary.fromHex(params.merkleRoot),
+      import_polkadot_api2.Binary.fromHex(params.nullifier),
+      params.assetId,
+      params.amount.toString(),
+      import_polkadot_api2.Binary.fromHex(params.recipientAddress)
+    );
+    return toTxResult(await tx.signAndSubmit(signer));
+  }
+  /**
+   * Performs a private (shielded) transfer between two notes.
+   * Extrinsic: shieldedPool.privateTransfer(inputs, outputs, proof, merkleRoot)
+   */
+  async privateTransfer(params, signer) {
+    const inputs = params.inputs.map((inp) => ({
+      nullifier: import_polkadot_api2.Binary.fromHex(inp.nullifier),
+      commitment: import_polkadot_api2.Binary.fromHex(inp.commitment)
+    }));
+    const outputs = params.outputs.map((out) => ({
+      commitment: import_polkadot_api2.Binary.fromHex(out.commitment),
+      memo: import_polkadot_api2.Binary.fromBytes(out.encryptedMemo ?? EncryptedMemo.dummy())
+    }));
+    const entry = resolveTx(this.substrate.unsafe, "shieldedPool", "privateTransfer");
+    const tx = callUnsafeTx(
+      entry,
+      inputs,
+      outputs,
+      import_polkadot_api2.Binary.fromBytes(params.proof),
+      import_polkadot_api2.Binary.fromHex(params.merkleRoot)
+    );
+    return toTxResult(await tx.signAndSubmit(signer));
+  }
+  // ─── Queries ───────────────────────────────────────────────────────────────
+  /** Returns whether a nullifier has already been spent. */
+  async isNullifierSpent(nullifierHex) {
+    const raw = await this.substrate.request(
+      "privacy_getNullifierStatus",
+      [nullifierHex]
+    );
+    return raw.is_spent;
+  }
+  /** Returns the full nullifier status object. */
+  async getNullifierStatus(nullifierHex) {
+    const raw = await this.substrate.request(
+      "privacy_getNullifierStatus",
+      [nullifierHex]
+    );
+    return { nullifier: raw.nullifier, isSpent: raw.is_spent };
+  }
+  /** Returns the total locked balance in the pool for a given asset. */
+  async getPoolBalance(assetId) {
+    const raw = await this.substrate.request(
+      "shieldedPool_getPoolBalance",
+      [assetId]
+    );
+    return { assetId, balance: BigInt(raw.balance) };
+  }
+  /**
+   * Returns Merkle tree info and pool balance for a given asset in a single call.
+   * Convenience wrapper used by both `app` and `privacy-explorer`.
+   */
+  async getPoolStats(assetId = 0) {
+    const [merkle, balance] = await Promise.all([
+      this.merkle.getTreeInfo(),
+      this.getPoolBalance(assetId)
+    ]);
+    return { merkle, balance };
+  }
+};
+
+// src/utils/address.ts
+var import_util_crypto = require("@polkadot/util-crypto");
+function normalizeEvmAddress(addr) {
+  const hex = addr.startsWith("0x") ? addr.slice(2) : addr;
+  return "0x" + hex.toLowerCase();
+}
+function isSs58(addr) {
+  return !addr.startsWith("0x") && addr.length >= 46 && addr.length <= 50;
+}
+function isEvmAddress(addr) {
+  return /^0x[0-9a-fA-F]{40}$/.test(addr);
+}
+function evmAddressToAccountId(evmAddr) {
+  const clean = evmAddr.startsWith("0x") ? evmAddr.slice(2) : evmAddr;
+  if (clean.length !== 40) {
+    throw new Error(`Expected 20-byte EVM address, got: ${evmAddr}`);
+  }
+  const bytes = new Uint8Array(32);
+  for (let i = 0; i < 20; i++) {
+    bytes[i + 12] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+function evmToImplicitSubstrate(evmAddr) {
+  const clean = evmAddr.startsWith("0x") ? evmAddr.slice(2) : evmAddr;
+  if (clean.length !== 40) {
+    throw new Error(`Expected 20-byte EVM address, got: ${evmAddr}`);
+  }
+  return "0x" + clean.toLowerCase() + "0".repeat(24);
+}
+function isImplicitEvmAccount(accountHex) {
+  const clean = accountHex.startsWith("0x") ? accountHex.slice(2) : accountHex;
+  if (clean.length !== 64) return false;
+  return clean.slice(40).toLowerCase() === "0".repeat(24);
+}
+function implicitSubstrateToEvm(accountHex) {
+  if (!isImplicitEvmAccount(accountHex)) {
+    throw new Error(`AccountId32 is not an implicit EVM-derived account: ${accountHex}`);
+  }
+  const clean = accountHex.startsWith("0x") ? accountHex.slice(2) : accountHex;
+  return "0x" + clean.slice(0, 40).toLowerCase();
+}
+var ACCOUNT_ID_BYTES = 32;
+var EVM_BYTES = 20;
+function isSubstrateAddress(addr) {
+  if (!addr || typeof addr !== "string" || isEvmAddress(addr)) return false;
+  if (addr.length < 40 || addr.length > 60) return false;
+  try {
+    const bytes = (0, import_util_crypto.decodeAddress)(addr);
+    return bytes.length === ACCOUNT_ID_BYTES;
+  } catch {
+    return false;
+  }
+}
+function isUnifiedAddress(addr) {
+  if (!addr || isEvmAddress(addr)) return false;
+  try {
+    const bytes = (0, import_util_crypto.decodeAddress)(addr);
+    if (bytes.length !== ACCOUNT_ID_BYTES) return false;
+    return bytes.slice(EVM_BYTES, ACCOUNT_ID_BYTES).every((b) => b === 0);
+  } catch {
+    return false;
+  }
+}
+function substrateToEvm(addr) {
+  if (!addr) return null;
+  if (isEvmAddress(addr)) return normalizeEvmAddress(addr);
+  try {
+    const bytes = (0, import_util_crypto.decodeAddress)(addr);
+    if (bytes.length !== ACCOUNT_ID_BYTES) return null;
+    const isUnified = bytes.slice(EVM_BYTES, ACCOUNT_ID_BYTES).every((b) => b === 0);
+    if (!isUnified) return null;
+    return "0x" + Array.from(bytes.slice(0, EVM_BYTES)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  } catch {
+    return null;
+  }
+}
+function evmToSubstrate(addr) {
+  const normalized = normalizeEvmAddress(addr);
+  if (!normalized) return null;
+  const hex = normalized.slice(2);
+  if (hex.length !== 40) return null;
+  const mapped = new Uint8Array(ACCOUNT_ID_BYTES);
+  for (let i = 0; i < EVM_BYTES; i++) {
+    mapped[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  try {
+    return (0, import_util_crypto.encodeAddress)(mapped);
+  } catch {
+    return null;
+  }
+}
+function accountIdHexToSs58(hex) {
+  if (!hex) return null;
+  try {
+    const h = hex.startsWith("0x") ? hex.slice(2) : hex;
+    if (h.length !== 64) return null;
+    const bytes = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+      bytes[i] = parseInt(h.slice(i * 2, i * 2 + 2), 16);
+    }
+    return (0, import_util_crypto.encodeAddress)(bytes);
+  } catch {
+    return null;
+  }
+}
+function substrateSs58ToAccountIdHex(addr) {
+  if (!addr) return null;
+  try {
+    const bytes = (0, import_util_crypto.decodeAddress)(addr);
+    if (bytes.length !== ACCOUNT_ID_BYTES) return null;
+    return "0x" + Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+  } catch {
+    return null;
+  }
+}
+function addressToAccountIdHex(addr) {
+  if (!addr) return null;
+  if (isEvmAddress(addr)) {
+    const hex = addr.startsWith("0x") ? addr.slice(2) : addr;
+    const mapped = new Uint8Array(ACCOUNT_ID_BYTES);
+    for (let i = 0; i < EVM_BYTES; i++) {
+      mapped[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return "0x" + Array.from(mapped).map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  if (/^0x[0-9a-fA-F]{64}$/.test(addr)) {
+    return addr.toLowerCase();
+  }
+  return substrateSs58ToAccountIdHex(addr);
+}
+
+// src/chain/ChainModule.ts
+var ChainModule = class {
+  constructor(substrate, evm) {
+    this.substrate = substrate;
+    this.evm = evm;
+  }
+  // ─── Node info ─────────────────────────────────────────────────────────────
+  /**
+   * Returns basic chain information from the node.
+   */
+  async getChainInfo() {
+    const [name, version] = await Promise.all([
+      this.substrate.request("system_name", []),
+      this.substrate.request("state_getRuntimeVersion", [])
+    ]);
+    return {
+      name,
+      version: String(version.specVersion),
+      ss58Prefix: version.ss58Prefix ?? 42
+    };
+  }
+  /**
+   * Returns the node's peer count and sync status.
+   */
+  async getHealth() {
+    return this.substrate.request("system_health", []);
+  }
+  /**
+   * Returns the node's software version string.
+   */
+  async getNodeVersion() {
+    return this.substrate.request("system_version", []);
+  }
+  /**
+   * Returns the genesis hash hex.
+   */
+  async getGenesisHash() {
+    return this.substrate.request("chain_getBlockHash", [0]);
+  }
+  // ─── Account mapping ───────────────────────────────────────────────────────
+  /**
+   * Resolves the full identity (Substrate + EVM addresses, alias) for an account.
+   * Accepts an EVM address (0x...) or a Substrate account hex (0x...32bytes).
+   */
+  async getFullIdentity(address) {
+    try {
+      const raw = await this.substrate.request(
+        "accountMapping_resolveFullIdentity",
+        [address]
+      );
+      return {
+        substrateAddress: raw.substrate_address ?? null,
+        evmAddress: raw.evm_address ? normalizeEvmAddress(raw.evm_address) : null,
+        alias: raw.alias ?? null
+      };
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Returns the mapped Substrate account hex for a given EVM address, or null.
+   */
+  async getMappedAccountByEvm(evmAddress) {
+    try {
+      return await this.substrate.request("accountMapping_getMappedAccount", [
+        normalizeEvmAddress(evmAddress)
+      ]);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Returns the alias registered for a Substrate account, or null.
+   */
+  async getAliasOf(accountHex) {
+    try {
+      return await this.substrate.request("accountMapping_getAliasOf", [
+        accountHex
+      ]);
+    } catch {
+      return null;
+    }
+  }
+  // ─── EVM helpers ───────────────────────────────────────────────────────────
+  /**
+   * Returns estimated EVM chain ID from the EVM RPC endpoint. Requires evmRpc
+   * to have been provided in `OrbinumClientConfig`.
+   */
+  async getEvmChainId() {
+    if (!this.evm)
+      throw new Error("No EVM RPC URL configured. Set evmRpc in OrbinumClientConfig.");
+    return this.evm.getChainId();
+  }
+  /**
+   * Returns the current EVM block number.
+   */
+  async getEvmBlockNumber() {
+    if (!this.evm) throw new Error("No EVM RPC URL configured.");
+    return this.evm.getBlockNumber();
+  }
+};
+
+// src/account-mapping/AccountMappingModule.ts
+var import_polkadot_api3 = require("polkadot-api");
+function toTxResult2(payload) {
+  const base = {
+    txHash: payload.txHash,
+    blockHash: payload.block.hash,
+    blockNumber: payload.block.number,
+    ok: payload.ok
+  };
+  if (!payload.ok) {
+    return { ...base, error: payload.dispatchError.type };
+  }
+  return base;
+}
+function callUnsafeTx2(txEntry, ...args) {
+  return txEntry(...args);
+}
+function resolveTx2(unsafe, pallet, call) {
+  const u = unsafe;
+  const p = u["tx"]?.[pallet];
+  if (p === void 0) throw new Error(`Pallet "${pallet}" not found in runtime metadata`);
+  const entry = p[call];
+  if (entry === void 0)
+    throw new Error(`Call "${pallet}.${call}" not found in runtime metadata`);
+  return entry;
+}
+function mapRawScheme(raw) {
+  if (raw === "Eip191" || raw === "eip191") return "Eip191";
+  if (raw === "Ed25519" || raw === "ed25519") return "Ed25519";
+  return raw;
+}
+var AccountMappingModule = class {
+  constructor(substrate) {
+    this.substrate = substrate;
+  }
+  // ─── Address resolution ─────────────────────────────────────────────────────
+  /**
+   * Returns the explicitly mapped (or fallback) Substrate AccountId32 hex for
+   * an EVM address. `mapped` is set only when `map_account` was called.
+   * `fallback` is always the EeSuffix rule: `H160 ++ [0x00; 12]`.
+   */
+  async getAccountAddresses(accountId) {
+    try {
+      const raw = await this.substrate.request(
+        "accountMapping_getAccountAddresses",
+        [accountId]
+      );
+      return { mapped: raw.mapped ?? null, fallback: raw.fallback ?? null };
+    } catch {
+      return { mapped: null, fallback: null };
+    }
+  }
+  /**
+   * Returns the explicitly mapped Substrate AccountId32 hex for a given EVM
+   * address, or null if no explicit mapping exists.
+   */
+  async getMappedAccount(evmAddress) {
+    try {
+      return await this.substrate.request("accountMapping_getMappedAccount", [
+        normalizeEvmAddress(evmAddress)
+      ]);
+    } catch {
+      return null;
+    }
+  }
+  // ─── Alias queries ──────────────────────────────────────────────────────────
+  /**
+   * Resolves "@alias" to basic info (owner, optional EVM address, link count).
+   * Accepts the alias with or without the leading "@".
+   */
+  async resolveAlias(alias) {
+    try {
+      const raw = await this.substrate.request(
+        "accountMapping_resolveAlias",
+        [alias]
+      );
+      if (!raw) return null;
+      return {
+        owner: raw.substrate_account,
+        evmAddress: raw.evm_address ? normalizeEvmAddress(raw.evm_address) : null,
+        chainLinksCount: raw.chain_links_count
+      };
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Returns the alias registered for the given Substrate AccountId32 hex, or null.
+   */
+  async getAliasOf(accountId) {
+    try {
+      return await this.substrate.request("accountMapping_getAliasOf", [
+        accountId
+      ]);
+    } catch {
+      return null;
+    }
+  }
+  // ─── Full identity ──────────────────────────────────────────────────────────
+  /**
+   * Resolves "@alias" to its full identity: owner, EVM address, all public
+   * chain links, and profile metadata.
+   */
+  async resolveFullIdentity(alias) {
+    try {
+      const raw = await this.substrate.request(
+        "accountMapping_resolveFullIdentity",
+        [alias]
+      );
+      if (!raw) return null;
+      return {
+        owner: raw.owner,
+        evmAddress: raw.evm_address ? normalizeEvmAddress(raw.evm_address) : null,
+        chainLinks: raw.chain_links.map((l) => ({
+          chainId: l.chain_id,
+          address: l.address
+        })),
+        metadata: raw.metadata ? {
+          displayName: raw.metadata.display_name ?? null,
+          bio: raw.metadata.bio ?? null,
+          avatar: raw.metadata.avatar ?? null
+        } : null
+      };
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Returns the profile metadata for a given Substrate AccountId32 hex, or null.
+   */
+  async getAccountMetadata(accountId) {
+    try {
+      const raw = await this.substrate.request(
+        "accountMapping_getAccountMetadata",
+        [accountId]
+      );
+      if (!raw) return null;
+      return {
+        displayName: raw.display_name ?? null,
+        bio: raw.bio ?? null,
+        avatar: raw.avatar ?? null
+      };
+    } catch {
+      return null;
+    }
+  }
+  // ─── Chain links ────────────────────────────────────────────────────────────
+  /**
+   * Returns the owner AccountId32 hex of a verified multichain link, or null.
+   */
+  async getLinkOwner(chainId, address) {
+    try {
+      return await this.substrate.request("accountMapping_getLinkOwner", [
+        chainId,
+        address
+      ]);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Returns all blockchain networks supported for verified cross-chain links.
+   */
+  async getSupportedChains() {
+    try {
+      const raw = await this.substrate.request(
+        "accountMapping_getSupportedChains",
+        []
+      );
+      return raw.map(([chainId, scheme]) => ({
+        chainId,
+        scheme: mapRawScheme(scheme)
+      }));
+    } catch {
+      return [];
+    }
+  }
+  // ─── Private links ──────────────────────────────────────────────────────────
+  /**
+   * Returns the private link commitments registered for an alias.
+   * Real addresses are never exposed. Returns null if the alias does not exist.
+   */
+  async getPrivateLinks(alias) {
+    try {
+      const raw = await this.substrate.request(
+        "accountMapping_getPrivateLinks",
+        [alias]
+      );
+      if (!raw) return null;
+      return raw.map((r) => ({ chainId: r.chain_id, commitment: r.commitment }));
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Returns true if the given commitment is registered as a private link for the alias.
+   */
+  async hasPrivateLink(alias, commitment) {
+    try {
+      return await this.substrate.request("accountMapping_hasPrivateLink", [
+        alias,
+        commitment
+      ]);
+    } catch {
+      return false;
+    }
+  }
+  // ─── Marketplace ────────────────────────────────────────────────────────────
+  /**
+   * Returns listing info if the alias is currently for sale, or null.
+   */
+  async getListingInfo(alias) {
+    try {
+      const raw = await this.substrate.request(
+        "accountMapping_getListingInfo",
+        [alias]
+      );
+      if (!raw) return null;
+      return {
+        price: BigInt(raw.price),
+        private: raw.private,
+        whitelistCount: raw.whitelist_count
+      };
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Returns the alias and its listing if the given account currently has an
+   * alias listed for sale. Returns null otherwise.
+   */
+  async getAccountListing(accountId) {
+    try {
+      const raw = await this.substrate.request(
+        "accountMapping_getAccountListing",
+        [accountId]
+      );
+      if (!raw) return null;
+      return {
+        alias: raw.alias,
+        listing: {
+          price: BigInt(raw.price),
+          private: raw.private,
+          whitelistCount: raw.whitelist_count
+        }
+      };
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Returns whether a specific buyer can purchase the given alias right now.
+   */
+  async canBuy(alias, buyerAccountId) {
+    try {
+      return await this.substrate.request("accountMapping_canBuy", [
+        alias,
+        buyerAccountId
+      ]);
+    } catch {
+      return false;
+    }
+  }
+  // ─── Extrinsics ─────────────────────────────────────────────────────────────
+  /**
+   * Creates an explicit EVM → Substrate account mapping.
+   * Stores an explicit `MappedAccounts` entry for the caller's H160.
+   * Extrinsic: accountMapping.mapAccount()
+   */
+  async mapAccount(signer) {
+    const entry = resolveTx2(this.substrate.unsafe, "accountMapping", "mapAccount");
+    const tx = callUnsafeTx2(entry);
+    return toTxResult2(await tx.signAndSubmit(signer));
+  }
+  /**
+   * Removes the EVM → Substrate mapping for the caller.
+   * Extrinsic: accountMapping.unmapAccount()
+   */
+  async unmapAccount(signer) {
+    const entry = resolveTx2(this.substrate.unsafe, "accountMapping", "unmapAccount");
+    const tx = callUnsafeTx2(entry);
+    return toTxResult2(await tx.signAndSubmit(signer));
+  }
+  /**
+   * Registers a unique @alias for the caller.
+   * Requires a deposit. The alias must be 3–32 ASCII lowercase alphanumeric chars + hyphens.
+   * Extrinsic: accountMapping.registerAlias(alias)
+   */
+  async registerAlias(alias, signer) {
+    const entry = resolveTx2(this.substrate.unsafe, "accountMapping", "registerAlias");
+    const tx = callUnsafeTx2(entry, import_polkadot_api3.Binary.fromText(alias));
+    return toTxResult2(await tx.signAndSubmit(signer));
+  }
+  /**
+   * Releases the caller's alias and recovers the deposit.
+   * Extrinsic: accountMapping.releaseAlias()
+   */
+  async releaseAlias(signer) {
+    const entry = resolveTx2(this.substrate.unsafe, "accountMapping", "releaseAlias");
+    const tx = callUnsafeTx2(entry);
+    return toTxResult2(await tx.signAndSubmit(signer));
+  }
+  /**
+   * Transfers the caller's alias to another account.
+   * Extrinsic: accountMapping.transferAlias(newOwner)
+   */
+  async transferAlias(newOwnerHex, signer) {
+    const entry = resolveTx2(this.substrate.unsafe, "accountMapping", "transferAlias");
+    const tx = callUnsafeTx2(entry, newOwnerHex);
+    return toTxResult2(await tx.signAndSubmit(signer));
+  }
+  /**
+   * Adds a verified public link to an external-chain wallet.
+   *
+   * `params.signature` must be produced by the external wallet over the caller's
+   * AccountId32 bytes:
+   *  - EIP-191 (EVM): sign(keccak256("\x19Ethereum Signed Message:\n32" + accountId32))
+   *  - Ed25519 (Solana): sign(accountId32 bytes)
+   *
+   * Extrinsic: accountMapping.addChainLink(chainId, address, signature)
+   */
+  async addChainLink(params, signer) {
+    const entry = resolveTx2(this.substrate.unsafe, "accountMapping", "addChainLink");
+    const tx = callUnsafeTx2(
+      entry,
+      params.chainId,
+      import_polkadot_api3.Binary.fromBytes(params.address),
+      import_polkadot_api3.Binary.fromBytes(params.signature)
+    );
+    return toTxResult2(await tx.signAndSubmit(signer));
+  }
+  /**
+   * Removes the external-chain link for the given chain ID.
+   * Extrinsic: accountMapping.removeChainLink(chainId)
+   */
+  async removeChainLink(chainId, signer) {
+    const entry = resolveTx2(this.substrate.unsafe, "accountMapping", "removeChainLink");
+    const tx = callUnsafeTx2(entry, chainId);
+    return toTxResult2(await tx.signAndSubmit(signer));
+  }
+  /**
+   * Updates the caller's public profile metadata.
+   * Extrinsic: accountMapping.setAccountMetadata(displayName, bio, avatar)
+   */
+  async setAccountMetadata(params, signer) {
+    const entry = resolveTx2(this.substrate.unsafe, "accountMapping", "setAccountMetadata");
+    const encode2 = (v) => v != null ? import_polkadot_api3.Binary.fromText(v) : void 0;
+    const tx = callUnsafeTx2(
+      entry,
+      encode2(params.displayName),
+      encode2(params.bio),
+      encode2(params.avatar)
+    );
+    return toTxResult2(await tx.signAndSubmit(signer));
+  }
+  /**
+   * Lists the caller's alias for sale on the alias marketplace.
+   * Extrinsic: accountMapping.putAliasOnSale(price, isPrivate)
+   */
+  async putAliasOnSale(params, signer) {
+    const entry = resolveTx2(this.substrate.unsafe, "accountMapping", "putAliasOnSale");
+    const tx = callUnsafeTx2(entry, params.price.toString(), params.isPrivate);
+    return toTxResult2(await tx.signAndSubmit(signer));
+  }
+  /**
+   * Cancels an active alias sale listing.
+   * Extrinsic: accountMapping.cancelSale()
+   */
+  async cancelSale(signer) {
+    const entry = resolveTx2(this.substrate.unsafe, "accountMapping", "cancelSale");
+    const tx = callUnsafeTx2(entry);
+    return toTxResult2(await tx.signAndSubmit(signer));
+  }
+  /**
+   * Purchases an alias listed for sale.
+   * Extrinsic: accountMapping.buyAlias(alias)
+   */
+  async buyAlias(alias, signer) {
+    const entry = resolveTx2(this.substrate.unsafe, "accountMapping", "buyAlias");
+    const tx = callUnsafeTx2(entry, import_polkadot_api3.Binary.fromText(alias));
+    return toTxResult2(await tx.signAndSubmit(signer));
+  }
+  /**
+   * Dispatches an arbitrary call on behalf of a linked external-chain wallet.
+   *
+   * This is the "Universal Proxy" feature that allows EVM/Solana wallets to
+   * authorize on-chain actions without holding a Substrate private key.
+   *
+   * The relayer (who pays gas) calls this with the external wallet's signature
+   * over the encoded call payload and the owner's AccountId32.
+   *
+   * Extrinsic: accountMapping.dispatchAsLinkedAccount(owner, chainId, address, signature, call)
+   */
+  async dispatchAsLinkedAccount(params, signer) {
+    const entry = resolveTx2(this.substrate.unsafe, "accountMapping", "dispatchAsLinkedAccount");
+    const tx = callUnsafeTx2(
+      entry,
+      params.owner,
+      params.chainId,
+      import_polkadot_api3.Binary.fromBytes(params.address),
+      import_polkadot_api3.Binary.fromBytes(params.signature),
+      import_polkadot_api3.Binary.fromBytes(params.callData)
+    );
+    return toTxResult2(await tx.signAndSubmit(signer));
+  }
+};
+
+// src/precompiles/abi.ts
+function concat(arrays) {
+  const total = arrays.reduce((s, a) => s + a.length, 0);
+  const out = new Uint8Array(total);
+  let o = 0;
+  for (const a of arrays) {
+    out.set(a, o);
+    o += a.length;
+  }
+  return out;
+}
+function padTo32Multiple(data) {
+  const rem = data.length % 32;
+  if (rem === 0) return data;
+  const padded = new Uint8Array(data.length + (32 - rem));
+  padded.set(data);
+  return padded;
+}
+var STATIC_TYPES = /* @__PURE__ */ new Set(["uint", "bytes32", "address", "bool"]);
+function encodeStaticParam(param) {
+  const buf = new Uint8Array(32);
+  switch (param.type) {
+    case "uint": {
+      return bigintTo32Be(param.value);
+    }
+    case "bytes32": {
+      buf.set(param.value.slice(0, 32));
+      return buf;
+    }
+    case "address": {
+      const clean = param.value.startsWith("0x") ? param.value.slice(2) : param.value;
+      const bytes = fromHex("0x" + clean.padStart(40, "0"));
+      buf.set(bytes, 12);
+      return buf;
+    }
+    case "bool": {
+      buf[31] = param.value ? 1 : 0;
+      return buf;
+    }
+    default:
+      throw new Error(
+        `encodeStatic: not a static ABI type: ${param.type}`
+      );
+  }
+}
+function encodeDynamicParam(param) {
+  switch (param.type) {
+    case "bytes": {
+      const data = param.value;
+      return concat([bigintTo32Be(BigInt(data.length)), padTo32Multiple(data)]);
+    }
+    case "string": {
+      const data = new TextEncoder().encode(param.value);
+      return concat([bigintTo32Be(BigInt(data.length)), padTo32Multiple(data)]);
+    }
+    case "bytes32[]": {
+      const n = param.value.length;
+      const parts = [bigintTo32Be(BigInt(n))];
+      for (const b32 of param.value) {
+        const slot = new Uint8Array(32);
+        slot.set(b32.slice(0, 32));
+        parts.push(slot);
+      }
+      return concat(parts);
+    }
+    case "address[]": {
+      const n = param.value.length;
+      const parts = [bigintTo32Be(BigInt(n))];
+      for (const addr of param.value) {
+        const slot = new Uint8Array(32);
+        const clean = addr.startsWith("0x") ? addr.slice(2) : addr;
+        const bytes = fromHex("0x" + clean.padStart(40, "0"));
+        slot.set(bytes, 12);
+        parts.push(slot);
+      }
+      return concat(parts);
+    }
+    case "bytes[]": {
+      const n = param.value.length;
+      const offsets = [];
+      const datas = [];
+      let offset = n * 32;
+      for (const item of param.value) {
+        offsets.push(bigintTo32Be(BigInt(offset)));
+        const itemBlock = concat([
+          bigintTo32Be(BigInt(item.length)),
+          padTo32Multiple(item)
+        ]);
+        datas.push(itemBlock);
+        offset += itemBlock.length;
+      }
+      return concat([bigintTo32Be(BigInt(n)), ...offsets, ...datas]);
+    }
+    default:
+      throw new Error(
+        `encodeDynamic: not a dynamic ABI type: ${param.type}`
+      );
+  }
+}
+function encode(selector, ...params) {
+  const n = params.length;
+  const headSize = n * 32;
+  const heads = [];
+  const tails = [];
+  let tailOffset = headSize;
+  for (const param of params) {
+    if (STATIC_TYPES.has(param.type)) {
+      heads.push(encodeStaticParam(param));
+    } else {
+      heads.push(bigintTo32Be(BigInt(tailOffset)));
+      const tail = encodeDynamicParam(param);
+      tails.push(tail);
+      tailOffset += tail.length;
+    }
+  }
+  return concat([selector, ...heads, ...tails]);
+}
+function encodeHex(selector, ...params) {
+  return toHex(encode(selector, ...params));
+}
+function decodeUint(data, offset = 0) {
+  let result = 0n;
+  for (let i = 0; i < 32; i++) {
+    result = result << 8n | BigInt(data[offset + i] ?? 0);
+  }
+  return result;
+}
+function decodeAddress2(data, offset = 0) {
+  return "0x" + toHex(data.slice(offset + 12, offset + 32)).slice(2);
+}
+function decodeBool(data, offset = 0) {
+  return data[offset + 31] !== 0;
+}
+function decodeBytes(data, slotOffset = 0) {
+  const dataOffset = Number(decodeUint(data, slotOffset));
+  const length = Number(decodeUint(data, dataOffset));
+  return data.slice(dataOffset + 32, dataOffset + 32 + length);
+}
+function decodeString(data, slotOffset = 0) {
+  return new TextDecoder().decode(decodeBytes(data, slotOffset));
+}
+function hexToBytes(hex) {
+  if (hex === "0x" || hex === "") return new Uint8Array(0);
+  return fromHex(hex.startsWith("0x") ? hex : "0x" + hex);
+}
+
+// src/precompiles/addresses.ts
+var PRECOMPILE_ADDR = {
+  // ── Ethereum standard (EIP) ─────────────────────────────────────────────
+  EC_RECOVER: "0x0000000000000000000000000000000000000001",
+  SHA256: "0x0000000000000000000000000000000000000002",
+  RIPEMD160: "0x0000000000000000000000000000000000000003",
+  IDENTITY: "0x0000000000000000000000000000000000000004",
+  MODEXP: "0x0000000000000000000000000000000000000005",
+  // ── Frontier / non-standard ─────────────────────────────────────────────
+  SHA3_FIPS256: "0x0000000000000000000000000000000000000400",
+  EC_RECOVER_PUBKEY: "0x0000000000000000000000000000000000000401",
+  CURVE25519_ADD: "0x0000000000000000000000000000000000000402",
+  CURVE25519_SCALAR_MUL: "0x0000000000000000000000000000000000000403",
+  // ── Orbinum custom ───────────────────────────────────────────────────────
+  ACCOUNT_MAPPING: "0x0000000000000000000000000000000000000800",
+  SHIELDED_POOL: "0x0000000000000000000000000000000000000801"
+};
+var AM_SEL = {
+  // ── Read-only ─────────────────────────────────────────────────────────────
+  // resolveAlias(string)                            → 0xd03149ab
+  RESOLVE_ALIAS: new Uint8Array([208, 49, 73, 171]),
+  // getAliasOf(address)                             → 0x7a0ed62c
+  GET_ALIAS_OF: new Uint8Array([122, 14, 214, 44]),
+  // hasPrivateLink(string,bytes32)                  → 0x47e05c6c
+  HAS_PRIVATE_LINK: new Uint8Array([71, 224, 92, 108]),
+  // ── No-argument writes ────────────────────────────────────────────────────
+  // mapAccount()                                    → 0xdca49d0e
+  MAP_ACCOUNT: new Uint8Array([220, 164, 157, 14]),
+  // unmapAccount()                                  → 0x08f57367
+  UNMAP_ACCOUNT: new Uint8Array([8, 245, 115, 103]),
+  // releaseAlias()                                  → 0x7fac359e
+  RELEASE_ALIAS: new Uint8Array([127, 172, 53, 158]),
+  // cancelSale()                                    → 0x4d023ab9
+  CANCEL_SALE: new Uint8Array([77, 2, 58, 185]),
+  // ── Writes with arguments ─────────────────────────────────────────────────
+  // registerAlias(string)                           → 0x2f8839c3
+  REGISTER_ALIAS: new Uint8Array([47, 136, 57, 195]),
+  // transferAlias(address)                          → 0x5ac998e7
+  TRANSFER_ALIAS: new Uint8Array([90, 201, 152, 231]),
+  // buyAlias(string)                                → 0x1625df3a
+  BUY_ALIAS: new Uint8Array([22, 37, 223, 58]),
+  // putAliasOnSale(uint256,address[])               → 0x32091192
+  PUT_ALIAS_ON_SALE: new Uint8Array([50, 9, 17, 146]),
+  // removeChainLink(uint32)                         → 0x6f579c0c
+  REMOVE_CHAIN_LINK: new Uint8Array([111, 87, 156, 12]),
+  // addChainLink(uint32,bytes,bytes)                → 0x5f3e837c
+  ADD_CHAIN_LINK: new Uint8Array([95, 62, 131, 124]),
+  // registerPrivateLink(uint32,bytes32)             → 0xc04e98f4
+  REGISTER_PRIVATE_LINK: new Uint8Array([192, 78, 152, 244]),
+  // removePrivateLink(bytes32)                      → 0xdfd8b57e
+  REMOVE_PRIVATE_LINK: new Uint8Array([223, 216, 181, 126]),
+  // revealPrivateLink(bytes32,bytes,bytes32,bytes)  → 0x4df1f33d
+  REVEAL_PRIVATE_LINK: new Uint8Array([77, 241, 243, 61]),
+  // setAccountMetadata(bytes,bytes,bytes)           → 0x776cf9ff
+  SET_ACCOUNT_METADATA: new Uint8Array([119, 108, 249, 255])
+};
+var SP_SEL = {
+  // shield(uint32,uint256,bytes32,bytes)                                  → 0x781442b9
+  SHIELD: new Uint8Array([120, 20, 66, 185]),
+  // privateTransfer(bytes,bytes32,bytes32[],bytes32[],bytes[])            → 0xdcd5b898
+  PRIVATE_TRANSFER: new Uint8Array([220, 213, 184, 152]),
+  // unshield(bytes,bytes32,bytes32,uint32,uint256,bytes32)                → 0xdcf1bff2
+  UNSHIELD: new Uint8Array([220, 241, 191, 242])
+};
+
+// src/precompiles/ShieldedPoolPrecompile.ts
+var ShieldedPoolPrecompile = class {
+  constructor(evm) {
+    this.evm = evm;
+  }
+  addr = PRECOMPILE_ADDR.SHIELDED_POOL;
+  // ─── shield ────────────────────────────────────────────────────────────────
+  /**
+   * Returns the ABI-encoded calldata for `shield(uint32, uint256, bytes32, bytes)`.
+   * Useful when you need to inspect or batch the calldata before sending.
+   */
+  buildShieldCalldata(params) {
+    const memo = params.encryptedMemo ?? EncryptedMemo.dummy();
+    const commitment = fromHex(params.commitment);
+    return encodeHex(
+      SP_SEL.SHIELD,
+      { type: "uint", value: BigInt(params.assetId) },
+      { type: "uint", value: params.amount },
+      { type: "bytes32", value: commitment },
+      { type: "bytes", value: memo }
+    );
+  }
+  /**
+   * Deposits tokens into the shielded pool from an EVM transaction.
+   *
+   * The EVM caller's address is deterministically mapped to a Substrate
+   * AccountId32 (`H160 ++ [0x00; 12]`). The pool deducts from that account.
+   *
+   * Extrinsic: `shieldedPool.shield(assetId, amount, commitment, encryptedMemo)`
+   */
+  async shield(params, signer) {
+    return signer({ to: this.addr, data: this.buildShieldCalldata(params) });
+  }
+  // ─── privateTransfer ───────────────────────────────────────────────────────
+  /**
+   * Returns the ABI-encoded calldata for
+   * `privateTransfer(bytes, bytes32, bytes32[], bytes32[], bytes[])`.
+   */
+  buildPrivateTransferCalldata(params) {
+    const nullifiers = params.inputs.map((i) => fromHex(i.nullifier));
+    const commitments = params.outputs.map((o) => fromHex(o.commitment));
+    const memos = params.outputs.map((o) => o.encryptedMemo ?? EncryptedMemo.dummy());
+    const root = fromHex(params.merkleRoot);
+    return encodeHex(
+      SP_SEL.PRIVATE_TRANSFER,
+      { type: "bytes", value: params.proof },
+      { type: "bytes32", value: root },
+      { type: "bytes32[]", value: nullifiers },
+      { type: "bytes32[]", value: commitments },
+      { type: "bytes[]", value: memos }
+    );
+  }
+  /**
+   * Submits a private transfer within the shielded pool from an EVM transaction.
+   *
+   * The EVM caller identity is **irrelevant to the ZK proof** — the sender is
+   * hidden by design. Any EVM address (including a relayer) can submit a valid proof.
+   *
+   * Extrinsic: `shieldedPool.privateTransfer(proof, merkleRoot, nullifiers, commitments, memos)`
+   */
+  async privateTransfer(params, signer) {
+    return signer({ to: this.addr, data: this.buildPrivateTransferCalldata(params) });
+  }
+  // ─── unshield ──────────────────────────────────────────────────────────────
+  /**
+   * Params for an `unshield` call via the EVM precompile.
+   * The `recipient` is a full 32-byte AccountId32 (Substrate account or
+   * EeSuffix-derived: `H160 ++ [0x00; 12]`).
+   */
+  buildUnshieldCalldata(params) {
+    const proof = params.proof;
+    const root = fromHex(params.merkleRoot);
+    const nullifier = fromHex(params.nullifier);
+    const recipientRaw = params.recipientAddress.startsWith("0x") ? params.recipientAddress.slice(2) : params.recipientAddress;
+    const recipientBytes = fromHex(
+      "0x" + (recipientRaw.length === 64 ? recipientRaw : recipientRaw.padEnd(64, "0"))
+    );
+    return encodeHex(
+      SP_SEL.UNSHIELD,
+      { type: "bytes", value: proof },
+      { type: "bytes32", value: root },
+      { type: "bytes32", value: nullifier },
+      { type: "uint", value: BigInt(params.assetId) },
+      { type: "uint", value: params.amount },
+      { type: "bytes32", value: recipientBytes }
+    );
+  }
+  /**
+   * Withdraws tokens from the shielded pool to a recipient account.
+   *
+   * `params.recipientAddress` must be a 0x-prefixed 64-hex-char AccountId32.
+   * To send to an EVM address, use `evmToImplicitSubstrate(evmAddr)` from
+   * `@orbinum/sdk` to derive the AccountId32 first.
+   *
+   * Extrinsic: `shieldedPool.unshield(proof, merkleRoot, nullifier, assetId, amount, recipient)`
+   */
+  async unshield(params, signer) {
+    return signer({ to: this.addr, data: this.buildUnshieldCalldata(params) });
+  }
+  // ─── Gas estimation ────────────────────────────────────────────────────────
+  /**
+   * Estimates the EVM gas for a `shield` call without submitting.
+   * Requires `from` to be set to the actual sender address.
+   */
+  async estimateShieldGas(params, from) {
+    return this.evm.estimateGas({
+      from,
+      to: this.addr,
+      data: this.buildShieldCalldata(params)
+    });
+  }
+  /**
+   * Estimates the EVM gas for a `privateTransfer` call.
+   */
+  async estimatePrivateTransferGas(params, from) {
+    return this.evm.estimateGas({
+      from,
+      to: this.addr,
+      data: this.buildPrivateTransferCalldata(params)
+    });
+  }
+  /**
+   * Estimates the EVM gas for an `unshield` call.
+   */
+  async estimateUnshieldGas(params, from) {
+    return this.evm.estimateGas({
+      from,
+      to: this.addr,
+      data: this.buildUnshieldCalldata(params)
+    });
+  }
+};
+
+// src/precompiles/AccountMappingPrecompile.ts
+var AccountMappingPrecompile = class {
+  constructor(evm) {
+    this.evm = evm;
+  }
+  addr = PRECOMPILE_ADDR.ACCOUNT_MAPPING;
+  // ─── Read-only ─────────────────────────────────────────────────────────────
+  /**
+   * Resolves `@alias` to its owner EVM address (and optionally a secondary EVM address).
+   *
+   * Returns `(address owner, address evmAddress)` — two 32-byte ABI-encoded slots.
+   * `evmAddress` is zero-address (`0x000...0`) if the owner has no explicit EVM address.
+   */
+  async resolveAlias(alias) {
+    try {
+      const data = encodeHex(AM_SEL.RESOLVE_ALIAS, { type: "string", value: alias });
+      const raw = hexToBytes(await this.evm.call(this.addr, data));
+      if (raw.length < 64) return null;
+      const owner = decodeAddress2(raw, 0);
+      const evm = decodeAddress2(raw, 32);
+      const ZERO = "0x0000000000000000000000000000000000000000";
+      return {
+        owner,
+        evmAddress: evm === ZERO ? null : normalizeEvmAddress(evm)
+      };
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Returns the alias registered for the given EVM address, or null.
+   * The precompile ABI encodes the alias as `bytes` (UTF-8).
+   */
+  async getAliasOf(evmAddress) {
+    try {
+      const data = encodeHex(AM_SEL.GET_ALIAS_OF, {
+        type: "address",
+        value: normalizeEvmAddress(evmAddress)
+      });
+      const raw = hexToBytes(await this.evm.call(this.addr, data));
+      if (raw.length === 0) return null;
+      const alias = decodeString(raw, 0);
+      return alias.length > 0 ? alias : null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Returns true if the given Poseidon commitment is registered as a private
+   * link for the given alias.
+   */
+  async hasPrivateLink(alias, commitment) {
+    try {
+      const commitmentBytes = fromHex(ensureHexPrefix(commitment));
+      const data = encodeHex(
+        AM_SEL.HAS_PRIVATE_LINK,
+        { type: "string", value: alias },
+        { type: "bytes32", value: commitmentBytes }
+      );
+      const raw = hexToBytes(await this.evm.call(this.addr, data));
+      if (raw.length < 32) return false;
+      return decodeBool(raw, 0);
+    } catch {
+      return false;
+    }
+  }
+  // ─── No-arg writes ─────────────────────────────────────────────────────────
+  /**
+   * Creates an explicit EVM → Substrate account mapping for the signer's address.
+   * Extrinsic: `accountMapping.mapAccount()`
+   */
+  async mapAccount(signer) {
+    return signer({ to: this.addr, data: encodeHex(AM_SEL.MAP_ACCOUNT) });
+  }
+  /**
+   * Removes the EVM → Substrate mapping for the signer's address.
+   * Extrinsic: `accountMapping.unmapAccount()`
+   */
+  async unmapAccount(signer) {
+    return signer({ to: this.addr, data: encodeHex(AM_SEL.UNMAP_ACCOUNT) });
+  }
+  /**
+   * Releases the signer's registered alias, recovering the deposit.
+   * Extrinsic: `accountMapping.releaseAlias()`
+   */
+  async releaseAlias(signer) {
+    return signer({ to: this.addr, data: encodeHex(AM_SEL.RELEASE_ALIAS) });
+  }
+  /**
+   * Cancels an active alias sale listing.
+   * Extrinsic: `accountMapping.cancelSale()`
+   */
+  async cancelSale(signer) {
+    return signer({ to: this.addr, data: encodeHex(AM_SEL.CANCEL_SALE) });
+  }
+  // ─── Writes with arguments ─────────────────────────────────────────────────
+  /**
+   * Registers a unique @alias for the signer's account.
+   * Requires a deposit. The alias must be 3–32 ASCII lowercase alphanumeric chars + hyphens.
+   * Extrinsic: `accountMapping.registerAlias(alias)`
+   */
+  async registerAlias(alias, signer) {
+    const data = encodeHex(AM_SEL.REGISTER_ALIAS, { type: "string", value: alias });
+    return signer({ to: this.addr, data });
+  }
+  /**
+   * Transfers the signer's alias to a new EVM `owner` address.
+   * Extrinsic: `accountMapping.transferAlias(newOwner)`
+   */
+  async transferAlias(newOwnerEvmAddress, signer) {
+    const data = encodeHex(AM_SEL.TRANSFER_ALIAS, {
+      type: "address",
+      value: normalizeEvmAddress(newOwnerEvmAddress)
+    });
+    return signer({ to: this.addr, data });
+  }
+  /**
+   * Purchases an alias currently listed for sale.
+   * Extrinsic: `accountMapping.buyAlias(alias)`
+   */
+  async buyAlias(alias, signer) {
+    const data = encodeHex(AM_SEL.BUY_ALIAS, { type: "string", value: alias });
+    return signer({ to: this.addr, data });
+  }
+  /**
+   * Lists the signer's alias for sale on the alias marketplace.
+   *
+   * @param price          Asking price in planck (ORB).
+   * @param allowedBuyers  Whitelist of EVM addresses allowed to buy.
+   *                       Pass an empty array for a public (open) listing.
+   * Extrinsic: `accountMapping.putAliasOnSale(price, allowedBuyers)`
+   */
+  async putAliasOnSale(price, allowedBuyers, signer) {
+    const data = encodeHex(
+      AM_SEL.PUT_ALIAS_ON_SALE,
+      { type: "uint", value: price },
+      { type: "address[]", value: allowedBuyers.map(normalizeEvmAddress) }
+    );
+    return signer({ to: this.addr, data });
+  }
+  /**
+   * Removes the external-chain link for the given chain ID.
+   * Extrinsic: `accountMapping.removeChainLink(chainId)`
+   */
+  async removeChainLink(chainId, signer) {
+    const data = encodeHex(AM_SEL.REMOVE_CHAIN_LINK, { type: "uint", value: BigInt(chainId) });
+    return signer({ to: this.addr, data });
+  }
+  /**
+   * Adds a verified public link to an external-chain wallet.
+   *
+   * @param chainId       Orbinum chain ID (use `SLIP0044_NAMESPACE | coinType` for SLIP-0044).
+   * @param externalAddr  External wallet address bytes (20 bytes for EVM, 32 for Solana).
+   * @param signature     Signature over the caller's AccountId32:
+   *                        - EIP-191 (EVM): 65 bytes over keccak256("\x19Ethereum Signed Message:\n32" + accountId32)
+   *                        - Ed25519 (Solana): 64 bytes over the raw accountId32 bytes
+   *
+   * Extrinsic: `accountMapping.addChainLink(chainId, address, signature)`
+   */
+  async addChainLink(chainId, externalAddr, signature, signer) {
+    const data = encodeHex(
+      AM_SEL.ADD_CHAIN_LINK,
+      { type: "uint", value: BigInt(chainId) },
+      { type: "bytes", value: externalAddr },
+      { type: "bytes", value: signature }
+    );
+    return signer({ to: this.addr, data });
+  }
+  /**
+   * Registers a private chain link — only the Poseidon commitment is stored.
+   * The real external address is never revealed on-chain.
+   *
+   * @param chainId     External chain ID.
+   * @param commitment  0x-prefixed 32-byte Poseidon commitment hex.
+   *
+   * Extrinsic: `accountMapping.registerPrivateLink(chainId, commitment)`
+   */
+  async registerPrivateLink(chainId, commitment, signer) {
+    const commitmentBytes = fromHex(
+      commitment.startsWith("0x") ? commitment : "0x" + commitment
+    );
+    const data = encodeHex(
+      AM_SEL.REGISTER_PRIVATE_LINK,
+      { type: "uint", value: BigInt(chainId) },
+      { type: "bytes32", value: commitmentBytes }
+    );
+    return signer({ to: this.addr, data });
+  }
+  /**
+   * Removes a private link by its commitment.
+   * Extrinsic: `accountMapping.removePrivateLink(commitment)`
+   */
+  async removePrivateLink(commitment, signer) {
+    const commitmentBytes = fromHex(
+      commitment.startsWith("0x") ? commitment : "0x" + commitment
+    );
+    const data = encodeHex(AM_SEL.REMOVE_PRIVATE_LINK, {
+      type: "bytes32",
+      value: commitmentBytes
+    });
+    return signer({ to: this.addr, data });
+  }
+  /**
+   * Reveals a private link publicly by providing the real address and blinding.
+   * After this call the link becomes a public chain link.
+   *
+   * @param commitment  32-byte commitment hex.
+   * @param address     External address bytes (the actual wallet address).
+   * @param blinding    32-byte blinding factor used when computing the commitment.
+   * @param signature   Signature over the AccountId32 bytes (same rules as `addChainLink`).
+   *
+   * Extrinsic: `accountMapping.revealPrivateLink(commitment, address, blinding, signature)`
+   */
+  async revealPrivateLink(commitment, address, blinding, signature, signer) {
+    const commitmentBytes = fromHex(
+      commitment.startsWith("0x") ? commitment : "0x" + commitment
+    );
+    const blindingBytes = fromHex(blinding.startsWith("0x") ? blinding : "0x" + blinding);
+    const data = encodeHex(
+      AM_SEL.REVEAL_PRIVATE_LINK,
+      { type: "bytes32", value: commitmentBytes },
+      { type: "bytes", value: address },
+      { type: "bytes32", value: blindingBytes },
+      { type: "bytes", value: signature }
+    );
+    return signer({ to: this.addr, data });
+  }
+  /**
+   * Updates the signer's public profile metadata.
+   * Pass `null` for any field to leave it unchanged.
+   *
+   * Extrinsic: `accountMapping.setAccountMetadata(displayName, bio, avatar)`
+   */
+  async setAccountMetadata(displayName, bio, avatar, signer) {
+    const enc = (v) => v != null ? new TextEncoder().encode(v) : new Uint8Array(0);
+    const data = encodeHex(
+      AM_SEL.SET_ACCOUNT_METADATA,
+      { type: "bytes", value: enc(displayName) },
+      { type: "bytes", value: enc(bio) },
+      { type: "bytes", value: enc(avatar) }
+    );
+    return signer({ to: this.addr, data });
+  }
+  // ─── Calldata builders (for custom signing / batching) ─────────────────────
+  /** Returns the raw ABI-encoded calldata for `registerAlias`. */
+  buildRegisterAliasCalldata(alias) {
+    return encodeHex(AM_SEL.REGISTER_ALIAS, { type: "string", value: alias });
+  }
+  /** Returns the raw ABI-encoded calldata for `mapAccount`. */
+  buildMapAccountCalldata() {
+    return encodeHex(AM_SEL.MAP_ACCOUNT);
+  }
+};
+
+// src/precompiles/CryptoPrecompiles.ts
+var CryptoPrecompiles = class {
+  constructor(evm) {
+    this.evm = evm;
+  }
+  // ─── ECRecover (0x0001) ───────────────────────────────────────────────────
+  /**
+   * Recovers the Ethereum address from an ECDSA signature.
+   *
+   * Classic Ethereum ECRecover (EIP-spec): input is always 128 bytes:
+   *   hash(32) + v_padded(32, v=27 or 28) + r(32) + s(32)
+   *
+   * Returns a 0x-prefixed lowercase 20-byte EVM address.
+   */
+  async ecRecover(hash, v, r, s) {
+    const input = new Uint8Array(128);
+    input.set(hash.slice(0, 32), 0);
+    input[63] = v;
+    input.set(r.slice(0, 32), 64);
+    input.set(s.slice(0, 32), 96);
+    const raw = hexToBytes(await this.evm.call(PRECOMPILE_ADDR.EC_RECOVER, toHex(input)));
+    if (raw.length < 32) return "0x" + "00".repeat(20);
+    return "0x" + toHex(raw.slice(12, 32)).slice(2);
+  }
+  /**
+   * Recovers the **full uncompressed public key** (64 bytes, no 0x04 prefix)
+   * from an ECDSA signature.
+   *
+   * Same input format as `ecRecover`. Output is 64 bytes (32-byte X + 32-byte Y).
+   */
+  async ecRecoverPublicKey(hash, v, r, s) {
+    const input = new Uint8Array(128);
+    input.set(hash.slice(0, 32), 0);
+    input[63] = v;
+    input.set(r.slice(0, 32), 64);
+    input.set(s.slice(0, 32), 96);
+    return hexToBytes(await this.evm.call(PRECOMPILE_ADDR.EC_RECOVER_PUBKEY, toHex(input)));
+  }
+  // ─── SHA-256 (0x0002) ─────────────────────────────────────────────────────
+  /**
+   * Computes SHA-256 of arbitrary bytes via EVM precompile.
+   * Returns a 32-byte digest.
+   */
+  async sha256(data) {
+    return hexToBytes(await this.evm.call(PRECOMPILE_ADDR.SHA256, toHex(data)));
+  }
+  // ─── RIPEMD-160 (0x0003) ──────────────────────────────────────────────────
+  /**
+   * Computes RIPEMD-160 of arbitrary bytes via EVM precompile.
+   * Returns the 20-byte digest right-padded to 32 bytes (standard ABI output).
+   */
+  async ripemd160(data) {
+    const raw = hexToBytes(await this.evm.call(PRECOMPILE_ADDR.RIPEMD160, toHex(data)));
+    return raw.length >= 32 ? raw.slice(12, 32) : raw;
+  }
+  // ─── Identity (0x0004) ────────────────────────────────────────────────────
+  /**
+   * Data copy via EVM precompile (identity). Returns the input unchanged.
+   * Mainly useful for gas benchmarking.
+   */
+  async identity(data) {
+    return hexToBytes(await this.evm.call(PRECOMPILE_ADDR.IDENTITY, toHex(data)));
+  }
+  // ─── SHA3-FIPS-256 / Keccak-256 (0x0400) ─────────────────────────────────
+  /**
+   * Computes Keccak-256 (= SHA3-FIPS-256 as used by Ethereum) of arbitrary bytes.
+   * Returns a 32-byte digest.
+   */
+  async keccak256(data) {
+    return hexToBytes(await this.evm.call(PRECOMPILE_ADDR.SHA3_FIPS256, toHex(data)));
+  }
+  // ─── Curve25519 / Ristretto (0x0402, 0x0403) ─────────────────────────────
+  /**
+   * Adds up to 10 Ristretto (Curve25519) compressed points via EVM precompile.
+   *
+   * Input: N × 32-byte CompressedRistretto points concatenated (N ≤ 10).
+   * Output: 32-byte CompressedRistretto sum.
+   *
+   * Useful for ZK protocols that require verifiable Pedersen commitments.
+   */
+  async curve25519Add(points) {
+    if (points.length === 0 || points.length > 10) {
+      throw new Error(`curve25519Add: expected 1\u201310 points, got ${points.length}`);
+    }
+    const input = new Uint8Array(points.length * 32);
+    for (let i = 0; i < points.length; i++) {
+      const pt = points[i];
+      if (!pt || pt.length !== 32) {
+        throw new Error(`curve25519Add: point[${i}] must be exactly 32 bytes`);
+      }
+      input.set(pt, i * 32);
+    }
+    return hexToBytes(await this.evm.call(PRECOMPILE_ADDR.CURVE25519_ADD, toHex(input)));
+  }
+  /**
+   * Multiplies a Ristretto compressed point by a scalar via EVM precompile.
+   *
+   * Input: 32-byte scalar (little-endian) + 32-byte CompressedRistretto point.
+   * Output: 32-byte CompressedRistretto result.
+   *
+   * Useful for computing key images and Pedersen commitments in ZK protocols.
+   */
+  async curve25519ScalarMul(scalar, point) {
+    if (scalar.length !== 32) throw new Error("curve25519ScalarMul: scalar must be 32 bytes");
+    if (point.length !== 32) throw new Error("curve25519ScalarMul: point must be 32 bytes");
+    const input = new Uint8Array(64);
+    input.set(scalar, 0);
+    input.set(point, 32);
+    return hexToBytes(await this.evm.call(PRECOMPILE_ADDR.CURVE25519_SCALAR_MUL, toHex(input)));
+  }
+};
+
+// src/client.ts
+var OrbinumClient = class _OrbinumClient {
+  /** Raw access to the Substrate WebSocket connection and RPC. */
+  substrate;
+  /** Raw access to the EVM HTTP JSON-RPC endpoint (if configured). */
+  evm;
+  /** Shielded-pool operations: shield, unshield, privateTransfer, and merkle queries. */
+  shieldedPool;
+  /** General chain queries: node info, identity resolution. */
+  chain;
+  /** Account mapping: aliases, chain links, metadata, marketplace, and identity extrinsics. */
+  accountMapping;
+  /**
+   * EVM precompiles: shielded pool + account mapping callable from an EVM wallet.
+   * Only available when `evmRpc` is configured. Methods throw if `evm` is null.
+   */
+  precompiles;
+  constructor(substrate, evm) {
+    this.substrate = substrate;
+    this.evm = evm;
+    const merkle = new MerkleModule(substrate);
+    this.shieldedPool = new ShieldedPoolModule(substrate, merkle);
+    this.chain = new ChainModule(substrate, evm);
+    this.accountMapping = new AccountMappingModule(substrate);
+    this.precompiles = evm ? {
+      shieldedPool: new ShieldedPoolPrecompile(evm),
+      accountMapping: new AccountMappingPrecompile(evm),
+      crypto: new CryptoPrecompiles(evm)
+    } : null;
+  }
+  /**
+   * Connects to an Orbinum node and returns a ready-to-use `OrbinumClient`.
+   * Throws if the Substrate node is unreachable within `connectTimeoutMs`.
+   */
+  static async connect(config) {
+    const substrate = await SubstrateClient.connect(
+      config.substrateWs,
+      config.connectTimeoutMs ?? 15e3
+    );
+    const evm = config.evmRpc ? new EvmClient(config.evmRpc) : null;
+    return new _OrbinumClient(substrate, evm);
+  }
+  /**
+   * Convenience getter for the Merkle module (shortcut for `shieldedPool.merkle`).
+   */
+  get merkle() {
+    return this.shieldedPool.merkle;
+  }
+  /** Closes the WebSocket connection to the Substrate node. */
+  destroy() {
+    this.substrate.destroy();
+  }
+};
+
+// src/shielded-pool/NoteDecryptor.ts
+var import_poseidon_lite2 = require("poseidon-lite");
+function tryDecryptNote(commitment, viewingKey, spendingKey) {
+  if (!commitment.encryptedMemo) return null;
+  let commitmentBytes;
+  let memoBytes;
+  try {
+    commitmentBytes = fromHex(commitment.commitmentHex);
+    memoBytes = fromHex(commitment.encryptedMemo);
+  } catch {
+    return null;
+  }
+  const plaintext = EncryptedMemo.decrypt(memoBytes, commitmentBytes, viewingKey);
+  if (!plaintext) return null;
+  const recomputed = (0, import_poseidon_lite2.poseidon4)([
+    plaintext.value,
+    plaintext.assetId,
+    plaintext.ownerPk,
+    plaintext.blinding
+  ]);
+  if (recomputed !== bytesToBigintLE(commitmentBytes)) return null;
+  const nullifier = (0, import_poseidon_lite2.poseidon2)([recomputed, spendingKey]);
+  return {
+    value: plaintext.value,
+    assetId: plaintext.assetId,
+    ownerPk: plaintext.ownerPk,
+    blinding: plaintext.blinding,
+    spendingKey,
+    spent: false,
+    spentAt: null,
+    commitment: recomputed,
+    nullifier,
+    commitmentHex: toHex(bigintTo32Le(recomputed)),
+    nullifierHex: toHex(bigintTo32Le(nullifier)),
+    memo: Array.from(memoBytes)
+  };
+}
+
+// src/shielded-pool/PrivacyKeys.ts
+var import_hkdf = require("@noble/hashes/hkdf.js");
+var import_sha22 = require("@noble/hashes/sha2.js");
+var import_baby_jubjub = require("@zk-kit/baby-jubjub");
+var BN254_R = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+var IVK_DOMAIN = new TextEncoder().encode("orbinum-ivk-v1");
+function deriveSpendingKeyMessage(chainId, address) {
+  return `orbinum-spending-key-v1
+${chainId}
+${address.toLowerCase()}`;
+}
+async function deriveSpendingKeyFromSignature(signatureHex, chainId, address) {
+  const hex = signatureHex.startsWith("0x") ? signatureHex.slice(2) : signatureHex;
+  const sigBytes = new Uint8Array((hex.match(/.{2}/g) ?? []).map((b) => parseInt(b, 16)));
+  const info = new TextEncoder().encode(`orbinum-sk-v1:${chainId}:${address.toLowerCase()}`);
+  const skBytes = (0, import_hkdf.hkdf)(import_sha22.sha256, sigBytes, new Uint8Array(0), info, 32);
+  const skBigint = BigInt(
+    "0x" + Array.from(skBytes).map((b) => b.toString(16).padStart(2, "0")).join("")
+  ) % BN254_R;
+  return skBigint === 0n ? 1n : skBigint;
+}
+function deriveViewingKey(spendingKey) {
+  const ikm = bigintTo32Le(spendingKey);
+  return (0, import_hkdf.hkdf)(import_sha22.sha256, ikm, void 0, IVK_DOMAIN, 32);
+}
+function deriveOwnerPk(spendingKey) {
+  try {
+    const pubPoint = (0, import_baby_jubjub.mulPointEscalar)(import_baby_jubjub.Base8, spendingKey);
+    return pubPoint[0];
+  } catch {
+    return 0n;
+  }
+}
+
+// src/shielded-pool/PrivacyKeyManager.ts
+var BN254_R2 = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+var _state = {
+  spendingKey: null,
+  viewingKey: null,
+  ownerPk: null
+};
+var PrivacyKeyManager = {
+  /**
+   * Load a spending key into the in-memory session.
+   * Derives viewingKey and ownerPk immediately.
+   * Replaces any previously loaded key.
+   */
+  async load(spendingKey) {
+    const viewingKey = deriveViewingKey(spendingKey);
+    const ownerPk = deriveOwnerPk(spendingKey);
+    _state = { spendingKey, viewingKey, ownerPk };
+  },
+  /** Clear all key material from memory. Call on vault lock / sign-out. */
+  clear() {
+    _state = { spendingKey: null, viewingKey: null, ownerPk: null };
+  },
+  /** Returns true if a spending key has been loaded. */
+  isLoaded() {
+    return _state.spendingKey !== null;
+  },
+  /** Returns the spending key. Throws if not loaded. */
+  getSpendingKey() {
+    if (_state.spendingKey === null) {
+      throw new Error("PrivacyKeyManager: no key loaded. Call load() first.");
+    }
+    return _state.spendingKey;
+  },
+  /** Returns the 32-byte viewing key. Throws if not loaded. */
+  getViewingKey() {
+    if (_state.viewingKey === null) {
+      throw new Error("PrivacyKeyManager: no key loaded. Call load() first.");
+    }
+    return _state.viewingKey;
+  },
+  /** Returns the BabyJubJub owner public key (x-coordinate). Throws if not loaded. */
+  getOwnerPk() {
+    if (_state.ownerPk === null) {
+      throw new Error("PrivacyKeyManager: no key loaded. Call load() first.");
+    }
+    return _state.ownerPk;
+  },
+  /** Returns the spending key as a 32-byte little-endian Uint8Array. Throws if not loaded. */
+  getSpendingKeyBytes() {
+    return bigintTo32Le(this.getSpendingKey());
+  },
+  /** Exports the spending key as a 0x-prefixed 64-char hex string. Throws if not loaded. */
+  exportHex() {
+    return "0x" + this.getSpendingKey().toString(16).padStart(64, "0");
+  },
+  /**
+   * Load a spending key from a 0x-prefixed or bare hex string.
+   * Validates the key is in the valid range [1, BN254_R).
+   */
+  async importFromHex(hex) {
+    const key = BigInt(hex.startsWith("0x") ? hex : "0x" + hex);
+    if (key === 0n || key >= BN254_R2) {
+      throw new Error("PrivacyKeyManager: invalid spending key \u2014 out of BN254 range.");
+    }
+    await this.load(key);
+  }
+};
+
+// src/shielded-pool/VaultCrypto.ts
+function vaultReplacer(_key, value) {
+  if (typeof value === "bigint") return { __bigint: value.toString() };
+  return value;
+}
+function vaultReviver(_key, value) {
+  if (value !== null && typeof value === "object" && "__bigint" in value) {
+    return BigInt(value.__bigint);
+  }
+  return value;
+}
+function toBase64(buf) {
+  const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+  let str = "";
+  for (const b of bytes) str += String.fromCharCode(b);
+  return btoa(str);
+}
+function fromBase64(b64) {
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+var VAULT_KEY_INFO = new TextEncoder().encode("orbinum-vault-key-v1");
+var IV_BYTES = 12;
+async function deriveVaultKey(spendingKeyBytes) {
+  const keyMaterial = await crypto.subtle.importKey(
+    "raw",
+    spendingKeyBytes.slice(0),
+    "HKDF",
+    false,
+    ["deriveKey"]
+  );
+  return crypto.subtle.deriveKey(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: new Uint8Array(0),
+      info: VAULT_KEY_INFO
+    },
+    keyMaterial,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
+}
+async function encryptJson(key, payload) {
+  const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+  const plaintext = new TextEncoder().encode(JSON.stringify(payload, vaultReplacer));
+  const ciphertextBuf = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, plaintext);
+  return { iv: toBase64(iv), ciphertext: toBase64(ciphertextBuf) };
+}
+async function decryptJson(key, iv, ciphertext) {
+  const plainBuf = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv: new Uint8Array(fromBase64(iv)) },
+    key,
+    new Uint8Array(fromBase64(ciphertext))
+  );
+  return JSON.parse(new TextDecoder().decode(plainBuf), vaultReviver);
+}
+
+// src/types.ts
+var SLIP0044_NAMESPACE = 2147483648;
+
+// src/index.ts
+var import_signer = require("polkadot-api/signer");
+var import_pjs_signer = require("polkadot-api/pjs-signer");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AccountMappingModule,
+  AccountMappingPrecompile,
+  ChainModule,
+  CryptoPrecompiles,
+  EncryptedMemo,
+  EvmClient,
+  MerkleModule,
+  NoteBuilder,
+  OrbinumClient,
+  PRECOMPILE_ADDR,
+  PrivacyKeyManager,
+  SLIP0044_NAMESPACE,
+  ShieldedPoolModule,
+  ShieldedPoolPrecompile,
+  SubstrateClient,
+  accountIdHexToSs58,
+  addressToAccountIdHex,
+  bigintTo32Be,
+  bigintTo32Le,
+  bigintTo32LeArr,
+  bytesToBigintLE,
+  computePathIndices,
+  decryptJson,
+  deriveOwnerPk,
+  deriveSpendingKeyFromSignature,
+  deriveSpendingKeyMessage,
+  deriveVaultKey,
+  deriveViewingKey,
+  encryptJson,
+  ensureHexPrefix,
+  evmAddressToAccountId,
+  evmToImplicitSubstrate,
+  evmToSubstrate,
+  fromHex,
+  getPolkadotSigner,
+  getPolkadotSignerFromPjs,
+  implicitSubstrateToEvm,
+  isEvmAddress,
+  isImplicitEvmAccount,
+  isSs58,
+  isSubstrateAddress,
+  isUnifiedAddress,
+  leHexToBigint,
+  normalizeEvmAddress,
+  substrateSs58ToAccountIdHex,
+  substrateToEvm,
+  toHex,
+  tryDecryptNote,
+  vaultReplacer,
+  vaultReviver
+});