fix(ts-sdk): locate refund auth-anchor positionally per protocol

Author: jrwbabylonlab

packages/babylon-ts-sdk/src/tbv/core/managers/pegin/__tests__/assertAuthAnchorOpReturn.test.ts

@@ -3,7 +3,8 @@ import { describe, expect, it } from "vitest";
 
 import {
   assertAuthAnchorOpReturn,
-  findAuthAnchorOpReturn,
+  countHtlcOutputs,
+  readAuthAnchorOpReturn,
 } from "../assertAuthAnchorOpReturn";
 
 const ANCHOR_HASH = "ab".repeat(32);
@@ -133,100 +134,104 @@ describe("assertAuthAnchorOpReturn", () => {
   });
 });
 
-describe("findAuthAnchorOpReturn", () => {
-  it("returns {vout, hash} for a single-vault tx (HTLC@0, OP_RETURN@1)", () => {
-    const txHex = buildTxHex([htlcOutput(), opReturnOutput(ANCHOR_HASH)]);
-    expect(findAuthAnchorOpReturn(txHex)).toEqual({
-      vout: 1,
-      hash: ANCHOR_HASH,
-    });
+describe("countHtlcOutputs", () => {
+  it("counts 1 for a single-vault auth-anchored tx [HTLC, OP_RETURN, anchor]", () => {
+    const txHex = buildTxHex([
+      htlcOutput(),
+      opReturnOutput(ANCHOR_HASH),
+      htlcOutput(),
+    ]);
+    expect(countHtlcOutputs(txHex)).toBe(1);
   });
 
-  it("returns {vout, hash} for a two-vault tx (HTLCs@0,1, OP_RETURN@2)", () => {
+  it("counts 1 for a single-vault tx with no auth anchor [HTLC, anchor]", () => {
+    const txHex = buildTxHex([htlcOutput(), htlcOutput()]);
+    expect(countHtlcOutputs(txHex)).toBe(1);
+  });
+
+  it("counts 2 for a two-vault auth-anchored tx [HTLC, HTLC, OP_RETURN, anchor]", () => {
     const txHex = buildTxHex([
       htlcOutput(),
       htlcOutput(),
       opReturnOutput(ANCHOR_HASH),
+      htlcOutput(),
     ]);
-    expect(findAuthAnchorOpReturn(txHex)).toEqual({
-      vout: 2,
-      hash: ANCHOR_HASH,
-    });
+    expect(countHtlcOutputs(txHex)).toBe(2);
   });
 
-  it("returns {vout, hash} even when followed by a CPFP-anchor-like output", () => {
-    // Real funded Pre-PegIns also carry a CPFP anchor / change output
-    // after the OP_RETURN. The finder must locate the anchor regardless
-    // of what comes after.
+  it("counts 2 for a two-vault tx with no auth anchor [HTLC, HTLC, anchor]", () => {
+    const txHex = buildTxHex([htlcOutput(), htlcOutput(), htlcOutput()]);
+    expect(countHtlcOutputs(txHex)).toBe(2);
+  });
+
+  it("stops at the first OP_RETURN — a trailing extra OP_RETURN does not change the count", () => {
+    // [HTLC, OP_RETURN, OP_RETURN]: the second OP_RETURN sits in the
+    // last (CPFP-anchor) slot and is irrelevant; the HTLC count is 1.
     const txHex = buildTxHex([
       htlcOutput(),
       opReturnOutput(ANCHOR_HASH),
-      htlcOutput(),
+      opReturnOutput(OTHER_HASH),
     ]);
-    expect(findAuthAnchorOpReturn(txHex)).toEqual({
-      vout: 1,
-      hash: ANCHOR_HASH,
-    });
+    expect(countHtlcOutputs(txHex)).toBe(1);
   });
 
-  it("strips a leading 0x prefix from the funded tx hex", () => {
-    const txHex = buildTxHex([htlcOutput(), opReturnOutput(ANCHOR_HASH)]);
-    expect(findAuthAnchorOpReturn(`0x${txHex}`)).toEqual({
-      vout: 1,
-      hash: ANCHOR_HASH,
-    });
+  it("throws when the tx has fewer than 2 outputs", () => {
+    const txHex = buildTxHex([htlcOutput()]);
+    expect(() => countHtlcOutputs(txHex)).toThrow(/at least 2 outputs/);
   });
 
-  it("returns undefined for a legacy (non-auth-anchored) tx with no OP_RETURN", () => {
-    const txHex = buildTxHex([htlcOutput(), htlcOutput()]);
-    expect(findAuthAnchorOpReturn(txHex)).toBeUndefined();
+  it("strips a leading 0x prefix from the funded tx hex", () => {
+    const txHex = buildTxHex([htlcOutput(), opReturnOutput(ANCHOR_HASH)]);
+    expect(countHtlcOutputs(`0x${txHex}`)).toBe(1);
   });
+});
 
-  it("throws when more than one OP_RETURN+PUSH32 output is present (ambiguous)", () => {
-    // A well-formed Pre-PegIn carries exactly one auth-anchor commitment.
-    // Multiple matches are malformed input — refuse rather than guess.
+describe("readAuthAnchorOpReturn", () => {
+  it("returns the hash when vout points at an OP_RETURN PUSH32 output", () => {
     const txHex = buildTxHex([
       htlcOutput(),
       opReturnOutput(ANCHOR_HASH),
-      opReturnOutput(OTHER_HASH),
+      htlcOutput(),
     ]);
-    expect(() => findAuthAnchorOpReturn(txHex)).toThrow(
-      /OP_RETURN PUSH32 outputs/,
-    );
+    expect(readAuthAnchorOpReturn(txHex, 1)).toBe(ANCHOR_HASH);
+  });
+
+  it("returns undefined when the output at vout is not an OP_RETURN (no auth anchor)", () => {
+    // [HTLC, anchor] — vout 1 is the CPFP anchor, not an OP_RETURN.
+    const txHex = buildTxHex([htlcOutput(), htlcOutput()]);
+    expect(readAuthAnchorOpReturn(txHex, 1)).toBeUndefined();
+  });
+
+  it("returns undefined when vout is out of bounds", () => {
+    const txHex = buildTxHex([htlcOutput(), htlcOutput()]);
+    expect(readAuthAnchorOpReturn(txHex, 5)).toBeUndefined();
   });
 
-  it("ignores OP_RETURN outputs with non-zero value", () => {
-    // Non-standard OP_RETURNs (non-zero value) cannot have been emitted
-    // by the WASM builder — skip them rather than treat them as a hit.
+  it("reads only the output at vout — an OP_RETURN elsewhere is ignored", () => {
+    // OP_RETURN at vout 2, but vout 1 is a plain output → no auth anchor.
     const txHex = buildTxHex([
       htlcOutput(),
-      opReturnOutput(ANCHOR_HASH, /* value */ 546),
+      htlcOutput(),
+      opReturnOutput(ANCHOR_HASH),
     ]);
-    expect(findAuthAnchorOpReturn(txHex)).toBeUndefined();
+    expect(readAuthAnchorOpReturn(txHex, 1)).toBeUndefined();
   });
 
-  it("ignores OP_RETURN outputs with non-32-byte payloads", () => {
-    // OP_RETURN PUSH16 <16 bytes> — wrong push opcode, shorter payload.
-    const tooShort = {
-      scriptHex: `6a10${"ab".repeat(16)}`,
-      value: 0,
-    };
-    const txHex = buildTxHex([htlcOutput(), tooShort]);
-    expect(findAuthAnchorOpReturn(txHex)).toBeUndefined();
+  it("throws when the output at vout is an OP_RETURN but not a clean 32-byte push", () => {
+    // OP_RETURN PUSH16 <16 bytes> — an OP_RETURN, but malformed as an
+    // auth anchor. Must throw, not silently degrade to "no anchor".
+    const malformed = { scriptHex: `6a10${"ab".repeat(16)}`, value: 0 };
+    const txHex = buildTxHex([htlcOutput(), malformed]);
+    expect(() => readAuthAnchorOpReturn(txHex, 1)).toThrow(/malformed/);
   });
 
-  it("returns undefined for unparseable hex", () => {
-    expect(findAuthAnchorOpReturn("not a real tx hex")).toBeUndefined();
+  it("strips a leading 0x prefix from the funded tx hex", () => {
+    const txHex = buildTxHex([htlcOutput(), opReturnOutput(ANCHOR_HASH)]);
+    expect(readAuthAnchorOpReturn(`0x${txHex}`, 1)).toBe(ANCHOR_HASH);
   });
 
   it("normalizes the hash to lowercase regardless of input case", () => {
-    // OP_RETURN payloads are raw bytes; the hex serialization picks a
-    // case. Normalize at the boundary so downstream byte-equality holds.
-    const upperHash = "CD".repeat(32);
-    const txHex = buildTxHex([htlcOutput(), opReturnOutput(upperHash)]);
-    expect(findAuthAnchorOpReturn(txHex)).toEqual({
-      vout: 1,
-      hash: "cd".repeat(32),
-    });
+    const txHex = buildTxHex([htlcOutput(), opReturnOutput("CD".repeat(32))]);
+    expect(readAuthAnchorOpReturn(txHex, 1)).toBe("cd".repeat(32));
   });
 });

packages/babylon-ts-sdk/src/tbv/core/managers/pegin/assertAuthAnchorOpReturn.ts

@@ -80,90 +80,74 @@ export function assertAuthAnchorOpReturn(
 }
 
 /**
- * Best-effort reader for the auth-anchor OP_RETURN payload at `vout` of
- * a funded Pre-PegIn transaction.
+ * Read the auth-anchor OP_RETURN payload at the fixed index `vout` of a
+ * funded Pre-PegIn transaction.
  *
- * Returns the 32-byte payload as lowercase hex (no `0x` prefix) if the
- * output at `vout` is exactly `OP_RETURN || PUSH32 || <32 bytes>` with
- * a zero value. Returns `undefined` for any structural mismatch —
- * missing output, wrong script shape, non-zero value — so legacy
- * non-auth-anchored Pre-PegIns parse as "no anchor" rather than
- * raising.
+ * Positional, matching the protocol: the auth anchor — when present — sits
+ * at `vout = htlcCount` (see {@link countHtlcOutputs}). Mirrors btc-vault
+ * `PrePegInTx::extract_auth_anchor_hash`:
+ *  - returns `undefined` when the output at `vout` is absent or is not an
+ *    OP_RETURN (no auth anchor — a legitimate shape);
+ *  - returns the 32-byte payload as lowercase hex when the output is a
+ *    well-formed `OP_RETURN || PUSH32 || <32 bytes>`;
+ *  - throws when the output IS an OP_RETURN but malformed — that must not
+ *    silently collapse to "no anchor".
  *
- * Used by the refund flow to reconstruct the unfunded WASM template
- * with the same output shape as the on-chain funded transaction.
- * Assertion semantics (compare against an expected value, throw on
- * mismatch) live in {@link assertAuthAnchorOpReturn}.
+ * @throws If `vout`'s output is an OP_RETURN that is not a clean 32-byte push.
  */
 export function readAuthAnchorOpReturn(
   fundedPrePeginTxHex: string,
   vout: number,
 ): string | undefined {
-  let tx: bitcoin.Transaction;
-  try {
-    tx = bitcoin.Transaction.fromHex(stripHexPrefix(fundedPrePeginTxHex));
-  } catch {
-    // Best-effort: unparseable hex is also "no extractable anchor".
-    // The same hex flows into the refund PSBT primitive immediately
-    // after, where Transaction.fromHex will surface a real parse error.
-    return undefined;
-  }
-
-  if (tx.outs.length <= vout) return undefined;
+  const tx = bitcoin.Transaction.fromHex(stripHexPrefix(fundedPrePeginTxHex));
 
   const output = tx.outs[vout];
+  if (output === undefined) return undefined;
+
   const script = output.script;
-  if (
-    script.length !== OP_RETURN_PUSH32_SCRIPT_LEN ||
-    script[0] !== OP_RETURN ||
-    script[1] !== OP_PUSH32
-  ) {
-    return undefined;
-  }
-  if (output.value !== 0) return undefined;
+  // Not an OP_RETURN → no auth anchor at this position (legitimate).
+  if (script.length === 0 || script[0] !== OP_RETURN) return undefined;
 
+  // It IS an OP_RETURN — it must be the canonical 32-byte push, or throw.
+  if (script.length !== OP_RETURN_PUSH32_SCRIPT_LEN || script[1] !== OP_PUSH32) {
+    throw new Error(
+      `Auth-anchor OP_RETURN at vout ${vout} is malformed: expected ` +
+        `${OP_RETURN_PUSH32_SCRIPT_LEN}-byte OP_RETURN + PUSH32 layout, got a ` +
+        `${script.length}-byte script`,
+    );
+  }
   return script.slice(2).toString("hex").toLowerCase();
 }
 
 /**
- * Scan a funded Pre-PegIn transaction for its auth-anchor commitment
- * (an `OP_RETURN || PUSH32 || <32 bytes>` output with value 0).
+ * Count the HTLC outputs at the head of a funded Pre-PegIn transaction.
+ *
+ * Mirrors btc-vault `PrePegInTx::count_htlc_outputs` and the contract's
+ * `PeginLogic._countHtlcOutputs`: the HTLC outputs are the contiguous
+ * leading outputs before the first OP_RETURN; the optional auth-anchor
+ * OP_RETURN sits right after them, and the CPFP anchor is always the last
+ * output. Walks outputs `[0, len - 1)` (the last is the CPFP anchor) and
+ * stops at the first OP_RETURN.
  *
- * Returns `{ vout, hash }` for exactly one match, `undefined` for zero
- * matches (legacy / unparseable). Throws on multiple matches — that
- * shape is malformed and must not silently collapse to "no anchor".
+ * The returned count doubles as the auth-anchor index for
+ * {@link readAuthAnchorOpReturn}.
+ *
+ * @throws If the transaction has fewer than 2 outputs.
  */
-export function findAuthAnchorOpReturn(
-  fundedPrePeginTxHex: string,
-): { vout: number; hash: string } | undefined {
-  let tx: bitcoin.Transaction;
-  try {
-    tx = bitcoin.Transaction.fromHex(stripHexPrefix(fundedPrePeginTxHex));
-  } catch {
-    return undefined;
-  }
-
-  const hits: { vout: number; hash: string }[] = [];
-  for (let i = 0; i < tx.outs.length; i++) {
-    const output = tx.outs[i];
-    const script = output.script;
-    if (
-      script.length === OP_RETURN_PUSH32_SCRIPT_LEN &&
-      script[0] === OP_RETURN &&
-      script[1] === OP_PUSH32 &&
-      output.value === 0
-    ) {
-      hits.push({
-        vout: i,
-        hash: script.slice(2).toString("hex").toLowerCase(),
-      });
-    }
-  }
+export function countHtlcOutputs(fundedPrePeginTxHex: string): number {
+  const tx = bitcoin.Transaction.fromHex(stripHexPrefix(fundedPrePeginTxHex));
 
-  if (hits.length > 1) {
+  if (tx.outs.length < 2) {
     throw new Error(
-      `Funded Pre-PegIn has ${hits.length} OP_RETURN PUSH32 outputs (vouts ${hits.map((h) => h.vout).join(", ")}); expected at most 1.`,
+      `Funded Pre-PegIn must have at least 2 outputs (HTLC + CPFP anchor), ` +
+        `got ${tx.outs.length}`,
     );
   }
-  return hits[0];
+
+  let count = 0;
+  for (let i = 0; i < tx.outs.length - 1; i++) {
+    if (tx.outs[i].script[0] === OP_RETURN) break;
+    count++;
+  }
+  return count;
 }

packages/babylon-ts-sdk/src/tbv/core/managers/pegin/index.ts

@@ -8,7 +8,7 @@
 
 export {
   assertAuthAnchorOpReturn,
-  findAuthAnchorOpReturn,
+  countHtlcOutputs,
   readAuthAnchorOpReturn,
 } from "./assertAuthAnchorOpReturn";
 export {