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

package/src/modules/agent.ts

@@ -1,319 +0,0 @@
-/**
- * @module agent
- * @description Agent lifecycle operations for the Synapse 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, type PublicKey, type TransactionSignature } from "@solana/web3.js";
-import { BaseModule } from "./base";
-import { deriveAgent, deriveAgentStats, deriveGlobalRegistry } from "../pda";
-import type {
-  AgentAccountData,
-  AgentStatsData,
-  RegisterAgentArgs,
-  UpdateAgentArgs,
-} from "../types";
-
-/**
- * @name AgentModule
- * @description Manages the full agent lifecycle on the Synapse 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?: PublicKey): readonly [PublicKey, number] {
-    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: PublicKey): readonly [PublicKey, number] {
-    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: RegisterAgentArgs): Promise<TransactionSignature> {
-    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: UpdateAgentArgs): Promise<TransactionSignature> {
-    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(): Promise<TransactionSignature> {
-    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(): Promise<TransactionSignature> {
-    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(): Promise<TransactionSignature> {
-    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: number | bigint): Promise<TransactionSignature> {
-    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: number,
-    uptimePercent: number,
-  ): Promise<TransactionSignature> {
-    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?: PublicKey): Promise<AgentAccountData> {
-    const [pda] = this.deriveAgent(wallet ?? this.walletPubkey);
-    return this.fetchAccount<AgentAccountData>("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?: PublicKey): Promise<AgentAccountData | null> {
-    const [pda] = this.deriveAgent(wallet ?? this.walletPubkey);
-    return this.fetchAccountNullable<AgentAccountData>("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: PublicKey): Promise<AgentStatsData> {
-    const [pda] = this.deriveStats(agentPda);
-    return this.fetchAccount<AgentStatsData>("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: PublicKey): Promise<AgentStatsData | null> {
-    const [pda] = this.deriveStats(agentPda);
-    return this.fetchAccountNullable<AgentStatsData>("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(): Promise<import("../types").GlobalRegistryData> {
-    const [pda] = deriveGlobalRegistry();
-    return this.fetchAccount("globalRegistry", pda);
-  }
-}

package/src/modules/attestation.ts

@@ -1,168 +0,0 @@
-/**
- * @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, type PublicKey, type TransactionSignature } from "@solana/web3.js";
-import { BaseModule } from "./base";
-import { deriveAgent, deriveAttestation, deriveGlobalRegistry } from "../pda";
-import type { AgentAttestationData, CreateAttestationArgs } from "../types";
-
-/**
- * @name AttestationModule
- * @description Manages on-chain attestations for the Synapse 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: PublicKey,
-    attester?: PublicKey,
-  ): readonly [PublicKey, number] {
-    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: PublicKey,
-    args: CreateAttestationArgs,
-  ): Promise<TransactionSignature> {
-    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: PublicKey): Promise<TransactionSignature> {
-    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: PublicKey): Promise<TransactionSignature> {
-    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: PublicKey,
-    attester?: PublicKey,
-  ): Promise<AgentAttestationData> {
-    const [pda] = this.deriveAttestation(agentPda, attester);
-    return this.fetchAccount<AgentAttestationData>("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: PublicKey,
-    attester?: PublicKey,
-  ): Promise<AgentAttestationData | null> {
-    const [pda] = this.deriveAttestation(agentPda, attester);
-    return this.fetchAccountNullable<AgentAttestationData>("agentAttestation", pda);
-  }
-}

package/src/modules/base.ts

@@ -1,158 +0,0 @@
-/**
- * @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 { type AnchorProvider, type Program, BN } from "@coral-xyz/anchor";
-import type { PublicKey, TransactionSignature } from "@solana/web3.js";
-
-/**
- * Anchor `Program` instance typed for the Synapse Agent SAP IDL.
- *
- * @name SapProgram
- * @description Alias for `Program<any>` — the Anchor program reference
- *   used as the backbone of every module in the SDK.
- * @category Modules
- * @since v0.1.0
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type SapProgram = Program<any>;
-
-/**
- * @name SapTransactionResult
- * @description Instruction builder return type — a ready-to-send transaction.
- * Contains the finalized transaction signature after RPC submission.
- * @category Modules
- * @since v0.1.0
- */
-export interface SapTransactionResult {
-  /** The base-58 encoded transaction signature returned by the RPC node. */
-  readonly signature: TransactionSignature;
-}
-
-/**
- * @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 abstract class BaseModule {
-  /**
-   * Create a new module instance.
-   *
-   * @param program - The Anchor `Program` instance for the SAP IDL.
-   * @protected
-   */
-  constructor(protected readonly program: SapProgram) {}
-
-  /**
-   * @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
-  protected get methods(): any {
-    // 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
-   */
-  protected get provider(): AnchorProvider {
-    return this.program.provider as AnchorProvider;
-  }
-
-  /**
-   * @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
-   */
-  protected get walletPubkey(): PublicKey {
-    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
-   */
-  protected async fetchAccount<T>(
-    accountName: string,
-    address: PublicKey,
-  ): Promise<T> {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
-    return (this.program.account as any)[accountName].fetch(address) as Promise<T>;
-  }
-
-  /**
-   * @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
-   */
-  protected async fetchAccountNullable<T>(
-    accountName: string,
-    address: PublicKey,
-  ): Promise<T | null> {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
-    return (this.program.account as any)[accountName].fetchNullable(address) as Promise<T | null>;
-  }
-
-  /**
-   * @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
-   */
-  protected bn(value: number | bigint | BN): BN {
-    if (BN.isBN(value)) return value;
-    return new BN(value.toString());
-  }
-}