@infantmen-labs/harbor-sdk 0.4.3 → 0.5.0

package/README.md

@@ -0,0 +1,55 @@
+# harbor-sdk
+
+TypeScript SDK for Harbor bonded refunds on Solana: PDA helpers,
+instruction builders, receipt codec, ed25519 verify, account decoders.
+
+```sh
+npm i @infantmen-labs/harbor-sdk
+```
+
+```ts
+import {
+  bondPda,
+  decodeBond,
+  receiptMessageBytes,
+  verifyEd25519,
+} from "@infantmen-labs/harbor-sdk";
+
+// Locate any merchant's bond — derived offline, no RPC call.
+const [bond] = bondPda(merchant, mint);
+
+// Read its health: bonded, reserved, and free collateral.
+const info = await connection.getAccountInfo(bond);
+const { amount, reserved, openDisputes } = decodeBond(info.data);
+
+// Verify every delivery before paying for the next unit.
+const ok = verifyEd25519(signer, receiptMessageBytes(receipt), signature);
+```
+
+What it covers: `bondPda` / `bindingPda` / `disputePda` / `receiptPda` /
+`treasuryPda` / `claimPda`, instruction builders for all 11 program
+entrypoints, the frozen 185-byte receipt layout, voucher bytes, and
+zero-dependency account decoders. See `examples/bond-watch` for a
+complete third-party monitor built on SDK + web3.js only.
+
+## Buyer patterns (demand-side integration)
+
+Upstream channel builders (`openChannelIx` / `topUpIx` / `settleIx`,
+`deriveChannel`) live here so buyers never reimplement
+consensus-critical bytes by copy-paste. The proven demand-side flow:
+
+1. **Gate on collateral.** Derive `bondPda(merchant, mint)` offline,
+   `decodeBond` it, refuse when `amount − reserved` is below your
+   policy — before opening any channel or locking any escrow.
+2. **Cover every voucher.** `assertVoucherCoversQuote` enforces
+   voucher-delta ≥ quoted cost. This is billing-ack hygiene, NOT
+   delivery acceptance: pay for unit N+1 only after verifying unit N's
+   receipt AND accepting unit N's output bytes yourself. A valid
+   signature never proves correctness — nothing in this SDK will stop
+   you from treating it as one, so separate the two checks explicitly.
+3. **Size disputes from chain, not memory.** `suggestClaimSpend`
+   returns `min(binding.maxSpend, funded ATA, floor(bondFree / 3))`.
+   A `0n` suggestion means no safe claim exists — do not open.
+4. **Resolve via any live keeper.** Any keeper watching the program
+   resolves matured disputes; verify onchain (dispute account closed,
+   claimant +95%). Operate your own for production (see keeper README).

package/dist/src/accounts.d.ts

@@ -23,10 +23,25 @@ export interface Dispute {
     stakeLamports: bigint;
     claimSpend: bigint;
 }
+export interface Binding {
+    channel: PublicKey;
+    merchant: PublicKey;
+    bond: PublicKey;
+    channelProgram: PublicKey;
+    maxSpend: bigint;
+    lastNonce: bigint;
+    lastCumulativeSpend: bigint;
+    halted: boolean;
+}
 /** MerchantBond layout: disc(8) + merchant(32) + mint(32) + amount(8) +
  * slaBps(2) + challengeSlots(8) + openDisputes(8) + lastChangeSlot(8) +
  * reserved(8) + bump(1). */
 export declare function decodeBond(data: Uint8Array): Bond;
+/** ChannelBinding layout: disc(8) + channel(32) + merchant(32) +
+ * bond(32) + channel_program(32) + maxSpend(8) + lastNonce(8) +
+ * lastCumulativeSpend(8) + halted(1) + bump(1) = 162 bytes.
+ * Offsets verified against a live devnet binding. */
+export declare function decodeBinding(data: Uint8Array): Binding;
 /** Dispute layout: disc(8) + binding(32) + nonce(8) + reason(1) +
  * claimant(32) + deadlineSlot(8) + stakeLamports(8) + claimSpend(8) +
  * bump(1). */

package/dist/src/accounts.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.decodeBond = decodeBond;
+exports.decodeBinding = decodeBinding;
 exports.decodeDispute = decodeDispute;
 const web3_js_1 = require("@solana/web3.js");
 function u64(d, o) {
@@ -34,6 +35,22 @@ function decodeBond(data) {
         reserved: u64(data, 106),
     };
 }
+/** ChannelBinding layout: disc(8) + channel(32) + merchant(32) +
+ * bond(32) + channel_program(32) + maxSpend(8) + lastNonce(8) +
+ * lastCumulativeSpend(8) + halted(1) + bump(1) = 162 bytes.
+ * Offsets verified against a live devnet binding. */
+function decodeBinding(data) {
+    return {
+        channel: pk(data, 8),
+        merchant: pk(data, 40),
+        bond: pk(data, 72),
+        channelProgram: pk(data, 104),
+        maxSpend: u64(data, 136),
+        lastNonce: u64(data, 144),
+        lastCumulativeSpend: u64(data, 152),
+        halted: data[160] !== 0,
+    };
+}
 /** Dispute layout: disc(8) + binding(32) + nonce(8) + reason(1) +
  * claimant(32) + deadlineSlot(8) + stakeLamports(8) + claimSpend(8) +
  * bump(1). */

package/dist/src/buyer.d.ts

