@infantmen-labs/harbor-sdk 0.4.4 → 0.6.0

package/README.md

@@ -31,3 +31,28 @@ What it covers: `bondPda` / `bindingPda` / `disputePda` / `receiptPda` /
 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`, plus the close lifecycle `requestCloseIx` / `sealIx` /
+`withdrawPayerIx` / `distributeIx` / `reclaimIx`) live here so buyers
+never reimplement consensus-critical bytes by copy-paste. `vaultAta`,
+`decodeBinding`, and receipt-expiry readers round out the buyer surface.
+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,90 @@
+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;
+/**
+ * Upstream forced-close lifecycle (buyer reclaim path). All no-arg beyond
+ * the discriminator; discriminators from the pinned upstream IDL
+ * (requestClose 5, seal 6, withdrawPayer 8, reclaim 9).
+ *
+ * Reclaim flow: `requestClose` (payer starts grace) → wait past grace →
+ * `seal` → `withdrawPayer` (unspent remainder back to the payer) →
+ * `reclaim` (deallocate channel, rent to rentPayer). Cooperative
+ * alternative: `settleAndSeal` (needs payee signature — not built here).
+ */
+export declare function requestCloseIx(args: {
+    programId: PublicKey;
+    payer: PublicKey;
+    channel: PublicKey;
+}): TransactionInstruction;
+export declare function sealIx(args: {
+    programId: PublicKey;
+    channel: PublicKey;
+}): TransactionInstruction;
+export declare function withdrawPayerIx(args: {
+    programId: PublicKey;
+    payer: PublicKey;
+    channel: PublicKey;
+    channelAta: PublicKey;
+    payerAta: PublicKey;
+    mint: PublicKey;
+}): TransactionInstruction;
+export declare function reclaimIx(args: {
+    programId: PublicKey;
+    channel: PublicKey;
+    rentPayer: PublicKey;
+}): TransactionInstruction;
+/**
+ * Upstream `distribute` with an explicit recipient list (empty = payee
+ * remainder only). Data: disc(7) | count(u32 LE) | entries. The onchain
+ * program rehashes the revealed plan and compares against the commitment
+ * stored at `open` — agent-opened channels commit to the empty plan
+ * (count 0), so empty args verify for them.
+ *
+ * Fixed accounts: channel(mut) | payer | rentPayer(mut) | channelAta(mut)
+ * | payerAta(mut) | payeeAta(mut) | treasuryAta(mut) | mint |
+ * tokenProgram | eventAuthority | selfProgram, then recipient ATAs in plan
+ * order. Permissionless crank: payer is deliberately NOT marked signer
+ * (the upstream docs require payer-side signatures only for topUp,
+ * requestClose and withdrawPayer — the fee payer signs the tx itself).
+ */
+export declare function distributeIx(args: {
+    programId: PublicKey;
+    channel: PublicKey;
+    payer: PublicKey;
+    rentPayer: PublicKey;
+    channelAta: PublicKey;
+    payerAta: PublicKey;
+    payeeAta: PublicKey;
+    treasuryAta: PublicKey;
+    mint: PublicKey;
+    eventAuthority: PublicKey;
+    recipientAtas?: PublicKey[];
+}): 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,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openChannelIx = openChannelIx;
+exports.settleIx = settleIx;
+exports.topUpIx = topUpIx;
+exports.requestCloseIx = requestCloseIx;
+exports.sealIx = sealIx;
+exports.withdrawPayerIx = withdrawPayerIx;
+exports.reclaimIx = reclaimIx;
+exports.distributeIx = distributeIx;
+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)]),
+    });
+}
+/**
+ * Upstream forced-close lifecycle (buyer reclaim path). All no-arg beyond
+ * the discriminator; discriminators from the pinned upstream IDL
+ * (requestClose 5, seal 6, withdrawPayer 8, reclaim 9).
+ *
+ * Reclaim flow: `requestClose` (payer starts grace) → wait past grace →
+ * `seal` → `withdrawPayer` (unspent remainder back to the payer) →
+ * `reclaim` (deallocate channel, rent to rentPayer). Cooperative
+ * alternative: `settleAndSeal` (needs payee signature — not built here).
+ */
+function requestCloseIx(args) {
+    return new web3_js_1.TransactionInstruction({
+        programId: args.programId,
+        keys: [m(args.payer, false, true), m(args.channel, true, false)],
+        data: Buffer.from([5]),
+    });
+}
+function sealIx(args) {
+    return new web3_js_1.TransactionInstruction({
+        programId: args.programId,
+        keys: [m(args.channel, true, false)],
+        data: Buffer.from([6]),
+    });
+}
+function withdrawPayerIx(args) {
+    return new web3_js_1.TransactionInstruction({
+        programId: args.programId,
+        keys: [
+            m(args.payer, false, true),
+            m(args.channel, true, false),
+            m(args.channelAta, true, false),
+            m(args.payerAta, true, false),
+            m(args.mint, false, false),
+            m(ids_1.TOKEN_PROGRAM_ID, false, false),
+        ],
+        data: Buffer.from([8]),
+    });
+}
+function reclaimIx(args) {
+    return new web3_js_1.TransactionInstruction({
+        programId: args.programId,
+        keys: [m(args.channel, true, false), m(args.rentPayer, true, false)],
+        data: Buffer.from([9]),
+    });
+}
+/**
+ * Upstream `distribute` with an explicit recipient list (empty = payee
+ * remainder only). Data: disc(7) | count(u32 LE) | entries. The onchain
+ * program rehashes the revealed plan and compares against the commitment
+ * stored at `open` — agent-opened channels commit to the empty plan
+ * (count 0), so empty args verify for them.
+ *
+ * Fixed accounts: channel(mut) | payer | rentPayer(mut) | channelAta(mut)
+ * | payerAta(mut) | payeeAta(mut) | treasuryAta(mut) | mint |
+ * tokenProgram | eventAuthority | selfProgram, then recipient ATAs in plan
+ * order. Permissionless crank: payer is deliberately NOT marked signer
+ * (the upstream docs require payer-side signatures only for topUp,
+ * requestClose and withdrawPayer — the fee payer signs the tx itself).
+ */
+function distributeIx(args) {
+    const data = Buffer.concat([Buffer.from([7]), u32(0)]);
+    return new web3_js_1.TransactionInstruction({
+        programId: args.programId,
+        keys: [
+            m(args.channel, true, false),
+            m(args.payer, false, false),
+            m(args.rentPayer, true, false),
+            m(args.channelAta, true, false),
+            m(args.payerAta, true, false),
+            m(args.payeeAta, true, false),
+            m(args.treasuryAta, true, false),
+            m(args.mint, false, false),
+            m(ids_1.TOKEN_PROGRAM_ID, false, false),
+            m(args.eventAuthority, false, false),
+            m(args.programId, false, false),
+            ...(args.recipientAtas ?? []).map((a) => m(a, true, false)),
+        ],
+        data,
+    });
+}
+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/harbor-ix.d.ts

@@ -16,5 +16,11 @@ export interface SubmitReceiptArgs {
 }
 export declare function submitReceiptIx(programId: PublicKey, merchant: PublicKey, bond: PublicKey, binding: PublicKey, receipt: PublicKey, args: SubmitReceiptArgs): TransactionInstruction;
 export declare function openDisputeIx(programId: PublicKey, claimant: PublicKey, bond: PublicKey, binding: PublicKey, channel: PublicKey, dispute: PublicKey, claim: PublicKey, mint: PublicKey, claimantAta: PublicKey, vault: PublicKey, nonce: bigint, reason: number, claimSpend: bigint): TransactionInstruction;
+/**
+ * Closes an EMPTY bond (amount == 0, no open disputes) and its empty
+ * vault. Discriminator already tabled above (method-validated against
+ * submit_receipt); accounts mirror RefundUnused in the program.
+ */
+export declare function refundUnusedIx(programId: PublicKey, merchant: PublicKey, bond: PublicKey, mint: PublicKey, vault: PublicKey, merchantAta: PublicKey): TransactionInstruction;
 export declare function haltBindingIx(programId: PublicKey, merchant: PublicKey, binding: PublicKey): TransactionInstruction;
 export declare function resolveTimeoutIx(programId: PublicKey, resolver: PublicKey, bond: PublicKey, mint: PublicKey, binding: PublicKey, dispute: PublicKey, claimant: PublicKey, treasury: PublicKey, vault: PublicKey, treasuryAta: PublicKey, claimantAta: PublicKey, nonce: bigint): TransactionInstruction;

package/dist/src/harbor-ix.js

@@ -8,6 +8,7 @@ exports.withdrawTreasuryIx = withdrawTreasuryIx;
 exports.bindChannelIx = bindChannelIx;
 exports.submitReceiptIx = submitReceiptIx;
 exports.openDisputeIx = openDisputeIx;
+exports.refundUnusedIx = refundUnusedIx;
 exports.haltBindingIx = haltBindingIx;
 exports.resolveTimeoutIx = resolveTimeoutIx;
 const web3_js_1 = require("@solana/web3.js");
@@ -151,6 +152,21 @@ function openDisputeIx(programId, claimant, bond, binding, channel, dispute, cla
         { key: ids_1.SYSTEM_PROGRAM_ID },
     ]);
 }
+/**
+ * Closes an EMPTY bond (amount == 0, no open disputes) and its empty
+ * vault. Discriminator already tabled above (method-validated against
+ * submit_receipt); accounts mirror RefundUnused in the program.
+ */
+function refundUnusedIx(programId, merchant, bond, mint, vault, merchantAta) {
+    return keys(programId, D.refundUnused, Buffer.alloc(0), [
+        { key: merchant, w: true, s: true },
+        { key: bond, w: true },
+        { key: mint },
+        { key: vault, w: true },
+        { key: merchantAta, w: true },
+        { key: ids_1.TOKEN_PROGRAM_ID, w: false },
+    ]);
+}
 function haltBindingIx(programId, merchant, binding) {
     return keys(programId, D.haltBinding, Buffer.alloc(0), [
         { key: merchant, w: true, s: true },

package/dist/src/index.d.ts

@@ -4,6 +4,8 @@ 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

@@ -20,6 +20,8 @@ __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,8 @@ 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;
+/** Bond vault: the canonical ATA of the bond PDA (holds collateral). */
+export declare function vaultAta(bond: 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.vaultAta = vaultAta;
 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);
@@ -46,6 +49,14 @@ 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];
+}
+/** Bond vault: the canonical ATA of the bond PDA (holds collateral). */
+function vaultAta(bond, mint) {
+    return ataFor(bond, mint);
+}
 function channelAta(channel, tokenProgram, mint, ataProgram) {
     return web3_js_1.PublicKey.findProgramAddressSync([channel.toBuffer(), tokenProgram.toBuffer(), mint.toBuffer()], ataProgram);
 }

package/dist/src/receipt.d.ts

@@ -13,3 +13,17 @@ export interface ReceiptFields {
 /** Borsh encoding of the onchain ReceiptMessage. Field order is consensus. */
 export declare function receiptMessageBytes(f: ReceiptFields): Buffer;
 export declare const RECEIPT_MESSAGE_LEN = 185;
+/**
+ * Byte offset of expirySlot in the 185-byte receipt message
+ * (merchant 32 | binding 32 | cumulative 8 | meter 32 | output 32 |
+ * status 1 | nonce 8 | expiry 8 | signer 32).
+ */
+export declare const RECEIPT_EXPIRY_OFFSET = 145;
+/** Reads the expiry slot from encoded receipt message bytes. */
+export declare function receiptExpirySlot(message: Uint8Array): bigint;
+/**
+ * Buyer-side expiry check: a receipt is expired once the chain passes its
+ * expiry slot (mirrors the onchain `slot <= expiry_slot` gate in
+ * submit_receipt — expired receipts fail submit with `Expired`).
+ */
+export declare function isReceiptExpired(message: Uint8Array, slot: bigint | number): boolean;

package/dist/src/receipt.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RECEIPT_MESSAGE_LEN = void 0;
+exports.RECEIPT_EXPIRY_OFFSET = exports.RECEIPT_MESSAGE_LEN = void 0;
 exports.receiptMessageBytes = receiptMessageBytes;
+exports.receiptExpirySlot = receiptExpirySlot;
+exports.isReceiptExpired = isReceiptExpired;
 const u64_1 = require("./u64");
 function assertLen(b, n, name) {
     if (b.length !== n)
@@ -34,3 +36,25 @@ function receiptMessageBytes(f) {
     return out;
 }
 exports.RECEIPT_MESSAGE_LEN = 185;
+/**
+ * Byte offset of expirySlot in the 185-byte receipt message
+ * (merchant 32 | binding 32 | cumulative 8 | meter 32 | output 32 |
+ * status 1 | nonce 8 | expiry 8 | signer 32).
+ */
+exports.RECEIPT_EXPIRY_OFFSET = 145;
+/** Reads the expiry slot from encoded receipt message bytes. */
+function receiptExpirySlot(message) {
+    let v = 0n;
+    for (let i = 0; i < 8; i++) {
+        v |= BigInt(message[exports.RECEIPT_EXPIRY_OFFSET + i]) << BigInt(i * 8);
+    }
+    return v;
+}
+/**
+ * Buyer-side expiry check: a receipt is expired once the chain passes its
+ * expiry slot (mirrors the onchain `slot <= expiry_slot` gate in
+ * submit_receipt — expired receipts fail submit with `Expired`).
+ */
+function isReceiptExpired(message, slot) {
+    return BigInt(slot) > receiptExpirySlot(message);
+}

package/dist/test/vectors.test.js

@@ -212,3 +212,313 @@ const P = (n) => new web3_js_1.PublicKey(Buffer.alloc(32, n));
         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);
+    });
+});
+(0, node_test_1.describe)("upstream close lifecycle builders", () => {
+    const PROGRAM = P(1);
+    (0, node_test_1.it)("requestClose carries disc 5 with payer signer + channel", () => {
+        const ix = (0, index_1.requestCloseIx)({
+            programId: PROGRAM,
+            payer: P(2),
+            channel: P(6),
+        });
+        strict_1.default.deepEqual(Array.from(ix.data), [5]);
+        strict_1.default.equal(ix.keys.length, 2);
+        strict_1.default.equal(ix.keys[0]?.isSigner, true);
+    });
+    (0, node_test_1.it)("seal carries disc 6 with channel only", () => {
+        const ix = (0, index_1.sealIx)({ programId: PROGRAM, channel: P(6) });
+        strict_1.default.deepEqual(Array.from(ix.data), [6]);
+        strict_1.default.equal(ix.keys.length, 1);
+    });
+    (0, node_test_1.it)("withdrawPayer carries disc 8 with 6 accounts", () => {
+        const ix = (0, index_1.withdrawPayerIx)({
+            programId: PROGRAM,
+            payer: P(2),
+            channel: P(6),
+            channelAta: P(8),
+            payerAta: P(7),
+            mint: P(4),
+        });
+        strict_1.default.deepEqual(Array.from(ix.data), [8]);
+        strict_1.default.equal(ix.keys.length, 6);
+        strict_1.default.equal(ix.keys[0]?.isSigner, true);
+    });
+    (0, node_test_1.it)("reclaim carries disc 9 with channel + rentPayer", () => {
+        const ix = (0, index_1.reclaimIx)({
+            programId: PROGRAM,
+            channel: P(6),
+            rentPayer: P(2),
+        });
+        strict_1.default.deepEqual(Array.from(ix.data), [9]);
+        strict_1.default.equal(ix.keys.length, 2);
+    });
+});
+(0, node_test_1.describe)("receipt expiry readers", () => {
+    const F = {
+        merchant: P(1),
+        binding: P(2),
+        cumulativeSpend: 10000n,
+        meterHash: new Uint8Array(32).fill(3),
+        outputHash: new Uint8Array(32).fill(4),
+        status: 0,
+        nonce: 7n,
+        expirySlot: 999n,
+        signer: P(1),
+    };
+    (0, node_test_1.it)("reads back the encoded expiry slot", () => {
+        const msg = (0, index_1.receiptMessageBytes)(F);
+        strict_1.default.equal((0, index_1.receiptExpirySlot)(msg), 999n);
+    });
+    (0, node_test_1.it)("expires strictly past the slot (mirrors onchain <= gate)", () => {
+        const msg = (0, index_1.receiptMessageBytes)(F);
+        strict_1.default.equal((0, index_1.isReceiptExpired)(msg, 998), false);
+        strict_1.default.equal((0, index_1.isReceiptExpired)(msg, 999), false);
+        strict_1.default.equal((0, index_1.isReceiptExpired)(msg, 1000), true);
+    });
+});
+(0, node_test_1.describe)("refundUnusedIx", () => {
+    (0, node_test_1.it)("carries the tabled discriminator with 6 accounts", () => {
+        const ix = (0, index_1.refundUnusedIx)(P(0), P(1), P(2), P(3), P(4), P(5));
+        strict_1.default.deepEqual(Array.from(ix.data), [239, 108, 1, 110, 2, 81, 44, 174]);
+        strict_1.default.equal(ix.keys.length, 6);
+        strict_1.default.equal(ix.keys[0]?.isSigner, true);
+    });
+});
+(0, node_test_1.describe)("distributeIx (empty plan)", () => {
+    (0, node_test_1.it)("encodes disc 7 + zero count with 11 fixed accounts, no signers", () => {
+        const ix = (0, index_1.distributeIx)({
+            programId: P(1),
+            channel: P(6),
+            payer: P(2),
+            rentPayer: P(2),
+            channelAta: P(8),
+            payerAta: P(7),
+            payeeAta: P(10),
+            treasuryAta: P(11),
+            mint: P(4),
+            eventAuthority: P(9),
+        });
+        strict_1.default.deepEqual(Array.from(ix.data), [7, 0, 0, 0, 0]);
+        strict_1.default.equal(ix.keys.length, 11);
+        strict_1.default.ok(ix.keys.every((k) => k.isSigner === false));
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infantmen-labs/harbor-sdk",
-  "version": "0.4.4",
+  "version": "0.6.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": {