@chironbuilder/ootle-sdk 0.1.8 → 0.1.9

package/dist/accountApi.d.ts

@@ -1,11 +1,16 @@
 import type { IndexerProvider } from "@tari-project/ootle-indexer";
 import type { Instruction, SubstateRequirement } from "@tari-project/ootle-ts-bindings";
-import type { TokenBalance } from "./wallet.js";
+import type { FeeType, TokenBalance } from "./wallet.js";
 export interface TransactionExecuteOpts {
     maxFee?: bigint;
     dryRun?: boolean;
     inputs?: SubstateRequirement[];
     maxRetries?: number;
+    /** See `FeeType`'s own doc comment. `OotleAccount` honors this; a `DaemonAccount`
+     * (walletd-relayed) implementation of this interface must implement its own support or
+     * explicitly reject `{ kind: "private" }` -- there is no default private-fee behavior a shared
+     * interface can provide for a backend this package doesn't talk to. */
+    feeType?: FeeType;
 }
 /**
  * Shared surface both `OotleAccount` (this extension's own seed-derived signer) and `DaemonAccount`
@@ -27,7 +32,7 @@ export interface WalletAccountApi {
      * requires the owner public key the wallet address encodes; a bare component address never
      * reveals it, so that form can only pay an account that already exists). Prefer asking senders
      * for the wallet address — it's the one form that always works. */
-    send(recipientAddress: string, resourceAddress: string, amount: bigint, maxFee?: bigint): Promise<unknown>;
+    send(recipientAddress: string, resourceAddress: string, amount: bigint, maxFee?: bigint, feeType?: FeeType): Promise<unknown>;
     claimTestnetXtr(): Promise<unknown>;
 }
 //# sourceMappingURL=accountApi.d.ts.map

