@chironbuilder/ootle-sdk 0.1.13 → 0.1.14

package/README.md

@@ -81,13 +81,57 @@ The claimed funds arrive as a stealth output owned by this account and are recor
 balance. Validators accept a burn only once its L1 block is well confirmed, so an early claim is
 rejected and can be retried.
 
+### HTLCs and atomic swaps
+
+`htlcFund` / `htlcClaim` / `htlcRefund` are built for settlement safety, not just for constructing
+the transactions:
+
+```ts
+// Lock 5,000 units of a stealth-created asset from exact private outputs. The fee stays in its own
+// native-TARI lane (here: private), the asset stays in the main lane, excess comes back as change.
+const fund = await account.htlcFund(asset, 5_000n, claimantAddress, hashLockHex, refundEpoch, 50_000n,
+  { kind: "private", feeResourceAddress: TARI }, { source: { kind: "stealth", commitments: [myUtxo] } });
+// fund.conditions → send to the claimant. fund.outputMask is also journaled (fund.journalId).
+
+// Claimant: nothing is revealed unless the funded output matches the agreed terms.
+const check = await account.verifyHtlc(asset, fund.ownCommitment, fund.conditions, { amount: 5_000n, minEpochsBeforeRefund: 3n });
+await account.htlcClaim(asset, fund.ownCommitment, fund.conditions, preimageHex, 50_000n, feeType,
+  { expected: { amount: 5_000n, refunderPublicKeyHex, minEpochsBeforeRefund: 3n } });
+
+// Funder, once currentEpoch >= refundEpoch:
+await account.refundFromJournal(fund.journalId);
+```
+
+- **Two lanes.** The fee (native TARI, public or a private UTXO) never shares a UTXO with the HTLC
+  value. `source: { kind: "stealth" }` spends this account's own stealth outputs of the resource,
+  so no public balance of it is needed.
+- **Dry run first.** Every fund/claim/refund dry-runs the exact transaction before the real submit
+  (`preflight: false` to skip — a claim's dry run sends the preimage to the indexer's dry-run
+  endpoint).
+- **Verified before the preimage leaves the device.** `htlcClaim` (and `verifyHtlc`) checks the
+  amount, that the claim leaf is your key and the refund leaf the agreed counterparty's, that the
+  on-chain condition root equals the tree's root, that the preimage matches the hash lock, and that
+  enough claim epochs remain; it throws `HtlcVerificationError` otherwise.
+- **Durable journal.** The sealed transaction, the condition tree and the HTLC output's mask (the
+  only thing that makes a refund possible) are persisted *before* submission. An ambiguous outcome
+  throws `HtlcUnknownOutcomeError` — "pending", never "failed" — and `reconcileHtlcs()` (call at
+  startup) resolves it by resubmitting the identical transaction and applying its bookkeeping.
+  `listHtlcs()` shows every operation and its state.
+- **Exact inputs are reserved** for the duration of an operation (and while its outcome is
+  unknown), so a concurrent send/unshield/fee selection can't pick them.
+- **Epoch rules match the engine:** the refund leaf is `AfterEpoch` (open when
+  `currentEpoch >= refundEpoch`), the claim leaf `BeforeEpoch` — see `isHtlcRefundable` /
+  `isHtlcClaimableByEpoch`.
+- Claimed and refunded outputs are recorded in the shielded ledger, so they're spendable at once.
+
 ## What's in here, and what isn't
 
 - **Account core** (`wallet.ts`): `OotleAccount`, balance/plan-resolution helpers, the transaction
   auto-resolve retry loop.
 - **Crypto/derivation**: `derivation.ts`, `domainHash.ts`, `componentAddress.ts`, `vault.ts`,
   `ownershipProof.ts`, `confidential.ts`.
-- **HTLC**: `htlc.ts`.
+- **HTLC**: `htlc.ts` (condition trees), `htlcSafety.ts` (epoch rules, pre-claim verification,
+  per-output masks, outcome classification) + the journaled `OotleAccount` HTLC methods.
 - **L1 burn claims**: `burnClaim.ts` (proof assembly) + `OotleAccount.claimBurn`.
 - **Storage abstraction**: `storage.ts` + `adapters.ts`.
 - **Not included**: UI, an approval/permission model for dApp connections, address books, daemon

package/dist/htlcSafety.d.ts

