@chironbuilder/ootle-sdk 0.1.13 → 0.1.15

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/burnClaim.d.ts

@@ -7,8 +7,8 @@ export interface BurnClaimProofContents {
 }
 /**
  * The claim material an L1 wallet has as soon as it builds a burn (see tari_l1_wasm's
- * `WasmSignedBurn`). Everything except the kernel merkle proof, which only exists once the burn
- * is mined.
+ * `WasmSignedBurn`). Everything except the output's inclusion proof, which only exists once the
+ * burn is mined.
  */
 export interface L1BurnProofParts {
     /** The Ootle account public key `P` the burn was addressed to. */
@@ -19,29 +19,71 @@ export interface L1BurnProofParts {
     senderOffsetPublicKeyHex: string;
     encryptedDataHex: string;
     amount: bigint;
-    kernel: {
-        version: number;
-        fee: bigint;
-        lockHeight: bigint;
-        excessHex: string;
-        nonceHex: string;
-        signatureHex: string;
-    };
+    /** No longer part of a claim (tari-ootle#2709); kept so records written before it still load. */
+    kernel?: unknown;
 }
-/** A base node's `/generate_kernel_merkle_proof` response, passed through unchanged. */
-export interface KernelMerkleProof {
-    /** base64 */
-    block_hash: string;
-    /** base64 */
-    encoded_merkle_proof: string;
+/** An L1 MMR inclusion proof, as a base node serialises it (hashes are hex). */
+export interface L1MmrInclusionProof {
     leaf_index: number | string;
-    block_height?: number | null;
+    mmr_size: number | string;
+    path: string[];
+    peaks: string[];
 }
-/** Joins an L1 burn's claim material with its kernel merkle proof into a claimable proof. */
-export declare function assembleBurnClaimProof(parts: L1BurnProofParts, merkle: KernelMerkleProof): BurnClaimProofContents;
+/**
+ * A base node's `BurnOutputProof` (the `proof` of a `/generate_burn_output_proof` response, or
+ * `claim_proof.output_proof` of a `minotari_console_wallet` proof file). Byte fields are hex.
+ */
+export interface BurnOutputProof {
+    block_hash: string;
+    block_height?: number | string;
+    output: {
+        version: number;
+        /** Consensus (borsh) encoded `OutputFeatures` */
+        features: string;
+        commitment: string;
+        rangeproof_hash: string;
+        script: string;
+        sender_offset_public_key: string;
+        metadata_signature: {
+            ephemeral_commitment: string;
+            ephemeral_pubkey: string;
+            u_a: string;
+            u_x: string;
+            u_y: string;
+        };
+        covenant: string;
+        encrypted_data: string;
+        minimum_value_promise: number | string;
+    };
+    normal_output_proof: L1MmrInclusionProof;
+    normal_output_mr: string;
+    block_output_proof: L1MmrInclusionProof;
+}
+type BurnOutputFeatures = MinotariBurnClaimProof["output"]["features"];
+/**
+ * Decodes a burn output's consensus-encoded `OutputFeatures` into the fields a claim carries,
+ * refusing anything Ootle can't mint against (not a burn, or no confidential-output sidechain
+ * feature naming a claimant) -- the same checks as `claim_proof_from_l1`.
+ */
+export declare function decodeBurnOutputFeatures(featuresHex: string): BurnOutputFeatures;
+/**
+ * Converts a base node's `BurnOutputProof` plus the burn's ownership proof and value into the
+ * claim Ootle verifies (`claim_proof_from_l1`).
+ */
+export declare function claimProofFromL1(outputProof: BurnOutputProof, ownershipProof: {
+    public_nonce: string;
+    signature: string;
+}, value: bigint | string | number): MinotariBurnClaimProof;
+/**
+ * Joins an L1 burn's claim material with its mined output's inclusion proof (a base node's
+ * `/generate_burn_output_proof` `proof`) into a claimable proof.
+ */
+export declare function assembleBurnClaimProof(parts: L1BurnProofParts, outputProof: BurnOutputProof): BurnClaimProofContents;
 /**
  * Reads a proof file written by `minotari_console_wallet` into its `burn_proofs` directory
- * (`CompleteClaimBurnProof`). Its layout matches Ootle's except that `encrypted_data` is base64.
+ * (`CompleteClaimBurnProof`: `claim_proof` is a Minotari `BurnClaimProof` carrying the
+ * `output_proof`), converting it to Ootle's claim. A file already in Ootle's shape passes through.
  */
 export declare function parseConsoleWalletBurnProof(json: string | Record<string, unknown>): BurnClaimProofContents;
+export {};
 //# sourceMappingURL=burnClaim.d.ts.map

package/dist/burnClaim.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"burnClaim.d.ts","sourceRoot":"","sources":["../src/burnClaim.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAE9E,gGAAgG;AAChG,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,sBAAsB,CAAC;IACpC,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,wBAAwB,EAAE,MAAM,CAAC;IACjC,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,GAAG,EAAE,MAAM,CAAC;QACZ,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED,wFAAwF;AACxF,MAAM,WAAW,iBAAiB;IAChC,aAAa;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa;IACb,oBAAoB,EAAE,MAAM,CAAC;IAC7B,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAUD,6FAA6F;AAC7F,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,iBAAiB,GAAG,sBAAsB,CAgCjH;AASD;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,sBAAsB,CAc1G"}
+{"version":3,"file":"burnClaim.d.ts","sourceRoot":"","sources":["../src/burnClaim.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAE9E,gGAAgG;AAChG,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,sBAAsB,CAAC;IACpC,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,wBAAwB,EAAE,MAAM,CAAC;IACjC,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,iGAAiG;IACjG,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,iDAAiD;QACjD,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,eAAe,EAAE,MAAM,CAAC;QACxB,MAAM,EAAE,MAAM,CAAC;QACf,wBAAwB,EAAE,MAAM,CAAC;QACjC,kBAAkB,EAAE;YAClB,oBAAoB,EAAE,MAAM,CAAC;YAC7B,gBAAgB,EAAE,MAAM,CAAC;YACzB,GAAG,EAAE,MAAM,CAAC;YACZ,GAAG,EAAE,MAAM,CAAC;YACZ,GAAG,EAAE,MAAM,CAAC;SACb,CAAC;QACF,QAAQ,EAAE,MAAM,CAAC;QACjB,cAAc,EAAE,MAAM,CAAC;QACvB,qBAAqB,EAAE,MAAM,GAAG,MAAM,CAAC;KACxC,CAAC;IACF,mBAAmB,EAAE,mBAAmB,CAAC;IACzC,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,mBAAmB,CAAC;CACzC;AAgFD,KAAK,kBAAkB,GAAG,sBAAsB,CAAC,QAAQ,CAAC,CAAC,UAAU,CAAC,CAAC;AAEvE;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,CA6BhF;AA6BD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,eAAe,EAC5B,cAAc,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAC3D,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAC9B,sBAAsB,CA2BxB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,eAAe,GAAG,sBAAsB,CAWpH;AASD;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,sBAAsB,CA2B1G"}

package/dist/burnClaim.js

@@ -1,7 +1,12 @@
 // Claim proofs for Layer 1 (minotari) burns, in the exact serde shape Ootle's `ClaimBurn`
-// instruction deserialises (`tari_engine_types::confidential::MinotariBurnClaimProof`): byte fields
-// are hex, the merkle proof's two byte fields are base64, and every u64 is carried as a decimal
-// string -- a burn value can exceed 2^53, and the engine accepts strings for all of them.
+// instruction deserialises (`tari_engine_types::confidential::MinotariBurnClaimProof`).
+//
+// Since tari-ootle#2709 (Ootle 0.42, Minotari 6.0.1-pre.1) a claim proves the L1 burn *output*
+// rather than its kernel: the output's hashed fields plus a two-level MMR inclusion proof (output
+// hash -> normal output MMR root -> last leaf of the block's `block_output_mr`). A base node serves
+// that proof as a Minotari `BurnOutputProof` (`/generate_burn_output_proof?commitment=<hex>`); this
+// module converts it the way `claim_proof_from_l1` (tari_ootle_app_utilities) does, and
+// `burnClaim.test.ts` checks the conversion against vectors produced by that Rust function.
 const HEX_32 = /^[0-9a-f]{64}$/;
 function hex32(value, field) {
     const v = value.toLowerCase();
@@ -9,40 +14,192 @@ function hex32(value, field) {
         throw new Error(`${field} must be 32 bytes of hex`);
     return v;
 }
-/** Joins an L1 burn's claim material with its kernel merkle proof into a claimable proof. */
-export function assembleBurnClaimProof(parts, merkle) {
-    if (!/^[0-9a-f]+$/i.test(parts.encryptedDataHex) || parts.encryptedDataHex.length % 2 !== 0) {
-        throw new Error("encryptedDataHex must be hex");
+function hexToBytes(hex, field) {
+    if (!/^[0-9a-f]*$/i.test(hex) || hex.length % 2 !== 0)
+        throw new Error(`${field} must be hex`);
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+function bytesToHex(bytes) {
+    let out = "";
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, "0");
+    return out;
+}
+function bytesToBase64(bytes) {
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin);
+}
+/** Reads the L1 consensus (borsh) encoding. Every read is bounds-checked. */
+class BorshReader {
+    buf;
+    what;
+    pos = 0;
+    constructor(buf, what) {
+        this.buf = buf;
+        this.what = what;
+    }
+    take(n) {
+        if (this.pos + n > this.buf.length)
+            throw new Error(`${this.what}: truncated`);
+        const out = this.buf.subarray(this.pos, this.pos + n);
+        this.pos += n;
+        return out;
+    }
+    u8() {
+        return this.take(1)[0];
+    }
+    u32() {
+        const b = this.take(4);
+        return (b[0] | (b[1] << 8) | (b[2] << 16)) + b[3] * 0x1000000;
+    }
+    u64() {
+        const b = this.take(8);
+        let v = 0n;
+        for (let i = 7; i >= 0; i--)
+            v = (v << 8n) | BigInt(b[i]);
+        return v;
+    }
+    /** A `Vec<u8>` / `&[u8]`: u32 length, then the bytes. */
+    bytes(max) {
+        const n = this.u32();
+        if (n > max)
+            throw new Error(`${this.what}: byte string of ${n} exceeds ${max}`);
+        return this.take(n);
+    }
+    /** A compressed key or scalar, which L1 encodes as a 32-byte `&[u8]`. */
+    key(field) {
+        const b = this.bytes(32);
+        if (b.length !== 32)
+            throw new Error(`${this.what}: ${field} is ${b.length} bytes, expected 32`);
+        return bytesToHex(b);
+    }
+    option() {
+        const tag = this.u8();
+        if (tag > 1)
+            throw new Error(`${this.what}: invalid Option tag ${tag}`);
+        return tag === 1;
+    }
+    end() {
+        if (this.pos !== this.buf.length)
+            throw new Error(`${this.what}: ${this.buf.length - this.pos} trailing bytes`);
+    }
+}
+const OUTPUT_TYPE_BURN = 2;
+/** `SideChainFeatureData::ConfidentialOutput` */
+const SIDECHAIN_CONFIDENTIAL_OUTPUT = 2;
+/** `CoinBaseExtra = MaxSizeBytes<258>` */
+const COINBASE_EXTRA_MAX = 258;
+/**
+ * Decodes a burn output's consensus-encoded `OutputFeatures` into the fields a claim carries,
+ * refusing anything Ootle can't mint against (not a burn, or no confidential-output sidechain
+ * feature naming a claimant) -- the same checks as `claim_proof_from_l1`.
+ */
+export function decodeBurnOutputFeatures(featuresHex) {
+    const r = new BorshReader(hexToBytes(featuresHex, "burn output features"), "burn output features");
+    const version = r.u8();
+    const outputType = r.u8();
+    const maturity = r.u64();
+    r.bytes(COINBASE_EXTRA_MAX);
+    if (outputType !== OUTPUT_TYPE_BURN)
+        throw new Error(`the output is not a burn (output type ${outputType})`);
+    if (!r.option())
+        throw new Error("the burn output has no sidechain feature, so it names no claimant");
+    const variant = r.u8();
+    if (variant !== SIDECHAIN_CONFIDENTIAL_OUTPUT) {
+        throw new Error(`the burn output's sidechain feature is not a confidential output (variant ${variant})`);
+    }
+    const claimPublicKey = r.key("claim_public_key");
+    let sidechainId = null;
+    if (r.option()) {
+        const publicKey = r.key("sidechain public_key");
+        const nonce = r.key("sidechain knowledge_proof.public_nonce");
+        const signature = r.key("sidechain knowledge_proof.signature");
+        sidechainId = { public_key: publicKey, knowledge_proof: { public_nonce: nonce, signature } };
     }
+    const rangeProofType = r.u8();
+    r.end();
     return {
-        claim_proof: {
-            burn_public_key: hex32(parts.claimPublicKeyHex, "claimPublicKeyHex"),
-            commitment: hex32(parts.commitmentHex, "commitmentHex"),
-            ownership_proof: {
-                public_nonce: hex32(parts.ownershipNonceHex, "ownershipNonceHex"),
-                signature: hex32(parts.ownershipSignatureHex, "ownershipSignatureHex"),
-            },
-            encoded_merkle_proof: {
-                block_hash: merkle.block_hash,
-                encoded_merkle_proof: merkle.encoded_merkle_proof,
-                leaf_index: String(merkle.leaf_index),
-            },
-            kernel: {
-                version: parts.kernel.version,
-                fee: parts.kernel.fee.toString(),
-                lock_height: parts.kernel.lockHeight.toString(),
-                excess: hex32(parts.kernel.excessHex, "kernel.excessHex"),
-                excess_sig: {
-                    public_nonce: hex32(parts.kernel.nonceHex, "kernel.nonceHex"),
-                    signature: hex32(parts.kernel.signatureHex, "kernel.signatureHex"),
-                },
-            },
-            value: parts.amount.toString(),
-            sender_offset_public_key: hex32(parts.senderOffsetPublicKeyHex, "senderOffsetPublicKeyHex"),
+        version,
+        maturity: maturity.toString(),
+        claim_public_key: claimPublicKey,
+        sidechain_id: sidechainId,
+        range_proof_type: rangeProofType,
+    };
+}
+/** The L1 consensus (borsh) encoding of a `ComAndPubSignature`: five 32-byte fields, each length-prefixed. */
+function encodeMetadataSignature(sig) {
+    const fields = [sig.ephemeral_commitment, sig.ephemeral_pubkey, sig.u_a, sig.u_x, sig.u_y];
+    const out = new Uint8Array(fields.length * 36);
+    fields.forEach((f, i) => {
+        out.set([32, 0, 0, 0], i * 36);
+        out.set(hexToBytes(hex32(f, "metadata_signature field"), "metadata_signature field"), i * 36 + 4);
+    });
+    return out;
+}
+function mmrProof(p) {
+    return {
+        leaf_index: String(p.leaf_index),
+        mmr_size: String(p.mmr_size),
+        path: p.path.map((h) => hex32(h, "MMR path hash")),
+        peaks: p.peaks.map((h) => hex32(h, "MMR peak hash")),
+    };
+}
+/** A `BoundedVec<u8, 1, N>` field: non-empty, at most `max` bytes, serialised as base64. */
+function opaque(hex, field, max) {
+    const b = hexToBytes(hex, field);
+    if (b.length < 1 || b.length > max)
+        throw new Error(`burn output ${field} length ${b.length} is out of range`);
+    return bytesToBase64(b);
+}
+/**
+ * Converts a base node's `BurnOutputProof` plus the burn's ownership proof and value into the
+ * claim Ootle verifies (`claim_proof_from_l1`).
+ */
+export function claimProofFromL1(outputProof, ownershipProof, value) {
+    const o = outputProof.output;
+    return {
+        commitment: hex32(o.commitment, "commitment"),
+        ownership_proof: {
+            public_nonce: hex32(ownershipProof.public_nonce, "ownership_proof.public_nonce"),
+            signature: hex32(ownershipProof.signature, "ownership_proof.signature"),
+        },
+        value: BigInt(value).toString(),
+        output: {
+            version: o.version,
+            features: decodeBurnOutputFeatures(o.features),
+            rangeproof_hash: hex32(o.rangeproof_hash, "rangeproof_hash"),
+            script: opaque(o.script, "script", 4096),
+            sender_offset_public_key: hex32(o.sender_offset_public_key, "sender_offset_public_key"),
+            metadata_signature: bytesToBase64(encodeMetadataSignature(o.metadata_signature)),
+            covenant: opaque(o.covenant, "covenant", 4096),
+            encrypted_data: opaque(o.encrypted_data, "encrypted data", 4096),
+            minimum_value_promise: BigInt(o.minimum_value_promise).toString(),
+        },
+        inclusion_proof: {
+            block_hash: hex32(outputProof.block_hash, "block_hash"),
+            normal_output_proof: mmrProof(outputProof.normal_output_proof),
+            normal_output_mr: hex32(outputProof.normal_output_mr, "normal_output_mr"),
+            block_output_proof: mmrProof(outputProof.block_output_proof),
         },
-        encrypted_data: parts.encryptedDataHex.toLowerCase(),
     };
 }
+/**
+ * Joins an L1 burn's claim material with its mined output's inclusion proof (a base node's
+ * `/generate_burn_output_proof` `proof`) into a claimable proof.
+ */
+export function assembleBurnClaimProof(parts, outputProof) {
+    const commitment = hex32(parts.commitmentHex, "commitmentHex");
+    if (outputProof.output.commitment.toLowerCase() !== commitment) {
+        throw new Error("The base node's burn output proof is for a different commitment than this burn");
+    }
+    const claim = claimProofFromL1(outputProof, { public_nonce: parts.ownershipNonceHex, signature: parts.ownershipSignatureHex }, parts.amount);
+    return { claim_proof: claim, encrypted_data: bytesToHex(hexToBytes(parts.encryptedDataHex, "encryptedDataHex")) };
+}
 function base64ToHex(b64) {
     const bin = atob(b64);
     let out = "";
@@ -52,7 +209,8 @@ function base64ToHex(b64) {
 }
 /**
  * Reads a proof file written by `minotari_console_wallet` into its `burn_proofs` directory
- * (`CompleteClaimBurnProof`). Its layout matches Ootle's except that `encrypted_data` is base64.
+ * (`CompleteClaimBurnProof`: `claim_proof` is a Minotari `BurnClaimProof` carrying the
+ * `output_proof`), converting it to Ootle's claim. A file already in Ootle's shape passes through.
  */
 export function parseConsoleWalletBurnProof(json) {
     const file = (typeof json === "string" ? JSON.parse(json) : json);
@@ -64,5 +222,14 @@ export function parseConsoleWalletBurnProof(json) {
         : /^[0-9a-f]+$/i.test(file.encrypted_data) && file.encrypted_data.length % 2 === 0
             ? file.encrypted_data.toLowerCase()
             : base64ToHex(file.encrypted_data);
-    return { claim_proof: file.claim_proof, encrypted_data: encrypted };
+    const cp = file.claim_proof;
+    if (cp.output_proof) {
+        if (!cp.ownership_proof || cp.value === undefined)
+            throw new Error("Burn proof is missing its ownership proof or value");
+        return { claim_proof: claimProofFromL1(cp.output_proof, cp.ownership_proof, cp.value), encrypted_data: encrypted };
+    }
+    if (cp.inclusion_proof && cp.output)
+        return { claim_proof: cp, encrypted_data: encrypted };
+    throw new Error("This burn proof predates Ootle 0.42 (it proves the burn kernel, not the burn output). Regenerate it with a " +
+        "Minotari 6.0.1+ wallet, or claim the burn from its commitment.");
 }

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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"}