@orbinum/sdk 2.0.0 → 2.1.0

package/dist/index.d.mts

@@ -2215,6 +2215,18 @@ interface UnshieldProofResult extends ProofResult {
  */
 declare function generateUnshieldProof(inputs: UnshieldProofInputs, options?: ProofOptions): Promise<UnshieldProofResult>;
 
+/**
+ * Witness assembly for the fee-claim circuit — accrued relayer fees minted
+ * straight into a shielded note.
+ *
+ * No input note and no merkle path: this proves knowledge of a commitment's
+ * preimage, so the chain can check the note encodes exactly the amount being
+ * claimed and a relayer cannot inflate its own payout.
+ *
+ * The public signals are a fixed 76-byte buffer the runtime parses by offset,
+ * so their layout is a wire contract rather than an implementation detail.
+ */
+
 /**
  * Inputs required to generate a fee-claim proof.
  *
@@ -3080,6 +3092,23 @@ type ShieldParams = {
     /** Encrypted memo bytes (180 bytes). Required — notes without valid memos are irrecoverable. */
     encryptedMemo: Uint8Array;
 };
+/**
+ * How the relay fee recipient is decided.
+ *
+ * It is not a parameter anywhere in this module: the chain reads it from the
+ * dispatch origin, which calldata cannot influence. A `relayer` field would be an
+ * unauthenticated claim — anyone could take a propagated proof, resubmit it
+ * naming themselves, and collect a fee they never paid for.
+ *
+ * | Submitted via | Credited |
+ * |---|---|
+ * | EVM precompile | whoever signed that EVM transaction and paid its gas |
+ * | Signed extrinsic | the signer's registered EVM address |
+ * | Unsigned extrinsic | the block author |
+ *
+ * `fee` below still matters: it is a ZK public input, so it cannot be altered
+ * without regenerating the proof. Only the *recipient* moved to the origin.
+ */
 /** Parameters for shieldedPool.unshield — withdraws from the pool to a clear address. */
 type UnshieldParams = {
     /** ZK proof bytes */
@@ -3187,7 +3216,9 @@ type ClaimShieldedFeesParams = {
  * which means the Orbinum node must be reachable on first use.
  * Signing is delegated to a SubstrateSigner (see polkadot-api/signer).
  *
- * Parameter order matches the Orbinum runtime extrinsics exactly.
+ * Arguments are passed BY NAME through PAPI, so the field names — not the
+ * order — have to match the runtime's. A renamed parameter fails at
+ * encoding rather than silently shifting a value into the wrong slot.
  */
 declare class ShieldedPoolModule {
     private readonly substrate;
@@ -3204,14 +3235,22 @@ declare class ShieldedPoolModule {
      * 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.
      */
     unshield(params: UnshieldParams, signer?: PolkadotSigner, options?: SubmitOptions): Promise<TxResult>;
     /**
      * 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.
      */
     privateTransfer(params: PrivateTransferParams, signer?: PolkadotSigner, options?: SubmitOptions): Promise<TxResult>;
     /**
@@ -3394,7 +3433,9 @@ declare class ShieldedPoolPrecompile {
      * 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.
      */
     privateTransfer(params: PrivateTransferParams, signer: EvmSigner): Promise<string>;
     /**
@@ -3403,7 +3444,14 @@ declare class ShieldedPoolPrecompile {
      * `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)`
+     * Extrinsic: `shieldedPool.unshield(proof, merkleRoot, nullifier, assetId,
+     * amount, recipient, fee, changeCommitment, changeEncryptedMemo,
+     * circuitVersion)` — ten arguments; see `buildUnshieldCalldata`.
+     *
+     * **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.
      */
     unshield(params: UnshieldParams, signer: EvmSigner): Promise<string>;
     /**
@@ -3419,7 +3467,9 @@ declare class ShieldedPoolPrecompile {
      * 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)`
+     * Extrinsic: `shieldedPool.claim_shielded_fees(commitment, amount, assetId,
+     * memo, proof, publicSignals, circuitVersion)` — seven arguments; see
+     * `buildClaimShieldedFeesCalldata`.
      */
     claimShieldedFees(params: ClaimShieldedFeesParams, signer: EvmSigner): Promise<string>;
     estimateShieldGas(params: ShieldParams, from: string): Promise<bigint>;
@@ -3904,13 +3954,18 @@ declare function isGhostNoteError(rawMessage: string): boolean;
  * `fee`, and without this a host is left reverse-engineering the number from a
  * failed extrinsic.
  *
- * A runtime upgrade can change these. They are exported as the current chain's
- * values, which is what every caller needs today; a chain that has moved on
- * should pass its own.
+ * These are the current chain's values, which is what every caller needs today.
+ * A chain that has moved on should pass its own — and note that not all of them
+ * need a runtime upgrade to move: see `MIN_GASLESS_FEE`.
  */
 /**
  * Smallest fee an unsigned (gasless) shielded-pool extrinsic may carry, in
- * planck. Mirrors the runtime's `MinGaslessFee`.
+ * planck — the default of `pallet-relayer`'s `MinRelayFee`.
+ *
+ * MUTABLE STORAGE, not a runtime constant: governance moves it with
+ * `set_min_relay_fee`, no upgrade required. A wallet that hardcodes this value
+ * starts failing with `FeeTooLow` the moment the floor rises, so read
+ * `min_relay_fee()` when the answer has to be current.
  *
  * Below it the pallet rejects with `FeeTooLow`. The fee is paid to the block
  * author by the runtime, which is what lets a user with no public balance spend
@@ -4317,10 +4372,13 @@ declare function getPrecompileLabel(address: string | null | undefined): string
  * `unshield` — a classifier that checks in the wrong order reports every
  * unshield as a shield, silently, and a new pallet method breaks it again.
  */
-type PrecompileMethod = 'shield' | 'unshield' | 'privateTransfer' | 'shieldBatch';
+type PrecompileMethod = 'shield' | 'unshield' | 'privateTransfer' | 'shieldBatch' | 'claimShieldedFees';
 type DecodedPrecompile = {
     fnSig: string;
-    /** The operation, from the selector. Null for a known precompile's unmapped call. */
+    /**
+     * The operation, from the selector. Null only when the args below could not
+     * be decoded either — every signature this file decodes maps to a name.
+     */
     method: PrecompileMethod | null;
     args: Record<string, unknown>;
 };
@@ -5357,7 +5415,9 @@ interface FeeClaimDeps {
     buildNote: (params: {
         value: bigint;
         assetId: bigint;
-    }) => Promise<ZkNote>;
+    }) => Promise<{
+        note: ZkNote;
+    }>;
     resolver: Pick<CircuitVersionResolver, 'resolve'>;
     pool: Pick<ShieldedPoolModule, 'claimShieldedFees'>;
     /** Where the minted note lands once the claim finalizes. */

package/dist/index.d.ts

@@ -2215,6 +2215,18 @@ interface UnshieldProofResult extends ProofResult {
  */
 declare function generateUnshieldProof(inputs: UnshieldProofInputs, options?: ProofOptions): Promise<UnshieldProofResult>;
 
+/**
+ * Witness assembly for the fee-claim circuit — accrued relayer fees minted
+ * straight into a shielded note.
+ *
+ * No input note and no merkle path: this proves knowledge of a commitment's
+ * preimage, so the chain can check the note encodes exactly the amount being
+ * claimed and a relayer cannot inflate its own payout.
+ *
+ * The public signals are a fixed 76-byte buffer the runtime parses by offset,
+ * so their layout is a wire contract rather than an implementation detail.
+ */
+
 /**
  * Inputs required to generate a fee-claim proof.
  *
@@ -3080,6 +3092,23 @@ type ShieldParams = {
     /** Encrypted memo bytes (180 bytes). Required — notes without valid memos are irrecoverable. */
     encryptedMemo: Uint8Array;
 };
+/**
+ * How the relay fee recipient is decided.
+ *
+ * It is not a parameter anywhere in this module: the chain reads it from the
+ * dispatch origin, which calldata cannot influence. A `relayer` field would be an
+ * unauthenticated claim — anyone could take a propagated proof, resubmit it
+ * naming themselves, and collect a fee they never paid for.
+ *
+ * | Submitted via | Credited |
+ * |---|---|
+ * | EVM precompile | whoever signed that EVM transaction and paid its gas |
+ * | Signed extrinsic | the signer's registered EVM address |
+ * | Unsigned extrinsic | the block author |
+ *
+ * `fee` below still matters: it is a ZK public input, so it cannot be altered
+ * without regenerating the proof. Only the *recipient* moved to the origin.
+ */
 /** Parameters for shieldedPool.unshield — withdraws from the pool to a clear address. */
 type UnshieldParams = {
     /** ZK proof bytes */
@@ -3187,7 +3216,9 @@ type ClaimShieldedFeesParams = {
  * which means the Orbinum node must be reachable on first use.
  * Signing is delegated to a SubstrateSigner (see polkadot-api/signer).
  *
- * Parameter order matches the Orbinum runtime extrinsics exactly.
+ * Arguments are passed BY NAME through PAPI, so the field names — not the
+ * order — have to match the runtime's. A renamed parameter fails at
+ * encoding rather than silently shifting a value into the wrong slot.
  */
 declare class ShieldedPoolModule {
     private readonly substrate;
@@ -3204,14 +3235,22 @@ declare class ShieldedPoolModule {
      * 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.
      */
     unshield(params: UnshieldParams, signer?: PolkadotSigner, options?: SubmitOptions): Promise<TxResult>;
     /**
      * 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.
      */
     privateTransfer(params: PrivateTransferParams, signer?: PolkadotSigner, options?: SubmitOptions): Promise<TxResult>;
     /**
@@ -3394,7 +3433,9 @@ declare class ShieldedPoolPrecompile {
      * 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.
      */
     privateTransfer(params: PrivateTransferParams, signer: EvmSigner): Promise<string>;
     /**
@@ -3403,7 +3444,14 @@ declare class ShieldedPoolPrecompile {
      * `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)`
+     * Extrinsic: `shieldedPool.unshield(proof, merkleRoot, nullifier, assetId,
+     * amount, recipient, fee, changeCommitment, changeEncryptedMemo,
+     * circuitVersion)` — ten arguments; see `buildUnshieldCalldata`.
+     *
+     * **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.
      */
     unshield(params: UnshieldParams, signer: EvmSigner): Promise<string>;
     /**
@@ -3419,7 +3467,9 @@ declare class ShieldedPoolPrecompile {
      * 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)`
+     * Extrinsic: `shieldedPool.claim_shielded_fees(commitment, amount, assetId,
+     * memo, proof, publicSignals, circuitVersion)` — seven arguments; see
+     * `buildClaimShieldedFeesCalldata`.
      */
     claimShieldedFees(params: ClaimShieldedFeesParams, signer: EvmSigner): Promise<string>;
     estimateShieldGas(params: ShieldParams, from: string): Promise<bigint>;
@@ -3904,13 +3954,18 @@ declare function isGhostNoteError(rawMessage: string): boolean;
  * `fee`, and without this a host is left reverse-engineering the number from a
  * failed extrinsic.
  *
- * A runtime upgrade can change these. They are exported as the current chain's
- * values, which is what every caller needs today; a chain that has moved on
- * should pass its own.
+ * These are the current chain's values, which is what every caller needs today.
+ * A chain that has moved on should pass its own — and note that not all of them
+ * need a runtime upgrade to move: see `MIN_GASLESS_FEE`.
  */
 /**
  * Smallest fee an unsigned (gasless) shielded-pool extrinsic may carry, in
- * planck. Mirrors the runtime's `MinGaslessFee`.
+ * planck — the default of `pallet-relayer`'s `MinRelayFee`.
+ *
+ * MUTABLE STORAGE, not a runtime constant: governance moves it with
+ * `set_min_relay_fee`, no upgrade required. A wallet that hardcodes this value
+ * starts failing with `FeeTooLow` the moment the floor rises, so read
+ * `min_relay_fee()` when the answer has to be current.
  *
  * Below it the pallet rejects with `FeeTooLow`. The fee is paid to the block
  * author by the runtime, which is what lets a user with no public balance spend
@@ -4317,10 +4372,13 @@ declare function getPrecompileLabel(address: string | null | undefined): string
  * `unshield` — a classifier that checks in the wrong order reports every
  * unshield as a shield, silently, and a new pallet method breaks it again.
  */
-type PrecompileMethod = 'shield' | 'unshield' | 'privateTransfer' | 'shieldBatch';
+type PrecompileMethod = 'shield' | 'unshield' | 'privateTransfer' | 'shieldBatch' | 'claimShieldedFees';
 type DecodedPrecompile = {
     fnSig: string;
-    /** The operation, from the selector. Null for a known precompile's unmapped call. */
+    /**
+     * The operation, from the selector. Null only when the args below could not
+     * be decoded either — every signature this file decodes maps to a name.
+     */
     method: PrecompileMethod | null;
     args: Record<string, unknown>;
 };
@@ -5357,7 +5415,9 @@ interface FeeClaimDeps {
     buildNote: (params: {
         value: bigint;
         assetId: bigint;
-    }) => Promise<ZkNote>;
+    }) => Promise<{
+        note: ZkNote;
+    }>;
     resolver: Pick<CircuitVersionResolver, 'resolve'>;
     pool: Pick<ShieldedPoolModule, 'claimShieldedFees'>;
     /** Where the minted note lands once the claim finalizes. */

package/dist/index.js

@@ -3460,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");
@@ -3484,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) {
@@ -3497,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);
@@ -3518,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) {
@@ -4036,7 +4040,9 @@ var ShieldedPoolPrecompile = class {
    * 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: buildPrivateTransferCalldata(params) });
@@ -4048,7 +4054,14 @@ var ShieldedPoolPrecompile = class {
    * `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)`
+   * Extrinsic: `shieldedPool.unshield(proof, merkleRoot, nullifier, assetId,
+   * amount, recipient, fee, changeCommitment, changeEncryptedMemo,
+   * circuitVersion)` — ten arguments; see `buildUnshieldCalldata`.
+   *
+   * **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: buildUnshieldCalldata(params) });
@@ -4067,7 +4080,9 @@ var ShieldedPoolPrecompile = class {
    * 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)`
+   * Extrinsic: `shieldedPool.claim_shielded_fees(commitment, amount, assetId,
+   * memo, proof, publicSignals, circuitVersion)` — seven arguments; see
+   * `buildClaimShieldedFeesCalldata`.
    */
   async claimShieldedFees(params, signer) {
     return signer({
@@ -4081,7 +4096,12 @@ var ShieldedPoolPrecompile = class {
   // 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) });
+    return this.evm.estimateGas({
+      from,
+      to: this.addr,
+      data: buildShieldCalldata(params),
+      value: `0x${params.amount.toString(16)}`
+    });
   }
   async estimatePrivateTransferGas(params, from) {
     return this.evm.estimateGas({
@@ -5188,6 +5208,7 @@ 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;
 }
@@ -7302,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(

package/dist/index.mjs

@@ -2200,7 +2200,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");
@@ -2224,8 +2228,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) {
@@ -2237,7 +2239,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);
@@ -2258,8 +2264,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) {
@@ -2776,7 +2780,9 @@ var ShieldedPoolPrecompile = class {
    * 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: buildPrivateTransferCalldata(params) });
@@ -2788,7 +2794,14 @@ var ShieldedPoolPrecompile = class {
    * `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)`
+   * Extrinsic: `shieldedPool.unshield(proof, merkleRoot, nullifier, assetId,
+   * amount, recipient, fee, changeCommitment, changeEncryptedMemo,
+   * circuitVersion)` — ten arguments; see `buildUnshieldCalldata`.
+   *
+   * **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: buildUnshieldCalldata(params) });
@@ -2807,7 +2820,9 @@ var ShieldedPoolPrecompile = class {
    * 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)`
+   * Extrinsic: `shieldedPool.claim_shielded_fees(commitment, amount, assetId,
+   * memo, proof, publicSignals, circuitVersion)` — seven arguments; see
+   * `buildClaimShieldedFeesCalldata`.
    */
   async claimShieldedFees(params, signer) {
     return signer({
@@ -2821,7 +2836,12 @@ var ShieldedPoolPrecompile = class {
   // 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) });
+    return this.evm.estimateGas({
+      from,
+      to: this.addr,
+      data: buildShieldCalldata(params),
+      value: `0x${params.amount.toString(16)}`
+    });
   }
   async estimatePrivateTransferGas(params, from) {
     return this.evm.estimateGas({
@@ -3935,6 +3955,7 @@ 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;
 }
@@ -6038,7 +6059,7 @@ async function unshieldNote(deps, params, onProgress) {
 import { CircuitType as CircuitType7 } from "@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(CircuitType7.ValueProof, note.circuitVersion);
   onStep?.("generating-proof");
   const proofOutput = await generateFeeClaimProof(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orbinum/sdk",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Official TypeScript SDK for Orbinum.",
   "author": "Orbinum",
   "license": "MIT",