@@ -0,0 +1,61 @@
+import { Connection, PublicKey } from "@solana/web3.js";
+/**
+ * Buyer-side incident helpers. These encode the operator judgments a
+ * demand buyer otherwise hand-rolls at 2am: how large a claim is safe,
+ * and whether a voucher covers the quoted price. Pure chain reads —
+ * nothing here opens disputes or moves funds.
+ */
+/** A voucher authorizing less than the quoted cost. */
+export declare class VoucherUnderquoted extends Error {
+    readonly quoted: bigint;
+    readonly authorized: bigint;
+    constructor(quoted: bigint, authorized: bigint);
+}
+/** A voucher older than the channel watermark (replay or reorder). */
+export declare class StaleVoucher extends Error {
+    readonly watermark: bigint;
+    readonly voucherCumulative: bigint;
+    constructor(watermark: bigint, voucherCumulative: bigint);
+}
+/**
+ * Coverage check: the voucher's marginal authorization must cover the
+ * quoted cost. This is billing-ack hygiene, NOT delivery acceptance —
+ * a covered voucher says the merchant may be paid, never that the
+ * output was correct (verify output bytes separately).
+ */
+export declare function assertVoucherCoversQuote(args: {
+    lastCumulative: bigint;
+    voucherCumulative: bigint;
+    quotedCost: bigint;
+}): void;
+export interface ClaimSuggestion {
+    /** Nonce to dispute (explicit, or binding.lastNonce + 1). */
+    nonce: bigint;
+    /** Onchain ceiling: claim_spend must be ≤ this (binding.maxSpend). */
+    maxSpend: bigint;
+    /** Claimant ATA balance for the bond mint. */
+    funded: bigint;
+    /** Bond free collateral (amount − reserved). */
+    bondFree: bigint;
+    /** Largest claim the bond can back: floor(free / 3). */
+    bondCap: bigint;
+    /**
+     * Suggested claim_spend = min(maxSpend, funded, bondCap). 0n means no
+     * safe claim exists — do NOT open a dispute (claim_spend must be > 0
+     * onchain); top up, wait, or walk away instead.
+     */
+    claimSpend: bigint;
+}
+/**
+ * Maps "failed nonce N" to a safe claim amount. Reads the binding (cap +
+ * nonce default), the bond (free collateral — every unit of claim locks
+ * 3x: refund + fee + penalty), and the claimant's ATA (the claim stake
+ * must actually be funded). Throws when the binding or bond account is
+ * missing.
+ */
+export declare function suggestClaimSpend(conn: Connection, args: {
+    binding: PublicKey;
+    claimant: PublicKey;
+    mint: PublicKey;
+    nonce?: bigint;
+}): Promise<ClaimSuggestion>;

package/dist/src/buyer.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StaleVoucher = exports.VoucherUnderquoted = void 0;
+exports.assertVoucherCoversQuote = assertVoucherCoversQuote;
+exports.suggestClaimSpend = suggestClaimSpend;
+const accounts_1 = require("./accounts");
+const pda_1 = require("./pda");
+/**
+ * Buyer-side incident helpers. These encode the operator judgments a
+ * demand buyer otherwise hand-rolls at 2am: how large a claim is safe,
+ * and whether a voucher covers the quoted price. Pure chain reads —
+ * nothing here opens disputes or moves funds.
+ */
+/** A voucher authorizing less than the quoted cost. */
+class VoucherUnderquoted extends Error {
+    quoted;
+    authorized;
+    constructor(quoted, authorized) {
+        super(`voucher authorizes ${authorized} but merchant quoted ${quoted}`);
+        this.quoted = quoted;
+        this.authorized = authorized;
+        this.name = "VoucherUnderquoted";
+    }
+}
+exports.VoucherUnderquoted = VoucherUnderquoted;
+/** A voucher older than the channel watermark (replay or reorder). */
+class StaleVoucher extends Error {
+    watermark;
+    voucherCumulative;
+    constructor(watermark, voucherCumulative) {
+        super(`voucher cumulative ${voucherCumulative} is behind watermark ${watermark}`);
+        this.watermark = watermark;
+        this.voucherCumulative = voucherCumulative;
+        this.name = "StaleVoucher";
+    }
+}
+exports.StaleVoucher = StaleVoucher;
+/**
+ * Coverage check: the voucher's marginal authorization must cover the
+ * quoted cost. This is billing-ack hygiene, NOT delivery acceptance —
+ * a covered voucher says the merchant may be paid, never that the
+ * output was correct (verify output bytes separately).
+ */
+function assertVoucherCoversQuote(args) {
+    if (args.voucherCumulative < args.lastCumulative) {
+        throw new StaleVoucher(args.lastCumulative, args.voucherCumulative);
+    }
+    const authorized = args.voucherCumulative - args.lastCumulative;
+    if (authorized < args.quotedCost) {
+        throw new VoucherUnderquoted(args.quotedCost, authorized);
+    }
+}
+/**
+ * Maps "failed nonce N" to a safe claim amount. Reads the binding (cap +
+ * nonce default), the bond (free collateral — every unit of claim locks
+ * 3x: refund + fee + penalty), and the claimant's ATA (the claim stake
+ * must actually be funded). Throws when the binding or bond account is
+ * missing.
+ */
+async function suggestClaimSpend(conn, args) {
+    const bindingInfo = await conn.getAccountInfo(args.binding);
+    if (bindingInfo === null)
+        throw new Error("binding account missing");
+    const binding = (0, accounts_1.decodeBinding)(bindingInfo.data);
+    const nonce = args.nonce ?? binding.lastNonce + 1n;
+    const bondInfo = await conn.getAccountInfo(binding.bond);
+    if (bondInfo === null)
+        throw new Error("bond account missing");
+    const bond = (0, accounts_1.decodeBond)(bondInfo.data);
+    const bondFree = bond.amount - bond.reserved;
+    // Outflow per unit of claim is 3x (refund + fee + penalty).
+    const bondCap = bondFree >= 0n ? bondFree / 3n : 0n;
+    const claimantAta = (0, pda_1.ataFor)(args.claimant, args.mint);
+    const ataInfo = await conn.getAccountInfo(claimantAta);
+    let funded = 0n;
+    if (ataInfo !== null) {
+        const bal = await conn.getTokenAccountBalance(claimantAta);
+        funded = BigInt(bal.value.amount);
+    }
+    let claimSpend = binding.maxSpend;
+    if (funded < claimSpend)
+        claimSpend = funded;
+    if (bondCap < claimSpend)
+        claimSpend = bondCap;
+    return {
+        nonce,
+        maxSpend: binding.maxSpend,
+        funded,
+        bondFree,
+        bondCap,
+        claimSpend,
+    };
+}