@@ -0,0 +1,123 @@
+/** The refund leaf is `AfterEpoch(refundEpoch)`: admissible when `currentEpoch >= refundEpoch`. */
+export declare function isHtlcRefundable(currentEpoch: bigint, refundEpoch: bigint): boolean;
+/** The claim leaf is `BeforeEpoch(refundEpoch)`: admissible only while `currentEpoch < refundEpoch`. */
+export declare function isHtlcClaimableByEpoch(currentEpoch: bigint, refundEpoch: bigint): boolean;
+/** Epochs left in which a claim is still admissible (0 once the claim window has closed). */
+export declare function epochsUntilRefund(currentEpoch: bigint, refundEpoch: bigint): bigint;
+/**
+ * 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 declare function conditionRootOf(conditions: object[]): string;
+/**
+ * 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 declare function findScriptRoot(body: unknown, depth?: number): string | null;
+/** What the claimant's side of the swap agreed to — checked against the chain before the preimage
+ * is ever revealed. Omit a field to skip that particular check. */
+export interface HtlcExpectations {
+    /** Exact amount expected (raw units). */
+    amount?: bigint;
+    /** Minimum acceptable amount, when an exact figure isn't agreed. */
+    minAmount?: bigint;
+    hashLockHex?: string;
+    refundEpoch?: bigint;
+    /** The counterparty (funder) who may refund — checked by rebuilding the tree from expectations. */
+    refunderPublicKeyHex?: string;
+    /** Refuse to claim with fewer than this many claim-admissible epochs left, so the claim can't be
+     * racing the refund window. Default 1 (the claim must land strictly before `refundEpoch`). */
+    minEpochsBeforeRefund?: bigint;
+}
+export interface HtlcFacts {
+    /** Decrypted value of the funded output (null when it didn't decrypt as ours). */
+    value: bigint | null;
+    /** Condition root the on-chain output actually commits to (null when absent/unreadable). */
+    onChainRoot: string | null;
+    /** The condition tree the claimant was handed. */
+    conditions: object[];
+    /** This account's own owner public key — must be the claim leaf's key. */
+    claimantPublicKeyHex: string;
+    currentEpoch: bigint;
+    /** When a preimage is supplied, SHA-256(preimage) must equal the tree's hash lock. */
+    preimageHashHex?: string;
+}
+/** Reads the hash lock and refund epoch back out of a `[claim, refund]` tree built by `htlcConditions`. */
+export declare function describeHtlcConditions(conditions: object[]): {
+    hashLockHex: string;
+    refundEpoch: bigint;
+};
+/**
+ * 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 declare function verifyHtlcTerms(facts: HtlcFacts, expected?: HtlcExpectations): string[];
+export declare class HtlcVerificationError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+/**
+ * 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 declare function isDefinitiveRejection(e: unknown): boolean;
+/**
+ * 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 declare class HtlcUnknownOutcomeError extends Error {
+    readonly journalId: string;
+    readonly details: {
+        kind: "fund" | "claim" | "refund";
+        transactionId?: string;
+        conditions: object[];
+        htlcCommitment?: string;
+        outputMask?: string;
+    };
+    constructor(journalId: string, details: {
+        kind: "fund" | "claim" | "refund";
+        transactionId?: string;
+        conditions: object[];
+        htlcCommitment?: string;
+        outputMask?: string;
+    }, cause: unknown);
+}
+/**
+ * `(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 declare function subtractScalars(aHex: string, bHex: string): string;
+/**
+ * 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 declare function decryptOwnStatementOutput(outputJson: unknown, viewSecret: Uint8Array): {
+    value: bigint;
+    maskHex: string;
+    commitment: string;
+};
+/** The Pedersen commitment of input `index` in a full statement JSON (what a spend of it commits to). */
+export declare function statementInputCommitment(statementJson: string, index?: number): string | null;
+/** 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 declare function statementOutputCommitment(statementJson: string, index?: number): string;
+export declare function sha256Hex(data: Uint8Array): Promise<string>;
+/** A fresh, random operation id (journal ids and reservation holders). */
+export declare function newOperationId(prefix: string): string;
+//# sourceMappingURL=htlcSafety.d.ts.map

package/dist/htlcSafety.d.ts.map

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

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

@@ -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,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,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

@@ -6,10 +6,11 @@ export { scanTransactionsForOwnedOutputs, sumConfidentialCommitments } from "./c
 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. */