/**
 * @module utils/escrow-validation
 * @description Server-side escrow validation pipeline.
 *
 * Provides typed helpers to validate escrow state before settlement
 * and to build the correct SPL `AccountMeta[]` for token escrows.
 *
 * @category Utils
 * @since v0.6.4
 */
import { PublicKey, type Connection, type AccountMeta } from "@solana/web3.js";
import { SapError } from "../errors";
import type { EscrowAccountV2Data } from "../types";
/**
 * @interface SplAccountMeta
 * @description Typed SPL account metadata for escrow operations.
 * @category Utils
 * @since v0.6.4
 */
export interface SplAccountMeta {
    /** Account role in the escrow pipeline. */
    readonly kind: "escrowAta" | "depositorAta" | "tokenMint" | "tokenProgram";
    /** Account public key. */
    readonly pubkey: PublicKey;
    /** Whether this account is writable. */
    readonly writable: boolean;
}
/**
 * @interface EscrowValidationResult
 * @description Result of server-side escrow state validation.
 * @category Utils
 * @since v0.6.4
 */
export interface EscrowValidationResult {
    /** Whether the escrow is valid for settlement. */
    readonly valid: boolean;
    /** Escrow account data (if found). */
    readonly escrow: EscrowAccountV2Data | null;
    /** Escrow PDA address. */
    readonly escrowPda: PublicKey;
    /** Agent PDA address. */
    readonly agentPda: PublicKey;
    /** Whether this is an SPL token escrow (vs SOL). */
    readonly isSplEscrow: boolean;
    /** Generated SPL account metas (empty for SOL escrows). */
    readonly splAccounts: SplAccountMeta[];
    /** Validation errors (empty when valid). */
    readonly errors: string[];
}
/**
 * @name MissingEscrowAtaError
 * @description Thrown when an SPL escrow operation is missing required
 * Associated Token Accounts.
 * @category Errors
 * @since v0.6.4
 */
export declare class MissingEscrowAtaError extends SapError {
    /** The ATA address that is missing. */
    readonly ataAddress: string;
    /** Which side is missing: depositor or escrow. */
    readonly side: "depositor" | "escrow";
    constructor(ataAddress: string, side: "depositor" | "escrow");
}
/**
 * @name validateEscrowState
 * @description Validates that an escrow is in a correct state for settlement.
 *
 * Checks:
 * - Escrow PDA exists on-chain
 * - If SPL: depositor ATA exists, escrow ATA exists, token mint matches
 * - Balance >= requested settlement amount
 * - Escrow is not expired
 * - Max calls not exceeded
 *
 * @param connection  - Solana RPC connection.
 * @param agentWallet - The agent's wallet public key.
 * @param depositorWallet - The depositor's wallet public key.
 * @param fetchEscrow - Callback to fetch escrow data (avoids coupling to SapProgram).
 * @param opts
 * @param opts.callsToSettle - Number of calls to validate affordability for.
 *
 * @returns A detailed {@link EscrowValidationResult}.
 *
 * @category Utils
 * @since v0.6.4
 *
 * @example
 * ```ts
 * const result = await validateEscrowState(
 *   connection,
 *   agentWallet,
 *   depositorWallet,
 *   (pda) => client.escrow.fetchByPda(pda),
 *   { callsToSettle: 5 },
 * );
 *
 * if (!result.valid) {
 *   console.error("Escrow validation failed:", result.errors);
 * }
 * ```
 */
export declare function validateEscrowState(connection: Connection, agentWallet: PublicKey, depositorWallet: PublicKey, fetchEscrow: (escrowPda: PublicKey) => Promise<EscrowAccountV2Data | null>, opts?: {
    callsToSettle?: number;
}): Promise<EscrowValidationResult>;
/**
 * @name attachSplAccounts
 * @description Build the typed `SplAccountMeta[]` for an SPL token escrow operation.
 * Does NOT validate existence — use {@link validateEscrowState} for full validation.
 *
 * @param escrowPda      - The escrow PDA address.
 * @param depositorWallet - The depositor's wallet public key.
 * @param tokenMint      - The SPL token mint.
 * @returns An array of typed {@link SplAccountMeta} for SPL escrow operations.
 *
 * @category Utils
 * @since v0.6.4
 *
 * @example
 * ```ts
 * const splMetas = attachSplAccounts(escrowPda, depositorWallet, usdcMint);
 *
 * // Convert to Anchor-compatible AccountMeta[]
 * const accountMetas = splMetas.map(m => ({
 *   pubkey: m.pubkey,
 *   isWritable: m.writable,
 *   isSigner: false,
 * }));
 *
 * await client.escrow.settle(depositor, calls, hash, accountMetas);
 * ```
 */
export declare function attachSplAccounts(escrowPda: PublicKey, depositorWallet: PublicKey, tokenMint: PublicKey): SplAccountMeta[];
/**
 * @name toAccountMetas
 * @description Convert typed {@link SplAccountMeta} to Anchor-compatible
 * `AccountMeta[]` for use with `.remainingAccounts()`.
 *
 * @param splMetas - Array of typed SPL account metas.
 * @returns `AccountMeta[]` compatible with Anchor's `remainingAccounts`.
 *
 * @category Utils
 * @since v0.6.4
 */
export declare function toAccountMetas(splMetas: SplAccountMeta[]): AccountMeta[];
//# sourceMappingURL=escrow-validation.d.ts.map