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

package/dist/esm/modules/attestation.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @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 { type PublicKey, type TransactionSignature } from "@solana/web3.js";
+import { BaseModule } from "./base";
+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 declare class AttestationModule extends BaseModule {
+    /**
+     * @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];
+    /**
+     * @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
+     */
+    create(agentWallet: PublicKey, args: CreateAttestationArgs): Promise<TransactionSignature>;
+    /**
+     * @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
+     */
+    revoke(agentWallet: PublicKey): Promise<TransactionSignature>;
+    /**
+     * @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
+     */
+    close(agentWallet: PublicKey): Promise<TransactionSignature>;
+    /**
+     * @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
+     */
+    fetch(agentPda: PublicKey, attester?: PublicKey): Promise<AgentAttestationData>;
+    /**
+     * @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
+     */
+    fetchNullable(agentPda: PublicKey, attester?: PublicKey): Promise<AgentAttestationData | null>;
+}
+//# sourceMappingURL=attestation.d.ts.map

package/dist/esm/modules/attestation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attestation.d.ts","sourceRoot":"","sources":["../../../src/modules/attestation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC3F,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC,OAAO,KAAK,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,iBAAkB,SAAQ,UAAU;IAG/C;;;;;;;;OAQG;IACH,iBAAiB,CACf,QAAQ,EAAE,SAAS,EACnB,QAAQ,CAAC,EAAE,SAAS,GACnB,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC;IAM/B;;;;;;;;OAQG;IACG,MAAM,CACV,WAAW,EAAE,SAAS,EACtB,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,oBAAoB,CAAC;IAiBhC;;;;;;;OAOG;IACG,MAAM,CAAC,WAAW,EAAE,SAAS,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAanE;;;;;;OAMG;IACG,KAAK,CAAC,WAAW,EAAE,SAAS,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAiBlE;;;;;;;;OAQG;IACG,KAAK,CACT,QAAQ,EAAE,SAAS,EACnB,QAAQ,CAAC,EAAE,SAAS,GACnB,OAAO,CAAC,oBAAoB,CAAC;IAKhC;;;;;;;;OAQG;IACG,aAAa,CACjB,QAAQ,EAAE,SAAS,EACnB,QAAQ,CAAC,EAAE,SAAS,GACnB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;CAIxC"}

package/dist/esm/modules/base.d.ts