package/dist/src/channels.d.ts

@@ -0,0 +1,31 @@
+import { PublicKey, TransactionInstruction } from "@solana/web3.js";
+/** Upstream `open`. Layout: disc(1) | salt(8) | deposit(8) | grace(4) | slot(8) | recipients u32. */
+export declare function openChannelIx(args: {
+    programId: PublicKey;
+    payer: PublicKey;
+    payee: PublicKey;
+    mint: PublicKey;
+    authorizedSigner: PublicKey;
+    channel: PublicKey;
+    payerAta: PublicKey;
+    channelAta: PublicKey;
+    eventAuthority: PublicKey;
+    salt: bigint;
+    deposit: bigint;
+    gracePeriod: number;
+    openSlot: bigint;
+}): TransactionInstruction;
+export declare function settleIx(programId: PublicKey, channel: PublicKey): TransactionInstruction;
+/** Upstream `top_up`. Layout: disc(3) | amount(8). */
+export declare function topUpIx(args: {
+    programId: PublicKey;
+    payer: PublicKey;
+    channel: PublicKey;
+    payerAta: PublicKey;
+    channelAta: PublicKey;
+    mint: PublicKey;
+    amount: bigint;
+}): TransactionInstruction;
+export declare function deriveChannel(programId: PublicKey, payer: PublicKey, payee: PublicKey, mint: PublicKey, authorizedSigner: PublicKey, salt: bigint, openSlot: bigint): {
+    channel: PublicKey;
+};

package/dist/src/channels.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openChannelIx = openChannelIx;
+exports.settleIx = settleIx;
+exports.topUpIx = topUpIx;
+exports.deriveChannel = deriveChannel;
+const web3_js_1 = require("@solana/web3.js");
+const ids_1 = require("./ids");
+const pda_1 = require("./pda");
+const u64_1 = require("./u64");
+/**
+ * Upstream payment-channels instruction builders. These encode the pinned
+ * upstream layouts (see docs/upstream-pin.md) so third-party buyers never
+ * reimplement consensus-critical bytes by copy-paste. Previously lived in
+ * the reference agent; moved here verbatim (byte-identical output).
+ */
+function m(pubkey, writable, signer) {
+    return { pubkey, isWritable: writable, isSigner: signer };
+}
+function u32(v) {
+    const b = Buffer.alloc(4);
+    b.writeUInt32LE(v);
+    return b;
+}
+/** Upstream `open`. Layout: disc(1) | salt(8) | deposit(8) | grace(4) | slot(8) | recipients u32. */
+function openChannelIx(args) {
+    const data = Buffer.concat([
+        Buffer.from([1]),
+        (0, u64_1.u64le)(args.salt),
+        (0, u64_1.u64le)(args.deposit),
+        u32(args.gracePeriod),
+        (0, u64_1.u64le)(args.openSlot),
+        u32(0),
+    ]);
+    return new web3_js_1.TransactionInstruction({
+        programId: args.programId,
+        keys: [
+            m(args.payer, true, true),
+            m(args.payer, true, true),
+            m(args.payee, false, false),
+            m(args.mint, false, false),
+            m(args.authorizedSigner, false, false),
+            m(args.channel, true, false),
+            m(args.payerAta, true, false),
+            m(args.channelAta, true, false),
+            m(ids_1.TOKEN_PROGRAM_ID, false, false),
+            m(ids_1.SYSTEM_PROGRAM_ID, false, false),
+            m(ids_1.RENT_SYSVAR_ID, false, false),
+            m(ids_1.ATA_PROGRAM_ID, false, false),
+            m(args.eventAuthority, false, false),
+            m(args.programId, false, false),
+        ],
+        data,
+    });
+}
+function settleIx(programId, channel) {
+    return new web3_js_1.TransactionInstruction({
+        programId,
+        keys: [m(channel, true, false), m(ids_1.IX_SYSVAR_ID, false, false)],
+        data: Buffer.from([2]),
+    });
+}
+/** Upstream `top_up`. Layout: disc(3) | amount(8). */
+function topUpIx(args) {
+    return new web3_js_1.TransactionInstruction({
+        programId: args.programId,
+        keys: [
+            m(args.payer, true, true),
+            m(args.channel, true, false),
+            m(args.payerAta, true, false),
+            m(args.channelAta, true, false),
+            m(args.mint, false, false),
+            m(ids_1.TOKEN_PROGRAM_ID, false, false),
+        ],
+        data: Buffer.concat([Buffer.from([3]), (0, u64_1.u64le)(args.amount)]),
+    });
+}
+function deriveChannel(programId, payer, payee, mint, authorizedSigner, salt, openSlot) {
+    const [channel] = (0, pda_1.channelPda)(programId, payer, payee, mint, authorizedSigner, salt, openSlot);
+    return { channel };
+}

