@orbinum/sdk 1.4.0 → 2.0.0

package/dist/index.mjs

@@ -29,6 +29,7 @@ import {
   bytesToBjjScalar,
   canPairWith,
   clearKnownEphWindow,
+  collectOutgoingFacts,
   commitmentHexOf,
   computeNoteCommitment,
   computeNullifier,
@@ -59,6 +60,7 @@ import {
   hexToBigint,
   hexToNumber,
   isAbortError,
+  isHexOfLength,
   isSpendable,
   isValidLeafIndex,
   leHexToBigint,
@@ -77,7 +79,7 @@ import {
   tryDecryptNote,
   tryDecryptNoteVerbose,
   tryRecoverOutgoing
-} from "./chunk-A2ZRMEYW.mjs";
+} from "./chunk-VYKKBXOE.mjs";
 
 // src/foundation/encoding/base64.ts
 var ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
@@ -382,6 +384,7 @@ var SLIP_DOMAIN = new TextEncoder().encode("orbinum-payment-slip-v1");
 var NONCE_PREFIX = new TextEncoder().encode("SLP1");
 var EPH_PK_SIZE = 32;
 var NONCE_SUFFIX_SIZE = 8;
+var MAX_SLIP_ENVELOPE_SIZE = 4096;
 function deriveSlipKey(sharedSecret) {
   return hkdf(sha256, sharedSecret, void 0, SLIP_DOMAIN, 32);
 }
@@ -416,6 +419,7 @@ function sealPaymentSlip(recipientIvkPacked, fields) {
 }
 function openPaymentSlip(recipientIvsk, envelope) {
   if (envelope.length < EPH_PK_SIZE + NONCE_SUFFIX_SIZE + 16) return null;
+  if (envelope.length > MAX_SLIP_ENVELOPE_SIZE) return null;
   try {
     const ephPkPacked = envelope.subarray(0, EPH_PK_SIZE);
     const ephPkPoint = unpackPoint(bytesToBigintLE(ephPkPacked));
@@ -427,11 +431,19 @@ function openPaymentSlip(recipientIvsk, envelope) {
     const sealed = envelope.subarray(EPH_PK_SIZE + NONCE_SUFFIX_SIZE);
     const cipher = chacha20poly1305(slipKey, buildNonce(suffix));
     const plaintext = cipher.decrypt(sealed);
-    const fields = JSON.parse(new TextDecoder().decode(plaintext));
-    if (typeof fields.commitmentHex !== "string" || typeof fields.encryptedMemo !== "string") {
-      return null;
-    }
-    return fields;
+    const parsed = JSON.parse(new TextDecoder().decode(plaintext));
+    if (!isHexOfLength(parsed["commitmentHex"], 32)) return null;
+    if (!isHexOfLength(parsed["encryptedMemo"], ENCRYPTED_MEMO_SIZE)) return null;
+    const leafIndex = parsed["leafIndex"];
+    if (leafIndex !== void 0 && !isValidLeafIndex(leafIndex)) return null;
+    const rawTxHash = parsed["txHash"];
+    const txHash = isHexOfLength(rawTxHash, 32) ? rawTxHash : void 0;
+    return {
+      commitmentHex: parsed["commitmentHex"],
+      encryptedMemo: parsed["encryptedMemo"],
+      ...leafIndex !== void 0 ? { leafIndex } : {},
+      ...txHash !== void 0 ? { txHash } : {}
+    };
   } catch {
     return null;
   }
@@ -1536,11 +1548,17 @@ var SubstrateClient = class _SubstrateClient {
 
 // src/chain/evm/EvmClient.ts
 var EvmClient = class {
-  /** @param rpcUrl - HTTP URL of the EVM JSON-RPC endpoint (e.g. `"http://localhost:9933"`). */
-  constructor(rpcUrl) {
+  /**
+   * @param rpcUrl - HTTP URL of the EVM JSON-RPC endpoint (e.g. `"http://localhost:9933"`).
+   * @param peerRpcUrl - Optional second endpoint, used only to tell a genuinely
+   *   pending transaction from one stranded on `rpcUrl` alone. See `waitForReceipt`.
+   */
+  constructor(rpcUrl, peerRpcUrl) {
     this.rpcUrl = rpcUrl;
+    this.peerRpcUrl = peerRpcUrl;
   }
   rpcUrl;
+  peerRpcUrl;
   /**
    * Performs a single JSON-RPC call and returns the typed result.
    * Throws on HTTP errors, RPC-level errors, or a `null` result.
@@ -1598,10 +1616,18 @@ var EvmClient = class {
     const hex = await this.request("eth_getTransactionCount", [address, "latest"]);
     return hexToNumber(hex);
   }
-  /** Returns the current gas price in wei. */
-  async getGasPrice() {
+  /**
+   * Returns the current gas price in wei, padded by `bumpPercent`.
+   *
+   * `eth_gasPrice` reports the base fee exactly, and the base fee moves
+   * between signing and the pool's next revalidation. A transaction priced at
+   * the bare minimum is evicted as `GasPriceTooLow` the moment it rises, which
+   * leaves every later nonce from that account stranded in the future queue.
+   * The default 25% pad absorbs the usual movement.
+   */
+  async getGasPrice(bumpPercent = 25) {
     const hex = await this.request("eth_gasPrice", []);
-    return hexToBigint(hex);
+    return hexToBigint(hex) * BigInt(100 + bumpPercent) / 100n;
   }
   /** Submits a signed raw transaction. Returns the transaction hash. */
   async sendRawTransaction(signedHex) {
@@ -1719,10 +1745,41 @@ var EvmClient = class {
         deadline = Math.min(deadline + timeoutMs, hardDeadline);
       }
     }
+    if (await this.isStrandedOnThisNode(txHash)) {
+      throw new Error(
+        `Transaction dropped from the tx pool (never propagated beyond the submitting node, ${Date.now() - start}ms): ${txHash}`
+      );
+    }
     throw new Error(
       `Transaction still pending after ${Date.now() - start}ms: ${txHash} \u2014 it may still confirm; check the hash on the explorer before retrying`
     );
   }
+  /**
+   * True when `rpcUrl` knows the transaction but the configured peer does not.
+   *
+   * Returns false without a peer configured, and on any peer error — an
+   * unreachable peer is not evidence that a live transaction is stranded.
+   */
+  async isStrandedOnThisNode(txHash) {
+    if (!this.peerRpcUrl) return false;
+    try {
+      const res = await postJsonWithRetry(
+        this.peerRpcUrl,
+        JSON.stringify({
+          id: 1,
+          jsonrpc: "2.0",
+          method: "eth_getTransactionByHash",
+          params: [txHash]
+        })
+      );
+      if (!res.ok) return false;
+      const json = await res.json();
+      if (json.error) return false;
+      return json.result === null;
+    } catch {
+      return false;
+    }
+  }
 };
 
 // src/chain/evm/explorer/EvmExplorer.ts
@@ -2441,6 +2498,23 @@ function padTo32Multiple(data) {
   padded.set(data);
   return padded;
 }
+function bytes32Slot(value) {
+  if (value.length !== 32) {
+    throw new Error(`encodeAbi: bytes32 needs 32 bytes, got ${value.length}`);
+  }
+  const slot = new Uint8Array(32);
+  slot.set(value);
+  return slot;
+}
+function addressSlot(address) {
+  const clean = address.startsWith("0x") ? address.slice(2) : address;
+  if (clean.length > 40) {
+    throw new Error(`encodeAbi: address needs at most 20 bytes, got ${clean.length / 2}`);
+  }
+  const slot = new Uint8Array(32);
+  slot.set(fromHex("0x" + clean.padStart(40, "0")), 12);
+  return slot;
+}
 function encodeStaticParam(param) {
   const buf = new Uint8Array(32);
   switch (param.type) {
@@ -2448,14 +2522,10 @@ function encodeStaticParam(param) {
       return bigintTo32Be(param.value);
     }
     case "bytes32": {
-      buf.set(param.value.slice(0, 32));
-      return buf;
+      return bytes32Slot(param.value);
     }
     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;
+      return addressSlot(param.value);
     }
     case "bool": {
       buf[31] = param.value ? 1 : 0;
@@ -2478,25 +2548,13 @@ function encodeDynamicParam(param) {
       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);
-      }
+      const parts = [bigintTo32Be(BigInt(param.value.length))];
+      for (const b32 of param.value) parts.push(bytes32Slot(b32));
       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);
-      }
+      const parts = [bigintTo32Be(BigInt(param.value.length))];
+      for (const addr of param.value) parts.push(addressSlot(addr));
       return concat(parts);
     }
     case "bytes[]": {
@@ -2552,6 +2610,122 @@ function decodeUint(data, offset = 0) {
   return result;
 }
 
+// src/chain/evm/precompiles/shieldedPoolCalldata.ts
+var CLAIM_PUBLIC_SIGNALS_SIZE = 76;
+function bytes32(hex, field) {
+  if (!isHexOfLength(hex, 32)) {
+    throw new Error(`${field}: expected a 0x-prefixed 32-byte hex string, got ${hex}`);
+  }
+  return fromHex(hex);
+}
+function uint32(value, field) {
+  if (!Number.isInteger(value) || value < 0 || value > 4294967295) {
+    throw new Error(`${field}: expected a uint32 (0..4294967295), got ${value}`);
+  }
+  return BigInt(value);
+}
+function accountId32(address, field) {
+  const raw = address.startsWith("0x") ? address.slice(2) : address;
+  if (raw.length > 64) {
+    throw new Error(`${field}: expected at most 32 bytes, got ${raw.length / 2}`);
+  }
+  return bytes32("0x" + raw.padEnd(64, "0"), field);
+}
+function buildShieldCalldata(params) {
+  EncryptedMemo.validate(params.encryptedMemo, "buildShieldCalldata.encryptedMemo");
+  const commitment = bytes32(params.commitment, "buildShieldCalldata.commitment");
+  return encodeHex(
+    SP_SEL.SHIELD,
+    { type: "uint", value: uint32(params.assetId, "buildShieldCalldata.assetId") },
+    { type: "bytes32", value: commitment },
+    { type: "bytes", value: params.encryptedMemo }
+  );
+}
+function buildPrivateTransferCalldata(params) {
+  const nullifiers = params.inputs.map(
+    (input, i) => bytes32(input.nullifier, `buildPrivateTransferCalldata.inputs[${i}].nullifier`)
+  );
+  const commitments = params.outputs.map(
+    (output, i) => bytes32(output.commitment, `buildPrivateTransferCalldata.outputs[${i}].commitment`)
+  );
+  const memos = params.outputs.map((output, i) => {
+    EncryptedMemo.validate(
+      output.encryptedMemo,
+      `buildPrivateTransferCalldata.outputs[${i}].encryptedMemo`
+    );
+    return output.encryptedMemo;
+  });
+  const root = bytes32(params.merkleRoot, "buildPrivateTransferCalldata.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 },
+    { type: "uint", value: uint32(params.assetId, "buildPrivateTransferCalldata.assetId") },
+    { type: "uint", value: params.fee ?? 0n },
+    {
+      type: "uint",
+      value: uint32(params.circuitVersion, "buildPrivateTransferCalldata.circuitVersion")
+    }
+  );
+}
+function buildUnshieldCalldata(params) {
+  const root = bytes32(params.merkleRoot, "buildUnshieldCalldata.merkleRoot");
+  const nullifier = bytes32(params.nullifier, "buildUnshieldCalldata.nullifier");
+  const recipient = accountId32(
+    params.recipientAddress,
+    "buildUnshieldCalldata.recipientAddress"
+  );
+  const changeCommitment = bytes32(
+    params.changeCommitment ?? "0x" + "00".repeat(32),
+    "buildUnshieldCalldata.changeCommitment"
+  );
+  const changeEncryptedMemo = params.changeEncryptedMemo ?? new Uint8Array();
+  return encodeHex(
+    SP_SEL.UNSHIELD,
+    { type: "bytes", value: params.proof },
+    { type: "bytes32", value: root },
+    { type: "bytes32", value: nullifier },
+    { type: "uint", value: uint32(params.assetId, "buildUnshieldCalldata.assetId") },
+    { type: "uint", value: params.amount },
+    { type: "bytes32", value: recipient },
+    { type: "uint", value: params.fee ?? 0n },
+    { type: "bytes32", value: changeCommitment },
+    { type: "bytes", value: changeEncryptedMemo },
+    {
+      type: "uint",
+      value: uint32(params.circuitVersion, "buildUnshieldCalldata.circuitVersion")
+    }
+  );
+}
+function buildClaimShieldedFeesCalldata(params) {
+  EncryptedMemo.validate(params.encryptedMemo, "buildClaimShieldedFeesCalldata.encryptedMemo");
+  if (params.proof.length === 0) {
+    throw new Error("claimShieldedFees: proof must not be empty");
+  }
+  if (params.publicSignals.length !== CLAIM_PUBLIC_SIGNALS_SIZE) {
+    throw new Error(
+      `claimShieldedFees: publicSignals must be ${CLAIM_PUBLIC_SIGNALS_SIZE} bytes, got ${params.publicSignals.length}`
+    );
+  }
+  const commitment = bytes32(params.commitment, "buildClaimShieldedFeesCalldata.commitment");
+  return encodeHex(
+    SP_SEL.CLAIM_SHIELDED_FEES,
+    { type: "bytes32", value: commitment },
+    { type: "uint", value: params.amount },
+    { type: "uint", value: uint32(params.assetId, "buildClaimShieldedFeesCalldata.assetId") },
+    { type: "bytes", value: params.encryptedMemo },
+    { type: "bytes", value: params.proof },
+    { type: "bytes", value: params.publicSignals },
+    {
+      type: "uint",
+      value: uint32(params.circuitVersion, "buildClaimShieldedFeesCalldata.circuitVersion")
+    }
+  );
+}
+
 // src/chain/evm/precompiles/ShieldedPoolPrecompile.ts
 var ShieldedPoolPrecompile = class {
   constructor(evm) {
@@ -2559,228 +2733,111 @@ var ShieldedPoolPrecompile = class {
   }
   evm;
   addr = PRECOMPILE_ADDR.SHIELDED_POOL;
-  // ─── shield ────────────────────────────────────────────────────────────────
-  /**
-   * Returns the ABI-encoded calldata for `shield(uint32, bytes32, bytes)`.
-   * The token amount must be sent as `msg.value` (the `value` field of the EVM
-   * transaction) — this is what MetaMask and other wallets display to the user.
-   */
+  // ─── Calldata ────────────────────────────────────────────────────────────
+  //
+  // Thin delegates to `shieldedPoolCalldata`, kept because they are public
+  // API. New code should import those functions directly: they are pure, so
+  // using them needs no `EvmClient` to construct.
   buildShieldCalldata(params) {
-    EncryptedMemo.validate(params.encryptedMemo, "buildShieldCalldata.encryptedMemo");
-    const commitment = fromHex(params.commitment);
-    return encodeHex(
-      SP_SEL.SHIELD,
-      { type: "uint", value: BigInt(params.assetId) },
-      { type: "bytes32", value: commitment },
-      { type: "bytes", value: params.encryptedMemo }
-    );
+    return buildShieldCalldata(params);
+  }
+  buildPrivateTransferCalldata(params) {
+    return buildPrivateTransferCalldata(params);
+  }
+  buildUnshieldCalldata(params) {
+    return buildUnshieldCalldata(params);
+  }
+  buildClaimShieldedFeesCalldata(params) {
+    return buildClaimShieldedFeesCalldata(params);
   }
+  // ─── shield ──────────────────────────────────────────────────────────────
   /**
    * Deposits tokens into the shielded pool from a payable EVM transaction.
    *
-   * The token amount is sent as `msg.value` so EVM wallets (MetaMask, etc.) display
-   * the correct amount on the confirmation screen. The precompile dispatches
-   * `shieldedPool.shield` with its own address as origin, so the funds flow:
-   *   caller → precompile (via msg.value, handled by EVM)
-   *   precompile → pool (via pallet transfer)
-   * This avoids double-deduction while keeping the displayed amount accurate.
+   * The amount rides as `msg.value` so EVM wallets show the correct figure on
+   * the confirmation screen. The precompile then dispatches with its OWN
+   * address as origin, so funds flow caller → precompile → pool. That avoids
+   * a double deduction while keeping the displayed amount accurate.
    *
    * Extrinsic: `shieldedPool.shield(assetId, amount, commitment, encryptedMemo)`
    */
   async shield(params, signer) {
     return signer({
       to: this.addr,
-      data: this.buildShieldCalldata(params),
+      data: buildShieldCalldata(params),
       value: params.amount
     });
   }
-  // ─── privateTransfer ───────────────────────────────────────────────────────
-  /**
-   * Returns the ABI-encoded calldata for
-   * `privateTransfer(bytes, bytes32, bytes32[], bytes32[], bytes[], uint32, uint256, uint32)`.
-   * The trailing `uint32` is the circuit version the input notes were created under.
-   */
-  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, i) => {
-      EncryptedMemo.validate(
-        o.encryptedMemo,
-        `buildPrivateTransferCalldata.outputs[${i}].encryptedMemo`
-      );
-      return o.encryptedMemo;
-    });
-    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 },
-      { type: "uint", value: BigInt(params.assetId) },
-      { type: "uint", value: params.fee ?? 0n },
-      { type: "uint", value: BigInt(params.circuitVersion) }
-    );
-  }
+  // ─── privateTransfer ─────────────────────────────────────────────────────
   /**
-   * Submits a private transfer within the shielded pool from an EVM transaction.
+   * Submits a private transfer within the shielded pool.
    *
-   * 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.
+   * The EVM caller identity is IRRELEVANT to the ZK proof — the sender is
+   * hidden by design, so any address (a relayer included) 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"))
-    );
-    const changeCommitmentHex = params.changeCommitment ?? "0x" + "00".repeat(32);
-    const changeCommitment = fromHex(changeCommitmentHex);
-    const changeEncryptedMemo = params.changeEncryptedMemo ?? new Uint8Array();
-    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 },
-      { type: "uint", value: params.fee ?? 0n },
-      { type: "bytes32", value: changeCommitment },
-      { type: "bytes", value: changeEncryptedMemo },
-      { type: "uint", value: BigInt(params.circuitVersion) }
-    );
+    return signer({ to: this.addr, data: buildPrivateTransferCalldata(params) });
   }
+  // ─── unshield ────────────────────────────────────────────────────────────
   /**
    * 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.
+   * `params.recipientAddress` must be a 0x-prefixed AccountId32. To send to an
+   * EVM address, derive it first with `evmToImplicitSubstrate(evmAddr)`.
    *
    * Extrinsic: `shieldedPool.unshield(proof, merkleRoot, nullifier, assetId, amount, recipient)`
    */
   async unshield(params, signer) {
-    return signer({ to: this.addr, data: this.buildUnshieldCalldata(params) });
+    return signer({ to: this.addr, data: buildUnshieldCalldata(params) });
   }
-  // ─── Gas estimation ────────────────────────────────────────────────────────
+  // ─── claimShieldedFees ───────────────────────────────────────────────────
   /**
-   * Estimates the EVM gas for a `shield` call without submitting.
-   * Requires `from` to be set to the actual sender address.
+   * Claims accrued relay fees as a private shielded note.
+   *
+   * For validators/relayers holding fees in `pallet-relayer` who want them
+   * paid privately into the shielded pool rather than as a public balance
+   * credit. The ZK `value_proof` binds `commitment` to
+   * `(amount, assetId, ownerPk, blinding)`, so the runtime can verify the note
+   * encodes exactly the claimed amount and a malicious relayer cannot inflate
+   * the withdrawal.
+   *
+   * The `msg.sender` address is the validator identity, and must match the
+   * one with pending fees.
+   *
+   * Extrinsic: `shieldedPool.claim_shielded_fees(commitment, amount, assetId, memo, proof, publicSignals)`
    */
-  async estimateShieldGas(params, from) {
-    return this.evm.estimateGas({
-      from,
+  async claimShieldedFees(params, signer) {
+    return signer({
       to: this.addr,
-      data: this.buildShieldCalldata(params)
+      data: buildClaimShieldedFeesCalldata(params)
     });
   }
-  /**
-   * Estimates the EVM gas for a `privateTransfer` call.
-   */
+  // ─── Gas estimation ──────────────────────────────────────────────────────
+  //
+  // `from` must be the real sender: the precompile resolves it to an
+  // AccountId32, so estimating from a different address measures a different
+  // call.
+  async estimateShieldGas(params, from) {
+    return this.evm.estimateGas({ from, to: this.addr, data: buildShieldCalldata(params) });
+  }
   async estimatePrivateTransferGas(params, from) {
     return this.evm.estimateGas({
       from,
       to: this.addr,
-      data: this.buildPrivateTransferCalldata(params)
+      data: 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)
-    });
-  }
-  // ─── claimShieldedFees ───────────────────────────────────────────────────────────────────
-  /**
-   * Returns the ABI-encoded calldata for
-   * `claimShieldedFees(bytes32,uint256,uint32,bytes,bytes,bytes,uint32)`.
-   *
-   * ABI layout (params after selector):
-   * - `commitment`    — bytes32 (fixed)
-   * - `amount`        — uint256 (fixed)
-   * - `asset_id`      — uint32  (fixed, right-aligned)
-   * - `memo`          — bytes   (dynamic)
-   * - `proof`         — bytes   (dynamic, 128 bytes Groth16)
-   * - `publicSignals` — bytes   (dynamic, 76 bytes)
-   * - `circuitVersion` — uint32 (fixed, right-aligned)
-   *
-   * The validator identity is derived from `msg.sender` in the precompile —
-   * do NOT include it in the calldata.
-   */
-  buildClaimShieldedFeesCalldata(params) {
-    EncryptedMemo.validate(
-      params.encryptedMemo,
-      "buildClaimShieldedFeesCalldata.encryptedMemo"
-    );
-    if (params.proof.length === 0) {
-      throw new Error("claimShieldedFees: proof must not be empty");
-    }
-    if (params.publicSignals.length !== 76) {
-      throw new Error(
-        `claimShieldedFees: publicSignals must be 76 bytes, got ${params.publicSignals.length}`
-      );
-    }
-    const commitment = fromHex(params.commitment);
-    return encodeHex(
-      SP_SEL.CLAIM_SHIELDED_FEES,
-      { type: "bytes32", value: commitment },
-      { type: "uint", value: params.amount },
-      { type: "uint", value: BigInt(params.assetId) },
-      { type: "bytes", value: params.encryptedMemo },
-      { type: "bytes", value: params.proof },
-      { type: "bytes", value: params.publicSignals },
-      { type: "uint", value: BigInt(params.circuitVersion) }
-    );
-  }
-  /**
-   * Claims accumulated relay fees as a private shielded note.
-   *
-   * This extrinsic is for **validators/relayers** who have accrued fees in
-   * `pallet-relayer` and want to receive them privately inside the shielded pool
-   * instead of as a public balance credit.
-   *
-   * The ZK `value_proof` binds `commitment` to `(amount, assetId, ownerPk, blinding)`
-   * so the runtime can verify the note encodes exactly the claimed fee amount,
-   * preventing a malicious relayer from inflating the withdrawal.
-   *
-   * The `msg.sender` EVM address is used as the validator identity; it must match
-   * the address that has pending relay fees in `pallet-relayer`.
-   *
-   * Extrinsic: `shieldedPool.claim_shielded_fees(commitment, amount, assetId, memo, proof, publicSignals)`
-   */
-  async claimShieldedFees(params, signer) {
-    return signer({
-      to: this.addr,
-      data: this.buildClaimShieldedFeesCalldata(params)
-    });
+    return this.evm.estimateGas({ from, to: this.addr, data: buildUnshieldCalldata(params) });
   }
-  /**
-   * Estimates the EVM gas for a `claimShieldedFees` call.
-   */
   async estimateClaimShieldedFeesGas(params, from) {
     return this.evm.estimateGas({
       from,
       to: this.addr,
-      data: this.buildClaimShieldedFeesCalldata(params)
+      data: buildClaimShieldedFeesCalldata(params)
     });
   }
 };
@@ -2952,7 +3009,7 @@ var OrbinumClient = class _OrbinumClient {
    */
   static async connect(config) {
     const substrate = config.papi ? SubstrateClient.adopt(config.papi, config.substrateHttp) : await SubstrateClient.connect(config.substrateWs, config.connectTimeoutMs ?? 15e3);
-    const evm = config.evmRpc ? new EvmClient(config.evmRpc) : null;
+    const evm = config.evmRpc ? new EvmClient(config.evmRpc, config.evmRpcPeer) : null;
     return new _OrbinumClient(substrate, evm, config.circuitsBaseUrl);
   }
   /**
@@ -3092,6 +3149,7 @@ var OrbinumClientProvider = class _OrbinumClientProvider {
         connectTimeoutMs: this.connectTimeoutMs
       };
       if (this.config.evmRpc) connectConfig.evmRpc = this.config.evmRpc;
+      if (this.config.evmRpcPeer) connectConfig.evmRpcPeer = this.config.evmRpcPeer;
       if (this.config.circuitsBaseUrl)
         connectConfig.circuitsBaseUrl = this.config.circuitsBaseUrl;
       clientPromise = OrbinumClient.connect(connectConfig);
@@ -3880,6 +3938,9 @@ function methodOf(fnSig) {
   if (fnSig.startsWith("shield(")) return "shield";
   return null;
 }
+function hasFullHead(data, slots) {
+  return data.length >= slots * 32;
+}
 function decodePrecompileCalldata(address, input) {
   const info = KNOWN_PRECOMPILES[address.toLowerCase()];
   if (!info || !input || input.length < 10) return null;
@@ -3889,6 +3950,7 @@ function decodePrecompileCalldata(address, input) {
   if (fnSig.startsWith("shield(")) {
     try {
       const data = fromHex(input.slice(10));
+      if (!hasFullHead(data, 3)) return { fnSig, method: methodOf(fnSig), args: {} };
       const assetId = decodeUint(data, 0);
       const commitment = toHex(data.slice(32, 64));
       return { fnSig, method: methodOf(fnSig), args: { assetId, commitment } };
@@ -3899,6 +3961,7 @@ function decodePrecompileCalldata(address, input) {
   if (fnSig.startsWith("unshield(")) {
     try {
       const data = fromHex(input.slice(10));
+      if (!hasFullHead(data, 10)) return { fnSig, method: methodOf(fnSig), args: {} };
       const root = toHex(data.slice(32, 64));
       const nullifier = toHex(data.slice(64, 96));
       const assetId = decodeUint(data, 96);
@@ -3928,18 +3991,25 @@ function decodePrecompileCalldata(address, input) {
   if (fnSig.startsWith("privateTransfer(")) {
     try {
       const data = fromHex(input.slice(10));
+      if (!hasFullHead(data, 8)) return { fnSig, method: methodOf(fnSig), args: {} };
       const root = toHex(data.slice(32, 64));
-      const nullOffset = Number(decodeUint(data, 64));
-      const commOffset = Number(decodeUint(data, 96));
-      const nullifiers = Number(decodeUint(data, nullOffset));
-      const commitments = Number(decodeUint(data, commOffset));
       const assetId = decodeUint(data, 160);
       const fee = decodeUint(data, 192);
       const circuitVersion = decodeUint(data, 224);
+      const counts = {};
+      for (const [name, slot] of [
+        ["nullifiers", 64],
+        ["commitments", 96]
+      ]) {
+        const offset = decodeUint(data, slot);
+        if (offset <= BigInt(data.length - 32)) {
+          counts[name] = Number(decodeUint(data, Number(offset)));
+        }
+      }
       return {
         fnSig,
         method: methodOf(fnSig),
-        args: { root, nullifiers, commitments, assetId, fee, circuitVersion }
+        args: { root, ...counts, assetId, fee, circuitVersion }
       };
     } catch {
       return { fnSig, method: methodOf(fnSig), args: {} };
@@ -3948,6 +4018,7 @@ function decodePrecompileCalldata(address, input) {
   if (fnSig.startsWith("claimShieldedFees(")) {
     try {
       const data = fromHex(input.slice(10));
+      if (!hasFullHead(data, 7)) return { fnSig, method: methodOf(fnSig), args: {} };
       const commitment = toHex(data.slice(0, 32));
       const amount = decodeUint(data, 32);
       const assetId = decodeUint(data, 64);
@@ -4154,7 +4225,7 @@ var MemoryVaultStorage = class {
 };
 
 // src/wallet/vault/storage/config.ts
-var VAULT_SCHEMA_VERSION = 4;
+var VAULT_SCHEMA_VERSION = 5;
 function normalizeChainFingerprint(chainFingerprint) {
   return chainFingerprint ? chainFingerprint.toLowerCase() : void 0;
 }
@@ -4303,7 +4374,7 @@ async function noteBlindTag(blindKey, hex) {
 
 // src/wallet/vault/notes/meta.ts
 function noteOrigin(note) {
-  return note.counterpartyPk === 0n ? "shield" : "private-transfer";
+  return note.sourcePk === 0n ? "shield" : "private-transfer";
 }
 function noteCreatedAt(note) {
   return note.createdAt ?? null;
@@ -4372,9 +4443,9 @@ var NOTE_BIGINT_FIELDS = [
   "spendingKey",
   "commitment",
   "nullifier",
-  "counterpartyPk"
+  "sourcePk"
 ];
-var ABSENT_MEANS_ZERO = /* @__PURE__ */ new Set(["counterpartyPk"]);
+var ABSENT_MEANS_ZERO = /* @__PURE__ */ new Set(["sourcePk"]);
 function normalizeNote(note) {
   let patch = null;
   for (const field of NOTE_BIGINT_FIELDS) {
@@ -4627,12 +4698,12 @@ var VaultStore = class {
     const { blindKey } = this.keys();
     if (commitmentHexes.length === 0) return 0;
     const toRemove = new Set(commitmentHexes);
-    const present = this.deps.notes.get().filter((n) => toRemove.has(n.commitmentHex));
-    if (present.length === 0) return 0;
-    const tags = await Promise.all(present.map((n) => noteBlindTag(blindKey, n.commitmentHex)));
+    const present2 = this.deps.notes.get().filter((n) => toRemove.has(n.commitmentHex));
+    if (present2.length === 0) return 0;
+    const tags = await Promise.all(present2.map((n) => noteBlindTag(blindKey, n.commitmentHex)));
     await this.deps.storage.deleteNotes(tags);
     this.deps.notes.set(removeByCommitment(this.deps.notes.get(), toRemove));
-    return present.length;
+    return present2.length;
   }
   /**
    * Stores an outgoing transaction, encrypted.
@@ -5223,26 +5294,147 @@ function parseFeeArg(argsJson) {
   }
 }
 
+// src/wallet/provenance/selectDescribingNote.ts
+function hasSourcePk(note) {
+  return typeof note.sourcePk === "bigint" && note.sourcePk !== 0n;
+}
+function selectDescribingNote(candidates) {
+  return candidates.find(hasSourcePk) ?? candidates[0];
+}
+function selectDescribingNoteByCommitment(commitments, noteByCommitment) {
+  const owned = commitments.map((hex) => noteByCommitment.get(hex)).filter((note) => note !== void 0);
+  return selectDescribingNote(owned);
+}
+
+// src/wallet/provenance/merge.ts
+var SOURCE_RANK = {
+  witnessed: 3,
+  memo: 2,
+  chain: 1,
+  inferred: 0
+};
+function rankOf(source) {
+  return SOURCE_RANK[source] ?? -1;
+}
+function outranks(a, b) {
+  return rankOf(a) > rankOf(b);
+}
+function mergeProvenance(existing, incoming) {
+  if (existing.id !== incoming.id) {
+    throw new Error(
+      `mergeProvenance: id mismatch \u2014 refusing to merge ${existing.id} with ${incoming.id}`
+    );
+  }
+  const incomingWins = outranks(incoming.source, existing.source);
+  const base = incomingWins ? incoming : existing;
+  const other = incomingWins ? existing : incoming;
+  const fee = base.feePlanck ?? other.feePlanck;
+  const publicRecipient = firstPresent(base.publicRecipient, other.publicRecipient);
+  const slip = present(base.slip?.encoded) ? base.slip : other.slip ?? base.slip;
+  const note = base.note ?? other.note;
+  return {
+    // The loser is spread FIRST so a field only it carries survives. A host
+    // stores its own record type through this — `ReconstructedTxRecord` has
+    // `amountApproximate`, which marks an amount derived without subtracting
+    // the fee — and dropping such a field turns an approximate figure into
+    // one that merely looks exact. Every key the winner knows about is
+    // overwritten below, so rank still decides every shared fact.
+    ...other,
+    ...base,
+    // A known peer beats an unknown one even when the winner is silent:
+    // backfilling the recipient is the whole point of re-running this.
+    // `scope: 'none'` is "this operation has no counterparty", so it is a
+    // gap too — treating it as known would block the backfill it exists for.
+    peer: copyPeer(knownPeer(base.peer) ?? knownPeer(other.peer) ?? base.peer ?? other.peer),
+    // A number that stands for "not known yet" must not win by rank. Zero is
+    // exactly that here: `RECOVERED_TX_RESULT` and a failed submission both
+    // report block 0, and their own comment says a caller who needs the
+    // value must look it up rather than trust the field.
+    blockNumber: firstPositive(base.blockNumber, other.blockNumber),
+    timestampMs: firstPositive(base.timestampMs, other.timestampMs),
+    // Reconstruction writes an empty hash when the extrinsic was not decoded.
+    hash: firstPresent(base.hash, other.hash) ?? base.hash,
+    // `exact` is a property of the FIGURE, not of the source. A `witnessed`
+    // row whose amount was marked approximate is not better data than an
+    // exact one from a weaker source, so rank only breaks a tie between two
+    // figures of equal standing.
+    amount: { ...betterAmount(base.amount, other.amount) },
+    // The chain's outcome is not something one source knows better than
+    // another — anyone who looks sees the same thing. Letting rank decide
+    // would let a row written at submit time mark a transaction failed that
+    // the chain went on to accept.
+    status: base.status === "success" || other.status === "success" ? "success" : "failed",
+    ...fee !== void 0 && { feePlanck: fee },
+    ...publicRecipient !== void 0 && { publicRecipient },
+    ...slip !== void 0 && { slip: { ...slip } },
+    ...note !== void 0 && { note: { ...note } }
+  };
+}
+function betterAmount(base, other) {
+  if (base.exact === other.exact) return base;
+  return base.exact ? base : other;
+}
+function present(value) {
+  return value !== void 0 && value.length > 0;
+}
+function firstPresent(base, other) {
+  return present(base) ? base : present(other) ? other : void 0;
+}
+function firstPositive(base, other) {
+  return base > 0 ? base : other > 0 ? other : base;
+}
+function copyPeer(peer) {
+  return peer ? { ...peer } : null;
+}
+function knownPeer(peer) {
+  return peer && peer.scope !== "none" ? peer : null;
+}
+
+// src/wallet/provenance/regenerateSlip.ts
+function regeneratePaymentSlip(facts, recipientIvkPacked, txHash) {
+  if (!isHexOfLength(facts.commitmentHex, 32)) {
+    throw new Error("regeneratePaymentSlip: commitmentHex must be 32 bytes of hex");
+  }
+  if (!isHexOfLength(facts.encryptedMemo, ENCRYPTED_MEMO_SIZE)) {
+    throw new Error(
+      `regeneratePaymentSlip: encryptedMemo must be ${ENCRYPTED_MEMO_SIZE} bytes of hex`
+    );
+  }
+  if (facts.leafIndex !== void 0 && !isValidLeafIndex(facts.leafIndex)) {
+    throw new Error("regeneratePaymentSlip: leafIndex must be a real tree position");
+  }
+  const envelope = sealPaymentSlip(recipientIvkPacked, {
+    commitmentHex: facts.commitmentHex,
+    encryptedMemo: facts.encryptedMemo,
+    ...facts.leafIndex !== void 0 ? { leafIndex: facts.leafIndex } : {},
+    // Rendered as an explorer link by the recipient, where an unconstrained
+    // string is a URL injection wearing the authority of a decrypted slip.
+    // Dropped rather than fatal: the slip still rebuilds the note, which is
+    // the part that matters.
+    ...isHexOfLength(txHash, 32) ? { txHash } : {}
+  });
+  return encodePaymentSlip(envelope);
+}
+
 // src/wallet/scanner/history/reconstruct.ts
 var ZERO_PK = "0x" + "00".repeat(32);
 function extrinsicKey(row) {
   return `${row.blockNumber}:${row.extrinsicIndex ?? "null"}`;
 }
-function toPkHex(counterpartyPk) {
-  return counterpartyPk != null && counterpartyPk !== 0n ? scalarToHex(counterpartyPk) : ZERO_PK;
-}
-function findChangeNote(commitments, noteByCommitment) {
-  const candidates = commitments.map((h) => noteByCommitment.get(h)).filter((n) => n !== void 0);
-  return candidates.find((n) => n.counterpartyPk != null && n.counterpartyPk !== 0n) ?? candidates[0];
+function toPkHex(sourcePk) {
+  return typeof sourcePk === "bigint" && hasSourcePk({ sourcePk }) ? scalarToHex(sourcePk) : ZERO_PK;
 }
 async function loadExistingRecords(vault) {
   try {
     const records = await vault.getTxRecords();
-    return new Map(records.map((r) => [r.hash, r]));
+    return new Map(records.map((r) => [r.id, r]));
   } catch {
     return /* @__PURE__ */ new Map();
   }
 }
+function recordKey(transfer) {
+  return transfer.hash ?? `${transfer.blockNumber}-${transfer.extrinsicIndex ?? 0}`;
+}
 async function reconstructOutgoingTxRecords(deps) {
   const { vault, transfers } = deps;
   const now = deps.now ?? Date.now;
@@ -5259,17 +5451,17 @@ async function reconstructOutgoingTxRecords(deps) {
   const commitmentsByExtrinsic = new Map(
     commitmentTransfers.map((ct) => [extrinsicKey(ct), ct.matchedCommitments ?? []])
   );
-  const existingByHash = await loadExistingRecords(vault);
+  const existingByKey = await loadExistingRecords(vault);
   for (const transfer of outgoingTransfers) {
-    const existing = transfer.hash ? existingByHash.get(transfer.hash) : void 0;
+    const existing = existingByKey.get(recordKey(transfer));
     if (existing?.recipientPkHex && existing.recipientPkHex !== ZERO_PK) continue;
     const inputNotes = (transfer.matchedNullifiers ?? []).map((h) => noteByNullifier.get(h)).filter((n) => n !== void 0);
     if (inputNotes.length === 0) continue;
-    const changeNote = findChangeNote(
+    const changeNote = selectDescribingNoteByCommitment(
       commitmentsByExtrinsic.get(extrinsicKey(transfer)) ?? [],
       noteByCommitment
     );
-    const recipientPkHex = toPkHex(changeNote?.counterpartyPk);
+    const recipientPkHex = toPkHex(changeNote?.sourcePk);
     if (existing) {
       if (recipientPkHex === ZERO_PK) continue;
       await vault.saveTxRecord({ ...existing, recipientPkHex });
@@ -5280,7 +5472,7 @@ async function reconstructOutgoingTxRecords(deps) {
     const transferAmount = totalInputValue - (changeNote?.value ?? 0n) - (fee ?? 0n);
     if (transferAmount <= 0n) continue;
     const record = {
-      id: transfer.hash ?? `${transfer.blockNumber}-${transfer.extrinsicIndex ?? 0}`,
+      id: recordKey(transfer),
       type: "private_transfer",
       blockNumber: transfer.blockNumber,
       hash: transfer.hash ?? "",
@@ -5331,7 +5523,7 @@ async function buildZkNote(params, deps) {
     circuitVersion: params.circuitVersion,
     // Omitted rather than passed as undefined: the builder distinguishes an
     // absent recipient (a self note) from one explicitly set.
-    ...params.counterpartyPk !== void 0 && { counterpartyPk: params.counterpartyPk },
+    ...params.sourcePk !== void 0 && { sourcePk: params.sourcePk },
     ...params.recipientOwnerPk !== void 0 && {
       recipientOwnerPk: params.recipientOwnerPk
     },
@@ -5650,7 +5842,7 @@ async function transferNotes(deps, params, onProgress) {
     value: transferAmount,
     assetId: noteA.assetId,
     ownerPk: recipientPk,
-    counterpartyPk: effectiveSenderPk,
+    sourcePk: effectiveSenderPk,
     // Undefined → dummy memo; the recipient finds the note by scanning.
     ...recipientViewingPublicKey !== void 0 ? { viewingPublicKey: recipientViewingPublicKey } : {},
     // With a viewing key present this activates stealth derivation.
@@ -5661,7 +5853,7 @@ async function transferNotes(deps, params, onProgress) {
     assetId: noteA.assetId,
     ownerPk: effectiveSenderPk,
     spendingKey: noteA.spendingKey,
-    counterpartyPk: recipientNote.ownerPk,
+    sourcePk: recipientNote.ownerPk,
     viewingPublicKey: senderViewingPublicKey
   });
   onProgress?.("generating-zk");
@@ -6415,6 +6607,7 @@ export {
   clearKnownEphWindow,
   clearSession,
   collectNullifiersToQuery,
+  collectOutgoingFacts,
   collectScanEntries,
   commitmentHexOf,
   computeNoteCommitment,
@@ -6490,6 +6683,7 @@ export {
   getPolkadotSignerFromPjs as getSubstrateSignerFromExtension,
   hasCachedSession,
   hasInjectedExtensions,
+  hasSourcePk,
   hexToBigint,
   hexToNumber,
   implicitSubstrateToEvm,
@@ -6501,6 +6695,7 @@ export {
   isConnectionLossError,
   isEvmAddress,
   isGhostNoteError,
+  isHexOfLength,
   isImplicitEvmAccount,
   isNativeAsset,
   isNoteSelfConsistent,
@@ -6513,6 +6708,7 @@ export {
   mapExtrinsicArgs,
   mapZkEventData,
   markInputsSpent,
+  mergeProvenance,
   normalizeChainFingerprint,
   normalizeEvmAddress,
   normalizeNote,
@@ -6527,6 +6723,7 @@ export {
   noteTxKind,
   openOutgoingBlob,
   openPaymentSlip,
+  outranks,
   pairwiseEphWindow,
   palletErrorKind,
   parseAmount,
@@ -6541,6 +6738,7 @@ export {
   recoverOwnerPkPoint,
   recoverSelfStealthNote,
   refuseIfAlreadySpent,
+  regeneratePaymentSlip,
   removeByCommitment,
   requireSessionKeys,
   reservePairwiseIndex,
@@ -6554,6 +6752,8 @@ export {
   scanAbortError,
   sealOutgoingBlob,
   sealPaymentSlip,
+  selectDescribingNote,
+  selectDescribingNoteByCommitment,
   selectGhosts,
   selectNotes,
   selfEphWindow,