@@ -0,0 +1,161 @@
+/**
+ * @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";
+import { SAP_ERROR_BY_NAME } from "../utils/anchor-errors";
+/**
+ * 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
+ */
+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 declare abstract class BaseModule {
+    protected readonly program: SapProgram;
+    /**
+     * Create a new module instance.
+     *
+     * @param program - The Anchor `Program` instance for the SAP IDL.
+     * @protected
+     */
+    constructor(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
+     */
+    protected get methods(): any;
+    /**
+     * @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;
+    /**
+     * @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;
+    /**
+     * @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 fetchAccount<T>(accountName: string, address: PublicKey): 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 fetchAccountNullable<T>(accountName: string, address: PublicKey): 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;
+    /**
+     * @name requireAccountExists
+     * @description Fetch a required account; throw a {@link SapPreflightError}
+     *   with an actionable message if it does not exist.
+     * @typeParam T - Expected account type.
+     * @param accountName - Anchor account discriminator name.
+     * @param address - PDA to fetch.
+     * @param onMissing - `{ predicted, hint }` describing the on-chain rejection
+     *   that would otherwise occur.
+     * @protected
+     * @since v0.13.0
+     */
+    protected requireAccountExists<T>(accountName: string, address: PublicKey, onMissing: {
+        predicted: keyof typeof SAP_ERROR_BY_NAME;
+        hint?: string;
+    }): Promise<T>;
+    /**
+     * @name requireAccountAbsent
+     * @description Verify a PDA does not yet exist on-chain. Used before any
+     *   `init` instruction to catch `account already in use` early.
+     * @protected
+     * @since v0.13.0
+     */
+    protected requireAccountAbsent(accountName: string, address: PublicKey, hint: string): Promise<void>;
+    /**
+     * @name simulateOrThrow
+     * @description Run `simulate()` on a method builder. If the simulation
+     *   reports a SAP program error, throw it as a {@link SapPreflightError}
+     *   with the decoded name + friendly hint *before* the user pays fees.
+     *   Returns the simulation logs on success for inspection.
+     * @protected
+     * @since v0.13.0
+     */
+    protected simulateOrThrow(builder: any, label: string): Promise<readonly string[]>;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/esm/modules/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/modules/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,OAAO,EAAE,EAAE,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,KAAK,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAIL,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;GAQG;AAEH,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;AAEtC;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,oBAAoB,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,8BAAsB,UAAU;IAOlB,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,UAAU;IANlD;;;;;OAKG;gBAC4B,OAAO,EAAE,UAAU;IAElD;;;;;;;;OAQG;IAEH,SAAS,KAAK,OAAO,IAAI,GAAG,CAG3B;IAED;;;;;;;OAOG;IACH,SAAS,KAAK,QAAQ,IAAI,cAAc,CAEvC;IAED;;;;;;OAMG;IACH,SAAS,KAAK,YAAY,IAAI,SAAS,CAEtC;IAED;;;;;;;;;;;OAWG;cACa,YAAY,CAAC,CAAC,EAC5B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,SAAS,GACjB,OAAO,CAAC,CAAC,CAAC;IAKb;;;;;;;;;;OAUG;cACa,oBAAoB,CAAC,CAAC,EACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,SAAS,GACjB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAKpB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,EAAE,GAAG,EAAE;IAO7C;;;;;;;;;;;OAWG;cACa,oBAAoB,CAAC,CAAC,EACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,SAAS,EAClB,SAAS,EAAE;QAAE,SAAS,EAAE,MAAM,OAAO,iBAAiB,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GACtE,OAAO,CAAC,CAAC,CAAC;IAQb;;;;;;OAMG;cACa,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,SAAS,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC;IAYhB;;;;;;;;OAQG;cACa,eAAe,CAE7B,OAAO,EAAE,GAAG,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC;CAoB9B"}

package/dist/esm/modules/escrow-v2.d.ts

@@ -0,0 +1,169 @@
+/**
+ * @module escrow-v2
+ * @description V2 escrow settlement layer — supports settlement security
+ * modes (CoSigned, DisputeWindow), receipt-based dispute resolution,
+ * pending settlements, and automatic resolution via merkle proofs.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @packageDocumentation
+ */
+import { type PublicKey, type TransactionSignature, type AccountMeta, type Signer } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import { BaseModule } from "./base";
+import type { EscrowAccountV2Data, PendingSettlementData, DisputeRecordData, CreateEscrowV2Args } from "../types";
+import type { SettleOptions } from "../utils/priority-fee";
+/**
+ * @name EscrowV2Module
+ * @description Manages V2 escrow accounts with settlement security modes,
+ * dispute windows, and pending settlement flows.
+ *
+ * @category Modules
+ * @since v0.7.0
+ * @extends BaseModule
+ */
+export declare class EscrowV2Module extends BaseModule {
+    /** Convert BN | number | bigint → number for PDA seed functions. */
+    private toNum;
+    deriveEscrow(agentPda: PublicKey, depositor?: PublicKey, nonce?: BN | number | bigint): readonly [PublicKey, number];
+    derivePendingSettlement(escrowV2Pda: PublicKey, settlementIndex: BN | number | bigint): readonly [PublicKey, number];
+    deriveDispute(pendingSettlementPda: PublicKey): readonly [PublicKey, number];
+    create(agentWallet: PublicKey, args: CreateEscrowV2Args, splAccounts?: AccountMeta[]): Promise<TransactionSignature>;
+    deposit(agentWallet: PublicKey, nonce: BN | number | bigint, amount: BN | number | bigint, splAccounts?: AccountMeta[]): Promise<TransactionSignature>;
+    /**
+     * Settle a batch of calls against a V2 escrow.
+     *
+     * **v0.13.0 — Auto-bundle DisputeWindow:** when the escrow's
+     * `settlementSecurity` is `DisputeWindow`, this method now bundles
+     * **`settleCallsV2` + `createPendingSettlement`** into the SAME
+     * transaction. This eliminates the foot-gun where a caller would call
+     * `createPendingSettlement` directly without a preceding `settleCallsV2`,
+     * leaving `escrow.pending_amount = 0` and causing `finalizeSettlement`
+     * to abort with `ArithmeticOverflow` (6075).
+     *
+     * Flow per security mode:
+     * - **CoSigned** — single IX (`settleCallsV2`) with co-signer in
+     *   remaining accounts; funds move immediately.
+     * - **DisputeWindow** — two IXs in one tx:
+     *   1. `settleCallsV2` — bumps `pending_amount` and `settlement_index`
+     *   2. `createPendingSettlement(idx)` — locks the dispute tracker PDA
+     *
+     *   After this tx confirms, wait `escrow.disputeWindowSlots` slots and
+     *   call {@link finalizeSettlement} with the index returned via
+     *   `SettlementPendingEvent` or readable from `escrow.settlement_index - 1`.
+     *
+     * Pass `opts.skipAutoPending = true` to opt out of the auto-bundle (e.g.
+     * if you want to drive `createPendingSettlement` separately for advanced
+     * flows like batched off-chain receipt aggregation).
+     *
+     * @param depositorWallet - Depositor of the escrow being settled.
+     * @param nonce - Escrow nonce (default 0 for the canonical escrow).
+     * @param callsToSettle - Number of calls to settle in this batch.
+     * @param serviceHash - 32-byte sha256 of the service payload.
+     * @param splAccounts - Optional remaining accounts (SPL transfer + co-signer).
+     * @param opts - Priority-fee + auto-pending options.
+     * @param coSigner - Required for CoSigned escrows.
+     * @returns The transaction signature.
+     * @since v0.7.0 — initial release
+     * @since v0.13.0 — auto-bundles `createPendingSettlement` for DisputeWindow
+     */
+    settle(depositorWallet: PublicKey, nonce: BN | number | bigint, callsToSettle: BN | number | bigint, serviceHash: number[], splAccounts?: AccountMeta[], opts?: SettleOptions & {
+        /**
+         * v0.13.0 — Opt out of the DisputeWindow auto-bundle. When `true`,
+         * `settle()` only emits `settleCallsV2` and the caller is responsible
+         * for sending `createPendingSettlement` afterwards (legacy 2-tx flow).
+         * Default: `false` (auto-bundle is on).
+         */
+        skipAutoPending?: boolean;
+        /**
+         * v0.13.0 — `receiptMerkleRoot` to inscribe in the auto-bundled
+         * `createPendingSettlement`. Defaults to 32 zero bytes (no receipt
+         * batch). Ignored when `skipAutoPending = true`.
+         */
+        receiptMerkleRoot?: number[];
+    }, coSigner?: Signer): Promise<TransactionSignature>;
+    /**
+     * Read the current `escrow.settlement_index` from chain.
+     *
+     * In DisputeWindow mode (`settlementSecurity = 2`), every successful
+     * `settleCallsV2` increments this value. The PRE-increment value is the
+     * one to pass to {@link createPendingSettlement} for that batch.
+     *
+     * @returns the current `settlementIndex` as `bigint` (next index to use
+     *   for `createPendingSettlement` if you have NOT yet called `settle` for
+     *   it; if you HAVE just settled, subtract 1 — but prefer the event
+     *   `SettlementPendingEvent.settlement_index` over arithmetic).
+     * @since v0.12.8
+     */
+    nextSettlementIndex(agentWallet: PublicKey, depositorWallet: PublicKey, nonce: BN | number | bigint): Promise<bigint>;
+    /**
+     * Create the PendingSettlement PDA for a DisputeWindow batch.
+     *
+     * **v0.13.0 NOTE:** in almost all cases you should call
+     * {@link settle} instead — it auto-bundles `settleCallsV2 +
+     * createPendingSettlement` in a single transaction so the two
+     * cannot drift out of sync. Use this method standalone ONLY when
+     * you intentionally pass `skipAutoPending: true` to `settle()`
+     * (e.g. batched receipt-merkle aggregation across multiple
+     * `settleCallsV2` runs).
+     *
+     * Calling this without a preceding `settleCallsV2` (which bumps
+     * `escrow.pending_amount`) creates an orphan PDA whose
+     * `pending.amount > escrow.pending_amount` — `finalizeSettlement`
+     * will then abort with `ArithmeticOverflow` (6075) forever.
+     *
+     * @since v0.7.0
+     */
+    createPendingSettlement(agentWallet: PublicKey, depositorWallet: PublicKey, nonce: BN | number | bigint, settlementIndex: BN | number | bigint, callsToSettle: BN | number | bigint, amount: BN | number | bigint, serviceHash: number[], receiptMerkleRoot?: number[]): Promise<TransactionSignature>;
+    finalizeSettlement(agentWallet: PublicKey, depositorWallet: PublicKey, nonce: BN | number | bigint, settlementIndex: BN | number | bigint): Promise<TransactionSignature>;
+    /**
+     * Identify orphan PendingSettlement PDAs that cannot be finalized.
+     *
+     * @returns `null` if the PDA is finalizable (or already finalized / disputed).
+     *          Otherwise an object describing the inconsistency, suitable for
+     *          logging or feeding into a quarantine list. Use this from a
+     *          recovery script to scan a range of `settlement_index` values:
+     *
+     * ```ts
+     * for (let idx = 0n; idx < currentIdx; idx++) {
+     *   const orphan = await sap.escrowV2.diagnoseOrphanPending(
+     *     agentWallet, depositorWallet, nonce, idx,
+     *   );
+     *   if (orphan) log.warn({ idx, ...orphan }, "skip orphan");
+     * }
+     * ```
+     *
+     * @since v0.12.9
+     */
+    diagnoseOrphanPending(agentWallet: PublicKey, depositorWallet: PublicKey, nonce: BN | number | bigint, settlementIndex: BN | number | bigint): Promise<{
+        pendingPda: PublicKey;
+        psAmount: bigint;
+        escrowPendingAmount: bigint;
+        escrowBalance: bigint;
+        isFinalized: boolean;
+        isDisputed: boolean;
+        reason: "ok" | "missing" | "amount_exceeds_pending" | "amount_exceeds_balance" | "already_finalized" | "disputed";
+    } | null>;
+    fileDispute(agentWallet: PublicKey, nonce: BN | number | bigint, settlementIndex: BN | number | bigint, evidenceHash: number[], disputeType?: number): Promise<TransactionSignature>;
+    /**
+     * @deprecated Since v0.7.0 — Arbiter-based resolution removed.
+     * Use {@link ReceiptModule.submitReceiptProof} + {@link ReceiptModule.autoResolveDispute} instead.
+     */
+    resolveDispute(_depositorWallet: PublicKey, _agentWallet: PublicKey, _nonce: BN | number | bigint, _settlementIndex: BN | number | bigint, _outcome: number): Promise<TransactionSignature>;
+    closeDispute(pendingSettlementPda: PublicKey): Promise<TransactionSignature>;
+    closePendingSettlement(pendingSettlementPda: PublicKey): Promise<TransactionSignature>;
+    withdraw(agentWallet: PublicKey, nonce: BN | number | bigint, amount: BN | number | bigint): Promise<TransactionSignature>;
+    close(agentWallet: PublicKey, nonce?: BN | number | bigint): Promise<TransactionSignature>;
+    /**
+     * @deprecated Since v0.7.0 — Migration instruction removed from program.
+     */
+    migrateFromV1(_agentWallet: PublicKey): Promise<TransactionSignature>;
+    fetch(agentPda: PublicKey, depositor?: PublicKey, nonce?: BN | number | bigint): Promise<EscrowAccountV2Data>;
+    fetchNullable(agentPda: PublicKey, depositor?: PublicKey, nonce?: BN | number | bigint): Promise<EscrowAccountV2Data | null>;
+    fetchByPda(escrowPda: PublicKey): Promise<EscrowAccountV2Data>;
+    fetchPendingSettlement(pendingPda: PublicKey): Promise<PendingSettlementData>;
+    fetchPendingSettlementNullable(pendingPda: PublicKey): Promise<PendingSettlementData | null>;
+    fetchDispute(disputePda: PublicKey): Promise<DisputeRecordData>;
+    fetchDisputeNullable(disputePda: PublicKey): Promise<DisputeRecordData | null>;
+}
+//# sourceMappingURL=escrow-v2.d.ts.map

package/dist/esm/modules/escrow-v2.d.ts.map

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

package/dist/esm/modules/feedback.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @module feedback
+ * @description Trustless reputation system — give, update, revoke, and close
+ *   on-chain feedback entries for agents.
+ *
+ * Feedback entries are PDA-based reviews tied to an agent and a reviewer wallet,
+ * enabling permissionless, verifiable reputation on Solana.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @packageDocumentation
+ */
+import { type PublicKey, type TransactionSignature } from "@solana/web3.js";
+import { BaseModule } from "./base";
+import type { FeedbackAccountData, GiveFeedbackArgs, UpdateFeedbackArgs } from "../types";
+/**
+ * @name FeedbackModule
+ * @description Manages on-chain feedback entries for the Synapse Agent Protocol.
+ *   Provides methods to give, update, revoke, close, and fetch feedback PDAs
+ *   that form the trustless reputation layer.
+ *
+ * @category Modules
+ * @since v0.1.0
+ * @extends BaseModule
+ *
+ * @example
+ * ```ts
+ * const sap = new SapClient(provider);
+ * const sig = await sap.feedback.give(agentWallet, {
+ *   score: 5,
+ *   tag: { quality: {} },
+ *   commentHash: null,
+ * });
+ * ```
+ */
+export declare class FeedbackModule extends BaseModule {
+    /**
+     * @name deriveFeedback
+     * @description Derive the `FeedbackAccount` PDA for a given agent and reviewer.
+     * @param agentPda - The agent account PDA to review.
+     * @param reviewer - The reviewer wallet. Defaults to the connected wallet.
+     * @returns A tuple of `[PublicKey, bump]` for the feedback PDA.
+     * @see {@link deriveFeedback} from `pda/` module for the underlying derivation.
+     * @since v0.1.0
+     */
+    deriveFeedback(agentPda: PublicKey, reviewer?: PublicKey): readonly [PublicKey, number];
+    /**
+     * @name give
+     * @description Leave on-chain feedback for an agent. Creates a new
+     *   `FeedbackAccount` PDA owned by the reviewer.
+     * @param agentWallet - The wallet that owns the target agent.
+     * @param args - Feedback parameters (score, tag, optional comment hash).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    give(agentWallet: PublicKey, args: GiveFeedbackArgs): Promise<TransactionSignature>;
+    /**
+     * @name update
+     * @description Update an existing feedback entry. Only the original reviewer
+     *   may update their feedback.
+     * @param agentWallet - The wallet that owns the target agent.
+     * @param args - Updated feedback parameters (new score, optional new tag, optional comment hash).
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    update(agentWallet: PublicKey, args: UpdateFeedbackArgs): Promise<TransactionSignature>;
+    /**
+     * @name revoke
+     * @description Revoke a feedback entry, marking it as revoked and excluding
+     *   it from reputation calculations.
+     * @param agentWallet - The wallet that owns the target agent.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    revoke(agentWallet: PublicKey): Promise<TransactionSignature>;
+    /**
+     * @name close
+     * @description Close a revoked feedback PDA and reclaim rent to the reviewer.
+     * @param agentWallet - The wallet that owns the target agent.
+     * @returns {Promise<TransactionSignature>} The transaction signature.
+     * @since v0.1.0
+     */
+    close(agentWallet: PublicKey): Promise<TransactionSignature>;
+    /**
+     * @name fetch
+     * @description Fetch a deserialized `FeedbackAccount`.
+     * @param agentPda - The agent account PDA.
+     * @param reviewer - The reviewer wallet. Defaults to the connected wallet.
+     * @returns {Promise<FeedbackAccountData>} The feedback account data.
+     * @throws Will throw if the feedback account does not exist.
+     * @since v0.1.0
+     */
+    fetch(agentPda: PublicKey, reviewer?: PublicKey): Promise<FeedbackAccountData>;
+    /**
+     * @name fetchNullable
+     * @description Fetch a deserialized `FeedbackAccount`, or `null` if it
+     *   does not exist on-chain.
+     * @param agentPda - The agent account PDA.
+     * @param reviewer - The reviewer wallet. Defaults to the connected wallet.
+     * @returns {Promise<FeedbackAccountData | null>} The feedback data or `null`.
+     * @since v0.1.0
+     */
+    fetchNullable(agentPda: PublicKey, reviewer?: PublicKey): Promise<FeedbackAccountData | null>;
+}
+//# sourceMappingURL=feedback.d.ts.map

package/dist/esm/modules/feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../../../src/modules/feedback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC3F,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE1F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,cAAe,SAAQ,UAAU;IAG5C;;;;;;;;OAQG;IACH,cAAc,CACZ,QAAQ,EAAE,SAAS,EACnB,QAAQ,CAAC,EAAE,SAAS,GACnB,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC;IAM/B;;;;;;;;OAQG;IACG,IAAI,CACR,WAAW,EAAE,SAAS,EACtB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,oBAAoB,CAAC;IAiBhC;;;;;;;;OAQG;IACG,MAAM,CACV,WAAW,EAAE,SAAS,EACtB,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,oBAAoB,CAAC;IAchC;;;;;;;OAOG;IACG,MAAM,CAAC,WAAW,EAAE,SAAS,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAcnE;;;;;;OAMG;IACG,KAAK,CAAC,WAAW,EAAE,SAAS,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAelE;;;;;;;;OAQG;IACG,KAAK,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAKpF;;;;;;;;OAQG;IACG,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;CAIpG"}

package/{src/modules/index.ts → dist/esm/modules/index.d.ts}

@@ -11,7 +11,6 @@
  * @since v0.1.0
  * @packageDocumentation
  */
-
 export { AgentModule } from "./agent";
 export { FeedbackModule } from "./feedback";
 export { IndexingModule } from "./indexing";
@@ -26,3 +25,4 @@ export { AttestationModule } from "./attestation";
 export { LedgerModule } from "./ledger";
 export { BaseModule } from "./base";
 export type { SapProgram, SapTransactionResult } from "./base";
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/modules/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,YAAY,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC"}