@chironbuilder/ootle-sdk 0.1.14 → 0.1.16

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";
@@ -171,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();
     }
@@ -781,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
@@ -924,9 +933,15 @@ export class OotleAccount {
             // 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)
+            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) {
@@ -1014,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 }))
@@ -1082,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);
@@ -1237,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);
@@ -1551,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);
@@ -1666,7 +1683,7 @@ export class OotleAccount {
             // 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).withBuilder((bb) => bb.addInput({ substate_id: resourceAddress, version: null }));
+                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));
@@ -2165,7 +2182,7 @@ export class OotleAccount {
             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)
+            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) {
@@ -2275,9 +2292,163 @@ 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. With no
+     * change to pay the fee from (unshielding the whole private balance), the fee comes out of the
+     * unshielded amount instead, so the account receives `amount` less the fee.
+     *
+     * 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 private change first. An account that doesn't exist has nothing
+            // else to pay with, so whatever the change can't cover (all of it, when unshielding the whole
+            // balance) comes out of the unshielded amount: the account is created with `amount - shortfall`.
+            const fromChange = fee < remainder ? fee : remainder;
+            const shortfall = fee - fromChange;
+            const change = remainder - fromChange;
+            if (fee <= 0n || shortfall >= amount) {
+                throw new Error(`unshield: ${amount + remainder} is not enough to cover the ${fee} fee to create the account`);
+            }
+            const revealed = amount + fromChange;
+            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 };
+        };
+        // Any fee the balance can pay works as the dry run's probe; it only feeds the metered cost.
+        const payable = remainder + amount - 1n;
+        const probe = maxFee < payable ? maxFee : payable;
+        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);
@@ -2292,6 +2463,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.
@@ -2301,7 +2473,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);
@@ -2322,7 +2494,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();
@@ -2332,30 +2504,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" },
@@ -2370,7 +2522,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;
@@ -2383,7 +2535,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;
     }
     /**
@@ -2648,7 +2800,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).
@@ -3091,6 +3243,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) {
@@ -3233,3 +3393,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: "" });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chironbuilder/ootle-sdk",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Shared TypeScript client for Tari Ootle (L2): account derivation, balances, transactions, HTLCs, and stealth/confidential transfers — the account core behind Sapient and the Tari L1 web wallet's Ootle support.",
   "type": "module",
   "license": "MIT",
@@ -44,12 +44,16 @@
     "@tari-project/ootle": "file:./vendor/ootle-patched",
     "@tari-project/ootle-indexer": "^0.3.0",
     "@tari-project/ootle-secret-key-wallet": "^0.3.0",
-    "@tari-project/ootle-ts-bindings": "^1.49.1",
+    "@tari-project/ootle-ts-bindings": "^1.55.0",
     "@tari-project/ootle-wasm": "file:./vendor/ootle-wasm-patched"
   },
   "devDependencies": {
     "@types/chrome": "^0.0.280",
     "typescript": "^5.6.0",
     "vitest": "^4.1.0"
+  },
+  "overrides": {
+    "@tari-project/ootle-wasm": "$@tari-project/ootle-wasm",
+    "@tari-project/ootle": "$@tari-project/ootle"
   }
 }

package/vendor/ootle-patched/dist/index.d.ts

@@ -17,6 +17,7 @@ import { IndexerGetTransactionResultResponse } from '@tari-project/ootle-ts-bind
 import { IndexerSubmitTransactionRequest } from '@tari-project/ootle-ts-bindings';
 import { IndexerSubmitTransactionResponse } from '@tari-project/ootle-ts-bindings';
 import { IndexerTransactionFinalizedResult } from '@tari-project/ootle-ts-bindings';
+import { InputDeclaration } from '@tari-project/ootle-ts-bindings';
 import { Instruction } from '@tari-project/ootle-ts-bindings';
 import { InstructionArg } from '@tari-project/ootle-ts-bindings';
 import { ListRecentTransactionsRequest } from '@tari-project/ootle-ts-bindings';
@@ -517,7 +518,7 @@ export declare function fromHexStr(hex: string): Uint8Array;
  * @returns A complete transfer statement.
  * @throws {InvalidArgumentError} if `specs` is empty.
  */
