@infantmen-labs/harbor-sdk 0.4.1 → 0.4.4

package/README.md

@@ -0,0 +1,33 @@
+# 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.

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,8 @@ export * from "./ids";
 export * from "./pda";
 export * from "./accounts";
 export * from "./receipt";
+export * from "./tx";
+export * from "./u64";
 export * from "./ed25519";
 export * from "./verify";
 export * from "./harbor-ix";

package/dist/src/index.js

@@ -18,6 +18,8 @@ __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("./ed25519"), exports);
 __exportStar(require("./verify"), exports);
 __exportStar(require("./harbor-ix"), exports);

package/dist/src/pda.js

@@ -10,6 +10,7 @@ exports.channelPda = channelPda;
 exports.channelAta = channelAta;
 const web3_js_1 = require("@solana/web3.js");
 const ids_1 = 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 +18,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 +30,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(),

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,74 @@ 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);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infantmen-labs/harbor-sdk",
-  "version": "0.4.1",
+  "version": "0.4.4",
   "description": "TypeScript SDK for Harbor bonded refunds on Solana: PDA helpers, instruction builders, receipt codec, ed25519 verify, account decoders.",
   "license": "MIT",
   "keywords": [