@oobe-protocol-labs/synapse-sap-sdk 0.14.0 → 0.15.0

package/dist/esm/utils/x402-direct.js

@@ -0,0 +1,228 @@
+/**
+ * @module utils/x402-direct
+ * @description Recognize x402 direct SPL token payments on an agent's ATA
+ * by scanning transaction history and filtering for x402 patterns.
+ *
+ * @category Utils
+ * @since v0.6.4
+ */
+import { PublicKey, } from "@solana/web3.js";
+import { sha256 } from "../utils";
+// ═══════════════════════════════════════════════════════════════════
+//  Core
+// ═══════════════════════════════════════════════════════════════════
+/** Recognized x402 memo prefixes. */
+const X402_MEMO_PREFIXES = ["x402:", "SAP-x402:", "x402-direct:"];
+/**
+ * @name extractSplTransfer
+ * @description Extract SPL Token transfer details from a parsed transaction.
+ *
+ * Looks for `transfer` or `transferChecked` inner instructions on the
+ * Token Program and returns source/dest/amount/mint.
+ *
+ * @internal
+ */
+function extractSplTransfer(tx, payToAta) {
+    if (!tx.meta?.innerInstructions && !tx.transaction.message.instructions) {
+        return null;
+    }
+    // Check all instructions (outer + inner)
+    const allIxs = [
+        ...tx.transaction.message.instructions,
+        ...(tx.meta?.innerInstructions?.flatMap((g) => g.instructions) ?? []),
+    ];
+    for (const ix of allIxs) {
+        // Only process parsed instructions with known program
+        if (!("parsed" in ix) || !("program" in ix))
+            continue;
+        const parsed = ix;
+        if (parsed.program !== "spl-token")
+            continue;
+        const info = parsed.parsed;
+        if (info.type !== "transfer" &&
+            info.type !== "transferChecked") {
+            continue;
+        }
+        const transferInfo = info.info;
+        if (!transferInfo?.source || !transferInfo?.destination)
+            continue;
+        // Check destination matches our payTo ATA
+        const destPk = new PublicKey(transferInfo.destination);
+        if (!destPk.equals(payToAta))
+            continue;
+        const amountStr = transferInfo.amount ?? transferInfo.tokenAmount?.amount ?? "0";
+        return {
+            amount: BigInt(amountStr),
+            source: new PublicKey(transferInfo.source),
+            destination: destPk,
+            mint: transferInfo.mint ? new PublicKey(transferInfo.mint) : destPk, // fallback
+        };
+    }
+    return null;
+}
+/**
+ * @name extractMemo
+ * @description Extract memo data from a parsed transaction.
+ * @internal
+ */
+function extractMemo(tx) {
+    const allIxs = [
+        ...tx.transaction.message.instructions,
+        ...(tx.meta?.innerInstructions?.flatMap((g) => g.instructions) ?? []),
+    ];
+    for (const ix of allIxs) {
+        if (!("parsed" in ix) || !("program" in ix))
+            continue;
+        const parsed = ix;
+        if (parsed.program === "spl-memo" && typeof parsed.parsed === "string") {
+            return parsed.parsed;
+        }
+    }
+    // Also check log messages for memo
+    if (tx.meta?.logMessages) {
+        for (const log of tx.meta.logMessages) {
+            if (log.startsWith("Program log: Memo")) {
+                const memoMatch = log.match(/Memo \(len \d+\): "(.*?)"/);
+                if (memoMatch?.[1])
+                    return memoMatch[1];
+            }
+        }
+    }
+    return null;
+}
+/**
+ * @name matchesX402Pattern
+ * @description Check if a transfer matches an x402 payment pattern.
+ *
+ * Matches if:
+ * - A memo with recognized x402 prefix is present, OR
+ * - The transfer matches a known settlement payload (deterministic hash), OR
+ * - `requireMemo` is false (any SPL transfer to the ATA is included)
+ *
+ * @internal
+ */
+function matchesX402Pattern(transfer, memo, knownSettlements, requireMemo) {
+    // 1. Check memo prefix
+    if (memo) {
+        for (const prefix of X402_MEMO_PREFIXES) {
+            if (memo.startsWith(prefix))
+                return true;
+        }
+        // Try base64 JSON parse for embedded x402 payload
+        try {
+            const decoded = Buffer.from(memo, "base64").toString("utf-8");
+            const parsed = JSON.parse(decoded);
+            if (parsed.protocol === "x402" || parsed.protocol === "SAP-x402") {
+                return true;
+            }
+        }
+        catch {
+            // Not base64 JSON — ignore
+        }
+    }
+    // 2. Match against known settlements (deterministic hash)
+    for (const settlement of knownSettlements) {
+        const expected = BigInt(settlement.amount);
+        if (transfer.amount !== expected)
+            continue;
+        // Deterministic hash: sha256(agentWallet + depositor + amount + timestamp)
+        const hashInput = settlement.agentWallet +
+            settlement.depositorWallet +
+            settlement.amount +
+            settlement.timestamp.toString();
+        const expectedHash = Buffer.from(sha256(hashInput)).toString("hex");
+        const serviceHash = settlement.serviceHash;
+        if (expectedHash === serviceHash)
+            return settlement;
+    }
+    // 3. If requireMemo is false, accept any SPL transfer to the ATA
+    if (!requireMemo)
+        return true;
+    return false;
+}
+/**
+ * @name getX402DirectPayments
+ * @description Scan an agent's ATA for x402 direct payments.
+ *
+ * Fetches recent transaction signatures for the given `payTo` ATA,
+ * inspects each transaction for SPL token transfers, and filters
+ * for x402 payment patterns (memo prefix, settlement hash match, etc.).
+ *
+ * @param connection - Solana RPC connection.
+ * @param payToAta   - The agent's receiving ATA (e.g. USDC ATA of Syra).
+ * @param opts       - Filter and pagination options.
+ * @returns Array of recognized x402 direct payments, newest first.
+ *
+ * @category Utils
+ * @since v0.6.4
+ *
+ * @example
+ * ```ts
+ * import { getX402DirectPayments, findATA } from "@oobe-protocol-labs/synapse-sap-sdk";
+ *
+ * const USDC_MINT = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
+ * const payToAta = findATA(agentWallet, USDC_MINT);
+ *
+ * const payments = await getX402DirectPayments(connection, payToAta, {
+ *   limit: 50,
+ *   knownSettlements: savedSettlements, // from your API PAYMENT-RESPONSE logs
+ * });
+ *
+ * for (const p of payments) {
+ *   console.log(`${p.signature}: ${p.amount} from ${p.payerAta.toBase58()}`);
+ *   if (p.settlement) {
+ *     console.log(`  Matched settlement: ${p.settlement.serviceHash}`);
+ *   }
+ * }
+ * ```
+ */
+export async function getX402DirectPayments(connection, payToAta, opts) {
+    const limit = opts?.limit ?? 100;
+    const knownSettlements = opts?.knownSettlements ?? [];
+    const requireMemo = opts?.requireMemo ?? false;
+    // 1. Fetch signatures
+    const sigOpts = { limit };
+    if (opts?.before)
+        sigOpts.before = opts.before;
+    if (opts?.until)
+        sigOpts.until = opts.until;
+    const sigs = await connection.getSignaturesForAddress(payToAta, sigOpts);
+    if (sigs.length === 0)
+        return [];
+    // 2. Fetch transactions (batch with getParsedTransactions if available)
+    const txs = await connection.getParsedTransactions(sigs.map((s) => s.signature), { maxSupportedTransactionVersion: 0 });
+    // 3. Extract and filter
+    const results = [];
+    for (let i = 0; i < txs.length; i++) {
+        const tx = txs[i];
+        if (!tx)
+            continue;
+        // Extract SPL transfer to our ATA
+        const transfer = extractSplTransfer(tx, payToAta);
+        if (!transfer)
+            continue;
+        // Filter by payer if specified
+        if (opts?.filterPayer && !transfer.source.equals(opts.filterPayer)) {
+            continue;
+        }
+        // Extract memo
+        const memo = extractMemo(tx);
+        // Match x402 pattern
+        const match = matchesX402Pattern(transfer, memo, knownSettlements, requireMemo);
+        if (match === false)
+            continue;
+        results.push({
+            signature: sigs[i].signature,
+            amount: transfer.amount,
+            payerAta: transfer.source,
+            payeeAta: transfer.destination,
+            mint: transfer.mint,
+            memo,
+            settlement: typeof match === "object" ? match : null,
+            blockTime: tx.blockTime ?? null,
+            slot: tx.slot,
+        });
+    }
+    return results;
+}
+//# sourceMappingURL=x402-direct.js.map