package/dist/accountApi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"accountApi.d.ts","sourceRoot":"","sources":["../src/accountApi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACxF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,WAAW,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IACvC;2FACuF;IACvF,WAAW,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;IACxC,OAAO,CAAC,YAAY,EAAE,WAAW,EAAE,EAAE,IAAI,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtF;;;;;uEAKmE;IACnE,IAAI,CAAC,gBAAgB,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3G,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CACrC"}
+{"version":3,"file":"accountApi.d.ts","sourceRoot":"","sources":["../src/accountApi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACxF,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEzD,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;2EAGuE;IACvE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,WAAW,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IACvC;2FACuF;IACvF,WAAW,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;IACxC,OAAO,CAAC,YAAY,EAAE,WAAW,EAAE,EAAE,IAAI,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtF;;;;;uEAKmE;IACnE,IAAI,CAAC,gBAAgB,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9H,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CACrC"}

package/dist/index.d.ts

@@ -16,6 +16,6 @@ export { withTimeout } from "./timeout.js";
 export type { KeyValueStore, PendingShield, ShieldedOutputRecord } from "./storage.js";
 export { addPendingShield, addShieldedOutput, configureOotleStorage, getKnownVersions, getPrivatePaymentScanCursor, listPendingShields, listShieldedOutputs, localAccountId, markShieldedOutputSpent, removePendingShield, serialized, setKnownVersions, setPrivatePaymentScanCursor, wipeOotleState, } from "./storage.js";
 export { chromeStorageAdapter, inMemoryAdapter, localStorageAdapter } from "./adapters.js";
-export type { PrivateBalance, TokenBalance } from "./wallet.js";
-export { OotleAccount, assertValidMinimumValuePromise, buildHtlcSpendStatement, extractMissingSubstateAddress, extractStaleLockVersion, forgetKnownVersions, pollTransactionResult, recoverPendingShields, resetKnownVersions, resolveInputsWithRetry, resolveSendPrivatelyPlan, resolveUnshieldPlan, selectShieldedUtxosForAmount, selectUnspentShieldedOutputs, substateExists, summarizePrivateHoldings, synthesizeShieldedOnlyBalances, } from "./wallet.js";
+export type { FeeType, PrivateBalance, TokenBalance } from "./wallet.js";
+export { OotleAccount, assertValidMinimumValuePromise, buildHtlcSpendStatement, extractMissingSubstateAddress, extractStaleLockVersion, forgetKnownVersions, pollTransactionResult, recoverPendingShields, resetKnownVersions, resolveInputsWithRetry, resolveSendPrivatelyPlan, resolveUnshieldPlan, selectPrivateFeeUtxo, selectShieldedUtxosForAmount, selectUnspentShieldedOutputs, substateExists, summarizePrivateHoldings, synthesizeShieldedOnlyBalances, } from "./wallet.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEhF,OAAO,EACL,wBAAwB,EACxB,iCAAiC,EACjC,6BAA6B,EAC7B,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,EAAE,+BAA+B,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAEhG,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAEhI,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,4BAA4B,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEzE,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,oCAAoC,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAEpI,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExE,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACvF,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,2BAA2B,EAC3B,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,mBAAmB,EACnB,UAAU,EACV,gBAAgB,EAChB,2BAA2B,EAC3B,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAE3F,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EACL,YAAY,EACZ,8BAA8B,EAC9B,uBAAuB,EACvB,6BAA6B,EAC7B,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,wBAAwB,EACxB,mBAAmB,EACnB,4BAA4B,EAC5B,4BAA4B,EAC5B,cAAc,EACd,wBAAwB,EACxB,8BAA8B,GAC/B,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEhF,OAAO,EACL,wBAAwB,EACxB,iCAAiC,EACjC,6BAA6B,EAC7B,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,EAAE,+BAA+B,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAEhG,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAEhI,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,4BAA4B,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEzE,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,oCAAoC,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAEpI,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExE,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACvF,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,2BAA2B,EAC3B,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,mBAAmB,EACnB,UAAU,EACV,gBAAgB,EAChB,2BAA2B,EAC3B,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAE3F,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EACL,YAAY,EACZ,8BAA8B,EAC9B,uBAAuB,EACvB,6BAA6B,EAC7B,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,EACpB,4BAA4B,EAC5B,4BAA4B,EAC5B,cAAc,EACd,wBAAwB,EACxB,8BAA8B,GAC/B,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -11,4 +11,4 @@ export { decryptVault, encryptVault, fromHex, toHex } from "./vault.js";
 export { withTimeout } from "./timeout.js";
 export { addPendingShield, addShieldedOutput, configureOotleStorage, getKnownVersions, getPrivatePaymentScanCursor, listPendingShields, listShieldedOutputs, localAccountId, markShieldedOutputSpent, removePendingShield, serialized, setKnownVersions, setPrivatePaymentScanCursor, wipeOotleState, } from "./storage.js";
 export { chromeStorageAdapter, inMemoryAdapter, localStorageAdapter } from "./adapters.js";
-export { OotleAccount, assertValidMinimumValuePromise, buildHtlcSpendStatement, extractMissingSubstateAddress, extractStaleLockVersion, forgetKnownVersions, pollTransactionResult, recoverPendingShields, resetKnownVersions, resolveInputsWithRetry, resolveSendPrivatelyPlan, resolveUnshieldPlan, selectShieldedUtxosForAmount, selectUnspentShieldedOutputs, substateExists, summarizePrivateHoldings, synthesizeShieldedOnlyBalances, } from "./wallet.js";
+export { OotleAccount, assertValidMinimumValuePromise, buildHtlcSpendStatement, extractMissingSubstateAddress, extractStaleLockVersion, forgetKnownVersions, pollTransactionResult, recoverPendingShields, resetKnownVersions, resolveInputsWithRetry, resolveSendPrivatelyPlan, resolveUnshieldPlan, selectPrivateFeeUtxo, selectShieldedUtxosForAmount, selectUnspentShieldedOutputs, substateExists, summarizePrivateHoldings, synthesizeShieldedOnlyBalances, } from "./wallet.js";

package/dist/wallet.d.ts

@@ -6,6 +6,16 @@ import type { WalletAccountApi } from "./accountApi.js";
 import type { ScannedStealthOutput } from "./confidential.js";
 import { type NetworkName } from "./ootleNetwork.js";
 import type { ShieldedOutputRecord } from "./storage.js";
+/** How a transaction's fee is paid. Defaults to `transparent` everywhere (unchanged behavior:
+ * revealed balance, reveals the paying account on-chain). `private` instead spends a stealth
+ * UTXO of `feeResourceAddress` -- see `OotleAccount.buildPrivateFeeInstructions`'s doc comment
+ * for why this is single-UTXO only, and `selectPrivateFeeUtxo` for how one is chosen. */
+export type FeeType = {
+    kind: "transparent";
+} | {
+    kind: "private";
+    feeResourceAddress: string;
+};
 export interface TokenBalance {
     resourceAddress: string;
     kind: string;
@@ -129,10 +139,21 @@ export declare class OotleAccount implements WalletAccountApi {
         dryRun?: boolean;
         inputs?: SubstateRequirement[];
         maxRetries?: number;
+        /**
+         * Defaults to `{ kind: "transparent" }` (unchanged behavior: fee paid from the account's
+         * revealed balance, which reveals `account` on-chain). `{ kind: "private" }` instead pays
+         * from a shielded UTXO of `feeResourceAddress`, auto-selected via `selectPrivateFeeUtxo`
+         * (smallest unspent record that alone covers `maxFee` -- shield some first if none
+         * qualifies) -- see `buildPrivateFeeInstructions`'s doc comment for why this is
+         * single-UTXO only. `dryRun` never touches local storage even when private.
+         */
+        feeType?: FeeType;
     }): Promise<{
         transaction_id: TransactionId;
         result: ExecuteResult;
     } | (IndexerGetTransactionResultResponse & {
+        transaction_id: TransactionId;
+    } & {
         transactionId?: string;
     })>;
     /**
@@ -191,10 +212,12 @@ export declare class OotleAccount implements WalletAccountApi {
      * never reveals the owner key `CreateAccount` needs, so that form can only pay an account that
      * already exists.
      */
-    send(recipientAddress: string, resourceAddress: string, amount: bigint, maxFee?: bigint): Promise<{
+    send(recipientAddress: string, resourceAddress: string, amount: bigint, maxFee?: bigint, feeType?: FeeType): Promise<{
         transaction_id: TransactionId;
         result: ExecuteResult;
     } | (IndexerGetTransactionResultResponse & {
+        transaction_id: TransactionId;
+    } & {
         transactionId?: string;
     })>;
     /**
@@ -227,10 +250,12 @@ export declare class OotleAccount implements WalletAccountApi {
      * produces a bucket holding the one new confidential output, which `deposit` puts back in the
      * same vault.
      */
-    depositConfidential(resourceAddress: string, amount: bigint, maxFee?: bigint): Promise<{
+    depositConfidential(resourceAddress: string, amount: bigint, maxFee?: bigint, feeType?: FeeType): Promise<{
         transaction_id: TransactionId;
         result: ExecuteResult;
     } | (IndexerGetTransactionResultResponse & {
+        transaction_id: TransactionId;
+    } & {
         transactionId?: string;
     })>;
     /**
@@ -287,7 +312,7 @@ export declare class OotleAccount implements WalletAccountApi {
      * erring high just wastes nothing; erring low burns the small fee-intent cost with nothing to
      * show for it, since only the fee half of the transaction gets committed.
      */
-    shield(resourceAddress: string, amount: bigint, maxFee?: bigint, memo?: string, minimumValuePromise?: bigint): Promise<{
+    shield(resourceAddress: string, amount: bigint, maxFee?: bigint, memo?: string, minimumValuePromise?: bigint, feeType?: FeeType): Promise<{
         transactionId: string;
         commitment: string;
         substateId: string;
@@ -360,7 +385,7 @@ export declare class OotleAccount implements WalletAccountApi {
      * mark the spent ones, even if the service worker dies between finalization and the storage
      * writes.
      */
-    unshield(resourceAddress: string, revealedOutAmount: bigint, maxFee?: bigint, memo?: string): Promise<{
+    unshield(resourceAddress: string, revealedOutAmount: bigint, maxFee?: bigint, memo?: string, feeType?: FeeType): Promise<{
         transactionId: string;
     }>;
     /**
@@ -390,7 +415,7 @@ export declare class OotleAccount implements WalletAccountApi {
      *   substate with `SubstateNotFound`. Each is registered by address, plus every vault its own
      *   state references (the same vault-discovery this account's own address already gets).
      */
-    withdrawStealthAndExecute(resourceAddress: string, amount: bigint, workspaceVarName: string, followUpInstructions: Instruction[], relatedComponents?: string[], maxFee?: bigint): Promise<{
+    withdrawStealthAndExecute(resourceAddress: string, amount: bigint, workspaceVarName: string, followUpInstructions: Instruction[], relatedComponents?: string[], maxFee?: bigint, feeType?: FeeType): Promise<{
         transactionId: string;
     }>;
     /**
@@ -421,7 +446,7 @@ export declare class OotleAccount implements WalletAccountApi {
      * @param relatedComponents Every *other* component `followUpInstructions` touches — same
      *   reasoning as `withdrawStealthAndExecute`'s own parameter of the same name.
      */
-    redeemStealthOutputAndExecute(resourceAddress: string, commitmentHex: string, revealedAmount: bigint, followUpInstructions: Instruction[], relatedComponents?: string[], maxFee?: bigint): Promise<{
+    redeemStealthOutputAndExecute(resourceAddress: string, commitmentHex: string, revealedAmount: bigint, followUpInstructions: Instruction[], relatedComponents?: string[], maxFee?: bigint, feeType?: FeeType): Promise<{
         transactionId: string;
     }>;
     /**
@@ -467,6 +492,68 @@ export declare class OotleAccount implements WalletAccountApi {
      *   (which records its own outputs locally) — callers doing several of these in sequence must
      *   thread this value into the next call's `feeCommitmentHex` themselves.
      */
+    /**
+     * Builds the fee-payment instructions/inputs for spending a single stealth UTXO of
+     * `feeResourceAddress` to cover `maxFee`, plus the one-time `Signer` that must co-sign the
+     * resulting `StealthTransfer` fee spend (an ordinary account signature can't authorize a
+     * stealth spend -- see `redeemStealthOutputWithPrivateFee`'s doc comment, which this method's
+     * fee-half logic was extracted from verbatim). The unspent remainder above `maxFee` becomes a
+     * new stealth output back to this account (`feeChangeCommitment`); this only builds
+     * instructions, it doesn't touch local storage -- the caller records the change output (e.g.
+     * via `recordKnownShieldedOutput`) and marks `feeCommitmentHex` spent once the transaction
+     * actually lands, exactly as `redeemStealthOutputWithPrivateFee` itself does inline.
+     *
+     * Deliberately single-UTXO only, like the method this was extracted from -- the only shape
+     * confirmed live. Aggregating several stealth inputs into one `StealthTransfer` fee spend
+     * isn't proven here: `unshield()`'s multi-commitment coin selection uses a different,
+     * higher-level signing pipeline (`WalletStealthAuthorizer`) that isn't available inside this
+     * raw `TransactionBuilder`/`resolveTransaction`/`signTransaction` pipeline. Callers needing
+     * more than one stealth input's worth of fee should pick the smallest single covering UTXO,
+     * not sum several.
+     */
+    private buildPrivateFeeInstructions;
+    /**
+     * Wires a `buildPrivateFeeInstructions()` result into a `StealthTransfer` builder in place of
+     * `.payFeeFromRevealed(maxFee)` -- via the builder's `withBuilder` escape hatch, since the
+     * class has no first-class "pay fee from a stealth UTXO" method of its own.
+     */
+    private attachPrivateFee;
+    /**
+     * Completes signing for a `StealthTransfer`-based operation whose fee was attached via
+     * `attachPrivateFee`: adds the fee UTXO's one-time authorization as an extra signature
+     * (`AuthorizedTransfer.addSignature`) alongside whatever `WalletStealthAuthorizer` already
+     * produced for the operation's own stealth inputs, then seals. Bound to the same seal public
+     * key `authorized` itself uses, so every signature verifies against the same tx hash (see
+     * `AuthorizedTransfer.seal`'s doc comment).
+     */
+    private sealWithPrivateFee;
+    /**
+     * Shared bookkeeping after ANY operation (`execute()` included) whose fee was paid privately
+     * lands on-chain: records the fee UTXO's change output and marks the spent one, mirroring
+     * `shield()`/`unshield()`'s existing pattern for their own outputs. Never call this for a dry
+     * run or a failed submission.
+     */
+    private recordPrivateFeeSpend;
+    /**
+     * Selects and builds everything needed to pay a transaction's fee privately, or returns `null`
+     * for `{ kind: "transparent" }` -- the single entry point every fee-paying method (`execute()`
+     * and every `StealthTransfer`-based one below) uses to interpret a `FeeType` the same way.
+     */
+    private resolvePrivateFee;
+    /**
+     * Shared prepare/authorize/seal/submit path for every `StealthTransfer`-based operation
+     * (shield/unshield/withdrawStealthAndExecute/etc.): `builder` must already have every
+     * operation-specific call applied (`spendRevealedInput`, `toStealthOutput`,
+     * `spendStealthInput`, `andThen`, ...) EXCEPT the fee -- this attaches either
+     * `.payFeeFromRevealed(maxFee)` or a private fee (via `resolvePrivateFee`/`attachPrivateFee`),
+     * then authorizes with `WalletStealthAuthorizer` (passing `authorizerOpts` through, e.g.
+     * `viewSecret` when the operation itself spends stealth inputs), seals (co-signing the private
+     * fee's UTXO when there is one), and submits -- but does NOT poll to finality or record
+     * anything: callers keep their own existing `addPendingShield`/poll/`recordKnownShieldedOutput`
+     * logic for the operation's own effect, and must call `recordPrivateFeeSpend` themselves once
+     * `transactionId` actually lands (never for a dry run) using the returned `privateFee`.
+     */
+    private prepareSignSubmit;
     redeemStealthOutputWithPrivateFee(resourceAddress: string, commitmentHex: string, revealedAmount: bigint, followUpInstructions: Instruction[], feeResourceAddress: string, feeCommitmentHex: string, maxFee: bigint, relatedComponents?: string[]): Promise<{
         transactionId: string;
         feeChangeCommitment: string;
@@ -501,7 +588,7 @@ export declare class OotleAccount implements WalletAccountApi {
      * other stealth payment addressed to them — spend authority is governed entirely separately, by
      * `payTo`.
      */
-    htlcFund(resourceAddress: string, amount: bigint, claimantWalletAddress: string, hashLockHex: string, refundEpoch: bigint, maxFee?: bigint): Promise<{
+    htlcFund(resourceAddress: string, amount: bigint, claimantWalletAddress: string, hashLockHex: string, refundEpoch: bigint, maxFee?: bigint, feeType?: FeeType): Promise<{
         transactionId: string;
         conditions: object[];
         ownCommitment: string;
@@ -534,7 +621,7 @@ export declare class OotleAccount implements WalletAccountApi {
      * unblinded mask+value and the two witnesses below, so there is nothing left for the builder
      * pipeline to add.
      */
-    htlcClaim(resourceAddress: string, commitmentHex: string, conditions: object[], preimageHex: string, maxFee?: bigint): Promise<{
+    htlcClaim(resourceAddress: string, commitmentHex: string, conditions: object[], preimageHex: string, maxFee?: bigint, feeType?: FeeType): Promise<{
         transactionId: string;
     }>;
     /**
@@ -555,7 +642,7 @@ export declare class OotleAccount implements WalletAccountApi {
      * `buildStealthTransferStatement`-in-one-call approach, same bypass of
      * `StealthTransfer`/`WalletStealthAuthorizer`.
      */
-    htlcRefund(resourceAddress: string, commitmentHex: string, conditions: object[], amount: bigint, outputMaskHex: string, maxFee?: bigint): Promise<{
+    htlcRefund(resourceAddress: string, commitmentHex: string, conditions: object[], amount: bigint, outputMaskHex: string, maxFee?: bigint, feeType?: FeeType): Promise<{
         transactionId: string;
     }>;
     /**
@@ -585,7 +672,7 @@ export declare class OotleAccount implements WalletAccountApi {
      * grabbing "the first new stealth output" would risk recording the recipient's payment as our
      * own. See `PendingShield.ownCommitment`'s doc comment.
      */
-    sendPrivately(resourceAddress: string, recipientWalletAddress: string, amount: bigint, maxFee?: bigint, memo?: string, minimumValuePromise?: bigint): Promise<{
+    sendPrivately(resourceAddress: string, recipientWalletAddress: string, amount: bigint, maxFee?: bigint, memo?: string, minimumValuePromise?: bigint, feeType?: FeeType): Promise<{
         transactionId: string;
         recipientCommitment: string;
         recipientSubstateId: string;
@@ -782,6 +869,14 @@ export declare function resolveUnshieldPlan(records: ShieldedOutputRecord[], res
     commitments: string[];
     remainder: bigint;
 };
+/**
+ * Pure planning for `execute()`'s private-fee path: picks the smallest unspent stealth UTXO of
+ * `feeResourceAddress` that alone covers `maxFee`. Deliberately the *smallest* qualifying record
+ * (not the largest, and never several combined) -- `buildPrivateFeeInstructions` only supports a
+ * single fee input (see its own doc comment for why), so this leaves larger shielded balances
+ * untouched for whatever they were shielded for rather than reaching for them first.
+ */
+export declare function selectPrivateFeeUtxo(records: ShieldedOutputRecord[], feeResourceAddress: string, maxFee: bigint, exclude?: string[]): ShieldedOutputRecord;
 /**
  * Pure planning for `sendPrivately()`: selects enough of the caller's unspent records for this
  * resource to cover `amount` — unlike `resolveUnshieldPlan`, sending the *entire* selected total

package/dist/wallet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wallet.d.ts","sourceRoot":"","sources":["../src/wallet.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"wallet.d.ts","sourceRoot":"","sources":["../src/wallet.ts"],"names":[],"mappings":"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"}

package/dist/wallet.js

@@ -320,6 +320,7 @@ export class OotleAccount {
         const provider = await this.getProvider();
         const account = await this.getComponentAddress();
         const maxFee = opts.maxFee ?? 5000n;
+        const feeType = opts.feeType ?? { kind: "transparent" };
         // Resolved once, outside the retry loop below: every transaction now carries a mandatory
         // `max_epoch`, and a fresh chain-tip lookup on every retry would buy nothing (the loop's
         // whole retry budget runs in well under an epoch in practice) at the cost of an extra
@@ -335,18 +336,34 @@ export class OotleAccount {
         const maxRetries = opts.maxRetries ?? 30;
         const seenAddresses = new Set();
         let inputs = await applyKnownVersions(opts.inputs ? [...opts.inputs] : []);
+        // Built once, outside the retry loop, like `maxEpoch` above: the fee stealth proof doesn't
+        // depend on which main-instruction substates a given attempt discovers, so redoing the
+        // indexer round trip + proof generation on every retry would buy nothing.
+        const accountId = localAccountId(this.index);
+        const privateFee = await this.resolvePrivateFee(feeType, maxFee);
         for (let attempt = 0;; attempt++) {
-            const builder = TransactionBuilder.new(this.network, maxEpoch)
-                .withInstructions(instructions)
-                .feeTransactionPayFromComponent(account, maxFee);
+            const builder = TransactionBuilder.new(this.network, maxEpoch).withInstructions(instructions);
+            if (privateFee) {
+                for (const instr of privateFee.feeInstructions)
+                    builder.addFeeInstruction(instr);
+            }
+            else {
+                builder.feeTransactionPayFromComponent(account, maxFee);
+            }
             if (inputs.length)
                 builder.withInputs(inputs);
+            if (privateFee)
+                builder.withInputs(privateFee.feeInputs);
             const unsignedTx = builder.buildUnsignedTransaction();
             try {
+                const extraSigners = privateFee ? [privateFee.feeSigner] : [];
                 if (opts.dryRun)
-                    return await withTimeout(this.submitDryRun(provider, unsignedTx), 30_000, "submitting the transaction");
-                const result = await withTimeout(this.submitReal(provider, unsignedTx), 60_000, "submitting the transaction");
+                    return await withTimeout(this.submitDryRun(provider, unsignedTx, extraSigners), 30_000, "submitting the transaction");
+                const result = await withTimeout(this.submitReal(provider, unsignedTx, extraSigners), 60_000, "submitting the transaction");
                 await recordKnownVersions(result);
+                if (privateFee && feeType.kind === "private") {
+                    await this.recordPrivateFeeSpend(accountId, feeType.feeResourceAddress, privateFee, String(result.transaction_id));
+                }
                 return withTransactionId(result);
             }
             catch (e) {
@@ -431,9 +448,9 @@ export class OotleAccount {
      * (only the real-submission response, which no longer carries a `result` field at all as of
      * the 0.39.0 protocol upgrade).
      */
-    async submitDryRun(provider, unsignedTx) {
+    async submitDryRun(provider, unsignedTx, extraSigners = []) {
         const resolved = await resolveTransaction(provider, { ...unsignedTx, dry_run: true });
-        const signed = await signTransaction([this.signer], resolved);
+        const signed = await signTransaction([this.signer, ...extraSigners], resolved);
         const envelope = sealTransaction(signed);
         const res = await fetch(`${defaultIndexerUrl(this.network)}/transactions/dry-run`, {
             method: "POST",
@@ -486,7 +503,7 @@ export class OotleAccount {
      * proven correct; only the result-polling and error-message construction are reimplemented, in
      * the same detailed shape `submitDryRun()` above already produces.
      */
-    async submitReal(provider, unsignedTx) {
+    async submitReal(provider, unsignedTx, extraSigners = []) {
         const resolved = await resolveTransaction(provider, unsignedTx);
         // Both of these parse the transaction inside the wasm as an untagged enum
         // (`ootle_wasm/core/src/transaction.rs`), so a single bad field anywhere collapses into "data
@@ -497,7 +514,7 @@ export class OotleAccount {
         // is attached here rather than guessed at afterwards.
         let signed;
         try {
-            signed = await signTransaction([this.signer], resolved);
+            signed = await signTransaction([this.signer, ...extraSigners], resolved);
         }
         catch (e) {
             throw new Error(`${e instanceof Error ? e.message : String(e)} — at signTransaction; resolved tx: ${describeResolvedTx(resolved)}`, { cause: e });
@@ -510,7 +527,8 @@ export class OotleAccount {
             throw new Error(`${e instanceof Error ? e.message : String(e)} — at sealTransaction; signed: ${describeSignedTx(signed)}`, { cause: e });
         }
         const { transaction_id } = await provider.submitTransaction(envelope);
-        return pollTransactionResult(provider, transaction_id);
+        const result = await pollTransactionResult(provider, transaction_id);
+        return { ...result, transaction_id };
     }
     /**
      * Transfers `amount` (raw, resource-native units) of `resourceAddress` from this account to
@@ -536,7 +554,7 @@ export class OotleAccount {
      * never reveals the owner key `CreateAccount` needs, so that form can only pay an account that
      * already exists.
      */
-    async send(recipientAddress, resourceAddress, amount, maxFee = 5000n) {
+    async send(recipientAddress, resourceAddress, amount, maxFee = 5000n, feeType = { kind: "transparent" }) {
         const account = await this.getComponentAddress();
         const isWalletAddress = recipientAddress.startsWith("otl");
         const recipient = isWalletAddress ? componentAddressFromWalletAddress(recipientAddress) : recipientAddress;
@@ -562,7 +580,7 @@ export class OotleAccount {
             }
         }
         instructions.push({ CallMethod: { call: { Address: account }, method: "withdraw", args: [resourceAddressLiteral(resourceAddress), amountLiteral(amount)] } }, { PutLastInstructionOutputOnWorkspace: { key: 0 } }, { CallMethod: { call: { Address: recipient }, method: "deposit", args: [{ Workspace: { id: 0, offset: null } }] } });
-        return this.execute(instructions, { maxFee });
+        return this.execute(instructions, { maxFee, feeType });
     }
     /**
      * Moves `amount` of this account's own REVEALED balance into a Confidential-type vault for the
@@ -594,7 +612,7 @@ export class OotleAccount {
      * produces a bucket holding the one new confidential output, which `deposit` puts back in the
      * same vault.
      */
-    async depositConfidential(resourceAddress, amount, maxFee = 50000n) {
+    async depositConfidential(resourceAddress, amount, maxFee = 50000n, feeType = { kind: "transparent" }) {
         if (amount <= 0n)
             throw new Error(`depositConfidential: amount must be greater than zero, got ${amount}`);
         const account = await this.getComponentAddress();
@@ -621,7 +639,7 @@ export class OotleAccount {
             { PutLastInstructionOutputOnWorkspace: { key: 0 } },
             { CallMethod: { call: { Address: account }, method: "deposit", args: [{ Workspace: { id: 0, offset: null } }] } },
         ];
-        return this.execute(instructions, { maxFee });
+        return this.execute(instructions, { maxFee, feeType });
     }
     /**
      * Claims free testnet XTR from the network's builtin faucet (esmeralda/igor only — there is no
@@ -739,7 +757,7 @@ export class OotleAccount {
      * erring high just wastes nothing; erring low burns the small fee-intent cost with nothing to
      * show for it, since only the fee half of the transaction gets committed.
      */
-    async shield(resourceAddress, amount, maxFee = 50000n, memo, minimumValuePromise = 0n) {
+    async shield(resourceAddress, amount, maxFee = 50000n, memo, minimumValuePromise = 0n, feeType = { kind: "transparent" }) {
         assertValidMinimumValuePromise(minimumValuePromise, amount);
         const accountId = localAccountId(this.index);
         const provider = await this.getProvider();
@@ -748,7 +766,7 @@ export class OotleAccount {
         // on-chain component address -- passing `account` here throws "Bech32 decode error" (confirmed
         // live). See getWalletAddress()'s doc comment for why these two addresses are easy to conflate.
         const walletAddress = await this.getWalletAddress();
-        const spec = await new StealthTransfer(provider, resourceAddress)
+        const builder = new StealthTransfer(provider, resourceAddress)
             // StealthTransfer.prepare() auto-adds the revealed account's own substate and any vault
             // addresses embedded in its on-chain state, but never the resource's own substate -- fine
             // for XTR (resource_0101...0101 is engine-special-cased and needs no lock), but any other
@@ -757,24 +775,25 @@ export class OotleAccount {
             // source (node_modules/@tari-project/ootle/dist/index.js) -- not assumed from the docs.
             .withBuilder((b) => b.addInput({ substate_id: resourceAddress, version: null }))
             .spendRevealedInput(account, amount)
-            .toStealthOutput(createOutput({ destination: walletAddress, amount, resourceAddress, memo: toMemo(memo), minimumValuePromise }))
-            .payFeeFromRevealed(maxFee)
-            .prepare();
+            .toStealthOutput(createOutput({ destination: walletAddress, amount, resourceAddress, memo: toMemo(memo), minimumValuePromise }));
+        // No stealth inputs to unblind for a shield's own transfer (revealed-only source), so no
+        // viewSecret needed here even when the FEE is paid privately -- `prepareSignSubmit` handles
+        // that UTXO's own decryption internally. `fromSpec`'s own default crypto is
+        // `new WasmStealthCrypto()` -- Network.LocalNet, NOT this account's real network -- which
+        // produced an "Invalid transaction signature" server-side rejection (confirmed live) since
+        // the balance proof it computes is network-domain-separated. Must match the network
+        // StealthTransfer itself used when it built the outputs statement (`prepareSignSubmit`
+        // already passes `this.network` for exactly this reason).
+        const { transactionId, spec, privateFee } = await this.prepareSignSubmit(builder, provider, account, maxFee, feeType);
         const ownCommitment = extractOutputCommitment(spec, 0);
-        const wallet = new OotleWallet().registerKeyProvider(account, this.signer).setDefaultSigner(account);
-        // No stealth inputs to unblind for a shield (revealed-only source), so no viewSecret needed.
-        // `fromSpec`'s own default crypto is `new WasmStealthCrypto()` -- Network.LocalNet, NOT this
-        // account's real network -- which produced an "Invalid transaction signature" server-side
-        // rejection (confirmed live) since the balance proof it computes is network-domain-separated.
-        // Must match the network StealthTransfer itself used when it built the outputs statement.
-        const authorized = await WalletStealthAuthorizer.fromSpec(wallet, spec, { crypto: new WasmStealthCrypto(this.network) }).prepare(provider);
-        const envelope = await authorized.seal();
-        const transactionId = await submitTransaction(provider, envelope);
         await addPendingShield({ transactionId, accountId, resourceAddress, amount: amount.toString(), ownCommitment, memo });
         try {
             const response = await withTimeout(pollTransactionResult(provider, transactionId), 60_000, "submitting the shield transaction");
             await recordKnownVersions(response);
             await recordKnownShieldedOutput(accountId, resourceAddress, ownCommitment, amount, transactionId, memo);
+            if (privateFee && feeType.kind === "private") {
+                await this.recordPrivateFeeSpend(accountId, feeType.feeResourceAddress, privateFee, transactionId);
+            }
         }
         finally {
             await removePendingShield(transactionId);
@@ -876,7 +895,7 @@ export class OotleAccount {
      * mark the spent ones, even if the service worker dies between finalization and the storage
      * writes.
      */
-    async unshield(resourceAddress, revealedOutAmount, maxFee = 100000n, memo) {
+    async unshield(resourceAddress, revealedOutAmount, maxFee = 100000n, memo, feeType = { kind: "transparent" }) {
         const accountId = localAccountId(this.index);
         const records = await listShieldedOutputs(accountId);
         const { commitments, remainder } = resolveUnshieldPlan(records, resourceAddress, revealedOutAmount);
@@ -894,18 +913,16 @@ export class OotleAccount {
         for (const commitment of commitments) {
             builder = builder.spendStealthInput(account, fromHex(commitment));
         }
-        const spec = await builder
+        builder = builder
             .toStealthOutput(createOutput({ destination: walletAddress, amount: remainder, resourceAddress, memo: toMemo(memo) }))
-            .toRevealedOutput(revealedOutAmount + dust)
-            .payFeeFromRevealed(maxFee)
-            .prepare();
-        const ownCommitment = extractOutputCommitment(spec, 0);
-        const wallet = new OotleWallet().registerKeyProvider(account, this.signer).setDefaultSigner(account);
+            .toRevealedOutput(revealedOutAmount + dust);
         const viewSecret = await this.signer.getViewSecret();
-        // See shield()'s comment: must pass this account's real network, not fromSpec's LocalNet default.
-        const authorized = await WalletStealthAuthorizer.fromSpec(wallet, spec, { viewSecret, crypto: new WasmStealthCrypto(this.network) }).prepare(provider);
-        const envelope = await authorized.seal();
-        const transactionId = await submitTransaction(provider, envelope);
+        // See shield()'s comment: must pass this account's real network, not fromSpec's LocalNet
+        // default. `commitments` is excluded from the fee UTXO's own selection so the same shielded
+        // record can never be spent twice in one transaction (as both a main input here and the fee
+        // input) when `resourceAddress` and the fee's resource happen to be the same currency.
+        const { transactionId, spec, privateFee } = await this.prepareSignSubmit(builder, provider, account, maxFee, feeType, { viewSecret }, commitments);
+        const ownCommitment = extractOutputCommitment(spec, 0);
         await addPendingShield({
             transactionId,
             accountId,
@@ -922,6 +939,9 @@ export class OotleAccount {
             for (const commitment of commitments) {
                 await markShieldedOutputSpent(accountId, commitment);
             }
+            if (privateFee && feeType.kind === "private") {
+                await this.recordPrivateFeeSpend(accountId, feeType.feeResourceAddress, privateFee, transactionId);
+            }
         }
         finally {
             await removePendingShield(transactionId);
@@ -955,7 +975,7 @@ export class OotleAccount {
      *   substate with `SubstateNotFound`. Each is registered by address, plus every vault its own
      *   state references (the same vault-discovery this account's own address already gets).
      */
-    async withdrawStealthAndExecute(resourceAddress, amount, workspaceVarName, followUpInstructions, relatedComponents = [], maxFee = 100000n) {
+    async withdrawStealthAndExecute(resourceAddress, amount, workspaceVarName, followUpInstructions, relatedComponents = [], maxFee = 100000n, feeType = { kind: "transparent" }) {
         if (amount <= 0n)
             throw new Error(`withdrawStealthAndExecute amount must be > 0, got ${amount}`);
         const provider = await this.getProvider();
@@ -983,14 +1003,13 @@ export class OotleAccount {
                 builder = builder.withBuilder((b) => b.addInput({ substate_id: vaultId, version: null }));
             }
         }
-        const spec = await builder.payFeeFromRevealed(maxFee).prepare();
-        const wallet = new OotleWallet().registerKeyProvider(account, this.signer).setDefaultSigner(account);
         const viewSecret = await this.signer.getViewSecret();
-        const authorized = await WalletStealthAuthorizer.fromSpec(wallet, spec, { viewSecret, crypto: new WasmStealthCrypto(this.network) }).prepare(provider);
-        const envelope = await authorized.seal();
-        const transactionId = await submitTransaction(provider, envelope);
+        const { transactionId, privateFee } = await this.prepareSignSubmit(builder, provider, account, maxFee, feeType, { viewSecret });
         const response = await withTimeout(pollTransactionResult(provider, transactionId), 60_000, "submitting the transaction");
         await recordKnownVersions(response);
+        if (privateFee && feeType.kind === "private") {
+            await this.recordPrivateFeeSpend(localAccountId(this.index), feeType.feeResourceAddress, privateFee, transactionId);
+        }
         return { transactionId };
     }
     /**
@@ -1021,7 +1040,7 @@ export class OotleAccount {
      * @param relatedComponents Every *other* component `followUpInstructions` touches — same
      *   reasoning as `withdrawStealthAndExecute`'s own parameter of the same name.
      */
-    async redeemStealthOutputAndExecute(resourceAddress, commitmentHex, revealedAmount, followUpInstructions, relatedComponents = [], maxFee = 100000n) {
+    async redeemStealthOutputAndExecute(resourceAddress, commitmentHex, revealedAmount, followUpInstructions, relatedComponents = [], maxFee = 100000n, feeType = { kind: "transparent" }) {
         if (revealedAmount <= 0n) {
             throw new Error(`redeemStealthOutputAndExecute: revealedAmount must be > 0, got ${revealedAmount}`);
         }
@@ -1046,6 +1065,7 @@ export class OotleAccount {
             agg_range_proof: "",
         });
         const statement = new StealthTransferStatement(new StealthInputsStatement([], 0n, inputsJson), new StealthOutputsStatement(outputsJson));
+        const privateFee = await this.resolvePrivateFee(feeType, maxFee);
         const maxEpoch = await resolveMaxEpoch(provider);
         const builder = TransactionBuilder.new(this.network, maxEpoch)
             .addInstruction({
@@ -1060,11 +1080,22 @@ export class OotleAccount {
             // (name resolution only applies to instructions built through *this* same chain; raw
             // pre-built instructions bypass it, same constraint `withdrawStealthAndExecute` documents).
             .saveVar("redeemed")
-            .withInstructions(followUpInstructions)
-            .feeTransactionPayFromComponent(account, maxFee)
+            .withInstructions(followUpInstructions);
+        if (privateFee) {
+            for (const instr of privateFee.feeInstructions)
+                builder.addFeeInstruction(instr);
+        }
+        else {
+            builder.feeTransactionPayFromComponent(account, maxFee);
+        }
+        builder
             .addInput({ substate_id: resourceAddress, version: null })
             .addInput({ substate_id: stealthUtxoSubstateId(resourceAddress, commitment), version: null })
             .addInput({ substate_id: account, version: null });
+        if (privateFee) {
+            for (const input of privateFee.feeInputs)
+                builder.addInput(input);
+        }
         for (const vaultId of await getVaultIdsForAccount(provider, account)) {
             builder.addInput({ substate_id: vaultId, version: null });
         }
@@ -1092,10 +1123,13 @@ export class OotleAccount {
         const wallet = new OotleWallet().registerKeyProvider(account, this.signer).setDefaultSigner(account);
         const viewSecret = await this.signer.getViewSecret();
         const authorized = await WalletStealthAuthorizer.fromSpec(wallet, spec, { viewSecret, crypto: new WasmStealthCrypto(this.network) }).prepare(provider);
-        const envelope = await authorized.seal();
+        const envelope = privateFee ? await this.sealWithPrivateFee(authorized, privateFee.feeSigner) : await authorized.seal();
         const transactionId = await submitTransaction(provider, envelope);
         const response = await withTimeout(pollTransactionResult(provider, transactionId), 60_000, "submitting the redemption transaction");
         await recordKnownVersions(response);
+        if (privateFee && feeType.kind === "private") {
+            await this.recordPrivateFeeSpend(localAccountId(this.index), feeType.feeResourceAddress, privateFee, transactionId);
+        }
         return { transactionId };
     }
     /**
@@ -1141,49 +1175,193 @@ export class OotleAccount {
      *   (which records its own outputs locally) — callers doing several of these in sequence must
      *   thread this value into the next call's `feeCommitmentHex` themselves.
      */
+    /**
+     * Builds the fee-payment instructions/inputs for spending a single stealth UTXO of
+     * `feeResourceAddress` to cover `maxFee`, plus the one-time `Signer` that must co-sign the
+     * resulting `StealthTransfer` fee spend (an ordinary account signature can't authorize a
+     * stealth spend -- see `redeemStealthOutputWithPrivateFee`'s doc comment, which this method's
+     * fee-half logic was extracted from verbatim). The unspent remainder above `maxFee` becomes a
+     * new stealth output back to this account (`feeChangeCommitment`); this only builds
+     * instructions, it doesn't touch local storage -- the caller records the change output (e.g.
+     * via `recordKnownShieldedOutput`) and marks `feeCommitmentHex` spent once the transaction
+     * actually lands, exactly as `redeemStealthOutputWithPrivateFee` itself does inline.
+     *
+     * Deliberately single-UTXO only, like the method this was extracted from -- the only shape
+     * confirmed live. Aggregating several stealth inputs into one `StealthTransfer` fee spend
+     * isn't proven here: `unshield()`'s multi-commitment coin selection uses a different,
+     * higher-level signing pipeline (`WalletStealthAuthorizer`) that isn't available inside this
+     * raw `TransactionBuilder`/`resolveTransaction`/`signTransaction` pipeline. Callers needing
+     * more than one stealth input's worth of fee should pick the smallest single covering UTXO,
+     * not sum several.
+     */
+    async buildPrivateFeeInstructions(feeResourceAddress, feeCommitmentHex, maxFee) {
+        if (maxFee <= 0n)
+            throw new Error(`buildPrivateFeeInstructions: maxFee must be > 0, got ${maxFee}`);
+        const provider = await this.getProvider();
+        const crypto = new WasmStealthCrypto(this.network);
+        const walletAddress = await this.getWalletAddress();
+        const viewSecret = await this.signer.getViewSecret();
+        const commitment = fromHex(feeCommitmentHex);
+        const substateId = stealthUtxoSubstateId(feeResourceAddress, commitment);
+        const substate = await provider.getSubstate(substateId);
+        const decrypted = await decryptOwnedUtxo(crypto, viewSecret, substate, substateId);
+        if (!decrypted) {
+            throw new Error(`buildPrivateFeeInstructions: cannot decrypt ${substateId} -- it doesn't belong to this account, or is already spent.`);
+        }
+        if (decrypted.value <= maxFee) {
+            throw new Error(`buildPrivateFeeInstructions: fee UTXO (${decrypted.value}) is too small to cover maxFee (${maxFee})`);
+        }
+        const feeChange = decrypted.value - maxFee;
+        const inputSkeleton = JSON.stringify({ inputs: [{ commitment: feeCommitmentHex, witness: "KeyPath" }], revealed_amount: "0" });
+        const feeChangeOutput = createOutput({ destination: walletAddress, amount: feeChange, resourceAddress: feeResourceAddress });
+        const { statement: feeOutputsStatement, outputMask: feeOutputMask } = await crypto.generateOutputsStatement([feeChangeOutput], maxFee);
+        const feeInputsStatement = new StealthInputsStatement([], 0n, inputSkeleton);
+        const feeAggInputMask = await crypto.aggregateInputMasks([decrypted.mask]);
+        const feeBalanceProof = await crypto.generateBalanceProofSignature(feeAggInputMask, feeOutputMask, feeInputsStatement.statementJson, feeOutputsStatement.statementJson);
+        const feeStatement = new StealthTransferStatement(feeInputsStatement, feeOutputsStatement, feeBalanceProof);
+        await crypto.validateTransfer(feeStatement);
+        const feeChangeCommitment = feeOutputsStatement.parsed().outputs[0].output.commitment;
+        const feeInstructions = [
+            {
+                StealthTransfer: {
+                    resource_address_ref: { Address: feeResourceAddress },
+                    statement: { __ootleRawJson: feeStatement.toCompactJson() },
+                    revealed_input_bucket: null,
+                },
+            },
+            { PutLastInstructionOutputOnWorkspace: { key: 0 } },
+            { PayFeeFromBucket: { bucket: { id: 0, offset: null } } },
+        ];
+        const feeInputs = [
+            { substate_id: feeResourceAddress, version: null },
+            { substate_id: substateId, version: null },
+        ];
+        // The fee input's own sender_public_nonce lives on its UTXO substate -- fetched again here
+        // (decryptOwnedUtxo above didn't return it) rather than parsed out of the substate response
+        // type, whose shape `decryptOwnedUtxo` already validated once. Same convention
+        // `redeemStealthOutputWithPrivateFee` used before this was extracted.
+        const feeSubstate = await provider.getSubstate(substateId);
+        const feeNonce = feeSubstate.substate.Utxo.output
+            .output.public_nonce;
+        const feeSigner = {
+            getAddress: async () => walletAddress,
+            getPublicKey: async () => parseOotleAddress(walletAddress).owner_key,
+            signTransaction: async (tx, sealPublicKey) => {
+                const json = serializeUnsignedTx(tx);
+                const sig = await this.signer.addStealthSignature(json, fromHex(feeNonce), sealPublicKey, { crypto });
+                return [sig];
+            },
+        };
+        return { feeInstructions, feeInputs, feeChangeCommitment, feeChangeAmount: feeChange, feeSigner };
+    }
+    /**
+     * Wires a `buildPrivateFeeInstructions()` result into a `StealthTransfer` builder in place of
+     * `.payFeeFromRevealed(maxFee)` -- via the builder's `withBuilder` escape hatch, since the
+     * class has no first-class "pay fee from a stealth UTXO" method of its own.
+     */
+    attachPrivateFee(builder, fee) {
+        return builder.withBuilder((b) => {
+            for (const instr of fee.feeInstructions)
+                b.addFeeInstruction(instr);
+            for (const input of fee.feeInputs)
+                b.addInput(input);
+            return b;
+        });
+    }
+    /**
+     * Completes signing for a `StealthTransfer`-based operation whose fee was attached via
+     * `attachPrivateFee`: adds the fee UTXO's one-time authorization as an extra signature
+     * (`AuthorizedTransfer.addSignature`) alongside whatever `WalletStealthAuthorizer` already
+     * produced for the operation's own stealth inputs, then seals. Bound to the same seal public
+     * key `authorized` itself uses, so every signature verifies against the same tx hash (see
+     * `AuthorizedTransfer.seal`'s doc comment).
+     */
+    async sealWithPrivateFee(authorized, feeSigner) {
+        const sealPublicKey = authorized.getSealPublicKey();
+        const signatures = await feeSigner.signTransaction(authorized.getSpec().unsignedTx, sealPublicKey);
+        for (const signature of signatures)
+            authorized.addSignature(signature);
+        return authorized.seal();
+    }
+    /**
+     * Shared bookkeeping after ANY operation (`execute()` included) whose fee was paid privately
+     * lands on-chain: records the fee UTXO's change output and marks the spent one, mirroring
+     * `shield()`/`unshield()`'s existing pattern for their own outputs. Never call this for a dry
+     * run or a failed submission.
+     */
+    async recordPrivateFeeSpend(accountId, feeResourceAddress, fee, transactionId) {
+        await recordKnownShieldedOutput(accountId, feeResourceAddress, fee.feeChangeCommitment, fee.feeChangeAmount, transactionId);
+        await markShieldedOutputSpent(accountId, fee.spentCommitment);
+    }
+    /**
+     * Selects and builds everything needed to pay a transaction's fee privately, or returns `null`
+     * for `{ kind: "transparent" }` -- the single entry point every fee-paying method (`execute()`
+     * and every `StealthTransfer`-based one below) uses to interpret a `FeeType` the same way.
+     */
+    async resolvePrivateFee(feeType, maxFee, 
+    /** Commitments already claimed by the operation's own main effect (e.g. `unshield()`'s or
+     * `sendPrivately()`'s own multi-UTXO coin selection) -- excluded so the same commitment can
+     * never be selected as both a main input and the fee input in one transaction. */
+    exclude = []) {
+        if (feeType.kind !== "private")
+            return null;
+        const accountId = localAccountId(this.index);
+        const chosen = selectPrivateFeeUtxo(await listShieldedOutputs(accountId), feeType.feeResourceAddress, maxFee, exclude);
+        const built = await this.buildPrivateFeeInstructions(feeType.feeResourceAddress, chosen.commitment, maxFee);
+        return { ...built, spentCommitment: chosen.commitment };
+    }
+    /**
+     * Shared prepare/authorize/seal/submit path for every `StealthTransfer`-based operation
+     * (shield/unshield/withdrawStealthAndExecute/etc.): `builder` must already have every
+     * operation-specific call applied (`spendRevealedInput`, `toStealthOutput`,
+     * `spendStealthInput`, `andThen`, ...) EXCEPT the fee -- this attaches either
+     * `.payFeeFromRevealed(maxFee)` or a private fee (via `resolvePrivateFee`/`attachPrivateFee`),
+     * then authorizes with `WalletStealthAuthorizer` (passing `authorizerOpts` through, e.g.
+     * `viewSecret` when the operation itself spends stealth inputs), seals (co-signing the private
+     * fee's UTXO when there is one), and submits -- but does NOT poll to finality or record
+     * anything: callers keep their own existing `addPendingShield`/poll/`recordKnownShieldedOutput`
+     * logic for the operation's own effect, and must call `recordPrivateFeeSpend` themselves once
+     * `transactionId` actually lands (never for a dry run) using the returned `privateFee`.
+     */
+    async prepareSignSubmit(builder, provider, account, maxFee, feeType, authorizerOpts = {}, 
+    /** See `resolvePrivateFee`'s own doc comment. */
+    excludeFromFeeSelection = []) {
+        const privateFee = await this.resolvePrivateFee(feeType, maxFee, excludeFromFeeSelection);
+        const spec = await (privateFee ? this.attachPrivateFee(builder, privateFee) : builder.payFeeFromRevealed(maxFee)).prepare();
+        const wallet = new OotleWallet().registerKeyProvider(account, this.signer).setDefaultSigner(account);
+        const authorized = await WalletStealthAuthorizer.fromSpec(wallet, spec, {
+            crypto: new WasmStealthCrypto(this.network),
+            ...authorizerOpts,
+        }).prepare(provider);
+        const envelope = privateFee ? await this.sealWithPrivateFee(authorized, privateFee.feeSigner) : await authorized.seal();
+        const transactionId = await submitTransaction(provider, envelope);
+        return { transactionId, spec, privateFee };
+    }
     async redeemStealthOutputWithPrivateFee(resourceAddress, commitmentHex, revealedAmount, followUpInstructions, feeResourceAddress, feeCommitmentHex, maxFee, relatedComponents = []) {
         if (revealedAmount <= 0n)
             throw new Error(`redeemStealthOutputWithPrivateFee: revealedAmount must be > 0, got ${revealedAmount}`);
-        if (maxFee <= 0n)
-            throw new Error(`redeemStealthOutputWithPrivateFee: maxFee must be > 0, got ${maxFee}`);
         const provider = await this.getProvider();
         const crypto = new WasmStealthCrypto(this.network);
         const walletAddress = await this.getWalletAddress();
         const viewSecret = await this.signer.getViewSecret();
-        const decryptStealthInput = async (resource, commitmentHexIn) => {
-            const commitment = fromHex(commitmentHexIn);
-            const substateId = stealthUtxoSubstateId(resource, commitment);
-            const substate = await provider.getSubstate(substateId);
-            const decrypted = await decryptOwnedUtxo(crypto, viewSecret, substate, substateId);
-            if (!decrypted) {
-                throw new Error(`redeemStealthOutputWithPrivateFee: cannot decrypt ${substateId} -- it doesn't belong to this account, or is already spent.`);
-            }
-            return { commitmentHex: commitmentHexIn, substateId, mask: decrypted.mask, value: decrypted.value };
-        };
-        const redeemed = await decryptStealthInput(resourceAddress, commitmentHex);
-        const feeInput = await decryptStealthInput(feeResourceAddress, feeCommitmentHex);
-        if (feeInput.value <= maxFee) {
-            throw new Error(`redeemStealthOutputWithPrivateFee: fee UTXO (${feeInput.value}) is too small to cover maxFee (${maxFee})`);
+        const commitment = fromHex(commitmentHex);
+        const substateId = stealthUtxoSubstateId(resourceAddress, commitment);
+        const substate = await provider.getSubstate(substateId);
+        const decrypted = await decryptOwnedUtxo(crypto, viewSecret, substate, substateId);
+        if (!decrypted) {
+            throw new Error(`redeemStealthOutputWithPrivateFee: cannot decrypt ${substateId} -- it doesn't belong to this account, or is already spent.`);
         }
-        const feeChange = feeInput.value - maxFee;
-        const inputSkeleton = (hex) => JSON.stringify({ inputs: [{ commitment: hex, witness: "KeyPath" }], revealed_amount: "0" });
+        const redeemed = { commitmentHex, substateId, mask: decrypted.mask, value: decrypted.value };
+        const { feeInstructions, feeInputs, feeChangeCommitment, feeSigner } = await this.buildPrivateFeeInstructions(feeResourceAddress, feeCommitmentHex, maxFee);
+        const inputSkeleton = JSON.stringify({ inputs: [{ commitment: redeemed.commitmentHex, witness: "KeyPath" }], revealed_amount: "0" });
         // Redeemed resource: 1 stealth input -> 0 stealth outputs, fully revealed into the bucket
         // `followUpInstructions` consumes.
-        const redeemedInputsStatement = new StealthInputsStatement([], 0n, inputSkeleton(redeemed.commitmentHex));
+        const redeemedInputsStatement = new StealthInputsStatement([], 0n, inputSkeleton);
         const redeemedOutputsStatement = new StealthOutputsStatement(JSON.stringify({ outputs: [], revealed_output_amount: revealedAmount.toString(), agg_range_proof: "" }));
         const redeemedAggInputMask = await crypto.aggregateInputMasks([redeemed.mask]);
         const redeemedBalanceProof = await crypto.generateBalanceProofSignature(redeemedAggInputMask, Mask.zero(), redeemedInputsStatement.statementJson, redeemedOutputsStatement.statementJson);
         const redeemedStatement = new StealthTransferStatement(redeemedInputsStatement, redeemedOutputsStatement, redeemedBalanceProof);
         await crypto.validateTransfer(redeemedStatement);
-        // Fee resource: 1 stealth input -> 1 stealth change output + revealed maxFee.
-        const feeChangeOutput = createOutput({ destination: walletAddress, amount: feeChange, resourceAddress: feeResourceAddress });
-        const { statement: feeOutputsStatement, outputMask: feeOutputMask } = await crypto.generateOutputsStatement([feeChangeOutput], maxFee);
-        const feeInputsStatement = new StealthInputsStatement([], 0n, inputSkeleton(feeInput.commitmentHex));
-        const feeAggInputMask = await crypto.aggregateInputMasks([feeInput.mask]);
-        const feeBalanceProof = await crypto.generateBalanceProofSignature(feeAggInputMask, feeOutputMask, feeInputsStatement.statementJson, feeOutputsStatement.statementJson);
-        const feeStatement = new StealthTransferStatement(feeInputsStatement, feeOutputsStatement, feeBalanceProof);
-        await crypto.validateTransfer(feeStatement);
-        const feeChangeCommitment = feeOutputsStatement.parsed().outputs[0].output.commitment;
         const maxEpoch = await resolveMaxEpoch(provider);
         const builder = TransactionBuilder.new(this.network, maxEpoch)
             .addInstruction({
@@ -1194,20 +1372,12 @@ export class OotleAccount {
             },
         })
             .addInstruction({ PutLastInstructionOutputOnWorkspace: { key: 0 } })
-            .withInstructions(followUpInstructions)
-            .addFeeInstruction({
-            StealthTransfer: {
-                resource_address_ref: { Address: feeResourceAddress },
-                statement: { __ootleRawJson: feeStatement.toCompactJson() },
-                revealed_input_bucket: null,
-            },
-        })
-            .addFeeInstruction({ PutLastInstructionOutputOnWorkspace: { key: 0 } })
-            .addFeeInstruction({ PayFeeFromBucket: { bucket: { id: 0, offset: null } } })
-            .addInput({ substate_id: resourceAddress, version: null })
-            .addInput({ substate_id: redeemed.substateId, version: null })
-            .addInput({ substate_id: feeResourceAddress, version: null })
-            .addInput({ substate_id: feeInput.substateId, version: null });
+            .withInstructions(followUpInstructions);
+        for (const instr of feeInstructions)
+            builder.addFeeInstruction(instr);
+        builder.addInput({ substate_id: resourceAddress, version: null }).addInput({ substate_id: redeemed.substateId, version: null });
+        for (const input of feeInputs)
+            builder.addInput(input);
         for (const component of relatedComponents) {
             builder.addInput({ substate_id: component, version: null });
             for (const vaultId of await getVaultIdsForAccount(provider, component)) {
@@ -1215,28 +1385,22 @@ export class OotleAccount {
             }
         }
         const unsignedTx = await resolveTransaction(provider, builder.buildUnsignedTransaction());
-        // One addStealthSignature per stealth input, bound to a shared (arbitrary) seal key that
-        // signTransaction generates -- see this method's own doc comment for why no ordinary
+        // The redeemed input's one-time key co-signs the same way the fee input's does inside
+        // `buildPrivateFeeInstructions` -- see this method's own doc comment for why no ordinary
         // account-key signature is added.
-        const oneTimeSigner = (publicNonceHex) => ({
+        const redeemedSubstate = await provider.getSubstate(redeemed.substateId);
+        const redeemedNonce = redeemedSubstate.substate.Utxo
+            .output.output.public_nonce;
+        const redeemedSigner = {
             getAddress: async () => walletAddress,
             getPublicKey: async () => parseOotleAddress(walletAddress).owner_key,
             signTransaction: async (tx, sealPublicKey) => {
                 const json = serializeUnsignedTx(tx);
-                const sig = await this.signer.addStealthSignature(json, fromHex(publicNonceHex), sealPublicKey, { crypto });
+                const sig = await this.signer.addStealthSignature(json, fromHex(redeemedNonce), sealPublicKey, { crypto });
                 return [sig];
             },
-        });
-        // Each stealth input's own sender_public_nonce lives on its UTXO substate -- fetched again
-        // here (decryptOwnedUtxo above didn't return it) rather than parsed out of the substate
-        // response type, whose shape `decryptOwnedUtxo` already validated once.
-        const redeemedSubstate = await provider.getSubstate(redeemed.substateId);
-        const feeInputSubstate = await provider.getSubstate(feeInput.substateId);
-        const redeemedNonce = redeemedSubstate.substate.Utxo
-            .output.output.public_nonce;
-        const feeNonce = feeInputSubstate.substate.Utxo.output
-            .output.public_nonce;
-        const signed = await signTransaction([oneTimeSigner(redeemedNonce), oneTimeSigner(feeNonce)], unsignedTx);
+        };
+        const signed = await signTransaction([redeemedSigner, feeSigner], unsignedTx);
         const envelope = sealTransaction(signed);
         const transactionId = await submitTransaction(provider, envelope);
         const response = await withTimeout(pollTransactionResult(provider, transactionId), 60_000, "submitting the private-fee redemption transaction");
@@ -1273,7 +1437,7 @@ export class OotleAccount {
      * other stealth payment addressed to them — spend authority is governed entirely separately, by
      * `payTo`.
      */
-    async htlcFund(resourceAddress, amount, claimantWalletAddress, hashLockHex, refundEpoch, maxFee = 50000n) {
+    async htlcFund(resourceAddress, amount, claimantWalletAddress, hashLockHex, refundEpoch, maxFee = 50000n, feeType = { kind: "transparent" }) {
         const provider = await this.getProvider();
         const account = await this.getComponentAddress();
         const walletAddress = await this.getWalletAddress();
@@ -1287,21 +1451,20 @@ export class OotleAccount {
         });
         // See shield()'s comment: the resource's own substate must be pinned explicitly -- prepare()
         // never adds it on its own.
-        const spec = await new StealthTransfer(provider, resourceAddress)
+        const builder = new StealthTransfer(provider, resourceAddress)
             .withBuilder((b) => b.addInput({ substate_id: resourceAddress, version: null }))
             .spendRevealedInput(account, amount)
-            .toStealthOutput(createOutput({ destination: claimantWalletAddress, amount, resourceAddress, payTo: { Conditions: conditions } }))
-            .payFeeFromRevealed(maxFee)
-            .prepare();
+            .toStealthOutput(createOutput({ destination: claimantWalletAddress, amount, resourceAddress, payTo: { Conditions: conditions } }));
+        // No stealth inputs to unblind for this fund's own transfer (revealed-only source), so no
+        // viewSecret needed here even when the FEE is paid privately -- same as shield().
+        const { transactionId, spec, privateFee } = await this.prepareSignSubmit(builder, provider, account, maxFee, feeType);
         const ownCommitment = extractOutputCommitment(spec, 0);
         const outputMask = spec.outputMask.toHex();
-        const wallet = new OotleWallet().registerKeyProvider(account, this.signer).setDefaultSigner(account);
-        // No stealth inputs to unblind (revealed-only source), so no viewSecret needed -- same as shield().
-        const authorized = await WalletStealthAuthorizer.fromSpec(wallet, spec, { crypto: new WasmStealthCrypto(this.network) }).prepare(provider);
-        const envelope = await authorized.seal();
-        const transactionId = await submitTransaction(provider, envelope);
         const response = await withTimeout(pollTransactionResult(provider, transactionId), 60_000, "submitting the HTLC funding transaction");
         await recordKnownVersions(response);
+        if (privateFee && feeType.kind === "private") {
+            await this.recordPrivateFeeSpend(localAccountId(this.index), feeType.feeResourceAddress, privateFee, transactionId);
+        }
         return { transactionId, conditions, ownCommitment, outputMask };
     }
     /**
@@ -1331,7 +1494,7 @@ export class OotleAccount {
      * unblinded mask+value and the two witnesses below, so there is nothing left for the builder
      * pipeline to add.
      */
-    async htlcClaim(resourceAddress, commitmentHex, conditions, preimageHex, maxFee = 50000n) {
+    async htlcClaim(resourceAddress, commitmentHex, conditions, preimageHex, maxFee = 50000n, feeType = { kind: "transparent" }) {
         if (!/^[0-9a-f]{64}$/i.test(preimageHex)) {
             throw new Error(`htlcClaim: preimageHex must be exactly 64 hex characters (32 bytes), got ${JSON.stringify(preimageHex)}`);
         }
@@ -1359,6 +1522,7 @@ export class OotleAccount {
             destinationWalletAddress: walletAddress,
             resourceAddress,
         });
+        const privateFee = await this.resolvePrivateFee(feeType, maxFee);
         const transactionId = await submitHtlcSpend({
             provider,
             signer: this.signer,
@@ -1369,7 +1533,11 @@ export class OotleAccount {
             statementJson,
             maxFee,
             timeoutLabel: "submitting the HTLC claim transaction",
+            privateFee,
         });
+        if (privateFee && feeType.kind === "private") {
+            await this.recordPrivateFeeSpend(localAccountId(this.index), feeType.feeResourceAddress, privateFee, transactionId);
+        }
         return { transactionId };
     }
     /**
@@ -1390,7 +1558,7 @@ export class OotleAccount {
      * `buildStealthTransferStatement`-in-one-call approach, same bypass of
      * `StealthTransfer`/`WalletStealthAuthorizer`.
      */
-    async htlcRefund(resourceAddress, commitmentHex, conditions, amount, outputMaskHex, maxFee = 50000n) {
+    async htlcRefund(resourceAddress, commitmentHex, conditions, amount, outputMaskHex, maxFee = 50000n, feeType = { kind: "transparent" }) {
         const provider = await this.getProvider();
         const account = await this.getComponentAddress();
         const walletAddress = await this.getWalletAddress();
@@ -1409,6 +1577,7 @@ export class OotleAccount {
             destinationWalletAddress: walletAddress,
             resourceAddress,
         });
+        const privateFee = await this.resolvePrivateFee(feeType, maxFee);
         const transactionId = await submitHtlcSpend({
             provider,
             signer: this.signer,
@@ -1419,7 +1588,11 @@ export class OotleAccount {
             statementJson,
             maxFee,
             timeoutLabel: "submitting the HTLC refund transaction",
+            privateFee,
         });
+        if (privateFee && feeType.kind === "private") {
+            await this.recordPrivateFeeSpend(localAccountId(this.index), feeType.feeResourceAddress, privateFee, transactionId);
+        }
         return { transactionId };
     }
     /**
@@ -1449,7 +1622,7 @@ export class OotleAccount {
      * grabbing "the first new stealth output" would risk recording the recipient's payment as our
      * own. See `PendingShield.ownCommitment`'s doc comment.
      */
-    async sendPrivately(resourceAddress, recipientWalletAddress, amount, maxFee = 100000n, memo, minimumValuePromise = 0n) {
+    async sendPrivately(resourceAddress, recipientWalletAddress, amount, maxFee = 100000n, memo, minimumValuePromise = 0n, feeType = { kind: "transparent" }) {
         assertValidMinimumValuePromise(minimumValuePromise, amount);
         const accountId = localAccountId(this.index);
         const records = await listShieldedOutputs(accountId);
@@ -1473,18 +1646,18 @@ export class OotleAccount {
         if (changeAmount > 0n) {
             builder = builder.toStealthOutput(createOutput({ destination: ownWalletAddress, amount: changeAmount, resourceAddress }));
         }
-        const spec = await builder.toRevealedOutput(dust).payFeeFromRevealed(maxFee).prepare();
+        builder = builder.toRevealedOutput(dust);
+        const viewSecret = await this.signer.getViewSecret();
+        // `commitments` excluded from the fee UTXO's own selection -- see unshield()'s identical
+        // comment on why (this and unshield are the only two methods with their own multi-UTXO
+        // coin selection of potentially the same resource as the fee).
+        const { transactionId, spec, privateFee } = await this.prepareSignSubmit(builder, provider, account, maxFee, feeType, { viewSecret }, commitments);
         // Output 0 is the recipient's; output 1 (only present when there's change) is ours. The
         // recipient has no way to discover their new output on their own (no scan-by-view-key API
         // exists) -- this commitment must be handed back to the caller so it can be shared with them
         // out of band; without it, the payment is invisible to them even though it succeeded on-chain.
         const recipientCommitment = extractOutputCommitment(spec, 0);
         const ownCommitment = changeAmount > 0n ? extractOutputCommitment(spec, 1) : undefined;
-        const wallet = new OotleWallet().registerKeyProvider(account, this.signer).setDefaultSigner(account);
-        const viewSecret = await this.signer.getViewSecret();
-        const authorized = await WalletStealthAuthorizer.fromSpec(wallet, spec, { viewSecret, crypto: new WasmStealthCrypto(this.network) }).prepare(provider);
-        const envelope = await authorized.seal();
-        const transactionId = await submitTransaction(provider, envelope);
         await addPendingShield({
             transactionId,
             accountId,
@@ -1501,6 +1674,9 @@ export class OotleAccount {
             for (const commitment of commitments) {
                 await markShieldedOutputSpent(accountId, commitment);
             }
+            if (privateFee && feeType.kind === "private") {
+                await this.recordPrivateFeeSpend(accountId, feeType.feeResourceAddress, privateFee, transactionId);
+            }
         }
         finally {
             await removePendingShield(transactionId);
@@ -1827,7 +2003,6 @@ async function submitHtlcSpend(params) {
     const builder = TransactionBuilder.new(params.network, maxEpoch)
         .addInput({ substate_id: params.substateId, version: null })
         .addInput({ substate_id: params.account, version: null })
-        .feeTransactionPayFromComponent(params.account, params.maxFee)
         .addInstruction(
     // `statement` is spliced as a raw JSON fragment (see buildHtlcSpendStatement), the same
     // technique `@tari-project/ootle`'s own `statementAsWire` uses internally for the piecemeal
@@ -1839,11 +2014,21 @@ async function submitHtlcSpend(params) {
             revealed_input_bucket: null,
         },
     });
+    if (params.privateFee) {
+        for (const instr of params.privateFee.feeInstructions)
+            builder.addFeeInstruction(instr);
+        for (const input of params.privateFee.feeInputs)
+            builder.addInput(input);
+    }
+    else {
+        builder.feeTransactionPayFromComponent(params.account, params.maxFee);
+    }
     for (const vaultId of await getVaultIdsForAccount(params.provider, params.account)) {
         builder.addInput({ substate_id: vaultId, version: null });
     }
     const unsignedTx = await resolveTransaction(params.provider, builder.buildUnsignedTransaction());
-    const signed = await signTransaction([params.signer], unsignedTx);
+    const extraSigners = params.privateFee ? [params.privateFee.feeSigner] : [];
+    const signed = await signTransaction([params.signer, ...extraSigners], unsignedTx);
     const envelope = await sealTransaction(signed);
     const transactionId = await submitTransaction(params.provider, envelope);
     const response = await withTimeout(pollTransactionResult(params.provider, transactionId), 60_000, params.timeoutLabel);
@@ -2002,6 +2187,27 @@ export function resolveUnshieldPlan(records, resourceAddress, revealedOutAmount)
     }
     return { commitments: finalSelected.map((r) => r.commitment), remainder: finalTotal - revealedOutAmount };
 }
+/**
+ * Pure planning for `execute()`'s private-fee path: picks the smallest unspent stealth UTXO of
+ * `feeResourceAddress` that alone covers `maxFee`. Deliberately the *smallest* qualifying record
+ * (not the largest, and never several combined) -- `buildPrivateFeeInstructions` only supports a
+ * single fee input (see its own doc comment for why), so this leaves larger shielded balances
+ * untouched for whatever they were shielded for rather than reaching for them first.
+ */
+export function selectPrivateFeeUtxo(records, feeResourceAddress, maxFee, exclude = []) {
+    const excluded = new Set(exclude);
+    const candidates = records
+        .filter((r) => !r.spent && !excluded.has(r.commitment) && r.resourceAddress === feeResourceAddress && BigInt(r.amount) > maxFee)
+        .sort((a, b) => {
+        const diff = BigInt(a.amount) - BigInt(b.amount);
+        return diff > 0n ? 1 : diff < 0n ? -1 : 0;
+    });
+    const chosen = candidates[0];
+    if (!chosen) {
+        throw new Error(`No single shielded ${feeResourceAddress} UTXO is large enough to cover a private fee of ${maxFee}. Shield some first (see shield()).`);
+    }
+    return chosen;
+}
 /**
  * Pure planning for `sendPrivately()`: selects enough of the caller's unspent records for this
  * resource to cover `amount` — unlike `resolveUnshieldPlan`, sending the *entire* selected total

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chironbuilder/ootle-sdk",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Shared TypeScript client for Tari Ootle (L2): account derivation, balances, transactions, HTLCs, and stealth/confidential transfers — the account core behind Sapient and the Tari L1 web wallet's Ootle support.",
   "type": "module",
   "license": "MIT",
@@ -9,7 +9,13 @@
     "url": "git+https://github.com/chironbuilds/ootle-sdk-ts.git"
   },
   "homepage": "https://github.com/chironbuilds/ootle-sdk-ts",
-  "keywords": ["tari", "ootle", "wallet", "blockchain", "web3"],
+  "keywords": [
+    "tari",
+    "ootle",
+    "wallet",
+    "blockchain",
+    "web3"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -22,7 +28,10 @@
       "default": "./dist/adapters.js"
     }
   },
-  "files": ["dist", "vendor"],
+  "files": [
+    "dist",
+    "vendor"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",