package/dist/src/ed25519.js

@@ -5,6 +5,7 @@ exports.buildEd25519Ix = buildEd25519Ix;
 exports.channelVoucherBytes = channelVoucherBytes;
 const web3_js_1 = require("@solana/web3.js");
 const ids_1 = require("./ids");
+const u64_1 = require("./u64");
 /**
  * Canonical single-signature Ed25519 precompile ix. Offsets point into this
  * ix's own data (indices u16::MAX). Layout: header(16) | pubkey(32) |
@@ -40,8 +41,8 @@ function channelVoucherBytes(channel, cumulative, expiresAt) {
     out.writeUInt8(0x56, 0);
     out.writeUInt8(0x01, 1);
     channel.toBuffer().copy(out, 2);
-    out.writeBigUInt64LE(cumulative, 34);
-    out.writeBigInt64LE(expiresAt, 42);
+    (0, u64_1.writeU64LE)(out, cumulative, 34);
+    (0, u64_1.writeI64LE)(out, expiresAt, 42);
     return out;
 }
 exports.VOUCHER_LEN = 50;

package/dist/src/harbor-ix.js

@@ -12,6 +12,7 @@ exports.haltBindingIx = haltBindingIx;
 exports.resolveTimeoutIx = resolveTimeoutIx;
 const web3_js_1 = require("@solana/web3.js");
 const ids_1 = require("./ids");
+const u64_1 = require("./u64");
 const D = {
     registerMerchant: [238, 245, 77, 132, 161, 88, 216, 248],
     postBond: [168, 151, 202, 119, 163, 58, 147, 247],
@@ -36,9 +37,7 @@ function u16(v) {
     return b;
 }
 function u64(v) {
-    const b = Buffer.alloc(8);
-    b.writeBigUInt64LE(v);
-    return b;
+    return (0, u64_1.u64le)(v);
 }
 function pk(k) {
     return k.toBuffer();

package/dist/src/index.d.ts

@@ -2,6 +2,10 @@ export * from "./ids";
 export * from "./pda";
 export * from "./accounts";
 export * from "./receipt";
+export * from "./tx";
+export * from "./u64";
+export * from "./channels";
+export * from "./buyer";
 export * from "./ed25519";
 export * from "./verify";
 export * from "./harbor-ix";

package/dist/src/index.js

@@ -18,6 +18,10 @@ __exportStar(require("./ids"), exports);
 __exportStar(require("./pda"), exports);
 __exportStar(require("./accounts"), exports);
 __exportStar(require("./receipt"), exports);
+__exportStar(require("./tx"), exports);
+__exportStar(require("./u64"), exports);
+__exportStar(require("./channels"), exports);
+__exportStar(require("./buyer"), exports);
 __exportStar(require("./ed25519"), exports);
 __exportStar(require("./verify"), exports);
 __exportStar(require("./harbor-ix"), exports);

package/dist/src/pda.d.ts

@@ -7,4 +7,6 @@ export declare function treasuryPda(mint: PublicKey): [PublicKey, number];
 /** Tombstone marking a (binding, nonce) as claimed exactly once. */
 export declare function claimPda(binding: PublicKey, nonce: bigint): [PublicKey, number];
 export declare function channelPda(channelProgram: PublicKey, payer: PublicKey, payee: PublicKey, mint: PublicKey, authorizedSigner: PublicKey, salt: bigint, openSlot: bigint): [PublicKey, number];
+/** Canonical associated token address for (owner, mint). */
+export declare function ataFor(owner: PublicKey, mint: PublicKey): PublicKey;
 export declare function channelAta(channel: PublicKey, tokenProgram: PublicKey, mint: PublicKey, ataProgram: PublicKey): [PublicKey, number];

package/dist/src/pda.js

@@ -7,9 +7,12 @@ exports.disputePda = disputePda;
 exports.treasuryPda = treasuryPda;
 exports.claimPda = claimPda;
 exports.channelPda = channelPda;
+exports.ataFor = ataFor;
 exports.channelAta = channelAta;
 const web3_js_1 = require("@solana/web3.js");
 const ids_1 = require("./ids");
+const ids_2 = require("./ids");
+const u64_1 = require("./u64");
 function bondPda(merchant, mint) {
     return web3_js_1.PublicKey.findProgramAddressSync([Buffer.from("bond"), merchant.toBuffer(), mint.toBuffer()], ids_1.HARBOR_PROGRAM_ID);
 }
