@chironbuilder/ootle-sdk 0.1.13 → 0.1.15

package/dist/wallet.js

@@ -1,4 +1,4 @@
-import { Mask, OotleWallet, StealthInput, StealthInputsStatement, StealthOutputsStatement, StealthTransfer, StealthTransferStatement, TARI_RESOURCE_ADDRESS, TransactionBuilder, WalletStealthAuthorizer, WasmStealthCrypto, XTR_FAUCET_CLAIM_RESOURCE_ADDRESS, XTR_FAUCET_COMPONENT_ADDRESS, XTR_FAUCET_VAULT_ADDRESS, amountLiteral, createOutput, decryptOwnedUtxo, defaultIndexerUrl, getVaultIdsForAccount, resolveMaxEpoch, resolveTransaction, resourceAddressLiteral, sealTransaction, sendTransaction, serializeUnsignedTx, signTransaction, stealthUtxoSubstateId, submitTransaction, } from "@tari-project/ootle";
+import { Mask, OotleWallet, StealthInput, StealthInputsStatement, StealthOutputsStatement, StealthTransfer, StealthTransferStatement, TARI_RESOURCE_ADDRESS, TransactionBuilder, WalletStealthAuthorizer, WasmStealthCrypto, XTR_FAUCET_CLAIM_RESOURCE_ADDRESS, XTR_FAUCET_COMPONENT_ADDRESS, XTR_FAUCET_VAULT_ADDRESS, amountLiteral, createOutput, decryptOwnedUtxo, defaultIndexerUrl, getVaultIdsForAccount, resolveMaxEpoch, resolveTransaction, resourceAddressLiteral, generateSealKeypair, sealTransaction, sendTransaction, serializeUnsignedTx, signTransaction, stealthUtxoSubstateId, submitTransaction, } from "@tari-project/ootle";
 import { IndexerProvider } from "@tari-project/ootle-indexer";
 import { SecretKeyWallet } from "@tari-project/ootle-secret-key-wallet";
 import { buildScriptPathWitness, burnClaimStealthSecret, buildStealthTransferStatement, createConfidentialWithdrawProofLiteral, createStealthOutputWitness, parseOotleAddress, publicKeyFromSecretKey, schnorrSign, stealthDhSecret, validateBurnClaimOwnershipProof, validateStealthTransfer, } from "@tari-project/ootle-wasm";
@@ -6,11 +6,23 @@ import { componentAddressFromWalletAddress, deriveAccountComponentAddress } from
 import { scanTransactionsForOwnedOutputs, sumConfidentialCommitments } from "./confidential.js";
 import { deriveAccountKeys } from "./derivation.js";
 import { htlcConditions } from "./htlc.js";
+import { HtlcUnknownOutcomeError, HtlcVerificationError, decryptOwnStatementOutput, describeHtlcConditions, findScriptRoot, isDefinitiveRejection, isHtlcRefundable, newOperationId, sha256Hex, statementInputCommitment, statementOutputCommitment, subtractScalars, verifyHtlcTerms, } from "./htlcSafety.js";
 import { buildOwnershipProofMessage, buildWalletOwnershipMessage } from "./ownershipProof.js";
 import { toOotleNetwork } from "./ootleNetwork.js";
-import { addPendingShield, addShieldedOutput, getKnownVersions, getPrivatePaymentScanCursor, listPendingShields, listShieldedOutputs, localAccountId, markShieldedOutputSpent, removePendingShield, setKnownVersions, setPrivatePaymentScanCursor, } from "./storage.js";
+import { addPendingShield, addShieldedOutput, getHtlcJournalEntry, getKnownVersions, getPrivatePaymentScanCursor, listHtlcJournal, listPendingShields, listReservedCommitments, listShieldedOutputs, localAccountId, markShieldedOutputSpent, putHtlcJournalEntry, releaseReservations, removePendingShield, reserveCommitments, setKnownVersions, setPrivatePaymentScanCursor, updateHtlcJournalEntry, CommitmentReservedError, } from "./storage.js";
 import { withTimeout } from "./timeout.js";
 import { fromHex, toHex } from "./vault.js";
+/** A private fee's bookkeeping, in the journal's serializable form. */
+function journalFee(feeType, fee) {
+    if (!fee || feeType.kind !== "private")
+        return undefined;
+    return {
+        feeResourceAddress: feeType.feeResourceAddress,
+        spentCommitment: fee.spentCommitment,
+        changeCommitment: fee.feeChangeCommitment,
+        changeAmount: fee.feeChangeAmount.toString(),
+    };
+}
 /**
  * Batch-reads each resource's on-chain `divisibility` and `metadata.SYMBOL`/`metadata.name`.
  * Decimal precision and display name are real chain data, never a client-side convention: XTR is 6
@@ -159,6 +171,15 @@ export class OotleAccount {
     async getWalletAddress() {
         return this.signer.getAddress();
     }
+    /**
+     * This account's owner public key, synchronously. Named as the receiver of every revealed
+     * stealth output this account's `StealthTransfer`s create (tari-ootle#2645): the engine only
+     * hands a revealed bucket to a key whose badge is in the transaction's auth scope, and those
+     * transfers are always signed with the account key.
+     */
+    get accountPublicKey() {
+        return publicKeyFromSecretKey(this.ownerSecret);
+    }
     async getPublicKey() {
         return this.signer.getPublicKey();
     }
@@ -769,7 +790,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 builder = new StealthTransfer(provider, resourceAddress)
+        const builder = new StealthTransfer(provider, resourceAddress).withRevealedReceiver(this.accountPublicKey)
             // 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
@@ -900,56 +921,70 @@ export class OotleAccount {
      */
     async unshield(resourceAddress, revealedOutAmount, maxFee = 100000n, memo, feeType = { kind: "transparent" }) {
         const accountId = localAccountId(this.index);
-        const records = await this.filterReadableShieldedOutputs(await listShieldedOutputs(accountId), resourceAddress, revealedOutAmount);
+        const opId = newOperationId("unshield");
+        const unavailable = await this.unavailableCommitments(accountId, opId);
+        const records = await this.filterReadableShieldedOutputs((await listShieldedOutputs(accountId)).filter((r) => !unavailable.has(r.commitment)), resourceAddress, revealedOutAmount);
         const { commitments, remainder } = resolveUnshieldPlan(records, resourceAddress, revealedOutAmount);
-        const dust = 1n;
-        const provider = await this.getProvider();
-        const account = await this.getComponentAddress();
-        // See shield()'s comment: Output.destination needs the bech32m wallet address, not the
-        // on-chain component address.
-        const walletAddress = await this.getWalletAddress();
-        // See shield()'s comment: the resource's own substate must be pinned explicitly -- prepare()
-        // never adds it on its own.
-        let builder = new StealthTransfer(provider, resourceAddress)
-            .withBuilder((b) => b.addInput({ substate_id: resourceAddress, version: null }))
-            .spendRevealedInput(account, dust);
-        for (const commitment of commitments) {
-            builder = builder.spendStealthInput(account, fromHex(commitment));
-        }
-        builder = builder
-            .toStealthOutput(createOutput({ destination: walletAddress, amount: remainder, resourceAddress, memo: toMemo(memo) }))
-            .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. `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,
-            resourceAddress,
-            amount: remainder.toString(),
-            spentCommitments: commitments,
-            ownCommitment,
-            memo,
-        });
+        await reserveCommitments(accountId, commitments, opId);
         try {
-            const response = await withTimeout(pollTransactionResult(provider, transactionId), 60_000, "submitting the unshield transaction");
-            await recordKnownVersions(response);
-            await recordKnownShieldedOutput(accountId, resourceAddress, ownCommitment, remainder, transactionId, memo);
+            const dust = 1n;
+            const provider = await this.getProvider();
+            const account = await this.getComponentAddress();
+            // See shield()'s comment: Output.destination needs the bech32m wallet address, not the
+            // on-chain component address.
+            const walletAddress = await this.getWalletAddress();
+            // An account that has only ever held private funds (e.g. a claimed L1 burn) has no component
+            // on-chain to withdraw dust from, deposit into, or pay a fee from. Its first unshield creates
+            // the account from the revealed funds instead, paying the fee from them too.
+            if (!(await substateExists(provider, account))) {
+                return await this.unshieldIntoNewAccount(provider, resourceAddress, revealedOutAmount, commitments, remainder, maxFee, memo);
+            }
+            // See shield()'s comment: the resource's own substate must be pinned explicitly -- prepare()
+            // never adds it on its own.
+            let builder = new StealthTransfer(provider, resourceAddress).withRevealedReceiver(this.accountPublicKey)
+                .withBuilder((b) => b.addInput({ substate_id: resourceAddress, version: null }))
+                .spendRevealedInput(account, dust);
             for (const commitment of commitments) {
-                await markShieldedOutputSpent(accountId, commitment);
+                builder = builder.spendStealthInput(account, fromHex(commitment));
             }
-            if (privateFee && feeType.kind === "private") {
-                await this.recordPrivateFeeSpend(accountId, feeType.feeResourceAddress, privateFee, transactionId);
+            builder = builder
+                .toStealthOutput(createOutput({ destination: walletAddress, amount: remainder, resourceAddress, memo: toMemo(memo) }))
+                .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. `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, opId);
+            const ownCommitment = extractOutputCommitment(spec, 0);
+            await addPendingShield({
+                transactionId,
+                accountId,
+                resourceAddress,
+                amount: remainder.toString(),
+                spentCommitments: commitments,
+                ownCommitment,
+                memo,
+            });
+            try {
+                const response = await withTimeout(pollTransactionResult(provider, transactionId), 60_000, "submitting the unshield transaction");
+                await recordKnownVersions(response);
+                await recordKnownShieldedOutput(accountId, resourceAddress, ownCommitment, remainder, transactionId, memo);
+                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);
             }
