@infantmen-labs/harbor-sdk 0.5.0 → 0.6.0

package/README.md

@@ -35,8 +35,11 @@ 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:
+`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

package/dist/src/channels.d.ts

@@ -26,6 +26,65 @@ export declare function topUpIx(args: {
     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

@@ -3,6 +3,11 @@ 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");
@@ -75,6 +80,86 @@ function topUpIx(args) {
         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/pda.d.ts

@@ -9,4 +9,6 @@ export declare function claimPda(binding: PublicKey, nonce: bigint): [PublicKey,
 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

@@ -8,6 +8,7 @@ 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");
@@ -52,6 +53,10 @@ function channelPda(channelProgram, payer, payee, mint, authorizedSigner, salt,
 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

@@ -432,3 +432,93 @@ const P = (n) => new web3_js_1.PublicKey(Buffer.alloc(32, n));
         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.5.0",
+  "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": [