-export declare function generateOutputsStatement(crypto: StealthCryptoProvider, specs: Output[], revealed: bigint): Promise<StealthTransferStatement>;
+export declare function generateOutputsStatement(crypto: StealthCryptoProvider, specs: Output[], revealed: bigint, revealedReceiver?: Uint8Array): Promise<StealthTransferStatement>;
 
 /**
  * Generate a fresh seal keypair (a thin wrapper over the WASM `generateKeypair`).
@@ -1195,10 +1196,13 @@ export declare interface StealthCryptoProvider {
      *
      * @param specs - The outputs to create (incl. change).
      * @param revealedOutputAmount - The un-confidential (revealed) µTari output amount.
+     * @param revealedReceiver - The 32-byte public key allowed to take the revealed output
+     *   (tari-ootle#2645: the engine requires its badge in the transaction's auth scope). Required
+     *   when `revealedOutputAmount > 0`, ignored otherwise.
      * @returns The WASM-produced {@link StealthOutputsStatement} and the aggregated
      *   `outputMask` for the balance proof.
      */
-    generateOutputsStatement(specs: Output[], revealedOutputAmount: bigint): Promise<{
+    generateOutputsStatement(specs: Output[], revealedOutputAmount: bigint, revealedReceiver?: Uint8Array): Promise<{
         statement: StealthOutputsStatement;
         outputMask: Mask;
     }>;
@@ -1363,11 +1367,23 @@ export declare class StealthTransfer {
     /** Guards against a second {@link prepare} re-emitting instructions into the same builder. */
     private prepared;
     /**
-     * Set by {@link toRevealedOutputAsBucket}; when non-null, {@link emitInstructions} leaves the
-     * revealed-change bucket on the workspace under this name instead of auto-depositing it back
-     * to the revealed source account.
+     * When set, revealed change is captured as a bucket on the workspace under this name
+     * instead of being auto-deposited back to `revealedInput.source` — see
+     * {@link toRevealedOutputAsBucket}.
      */
     private revealedOutputBucketVar;
+    /**
+     * Extra instructions appended after the native `StealthTransfer` instruction (and its
+     * change-bucket handling), in the same transaction — see {@link andThen}. Lets a caller
+     * chain e.g. a custom contract call that consumes the bucket saved by
+     * {@link toRevealedOutputAsBucket}, all signed together by the authorizer in one
+     * transaction instead of needing a separate one.
+     */
+    private followUpInstructions;
+    /**
+     * The public key allowed to take the revealed output — see {@link withRevealedReceiver}.
+     */
+    private revealedReceiver;
     /**
      * @param provider - Read-only chain access (used by {@link prepare} to resolve inputs).
      * @param resourceAddress - The resource being transferred.
@@ -1394,32 +1410,40 @@ export declare class StealthTransfer {
      */
     toRevealedOutput(amount: bigint): this;
     /**
-     * Like {@link toRevealedOutput}, but leaves the revealed-change bucket on the workspace under
-     * `workspaceVarName` instead of auto-depositing it back to the revealed source account. Pairs
-     * with {@link andThen} so a caller can route Stealth-typed funds into its own follow-up
-     * instructions in the same signed transaction — a plain `CallMethod withdraw` on a Stealth
-     * vault is not a standalone-valid instruction; moving Stealth funds anywhere always requires
-     * the native `StealthTransfer` instruction this builder already emits.
+     * Like {@link toRevealedOutput}, but instead of auto-depositing the change back into
+     * `revealedInput.source`, the `StealthTransfer` instruction's bucket output is left on the
+     * workspace under `workspaceVarName` for {@link andThen}'s instructions (or a caller-supplied
+     * `withBuilder` continuation) to consume directly — e.g. passing it straight into a custom
+     * contract call in the same transaction, rather than requiring a second transaction that
+     * withdraws it back out again (which a plain `CallMethod withdraw` on a Stealth-typed vault
+     * cannot do standalone — see this class's own `emitInstructions` doc comment: the account
+     * template's `withdraw` only produces a valid bucket when paired with the native
+     * `StealthTransfer` instruction in the same transaction).
      *
-     * Mutually exclusive with {@link toRevealedOutput} in the same builder — call one or the
-     * other, not both, since they disagree on where the change bucket ends up.
+     * A real `toStealthOutput` is still required elsewhere on this builder (`validate()` enforces
+     * it): the bundled `ootle-wasm@0.37.0` signer cannot parse a statement with zero stealth
+     * outputs at all — confirmed live, `signTransaction`'s own WASM call throws the generic "did
+     * not match any variant of untagged enum TransactionInput" error regardless of how
+     * `balance_proof` is represented. A small dust self-output (as `OotleAccount.
+     * withdrawStealthAndExecute` in tari-wallet-extension does) satisfies this cheaply.
      *
-     * @throws {InvalidArgumentError} if `amount` is not `> 0`, or a different workspace name was
-     *   already set by an earlier call.
+     * @throws {InvalidArgumentError} if `amount` is not `> 0`.
      */
     toRevealedOutputAsBucket(amount: bigint, workspaceVarName: string): this;
     /**
-     * Append raw instructions to run in the same signed transaction, after the native
-     * `StealthTransfer` instruction (and the revealed-change bucket save from
-     * {@link toRevealedOutputAsBucket}, if any) — typically used to consume that bucket in a
-     * custom contract call.
+     * Name the public key allowed to take the revealed output (tari-ootle#2645). The engine
+     * requires that key's badge in the transaction's auth scope before it creates the revealed
+     * bucket, so it must be a key that signs the transaction — normally the account key, which
+     * {@link WalletStealthAuthorizer} signs with by default. Required whenever the transfer has a
+     * revealed output ({@link toRevealedOutput} / {@link toRevealedOutputAsBucket}).
      *
-     * Workspace variable ids are a single flat counter across the whole transaction:
-     * `StealthTransfer` claims id `0` (and `1`, when there's a revealed input) internally via its
-     * own `saveVar` calls before these run, so instructions referencing workspace variables by
-     * **name** (`{ Workspace: "name" }`) resolve correctly through the builder's own name → id
-     * map — but any instruction constructed with a raw numeric `WorkspaceOffsetId` by hand must
-     * account for those already-claimed ids itself.
+     * @throws {InvalidArgumentError} if `publicKey` is not 32 bytes.
+     */
+    withRevealedReceiver(publicKey: Uint8Array): this;
+    /**
+     * Append `instructions` after the native `StealthTransfer` instruction (and its bucket
+     * handling), so they run in the same signed transaction — typically consuming the bucket
+     * {@link toRevealedOutputAsBucket} saved to the workspace. Repeatable; each call appends.
      */
     andThen(instructions: Instruction[]): this;
     /**
@@ -1840,8 +1864,13 @@ export declare class TransactionBuilder {
      * Note this REPLACES any fee instructions already set, as it always has.
      */
     withFeeInstructionsBuilder(builder: (b: TransactionBuilder) => TransactionBuilder): this;
-    addInput(input: SubstateRequirement): this;
-    withInputs(inputs: SubstateRequirement[]): this;
+    /**
+     * Declare a transaction input. Since tari-ootle#2640 every input declares read or write
+     * intent; a plain {@link SubstateRequirement} (no `is_write`) is declared a **write**, the
+     * engine's own default — over-declaring only locks more, under-declaring aborts execution.
+     */
+    addInput(input: SubstateRequirement | InputDeclaration): this;
+    withInputs(inputs: (SubstateRequirement | InputDeclaration)[]): this;
     /** @throws {InvalidArgumentError} if `minEpoch` is not a non-negative integer. */
     withMinEpoch(minEpoch: number): this;
     /**
@@ -2076,7 +2105,7 @@ export declare class WasmStealthCrypto implements StealthCryptoProvider {
      */
     private readonly network;
     constructor(network?: Network);
-    generateOutputsStatement(specs: Output[], revealedOutputAmount: bigint): Promise<{
+    generateOutputsStatement(specs: Output[], revealedOutputAmount: bigint, revealedReceiver?: Uint8Array): Promise<{
         statement: StealthOutputsStatement;
         outputMask: Mask;
     }>;