+            return { transactionId };
         }
         finally {
-            await removePendingShield(transactionId);
+            await releaseReservations(opId);
         }
-        return { transactionId };
     }
     /**
      * Withdraws `amount` of a Stealth-typed resource (e.g. XTR) from this account's revealed
@@ -994,7 +1029,7 @@ export class OotleAccount {
         // stealth output back to this account -- the same proven-working shape -- alongside the real
         // amount as a revealed bucket.
         const dust = 1n;
-        let builder = new StealthTransfer(provider, resourceAddress)
+        let builder = new StealthTransfer(provider, resourceAddress).withRevealedReceiver(this.accountPublicKey)
             .withBuilder((b) => b.addInput({ substate_id: resourceAddress, version: null }))
             .spendRevealedInput(account, amount + dust)
             .toStealthOutput(createOutput({ destination: walletAddress, amount: dust, resourceAddress }))
@@ -1062,11 +1097,8 @@ export class OotleAccount {
             inputs: [{ commitment: commitmentHex, witness: "KeyPath" }],
             revealed_amount: "0",
         });
-        const outputsJson = JSON.stringify({
-            outputs: [],
-            revealed_output_amount: revealedAmount.toString(),
-            agg_range_proof: "",
-        });
+        // The account key signs this transaction (the authorizer's default), so it takes the revealed funds.
+        const outputsJson = revealOnlyOutputsJson(revealedAmount, this.accountPublicKey);
         const statement = new StealthTransferStatement(new StealthInputsStatement([], 0n, inputsJson), new StealthOutputsStatement(outputsJson));
         const privateFee = await this.resolvePrivateFee(feeType, maxFee);
         const maxEpoch = await resolveMaxEpoch(provider);
@@ -1217,7 +1249,9 @@ export class OotleAccount {
         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 { statement: feeOutputsStatement, outputMask: feeOutputMask } = await crypto.generateOutputsStatement([feeChangeOutput], maxFee, 
+        // The revealed fee goes to the fee UTXO's one-time key, which signs for it (see `feeSigner`).
+        utxoSpendKey(substate));
         const feeInputsStatement = new StealthInputsStatement([], 0n, inputSkeleton);
         const feeAggInputMask = await crypto.aggregateInputMasks([decrypted.mask]);
         const feeBalanceProof = await crypto.generateBalanceProofSignature(feeAggInputMask, feeOutputMask, feeInputsStatement.statementJson, feeOutputsStatement.statementJson);
@@ -1305,11 +1339,17 @@ export class OotleAccount {
     /** 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 = []) {
+    exclude = [], 
+    /** When set, the chosen fee UTXO is reserved for this operation (see `reserveCommitments`) so a
+     * concurrent operation can't pick it too. Whether set or not, UTXOs another operation has
+     * reserved are never chosen. */
+    reservationHolder) {
         if (feeType.kind !== "private")
             return null;
         const accountId = localAccountId(this.index);
         const records = await listShieldedOutputs(accountId);
+        for (const unavailable of await this.unavailableCommitments(accountId, reservationHolder))
+            exclude = [...exclude, unavailable];
         // Retries with the next-smallest qualifying UTXO if one fails to read -- confirmed live that a
         // record this wallet still has as "unspent" can 500 on the indexer (consistent with it having
         // actually been spent already, e.g. from another device/session sharing this seed, hitting an
@@ -1336,6 +1376,17 @@ export class OotleAccount {
                 }
                 throw selectError;
             }