package/dist/esm/utils/x402-direct.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-direct.js","sourceRoot":"","sources":["../../../src/utils/x402-direct.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEL,SAAS,GAGV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AA4ElC,sEAAsE;AACtE,QAAQ;AACR,sEAAsE;AAEtE,qCAAqC;AACrC,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC;AAElE;;;;;;;;GAQG;AACH,SAAS,kBAAkB,CACzB,EAA6B,EAC7B,QAAmB;IAOnB,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,iBAAiB,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;QACxE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,yCAAyC;IACzC,MAAM,MAAM,GAAG;QACb,GAAG,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,YAAY;QACtC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC;KACtE,CAAC;IAEF,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;QACxB,sDAAsD;QACtD,IAAI,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC;YAAE,SAAS;QACtD,MAAM,MAAM,GAAG,EAA0D,CAAC;QAE1E,IAAI,MAAM,CAAC,OAAO,KAAK,WAAW;YAAE,SAAS;QAE7C,MAAM,IAAI,GAAG,MAAM,CAAC,MAUnB,CAAC;QAEF,IACE,IAAI,CAAC,IAAI,KAAK,UAAU;YACxB,IAAI,CAAC,IAAI,KAAK,iBAAiB,EAC/B,CAAC;YACD,SAAS;QACX,CAAC;QAED,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC;QAC/B,IAAI,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC,YAAY,EAAE,WAAW;YAAE,SAAS;QAElE,0CAA0C;QAC1C,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC;YAAE,SAAS;QAEvC,MAAM,SAAS,GACb,YAAY,CAAC,MAAM,IAAI,YAAY,CAAC,WAAW,EAAE,MAAM,IAAI,GAAG,CAAC;QAEjE,OAAO;YACL,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC;YACzB,MAAM,EAAE,IAAI,SAAS,CAAC,YAAY,CAAC,MAAM,CAAC;YAC1C,WAAW,EAAE,MAAM;YACnB,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,WAAW;SACjF,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,EAA6B;IAChD,MAAM,MAAM,GAAG;QACb,GAAG,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,YAAY;QACtC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC;KACtE,CAAC;IAEF,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;QACxB,IAAI,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC;YAAE,SAAS;QACtD,MAAM,MAAM,GAAG,EAA0C,CAAC;QAC1D,IAAI,MAAM,CAAC,OAAO,KAAK,UAAU,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YACvE,OAAO,MAAM,CAAC,MAAM,CAAC;QACvB,CAAC;IACH,CAAC;IAED,mCAAmC;IACnC,IAAI,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,CAAC;QACzB,KAAK,MAAM,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtC,IAAI,GAAG,CAAC,UAAU,CAAC,mBAAmB,CAAC,EAAE,CAAC;gBACxC,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;gBACzD,IAAI,SAAS,EAAE,CAAC,CAAC,CAAC;oBAAE,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,kBAAkB,CACzB,QAA+C,EAC/C,IAAmB,EACnB,gBAAqC,EACrC,WAAoB;IAEpB,uBAAuB;IACvB,IAAI,IAAI,EAAE,CAAC;QACT,KAAK,MAAM,MAAM,IAAI,kBAAkB,EAAE,CAAC;YACxC,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;gBAAE,OAAO,IAAI,CAAC;QAC3C,CAAC;QACD,kDAAkD;QAClD,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YAC9D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACnC,IAAI,MAAM,CAAC,QAAQ,KAAK,MAAM,IAAI,MAAM,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;gBACjE,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,2BAA2B;QAC7B,CAAC;IACH,CAAC;IAED,0DAA0D;IAC1D,KAAK,MAAM,UAAU,IAAI,gBAAgB,EAAE,CAAC;QAC1C,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAC3C,IAAI,QAAQ,CAAC,MAAM,KAAK,QAAQ;YAAE,SAAS;QAE3C,2EAA2E;QAC3E,MAAM,SAAS,GACb,UAAU,CAAC,WAAW;YACtB,UAAU,CAAC,eAAe;YAC1B,UAAU,CAAC,MAAM;YACjB,UAAU,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC;QAClC,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACpE,MAAM,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC;QAE3C,IAAI,YAAY,KAAK,WAAW;YAAE,OAAO,UAAU,CAAC;IACtD,CAAC;IAED,iEAAiE;IACjE,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAE9B,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,UAAsB,EACtB,QAAmB,EACnB,IAA2B;IAE3B,MAAM,KAAK,GAAG,IAAI,EAAE,KAAK,IAAI,GAAG,CAAC;IACjC,MAAM,gBAAgB,GAAG,IAAI,EAAE,gBAAgB,IAAI,EAAE,CAAC;IACtD,MAAM,WAAW,GAAG,IAAI,EAAE,WAAW,IAAI,KAAK,CAAC;IAE/C,sBAAsB;IACtB,MAAM,OAAO,GAIT,EAAE,KAAK,EAAE,CAAC;IACd,IAAI,IAAI,EAAE,MAAM;QAAE,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC/C,IAAI,IAAI,EAAE,KAAK;QAAE,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAE5C,MAAM,IAAI,GACR,MAAM,UAAU,CAAC,uBAAuB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAE9D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEjC,wEAAwE;IACxE,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,qBAAqB,CAChD,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,EAC5B,EAAE,8BAA8B,EAAE,CAAC,EAAE,CACtC,CAAC;IAEF,wBAAwB;IACxB,MAAM,OAAO,GAAwB,EAAE,CAAC;IAExC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,EAAE;YAAE,SAAS;QAElB,kCAAkC;QAClC,MAAM,QAAQ,GAAG,kBAAkB,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;QAClD,IAAI,CAAC,QAAQ;YAAE,SAAS;QAExB,+BAA+B;QAC/B,IAAI,IAAI,EAAE,WAAW,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;YACnE,SAAS;QACX,CAAC;QAED,eAAe;QACf,MAAM,IAAI,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;QAE7B,qBAAqB;QACrB,MAAM,KAAK,GAAG,kBAAkB,CAC9B,QAAQ,EACR,IAAI,EACJ,gBAAgB,EAChB,WAAW,CACZ,CAAC;QACF,IAAI,KAAK,KAAK,KAAK;YAAE,SAAS;QAE9B,OAAO,CAAC,IAAI,CAAC;YACX,SAAS,EAAE,IAAI,CAAC,CAAC,CAAE,CAAC,SAAS;YAC7B,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,QAAQ,EAAE,QAAQ,CAAC,MAAM;YACzB,QAAQ,EAAE,QAAQ,CAAC,WAAW;YAC9B,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,IAAI;YACJ,UAAU,EAAE,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI;YACpD,SAAS,EAAE,EAAE,CAAC,SAAS,IAAI,IAAI;YAC/B,IAAI,EAAE,EAAE,CAAC,IAAI;SACd,CAAC,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/types/constants/addresses.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @module constants/addresses
+ * @description Pre-computed mainnet addresses for singleton PDAs and protocol infrastructure.
+ *
+ * These addresses are deterministic — derived from the canonical program ID
+ * and fixed seeds. They are provided for convenience so consumers can
+ * reference well-known accounts without re-deriving them.
+ *
+ * @category Constants
+ * @since v0.3.1
+ */
+import { PublicKey } from "@solana/web3.js";
+/**
+ * SAP v2 program ID on mainnet-beta (base58).
+ *
+ * @name SAP_PROGRAM
+ * @description The deployed and verified SAP v2 program address.
+ * @category Constants
+ * @since v0.3.1
+ */
+export declare const SAP_PROGRAM: PublicKey;
+/**
+ * Upgrade authority for the SAP v2 program.
+ *
+ * @name SAP_UPGRADE_AUTHORITY
+ * @description The wallet that holds upgrade authority over the deployed program.
+ * @category Constants
+ * @since v0.3.1
+ */
+export declare const SAP_UPGRADE_AUTHORITY: PublicKey;
+/**
+ * **GlobalRegistry** PDA — the protocol singleton.
+ *
+ * Seeds: `["sap_global"]` · Bump: `255`
+ *
+ * Tracks total agent count, active agent count, and protocol-level
+ * counters. Must be initialized once before any agent can register.
+ *
+ * @name GLOBAL_REGISTRY_ADDRESS
+ * @category Constants
+ * @since v0.3.1
+ */
+export declare const GLOBAL_REGISTRY_ADDRESS: PublicKey;
+/**
+ * Bump seed for the GlobalRegistry PDA.
+ * @name GLOBAL_REGISTRY_BUMP
+ * @category Constants
+ * @since v0.3.1
+ */
+export declare const GLOBAL_REGISTRY_BUMP = 255;
+/**
+ * IDL metadata account derived via the `program-metadata` standard.
+ *
+ * Seeds: `["idl", program_id]` under `pmetaypqG6SiB47xMigYVMAkuHDWeSDXcv3zzDrJJvA`.
+ *
+ * Contains the Anchor IDL JSON, queryable by explorers like Solscan.
+ *
+ * @name IDL_ACCOUNT_ADDRESS
+ * @category Constants
+ * @since v0.3.1
+ */
+export declare const IDL_ACCOUNT_ADDRESS: PublicKey;
+/**
+ * The `program-metadata` program used to store the IDL.
+ *
+ * @name PROGRAM_METADATA_PROGRAM
+ * @category Constants
+ * @since v0.3.1
+ */
+export declare const PROGRAM_METADATA_PROGRAM: PublicKey;
+/**
+ * Pre-computed Tool Category Index PDAs for each `ToolCategory` variant.
+ *
+ * Seeds: `["sap_tool_cat", category_byte]`
+ *
+ * Each entry corresponds to a `ToolCategory` enum discriminant:
+ *
+ * | Index | Category   | Address                                            |
+ * |-------|------------|----------------------------------------------------|
+ * | 0     | Swap       | `5H8yn9RuRgZWqkDiWbKNaCHzTMjqSpwbNQKMPLtUXx2G`   |
+ * | 1     | Lend       | `5Lqqk6VtFWnYq3h4Ae4FuUAKnFzw1Nm1DaSdt2cjcTDj`   |
+ * | 2     | Stake      | `kC8oAiVUcFMXEnmMNu1h2sdAc3dWKcwV5qVKRFYMmQD`    |
+ * | 3     | Nft        | `2zNWR9J3znvGQ5J6xDfJyZkd12Gi66mjErRDkgPeKbyF`   |
+ * | 4     | Payment    | `Eh7MwxJYWRN8bzAmY3ZPTRXYjWpWypokBf1STixu2dy9`   |
+ * | 5     | Data       | `AwpVxehQUZCVTAJ9icZfS6oRbF66jNo32duXaL11B5df`   |
+ * | 6     | Governance | `2573WjZzV9QtbqtM6Z86YGivkk1kdvJa4gK3tZRQ2jkN`   |
+ * | 7     | Bridge     | `664nyr6kBeeFiE1ij5gtdncNCVHrXqrk2uBhnKmUREvK`   |
+ * | 8     | Analytics  | `4DFsiTZ6h6RoCZuUeMTpaoQguepnPUMJBLJuwwjKg5GL`   |
+ * | 9     | Custom     | `3Nk5dvFWEyWPEArdG9cCdab6C6ym36mSWUSB8HzN35ZM`   |
+ *
+ * @name TOOL_CATEGORY_ADDRESSES
+ * @category Constants
+ * @since v0.3.1
+ */
+export declare const TOOL_CATEGORY_ADDRESSES: {
+    readonly Swap: PublicKey;
+    readonly Lend: PublicKey;
+    readonly Stake: PublicKey;
+    readonly Nft: PublicKey;
+    readonly Payment: PublicKey;
+    readonly Data: PublicKey;
+    readonly Governance: PublicKey;
+    readonly Bridge: PublicKey;
+    readonly Analytics: PublicKey;
+    readonly Custom: PublicKey;
+};
+/**
+ * Array-indexed version of {@link TOOL_CATEGORY_ADDRESSES}.
+ *
+ * `TOOL_CATEGORY_ADDRESS_LIST[0]` = Swap, `[1]` = Lend, etc.
+ *
+ * @name TOOL_CATEGORY_ADDRESS_LIST
+ * @category Constants
+ * @since v0.3.1
+ */
+export declare const TOOL_CATEGORY_ADDRESS_LIST: readonly PublicKey[];
+//# sourceMappingURL=addresses.d.ts.map