@@ -17,13 +20,11 @@ function bindingPda(channel) {
     return web3_js_1.PublicKey.findProgramAddressSync([Buffer.from("binding"), channel.toBuffer()], ids_1.HARBOR_PROGRAM_ID);
 }
 function receiptPda(binding, nonce) {
-    const nonceBuf = Buffer.alloc(8);
-    nonceBuf.writeBigUInt64LE(nonce);
+    const nonceBuf = (0, u64_1.u64le)(nonce);
     return web3_js_1.PublicKey.findProgramAddressSync([Buffer.from("receipt"), binding.toBuffer(), nonceBuf], ids_1.HARBOR_PROGRAM_ID);
 }
 function disputePda(binding, nonce) {
-    const nonceBuf = Buffer.alloc(8);
-    nonceBuf.writeBigUInt64LE(nonce);
+    const nonceBuf = (0, u64_1.u64le)(nonce);
     return web3_js_1.PublicKey.findProgramAddressSync([Buffer.from("dispute"), binding.toBuffer(), nonceBuf], ids_1.HARBOR_PROGRAM_ID);
 }
 function treasuryPda(mint) {
@@ -31,15 +32,12 @@ function treasuryPda(mint) {
 }
 /** Tombstone marking a (binding, nonce) as claimed exactly once. */
 function claimPda(binding, nonce) {
-    const nonceBuf = Buffer.alloc(8);
-    nonceBuf.writeBigUInt64LE(nonce);
+    const nonceBuf = (0, u64_1.u64le)(nonce);
     return web3_js_1.PublicKey.findProgramAddressSync([Buffer.from("claim"), binding.toBuffer(), nonceBuf], ids_1.HARBOR_PROGRAM_ID);
 }
 function channelPda(channelProgram, payer, payee, mint, authorizedSigner, salt, openSlot) {
-    const saltBuf = Buffer.alloc(8);
-    saltBuf.writeBigUInt64LE(salt);
-    const slotBuf = Buffer.alloc(8);
-    slotBuf.writeBigUInt64LE(openSlot);
+    const saltBuf = (0, u64_1.u64le)(salt);
+    const slotBuf = (0, u64_1.u64le)(openSlot);
     return web3_js_1.PublicKey.findProgramAddressSync([
         Buffer.from("channel"),
         payer.toBuffer(),
@@ -50,6 +48,10 @@ function channelPda(channelProgram, payer, payee, mint, authorizedSigner, salt,
         slotBuf,
     ], channelProgram);
 }
+/** Canonical associated token address for (owner, mint). */
+function ataFor(owner, mint) {
+    return web3_js_1.PublicKey.findProgramAddressSync([owner.toBuffer(), ids_2.TOKEN_PROGRAM_ID.toBuffer(), mint.toBuffer()], ids_2.ATA_PROGRAM_ID)[0];
+}
 function channelAta(channel, tokenProgram, mint, ataProgram) {
     return web3_js_1.PublicKey.findProgramAddressSync([channel.toBuffer(), tokenProgram.toBuffer(), mint.toBuffer()], ataProgram);
 }

package/dist/src/receipt.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RECEIPT_MESSAGE_LEN = void 0;
 exports.receiptMessageBytes = receiptMessageBytes;
+const u64_1 = require("./u64");
 function assertLen(b, n, name) {
     if (b.length !== n)
         throw new Error(`${name} must be ${n} bytes`);
@@ -16,7 +17,7 @@ function receiptMessageBytes(f) {
     o += 32;
     f.binding.toBuffer().copy(out, o);
     o += 32;
-    out.writeBigUInt64LE(f.cumulativeSpend, o);
+    (0, u64_1.writeU64LE)(out, f.cumulativeSpend, o);
     o += 8;
     Buffer.from(f.meterHash).copy(out, o);
     o += 32;
@@ -24,9 +25,9 @@ function receiptMessageBytes(f) {
     o += 32;
     out.writeUInt8(f.status, o);
     o += 1;
-    out.writeBigUInt64LE(f.nonce, o);
+    (0, u64_1.writeU64LE)(out, f.nonce, o);
     o += 8;
-    out.writeBigUInt64LE(f.expirySlot, o);
+    (0, u64_1.writeU64LE)(out, f.expirySlot, o);
     o += 8;
     f.signer.toBuffer().copy(out, o);
     o += 32;

package/dist/src/tx.d.ts

@@ -0,0 +1,11 @@
+import { Connection, Signer, Transaction, TransactionSignature } from "@solana/web3.js";
+/** True only for errors proving the tx can never confirm (safe to rebuild). */
+export declare function isExpiredError(e: unknown): boolean;
+/**
+ * Send with fresh-blockhash retries. Each attempt rebuilds the tx so a
+ * new blockhash is fetched; only expiry-proven failures retry (timeouts
+ * and unknown states propagate — resending those could double-execute).
+ * All Harbor ixs are init-or-check guarded, so a rebuilt resend after a
+ * proven expiry fails safe even in the worst case.
+ */
+export declare function sendWithRetry(conn: Connection, buildTx: () => Transaction, signers: Signer[], maxTries?: number): Promise<TransactionSignature>;

package/dist/src/tx.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isExpiredError = isExpiredError;
+exports.sendWithRetry = sendWithRetry;
+const web3_js_1 = require("@solana/web3.js");
+const EXPIRY = /block height exceeded|blockhash not found/i;
+/** True only for errors proving the tx can never confirm (safe to rebuild). */
+function isExpiredError(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return EXPIRY.test(msg);
+}
+/**
+ * Send with fresh-blockhash retries. Each attempt rebuilds the tx so a
+ * new blockhash is fetched; only expiry-proven failures retry (timeouts
+ * and unknown states propagate — resending those could double-execute).
+ * All Harbor ixs are init-or-check guarded, so a rebuilt resend after a
+ * proven expiry fails safe even in the worst case.
+ */
+async function sendWithRetry(conn, buildTx, signers, maxTries = 3) {
+    let lastErr = new Error("sendWithRetry: no attempts made");
+    for (let attempt = 1; attempt <= maxTries; attempt++) {
+        try {
+            return await (0, web3_js_1.sendAndConfirmTransaction)(conn, buildTx(), signers);
+        }
+        catch (e) {
+            lastErr = e;
+            if (attempt >= maxTries || !isExpiredError(e))
+                throw e;
+        }
+    }
+    throw lastErr;
+}

package/dist/src/u64.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Portable little-endian 64-bit encoders.
+ *
+ * Browser Buffer polyfills predate the BigInt read/write methods, so the
+ * SDK must never call writeBigUInt64LE / writeBigInt64LE directly — any
+ * bundler-shipped dapp (including our own web UI) would crash at runtime.
+ * Index assignment works on every Buffer/Uint8Array implementation.
+ */
+export declare function writeU64LE(out: Uint8Array, v: bigint | number, offset: number): void;
+export declare function writeI64LE(out: Uint8Array, v: bigint | number, offset: number): void;
+export declare function u64le(v: bigint | number): Buffer;

package/dist/src/u64.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeU64LE = writeU64LE;
+exports.writeI64LE = writeI64LE;
+exports.u64le = u64le;
+/**
+ * Portable little-endian 64-bit encoders.
+ *
+ * Browser Buffer polyfills predate the BigInt read/write methods, so the
+ * SDK must never call writeBigUInt64LE / writeBigInt64LE directly — any
+ * bundler-shipped dapp (including our own web UI) would crash at runtime.
+ * Index assignment works on every Buffer/Uint8Array implementation.
+ */
+function writeU64LE(out, v, offset) {
+    let x = typeof v === "bigint" ? v : BigInt(v);
+    if (x < 0n || x >= 1n << 64n)
+        throw new RangeError("u64 out of range");
+    for (let i = 0; i < 8; i++) {
+        out[offset + i] = Number(x & 0xffn);
+        x >>= 8n;
+    }
+}
+function writeI64LE(out, v, offset) {
+    let x = typeof v === "bigint" ? v : BigInt(v);
+    if (x < -(1n << 63n) || x >= 1n << 63n)
+        throw new RangeError("i64 out of range");
+    if (x < 0n)
+        x += 1n << 64n;
+    writeU64LE(out, x, offset);
+}
+function u64le(v) {
+    const b = Buffer.alloc(8);
+    writeU64LE(b, v, 0);
+    return b;
+}

package/dist/test/vectors.test.js

@@ -141,3 +141,294 @@ const P = (n) => new web3_js_1.PublicKey(Buffer.alloc(32, n));
         strict_1.default.equal(d.claimSpend, 3670n);
     });
 });
+(0, node_test_1.describe)("sendWithRetry", () => {
+    function mockConn(script) {
+        let builds = 0;
+        const conn = {
+            getLatestBlockhash: async () => ({
+                blockhash: "11111111111111111111111111111111",
+                lastValidBlockHeight: 1,
+            }),
+            sendTransaction: async () => {
+                const step = script.shift();
+                if (step === "expiry") {
+                    throw new Error("Signature X has expired: block height exceeded.");
+                }
+                if (step === "fatal")
+                    throw new Error("simulated failure");
+                return "sig-ok";
+            },
+            confirmTransaction: async () => ({ value: { err: null } }),
+        };
+        return {
+            conn,
+            builds: () => builds,
+            build: () => {
+                builds += 1;
+                return new web3_js_1.Transaction();
+            },
+        };
+    }
+    (0, node_test_1.it)("rebuilds and resends once after a single expiry", async () => {
+        const { conn, builds, build } = mockConn(["expiry", "ok"]);
+        const sig = await (0, index_1.sendWithRetry)(conn, build, [], 3);
+        strict_1.default.equal(sig, "sig-ok");
+        strict_1.default.equal(builds(), 2);
+    });
+    (0, node_test_1.it)("gives up after maxTries on repeated expiry", async () => {
+        const { conn, builds, build } = mockConn(["expiry", "expiry", "expiry"]);
+        await strict_1.default.rejects((0, index_1.sendWithRetry)(conn, build, [], 3), /block height exceeded/);
+        strict_1.default.equal(builds(), 3);
+    });
+    (0, node_test_1.it)("propagates non-expiry failures immediately without rebuild", async () => {
+        const { conn, builds, build } = mockConn(["fatal", "ok"]);
+        await strict_1.default.rejects((0, index_1.sendWithRetry)(conn, build, [], 3), /simulated failure/);
+        strict_1.default.equal(builds(), 1);
+    });
+});
+(0, node_test_1.describe)("portable u64 encoders", () => {
+    (0, node_test_1.it)("matches native writeBigUInt64LE byte-for-byte", () => {
+        for (const v of [0n, 1n, 255n, 256n, 2n ** 32n, 2n ** 64n - 1n]) {
+            const expected = Buffer.alloc(8);
+            expected.writeBigUInt64LE(v);
+            strict_1.default.deepEqual((0, index_1.u64le)(v), expected);
+            const out = Buffer.alloc(8);
+            (0, index_1.writeU64LE)(out, v, 0);
+            strict_1.default.deepEqual(out, expected);
+        }
+    });
+    (0, node_test_1.it)("encodes signed i64 incl. negatives like writeBigInt64LE", () => {
+        for (const v of [0n, 1n, -1n, -(2n ** 63n), 2n ** 63n - 1n]) {
+            const expected = Buffer.alloc(8);
+            expected.writeBigInt64LE(v);
+            const out = Buffer.alloc(8);
+            (0, index_1.writeI64LE)(out, v, 0);
+            strict_1.default.deepEqual(out, expected);
+        }
+    });
+    (0, node_test_1.it)("rejects out-of-range values instead of wrapping", () => {
+        strict_1.default.throws(() => (0, index_1.u64le)(-1n), RangeError);
+        strict_1.default.throws(() => (0, index_1.u64le)(2n ** 64n), RangeError);
+        strict_1.default.throws(() => (0, index_1.writeI64LE)(Buffer.alloc(8), 2n ** 63n, 0), RangeError);
+    });
+});
+(0, node_test_1.describe)("upstream channel builders (moved from agent, byte-identical)", () => {
+    const PROGRAM = P(1);
+    const args = {
+        programId: PROGRAM,
+        payer: P(2),
+        payee: P(3),
+        mint: P(4),
+        authorizedSigner: P(5),
+        channel: P(6),
+        payerAta: P(7),
+        channelAta: P(8),
+        eventAuthority: P(9),
+        salt: 42n,
+        deposit: 5000000n,
+        gracePeriod: 7200,
+        openSlot: 99n,
+    };
+    (0, node_test_1.it)("open encodes disc | salt | deposit | grace | slot | recipients", () => {
+        const ix = (0, index_1.openChannelIx)(args);
+        const d = Buffer.from(ix.data);
+        strict_1.default.equal(d.readUInt8(0), 1);
+        strict_1.default.equal(d.readBigUInt64LE(1), 42n);
+        strict_1.default.equal(d.readBigUInt64LE(9), 5000000n);
+        strict_1.default.equal(d.readUInt32LE(17), 7200);
+        strict_1.default.equal(d.readBigUInt64LE(21), 99n);
+        strict_1.default.equal(d.readUInt32LE(29), 0);
+        strict_1.default.equal(d.length, 33);
+        strict_1.default.equal(ix.keys.length, 14);
+        strict_1.default.ok(ix.programId.equals(PROGRAM));
+    });
+    (0, node_test_1.it)("settle is a bare discriminator with channel + sysvar", () => {
+        const ix = (0, index_1.settleIx)(PROGRAM, P(6));
+        strict_1.default.deepEqual(Array.from(ix.data), [2]);
+        strict_1.default.equal(ix.keys.length, 2);
+    });
+    (0, node_test_1.it)("top_up encodes disc | amount with 6 accounts", () => {
+        const ix = (0, index_1.topUpIx)({
+            programId: PROGRAM,
+            payer: P(2),
+            channel: P(6),
+            payerAta: P(7),
+            channelAta: P(8),
+            mint: P(4),
+            amount: 9n,
+        });
+        const d = Buffer.from(ix.data);
+        strict_1.default.equal(d.readUInt8(0), 3);
+        strict_1.default.equal(d.readBigUInt64LE(1), 9n);
+        strict_1.default.equal(d.length, 9);
+        strict_1.default.equal(ix.keys.length, 6);
+    });
+    (0, node_test_1.it)("deriveChannel matches channelPda", () => {
+        const { channel } = (0, index_1.deriveChannel)(P(1), P(2), P(3), P(4), P(5), 42n, 99n);
+        strict_1.default.equal(channel.toBase58().length, 44);
+    });
+});
+(0, node_test_1.describe)("decodeBinding", () => {
+    function bindingBytes() {
+        const b = Buffer.alloc(162);
+        P(6).toBuffer().copy(b, 8);
+        P(11).toBuffer().copy(b, 40);
+        P(12).toBuffer().copy(b, 72);
+        P(13).toBuffer().copy(b, 104);
+        b.writeBigUInt64LE(2000n, 136);
+        b.writeBigUInt64LE(4n, 144);
+        b.writeBigUInt64LE(15000n, 152);
+        b.writeUInt8(0, 160);
+        return b;
+    }
+    (0, node_test_1.it)("decodes every field at its documented offset", () => {
+        const d = (0, index_1.decodeBinding)(bindingBytes());
+        strict_1.default.ok(d.channel.equals(P(6)));
+        strict_1.default.ok(d.merchant.equals(P(11)));
+        strict_1.default.ok(d.bond.equals(P(12)));
+        strict_1.default.ok(d.channelProgram.equals(P(13)));
+        strict_1.default.equal(d.maxSpend, 2000n);
+        strict_1.default.equal(d.lastNonce, 4n);
+        strict_1.default.equal(d.lastCumulativeSpend, 15000n);
+        strict_1.default.equal(d.halted, false);
+    });
+});
+(0, node_test_1.describe)("assertVoucherCoversQuote", () => {
+    (0, node_test_1.it)("passes when the marginal authorization covers the quote", () => {
+        (0, index_1.assertVoucherCoversQuote)({
+            lastCumulative: 10000n,
+            voucherCumulative: 12050n,
+            quotedCost: 2000n,
+        });
+    });
+    (0, node_test_1.it)("throws VoucherUnderquoted on short authorization", () => {
+        strict_1.default.throws(() => (0, index_1.assertVoucherCoversQuote)({
+            lastCumulative: 10000n,
+            voucherCumulative: 11000n,
+            quotedCost: 2000n,
+        }), index_1.VoucherUnderquoted);
+    });
+    (0, node_test_1.it)("throws StaleVoucher when behind the watermark", () => {
+        strict_1.default.throws(() => (0, index_1.assertVoucherCoversQuote)({
+            lastCumulative: 10000n,
+            voucherCumulative: 9000n,
+            quotedCost: 1n,
+        }), index_1.StaleVoucher);
+    });
+});
+(0, node_test_1.describe)("suggestClaimSpend", () => {
+    const BINDING = P(20);
+    const CLAIMANT = P(21);
+    const MINT = P(22);
+    const BOND = P(23);
+    function bondBytes(amount, reserved) {
+        const b = Buffer.alloc(115);
+        P(11).toBuffer().copy(b, 8);
+        MINT.toBuffer().copy(b, 40);
+        b.writeBigUInt64LE(amount, 72);
+        b.writeBigUInt64LE(reserved, 106);
+        return b;
+    }
+    function bindingBytes(maxSpend, lastNonce) {
+        const b = Buffer.alloc(162);
+        P(6).toBuffer().copy(b, 8);
+        P(11).toBuffer().copy(b, 40);
+        BOND.toBuffer().copy(b, 72);
+        P(13).toBuffer().copy(b, 104);
+        b.writeBigUInt64LE(maxSpend, 136);
+        b.writeBigUInt64LE(lastNonce, 144);
+        return b;
+    }
+    function mockConn(opts) {
+        const ata = (0, index_1.ataFor)(CLAIMANT, MINT);
+        return {
+            getAccountInfo: async (k) => {
+                const key = k.toBase58();
+                if (key === BINDING.toBase58())
+                    return opts.binding === null ? null : { data: opts.binding };
+                if (key === BOND.toBase58())
+                    return { data: bondBytes(opts.bondAmount, opts.bondReserved) };
+                if (key === ata.toBase58())
+                    return opts.ataExists ? { data: Buffer.alloc(165) } : null;
+                return null;
+            },
+            getTokenAccountBalance: async () => ({
+                value: { amount: opts.funded.toString() },
+            }),
+        };
+    }
+    const base = {
+        binding: BINDING,
+        claimant: CLAIMANT,
+        mint: MINT,
+    };
+    (0, node_test_1.it)("caps at binding maxSpend and defaults nonce to lastNonce + 1", async () => {
+        const conn = mockConn({
+            binding: bindingBytes(2000n, 4n),
+            bondAmount: 500000n,
+            bondReserved: 0n,
+            funded: 100000n,
+            ataExists: true,
+        });
+        const s = await (0, index_1.suggestClaimSpend)(conn, base);
+        strict_1.default.equal(s.nonce, 5n);
+        strict_1.default.equal(s.maxSpend, 2000n);
+        strict_1.default.equal(s.funded, 100000n);
+        strict_1.default.equal(s.claimSpend, 2000n);
+    });
+    (0, node_test_1.it)("caps at funded balance when the claimant is thin", async () => {
+        const conn = mockConn({
+            binding: bindingBytes(2000n, 4n),
+            bondAmount: 500000n,
+            bondReserved: 0n,
+            funded: 500n,
+            ataExists: true,
+        });
+        const s = await (0, index_1.suggestClaimSpend)(conn, base);
+        strict_1.default.equal(s.claimSpend, 500n);
+    });
+    (0, node_test_1.it)("caps at bond capacity floor(free / 3)", async () => {
+        const conn = mockConn({
+            binding: bindingBytes(2000n, 4n),
+            bondAmount: 3000n,
+            bondReserved: 0n,
+            funded: 100000n,
+            ataExists: true,
+        });
+        const s = await (0, index_1.suggestClaimSpend)(conn, base);
+        strict_1.default.equal(s.bondFree, 3000n);
+        strict_1.default.equal(s.bondCap, 1000n);
+        strict_1.default.equal(s.claimSpend, 1000n);
+    });
+    (0, node_test_1.it)("suggests 0 when the ATA is missing (do not open)", async () => {
+        const conn = mockConn({
+            binding: bindingBytes(2000n, 4n),
+            bondAmount: 500000n,
+            bondReserved: 0n,
+            funded: 0n,
+            ataExists: false,
+        });
+        const s = await (0, index_1.suggestClaimSpend)(conn, base);
+        strict_1.default.equal(s.funded, 0n);
+        strict_1.default.equal(s.claimSpend, 0n);
+    });
+    (0, node_test_1.it)("throws on missing binding and passes explicit nonce", async () => {
+        const conn = mockConn({
+            binding: null,
+            bondAmount: 0n,
+            bondReserved: 0n,
+            funded: 0n,
+            ataExists: false,
+        });
+        await strict_1.default.rejects((0, index_1.suggestClaimSpend)(conn, base), /binding/);
+        const conn2 = mockConn({
+            binding: bindingBytes(2000n, 4n),
+            bondAmount: 500000n,
+            bondReserved: 0n,
+            funded: 100000n,
+            ataExists: true,
+        });
+        const s = await (0, index_1.suggestClaimSpend)(conn2, { ...base, nonce: 9n });
+        strict_1.default.equal(s.nonce, 9n);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infantmen-labs/harbor-sdk",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "TypeScript SDK for Harbor bonded refunds on Solana: PDA helpers, instruction builders, receipt codec, ed25519 verify, account decoders.",
   "license": "MIT",
   "keywords": [
@@ -17,6 +17,7 @@
   "types": "dist/src/index.d.ts",
   "scripts": {
     "build": "tsc -p .",
+    "clean": "rm -rf dist",
     "test": "node --test dist/test/vectors.test.js"
   },
   "dependencies": {