@orbinum/sdk 1.4.0 → 2.1.0

package/dist/index.js

@@ -109,6 +109,7 @@ __export(index_exports, {
   clearKnownEphWindow: () => clearKnownEphWindow,
   clearSession: () => clearSession,
   collectNullifiersToQuery: () => collectNullifiersToQuery,
+  collectOutgoingFacts: () => collectOutgoingFacts,
   collectScanEntries: () => collectScanEntries,
   commitmentHexOf: () => commitmentHexOf,
   computeNoteCommitment: () => computeNoteCommitment,
@@ -184,6 +185,7 @@ __export(index_exports, {
   getSubstrateSignerFromExtension: () => import_pjs_signer.getPolkadotSignerFromPjs,
   hasCachedSession: () => hasCachedSession,
   hasInjectedExtensions: () => hasInjectedExtensions,
+  hasSourcePk: () => hasSourcePk,
   hexToBigint: () => hexToBigint,
   hexToNumber: () => hexToNumber,
   implicitSubstrateToEvm: () => implicitSubstrateToEvm,
@@ -195,6 +197,7 @@ __export(index_exports, {
   isConnectionLossError: () => isConnectionLossError,
   isEvmAddress: () => isEvmAddress,
   isGhostNoteError: () => isGhostNoteError,
+  isHexOfLength: () => isHexOfLength,
   isImplicitEvmAccount: () => isImplicitEvmAccount,
   isNativeAsset: () => isNativeAsset,
   isNoteSelfConsistent: () => isNoteSelfConsistent,
@@ -207,6 +210,7 @@ __export(index_exports, {
   mapExtrinsicArgs: () => mapExtrinsicArgs,
   mapZkEventData: () => mapZkEventData,
   markInputsSpent: () => markInputsSpent,
+  mergeProvenance: () => mergeProvenance,
   normalizeChainFingerprint: () => normalizeChainFingerprint,
   normalizeEvmAddress: () => normalizeEvmAddress,
   normalizeNote: () => normalizeNote,
@@ -221,6 +225,7 @@ __export(index_exports, {
   noteTxKind: () => noteTxKind,
   openOutgoingBlob: () => openOutgoingBlob,
   openPaymentSlip: () => openPaymentSlip,
+  outranks: () => outranks,
   pairwiseEphWindow: () => pairwiseEphWindow,
   palletErrorKind: () => palletErrorKind,
   parseAmount: () => parseAmount,
@@ -235,6 +240,7 @@ __export(index_exports, {
   recoverOwnerPkPoint: () => recoverOwnerPkPoint,
   recoverSelfStealthNote: () => recoverSelfStealthNote,
   refuseIfAlreadySpent: () => refuseIfAlreadySpent,
+  regeneratePaymentSlip: () => regeneratePaymentSlip,
   removeByCommitment: () => removeByCommitment,
   requireSessionKeys: () => requireSessionKeys,
   reservePairwiseIndex: () => reservePairwiseIndex,
@@ -248,6 +254,8 @@ __export(index_exports, {
   scanAbortError: () => scanAbortError,
   sealOutgoingBlob: () => sealOutgoingBlob,
   sealPaymentSlip: () => sealPaymentSlip,
+  selectDescribingNote: () => selectDescribingNote,
+  selectDescribingNoteByCommitment: () => selectDescribingNoteByCommitment,
   selectGhosts: () => selectGhosts,
   selectNotes: () => selectNotes,
   selfEphWindow: () => selfEphWindow,
@@ -285,6 +293,9 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/foundation/encoding/hex.ts
+function isHexOfLength(value, byteLen) {
+  return typeof value === "string" && new RegExp(`^0x[0-9a-fA-F]{${byteLen * 2}}$`).test(value);
+}
 function toHex(bytes) {
   return "0x" + Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
 }
@@ -293,11 +304,12 @@ function fromHex(hex) {
   if (clean.length % 2 !== 0) {
     throw new Error(`Invalid hex string \u2014 odd length: "${hex}"`);
   }
+  if (!/^[0-9a-fA-F]*$/.test(clean)) {
+    throw new Error("Invalid hex string \u2014 non-hex characters");
+  }
   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;
+    bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
   }
   return bytes;
 }
@@ -315,7 +327,13 @@ function scalarToHex(value) {
 }
 
 // src/foundation/encoding/bytes.ts
+function assert32ByteRange(n, fn) {
+  if (n < 0n || n >= 1n << 256n) {
+    throw new Error(`${fn}: value does not fit in 32 bytes: ${n}`);
+  }
+}
 function bigintTo32Le(n) {
+  assert32ByteRange(n, "bigintTo32Le");
   const buf = new Uint8Array(32);
   let v = n;
   for (let i = 0; i < 32; i++) {
@@ -332,6 +350,7 @@ function bytesToBigintLE(bytes) {
   return result;
 }
 function bigintTo32Be(n) {
+  assert32ByteRange(n, "bigintTo32Be");
   const buf = new Uint8Array(32);
   let v = n;
   for (let i = 31; i >= 0 && v > 0n; i--) {
@@ -341,6 +360,7 @@ function bigintTo32Be(n) {
   return buf;
 }
 function bigintTo32LeArr(n) {
+  assert32ByteRange(n, "bigintTo32LeArr");
   const out = new Array(32).fill(0);
   let v = n;
   for (let i = 0; i < 32; i++) {
@@ -827,7 +847,7 @@ var import_sha22 = require("@noble/hashes/sha2.js");
 var KEY_DOMAIN = new TextEncoder().encode("orbinum-note-encryption-v1");
 var VIEW_TAG_DOMAIN = new TextEncoder().encode("orbinum-view-tag-v1");
 var MEMO_PLAINTEXT_SIZE = 120;
-function serializeMemo(value, ownerPk, blinding, assetId, counterpartyPk, circuitVersion) {
+function serializeMemo(value, ownerPk, blinding, assetId, sourcePk, circuitVersion) {
   const buf = new Uint8Array(MEMO_PLAINTEXT_SIZE);
   const view = new DataView(buf.buffer);
   view.setBigUint64(0, value & 0xffffffffffffffffn, true);
@@ -835,7 +855,7 @@ function serializeMemo(value, ownerPk, blinding, assetId, counterpartyPk, circui
   buf.set(ownerPk.slice(0, 32), 16);
   buf.set(blinding.slice(0, 32), 48);
   view.setUint32(80, assetId >>> 0, true);
-  buf.set(counterpartyPk.slice(0, 32), 84);
+  buf.set(sourcePk.slice(0, 32), 84);
   view.setUint32(116, circuitVersion >>> 0, true);
   return buf;
 }
@@ -873,9 +893,9 @@ function parsePlaintext(nonce, ciphertextWithMac, encKey) {
     const ownerPk = bytesToBigintLE(plaintext.slice(16, 48));
     const blinding = bytesToBigintLE(plaintext.slice(48, 80));
     const assetId = BigInt(view.getUint32(80, true));
-    const counterpartyPk = bytesToBigintLE(plaintext.slice(84, 116));
+    const sourcePk = bytesToBigintLE(plaintext.slice(84, 116));
     const circuitVersion = view.getUint32(116, true);
-    return { value, ownerPk, blinding, assetId, counterpartyPk, circuitVersion };
+    return { value, ownerPk, blinding, assetId, sourcePk, circuitVersion };
   } catch {
     return null;
   }
@@ -893,19 +913,19 @@ var EncryptedMemo = {
    *                           (from PrivacyKeyManager.getViewingPublicKeyPacked() or
    *                           decoded from a privacy address).
    *                           Pass `new Uint8Array(32)` (all zeros) for a publicly-readable memo.
-   * @param counterpartyPk     32-byte counterparty BJJ Ax. Default: all zeros.
+   * @param sourcePk     32-byte counterparty BJJ Ax. Default: all zeros.
    * @param circuitVersion     ZK circuit version the note is spent under. Default: 0.
    * @param ephSkOverride      32-byte ephemeral secret key (stealth coordination). Optional.
    * @returns 180-byte encrypted memo: nonce(12) || ciphertext+MAC(136) || ephPk(32).
    */
-  encrypt(value, ownerPk, blinding, assetId, commitment, recipientIvkPacked, counterpartyPk = new Uint8Array(32), circuitVersion = 0, ephSkOverride) {
+  encrypt(value, ownerPk, blinding, assetId, commitment, recipientIvkPacked, sourcePk = new Uint8Array(32), circuitVersion = 0, ephSkOverride) {
     const nonce = (0, import_utils.randomBytes)(NONCE_SIZE);
     const plaintext = serializeMemo(
       value,
       ownerPk,
       blinding,
       assetId,
-      counterpartyPk,
+      sourcePk,
       circuitVersion
     );
     const isZeroKey = recipientIvkPacked.every((b) => b === 0);
@@ -1117,10 +1137,72 @@ var import_utils3 = require("@noble/ciphers/utils.js");
 var import_hkdf3 = require("@noble/hashes/hkdf.js");
 var import_sha24 = require("@noble/hashes/sha2.js");
 var import_baby_jubjub4 = require("@zk-kit/baby-jubjub");
+
+// src/protocol/spend/coinSelection.ts
+var TRANSFER_TREE_DEPTH = 20;
+var LEAVES_PER_TREE = 1 << TRANSFER_TREE_DEPTH;
+function isValidLeafIndex(leafIndex) {
+  return leafIndex !== null && leafIndex !== void 0 && Number.isSafeInteger(leafIndex) && leafIndex >= 0 && leafIndex < 2 ** 32;
+}
+function treeIdOf(note) {
+  const idx = note.leafIndex;
+  return isValidLeafIndex(idx) ? Math.floor(idx / LEAVES_PER_TREE) : 0;
+}
+function isSpendable(note) {
+  return !note.spent && note.value > 0n;
+}
+function canPairWith(a, b) {
+  return a.circuitVersion === b.circuitVersion && treeIdOf(a) === treeIdOf(b);
+}
+function selectNotes(notes, needed) {
+  const unspent = notes.filter(isSpendable);
+  const sorted = [...unspent].sort((a, b) => a.value < b.value ? -1 : 1);
+  const single = sorted.find((n) => n.value >= needed);
+  if (single) return [single, null];
+  for (let i = 0; i < sorted.length; i++) {
+    for (let j = i + 1; j < sorted.length; j++) {
+      const a = sorted[i];
+      const b = sorted[j];
+      if (a !== void 0 && b !== void 0 && canPairWith(a, b) && a.value + b.value >= needed) {
+        return [a, b];
+      }
+    }
+  }
+  for (let i = 0; i < sorted.length; i++) {
+    for (let j = i + 1; j < sorted.length; j++) {
+      const a = sorted[i];
+      const b = sorted[j];
+      if (a !== void 0 && b !== void 0 && a.circuitVersion === b.circuitVersion && a.value + b.value >= needed) {
+        return { needsConsolidation: true };
+      }
+    }
+  }
+  return null;
+}
+function buildDummyTransferInput(assetId) {
+  const zeroSibling = "0x" + "00".repeat(32);
+  return {
+    nullifier: 0n,
+    // Constraint 9: nullifier * is_dummy.out === 0 → must be 0
+    value: 0n,
+    // triggers is_dummy[i].out = 1 in the circuit
+    assetId,
+    // must match real note (Constraint 7)
+    ownerPk: 0n,
+    blinding: 0n,
+    spendingKey: 1n,
+    // arbitrary; EdDSA is disabled (enabled = 0) for dummy inputs
+    pathSiblings: Array(TRANSFER_TREE_DEPTH).fill(zeroSibling),
+    leafIndex: 0
+  };
+}
+
+// src/protocol/memo/PaymentSlip.ts
 var SLIP_DOMAIN = new TextEncoder().encode("orbinum-payment-slip-v1");
 var NONCE_PREFIX2 = new TextEncoder().encode("SLP1");
 var EPH_PK_SIZE2 = 32;
 var NONCE_SUFFIX_SIZE2 = 8;
+var MAX_SLIP_ENVELOPE_SIZE = 4096;
 function deriveSlipKey(sharedSecret) {
   return (0, import_hkdf3.hkdf)(import_sha24.sha256, sharedSecret, void 0, SLIP_DOMAIN, 32);
 }
@@ -1155,6 +1237,7 @@ function sealPaymentSlip(recipientIvkPacked, fields) {
 }
 function openPaymentSlip(recipientIvsk, envelope) {
   if (envelope.length < EPH_PK_SIZE2 + NONCE_SUFFIX_SIZE2 + 16) return null;
+  if (envelope.length > MAX_SLIP_ENVELOPE_SIZE) return null;
   try {
     const ephPkPacked = envelope.subarray(0, EPH_PK_SIZE2);
     const ephPkPoint = (0, import_baby_jubjub4.unpackPoint)(bytesToBigintLE(ephPkPacked));
@@ -1166,11 +1249,19 @@ function openPaymentSlip(recipientIvsk, envelope) {
     const sealed = envelope.subarray(EPH_PK_SIZE2 + NONCE_SUFFIX_SIZE2);
     const cipher = (0, import_chacha3.chacha20poly1305)(slipKey, buildNonce2(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;
   }
@@ -1299,14 +1390,14 @@ var NoteBuilder = class {
     const ownerPk = input.ownerPk ?? 0n;
     const blinding = input.blinding ?? BigInt(Date.now());
     const spendingKey = input.spendingKey ?? 0n;
-    const counterpartyPk = input.counterpartyPk ?? 0n;
+    const sourcePk = input.sourcePk ?? 0n;
     const circuitVersion = input.circuitVersion ?? CURRENT_CIRCUIT_VERSION;
     const useStealth = input.viewingPublicKey !== void 0 && input.recipientOwnerPk !== void 0;
     let memo;
     if (useStealth) {
       const recipientOwnerPk = input.recipientOwnerPk;
       const recipientIvkPacked = input.viewingPublicKey;
-      const ephSk = (0, import_utils4.randomBytes)(32);
+      const ephSk = input.ephSkOverride ?? (0, import_utils4.randomBytes)(32);
       const ivkPackedBigint = bytesToBigintLE(recipientIvkPacked);
       const ivkPoint = (0, import_baby_jubjub7.unpackPoint)(ivkPackedBigint);
       if (!ivkPoint)
@@ -1334,7 +1425,7 @@ var NoteBuilder = class {
           Number(assetId),
           stealthCommitmentBytes,
           recipientIvkPacked,
-          bigintTo32Le(counterpartyPk),
+          bigintTo32Le(sourcePk),
           circuitVersion,
           ephSk
         )
@@ -1376,7 +1467,7 @@ var NoteBuilder = class {
         commitmentHex: toHex(commitmentBytes2),
         nullifierHex: toHex(nullifierBytes2),
         memo,
-        counterpartyPk,
+        sourcePk,
         ...ovkBlob ? { ovkBlob } : {}
       };
     }
@@ -1392,7 +1483,7 @@ var NoteBuilder = class {
         Number(assetId),
         commitmentBytes,
         input.viewingPublicKey,
-        bigintTo32Le(counterpartyPk),
+        bigintTo32Le(sourcePk),
         circuitVersion,
         input.ephSkOverride
       )
@@ -1415,7 +1506,7 @@ var NoteBuilder = class {
       commitmentHex: toHex(commitmentBytes),
       nullifierHex: toHex(nullifierBytes),
       memo,
-      counterpartyPk
+      sourcePk
     };
   }
   /**
@@ -1427,10 +1518,10 @@ var NoteBuilder = class {
    * @param note                    The ZkNote whose fields populate the plaintext.
    * @param recipientIvkPacked      32-byte LE packed BJJ viewing public key of the recipient.
    *                                Pass `new Uint8Array(32)` (default) for a public/dummy memo.
-   * @param counterpartyPk          32-byte counterparty BabyJubJub Ax.
+   * @param sourcePk          32-byte counterparty BabyJubJub Ax.
    *                                Pass `new Uint8Array(32)` (default) for no counterparty.
    */
-  static buildMemo(note, recipientIvkPacked, counterpartyPk) {
+  static buildMemo(note, recipientIvkPacked, sourcePk) {
     return EncryptedMemo.encrypt(
       note.value,
       bigintTo32Le(note.ownerPk),
@@ -1438,7 +1529,7 @@ var NoteBuilder = class {
       Number(note.assetId),
       bigintTo32Le(note.commitment),
       recipientIvkPacked ?? new Uint8Array(32),
-      counterpartyPk ?? bigintTo32Le(note.counterpartyPk ?? 0n),
+      sourcePk ?? bigintTo32Le(note.sourcePk ?? 0n),
       note.circuitVersion
     );
   }
@@ -1446,67 +1537,6 @@ var NoteBuilder = class {
 
 // src/protocol/note/NoteDecryptor.ts
 var import_poseidon_lite2 = require("poseidon-lite");
-
-// src/protocol/spend/coinSelection.ts
-var TRANSFER_TREE_DEPTH = 20;
-var LEAVES_PER_TREE = 1 << TRANSFER_TREE_DEPTH;
-function isValidLeafIndex(leafIndex) {
-  return leafIndex !== null && leafIndex !== void 0 && Number.isSafeInteger(leafIndex) && leafIndex >= 0 && leafIndex < 2 ** 32;
-}
-function treeIdOf(note) {
-  const idx = note.leafIndex;
-  return isValidLeafIndex(idx) ? Math.floor(idx / LEAVES_PER_TREE) : 0;
-}
-function isSpendable(note) {
-  return !note.spent && note.value > 0n;
-}
-function canPairWith(a, b) {
-  return a.circuitVersion === b.circuitVersion && treeIdOf(a) === treeIdOf(b);
-}
-function selectNotes(notes, needed) {
-  const unspent = notes.filter(isSpendable);
-  const sorted = [...unspent].sort((a, b) => a.value < b.value ? -1 : 1);
-  const single = sorted.find((n) => n.value >= needed);
-  if (single) return [single, null];
-  for (let i = 0; i < sorted.length; i++) {
-    for (let j = i + 1; j < sorted.length; j++) {
-      const a = sorted[i];
-      const b = sorted[j];
-      if (a !== void 0 && b !== void 0 && canPairWith(a, b) && a.value + b.value >= needed) {
-        return [a, b];
-      }
-    }
-  }
-  for (let i = 0; i < sorted.length; i++) {
-    for (let j = i + 1; j < sorted.length; j++) {
-      const a = sorted[i];
-      const b = sorted[j];
-      if (a !== void 0 && b !== void 0 && a.circuitVersion === b.circuitVersion && a.value + b.value >= needed) {
-        return { needsConsolidation: true };
-      }
-    }
-  }
-  return null;
-}
-function buildDummyTransferInput(assetId) {
-  const zeroSibling = "0x" + "00".repeat(32);
-  return {
-    nullifier: 0n,
-    // Constraint 9: nullifier * is_dummy.out === 0 → must be 0
-    value: 0n,
-    // triggers is_dummy[i].out = 1 in the circuit
-    assetId,
-    // must match real note (Constraint 7)
-    ownerPk: 0n,
-    blinding: 0n,
-    spendingKey: 1n,
-    // arbitrary; EdDSA is disabled (enabled = 0) for dummy inputs
-    pathSiblings: Array(TRANSFER_TREE_DEPTH).fill(zeroSibling),
-    leafIndex: 0
-  };
-}
-
-// src/protocol/note/NoteDecryptor.ts
 function decryptAndVerifyPlaintext(memoBytes, commitmentBytes, sharedSecret, effectiveOwnerPk) {
   const plaintext = EncryptedMemo.decryptWithSharedSecret(
     memoBytes,
@@ -1597,7 +1627,7 @@ function tryDecryptNoteVerbose(commitment, viewingSecretKey, spendingKey, ownOwn
       commitmentHex: toHex(bigintTo32Le(recomputed)),
       nullifierHex: toHex(bigintTo32Le(nullifier)),
       memo: Array.from(memoBytes),
-      counterpartyPk: plaintext.counterpartyPk
+      sourcePk: plaintext.sourcePk
     }
   };
 }
@@ -1631,10 +1661,19 @@ function tryRecoverOutgoing(hint, ovk, opts) {
     assetId: plaintext.assetId,
     recipientStealthPk: plaintext.ownerPk,
     blinding: plaintext.blinding,
-    counterpartyPk: plaintext.counterpartyPk,
+    sourcePk: plaintext.sourcePk,
     circuitVersion: plaintext.circuitVersion
   };
 }
+function collectOutgoingFacts(hint) {
+  if (!isHexOfLength(hint.commitmentHex, 32)) return null;
+  if (!isHexOfLength(hint.encryptedMemo, ENCRYPTED_MEMO_SIZE)) return null;
+  return {
+    commitmentHex: hint.commitmentHex,
+    ...isValidLeafIndex(hint.leafIndex) ? { leafIndex: hint.leafIndex } : {},
+    encryptedMemo: hint.encryptedMemo
+  };
+}
 
 // src/protocol/note/NoteDisclosure.ts
 var import_poseidon_lite3 = require("poseidon-lite");
@@ -2769,11 +2808,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.
@@ -2831,10 +2876,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) {
@@ -2952,10 +3005,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
@@ -3376,7 +3460,11 @@ var ShieldedPoolModule = class {
    * Withdraws tokens from the shielded pool to a public address.
    * Submits as an UNSIGNED (gasless) transaction — fee is embedded in the ZK proof.
    * Pass a `signer` to fall back to signed submission (e.g. for testing).
-   * Extrinsic: shieldedPool.unshield(proof, merkleRoot, nullifier, assetId, amount, recipient, fee, changeCommitment, changeEncryptedMemo, relayer, circuitVersion)
+   * Extrinsic: shieldedPool.unshield(proof, merkleRoot, nullifier, assetId, amount, recipient, fee, changeCommitment, changeEncryptedMemo, circuitVersion)
+   *
+   * The relay fee recipient is NOT a parameter: the chain takes it from the
+   * dispatch origin. Submitting unsigned credits the block author; submitting
+   * through the EVM precompile credits whoever signed that transaction.
    */
   async unshield(params, signer, options) {
     const entry = resolveTx(this.substrate.unsafe, "ShieldedPool", "unshield");
@@ -3400,8 +3488,6 @@ var ShieldedPoolModule = class {
       fee: params.fee ?? 0n,
       change_commitment: changeCommitment,
       change_encrypted_memo: changeEncryptedMemo,
-      relayer: void 0,
-      // Option<H160> — None for direct Substrate submissions
       circuit_version: params.circuitVersion
     });
     if (signer) {
@@ -3413,7 +3499,11 @@ var ShieldedPoolModule = class {
    * Performs a private (shielded) transfer between two notes.
    * Submits as an UNSIGNED (gasless) transaction — fee is embedded in the ZK proof.
    * Pass a `signer` to fall back to signed submission (e.g. for testing).
-   * Extrinsic: shieldedPool.privateTransfer(proof, merkleRoot, nullifiers, commitments, memos, assetId, fee, relayer, circuitVersion)
+   * Extrinsic: shieldedPool.privateTransfer(proof, merkleRoot, nullifiers, commitments, memos, assetId, fee, circuitVersion)
+   *
+   * The relay fee recipient is NOT a parameter: the chain takes it from the
+   * dispatch origin. Submitting unsigned credits the block author; submitting
+   * through the EVM precompile credits whoever signed that transaction.
    */
   async privateTransfer(params, signer, options) {
     const nullifiers = params.inputs.map((inp) => inp.nullifier);
@@ -3434,8 +3524,6 @@ var ShieldedPoolModule = class {
       encrypted_memos: memos,
       asset_id: params.assetId,
       fee: params.fee ?? 0n,
-      relayer: void 0,
-      // Option<H160> — None for direct Substrate submissions
       circuit_version: params.circuitVersion
     });
     if (signer) {
@@ -3674,6 +3762,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) {
@@ -3681,14 +3786,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;
@@ -3711,25 +3812,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[]": {
@@ -3785,6 +3874,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) {
@@ -3792,228 +3997,127 @@ 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)`
+   * Extrinsic: `shieldedPool.privateTransfer(proof, merkleRoot, nullifiers,
+   * commitments, memos, assetId, fee, circuitVersion)` — eight arguments; see
+   * `buildPrivateTransferCalldata` for the encoding order.
    */
   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, fee, changeCommitment, changeEncryptedMemo,
+   * circuitVersion)` — ten arguments; see `buildUnshieldCalldata`.
    *
-   * Extrinsic: `shieldedPool.unshield(proof, merkleRoot, nullifier, assetId, amount, recipient)`
+   * **The relay fee goes to whoever `signer` is.** The chain takes the recipient
+   * from `msg.sender`, not from calldata, so the account behind this signer is
+   * the one credited — and it is also the one paying gas. Relaying on someone
+   * else's behalf and being paid for it is the same act here.
    */
   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, circuitVersion)` — seven arguments; see
+   * `buildClaimShieldedFeesCalldata`.
    */
-  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.
-   */
-  async estimatePrivateTransferGas(params, from) {
+  // ─── 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: this.buildPrivateTransferCalldata(params)
+      data: buildShieldCalldata(params),
+      value: `0x${params.amount.toString(16)}`
     });
   }
-  /**
-   * Estimates the EVM gas for an `unshield` call.
-   */
-  async estimateUnshieldGas(params, from) {
+  async estimatePrivateTransferGas(params, from) {
     return this.evm.estimateGas({
       from,
       to: this.addr,
-      data: this.buildUnshieldCalldata(params)
+      data: buildPrivateTransferCalldata(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)
-    });
+  async estimateUnshieldGas(params, from) {
+    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)
     });
   }
 };
@@ -4185,7 +4289,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);
   }
   /**
@@ -4325,6 +4429,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);
@@ -5103,9 +5208,13 @@ function methodOf(fnSig) {
   if (fnSig.startsWith("unshield(")) return "unshield";
   if (fnSig.startsWith("privateTransfer(")) return "privateTransfer";
   if (fnSig.startsWith("shieldBatch(")) return "shieldBatch";
+  if (fnSig.startsWith("claimShieldedFees(")) return "claimShieldedFees";
   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;
@@ -5115,6 +5224,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 } };
@@ -5125,6 +5235,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);
@@ -5154,18 +5265,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: {} };
@@ -5174,6 +5292,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);
@@ -5380,7 +5499,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;
 }
@@ -5529,7 +5648,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;
@@ -5598,9 +5717,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) {
@@ -5853,12 +5972,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.
@@ -6460,26 +6579,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;
@@ -6496,17 +6736,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 });
@@ -6517,7 +6757,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 ?? "",
@@ -6568,7 +6808,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
     },
@@ -6887,7 +7127,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.
@@ -6898,7 +7138,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");
@@ -7083,7 +7323,7 @@ async function unshieldNote(deps, params, onProgress) {
 var import_proof_generator8 = require("@orbinum/proof-generator");
 async function claimFees(deps, { assetId, amount, signer }, onStep) {
   onStep?.("building-note");
-  const note = await deps.buildNote({ value: amount, assetId: BigInt(assetId) });
+  const { note } = await deps.buildNote({ value: amount, assetId: BigInt(assetId) });
   const { provider } = await deps.resolver.resolve(import_proof_generator8.CircuitType.ValueProof, note.circuitVersion);
   onStep?.("generating-proof");
   const proofOutput = await generateFeeClaimProof(
@@ -7930,6 +8170,7 @@ var OrbinumWallet = class {
   clearKnownEphWindow,
   clearSession,
   collectNullifiersToQuery,
+  collectOutgoingFacts,
   collectScanEntries,
   commitmentHexOf,
   computeNoteCommitment,
@@ -8005,6 +8246,7 @@ var OrbinumWallet = class {
   getSubstrateSignerFromExtension,
   hasCachedSession,
   hasInjectedExtensions,
+  hasSourcePk,
   hexToBigint,
   hexToNumber,
   implicitSubstrateToEvm,
@@ -8016,6 +8258,7 @@ var OrbinumWallet = class {
   isConnectionLossError,
   isEvmAddress,
   isGhostNoteError,
+  isHexOfLength,
   isImplicitEvmAccount,
   isNativeAsset,
   isNoteSelfConsistent,
@@ -8028,6 +8271,7 @@ var OrbinumWallet = class {
   mapExtrinsicArgs,
   mapZkEventData,
   markInputsSpent,
+  mergeProvenance,
   normalizeChainFingerprint,
   normalizeEvmAddress,
   normalizeNote,
@@ -8042,6 +8286,7 @@ var OrbinumWallet = class {
   noteTxKind,
   openOutgoingBlob,
   openPaymentSlip,
+  outranks,
   pairwiseEphWindow,
   palletErrorKind,
   parseAmount,
@@ -8056,6 +8301,7 @@ var OrbinumWallet = class {
   recoverOwnerPkPoint,
   recoverSelfStealthNote,
   refuseIfAlreadySpent,
+  regeneratePaymentSlip,
   removeByCommitment,
   requireSessionKeys,
   reservePairwiseIndex,
@@ -8069,6 +8315,8 @@ var OrbinumWallet = class {
   scanAbortError,
   sealOutgoingBlob,
   sealPaymentSlip,
+  selectDescribingNote,
+  selectDescribingNoteByCommitment,
   selectGhosts,
   selectNotes,
   selfEphWindow,