@oobe-protocol-labs/synapse-sap-sdk 0.1.0

package/dist/esm/index.js

@@ -0,0 +1,70 @@
+/**
+ * @synapse-sap/sdk — TypeScript SDK for SAP v2 (Solana Agent Protocol)
+ *
+ * Modular architecture:
+ *
+ * | Path              | Description                                   |
+ * |-------------------|-----------------------------------------------|
+ * | `core/`           | SapClient, SapConnection (RPC factory)        |
+ * | `types/`          | On-chain enums, account data, instruction DTOs|
+ * | `constants/`      | Program IDs, PDA seeds, size limits           |
+ * | `pda/`            | Deterministic PDA derivation helpers          |
+ * | `events/`         | Transaction-log event parser                  |
+ * | `errors/`         | Typed SDK error classes                       |
+ * | `utils/`          | Hashing, validation, serialization            |
+ * | `modules/`        | Low-level per-domain instruction wrappers     |
+ * | `registries/`     | High-level abstractions (discovery, x402, …)  |
+ * | `plugin/`         | SynapseAgentKit adapter (52 tools)            |
+ * | `idl/`            | Embedded Anchor IDL                           |
+ *
+ * @example
+ * ```ts
+ * import { SapClient, SapConnection } from "@synapse-sap/sdk";
+ *
+ * // Quick start — from Anchor provider
+ * const client = SapClient.from(provider);
+ *
+ * // Or from RPC URL (synapse-client-sdk compatible)
+ * const conn = SapConnection.devnet();
+ * const client2 = conn.fromKeypair(keypair);
+ *
+ * // Use domain modules:
+ * await client.agent.register({ ... });
+ * await client.escrow.create(agentWallet, { ... });
+ * await client.ledger.write(sessionPda, data, contentHash);
+ *
+ * // Use registries (high-level):
+ * const agents = await client.discovery.findAgentsByProtocol("jupiter");
+ * const ctx = await client.session.start("conv-123");
+ * ```
+ *
+ * @packageDocumentation
+ * @category SDK
+ * @since v0.1.0
+ */
+// ── Core ─────────────────────────────────────────────
+export { SapClient, SapConnection } from "./core";
+export { TokenType, PluginType, SettlementMode, ToolHttpMethod, ToolCategory, DelegatePermission, SchemaType, CompressionType, } from "./types";
+// ── Constants ────────────────────────────────────────
+export { SAP_PROGRAM_ADDRESS, SAP_PROGRAM_ID, MAINNET_SAP_PROGRAM_ID, DEVNET_SAP_PROGRAM_ID, LOCALNET_SAP_PROGRAM_ID, SEEDS, LIMITS, AGENT_VERSION, VAULT_PROTOCOL_VERSION, TOOL_CATEGORY_VALUES, HTTP_METHOD_VALUES, } from "./constants";
+// ── IDL ──────────────────────────────────────────────
+export { SAP_IDL, IDL_PROGRAM_ADDRESS, IDL_METADATA } from "./idl/index";
+// ── PDA Derivation ───────────────────────────────────
+export { deriveGlobalRegistry, deriveAgent, deriveAgentStats, deriveFeedback, deriveCapabilityIndex, deriveProtocolIndex, deriveToolCategoryIndex, deriveVault, deriveSession, deriveEpochPage, deriveVaultDelegate, deriveCheckpoint, deriveTool, deriveEscrow, deriveAttestation, deriveLedger, deriveLedgerPage, } from "./pda";
+// ── Utilities ────────────────────────────────────────
+export { sha256, hashToArray, assert } from "./utils";
+export { serializeAccount, serializeValue } from "./utils";
+// ── Errors ───────────────────────────────────────────
+export { SapError, SapValidationError, SapRpcError, SapAccountNotFoundError, SapTimeoutError, SapPermissionError, } from "./errors";
+// ── Events ───────────────────────────────────────────
+export { EventParser, SAP_EVENT_NAMES } from "./events";
+// ── Modules (for advanced usage / tree-shaking) ──────
+export { AgentModule, FeedbackModule, IndexingModule, ToolsModule, VaultModule, EscrowModule, AttestationModule, LedgerModule, BaseModule, } from "./modules/index";
+// ── Plugin (SynapseAgentKit integration) ─────────────
+export { createSAPPlugin, SAPPlugin } from "./plugin/index";
+export { SAP_PROTOCOLS } from "./plugin/protocols";
+// ── PostgreSQL Adapter (off-chain mirror) ────────────────
+export { SapPostgres, SapSyncEngine, SAP_TABLE_MAP } from "./postgres";
+// ── Registries (high-level developer abstractions) ────
+export { DiscoveryRegistry, X402Registry, SessionManager, AgentBuilder, } from "./registries/index";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,wDAAwD;AACxD,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAoDlD,OAAO,EACL,SAAS,EACT,UAAU,EACV,cAAc,EACd,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,UAAU,EACV,eAAe,GAChB,MAAM,SAAS,CAAC;AAEjB,wDAAwD;AACxD,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,KAAK,EACL,MAAM,EACN,aAAa,EACb,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,wDAAwD;AACxD,OAAO,EAAE,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGzE,wDAAwD;AACxD,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,uBAAuB,EACvB,WAAW,EACX,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,GACjB,MAAM,OAAO,CAAC;AAEf,wDAAwD;AACxD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE3D,wDAAwD;AACxD,OAAO,EACL,QAAQ,EACR,kBAAkB,EAClB,WAAW,EACX,uBAAuB,EACvB,eAAe,EACf,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAElB,wDAAwD;AACxD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAaxD,wDAAwD;AACxD,OAAO,EACL,WAAW,EACX,cAAc,EACd,cAAc,EACd,WAAW,EACX,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,UAAU,GACX,MAAM,iBAAiB,CAAC;AAGzB,wDAAwD;AACxD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAY5D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,4DAA4D;AAC5D,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAevE,yDAAyD;AACzD,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,YAAY,GACb,MAAM,oBAAoB,CAAC"}