+            if (reservationHolder) {
+                try {
+                    await reserveCommitments(accountId, [chosen.commitment], reservationHolder);
+                }
+                catch (e) {
+                    if (!(e instanceof CommitmentReservedError))
+                        throw e;
+                    tried.add(chosen.commitment); // taken by a concurrent operation since we listed -- try the next one
+                    continue;
+                }
+            }
             try {
                 const built = await this.buildPrivateFeeInstructions(feeType.feeResourceAddress, chosen.commitment, maxFee);
                 return { ...built, spentCommitment: chosen.commitment };
@@ -1410,17 +1461,89 @@ export class OotleAccount {
      */
     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();
+    excludeFromFeeSelection = [], reservationHolder) {
+        const { envelope, spec, privateFee } = await this.sealStealthTransfer(builder, provider, account, maxFee, feeType, {
+            authorizerOpts,
+            excludeFromFeeSelection,
+            reservationHolder,
+        });
+        const transactionId = await submitTransaction(provider, envelope);
+        return { transactionId, spec, privateFee };
+    }
+    /**
+     * The prepare/authorize/seal half of `prepareSignSubmit`, without the submit — so the exact same
+     * transaction shape can be dry-run first (`dryRun: true` marks it before it's signed) and so the
+     * sealed envelope can be journaled before it ever reaches the network.
+     *
+     * `sourceless`: the operation's main lane spends only stealth inputs (no `spendRevealedInput` of
+     * its resource at all — e.g. a stealth-created asset this account holds no public balance of).
+     * A transparent fee then can't use `payFeeFromRevealed` (which needs a revealed source of the
+     * *operation's* resource); instead it's paid in native TARI straight from `account` — the fee
+     * lane — with the account and its vaults registered as inputs, exactly as `submitHtlcSpend` does.
+     * A private fee needs no special handling: it never touched the revealed source anyway.
+     */
+    async sealStealthTransfer(builder, provider, account, maxFee, feeType, opts = {}) {
+        const privateFee = await this.resolvePrivateFee(feeType, maxFee, opts.excludeFromFeeSelection ?? [], opts.reservationHolder);
+        let withFee;
+        if (privateFee) {
+            withFee = this.attachPrivateFee(builder, privateFee);
+        }
+        else if (opts.sourceless) {
+            const vaults = await getVaultIdsForAccount(provider, account);
+            withFee = builder.withBuilder((b) => {
+                b.feeTransactionPayFromComponent(account, maxFee);
+                b.addInput({ substate_id: account, version: null });
+                for (const vaultId of vaults)
+                    b.addInput({ substate_id: vaultId, version: null });
+                return b;
+            });
+        }
+        else {
+            withFee = builder.payFeeFromRevealed(maxFee);
+        }
+        const spec = await withFee.prepare();
+        // `dry_run` is part of the signed transaction, so it must be set before authorization/sealing.
+        if (opts.dryRun)
+            spec.unsignedTx.dry_run = true;
         const wallet = new OotleWallet().registerKeyProvider(account, this.signer).setDefaultSigner(account);
         const authorized = await WalletStealthAuthorizer.fromSpec(wallet, spec, {
             crypto: new WasmStealthCrypto(this.network),
-            ...authorizerOpts,
+            ...(opts.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 };
+        return { envelope, spec, privateFee };
+    }
+    /**
+     * Dry-runs a sealed envelope (one built with `dry_run` set) against the indexer's dry-run endpoint
+     * and returns the execution result, throwing — in the same "was rejected: …" shape real
+     * submissions use — if it would be rejected. Nothing reaches consensus; nothing is spent.
+     */
+    async dryRunEnvelope(envelope) {
+        const res = await fetch(`${defaultIndexerUrl(this.network)}/transactions/dry-run`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ transaction: envelope }),
+        });
+        const text = await res.text();
+        let body;
+        try {
+            body = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            // Not JSON — reported raw below.
+        }
+        if (!res.ok || body?.error || !body?.result) {
+            throw new Error(`The dry run failed: ${body?.error?.message ?? text ?? res.statusText}`);
+        }
+        const outcome = body.result.finalize.result;
+        if (typeof outcome === "object" && outcome !== null) {
+            if ("Reject" in outcome)
+                throw new Error(`The dry run was rejected: ${JSON.stringify(outcome.Reject)}`);
+            if ("AcceptFeeRejectRest" in outcome) {
+                throw new Error(`The dry run accepted the fee but rejected the rest: ${JSON.stringify(outcome.AcceptFeeRejectRest)}`);
+            }
+        }
+        return body.result;
     }
     async redeemStealthOutputWithPrivateFee(resourceAddress, commitmentHex, revealedAmount, followUpInstructions, feeResourceAddress, feeCommitmentHex, maxFee, relatedComponents = []) {
         if (revealedAmount <= 0n)
@@ -1442,7 +1565,10 @@ export class OotleAccount {
         // Redeemed resource: 1 stealth input -> 0 stealth outputs, fully revealed into the bucket
         // `followUpInstructions` consumes.
         const redeemedInputsStatement = new StealthInputsStatement([], 0n, inputSkeleton);
-        const redeemedOutputsStatement = new StealthOutputsStatement(JSON.stringify({ outputs: [], revealed_output_amount: revealedAmount.toString(), agg_range_proof: "" }));
+        const redeemedOutputsStatement = new StealthOutputsStatement(
+        // This transaction deliberately carries no account signature, so the revealed funds go to the
+        // key that does sign for them: the redeemed UTXO's own one-time spend key.
+        revealOnlyOutputsJson(revealedAmount, utxoSpendKey(substate)));
         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);
@@ -1496,33 +1622,43 @@ export class OotleAccount {
      * Funds an HTLC (hashed timelock contract): creates a stealth output for `amount` of
      * `resourceAddress`, gated not by a normal one-time stealth key but by a two-leaf TIP-0006
      * condition tree (`htlcConditions` in `./htlc.ts`) — a claim path admissible only to
-     * `claimantWalletAddress` (revealing the SHA-256 preimage of `hashLockHex`, before
+     * `claimantWalletAddress` (revealing the SHA-256 preimage of `hashLockHex`, strictly before
      * `refundEpoch`), and a refund path admissible only to this account (at/after `refundEpoch`).
-     * `htlcConditions`'s own doc comment covers the exact leaf shapes.
      *
-     * This account never needs (and must never be given) the actual preimage — only its hash. The
-     * caller resolves `refundEpoch` from a desired wall-clock deadline via the provider/network's
-     * current epoch, the same as any other epoch-relative on-chain deadline.
+     * This account never needs (and must never be given) the actual preimage — only its hash.
      *
-     * Returns the full `conditions` tree alongside the transaction id and this output's own
-     * commitment: only the tree's **root** is committed on-chain, so the claimant needs the exact
-     * leaves — out of band, via whatever swap protocol coordinates the two sides — to later reveal
-     * the claim leaf.
+     * **Two lanes.** The fee and the HTLC value never share a UTXO: the fee is paid in native TARI —
+     * privately from a separate stealth TARI UTXO (`feeType: private`) or from this account's public
+     * TARI — while the main lane moves only `resourceAddress`. With `source: { kind: "stealth" }` the
+     * main lane spends this account's *own stealth outputs* of the resource (exactly the given
+     * `commitments`, or selected automatically), returning any excess as same-resource stealth change;
+     * no public balance of the resource is needed at all, so a stealth-created asset can be locked.
+     * The default `source: { kind: "revealed" }` keeps the original behavior (public balance).
      *
-     * Also returns `outputMask` (hex): this account funded the output, so it's the one place the
-     * blinding mask is ever available to it without decryption — `encrypted_data` is encrypted for
-     * `claimantWalletAddress`'s view key, not this account's, so if the claim path is never taken
-     * and this account later calls `htlcRefund`, it cannot decrypt the output the normal way (the
-     * way `htlcClaim`'s claimant can, since the output is addressed to *them*). Retaining this mask
-     * now — alongside the known `amount` — is what makes an undecryptable refund possible at all.
-     * `htlcRefund`'s own doc comment covers the rest.
+     * **Settlement safety.**
+     * - The exact transaction is dry-run first (`preflight`, default on), so a doomed fund never
+     *   reaches the network.
+     * - Before submission, the `conditions` tree, the HTLC output's own blinding `outputMask` and the
+     *   sealed envelope are written to the HTLC journal. The funder can't decrypt an output
+     *   addressed to the claimant, so the mask is the only thing that makes a refund possible —
+     *   it's never held only in memory.
+     * - With stealth change, `outputMask` is derived as `aggregateMask − changeMask` and then
+     *   *proven* before submit: a refund built from it must reproduce the HTLC output's commitment,
+     *   or the fund is aborted.
+     * - Inputs (and a private fee's UTXO) are reserved for the duration, so a concurrent operation
+     *   can't select them.
+     * - If the outcome doesn't arrive in time this throws `HtlcUnknownOutcomeError` (carrying the
+     *   refund data) instead of a plain failure; `reconcileHtlcs()` resolves it later.
      *
-     * `destination` is set to the claimant's own wallet address (not this account's) so the
-     * claimant can independently decrypt and verify the funded amount themselves, the same as any
-     * other stealth payment addressed to them — spend authority is governed entirely separately, by
-     * `payTo`.
+     * Returns the full `conditions` tree (only its root is on-chain — the claimant needs the leaves,
+     * out of band), the HTLC output's commitment (`ownCommitment`, kept for compatibility), its
+     * `outputMask`, the change commitment when there was change, and the `journalId`.
      */
-    async htlcFund(resourceAddress, amount, claimantWalletAddress, hashLockHex, refundEpoch, maxFee = 50000n, feeType = { kind: "transparent" }) {
+    async htlcFund(resourceAddress, amount, claimantWalletAddress, hashLockHex, refundEpoch, maxFee = 50000n, feeType = { kind: "transparent" }, options = {}) {
+        if (amount <= 0n)
+            throw new Error("htlcFund: amount must be greater than zero.");
+        const opId = newOperationId("htlc-fund");
+        const accountId = localAccountId(this.index);
         const provider = await this.getProvider();
         const account = await this.getComponentAddress();
         const walletAddress = await this.getWalletAddress();
@@ -1534,124 +1670,256 @@ export class OotleAccount {
             claimantPublicKeyHex: toHex(claimant.owner_key),
             refunderPublicKeyHex: toHex(refunder.owner_key),
         });
-        // See shield()'s comment: the resource's own substate must be pinned explicitly -- prepare()
-        // never adds it on its own.
-        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 } }));
-        // 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 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);
+        const source = options.source ?? { kind: "revealed" };
+        const stealth = source.kind === "stealth";
+        const viewSecret = stealth ? await this.signer.getViewSecret() : undefined;
+        let commitments = [];
+        let change = 0n;
+        try {
+            if (stealth) {
+                ({ commitments, change } = await this.selectStealthSource(accountId, opId, resourceAddress, amount, source.commitments));
+                await reserveCommitments(accountId, commitments, opId);
+            }
+            // See shield()'s comment: the resource's own substate must be pinned explicitly -- prepare()
+            // never adds it on its own. Output 0 is the HTLC; output 1 (only with change) is ours.
+            const build = () => {
+                let b = new StealthTransfer(provider, resourceAddress).withRevealedReceiver(this.accountPublicKey).withBuilder((bb) => bb.addInput({ substate_id: resourceAddress, version: null }));
+                if (stealth)
+                    for (const c of commitments)
+                        b = b.spendStealthInput(account, fromHex(c));
+                else
+                    b = b.spendRevealedInput(account, amount);
+                // `destination` is the claimant's own wallet address so they can independently decrypt and
+                // verify the funded amount; spend authority is governed entirely by `payTo`.
+                b = b.toStealthOutput(createOutput({ destination: claimantWalletAddress, amount, resourceAddress, payTo: { Conditions: conditions } }));
+                if (change > 0n)
+                    b = b.toStealthOutput(createOutput({ destination: walletAddress, amount: change, resourceAddress }));
+                return b;
+            };
+            const sealOpts = {
+                authorizerOpts: viewSecret ? { viewSecret } : {},
+                excludeFromFeeSelection: commitments,
+                reservationHolder: opId,
+                sourceless: stealth,
+            };
+            if (options.preflight !== false) {
+                const dry = await this.sealStealthTransfer(build(), provider, account, maxFee, feeType, { ...sealOpts, dryRun: true });
+                await this.dryRunEnvelope(dry.envelope);
+            }
+            const { envelope, spec, privateFee } = await this.sealStealthTransfer(build(), provider, account, maxFee, feeType, sealOpts);
+            const htlcCommitment = extractOutputCommitment(spec, 0);
+            let outputMask = spec.outputMask.toHex();
+            let changeCommitment;
+            if (change > 0n) {
+                const outputs = spec.statement.outputsStatement.parsed().outputs;
+                const own = decryptOwnStatementOutput(outputs[1], viewSecret);
+                if (own.value !== change)
+                    throw new Error(`htlcFund: change output decrypted to ${own.value}, expected ${change} — aborting before submit.`);
+                changeCommitment = own.commitment;
+                outputMask = subtractScalars(outputMask, own.maskHex);
+            }
+            // Prove the refund is buildable before anything is at stake: the mask we're about to rely on
+            // must reproduce the HTLC output's exact commitment.
+            const refundProbe = buildHtlcSpendStatement({
+                network: this.network,
+                conditions,
+                leaf: conditions[1],
+                data: new Uint8Array(0),
+                mask: outputMask,
+                value: amount,
+                destinationWalletAddress: walletAddress,
+                resourceAddress,
+            });
+            if (statementInputCommitment(refundProbe) !== htlcCommitment.toLowerCase()) {
+                throw new Error("htlcFund: the derived output mask does not reproduce the HTLC commitment — refusing to fund an output that couldn't be refunded.");
+            }
+            const now = Date.now();
+            const entry = {
+                id: opId,
+                accountId,
+                kind: "fund",
+                status: "prepared",
+                resourceAddress,
+                amount: amount.toString(),
+                conditions,
+                hashLockHex: hashLockHex.toLowerCase(),
+                refundEpoch: refundEpoch.toString(),
+                htlcCommitment,
+                outputMask,
+                ownCommitment: changeCommitment,
+                ownAmount: change > 0n ? change.toString() : undefined,
+                spentCommitments: commitments.length ? commitments : undefined,
+                privateFee: journalFee(feeType, privateFee),
+                envelope,
+                createdAt: now,
+                updatedAt: now,
+            };
+            const { transactionId } = await this.submitJournaled(entry, provider, "submitting the HTLC funding transaction");
+            return { transactionId, conditions, ownCommitment: htlcCommitment, outputMask, changeCommitment, journalId: opId };
+        }
+        catch (e) {
+            if (!(e instanceof HtlcUnknownOutcomeError))
+                await releaseReservations(opId);
+            throw e;
+        }
+    }
+    /**
+     * Chooses the stealth inputs for a stealth-sourced HTLC fund: exactly `requested` when given
+     * (each must be this account's own unspent, unreserved record of `resourceAddress`, and must
+     * decrypt on-chain to the recorded amount), otherwise a largest-first selection covering `amount`.
+     */
+    async selectStealthSource(accountId, holder, resourceAddress, amount, requested) {
+        const unavailable = await this.unavailableCommitments(accountId, holder);
+        const records = (await listShieldedOutputs(accountId)).filter((r) => !unavailable.has(r.commitment));
+        let chosen;
+        if (requested && requested.length > 0) {
+            const provider = await this.getProvider();
+            const crypto = new WasmStealthCrypto(this.network);
+            const viewSecret = await this.signer.getViewSecret();
+            chosen = [];
+            for (const commitment of new Set(requested.map((c) => c.toLowerCase()))) {
+                const record = records.find((r) => r.commitment.toLowerCase() === commitment);
+                if (!record) {
+                    throw new Error(`htlcFund: ${commitment.slice(0, 12)}… is not one of this account's unspent, available stealth outputs (unknown, spent, or in use by another operation).`);
+                }
+                if (record.resourceAddress !== resourceAddress)
+                    throw new Error(`htlcFund: ${commitment.slice(0, 12)}… holds ${record.resourceAddress}, not ${resourceAddress}.`);
+                const substateId = stealthUtxoSubstateId(resourceAddress, fromHex(record.commitment));
+                const decrypted = await decryptOwnedUtxo(crypto, viewSecret, await provider.getSubstate(substateId), substateId);
+                if (!decrypted || decrypted.value !== BigInt(record.amount)) {
+                    throw new Error(`htlcFund: ${commitment.slice(0, 12)}… is not spendable as recorded (already spent, or its on-chain value differs).`);
+                }
+                chosen.push(record);
+            }
+        }
+        else {
+            const readable = await this.filterReadableShieldedOutputs(records, resourceAddress, amount);
+            chosen = selectShieldedUtxosForAmount(readable, resourceAddress, amount).selected;
         }
-        return { transactionId, conditions, ownCommitment, outputMask };
+        const total = chosen.reduce((s, r) => s + BigInt(r.amount), 0n);
+        if (total < amount)
+            throw new Error(`htlcFund: the selected stealth outputs hold ${total}, less than the ${amount} to lock.`);
+        return { commitments: chosen.map((r) => r.commitment), change: total - amount };
+    }
+    /**
+     * Checks a funded HTLC against agreed terms *without* claiming it — the verification a swap
+     * protocol runs before it reveals anything (or before it funds its own side). Returns every
+     * problem found; an empty list means the HTLC is exactly what was agreed. `htlcClaim` runs the
+     * same checks itself and refuses to reveal the preimage if any fail.
+     */
+    async verifyHtlc(resourceAddress, commitmentHex, conditions, expected = {}, preimageHex) {
+        const provider = await this.getProvider();
+        const substateId = stealthUtxoSubstateId(resourceAddress, fromHex(commitmentHex));
+        let substate = null;
+        try {
+            substate = await provider.getSubstate(substateId);
+        }
+        catch {
+            substate = null;
+        }
+        const decrypted = substate
+            ? await decryptOwnedUtxo(new WasmStealthCrypto(this.network), await this.signer.getViewSecret(), substate, substateId)
+            : null;
+        const currentEpoch = BigInt(await provider.getCurrentEpoch());
+        const facts = {
+            value: decrypted ? decrypted.value : null,
+            onChainRoot: substate ? findScriptRoot(substate) : null,
+            conditions,
+            claimantPublicKeyHex: toHex(parseOotleAddress(await this.getWalletAddress()).owner_key),
+            currentEpoch,
+            preimageHashHex: preimageHex !== undefined ? await sha256Hex(fromHex(preimageHex)) : undefined,
+        };
+        const problems = substate
+            ? verifyHtlcTerms(facts, expected)
+            : ["The HTLC output wasn't found on-chain — it may not be funded yet, or already claimed or refunded."];
+        return { ok: problems.length === 0, problems, value: facts.value, currentEpoch };
     }
     /**
      * Claims a funded HTLC (the counterpart to `htlcFund`): reveals the claim leaf's SHA-256
-     * preimage to spend the script-path-locked output, moving `amount` into a brand-new, normal
-     * (freely key-spendable) stealth output owned by this account.
+     * preimage to spend the script-path-locked output into a brand-new, normal (freely
+     * key-spendable) stealth output owned by this account — which is recorded in the shielded
+     * ledger, so the claimed funds are immediately spendable/visible.
      *
-     * This account must be the intended claimant — `htlcFund` addressed the output to this
-     * account's own wallet address, so it can unblind it the normal way: fetch the `utxo_...`
-     * substate and decrypt with this account's own view secret, exactly like `claimPrivatePayment`
-     * does for any other incoming stealth payment. `conditions` must be the *exact* two-leaf tree
-     * `htlcFund` returned (or was handed out of band) — the wrong tree produces a script-path
-     * witness whose condition root won't match the output's committed `SpendAuthorization::Script`
-     * root, and `buildStealthTransferStatement`/the network both reject the spend.
+     * **Nothing is revealed until the HTLC is proven safe.** Before the preimage leaves this device
+     * it checks (see `verifyHtlc`): the output decrypts as ours; its amount (`expected.amount` /
+     * `minAmount`); the tree is a standard HTLC whose claim leaf is *our* key (and, if given, whose
+     * refund leaf is the agreed counterparty); the on-chain condition root equals the tree's root;
+     * the preimage hashes to the lock; and at least `expected.minEpochsBeforeRefund` (default 1)
+     * claim-admissible epochs remain. Any failure throws `HtlcVerificationError`.
      *
-     * Fees are paid from this account's own existing revealed balance via `pay_fee` (same as any
-     * other transaction this wallet submits), not from the claimed HTLC funds — a transaction's fee
-     * instructions execute in a separate phase *before* its main instructions, so the claim's own
-     * `StealthTransfer` instruction (a main instruction) can't fund its own fee even in principle.
-     *
-     * Bypasses `StealthTransfer`/`WalletStealthAuthorizer` entirely — that builder pipeline only
-     * ever produces key-path stealth inputs (a one-time DH signature per input), which doesn't
-     * apply here: this spend's authorization is the revealed script-path leaf itself (its
-     * `AccessRule` atom, satisfied by this account's normal transaction signature), not a stealth
-     * spend key. `buildStealthTransferStatement` (tari-project/tari-ootle#2431) produces the
-     * complete statement — inputs/outputs/balance proof/covenant claims — in one call from the
-     * unblinded mask+value and the two witnesses below, so there is nothing left for the builder
-     * pipeline to add.
+     * Then the exact claim is dry-run (`preflight`, default on) so a claim that would fail never
+     * publishes the preimage on-chain, the journal entry moves to `claim_armed`, and only then is it
+     * submitted. The fee stays in its own lane (native TARI, public or private) — the claim's main
+     * instruction never funds its own fee. Note a dry run does send the transaction (preimage
+     * included) to the indexer's dry-run endpoint; pass `preflight: false` if that indexer isn't one
+     * you trust with it.
      */
