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

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/base.js

@@ -0,0 +1,185 @@
+/**
+ * @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";
+import { decodeAnchorError, SapPreflightError, throwPredicted, } from "../utils/anchor-errors";
+/**
+ * @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());
+    }
+    // ── v0.13.0 preflight helpers ─────────────────────────
+    /**
+     * @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
+     */
+    async requireAccountExists(accountName, address, onMissing) {
+        const acc = await this.fetchAccountNullable(accountName, address);
+        if (acc == null) {
+            throwPredicted(onMissing.predicted, onMissing.hint ?? `${accountName} ${address.toBase58()} not found`);
+        }
+        return acc;
+    }
+    /**
+     * @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
+     */
+    async requireAccountAbsent(accountName, address, hint) {
+        const acc = await this.provider.connection.getAccountInfo(address);
+        if (acc !== null) {
+            throw new SapPreflightError(`${accountName} ${address.toBase58()} already exists. ${hint}`, 0, "AccountAlreadyInUse", hint);
+        }
+    }
+    /**
+     * @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
+     */
+    async simulateOrThrow(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    builder, label) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+            const sim = await builder.simulate();
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+            const logs = (sim?.raw ?? sim?.logs ?? []);
+            return logs;
+        }
+        catch (err) {
+            const decoded = decodeAnchorError(err);
+            if (decoded) {
+                throw new SapPreflightError(`[${label}] simulation failed: ${decoded.friendly}`, decoded.code, decoded.name, decoded.logs?.slice(0, 6).join(" | "));
+            }
+            throw err;
+        }
+    }
+}
+//# 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;AAE1E,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,GAEf,MAAM,wBAAwB,CAAC;AA0BhC;;;;;;;;;;;;;;;;;;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;IAED,yDAAyD;IAEzD;;;;;;;;;;;OAWG;IACO,KAAK,CAAC,oBAAoB,CAClC,WAAmB,EACnB,OAAkB,EAClB,SAAuE;QAEvE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,oBAAoB,CAAI,WAAW,EAAE,OAAO,CAAC,CAAC;QACrE,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;YAChB,cAAc,CAAC,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC,IAAI,IAAI,GAAG,WAAW,IAAI,OAAO,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;QAC1G,CAAC;QACD,OAAO,GAAQ,CAAC;IAClB,CAAC;IAED;;;;;;OAMG;IACO,KAAK,CAAC,oBAAoB,CAClC,WAAmB,EACnB,OAAkB,EAClB,IAAY;QAEZ,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QACnE,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACjB,MAAM,IAAI,iBAAiB,CACzB,GAAG,WAAW,IAAI,OAAO,CAAC,QAAQ,EAAE,oBAAoB,IAAI,EAAE,EAC9D,CAAC,EACD,qBAAqB,EACrB,IAAI,CACL,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACO,KAAK,CAAC,eAAe;IAC7B,8DAA8D;IAC9D,OAAY,EACZ,KAAa;QAEb,IAAI,CAAC;YACH,yGAAyG;YACzG,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;YACrC,sEAAsE;YACtE,MAAM,IAAI,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,EAAE,IAAI,IAAI,EAAE,CAAsB,CAAC;YAChE,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;YACvC,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,IAAI,iBAAiB,CACzB,IAAI,KAAK,wBAAwB,OAAO,CAAC,QAAQ,EAAE,EACnD,OAAO,CAAC,IAAI,EACZ,OAAO,CAAC,IAAI,EACZ,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CACtC,CAAC;YACJ,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;CACF"}

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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"}