@chironbuilder/ootle-sdk 0.1.7 → 0.1.9

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);
@@ -1684,16 +1860,71 @@ export class OotleAccount {
         const known = await listShieldedOutputs(accountId);
         const knownCommitments = new Set(known.filter((r) => r.resourceAddress === resourceAddress).map((r) => r.commitment));
         const prefix = `utxo_${resourceAddress.startsWith("resource_") ? resourceAddress.slice(9) : resourceAddress}_`;
-        const pageSize = opts.pageSize ?? 50;
-        const pageBudget = opts.maxPages ?? 10;
         // Some resources (a voting template's ballot, a raffle ticket) mint at most one output per
         // account by construction -- a caller that already knows this can pass `limit: 1` to stop the
-        // walk (both the page loop and the per-transaction fetches) the moment it's satisfied, rather
-        // than paying for however much of the budget happened to be left.
+        // walk the moment it's satisfied, rather than paying for however much of the budget happened
+        // to be left.
         const limit = opts.limit ?? Infinity;
-        let lastId = null;
         const found = [];
-        pages: for (let page = 0; page < pageBudget; page++) {
+        // Checks one already-known transaction id for a matching output. Failures here (a 404 for a
+        // transaction the indexer hasn't finished materializing a full result for yet, a transient
+        // network error, whatever) are swallowed and treated as "nothing found in this one" rather than
+        // aborting the entire scan -- confirmed necessary empirically: a single bad lookup among dozens
+        // in a page used to fail the whole call, forcing a full retry from scratch for something that
+        // would otherwise have kept going and found the real match a few transactions later.
+        const checkTransaction = async (transactionId) => {
+            let response;
+            try {
+                response = await provider.getTransactionResult(transactionId);
+            }
+            catch {
+                return;
+            }
+            const result = response.result;
+            if (result === "Pending" || "Rejected" in result)
+                return;
+            const outcome = result.Finalized.execution_result?.finalize.result;
+            const upSubstates = outcome && typeof outcome === "object" && "Accept" in outcome
+                ? outcome.Accept.up_substates
+                : outcome && typeof outcome === "object" && "AcceptFeeRejectRest" in outcome
+                    ? outcome.AcceptFeeRejectRest[0].up_substates
+                    : undefined;
+            if (!upSubstates)
+                return;
+            for (const [substateId, substate] of upSubstates) {
+                if (!substateId.startsWith(prefix))
+                    continue;
+                const commitment = substateId.slice(prefix.length);
+                if (knownCommitments.has(commitment))
+                    continue;
+                const decrypted = await decryptOwnedUtxo(crypto, viewSecret, { ...substate, verified: true }, substateId);
+                if (!decrypted)
+                    continue;
+                const memo = fromMemo(decrypted.memo);
+                await recordKnownShieldedOutput(accountId, resourceAddress, commitment, decrypted.value, transactionId, memo);
+                knownCommitments.add(commitment);
+                found.push({ resourceAddress, commitment, amount: decrypted.value, transactionId, memo });
+                if (found.length >= limit)
+                    return;
+            }
+        };
+        // Targeted path: when the caller already knows exactly where this resource's outputs were
+        // created (e.g. a voting app's own election-creation transaction id, which is exactly where
+        // every ballot for that election was minted), check those directly instead of ever touching
+        // `listRecentTransactions` -- turns an O(recent chain history) walk into O(len(transactionIds))
+        // direct lookups.
+        for (const transactionId of opts.transactionIds ?? []) {
+            await checkTransaction(transactionId);
+            if (found.length >= limit)
+                return found;
+        }
+        if (found.length > 0 && opts.transactionIds?.length)
+            return found;
+        const pageSize = opts.pageSize ?? 50;
+        const pageBudget = opts.maxPages ?? 10;
+        const alreadyChecked = new Set(opts.transactionIds ?? []);
+        let lastId = null;
+        for (let page = 0; page < pageBudget; page++) {
             const { transactions } = await provider.listRecentTransactions({ limit: pageSize, last_id: lastId, source: null });
             if (transactions.length === 0)
                 break;
@@ -1701,34 +1932,11 @@ export class OotleAccount {
                 // No receipt yet, or rejected at mempool submission -- neither ever produced up_substates.
                 if (entry.rejected_reason !== null || !entry.summary)
                     continue;
-                const response = await provider.getTransactionResult(entry.transaction_id);
-                const result = response.result;
-                if (result === "Pending" || "Rejected" in result)
+                if (alreadyChecked.has(entry.transaction_id))
                     continue;
-                const outcome = result.Finalized.execution_result?.finalize.result;
-                const upSubstates = outcome && typeof outcome === "object" && "Accept" in outcome
-                    ? outcome.Accept.up_substates
-                    : outcome && typeof outcome === "object" && "AcceptFeeRejectRest" in outcome
-                        ? outcome.AcceptFeeRejectRest[0].up_substates
-                        : undefined;
-                if (!upSubstates)
-                    continue;
-                for (const [substateId, substate] of upSubstates) {
-                    if (!substateId.startsWith(prefix))
-                        continue;
-                    const commitment = substateId.slice(prefix.length);
-                    if (knownCommitments.has(commitment))
-                        continue;
-                    const decrypted = await decryptOwnedUtxo(crypto, viewSecret, { ...substate, verified: true }, substateId);
-                    if (!decrypted)
-                        continue;
-                    const memo = fromMemo(decrypted.memo);
-                    await recordKnownShieldedOutput(accountId, resourceAddress, commitment, decrypted.value, entry.transaction_id, memo);
-                    knownCommitments.add(commitment);
-                    found.push({ resourceAddress, commitment, amount: decrypted.value, transactionId: entry.transaction_id, memo });
-                    if (found.length >= limit)
-                        break pages;
-                }
+                await checkTransaction(entry.transaction_id);
+                if (found.length >= limit)
+                    return found;
             }
             lastId = transactions[transactions.length - 1].transaction_id;
         }
@@ -1795,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
@@ -1807,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);
@@ -1970,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