package/dist/types/constants/addresses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addresses.d.ts","sourceRoot":"","sources":["../../../src/constants/addresses.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAM5C;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,WAEvB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,WAEjC,CAAC;AAMF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,WAEnC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAMxC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,WAE/B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,WAEpC,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;CAW1B,CAAC;AAEX;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,SAAS,EAWjD,CAAC"}

package/dist/types/constants/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @module constants
+ * @description Protocol constants mirroring the on-chain Rust program.
+ *
+ * Organized into:
+ * - **programs** — Network-specific program IDs
+ * - **seeds** — PDA seed prefix strings
+ * - **limits** — Size constraints, versions, enum numeric values
+ *
+ * @category Constants
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import {
+ *   MAINNET_SAP_PROGRAM_ID,
+ *   DEVNET_SAP_PROGRAM_ID,
+ *   SEEDS,
+ *   LIMITS,
+ * } from "@synapse-sap/sdk/constants";
+ * ```
+ */
+export { SAP_PROGRAM_ADDRESS, MAINNET_SAP_PROGRAM_ID, DEVNET_SAP_PROGRAM_ID, LOCALNET_SAP_PROGRAM_ID, SAP_PROGRAM_ID, } from "./programs";
+export { SEEDS } from "./seeds";
+export type { SeedKey } from "./seeds";
+export { LIMITS, AGENT_VERSION, VAULT_PROTOCOL_VERSION, TOOL_CATEGORY_VALUES, HTTP_METHOD_VALUES, } from "./limits";
+export { SapNetwork } from "./network";
+export type { SapNetworkId } from "./network";
+export { SAP_PROGRAM, SAP_UPGRADE_AUTHORITY, GLOBAL_REGISTRY_ADDRESS, GLOBAL_REGISTRY_BUMP, IDL_ACCOUNT_ADDRESS, PROGRAM_METADATA_PROGRAM, TOOL_CATEGORY_ADDRESSES, TOOL_CATEGORY_ADDRESS_LIST, } from "./addresses";
+export { USDC_MINT_MAINNET, USDC_MINT_DEVNET, MIN_AGENT_STAKE_LAMPORTS, MAX_DELEGATE_DURATION_SECS, isAcceptedUsdcMint, isAcceptedPaymentToken, } from "./payments";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/constants/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/constants/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGvC,OAAO,EACL,MAAM,EACN,aAAa,EACb,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAG9C,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,EACxB,0BAA0B,EAC1B,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}

package/dist/types/constants/limits.d.ts

@@ -0,0 +1,149 @@
+/**
+ * @module constants/limits
+ * @description Protocol size limits, version constants, and enum numeric values.
+ *
+ * All values mirror the on-chain Rust constraints exactly.
+ * Used for client-side validation before sending transactions.
+ *
+ * @category Constants
+ * @since v0.1.0
+ */
+/**
+ * Protocol size constraints mirroring the Rust `impl` blocks.
+ *
+ * Use these values for client-side validation before submitting
+ * transactions — exceeding any limit will cause an on-chain error.
+ *
+ * @name LIMITS
+ * @description A frozen object containing all protocol-enforced size and length bounds.
+ * @category Constants
+ * @since v0.1.0
+ * @example
+ * ```ts
+ * import { LIMITS } from "@synapse-sap/sdk/constants";
+ *
+ * if (name.length > LIMITS.MAX_NAME_LEN) {
+ *   throw new Error("Agent name too long");
+ * }
+ * ```
+ */
+export declare const LIMITS: {
+    /** Max agent name length in bytes. */
+    readonly MAX_NAME_LEN: 64;
+    /** Max agent description length in bytes. */
+    readonly MAX_DESC_LEN: 256;
+    /** Max URI length (agent_uri, x402_endpoint). */
+    readonly MAX_URI_LEN: 256;
+    /** Max agent DID-style identifier length. */
+    readonly MAX_AGENT_ID_LEN: 128;
+    /** Max capabilities per agent. */
+    readonly MAX_CAPABILITIES: 10;
+    /** Max pricing tiers per agent. */
+    readonly MAX_PRICING_TIERS: 5;
+    /** Max protocol strings per agent. */
+    readonly MAX_PROTOCOLS: 5;
+    /** Max active plugins per agent. */
+    readonly MAX_PLUGINS: 5;
+    /** Max volume curve breakpoints per tier. */
+    readonly MAX_VOLUME_CURVE_POINTS: 5;
+    /** Max feedback tag length. */
+    readonly MAX_TAG_LEN: 32;
+    /** Max agents in a capability/protocol index. */
+    readonly MAX_AGENTS_PER_INDEX: 100;
+    /** Max tool name length. */
+    readonly MAX_TOOL_NAME_LEN: 32;
+    /** Max tools in a category index. */
+    readonly MAX_TOOLS_PER_CATEGORY: 100;
+    /** Max attestation type length. */
+    readonly MAX_ATTESTATION_TYPE_LEN: 32;
+    /** Max inscription size (encrypted_data per fragment). */
+    readonly MAX_INSCRIPTION_SIZE: 750;
+    /** Inscriptions per epoch page. */
+    readonly INSCRIPTIONS_PER_EPOCH: 1000;
+    /** Max memory chunk size (legacy). */
+    readonly MAX_CHUNK_SIZE: 900;
+    /** Max write size per buffer append (legacy). */
+    readonly MAX_BUFFER_WRITE_SIZE: 750;
+    /** Max total buffer page size (legacy). */
+    readonly MAX_BUFFER_TOTAL_SIZE: 10000;
+    /** Ring buffer capacity for MemoryLedger. */
+    readonly RING_CAPACITY: 4096;
+    /** Max ledger write size per call. */
+    readonly MAX_LEDGER_WRITE_SIZE: 750;
+    /** Max settlements in a batch. */
+    readonly MAX_BATCH_SETTLEMENTS: 10;
+    /** Feedback score range: 0–1000. */
+    readonly MAX_FEEDBACK_SCORE: 1000;
+};
+/**
+ * Current on-chain protocol version for `AgentAccount`.
+ *
+ * @name AGENT_VERSION
+ * @description Integer version stamped into every agent account on registration.
+ * @category Constants
+ * @since v0.1.0
+ */
+export declare const AGENT_VERSION = 1;
+/**
+ * Current on-chain protocol version for `MemoryVault`.
+ *
+ * @name VAULT_PROTOCOL_VERSION
+ * @description Integer version stamped into every vault account on initialisation.
+ * @category Constants
+ * @since v0.1.0
+ */
+export declare const VAULT_PROTOCOL_VERSION = 1;
+/**
+ * Tool category to `u8` discriminant mapping.
+ *
+ * Mirrors the Rust `ToolCategory` enum ordinals. Use these values
+ * when constructing or filtering tool-related instructions.
+ *
+ * @name TOOL_CATEGORY_VALUES
+ * @description Frozen mapping of tool category names to their on-chain `u8` discriminants.
+ * @category Constants
+ * @since v0.1.0
+ * @example
+ * ```ts
+ * import { TOOL_CATEGORY_VALUES } from "@synapse-sap/sdk/constants";
+ *
+ * const categoryByte = TOOL_CATEGORY_VALUES.Swap; // 0
+ * ```
+ */
+export declare const TOOL_CATEGORY_VALUES: {
+    readonly Swap: 0;
+    readonly Lend: 1;
+    readonly Stake: 2;
+    readonly Nft: 3;
+    readonly Payment: 4;
+    readonly Data: 5;
+    readonly Governance: 6;
+    readonly Bridge: 7;
+    readonly Analytics: 8;
+    readonly Custom: 9;
+};
+/**
+ * HTTP method to `u8` discriminant mapping.
+ *
+ * Mirrors the Rust `HttpMethod` enum ordinals. Used when publishing
+ * or filtering tool endpoints.
+ *
+ * @name HTTP_METHOD_VALUES
+ * @description Frozen mapping of HTTP method names to their on-chain `u8` discriminants.
+ * @category Constants
+ * @since v0.1.0
+ * @example
+ * ```ts
+ * import { HTTP_METHOD_VALUES } from "@synapse-sap/sdk/constants";
+ *
+ * const method = HTTP_METHOD_VALUES.Post; // 1
+ * ```
+ */
+export declare const HTTP_METHOD_VALUES: {
+    readonly Get: 0;
+    readonly Post: 1;
+    readonly Put: 2;
+    readonly Delete: 3;
+    readonly Compound: 4;
+};
+//# sourceMappingURL=limits.d.ts.map

package/dist/types/constants/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../../src/constants/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,MAAM;IACjB,sCAAsC;;IAEtC,6CAA6C;;IAE7C,iDAAiD;;IAEjD,6CAA6C;;IAE7C,kCAAkC;;IAElC,mCAAmC;;IAEnC,sCAAsC;;IAEtC,oCAAoC;;IAEpC,6CAA6C;;IAE7C,+BAA+B;;IAE/B,iDAAiD;;IAEjD,4BAA4B;;IAE5B,qCAAqC;;IAErC,mCAAmC;;IAEnC,0DAA0D;;IAE1D,mCAAmC;;IAEnC,sCAAsC;;IAEtC,iDAAiD;;IAEjD,2CAA2C;;IAE3C,6CAA6C;;IAE7C,sCAAsC;;IAEtC,kCAAkC;;IAElC,oCAAoC;;CAE5B,CAAC;AAMX;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAMxC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;CAWvB,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,kBAAkB;;;;;;CAMrB,CAAC"}

package/dist/types/constants/network.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @module constants/network
+ * @description Solana network identifiers for x402 payment headers.
+ *
+ * x402 providers validate the `X-Payment-Network` header against their
+ * own network identifier. Some providers (e.g. Coinbase, Phantom) accept
+ * the human-readable cluster name (`solana:mainnet-beta`), while others
+ * (e.g. Kamiyo, Helius x402) require the Solana genesis-hash form
+ * (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`).
+ *
+ * Use {@link SapNetwork} to select the correct format, or pass any
+ * custom string where needed.
+ *
+ * @category Constants
+ * @since v0.4.3
+ *
+ * @example
+ * ```ts
+ * import { SapNetwork } from "@synapse-sap/sdk";
+ *
+ * // Standard cluster name (default)
+ * const ctx = await x402.preparePayment(agentWallet, {
+ *   pricePerCall: 1000, deposit: 100_000,
+ *   networkIdentifier: SapNetwork.SOLANA_MAINNET,
+ * });
+ *
+ * // Genesis-hash form for providers that require it
+ * const ctx2 = await x402.preparePayment(agentWallet, {
+ *   pricePerCall: 1000, deposit: 100_000,
+ *   networkIdentifier: SapNetwork.SOLANA_MAINNET_GENESIS,
+ * });
+ * ```
+ */
+/**
+ * @name SapNetwork
+ * @description Network identifier strings for x402 `X-Payment-Network` headers.
+ *
+ * Two mainnet forms exist because x402 providers disagree on the canonical
+ * identifier:
+ *
+ * | Constant                | Value                                        | Accepted by          |
+ * |-------------------------|----------------------------------------------|----------------------|
+ * | `SOLANA_MAINNET`        | `solana:mainnet-beta`                        | Coinbase, Phantom    |
+ * | `SOLANA_MAINNET_GENESIS`| `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`   | Kamiyo, Helius x402  |
+ * | `SOLANA_DEVNET`         | `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`   | Devnet providers     |
+ * | `SOLANA_DEVNET_NAMED`   | `solana:devnet`                              | Local / test flows   |
+ *
+ * If your provider requires a different format, pass a raw string instead.
+ *
+ * @category Constants
+ * @since v0.4.3
+ */
+export declare const SapNetwork: {
+    /**
+     * Mainnet-beta, human-readable cluster name.
+     * Default value used by the SDK prior to v0.4.3.
+     */
+    readonly SOLANA_MAINNET: "solana:mainnet-beta";
+    /**
+     * Mainnet-beta, genesis-hash form (CAIP-2 compliant).
+     * Required by Kamiyo, Helius x402, and other providers that validate
+     * against the Solana genesis hash.
+     */
+    readonly SOLANA_MAINNET_GENESIS: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+    /**
+     * Devnet, genesis-hash form (CAIP-2 compliant).
+     */
+    readonly SOLANA_DEVNET: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
+    /**
+     * Devnet, human-readable cluster name.
+     * Useful for local development and test validators.
+     */
+    readonly SOLANA_DEVNET_NAMED: "solana:devnet";
+};
+/**
+ * @name SapNetworkId
+ * @description Union type of all known {@link SapNetwork} values.
+ * Accept `SapNetworkId | string` where custom identifiers are allowed.
+ */
+export type SapNetworkId = (typeof SapNetwork)[keyof typeof SapNetwork];
+//# sourceMappingURL=network.d.ts.map

package/dist/types/constants/network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../../src/constants/network.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAMH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,UAAU;IACrB;;;OAGG;;IAGH;;;;OAIG;;IAGH;;OAEG;;IAGH;;;OAGG;;CAEK,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC"}