package/dist/esm/modules/agent.js

@@ -0,0 +1,268 @@
+/**
+ * @module agent
+ * @description Agent lifecycle operations for the Solana Agent Protocol.
+ *
+ * Covers: register, update, deactivate, reactivate, close,
+ * report calls, update reputation metrics, and account fetching.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+import { SystemProgram } from "@solana/web3.js";
+import { BaseModule } from "./base";
+import { deriveAgent, deriveAgentStats, deriveGlobalRegistry } from "../pda";
+/**
+ * @name AgentModule
+ * @description Manages the full agent lifecycle on the Solana Agent Protocol.
+ *   Provides methods to register, update, deactivate, reactivate, and close
+ *   agent identities, as well as self-report call metrics and reputation data.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @extends BaseModule
+ *
+ * @example
+ * ```ts
+ * const sap = new SapClient(provider);
+ * // Register a new agent
+ * const sig = await sap.agent.register({
+ *   name: "my-agent",
+ *   description: "An example agent",
+ *   capabilities: [0, 1],
+ *   pricing: { free: {} },
+ *   protocols: [0],
+ * });
+ * // Fetch agent data
+ * const data = await sap.agent.fetch();
+ * ```
+ */
+export class AgentModule extends BaseModule {
+    // ── PDA helpers ──────────────────────────────────────
+    /**
+     * @name deriveAgent
+     * @description Derive the `AgentAccount` PDA for a wallet.
+     * @param wallet - The wallet public key. Defaults to the connected wallet.
+     * @returns A tuple of `[PublicKey, bump]` for the agent PDA.
+     * @see {@link deriveAgent} from `pda/` module for the underlying derivation.
+     * @since v0.1.0
+     */
+    deriveAgent(wallet) {
+        return deriveAgent(wallet ?? this.walletPubkey);
+    }
+    /**
+     * @name deriveStats
+     * @description Derive the `AgentStats` PDA for a given agent.
+     * @param agentPda - The agent account PDA.
+     * @returns A tuple of `[PublicKey, bump]` for the stats PDA.
+     * @see {@link deriveAgentStats} from `pda/` module for the underlying derivation.
+     * @since v0.1.0
+     */
+    deriveStats(agentPda) {
+        return deriveAgentStats(agentPda);
+    }
+    // ── Instructions ─────────────────────────────────────
+    /**
+     * @name register
+     * @description Register a new agent identity on-chain. Creates the
+     *   `AgentAccount`, `AgentStats`, and updates the `GlobalRegistry`.
+     * @param args - Registration parameters (name, description, capabilities, pricing, protocols, etc.).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async register(args) {
+        const [agentPda] = this.deriveAgent();
+        const [statsPda] = this.deriveStats(agentPda);
+        const [globalPda] = deriveGlobalRegistry();
+        return this.methods
+            .registerAgent(args.name, args.description, args.capabilities, args.pricing, args.protocols, args.agentId ?? null, args.agentUri ?? null, args.x402Endpoint ?? null)
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            agentStats: statsPda,
+            globalRegistry: globalPda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * @name update
+     * @description Update an existing agent's metadata fields. All fields
+     *   are optional — only non-null values are written.
+     * @param args - Partial update parameters.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async update(args) {
+        const [agentPda] = this.deriveAgent();
+        return this.methods
+            .updateAgent(args.name ?? null, args.description ?? null, args.capabilities ?? null, args.pricing ?? null, args.protocols ?? null, args.agentId ?? null, args.agentUri ?? null, args.x402Endpoint ?? null)
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * @name deactivate
+     * @description Deactivate an agent, setting `is_active = false`.
+     *   The agent remains on-chain but is excluded from active discovery.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async deactivate() {
+        const [agentPda] = this.deriveAgent();
+        const [statsPda] = this.deriveStats(agentPda);
+        return this.methods
+            .deactivateAgent()
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            agentStats: statsPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name reactivate
+     * @description Reactivate a previously deactivated agent, restoring
+     *   it to active status.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async reactivate() {
+        const [agentPda] = this.deriveAgent();
+        const [statsPda] = this.deriveStats(agentPda);
+        return this.methods
+            .reactivateAgent()
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            agentStats: statsPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name close
+     * @description Close an agent PDA and its associated stats PDA.
+     *   Rent is returned to the owner wallet.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async close() {
+        const [agentPda] = this.deriveAgent();
+        const [statsPda] = this.deriveStats(agentPda);
+        const [globalPda] = deriveGlobalRegistry();
+        return this.methods
+            .closeAgent()
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            agentStats: statsPda,
+            globalRegistry: globalPda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * @name reportCalls
+     * @description Self-report call metrics for the agent. This updates the
+     *   `AgentStats` counter but does not affect on-chain reputation.
+     * @param callsServed - The number of calls to report.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async reportCalls(callsServed) {
+        const [agentPda] = this.deriveAgent();
+        const [statsPda] = this.deriveStats(agentPda);
+        return this.methods
+            .reportCalls(this.bn(callsServed))
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+            agentStats: statsPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name updateReputation
+     * @description Update self-reported latency and uptime metrics.
+     *   These are informational and do not affect on-chain reputation scoring.
+     * @param avgLatencyMs - Average response latency in milliseconds.
+     * @param uptimePercent - Uptime percentage (0–100).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async updateReputation(avgLatencyMs, uptimePercent) {
+        const [agentPda] = this.deriveAgent();
+        return this.methods
+            .updateReputation(avgLatencyMs, uptimePercent)
+            .accounts({
+            wallet: this.walletPubkey,
+            agent: agentPda,
+        })
+            .rpc();
+    }
+    // ── Fetchers ─────────────────────────────────────────
+    /**
+     * @name fetch
+     * @description Fetch the deserialized `AgentAccount` data for a wallet.
+     * @param wallet - The wallet public key. Defaults to the connected wallet.
+     * @returns {Promise<AgentAccountData>} The agent account data.
+     * @throws Will throw if the agent account does not exist.
+     * @since v0.1.0
+     */
+    async fetch(wallet) {
+        const [pda] = this.deriveAgent(wallet ?? this.walletPubkey);
+        return this.fetchAccount("agentAccount", pda);
+    }
+    /**
+     * @name fetchNullable
+     * @description Fetch the deserialized `AgentAccount` data, or `null`
+     *   if the account doesn't exist on-chain.
+     * @param wallet - The wallet public key. Defaults to the connected wallet.
+     * @returns {Promise<AgentAccountData | null>} The agent data or `null`.
+     * @since v0.1.0
+     */
+    async fetchNullable(wallet) {
+        const [pda] = this.deriveAgent(wallet ?? this.walletPubkey);
+        return this.fetchAccountNullable("agentAccount", pda);
+    }
+    /**
+     * @name fetchStats
+     * @description Fetch the deserialized `AgentStats` data for an agent.
+     * @param agentPda - The agent account PDA.
+     * @returns {Promise<AgentStatsData>} The agent stats data.
+     * @throws Will throw if the stats account does not exist.
+     * @since v0.1.0
+     */
+    async fetchStats(agentPda) {
+        const [pda] = this.deriveStats(agentPda);
+        return this.fetchAccount("agentStats", pda);
+    }
+    /**
+     * @name fetchStatsNullable
+     * @description Fetch the deserialized `AgentStats` data, or `null`
+     *   if the account doesn't exist on-chain.
+     * @param agentPda - The agent account PDA.
+     * @returns {Promise<AgentStatsData | null>} The stats data or `null`.
+     * @since v0.1.0
+     */
+    async fetchStatsNullable(agentPda) {
+        const [pda] = this.deriveStats(agentPda);
+        return this.fetchAccountNullable("agentStats", pda);
+    }
+    /**
+     * @name fetchGlobalRegistry
+     * @description Fetch the `GlobalRegistry` singleton account that tracks
+     *   aggregate protocol statistics.
+     * @returns {Promise<GlobalRegistryData>} The global registry data.
+     * @throws Will throw if the registry has not been initialized.
+     * @since v0.1.0
+     */
+    async fetchGlobalRegistry() {
+        const [pda] = deriveGlobalRegistry();
+        return this.fetchAccount("globalRegistry", pda);
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/esm/modules/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../src/modules/agent.ts"],"names":[],"mappings":"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"}

package/dist/esm/modules/attestation.js

@@ -0,0 +1,143 @@
+/**
+ * @module attestation
+ * @description Web-of-trust attestations — create, revoke, and close
+ *   on-chain attestations that vouch for agent trustworthiness.
+ *
+ * Attestations are signed endorsements from one wallet to an agent,
+ * forming a composable trust graph on Solana.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+import { SystemProgram } from "@solana/web3.js";
+import { BaseModule } from "./base";
+import { deriveAgent, deriveAttestation, deriveGlobalRegistry } from "../pda";
+/**
+ * @name AttestationModule
+ * @description Manages on-chain attestations for the Solana Agent Protocol.
+ *   Provides methods to create, revoke, close, and fetch attestation PDAs
+ *   that form the web-of-trust layer.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @extends BaseModule
+ *
+ * @example
+ * ```ts
+ * const sap = new SapClient(provider);
+ * // Create an attestation for an agent
+ * const sig = await sap.attestation.create(agentWallet, {
+ *   attestationType: { identity: {} },
+ *   metadataHash: [...],
+ *   expiresAt: null,
+ * });
+ * ```
+ */
+export class AttestationModule extends BaseModule {
+    // ── PDA helpers ──────────────────────────────────────
+    /**
+     * @name deriveAttestation
+     * @description Derive the `AgentAttestation` PDA for a given agent and attester.
+     * @param agentPda - The agent account PDA to attest.
+     * @param attester - The attester wallet. Defaults to the connected wallet.
+     * @returns A tuple of `[PublicKey, bump]` for the attestation PDA.
+     * @see {@link deriveAttestation} from `pda/` module for the underlying derivation.
+     * @since v0.1.0
+     */
+    deriveAttestation(agentPda, attester) {
+        return deriveAttestation(agentPda, attester ?? this.walletPubkey);
+    }
+    // ── Instructions ─────────────────────────────────────
+    /**
+     * @name create
+     * @description Create an on-chain attestation vouching for an agent.
+     *   The connected wallet becomes the attester.
+     * @param agentWallet - The wallet that owns the target agent.
+     * @param args - Attestation parameters (type, metadata hash, optional expiry).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async create(agentWallet, args) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const [attestPda] = this.deriveAttestation(agentPda);
+        const [globalPda] = deriveGlobalRegistry();
+        return this.methods
+            .createAttestation(args.attestationType, args.metadataHash, args.expiresAt)
+            .accounts({
+            attester: this.walletPubkey,
+            agent: agentPda,
+            attestation: attestPda,
+            globalRegistry: globalPda,
+            systemProgram: SystemProgram.programId,
+        })
+            .rpc();
+    }
+    /**
+     * @name revoke
+     * @description Revoke a previously issued attestation. Only the original
+     *   attester may revoke.
+     * @param agentWallet - The wallet of the attested agent.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async revoke(agentWallet) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const [attestPda] = this.deriveAttestation(agentPda);
+        return this.methods
+            .revokeAttestation()
+            .accounts({
+            attester: this.walletPubkey,
+            attestation: attestPda,
+        })
+            .rpc();
+    }
+    /**
+     * @name close
+     * @description Close a revoked attestation PDA and reclaim rent to the attester.
+     * @param agentWallet - The wallet of the attested agent.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    async close(agentWallet) {
+        const [agentPda] = deriveAgent(agentWallet);
+        const [attestPda] = this.deriveAttestation(agentPda);
+        const [globalPda] = deriveGlobalRegistry();
+        return this.methods
+            .closeAttestation()
+            .accounts({
+            attester: this.walletPubkey,
+            attestation: attestPda,
+            globalRegistry: globalPda,
+        })
+            .rpc();
+    }
+    // ── Fetchers ─────────────────────────────────────────
+    /**
+     * @name fetch
+     * @description Fetch a deserialized `AgentAttestation` account.
+     * @param agentPda - The agent account PDA.
+     * @param attester - The attester wallet. Defaults to the connected wallet.
+     * @returns {Promise<AgentAttestationData>} The attestation account data.
+     * @throws Will throw if the attestation account does not exist.
+     * @since v0.1.0
+     */
+    async fetch(agentPda, attester) {
+        const [pda] = this.deriveAttestation(agentPda, attester);
+        return this.fetchAccount("agentAttestation", pda);
+    }
+    /**
+     * @name fetchNullable
+     * @description Fetch a deserialized `AgentAttestation` account, or `null`
+     *   if it does not exist on-chain.
+     * @param agentPda - The agent account PDA.
+     * @param attester - The attester wallet. Defaults to the connected wallet.
+     * @returns {Promise<AgentAttestationData | null>} The attestation data or `null`.
+     * @since v0.1.0
+     */
+    async fetchNullable(agentPda, attester) {
+        const [pda] = this.deriveAttestation(agentPda, attester);
+        return this.fetchAccountNullable("agentAttestation", pda);
+    }
+}
+//# sourceMappingURL=attestation.js.map

package/dist/esm/modules/attestation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attestation.js","sourceRoot":"","sources":["../../../src/modules/attestation.ts"],"names":[],"mappings":"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"}

package/dist/esm/modules/base.js

@@ -0,0 +1,124 @@
+/**
+ * @module base
+ * @description Abstract base class for all SDK modules.
+ *
+ * Provides shared access to the Anchor program, provider,
+ * and typed `fetch` / `fetchNullable` helpers.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+import { BN } from "@coral-xyz/anchor";
+/**
+ * @name BaseModule
+ * @description Abstract base module inherited by every domain module in the SDK.
+ * Encapsulates the Anchor program reference, provider access, and common
+ * helpers for account fetching and BN construction.
+ *
+ * @abstract
+ * @category Modules
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * class MyModule extends BaseModule {
+ *   async doSomething() {
+ *     const data = await this.fetchAccount<MyData>("myAccount", pda);
+ *   }
+ * }
+ * ```
+ */
+export class BaseModule {
+    program;
+    /**
+     * Create a new module instance.
+     *
+     * @param program - The Anchor `Program` instance for the SAP IDL.
+     * @protected
+     */
+    constructor(program) {
+        this.program = program;
+    }
+    /**
+     * @name methods
+     * @description Instruction method namespace — bypasses `noUncheckedIndexedAccess`
+     *   on `Program<any>` where every property is `T | undefined`.
+     *   Used internally by subclasses to build and send instructions.
+     * @returns The Anchor program `methods` object for chaining instruction builders.
+     * @protected
+     * @since v0.1.0
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    get methods() {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return this.program.methods;
+    }
+    /**
+     * @name provider
+     * @description The AnchorProvider from the program, giving access to
+     *   the connection and wallet for signing transactions.
+     * @returns {AnchorProvider} The Anchor provider instance.
+     * @protected
+     * @since v0.1.0
+     */
+    get provider() {
+        return this.program.provider;
+    }
+    /**
+     * @name walletPubkey
+     * @description Convenience accessor for the signer wallet's public key.
+     * @returns {PublicKey} The public key of the connected wallet.
+     * @protected
+     * @since v0.1.0
+     */
+    get walletPubkey() {
+        return this.provider.wallet.publicKey;
+    }
+    /**
+     * @name fetchAccount
+     * @description Generic account fetch — deserializes the on-chain account
+     *   data into the given type `T`, or throws if the account does not exist.
+     * @typeParam T - The expected deserialized account data type.
+     * @param accountName - The Anchor account discriminator name (e.g. `"agentAccount"`).
+     * @param address - The public key of the account to fetch.
+     * @returns {Promise<T>} The deserialized account data.
+     * @throws Will throw if the account does not exist on-chain.
+     * @protected
+     * @since v0.1.0
+     */
+    async fetchAccount(accountName, address) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+        return this.program.account[accountName].fetch(address);
+    }
+    /**
+     * @name fetchAccountNullable
+     * @description Generic nullable account fetch — deserializes the on-chain
+     *   account data into type `T`, or returns `null` if the account does not exist.
+     * @typeParam T - The expected deserialized account data type.
+     * @param accountName - The Anchor account discriminator name (e.g. `"agentAccount"`).
+     * @param address - The public key of the account to fetch.
+     * @returns {Promise<T | null>} The deserialized account data, or `null`.
+     * @protected
+     * @since v0.1.0
+     */
+    async fetchAccountNullable(accountName, address) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+        return this.program.account[accountName].fetchNullable(address);
+    }
+    /**
+     * @name bn
+     * @description Create an Anchor `BN` from a number, bigint, or existing BN.
+     *   Passes through values that are already `BN` instances.
+     * @param value - The numeric value to convert.
+     * @returns {BN} An Anchor-compatible big number.
+     * @protected
+     * @since v0.1.0
+     */
+    bn(value) {
+        if (BN.isBN(value))
+            return value;
+        return new BN(value.toString());
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/esm/modules/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/modules/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAqC,EAAE,EAAE,MAAM,mBAAmB,CAAC;AA2B1E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAgB,UAAU;IAOC;IAN/B;;;;;OAKG;IACH,YAA+B,OAAmB;QAAnB,YAAO,GAAP,OAAO,CAAY;IAAG,CAAC;IAEtD;;;;;;;;OAQG;IACH,8DAA8D;IAC9D,IAAc,OAAO;QACnB,+DAA+D;QAC/D,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;IAC9B,CAAC;IAED;;;;;;;OAOG;IACH,IAAc,QAAQ;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,QAA0B,CAAC;IACjD,CAAC;IAED;;;;;;OAMG;IACH,IAAc,YAAY;QACxB,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC;IACxC,CAAC;IAED;;;;;;;;;;;OAWG;IACO,KAAK,CAAC,YAAY,CAC1B,WAAmB,EACnB,OAAkB;QAElB,0GAA0G;QAC1G,OAAQ,IAAI,CAAC,OAAO,CAAC,OAAe,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,OAAO,CAAe,CAAC;IACjF,CAAC;IAED;;;;;;;;;;OAUG;IACO,KAAK,CAAC,oBAAoB,CAClC,WAAmB,EACnB,OAAkB;QAElB,0GAA0G;QAC1G,OAAQ,IAAI,CAAC,OAAO,CAAC,OAAe,CAAC,WAAW,CAAC,CAAC,aAAa,CAAC,OAAO,CAAsB,CAAC;IAChG,CAAC;IAED;;;;;;;;OAQG;IACO,EAAE,CAAC,KAA2B;QACtC,IAAI,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QACjC,OAAO,IAAI,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;IAClC,CAAC;CACF"}