-    async htlcClaim(resourceAddress, commitmentHex, conditions, preimageHex, maxFee = 50000n, feeType = { kind: "transparent" }) {
+    async htlcClaim(resourceAddress, commitmentHex, conditions, preimageHex, maxFee = 50000n, feeType = { kind: "transparent" }, options = {}) {
         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)}`);
         }
-        const provider = await this.getProvider();
-        const account = await this.getComponentAddress();
-        const walletAddress = await this.getWalletAddress();
-        const commitment = fromHex(commitmentHex);
-        const substateId = stealthUtxoSubstateId(resourceAddress, commitment);
-        const substate = await provider.getSubstate(substateId);
-        const viewSecret = await this.signer.getViewSecret();
-        const decrypted = await decryptOwnedUtxo(new WasmStealthCrypto(this.network), viewSecret, substate, substateId);
-        if (!decrypted) {
-            throw new Error("This HTLC output doesn't belong to your account, or wasn't found on-chain — it may already be claimed or refunded.");
-        }
         const claimLeaf = conditions[0];
         if (!claimLeaf)
             throw new Error("htlcClaim: conditions must be the two-leaf [claim, refund] tree htlcFund returned");
+        const verification = await this.verifyHtlc(resourceAddress, commitmentHex, conditions, options.expected ?? {}, preimageHex);
+        if (!verification.ok)
+            throw new HtlcVerificationError(verification.problems);
+        const value = verification.value;
+        const { hashLockHex, refundEpoch } = describeHtlcConditions(conditions);
+        const provider = await this.getProvider();
+        const substateId = stealthUtxoSubstateId(resourceAddress, fromHex(commitmentHex));
+        const decrypted = await decryptOwnedUtxo(new WasmStealthCrypto(this.network), await this.signer.getViewSecret(), await provider.getSubstate(substateId), substateId);
+        if (!decrypted)
+            throw new Error("htlcClaim: the HTLC output no longer decrypts — it may have just been claimed or refunded.");
+        const walletAddress = await this.getWalletAddress();
         const statementJson = buildHtlcSpendStatement({
             network: this.network,
             conditions,
             leaf: claimLeaf,
             data: fromHex(preimageHex),
             mask: decrypted.mask.toHex(),
-            value: decrypted.value,
+            value,
             destinationWalletAddress: walletAddress,
             resourceAddress,
         });
-        const privateFee = await this.resolvePrivateFee(feeType, maxFee);
-        const transactionId = await submitHtlcSpend({
-            provider,
-            signer: this.signer,
-            network: this.network,
-            account,
+        return this.spendHtlc({
+            kind: "claim",
             resourceAddress,
-            substateId,
+            commitmentHex,
+            conditions,
+            hashLockHex,
+            refundEpoch,
+            value,
             statementJson,
             maxFee,
-            timeoutLabel: "submitting the HTLC claim transaction",
-            privateFee,
+            feeType,
+            preflight: options.preflight !== false,
+            armedStatus: "claim_armed",
+            label: "submitting the HTLC claim transaction",
         });
-        if (privateFee && feeType.kind === "private") {
-            await this.recordPrivateFeeSpend(localAccountId(this.index), feeType.feeResourceAddress, privateFee, transactionId);
-        }
-        return { transactionId };
     }
     /**
-     * Refunds an HTLC this account itself funded (via `htlcFund`), once `refundEpoch` has passed:
-     * reveals the refund leaf to spend the output back into a brand-new, normal (freely
-     * key-spendable) stealth output owned by this account.
+     * Refunds an HTLC this account itself funded (via `htlcFund`), once the refund path is open:
+     * reveals the refund leaf to spend the output back into a brand-new, normal stealth output owned
+     * by this account (recorded in the shielded ledger).
      *
-     * Unlike `htlcClaim`, this account **cannot** decrypt the output on-chain — `htlcFund` addressed
-     * it to the claimant's wallet, so `encrypted_data` is encrypted for the claimant's view key, not
-     * this account's. `amount` and `outputMaskHex` must be exactly what `htlcFund` returned (or
-     * otherwise already known — this account chose `amount` itself when funding, and `outputMaskHex`
-     * is `htlcFund`'s own return value for exactly this purpose): reconstructing the commitment from
-     * a wrong mask or amount fails cleanly (the resulting input just doesn't match the on-chain
-     * commitment, so the network rejects the spend) rather than silently, but there is no recovery
-     * path if this account discarded the mask — see `htlcFund`'s doc comment.
-     *
-     * Otherwise identical to `htlcClaim`: same fee-from-own-balance reasoning, same
-     * `buildStealthTransferStatement`-in-one-call approach, same bypass of
-     * `StealthTransfer`/`WalletStealthAuthorizer`.
+     * The refund path is `AfterEpoch(refundEpoch)`, i.e. open when `currentEpoch >= refundEpoch` —
+     * checked here first, so an early refund fails with a clear message instead of an on-chain
+     * rejection. The funder can't decrypt the output (it's addressed to the claimant), so `amount` and
+     * `outputMaskHex` must be exactly what `htlcFund` returned — or use `refundFromJournal(journalId)`,
+     * which reads them back from the journal `htlcFund` wrote before submitting.
      */
-    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();
-        const commitment = fromHex(commitmentHex);
-        const substateId = stealthUtxoSubstateId(resourceAddress, commitment);
+    async htlcRefund(resourceAddress, commitmentHex, conditions, amount, outputMaskHex, maxFee = 50000n, feeType = { kind: "transparent" }, options = {}) {
         const refundLeaf = conditions[1];
         if (!refundLeaf)
             throw new Error("htlcRefund: conditions must be the two-leaf [claim, refund] tree htlcFund returned");
+        const { hashLockHex, refundEpoch } = describeHtlcConditions(conditions);
+        const provider = await this.getProvider();
+        const currentEpoch = BigInt(await provider.getCurrentEpoch());
+        if (!isHtlcRefundable(currentEpoch, refundEpoch)) {
+            throw new Error(`htlcRefund: the refund path opens at epoch ${refundEpoch}; the current epoch is ${currentEpoch}.`);
+        }
+        const walletAddress = await this.getWalletAddress();
         const statementJson = buildHtlcSpendStatement({
             network: this.network,
             conditions,
@@ -1662,23 +1930,215 @@ export class OotleAccount {
             destinationWalletAddress: walletAddress,
             resourceAddress,
         });
-        const privateFee = await this.resolvePrivateFee(feeType, maxFee);
-        const transactionId = await submitHtlcSpend({
-            provider,
-            signer: this.signer,
-            network: this.network,
-            account,
+        if (statementInputCommitment(statementJson) !== commitmentHex.toLowerCase()) {
+            throw new Error("htlcRefund: this amount/mask doesn't reproduce the HTLC commitment — use the exact values htlcFund returned (or refundFromJournal).");
+        }
+        return this.spendHtlc({
+            kind: "refund",
             resourceAddress,
-            substateId,
+            commitmentHex,
+            conditions,
+            hashLockHex,
+            refundEpoch,
+            value: amount,
             statementJson,
             maxFee,
-            timeoutLabel: "submitting the HTLC refund transaction",
-            privateFee,
+            feeType,
+            preflight: options.preflight !== false,
+            armedStatus: "prepared",
+            label: "submitting the HTLC refund transaction",
         });
-        if (privateFee && feeType.kind === "private") {
-            await this.recordPrivateFeeSpend(localAccountId(this.index), feeType.feeResourceAddress, privateFee, transactionId);
+    }
+    /** Refunds an HTLC this account funded, using the conditions/mask/amount `htlcFund` journaled. */
+    async refundFromJournal(journalId, maxFee = 50000n, feeType = { kind: "transparent" }) {
+        const entry = await getHtlcJournalEntry(journalId);
+        if (!entry || entry.kind !== "fund" || entry.accountId !== localAccountId(this.index)) {
+            throw new Error(`refundFromJournal: ${journalId} is not an HTLC this account funded.`);
+        }
+        if (!entry.htlcCommitment || !entry.outputMask)
+            throw new Error(`refundFromJournal: ${journalId} has no HTLC commitment/mask recorded.`);
+        return this.htlcRefund(entry.resourceAddress, entry.htlcCommitment, entry.conditions, BigInt(entry.amount), entry.outputMask, maxFee, feeType);
+    }
+    /** Shared claim/refund path: private-fee reservation, dry run, journal, submit, bookkeeping. */
+    async spendHtlc(p) {
+        const opId = newOperationId(`htlc-${p.kind}`);
+        const accountId = localAccountId(this.index);
+        const provider = await this.getProvider();
+        const account = await this.getComponentAddress();
+        const substateId = stealthUtxoSubstateId(p.resourceAddress, fromHex(p.commitmentHex));
+        const ownCommitment = statementOutputCommitment(p.statementJson, 0);
+        try {
+            const privateFee = await this.resolvePrivateFee(p.feeType, p.maxFee, [], opId);
+            const envelopeFor = (dryRun) => buildHtlcSpendEnvelope({
+                provider,
+                signer: this.signer,
+                network: this.network,
+                account,
+                resourceAddress: p.resourceAddress,
+                substateId,
+                statementJson: p.statementJson,
+                maxFee: p.maxFee,
+                privateFee,
+                dryRun,
+            });
+            if (p.preflight)
+                await this.dryRunEnvelope(await envelopeFor(true));
+            const envelope = await envelopeFor(false);
+            const now = Date.now();
+            const entry = {
+                id: opId,
+                accountId,
+                kind: p.kind,
+                status: p.armedStatus,
+                resourceAddress: p.resourceAddress,
+                amount: p.value.toString(),
+                conditions: p.conditions,
+                hashLockHex: p.hashLockHex,
+                refundEpoch: p.refundEpoch.toString(),
+                htlcCommitment: p.commitmentHex.toLowerCase(),
+                ownCommitment,
+                ownAmount: p.value.toString(),
+                privateFee: journalFee(p.feeType, privateFee),
+                envelope,
+                createdAt: now,
+                updatedAt: now,
+            };
+            const { transactionId } = await this.submitJournaled(entry, provider, p.label);
+            return { transactionId, receivedCommitment: ownCommitment, amount: p.value, journalId: opId };
+        }
+        catch (e) {
+            if (!(e instanceof HtlcUnknownOutcomeError))
+                await releaseReservations(opId);
+            throw e;
+        }
+    }
+    /**
+     * Journal → submit → poll → bookkeeping, for every HTLC operation. The entry (with its sealed
+     * envelope and recovery data) is persisted before submission; a definitive rejection marks it
+     * `failed`, anything ambiguous marks it `unknown` and throws `HtlcUnknownOutcomeError`.
+     */
+    async submitJournaled(entry, provider, label) {
+        await putHtlcJournalEntry(entry);
+        let transactionId;
+        try {
+            transactionId = await submitTransaction(provider, entry.envelope);
+            await updateHtlcJournalEntry(entry.id, { status: "submitted", transactionId });
+            const response = await withTimeout(pollTransactionResult(provider, transactionId), 60_000, label);
+            await this.finalizeHtlcEntry({ ...entry, transactionId }, response);
+            return { transactionId };
+        }
+        catch (e) {
+            const error = e instanceof Error ? e.message : String(e);
+            if (isDefinitiveRejection(e)) {
+                await updateHtlcJournalEntry(entry.id, { status: "failed", error, transactionId });
+                await releaseReservations(entry.id);
+                throw e;
+            }
+            await updateHtlcJournalEntry(entry.id, { status: "unknown", error, transactionId });
+            throw new HtlcUnknownOutcomeError(entry.id, { kind: entry.kind, transactionId, conditions: entry.conditions, htlcCommitment: entry.htlcCommitment, outputMask: entry.outputMask }, e);
         }
-        return { transactionId };
+    }
+    /** Applies a confirmed HTLC operation's local bookkeeping. Idempotent (see `addShieldedOutput`). */
+    async finalizeHtlcEntry(entry, response) {
+        const txId = entry.transactionId;
+        await recordKnownVersions(response);
+        if (entry.ownCommitment && entry.ownAmount) {
+            await recordKnownShieldedOutput(entry.accountId, entry.resourceAddress, entry.ownCommitment, BigInt(entry.ownAmount), txId);
+        }
+        for (const c of entry.spentCommitments ?? [])
+            await markShieldedOutputSpent(entry.accountId, c);
+        if (entry.privateFee) {
+            await recordKnownShieldedOutput(entry.accountId, entry.privateFee.feeResourceAddress, entry.privateFee.changeCommitment, BigInt(entry.privateFee.changeAmount), txId);
+            await markShieldedOutputSpent(entry.accountId, entry.privateFee.spentCommitment);
+        }
+        await updateHtlcJournalEntry(entry.id, { status: "confirmed", transactionId: txId, error: undefined });
+        await releaseReservations(entry.id);
+    }
+    /** This account's HTLC journal (every fund/claim/refund and its state), newest first. The
+     * entries' `envelope` of a claim contains the preimage — don't display or export it. */
+    async listHtlcs() {
+        return (await listHtlcJournal(localAccountId(this.index))).sort((a, b) => b.createdAt - a.createdAt);
+    }
+    /**
+     * Resolves every HTLC operation whose outcome isn't final (`prepared`, `claim_armed`,
+     * `submitted`, `unknown`) — call at startup and after any `HtlcUnknownOutcomeError`. An entry
+     * with no transaction id is resubmitted with its *identical* sealed envelope (the same
+     * transaction, so it can't execute twice; an expired one is simply rejected); then its result is
+     * checked once. Confirmed entries get their bookkeeping applied, rejected ones are marked
+     * `failed` and release their reserved UTXOs, still-pending ones are left for the next call.
+     */
+    async reconcileHtlcs() {
+        const provider = await this.getProvider();
+        const open = (await listHtlcJournal(localAccountId(this.index))).filter((e) => ["prepared", "claim_armed", "submitted", "unknown"].includes(e.status));
+        const out = [];
+        for (const entry of open) {
+            let current = entry;
+            try {
+                let txId = entry.transactionId;
+                if (!txId) {
+                    try {
+                        txId = await submitTransaction(provider, entry.envelope);
+                        current = (await updateHtlcJournalEntry(entry.id, { status: "submitted", transactionId: txId })) ?? current;
+                    }
+                    catch (e) {
+                        const error = e instanceof Error ? e.message : String(e);
+                        if (isDefinitiveRejection(e) || /HTTP 4\d\d/.test(error)) {
+                            current = (await updateHtlcJournalEntry(entry.id, { status: "failed", error })) ?? current;
+                            await releaseReservations(entry.id);
+                        }
+                        else {
+                            current = (await updateHtlcJournalEntry(entry.id, { status: "unknown", error })) ?? current;
+                        }
+                        out.push(current);
+                        continue;
+                    }
+                }
+                const response = await provider.getTransactionResult(txId);
+                const result = response.result;
+                if (result === "Pending") {
+                    out.push(current);
+                    continue;
+                }
+                if ("Rejected" in result) {
+                    current = (await updateHtlcJournalEntry(entry.id, { status: "failed", error: result.Rejected.details })) ?? current;
+                    await releaseReservations(entry.id);
+                    out.push(current);
+                    continue;
+                }
+                const outcome = result.Finalized.execution_result?.finalize.result;
+                if (outcome && typeof outcome === "object" && "Accept" in outcome) {
+                    await this.finalizeHtlcEntry({ ...entry, transactionId: txId }, response);
+                    current = (await getHtlcJournalEntry(entry.id)) ?? current;
+                }
+                else {
+                    current = (await updateHtlcJournalEntry(entry.id, { status: "failed", error: JSON.stringify(outcome ?? null) })) ?? current;
+                    await releaseReservations(entry.id);
+                }
+            }
+            catch (e) {
+                // A transient error on one entry must not block the rest; it stays open for next time.
+                current = (await updateHtlcJournalEntry(entry.id, { error: e instanceof Error ? e.message : String(e) })) ?? current;
+            }
+            out.push(current);
+        }
+        return out;
+    }
+    /**
+     * Stealth commitments this account must not select right now: reserved by another in-flight
+     * operation, or spent (as an input or a private fee) by an HTLC operation whose outcome isn't
+     * final — those may already be gone on-chain even after their reservation lapses.
+     */
+    async unavailableCommitments(accountId, holder) {
+        const out = await listReservedCommitments(accountId, holder);
+        for (const e of await listHtlcJournal(accountId)) {
+            if (e.id === holder || !["prepared", "claim_armed", "submitted", "unknown"].includes(e.status))
+                continue;
+            for (const c of e.spentCommitments ?? [])
+                out.add(c);
+            if (e.privateFee)
+                out.add(e.privateFee.spentCommitment);
+        }
+        return out;
     }
     /**
      * Sends `amount` of this account's shielded balance for `resourceAddress` directly to
@@ -1710,68 +2170,76 @@ export class OotleAccount {
     async sendPrivately(resourceAddress, recipientWalletAddress, amount, maxFee = 100000n, memo, minimumValuePromise = 0n, feeType = { kind: "transparent" }) {
         assertValidMinimumValuePromise(minimumValuePromise, amount);
         const accountId = localAccountId(this.index);
-        const records = await this.filterReadableShieldedOutputs(await listShieldedOutputs(accountId), resourceAddress, amount);
+        const opId = newOperationId("send-private");
+        const unavailable = await this.unavailableCommitments(accountId, opId);
+        const records = await this.filterReadableShieldedOutputs((await listShieldedOutputs(accountId)).filter((r) => !unavailable.has(r.commitment)), resourceAddress, amount);
         const { commitments, changeAmount } = resolveSendPrivatelyPlan(records, resourceAddress, amount);
-        const dust = 1n;
-        const provider = await this.getProvider();
-        const account = await this.getComponentAddress();
-        const ownWalletAddress = await this.getWalletAddress();
-        // See shield()'s comment: the resource's own substate must be pinned explicitly -- prepare()
-        // never adds it on its own.
-        let builder = new StealthTransfer(provider, resourceAddress)
-            .withBuilder((b) => b.addInput({ substate_id: resourceAddress, version: null }))
-            .spendRevealedInput(account, dust);
-        for (const commitment of commitments) {
-            builder = builder.spendStealthInput(account, fromHex(commitment));
-        }
-        // The promise rides on the recipient's output only. Putting one on the change output would
-        // publish a floor on this account's own remaining private balance -- an unrelated disclosure the
-        // caller never asked for, and one the recipient has no interest in.
-        builder = builder.toStealthOutput(createOutput({ destination: recipientWalletAddress, amount, resourceAddress, memo: toMemo(memo), minimumValuePromise }));
-        if (changeAmount > 0n) {
-            builder = builder.toStealthOutput(createOutput({ destination: ownWalletAddress, amount: changeAmount, resourceAddress }));
-        }
-        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;
-        await addPendingShield({
-            transactionId,
-            accountId,
-            resourceAddress,
-            amount: changeAmount.toString(),
-            spentCommitments: commitments,
-            ownCommitment,
-        });
+        await reserveCommitments(accountId, commitments, opId);
         try {
-            const response = await withTimeout(pollTransactionResult(provider, transactionId), 60_000, "submitting the private send");
-            await recordKnownVersions(response);
-            if (ownCommitment)
-                await recordKnownShieldedOutput(accountId, resourceAddress, ownCommitment, changeAmount, transactionId);
+            const dust = 1n;
+            const provider = await this.getProvider();
+            const account = await this.getComponentAddress();
+            const ownWalletAddress = await this.getWalletAddress();
+            // See shield()'s comment: the resource's own substate must be pinned explicitly -- prepare()
+            // never adds it on its own.
+            let builder = new StealthTransfer(provider, resourceAddress).withRevealedReceiver(this.accountPublicKey)
+                .withBuilder((b) => b.addInput({ substate_id: resourceAddress, version: null }))
+                .spendRevealedInput(account, dust);
             for (const commitment of commitments) {
-                await markShieldedOutputSpent(accountId, commitment);
+                builder = builder.spendStealthInput(account, fromHex(commitment));
             }
-            if (privateFee && feeType.kind === "private") {
-                await this.recordPrivateFeeSpend(accountId, feeType.feeResourceAddress, privateFee, transactionId);
+            // The promise rides on the recipient's output only. Putting one on the change output would
+            // publish a floor on this account's own remaining private balance -- an unrelated disclosure the
+            // caller never asked for, and one the recipient has no interest in.
+            builder = builder.toStealthOutput(createOutput({ destination: recipientWalletAddress, amount, resourceAddress, memo: toMemo(memo), minimumValuePromise }));
+            if (changeAmount > 0n) {
+                builder = builder.toStealthOutput(createOutput({ destination: ownWalletAddress, amount: changeAmount, resourceAddress }));
+            }
+            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, opId);
+            // 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;
+            await addPendingShield({
+                transactionId,
+                accountId,
+                resourceAddress,
+                amount: changeAmount.toString(),
+                spentCommitments: commitments,
+                ownCommitment,
+            });
+            try {
+                const response = await withTimeout(pollTransactionResult(provider, transactionId), 60_000, "submitting the private send");
+                await recordKnownVersions(response);
+                if (ownCommitment)
+                    await recordKnownShieldedOutput(accountId, resourceAddress, ownCommitment, changeAmount, transactionId);
+                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);
+            }
+            return {
+                transactionId,
+                recipientCommitment,
+                recipientSubstateId: stealthUtxoSubstateId(resourceAddress, fromHex(recipientCommitment)),
+                minimumValuePromise: minimumValuePromise.toString(),
+            };
         }
         finally {
-            await removePendingShield(transactionId);
+            await releaseReservations(opId);
         }
-        return {
-            transactionId,
-            recipientCommitment,
-            recipientSubstateId: stealthUtxoSubstateId(resourceAddress, fromHex(recipientCommitment)),
-            minimumValuePromise: minimumValuePromise.toString(),
-        };
     }
     /**
      * The recipient-side counterpart to `sendPrivately()`'s commitment hand-off: given a commitment
@@ -1824,9 +2292,156 @@ export class OotleAccount {
     async claimBurn(contents, maxFee, memo = "Burnt funds claimed from L1") {
         if (maxFee !== undefined && maxFee <= 0n)
             throw new Error(`claimBurn: maxFee must be > 0, got ${maxFee}`);
+        const { buildClaim, value, provider } = await this.prepareBurnClaim(contents, memo);
+        let fee = maxFee ?? (await this.estimateClaimFee(await buildClaim(claimFeeProbe(value), true)));
+        let attempt = await buildClaim(fee, false);
+        let transactionId = await submitTransaction(provider, attempt.envelope);
+        let response;
+        try {
+            response = await withTimeout(pollTransactionResult(provider, transactionId), 90_000, "claiming the burn");
+        }
+        catch (e) {
+            // A real run can meter a little differently from its dry run. When the rejection names the
+            // fee it wanted, a measured fee is resubmitted once at exactly that; an explicit one is not.
+            const required = maxFee === undefined ? requiredFeeFromRejection(e) : null;
+            if (required === null || required <= fee)
+                throw e;
+            fee = required;
+            attempt = await buildClaim(fee, false);
+            transactionId = await submitTransaction(provider, attempt.envelope);
+            response = await withTimeout(pollTransactionResult(provider, transactionId), 90_000, "claiming the burn");
+        }
+        await recordKnownVersions(response);
+        await recordKnownShieldedOutput(localAccountId(this.index), TARI_RESOURCE_ADDRESS, attempt.ownCommitment, attempt.claimedAmount, transactionId, memo);
+        return { transactionId, claimedAmount: attempt.claimedAmount, commitment: attempt.ownCommitment, fee };
+    }
+    /**
+     * The fee `claimBurn(contents)` would pay, measured by dry-running the claim -- nothing is
+     * submitted. The indexer's dry run checks everything about the claim except the burn's L1
+     * inclusion (the burn output rules, its ownership proof, the claim-key signature), so this also
+     * tells a caller whether the claim is well formed before anything is spent.
+     */
+    async estimateClaimBurnFee(contents, memo = "Burnt funds claimed from L1") {
+        const { buildClaim, value } = await this.prepareBurnClaim(contents, memo);
+        return this.estimateClaimFee(await buildClaim(claimFeeProbe(value), true));
+    }
+    /**
+     * `unshield()` for an account whose component doesn't exist on-chain yet. Everything runs in the
+     * fee phase, the way Tari's own wallet unshields into a new account: the stealth inputs reveal
+     * `amount + fee` (any excess returns as a stealth change output), `TakeFromBucket` splits off the
+     * fee for `PayFeeFromBucket`, and `CreateAccount` creates this account from the rest. The fee is
+     * measured with a dry run first, since a fee revealed from stealth funds is never refunded.
+     *
+     * The seal key is authorized as a signer and named as the revealed output's receiver
+     * (tari-ootle#2645); each input's one-time key co-signs its key-path spend.
+     */
+    async unshieldIntoNewAccount(provider, resourceAddress, amount, commitments, remainder, maxFee, memo) {
+        if (resourceAddress !== TARI_RESOURCE_ADDRESS) {
+            throw new Error("This account doesn't exist on-chain yet. Unshield some TARI first to create it, then unshield other resources.");
+        }
+        const accountId = localAccountId(this.index);
+        const crypto = new WasmStealthCrypto(this.network);
+        const viewSecret = await this.signer.getViewSecret();
+        const walletAddress = await this.getWalletAddress();
+        const inputs = await Promise.all(commitments.map(async (commitmentHex) => {
+            const substateId = stealthUtxoSubstateId(resourceAddress, fromHex(commitmentHex));
+            const substate = await provider.getSubstate(substateId);
+            const decrypted = await decryptOwnedUtxo(crypto, viewSecret, substate, substateId);
+            if (!decrypted)
+                throw new Error(`unshield: cannot decrypt ${substateId} -- it isn't this account's, or it is already spent.`);
+            const nonce = substate.substate.Utxo.output.output
+                .public_nonce;
+            return { commitmentHex, substateId, mask: decrypted.mask, nonce };
+        }));
+        const inputMask = await crypto.aggregateInputMasks(inputs.map((i) => i.mask));
+        const inputsJson = JSON.stringify({
+            inputs: inputs.map((i) => ({ commitment: i.commitmentHex, witness: "KeyPath" })),
+            revealed_amount: "0",
+        });
+        const sealKeypair = generateSealKeypair();
+        const build = async (fee, dryRun) => {
+            // The fee comes out of the stealth side: what's revealed is `amount + fee`, and the change
+            // output shrinks by `fee`.
+            const change = remainder - fee;
+            if (fee <= 0n || change < 0n) {
+                throw new Error(`unshield: the private balance does not cover ${amount} plus the ${fee} fee to create the account`);
+            }
+            const revealed = amount + fee;
+            let outputsStatement;
+            let outputMask = Mask.zero();
+            if (change > 0n) {
+                const output = createOutput({ destination: walletAddress, amount: change, resourceAddress, memo: toMemo(memo) });
+                ({ statement: outputsStatement, outputMask } = await crypto.generateOutputsStatement([output], revealed, sealKeypair.public_key));
+            }
+            else {
+                outputsStatement = new StealthOutputsStatement(revealOnlyOutputsJson(revealed, sealKeypair.public_key));
+            }
+            const inputsStatement = new StealthInputsStatement([], 0n, inputsJson);
+            const balanceProof = await crypto.generateBalanceProofSignature(inputMask, outputMask, inputsJson, outputsStatement.statementJson);
+            const statement = new StealthTransferStatement(inputsStatement, outputsStatement, balanceProof);
+            await crypto.validateTransfer(statement);
+            const changeCommitment = change > 0n ? outputsStatement.parsed().outputs[0].output.commitment : null;
+            const builder = TransactionBuilder.new(this.network, await resolveMaxEpoch(provider));
+            for (const instruction of [
+                {
+                    StealthTransfer: {
+                        resource_address_ref: { Address: resourceAddress },
+                        statement: { __ootleRawJson: statement.toCompactJson() },
+                        revealed_input_bucket: null,
+                    },
+                },
+                { PutLastInstructionOutputOnWorkspace: { key: 0 } },
+                { TakeFromBucket: { input_bucket: { id: 0, offset: null }, amount: fee.toString(), output_bucket: 1 } },
+                { PayFeeFromBucket: { bucket: { id: 1, offset: null } } },
+                {
+                    CreateAccount: {
+                        owner_public_key: toHex(this.accountPublicKey),
+                        owner_rule: null,
+                        access_rules: null,
+                        bucket_workspace_id: { id: 0, offset: null },
+                    },
+                },
+            ]) {
+                builder.addFeeInstruction(instruction);
+            }
+            builder.addInput({ substate_id: resourceAddress, version: null, is_write: false });
+            for (const input of inputs)
+                builder.addInput({ substate_id: input.substateId, version: null });
+            const unsignedBody = builder.buildUnsignedTransaction();
+            unsignedBody.is_seal_signer_authorized = true;
+            unsignedBody.dry_run = dryRun;
+            const unsignedTx = await resolveTransaction(provider, unsignedBody);
+            const signers = inputs.map((input) => ({
+                getAddress: async () => walletAddress,
+                getPublicKey: async () => parseOotleAddress(walletAddress).owner_key,
+                signTransaction: async (tx, sealPublicKey) => {
+                    const json = serializeUnsignedTx(tx);
+                    return [await this.signer.addStealthSignature(json, fromHex(input.nonce), sealPublicKey, { crypto })];
+                },
+            }));
+            const signed = await signTransaction(signers, unsignedTx, sealKeypair);
+            return { envelope: sealTransaction(signed), change, changeCommitment };
+        };
+        const probe = maxFee < remainder ? maxFee : remainder;
+        const fee = await this.estimateClaimFee(await build(probe, true), "unshield");
+        if (fee > maxFee)
+            throw new Error(`unshield: creating the account costs ${fee}, above the ${maxFee} limit`);
+        const attempt = await build(fee, false);
+        const transactionId = await submitTransaction(provider, attempt.envelope);
+        const response = await withTimeout(pollTransactionResult(provider, transactionId), 90_000, "unshielding into a new account");
+        await recordKnownVersions(response);
+        for (const input of inputs)
+            await markShieldedOutputSpent(accountId, input.commitmentHex);
+        if (attempt.changeCommitment) {
+            await recordKnownShieldedOutput(accountId, resourceAddress, attempt.changeCommitment, attempt.change, transactionId, memo);
+        }
+        return { transactionId };
+    }
+    /** Verifies a burn is ours and returns a builder for its claim transaction at a given fee. */
+    async prepareBurnClaim(contents, memo) {
         const proof = contents.claim_proof;
         const burnCommitment = fromHex(proof.commitment);
-        const senderOffset = fromHex(proof.sender_offset_public_key);
+        const senderOffset = fromHex(proof.output.sender_offset_public_key);
         const value = BigInt(proof.value);
         const stealthSecret = burnClaimStealthSecret(this.ownerSecret, senderOffset);
         const ownershipValid = validateBurnClaimOwnershipProof(this.network, fromHex(proof.ownership_proof.public_nonce), fromHex(proof.ownership_proof.signature), burnCommitment, value, stealthSecret);
@@ -1841,6 +2456,7 @@ export class OotleAccount {
         }
         const provider = await this.getProvider();
         const walletAddress = await this.getWalletAddress();
+        // The claim's only signer, so it is also the receiver of the revealed fee (tari-ootle#2645).
         const sealKeypair = { secret_key: stealthSecret, public_key: publicKeyFromSecretKey(stealthSecret) };
         // One claim transaction revealing `fee`. The output statement encodes the revealed amount, so
         // every fee needs its own statement and proofs.
@@ -1850,7 +2466,7 @@ export class OotleAccount {
                 throw new Error(`claimBurn: the burn (${decrypted.value}) does not cover the claim fee (${fee})`);
             }
             const output = createOutput({ destination: walletAddress, amount: claimedAmount, resourceAddress: TARI_RESOURCE_ADDRESS, memo: toMemo(memo) });
-            const { statement: outputsStatement, outputMask } = await crypto.generateOutputsStatement([output], fee);
+            const { statement: outputsStatement, outputMask } = await crypto.generateOutputsStatement([output], fee, sealKeypair.public_key);
             // The single input is the UTXO `ClaimBurn` mints in the same transaction; the instruction
             // itself authorises spending it, so it carries no witness.
             const inputsStatement = await crypto.buildInputsStatement([new StealthInput(burnCommitment)], 0n);
@@ -1871,7 +2487,7 @@ export class OotleAccount {
             })
                 .addFeeInstruction({ PutLastInstructionOutputOnWorkspace: { key: 0 } })
                 .addFeeInstruction({ PayFeeFromBucket: { bucket: { id: 0, offset: null } } })
-                .addInput({ substate_id: TARI_RESOURCE_ADDRESS, version: null });
+                .addInput({ substate_id: TARI_RESOURCE_ADDRESS, version: null, is_write: false });
             // The seal key `s` is the transaction's only signer, so it must be authorized as the main
             // signer; the TS builder leaves that off by default.
             const unsignedBody = builder.buildUnsignedTransaction();
@@ -1881,30 +2497,10 @@ export class OotleAccount {
             const signed = await signTransaction([], unsignedTx, sealKeypair);
             return { envelope: sealTransaction(signed), claimedAmount, ownCommitment };
         };
-        let fee = maxFee ?? (await this.estimateClaimFee(await buildClaim(claimFeeProbe(decrypted.value), true)));
-        let attempt = await buildClaim(fee, false);
-        let transactionId = await submitTransaction(provider, attempt.envelope);
-        let response;
-        try {
-            response = await withTimeout(pollTransactionResult(provider, transactionId), 90_000, "claiming the burn");
-        }
-        catch (e) {
-            // A real run can meter a little differently from its dry run. When the rejection names the
-            // fee it wanted, a measured fee is resubmitted once at exactly that; an explicit one is not.
-            const required = maxFee === undefined ? requiredFeeFromRejection(e) : null;
-            if (required === null || required <= fee)
-                throw e;
-            fee = required;
-            attempt = await buildClaim(fee, false);
-            transactionId = await submitTransaction(provider, attempt.envelope);
-            response = await withTimeout(pollTransactionResult(provider, transactionId), 90_000, "claiming the burn");
-        }
-        await recordKnownVersions(response);
-        await recordKnownShieldedOutput(localAccountId(this.index), TARI_RESOURCE_ADDRESS, attempt.ownCommitment, attempt.claimedAmount, transactionId, memo);
-        return { transactionId, claimedAmount: attempt.claimedAmount, commitment: attempt.ownCommitment, fee };
+        return { buildClaim, value: decrypted.value, provider };
     }
     /** Dry-runs a sealed claim and returns the fee it needs: what it was charged plus the allowance. */
-    async estimateClaimFee(dryRun) {
+    async estimateClaimFee(dryRun, what = "claim") {
         const res = await fetch(`${defaultIndexerUrl(this.network)}/transactions/dry-run`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
@@ -1919,7 +2515,7 @@ export class OotleAccount {
             // Not JSON — reported raw below.
         }
         if (!res.ok || body?.error || !body?.result) {
-            throw new Error(`Could not estimate the claim fee: ${body?.error?.message ?? text ?? res.statusText}`);
+            throw new Error(`Could not estimate the ${what} fee: ${body?.error?.message ?? text ?? res.statusText}`);
         }
         const finalize = body.result.finalize;
         const outcome = finalize.result;
@@ -1932,7 +2528,7 @@ export class OotleAccount {
             if (amount !== undefined)
                 charged += BigInt(amount);
         if (charged === 0n)
-            throw new Error("Could not estimate the claim fee: the dry run reported no cost");
+            throw new Error(`Could not estimate the ${what} fee: the dry run reported no cost`);
         return charged + FEE_ESTIMATE_ALLOWANCE;
     }
     /**
@@ -2197,7 +2793,7 @@ export function buildHtlcSpendStatement(params) {
     const destination = parseOotleAddress(params.destinationWalletAddress);
     const outputWitnessJson = createStealthOutputWitness(params.network, destination.owner_key, destination.view_key, params.value, params.resourceAddress, null, null, null, // pay_to_json: null -- default StealthPublicKey, a normal one-time key-spendable output.
     0n);
-    const statementJson = buildStealthTransferStatement(`[${inputEntry}]`, 0n, `[${outputWitnessJson}]`, 0n);
+    const statementJson = buildStealthTransferStatement(`[${inputEntry}]`, 0n, `[${outputWitnessJson}]`, 0n, new Uint8Array(0));
     // Fail fast locally rather than spend a network round trip on a malformed statement -- the same
     // check tari-ootle's own `build_stealth_transfer_statement` unit tests run before trusting its
     // output (crates/ootle_wasm/core/src/stealth/transfer.rs).
@@ -2205,17 +2801,17 @@ export function buildHtlcSpendStatement(params) {
     return statementJson;
 }
 /**
- * Submits a hand-built HTLC claim/refund transaction: one `StealthTransfer` instruction carrying
- * `statementJson` verbatim, spending `substateId`, fee paid from `account`'s own revealed balance.
+ * Builds and seals (but does not submit) a hand-built HTLC claim/refund transaction: one
+ * `StealthTransfer` instruction carrying `statementJson` verbatim, spending `substateId`, with the fee
+ * in its own lane -- native TARI from `account`'s public balance, or a private fee UTXO.
  *
- * Deliberately bypasses `TransactionBuilder`'s usual `WalletStealthAuthorizer` companion — that
- * pipeline only ever produces key-path stealth-input signatures, which don't apply to a
- * script-path spend (whose authorization is the revealed leaf's own `AccessRule`, satisfied by
- * this account's ordinary transaction signature) — `signTransaction`/`sealTransaction` alone are
- * both necessary and sufficient here, the same pipeline any plain `CallMethod`-only transaction
- * uses.
+ * Deliberately bypasses `TransactionBuilder`'s usual `WalletStealthAuthorizer` companion -- that
+ * pipeline only ever produces key-path stealth-input signatures, which don't apply to a script-path
+ * spend (whose authorization is the revealed leaf's own `AccessRule`, satisfied by this account's
+ * ordinary transaction signature) -- `signTransaction`/`sealTransaction` alone are both necessary and
+ * sufficient here. `dryRun` marks the transaction before it's signed, for `dryRunEnvelope`.
  */
-async function submitHtlcSpend(params) {
+async function buildHtlcSpendEnvelope(params) {
     const maxEpoch = await resolveMaxEpoch(params.provider);
     const builder = TransactionBuilder.new(params.network, maxEpoch)
         .addInput({ substate_id: params.substateId, version: null })
@@ -2243,14 +2839,12 @@ async function submitHtlcSpend(params) {
     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 unsigned = builder.buildUnsignedTransaction();
+    unsigned.dry_run = params.dryRun;
+    const unsignedTx = await resolveTransaction(params.provider, unsigned);
     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);
-    await recordKnownVersions(response);
-    return transactionId;
+    return sealTransaction(signed);
 }
 function extractOutputCommitment(spec, outputIndex) {
     const parsed = spec.statement.outputsStatement.parsed();
@@ -2642,6 +3236,14 @@ export async function pollTransactionResult(provider, transactionId, timeoutMs =
         if ("Rejected" in result) {
             throw new Error(`Transaction ${transactionId} was rejected: ${result.Rejected.details}`);
         }
+        // Consensus can abort a transaction whatever its execution said (a lock conflict, an expired
+        // epoch, too little fee); only a `Commit` means it happened.
+        const decision = result.Finalized.final_decision;
+        if (decision !== "Commit") {
+            const reason = typeof decision === "object" && decision && "Abort" in decision ? decision.Abort : JSON.stringify(decision);
+            const details = result.Finalized.abort_details ? `: ${result.Finalized.abort_details}` : "";
+            throw new Error(`Transaction ${transactionId} was aborted (${reason})${details}`);
+        }
         const outcome = result.Finalized.execution_result?.finalize.result;
         if (outcome && typeof outcome === "object") {
             if ("Reject" in outcome) {
@@ -2784,3 +3386,21 @@ function describeSignedTx(signed) {
         return "unavailable";
     }
 }
+/**
+ * The one-time spend key of a stealth UTXO substate (its `auth` `Key`, or `KeyAndScript.spend_key`).
+ * A key-path spend of the UTXO is signed with this key, so its badge is in the transaction's auth
+ * scope -- which makes it a valid receiver for a revealed output (tari-ootle#2645) in transactions
+ * this account deliberately doesn't sign with its own key.
+ */
+function utxoSpendKey(substate) {
+    const auth = substate.substate?.Utxo?.output?.auth;
+    const key = auth && "Key" in auth ? auth.Key : auth && "KeyAndScript" in auth ? auth.KeyAndScript.spend_key : undefined;
+    if (typeof key !== "string" || !/^[0-9a-f]{64}$/i.test(key)) {
+        throw new Error("This stealth output has no one-time spend key (it is script-only), so it can't be spent by key.");
+    }
+    return fromHex(key);
+}
+/** A hand-built outputs statement that reveals `amount` to `receiver` and creates no stealth outputs. */
+function revealOnlyOutputsJson(amount, receiver) {
+    return JSON.stringify({ outputs: [], revealed_output: { amount: amount.toString(), receiver: toHex(receiver) }, agg_range_proof: "" });
+}