@chironbuilder/ootle-sdk 0.1.13 → 0.1.15

package/dist/htlcSafety.js

@@ -0,0 +1,275 @@
+// Settlement-safety helpers for HTLCs: the epoch rules, condition-root checks, pre-claim term
+// verification and outcome classification that `OotleAccount`'s HTLC methods (and any swap
+// protocol built on them) rely on. Everything here is pure or wasm-only — no provider, no storage —
+// so every rule is unit-testable on its own (htlcSafety.test.ts).
+import { buildScriptPathWitness, encryptedDataDhKdfAead, unblindOutput } from "@tari-project/ootle-wasm";
+import { htlcConditions } from "./htlc.js";
+import { fromHex, toHex } from "./vault.js";
+// ── epoch rules (must match the engine's AfterEpoch / BeforeEpoch atoms exactly) ──────────────
+/** The refund leaf is `AfterEpoch(refundEpoch)`: admissible when `currentEpoch >= refundEpoch`. */
+export function isHtlcRefundable(currentEpoch, refundEpoch) {
+    return currentEpoch >= refundEpoch;
+}
+/** The claim leaf is `BeforeEpoch(refundEpoch)`: admissible only while `currentEpoch < refundEpoch`. */
+export function isHtlcClaimableByEpoch(currentEpoch, refundEpoch) {
+    return currentEpoch < refundEpoch;
+}
+/** Epochs left in which a claim is still admissible (0 once the claim window has closed). */
+export function epochsUntilRefund(currentEpoch, refundEpoch) {
+    return refundEpoch > currentEpoch ? refundEpoch - currentEpoch : 0n;
+}
+// ── condition roots ────────────────────────────────────────────────────────────────────────────
+/**
+ * The on-chain condition root of a `[claim, refund]` tree — what a `PayTo::Conditions` output
+ * commits to (its `auth.Script`). Computed through the refund leaf, which consumes no witness data,
+ * so no preimage is needed.
+ */
+export function conditionRootOf(conditions) {
+    const refundLeaf = conditions[1];
+    if (!refundLeaf)
+        throw new Error("conditionRootOf: expected the two-leaf [claim, refund] condition tree");
+    const result = JSON.parse(buildScriptPathWitness(JSON.stringify(conditions), JSON.stringify(refundLeaf), new Uint8Array(0)));
+    if (typeof result.condition_root !== "string")
+        throw new Error("conditionRootOf: wasm returned no condition_root");
+    return result.condition_root.toLowerCase();
+}
+/**
+ * Finds the script-path condition root committed by an on-chain UTXO body — the `Script` variant of
+ * its spend authorization. Searched structurally (a `Script` key holding 32 bytes of hex) rather
+ * than by a fixed path, so an indexer-side field rename can't turn "is this our HTLC?" into a
+ * silent pass: a body with no such field returns `null`, which every caller treats as a mismatch.
+ */
+export function findScriptRoot(body, depth = 0) {
+    if (depth > 8 || body === null || typeof body !== "object")
+        return null;
+    for (const [key, value] of Object.entries(body)) {
+        if (key === "Script" && typeof value === "string" && /^[0-9a-f]{64}$/i.test(value))
+            return value.toLowerCase();
+        const nested = findScriptRoot(value, depth + 1);
+        if (nested)
+            return nested;
+    }
+    return null;
+}
+/** Reads the hash lock and refund epoch back out of a `[claim, refund]` tree built by `htlcConditions`. */
+export function describeHtlcConditions(conditions) {
+    const claim = conditions[0];
+    const hash = claim?.find((a) => a.Builtin?.HashLock)?.Builtin?.HashLock?.hash;
+    const before = claim?.find((a) => a.Builtin?.BeforeEpoch !== undefined)?.Builtin?.BeforeEpoch;
+    if (typeof hash !== "string" || typeof before !== "number") {
+        throw new Error("Not an HTLC condition tree: the claim leaf has no HashLock/BeforeEpoch atoms.");
+    }
+    return { hashLockHex: hash.toLowerCase(), refundEpoch: BigInt(before) };
+}
+/**
+ * Every reason the funded HTLC does not match what was agreed — empty means safe to reveal the
+ * preimage. Checks, in order: the output decrypts as ours; its amount; the tree's shape (rebuilt
+ * from `expected` + this account's key and compared byte-for-byte, which pins the claimant, the
+ * refunder, the hash lock and the refund epoch at once); the on-chain root equals the tree's root
+ * (so the tree we'd reveal is the one actually committed); the preimage hashes to the lock; and
+ * enough claim-admissible epochs remain.
+ */
+export function verifyHtlcTerms(facts, expected = {}) {
+    const problems = [];
+    if (facts.value === null)
+        problems.push("The funded output does not decrypt with this account's view key — it isn't addressed to you.");
+    if (facts.value !== null && expected.amount !== undefined && facts.value !== expected.amount) {
+        problems.push(`The funded amount is ${facts.value}, not the agreed ${expected.amount}.`);
+    }
+    if (facts.value !== null && expected.minAmount !== undefined && facts.value < expected.minAmount) {
+        problems.push(`The funded amount ${facts.value} is below the agreed minimum ${expected.minAmount}.`);
+    }
+    let described = null;
+    try {
+        described = describeHtlcConditions(facts.conditions);
+    }
+    catch (e) {
+        problems.push(e instanceof Error ? e.message : String(e));
+    }
+    if (described) {
+        const hashLockHex = (expected.hashLockHex ?? described.hashLockHex).toLowerCase();
+        const refundEpoch = expected.refundEpoch ?? described.refundEpoch;
+        if (expected.hashLockHex !== undefined && expected.hashLockHex.toLowerCase() !== described.hashLockHex) {
+            problems.push("The condition tree's hash lock is not the agreed one.");
+        }
+        if (expected.refundEpoch !== undefined && expected.refundEpoch !== described.refundEpoch) {
+            problems.push(`The condition tree's refund epoch is ${described.refundEpoch}, not the agreed ${expected.refundEpoch}.`);
+        }
+        // Rebuild the tree the way a correct funder would have, and demand an exact match: this pins the
+        // claim leaf to *our* key (nobody else can take the claim path) and, when known, the refund leaf
+        // to the agreed counterparty.
+        const refunder = expected.refunderPublicKeyHex ?? refunderKeyOf(facts.conditions);
+        if (refunder) {
+            try {
+                const rebuilt = htlcConditions({ hashLockHex, refundEpoch, claimantPublicKeyHex: facts.claimantPublicKeyHex, refunderPublicKeyHex: refunder });
+                if (JSON.stringify(rebuilt) !== JSON.stringify(facts.conditions)) {
+                    problems.push("The condition tree is not a standard HTLC paying you on the claim path (claimant key, refunder key, hash lock or epoch differ).");
+                }
+            }
+            catch (e) {
+                problems.push(e instanceof Error ? e.message : String(e));
+            }
+        }
+        if (facts.preimageHashHex !== undefined && facts.preimageHashHex.toLowerCase() !== described.hashLockHex) {
+            problems.push("The preimage does not hash to this HTLC's hash lock.");
+        }
+        const minLeft = expected.minEpochsBeforeRefund ?? 1n;
+        const left = epochsUntilRefund(facts.currentEpoch, described.refundEpoch);
+        if (left < minLeft) {
+            problems.push(left === 0n
+                ? `The claim window has closed (current epoch ${facts.currentEpoch} ≥ refund epoch ${described.refundEpoch}).`
+                : `Only ${left} epoch(s) remain before the refund path opens; at least ${minLeft} required.`);
+        }
+    }
+    let treeRoot = null;
+    try {
+        treeRoot = conditionRootOf(facts.conditions);
+    }
+    catch (e) {
+        problems.push(`The condition tree is malformed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (treeRoot !== null && facts.onChainRoot !== treeRoot) {
+        problems.push(facts.onChainRoot === null
+            ? "The on-chain output is not script-locked (no condition root) — it is not this HTLC."
+            : "The on-chain output commits to a different condition tree than the one you were given.");
+    }
+    return problems;
+}
+/** The refund leaf's public key, read back from a tree built by `htlcConditions`. */
+function refunderKeyOf(conditions) {
+    const refund = conditions[1];
+    const rule = refund?.find((a) => a.AccessRule)?.AccessRule;
+    return rule?.Restricted?.Require?.Require?.NonFungibleAddress?.id?.U256 ?? null;
+}
+export class HtlcVerificationError extends Error {
+    problems;
+    constructor(problems) {
+        super(`Refusing to reveal the preimage — the funded HTLC doesn't match the agreed terms:\n- ${problems.join("\n- ")}`);
+        this.problems = problems;
+        this.name = "HtlcVerificationError";
+    }
+}
+// ── outcome classification ────────────────────────────────────────────────────────────────────
+/**
+ * Whether an error from submitting/polling is a *definitive* rejection (the transaction will never
+ * execute), as opposed to an ambiguous failure (timeout, network error, service worker killed)
+ * after which the transaction may still land. Only a definitive rejection may be treated as
+ * "nothing happened"; everything else must be reconciled, never assumed failed.
+ */
+export function isDefinitiveRejection(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return /was rejected:|accepted the fee but rejected the rest/i.test(msg);
+}
+/**
+ * Thrown (instead of a plain error) when an HTLC transaction was, or may have been, submitted but
+ * its outcome didn't arrive in time. Carries everything the caller needs — including the refund
+ * data — and the journal entry that `OotleAccount.reconcileHtlcs()` resolves later. Callers must
+ * treat this as "pending", never as "failed".
+ */
+export class HtlcUnknownOutcomeError extends Error {
+    journalId;
+    details;
+    constructor(journalId, details, cause) {
+        super(`The HTLC ${details.kind} was submitted but its outcome is not known yet (${cause instanceof Error ? cause.message : String(cause)}). ` +
+            `It is recorded as journal entry ${journalId}; call reconcileHtlcs() to resolve it. Do not retry it as a new operation.`, { cause });
+        this.journalId = journalId;
+        this.details = details;
+        this.name = "HtlcUnknownOutcomeError";
+    }
+}
+// ── output masks ──────────────────────────────────────────────────────────────────────────────
+/** The Ristretto255 group order ℓ = 2^252 + 27742317777372353535851937790883648493. */
+const RISTRETTO_L = (1n << 252n) + 27742317777372353535851937790883648493n;
+function scalarFromLeHex(hex) {
+    if (!/^[0-9a-f]{64}$/i.test(hex))
+        throw new Error(`expected a 32-byte scalar in hex, got ${hex.length} chars`);
+    let v = 0n;
+    for (let i = 62; i >= 0; i -= 2)
+        v = (v << 8n) | BigInt(parseInt(hex.slice(i, i + 2), 16));
+    return v;
+}
+function scalarToLeHex(v) {
+    let out = "";
+    for (let i = 0; i < 32; i++) {
+        out += Number(v & 0xffn).toString(16).padStart(2, "0");
+        v >>= 8n;
+    }
+    return out;
+}
+/**
+ * `(a - b) mod ℓ` for 32-byte little-endian scalars. A transfer's `outputMask` is the *sum* of its
+ * outputs' blinding masks (`aggregated_output_mask`), so when a fund creates the HTLC output plus
+ * this account's own change, the HTLC output's own mask is `aggregate - changeMask` — the change
+ * mask being recoverable because the change is addressed to this account. The result is only ever
+ * trusted after `OotleAccount.htlcFund` proves it reproduces the HTLC commitment (see there).
+ */
+export function subtractScalars(aHex, bHex) {
+    const a = scalarFromLeHex(aHex) % RISTRETTO_L;
+    const b = scalarFromLeHex(bHex) % RISTRETTO_L;
+    return scalarToLeHex((((a - b) % RISTRETTO_L) + RISTRETTO_L) % RISTRETTO_L);
+}
+/**
+ * Decrypts one of this account's *own* outputs straight out of a locally built outputs statement
+ * (before anything is submitted) and returns its value and blinding mask. `outputJson` is the
+ * statement's `outputs[i]` entry; `viewSecret` this account's view secret. Throws if the output
+ * isn't addressed to this view key (AEAD or commitment check fails inside `unblindOutput`).
+ */
+export function decryptOwnStatementOutput(outputJson, viewSecret) {
+    const commitment = findHexField(outputJson, ["commitment"]);
+    const nonce = findHexField(outputJson, ["public_nonce", "sender_public_nonce"]);
+    const encrypted = findHexField(outputJson, ["encrypted_data"], true);
+    if (!commitment || !nonce || !encrypted)
+        throw new Error("decryptOwnStatementOutput: output is missing commitment/public nonce/encrypted data");
+    const key = encryptedDataDhKdfAead(viewSecret, fromHex(nonce));
+    const result = unblindOutput(fromHex(commitment), fromHex(encrypted), key, true);
+    return { value: BigInt(result.value), maskHex: toHex(result.mask), commitment: commitment.toLowerCase() };
+}
+function findHexField(node, keys, anyLength = false, depth = 0) {
+    if (depth > 6 || node === null || typeof node !== "object")
+        return null;
+    for (const [key, value] of Object.entries(node)) {
+        if (keys.includes(key) && typeof value === "string" && /^[0-9a-f]+$/i.test(value) && (anyLength || value.length === 64))
+            return value;
+        const nested = findHexField(value, keys, anyLength, depth + 1);
+        if (nested)
+            return nested;
+    }
+    return null;
+}
+/** The Pedersen commitment of input `index` in a full statement JSON (what a spend of it commits to). */
+export function statementInputCommitment(statementJson, index = 0) {
+    const parsed = JSON.parse(statementJson);
+    const input = parsed.inputs_statement?.inputs?.[index];
+    return findCommitment(input);
+}
+function findCommitment(node, depth = 0) {
+    if (depth > 6 || node === null || typeof node !== "object")
+        return null;
+    for (const [key, value] of Object.entries(node)) {
+        if (key === "commitment" && typeof value === "string" && /^[0-9a-f]{64}$/i.test(value))
+            return value.toLowerCase();
+        const nested = findCommitment(value, depth + 1);
+        if (nested)
+            return nested;
+    }
+    return null;
+}
+// ── statements / hashing ──────────────────────────────────────────────────────────────────────
+/** The commitment of output `index` in a full `StealthTransferStatement` JSON string. Only the
+ * commitment strings are read, so parsing precision on large numeric fields doesn't matter here. */
+export function statementOutputCommitment(statementJson, index = 0) {
+    const parsed = JSON.parse(statementJson);
+    const commitment = parsed.outputs_statement?.outputs?.[index]?.output?.commitment;
+    if (typeof commitment !== "string" || commitment.length === 0) {
+        throw new Error(`statementOutputCommitment: no output commitment at index ${index}`);
+    }
+    return commitment;
+}
+export async function sha256Hex(data) {
+    return toHex(new Uint8Array(await crypto.subtle.digest("SHA-256", data)));
+}
+/** A fresh, random operation id (journal ids and reservation holders). */
+export function newOperationId(prefix) {
+    const bytes = crypto.getRandomValues(new Uint8Array(12));
+    return `${prefix}-${toHex(bytes)}`;
+}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export type { TransactionExecuteOpts, WalletAccountApi } from "./accountApi.js";
 export { ACCOUNT_TEMPLATE_ADDRESS, componentAddressFromWalletAddress, deriveAccountComponentAddress, deriveComponentAddress, } from "./componentAddress.js";
-export type { BurnClaimProofContents, KernelMerkleProof, L1BurnProofParts } from "./burnClaim.js";
-export { assembleBurnClaimProof, parseConsoleWalletBurnProof } from "./burnClaim.js";
+export type { BurnClaimProofContents, BurnOutputProof, L1BurnProofParts, L1MmrInclusionProof } from "./burnClaim.js";
+export { assembleBurnClaimProof, claimProofFromL1, decodeBurnOutputFeatures, parseConsoleWalletBurnProof } from "./burnClaim.js";
 export type { ConfidentialSumResult, ScannedStealthOutput } from "./confidential.js";
 export { scanTransactionsForOwnedOutputs, sumConfidentialCommitments } from "./confidential.js";
 export type { DerivedAccountKeys } from "./derivation.js";
@@ -9,15 +9,17 @@ export { deriveAccountKeys } from "./derivation.js";
 export { DomainSeparatedHasher, KEY_MANAGER_DOMAIN, KEY_MANAGER_DOMAIN_VERSION, keyManagerDomainHasher } from "./domainHash.js";
 export type { HtlcConditionsParams } from "./htlc.js";
 export { accessRuleRequiringPublicKey, htlcConditions } from "./htlc.js";
+export type { HtlcExpectations, HtlcFacts } from "./htlcSafety.js";
+export { HtlcUnknownOutcomeError, HtlcVerificationError, conditionRootOf, describeHtlcConditions, epochsUntilRefund, findScriptRoot, isDefinitiveRejection, isHtlcClaimableByEpoch, isHtlcRefundable, verifyHtlcTerms, } from "./htlcSafety.js";
 export type { NetworkName } from "./ootleNetwork.js";
 export { toOotleNetwork } from "./ootleNetwork.js";
 export { OWNERSHIP_PROOF_CHALLENGE_MAX_LENGTH, buildOwnershipProofMessage, buildWalletOwnershipMessage } from "./ownershipProof.js";
 export type { EncryptedVault } from "./vault.js";
 export { decryptVault, encryptVault, fromHex, toHex } from "./vault.js";
 export { withTimeout } from "./timeout.js";
-export type { KeyValueStore, PendingShield, ShieldedOutputRecord } from "./storage.js";
-export { addPendingShield, addShieldedOutput, configureOotleStorage, getKnownVersions, getPrivatePaymentScanCursor, listPendingShields, listShieldedOutputs, localAccountId, markShieldedOutputSpent, removePendingShield, serialized, setKnownVersions, setPrivatePaymentScanCursor, wipeOotleState, } from "./storage.js";
+export type { CommitmentReservation, HtlcJournalEntry, HtlcJournalStatus, KeyValueStore, PendingShield, ShieldedOutputRecord } from "./storage.js";
+export { addPendingShield, addShieldedOutput, configureOotleStorage, getKnownVersions, getPrivatePaymentScanCursor, listPendingShields, listShieldedOutputs, localAccountId, markShieldedOutputSpent, removePendingShield, serialized, setKnownVersions, setPrivatePaymentScanCursor, wipeOotleState, CommitmentReservedError, RESERVATION_TTL_MS, listHtlcJournal, } from "./storage.js";
 export { chromeStorageAdapter, inMemoryAdapter, localStorageAdapter } from "./adapters.js";
-export type { FeeType, PrivateBalance, TokenBalance } from "./wallet.js";
+export type { FeeType, HtlcClaimOptions, HtlcFundOptions, HtlcFundResult, HtlcSpendResult, PrivateBalance, TokenBalance } from "./wallet.js";
 export { OotleAccount, assertValidMinimumValuePromise, buildHtlcSpendStatement, extractMissingSubstateAddress, extractStaleLockVersion, forgetKnownVersions, pollTransactionResult, recoverPendingShields, resetKnownVersions, resolveInputsWithRetry, resolveSendPrivatelyPlan, resolveUnshieldPlan, selectPrivateFeeUtxo, selectShieldedUtxosForAmount, selectUnspentShieldedOutputs, substateExists, summarizePrivateHoldings, synthesizeShieldedOnlyBalances, } from "./wallet.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -1,15 +1,16 @@
 // Public surface. Import from the package root ("@chironbuilder/ootle-sdk") rather than reaching
 // into individual files -- the module layout underneath is free to change; this file is not.
 export { ACCOUNT_TEMPLATE_ADDRESS, componentAddressFromWalletAddress, deriveAccountComponentAddress, deriveComponentAddress, } from "./componentAddress.js";
-export { assembleBurnClaimProof, parseConsoleWalletBurnProof } from "./burnClaim.js";
+export { assembleBurnClaimProof, claimProofFromL1, decodeBurnOutputFeatures, parseConsoleWalletBurnProof } from "./burnClaim.js";
 export { scanTransactionsForOwnedOutputs, sumConfidentialCommitments } from "./confidential.js";
 export { deriveAccountKeys } from "./derivation.js";
 export { DomainSeparatedHasher, KEY_MANAGER_DOMAIN, KEY_MANAGER_DOMAIN_VERSION, keyManagerDomainHasher } from "./domainHash.js";
 export { accessRuleRequiringPublicKey, htlcConditions } from "./htlc.js";
+export { HtlcUnknownOutcomeError, HtlcVerificationError, conditionRootOf, describeHtlcConditions, epochsUntilRefund, findScriptRoot, isDefinitiveRejection, isHtlcClaimableByEpoch, isHtlcRefundable, verifyHtlcTerms, } from "./htlcSafety.js";
 export { toOotleNetwork } from "./ootleNetwork.js";
 export { OWNERSHIP_PROOF_CHALLENGE_MAX_LENGTH, buildOwnershipProofMessage, buildWalletOwnershipMessage } from "./ownershipProof.js";
 export { decryptVault, encryptVault, fromHex, toHex } from "./vault.js";
 export { withTimeout } from "./timeout.js";
-export { addPendingShield, addShieldedOutput, configureOotleStorage, getKnownVersions, getPrivatePaymentScanCursor, listPendingShields, listShieldedOutputs, localAccountId, markShieldedOutputSpent, removePendingShield, serialized, setKnownVersions, setPrivatePaymentScanCursor, wipeOotleState, } from "./storage.js";
+export { addPendingShield, addShieldedOutput, configureOotleStorage, getKnownVersions, getPrivatePaymentScanCursor, listPendingShields, listShieldedOutputs, localAccountId, markShieldedOutputSpent, removePendingShield, serialized, setKnownVersions, setPrivatePaymentScanCursor, wipeOotleState, CommitmentReservedError, RESERVATION_TTL_MS, listHtlcJournal, } from "./storage.js";
 export { chromeStorageAdapter, inMemoryAdapter, localStorageAdapter } from "./adapters.js";
 export { OotleAccount, assertValidMinimumValuePromise, buildHtlcSpendStatement, extractMissingSubstateAddress, extractStaleLockVersion, forgetKnownVersions, pollTransactionResult, recoverPendingShields, resetKnownVersions, resolveInputsWithRetry, resolveSendPrivatelyPlan, resolveUnshieldPlan, selectPrivateFeeUtxo, selectShieldedUtxosForAmount, selectUnspentShieldedOutputs, substateExists, summarizePrivateHoldings, synthesizeShieldedOnlyBalances, } from "./wallet.js";

package/dist/storage.d.ts

@@ -37,6 +37,72 @@ export interface PendingShield {
     /** This account's own memo for the operation, if any. */
     memo?: string;
 }
+/**
+ * Lifecycle of one HTLC operation, persisted *before* anything is submitted so a crash, a killed
+ * service worker or a confirmation timeout can never strand the only copy of what's needed to
+ * finish it (see `HtlcJournalEntry`):
+ *
+ * - `prepared`   the sealed envelope and every recovery field are stored; not yet submitted
+ * - `claim_armed` (claims only) the funded output passed every pre-claim check and a dry run; the
+ *                next step reveals the preimage on-chain
+ * - `submitted`  the network accepted the envelope for processing; outcome not yet known
+ * - `unknown`    submitted (or possibly submitted) but no final result arrived in time — resolved by
+ *                `OotleAccount.reconcileHtlcs()`, never assumed to have failed
+ * - `confirmed`  finalized and accepted; local bookkeeping done
+ * - `failed`     definitively rejected; nothing happened on-chain beyond (possibly) the fee
+ */
+export type HtlcJournalStatus = "prepared" | "claim_armed" | "submitted" | "unknown" | "confirmed" | "failed";
+export interface HtlcJournalEntry {
+    /** Local id, stable across retries of the same operation. */
+    id: string;
+    accountId: string;
+    kind: "fund" | "claim" | "refund";
+    status: HtlcJournalStatus;
+    resourceAddress: string;
+    /** Raw units. For a fund: the HTLC amount. For a claim/refund: the amount moving to this account. */
+    amount: string;
+    /** The exact two-leaf `[claim, refund]` condition tree — needed by both sides, never recomputable
+     * by the counterparty from on-chain data alone (only its root is committed). */
+    conditions: object[];
+    hashLockHex: string;
+    refundEpoch: string;
+    /** The HTLC output's commitment (hex): created by a fund, spent by a claim/refund. */
+    htlcCommitment?: string;
+    /** Fund only: the HTLC output's blinding mask. The funder can't decrypt an output addressed to the
+     * claimant, so without this a refund is impossible — which is why it is written here before submit. */
+    outputMask?: string;
+    /** This account's own new stealth output from the operation (a fund's change, a claim/refund's
+     * received output), recorded in the shielded ledger once the operation confirms. */
+    ownCommitment?: string;
+    ownAmount?: string;
+    /** Stealth inputs this operation spends (fund-from-stealth), marked spent once it confirms. */
+    spentCommitments?: string[];
+    /** Private-fee bookkeeping, applied once the operation confirms. */
+    privateFee?: {
+        feeResourceAddress: string;
+        spentCommitment: string;
+        changeCommitment: string;
+        changeAmount: string;
+    };
+    /** The sealed transaction exactly as submitted — lets reconciliation resubmit the identical
+     * transaction (same id, so it can never execute twice) if the first submit never reached the
+     * network. For a claim this contains the preimage, so it is only ever resubmitted, never shown. */
+    envelope: string;
+    transactionId?: string;
+    error?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+/** A stealth commitment held by an in-flight operation, so a concurrent one can't select it too. */
+export interface CommitmentReservation {
+    accountId: string;
+    commitment: string;
+    /** Who holds it — an operation id; the same holder may re-reserve idempotently. */
+    holder: string;
+    /** Epoch ms after which the reservation lapses on its own (a crashed operation can never lock a
+     * UTXO forever). */
+    expiresAt: number;
+}
 export declare function localAccountId(index: number): string;
 /** Runs a whole read-modify-write cycle to completion before the next one starts, so two
  * concurrent callers (two tabs, a page request racing a popup request) can't interleave their
@@ -48,6 +114,8 @@ export declare function localAccountId(index: number): string;
  * provide. */
 export declare function serialized<T>(fn: () => Promise<T>): Promise<T>;
 export declare function listShieldedOutputs(accountId: string): Promise<ShieldedOutputRecord[]>;
+/** Idempotent: a commitment already recorded for the same account is left as it is, so a
+ * reconciliation that re-applies a finished operation's bookkeeping can never double-count it. */
 export declare function addShieldedOutput(record: ShieldedOutputRecord): Promise<void>;
 export declare function markShieldedOutputSpent(accountId: string, commitment: string): Promise<void>;
 export declare function listPendingShields(): Promise<PendingShield[]>;
@@ -59,6 +127,30 @@ export declare function setPrivatePaymentScanCursor(accountId: string, transacti
  * this exists at all. */
 export declare function getKnownVersions(): Promise<Record<string, number>>;
 export declare function setKnownVersions(known: Record<string, number>): Promise<void>;
+export declare function listHtlcJournal(accountId?: string): Promise<HtlcJournalEntry[]>;
+export declare function getHtlcJournalEntry(id: string): Promise<HtlcJournalEntry | undefined>;
+/** Inserts or replaces (by id) — idempotent, so retrying the same write is always safe. */
+export declare function putHtlcJournalEntry(entry: HtlcJournalEntry): Promise<void>;
+/** Applies `patch` to an existing entry and bumps `updatedAt`. A missing id is a no-op. */
+export declare function updateHtlcJournalEntry(id: string, patch: Partial<HtlcJournalEntry>): Promise<HtlcJournalEntry | undefined>;
+/** Default lifetime of a reservation: long enough for any single operation (prepare + dry run +
+ * submit + confirmation), short enough that a crashed one frees its UTXOs within minutes. */
+export declare const RESERVATION_TTL_MS: number;
+/** Commitments currently reserved for `accountId` by anyone other than `exceptHolder`. */
+export declare function listReservedCommitments(accountId: string, exceptHolder?: string, now?: number): Promise<Set<string>>;
+/**
+ * Atomically reserves every commitment in `commitments` for `holder`, or none of them: if any is
+ * already held (unexpired) by a different holder, throws `CommitmentReservedError` naming them and
+ * writes nothing. Re-reserving one's own commitments just extends the lease. Expired leases are
+ * swept on every call.
+ */
+export declare function reserveCommitments(accountId: string, commitments: string[], holder: string, ttlMs?: number): Promise<void>;
+/** Releases every reservation `holder` holds (all accounts). Safe to call more than once. */
+export declare function releaseReservations(holder: string): Promise<void>;
+export declare class CommitmentReservedError extends Error {
+    readonly commitments: string[];
+    constructor(commitments: string[]);
+}
 /** Clears every key this module owns -- call this from a host's own "erase wallet" flow. Does not
  * touch anything else the host's `KeyValueStore` might hold (address books, settings, ...); this
  * SDK never wrote those keys, so it isn't this function's place to remove them. */

package/dist/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC5C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAID;0EAC0E;AAC1E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAEhE;AAcD,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,KAAK,EAAE,OAAO,CAAC;IACf,2FAA2F;IAC3F,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAiBD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AA0BD;;;;;;;cAOc;AACd,wBAAgB,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAgB9D;AAED,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAE5F;AAED,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAInF;AAED,wBAAsB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CASlG;AAED,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAEnE;AAED,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAM5E;AAED,wBAAsB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK9E;AAED,wBAAsB,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAE3F;AAED,wBAAsB,2BAA2B,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKzG;AAED;yBACyB;AACzB,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAExE;AAED,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAInF;AAED;;mFAEmF;AACnF,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAIpD"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}

package/dist/storage.js

@@ -28,6 +28,8 @@ const DEFAULTS = {
     pendingShields: [],
     privatePaymentScanCursors: {},
     knownVersions: {},
+    htlcJournal: [],
+    reservations: [],
 };
 export function localAccountId(index) {
     return `local:${index}`;
@@ -79,9 +81,14 @@ export function serialized(fn) {
 export async function listShieldedOutputs(accountId) {
     return (await read()).shieldedOutputs.filter((r) => r.accountId === accountId);
 }
+/** Idempotent: a commitment already recorded for the same account is left as it is, so a
+ * reconciliation that re-applies a finished operation's bookkeeping can never double-count it. */
 export async function addShieldedOutput(record) {
     await serialized(async () => {
-        write({ shieldedOutputs: [...(await read()).shieldedOutputs, record] });
+        const existing = (await read()).shieldedOutputs;
+        if (existing.some((r) => r.accountId === record.accountId && r.commitment === record.commitment))
+            return;
+        await write({ shieldedOutputs: [...existing, record] });
     });
 }
 export async function markShieldedOutputSpent(accountId, commitment) {
@@ -128,6 +135,83 @@ export async function setKnownVersions(known) {
         await write({ knownVersions: known });
     });
 }
+// ── HTLC journal ─────────────────────────────────────────────────────────────────────────────
+export async function listHtlcJournal(accountId) {
+    const all = (await read()).htlcJournal;
+    return accountId ? all.filter((e) => e.accountId === accountId) : all;
+}
+export async function getHtlcJournalEntry(id) {
+    return (await read()).htlcJournal.find((e) => e.id === id);
+}
+/** Inserts or replaces (by id) — idempotent, so retrying the same write is always safe. */
+export async function putHtlcJournalEntry(entry) {
+    await serialized(async () => {
+        const state = await read();
+        await write({ htlcJournal: [...state.htlcJournal.filter((e) => e.id !== entry.id), entry] });
+    });
+}
+/** Applies `patch` to an existing entry and bumps `updatedAt`. A missing id is a no-op. */
+export async function updateHtlcJournalEntry(id, patch) {
+    return serialized(async () => {
+        const state = await read();
+        const current = state.htlcJournal.find((e) => e.id === id);
+        if (!current)
+            return undefined;
+        const next = { ...current, ...patch, id, updatedAt: Date.now() };
+        await write({ htlcJournal: state.htlcJournal.map((e) => (e.id === id ? next : e)) });
+        return next;
+    });
+}
+// ── commitment reservations ──────────────────────────────────────────────────────────────────
+/** Default lifetime of a reservation: long enough for any single operation (prepare + dry run +
+ * submit + confirmation), short enough that a crashed one frees its UTXOs within minutes. */
+export const RESERVATION_TTL_MS = 10 * 60_000;
+/** Commitments currently reserved for `accountId` by anyone other than `exceptHolder`. */
+export async function listReservedCommitments(accountId, exceptHolder, now = Date.now()) {
+    return new Set((await read()).reservations
+        .filter((r) => r.accountId === accountId && r.expiresAt > now && r.holder !== exceptHolder)
+        .map((r) => r.commitment));
+}
+/**
+ * Atomically reserves every commitment in `commitments` for `holder`, or none of them: if any is
+ * already held (unexpired) by a different holder, throws `CommitmentReservedError` naming them and
+ * writes nothing. Re-reserving one's own commitments just extends the lease. Expired leases are
+ * swept on every call.
+ */
+export async function reserveCommitments(accountId, commitments, holder, ttlMs = RESERVATION_TTL_MS) {
+    if (commitments.length === 0)
+        return;
+    await serialized(async () => {
+        const now = Date.now();
+        const state = await read();
+        const live = state.reservations.filter((r) => r.expiresAt > now);
+        const taken = commitments.filter((c) => live.some((r) => r.accountId === accountId && r.commitment === c && r.holder !== holder));
+        if (taken.length > 0)
+            throw new CommitmentReservedError(taken);
+        const wanted = new Set(commitments);
+        const kept = live.filter((r) => !(r.accountId === accountId && wanted.has(r.commitment)));
+        const expiresAt = now + ttlMs;
+        await write({ reservations: [...kept, ...commitments.map((commitment) => ({ accountId, commitment, holder, expiresAt }))] });
+    });
+}
+/** Releases every reservation `holder` holds (all accounts). Safe to call more than once. */
+export async function releaseReservations(holder) {
+    await serialized(async () => {
+        const now = Date.now();
+        const state = await read();
+        await write({ reservations: state.reservations.filter((r) => r.holder !== holder && r.expiresAt > now) });
+    });
+}
+export class CommitmentReservedError extends Error {
+    commitments;
+    constructor(commitments) {
+        super(`${commitments.length === 1 ? "A private output this operation needs is" : "Private outputs this operation needs are"} ` +
+            `already in use by another operation in progress (${commitments.map((c) => c.slice(0, 12)).join(", ")}). ` +
+            "Wait for it to finish, then try again.");
+        this.commitments = commitments;
+        this.name = "CommitmentReservedError";
+    }
+}
 /** Clears every key this module owns -- call this from a host's own "erase wallet" flow. Does not
  * touch anything else the host's `KeyValueStore` might hold (address books, settings, ...); this
  * SDK never wrote those keys, so it isn't this function's place to remove them. */