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

package/src/modules/escrow-v2.ts

@@ -39,6 +39,8 @@ import {
 } from "../utils/priority-fee";
 import type { SettleOptions } from "../utils/priority-fee";
 import { isAcceptedPaymentToken, computeRequiredStakeLamports } from "../constants/payments";
+import { throwPredicted } from "../utils/anchor-errors";
+import { calculateSettleAmount } from "../utils/volume-curve";
 
 /**
  * @name EscrowV2Module
@@ -221,6 +223,22 @@ export class EscrowV2Module extends BaseModule {
     const [agentPda] = deriveAgent(agentWallet);
     const [escrowPda] = this.deriveEscrow(agentPda, undefined, nonce);
 
+    // v0.13.0 preflights — escrow exists, token shape matches, amount > 0
+    const escrow = await this.requireAccountExists<EscrowAccountV2Data>(
+      "escrowAccountV2",
+      escrowPda,
+      { predicted: "NotAuthority", hint: "Escrow V2 PDA not found — call createEscrow first" },
+    );
+    const want = BigInt(this.bn(amount).toString());
+    if (want <= 0n) throwPredicted("InsufficientEscrowBalance", "Deposit amount must be > 0");
+    const isSpl = escrow.tokenMint != null;
+    if (isSpl && splAccounts.length < 4) {
+      throwPredicted("SplTokenRequired", "Pass [depositorAta, escrowAta, tokenMint, tokenProgram]");
+    }
+    if (!isSpl && splAccounts.length > 0) {
+      throwPredicted("InvalidTokenAccount", "SOL escrow does not accept splAccounts");
+    }
+
     return this.methods
       .depositEscrowV2(this.bn(nonce), this.bn(amount))
       .accounts({
@@ -232,13 +250,64 @@ export class EscrowV2Module extends BaseModule {
       .rpc();
   }
 
+  /**
+   * 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
+   */
   async settle(
     depositorWallet: PublicKey,
     nonce: BN | number | bigint,
     callsToSettle: BN | number | bigint,
     serviceHash: number[],
     splAccounts: AccountMeta[] = [],
-    opts?: SettleOptions,
+    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> {
     const [agentPda] = deriveAgent(this.walletPubkey);
@@ -260,6 +329,28 @@ export class EscrowV2Module extends BaseModule {
         ]
       : splAccounts;
 
+    // ── v0.13.0 preflight: fetch escrow once to drive both branches ──
+    // We need it to (a) detect DisputeWindow vs CoSigned, (b) read the
+    // current `settlement_index` to feed `createPendingSettlement`, and
+    // (c) compute `amount` via the volume curve so the bundled IX matches
+    // what `settle_calls_v2` will compute on-chain.
+    const escrowAcc = await this.fetchAccountNullable<EscrowAccountV2Data>(
+      "escrowAccountV2",
+      escrowPda,
+    );
+    if (!escrowAcc) {
+      throw new Error(
+        `escrowV2.settle: escrow PDA ${escrowPda.toBase58()} not found on-chain ` +
+          `(agent=${agentPda.toBase58()}, depositor=${depositorWallet.toBase58()}, nonce=${this.bn(nonce).toString()}). ` +
+          `Did the depositor call escrowV2.create() yet?`,
+      );
+    }
+
+    const isDisputeWindow =
+      typeof escrowAcc.settlementSecurity === "object" &&
+      escrowAcc.settlementSecurity !== null &&
+      "disputeWindow" in (escrowAcc.settlementSecurity as Record<string, unknown>);
+
     let builder = this.methods
       .settleCallsV2(this.bn(nonce), this.bn(callsToSettle), serviceHash)
       .accountsPartial({
@@ -280,6 +371,71 @@ export class EscrowV2Module extends BaseModule {
       builder = builder.preInstructions(preIxs);
     }
 
+    // ── v0.13.0: auto-bundle createPendingSettlement on DisputeWindow ──
+    // The on-chain `settle_calls_v2_handler` (DisputeWindow branch) only
+    // bumps `escrow.pending_amount` and `escrow.settlement_index` — it
+    // does NOT create the PendingSettlement PDA. Without the followup
+    // `createPendingSettlement` IX in the SAME tx, a buggy caller can
+    // (a) call `createPendingSettlement` later with a stale index, or
+    // (b) skip `settleCallsV2` entirely on a fresh escrow → orphan PDA
+    // whose `amount > escrow.pending_amount` → finalize aborts forever
+    // with `ArithmeticOverflow` (6075). Bundling is the only way to
+    // make that race impossible.
+    const skipAutoPending = opts?.skipAutoPending === true;
+    if (isDisputeWindow && !skipAutoPending) {
+      // PRE-increment settlement_index — settle_calls_v2 will bump it
+      // to (current + 1) AFTER our IX runs, but the PDA seed used by
+      // create_pending_settlement is the PRE-increment value (matches
+      // `SettlementPendingEvent.settlement_index`).
+      const settlementIndex = escrowAcc.settlementIndex;
+
+      // Mirror the on-chain volume-curve math so `pending.amount`
+      // matches what `escrow.pending_amount` was bumped by.
+      const totalCallsBefore = escrowAcc.totalCallsSettled.add(escrowAcc.pendingCalls);
+      const amount = calculateSettleAmount(
+        escrowAcc.pricePerCall,
+        escrowAcc.volumeCurve,
+        totalCallsBefore,
+        this.bn(callsToSettle),
+      );
+
+      const [pendingPda] = this.derivePendingSettlement(escrowPda, settlementIndex);
+
+      // Defensive: if a stale pending PDA exists at this index (orphan
+      // from an aborted prior run), refuse to send — otherwise the IX
+      // will fail with `Allocate: account already in use` (custom 0x0).
+      const existing = await this.provider.connection.getAccountInfo(pendingPda);
+      if (existing) {
+        throw new Error(
+          `escrowV2.settle (auto-bundle): pending PDA ${pendingPda.toBase58()} ` +
+            `already exists for settlementIndex=${settlementIndex.toString()}. ` +
+            `An earlier run created it but did not finalize. Either finalize ` +
+            `that index first or skip it permanently. (Pass skipAutoPending=true ` +
+            `to bypass this guard and emit only settleCallsV2.)`,
+        );
+      }
+
+      const receiptMerkleRoot = opts?.receiptMerkleRoot ?? new Array(32).fill(0);
+      const pendingIx = await this.methods
+        .createPendingSettlement(
+          settlementIndex,
+          this.bn(callsToSettle),
+          amount,
+          serviceHash,
+          receiptMerkleRoot,
+        )
+        .accounts({
+          wallet: this.walletPubkey,
+          agent: agentPda,
+          escrow: escrowPda,
+          pendingSettlement: pendingPda,
+          systemProgram: SystemProgram.programId,
+        })
+        .instruction();
+
+      builder = builder.postInstructions([pendingIx]);
+    }
+
     return builder.rpc(rpcOpts);
   }
 
@@ -315,6 +471,24 @@ export class EscrowV2Module extends BaseModule {
     return BigInt(escrow.settlementIndex.toString());
   }
 
+  /**
+   * 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
+   */
   async createPendingSettlement(
     agentWallet: PublicKey,
     depositorWallet: PublicKey,
@@ -574,6 +748,25 @@ export class EscrowV2Module extends BaseModule {
     const [agentPda] = deriveAgent(agentWallet);
     const [escrowPda] = this.deriveEscrow(agentPda, undefined, nonce);
 
+    // v0.13.0 preflight — amount must fit (balance - pendingAmount); the
+    // on-chain handler subtracts pending_amount from withdrawable funds.
+    const escrow = await this.requireAccountExists<EscrowAccountV2Data>(
+      "escrowAccountV2",
+      escrowPda,
+      { predicted: "NotAuthority", hint: "Escrow V2 PDA not found" },
+    );
+    const want = BigInt(this.bn(amount).toString());
+    if (want <= 0n) throwPredicted("InsufficientEscrowBalance", "Withdraw amount must be > 0");
+    const balance = BigInt(escrow.balance.toString());
+    const pending = BigInt(escrow.pendingAmount.toString());
+    const free = balance > pending ? balance - pending : 0n;
+    if (want > free) {
+      throwPredicted(
+        "InsufficientEscrowBalance",
+        `requested ${want}, withdrawable ${free} (balance ${balance} − pending ${pending})`,
+      );
+    }
+
     return this.methods
       .withdrawEscrowV2(this.bn(amount))
       .accounts({
@@ -590,6 +783,26 @@ export class EscrowV2Module extends BaseModule {
     const [agentPda] = deriveAgent(agentWallet);
     const [escrowPda] = this.deriveEscrow(agentPda, undefined, nonce);
 
+    // v0.13.0 preflight — close fails if balance != 0 OR pending_amount != 0.
+    // Pending != 0 commonly indicates orphan PendingSettlement PDAs;
+    // run diagnoseOrphanPending() across the index range to identify them.
+    const escrow = await this.requireAccountExists<EscrowAccountV2Data>(
+      "escrowAccountV2",
+      escrowPda,
+      { predicted: "NotAuthority", hint: "Escrow V2 PDA already closed" },
+    );
+    const balance = BigInt(escrow.balance.toString());
+    const pending = BigInt(escrow.pendingAmount.toString());
+    if (balance !== 0n) {
+      throwPredicted("EscrowNotEmpty", `balance ${balance} > 0 — withdraw first`);
+    }
+    if (pending !== 0n) {
+      throwPredicted(
+        "EscrowNotClosed",
+        `pending_amount ${pending} > 0 — finalize all PendingSettlements first or quarantine orphans via diagnoseOrphanPending`,
+      );
+    }
+
     return this.methods
       .closeEscrowV2()
       .accounts({

package/src/modules/escrow.ts

@@ -39,6 +39,7 @@ import {
 import type { SettleOptions } from "../utils/priority-fee";
 import { computeBatchRoot, hashToArray } from "../utils/hash";
 import { isAcceptedPaymentToken } from "../constants/payments";
+import { throwPredicted } from "../utils/anchor-errors";
 
 /**
  * @name EscrowModule
@@ -160,6 +161,24 @@ export class EscrowModule extends BaseModule {
     const [agentPda] = deriveAgent(agentWallet);
     const [escrowPda] = this.deriveEscrow(agentPda);
 
+    // v0.13.0 preflight — escrow must exist; SPL deposits must include the
+    // 4 expected remaining accounts; SOL deposits must NOT include them.
+    const escrow = await this.requireAccountExists<EscrowAccountData>(
+      "escrowAccount",
+      escrowPda,
+      { predicted: "NotAuthority", hint: "Escrow PDA not found — call createEscrow first" },
+    );
+    const isSpl = escrow.tokenMint != null;
+    if (isSpl && splAccounts.length < 4) {
+      throwPredicted("SplTokenRequired", "Pass [depositorAta, escrowAta, tokenMint, tokenProgram] in splAccounts");
+    }
+    if (!isSpl && splAccounts.length > 0) {
+      throwPredicted("InvalidTokenAccount", "SOL escrow does not accept splAccounts; pass an empty array");
+    }
+    if (BigInt(this.bn(amount).toString()) <= 0n) {
+      throwPredicted("InsufficientEscrowBalance", "Deposit amount must be > 0");
+    }
+
     return this.methods
       .depositEscrow(this.bn(amount))
       .accounts({
@@ -235,6 +254,30 @@ export class EscrowModule extends BaseModule {
     const [agentPda] = deriveAgent(agentWallet);
     const [escrowPda] = this.deriveEscrow(agentPda);
 
+    // v0.13.0 preflight — verify balance covers amount, token program shape
+    // matches, and depositor matches the on-chain depositor.
+    const escrow = await this.requireAccountExists<EscrowAccountData>(
+      "escrowAccount",
+      escrowPda,
+      { predicted: "NotAuthority", hint: "Escrow PDA not found" },
+    );
+    const wantBN = this.bn(amount);
+    const want = BigInt(wantBN.toString());
+    if (want <= 0n) throwPredicted("InsufficientEscrowBalance", "Withdraw amount must be > 0");
+    if (want > BigInt(escrow.balance.toString())) {
+      throwPredicted(
+        "InsufficientEscrowBalance",
+        `requested ${want}, escrow.balance ${escrow.balance.toString()}`,
+      );
+    }
+    const isSpl = escrow.tokenMint != null;
+    if (isSpl && splAccounts.length < 4) {
+      throwPredicted("SplTokenRequired", "Pass [depositorAta, escrowAta, tokenMint, tokenProgram]");
+    }
+    if (!isSpl && splAccounts.length > 0) {
+      throwPredicted("InvalidTokenAccount", "SOL escrow does not accept splAccounts");
+    }
+
     return this.methods
       .withdrawEscrow(this.bn(amount))
       .accounts({
@@ -257,6 +300,19 @@ export class EscrowModule extends BaseModule {
     const [agentPda] = deriveAgent(agentWallet);
     const [escrowPda] = this.deriveEscrow(agentPda);
 
+    // v0.13.0 preflight — close fails on-chain if balance != 0.
+    const escrow = await this.requireAccountExists<EscrowAccountData>(
+      "escrowAccount",
+      escrowPda,
+      { predicted: "NotAuthority", hint: "Escrow PDA already closed or never created" },
+    );
+    if (BigInt(escrow.balance.toString()) !== 0n) {
+      throwPredicted(
+        "EscrowNotEmpty",
+        `balance ${escrow.balance.toString()} > 0 — withdraw remaining funds first`,
+      );
+    }
+
     return this.methods
       .closeEscrow()
       .accounts({

package/src/modules/staking.ts

@@ -21,6 +21,7 @@ import {
   MIN_AGENT_STAKE_LAMPORTS,
   computeRequiredStakeLamports,
 } from "../constants/payments";
+import { throwPredicted } from "../utils/anchor-errors";
 
 /**
  * @name StakingModule
@@ -46,6 +47,20 @@ export class StakingModule extends BaseModule {
     const [agentPda] = deriveAgent(agentWallet);
     const [stakePda] = this.deriveStake(agentPda);
 
+    // v0.13.0 preflights
+    const want = BigInt(this.bn(initialDeposit).toString());
+    if (want < MIN_AGENT_STAKE_LAMPORTS) {
+      throwPredicted(
+        "StakeBelowMinimum",
+        `initial deposit ${want} < MIN_AGENT_STAKE_LAMPORTS ${MIN_AGENT_STAKE_LAMPORTS}`,
+      );
+    }
+    await this.requireAccountAbsent(
+      "agentStake",
+      stakePda,
+      "Stake already initialized — use depositStake to top up",
+    );
+
     return this.methods
       .initStake(this.bn(initialDeposit))
       .accounts({
@@ -64,6 +79,16 @@ export class StakingModule extends BaseModule {
     const [agentPda] = deriveAgent(agentWallet);
     const [stakePda] = this.deriveStake(agentPda);
 
+    // v0.13.0 preflight — stake must already exist; amount > 0
+    if (BigInt(this.bn(amount).toString()) <= 0n) {
+      throwPredicted("InsufficientStake", "Deposit amount must be > 0");
+    }
+    await this.requireAccountExists<AgentStakeData>(
+      "agentStake",
+      stakePda,
+      { predicted: "NoStakeAccount", hint: "Call initStake first" },
+    );
+
     return this.methods
       .depositStake(this.bn(amount))
       .accounts({
@@ -82,6 +107,28 @@ export class StakingModule extends BaseModule {
     const [agentPda] = deriveAgent(agentWallet);
     const [stakePda] = this.deriveStake(agentPda);
 
+    // v0.13.0 preflight — enforce MIN_STAKE floor + no double-pending
+    const stake = await this.requireAccountExists<AgentStakeData>(
+      "agentStake",
+      stakePda,
+      { predicted: "NoStakeAccount", hint: "No stake account to unstake from" },
+    );
+    const want = BigInt(this.bn(amount).toString());
+    if (want <= 0n) throwPredicted("InsufficientStake", "Unstake amount must be > 0");
+    const max = this.getMaxUnstakeLamports(stake);
+    if (want > max) {
+      throwPredicted(
+        "StakeBelowMinimum",
+        `requested ${want} would drop stake below MIN_AGENT_STAKE_LAMPORTS (max unstake = ${max})`,
+      );
+    }
+    if (BigInt(stake.unstakeAmount.toString()) > 0n) {
+      throwPredicted(
+        "UnstakeAlreadyPending",
+        "A pending unstake already exists — completeUnstake first or wait for cooldown",
+      );
+    }
+
     return this.methods
       .requestUnstake(this.bn(amount))
       .accounts({
@@ -98,6 +145,25 @@ export class StakingModule extends BaseModule {
     const [agentPda] = deriveAgent(agentWallet);
     const [stakePda] = this.deriveStake(agentPda);
 
+    // v0.13.0 preflight — cooldown must have elapsed and an unstake must be pending
+    const stake = await this.requireAccountExists<AgentStakeData>(
+      "agentStake",
+      stakePda,
+      { predicted: "NoStakeAccount", hint: "No stake account" },
+    );
+    const pending = BigInt(stake.unstakeAmount.toString());
+    if (pending === 0n) {
+      throwPredicted("NoUnstakePending", "Call requestUnstake first");
+    }
+    const availableAt = BigInt(stake.unstakeAvailableAt.toString());
+    const nowSec = BigInt(Math.floor(Date.now() / 1000));
+    if (nowSec < availableAt) {
+      throwPredicted(
+        "UnstakeCooldownNotMet",
+        `available at unix ${availableAt}, now ${nowSec} (Δ ${availableAt - nowSec}s)`,
+      );
+    }
+
     return this.methods
       .completeUnstake()
       .accounts({

package/src/modules/tools.ts

@@ -27,6 +27,7 @@ import type {
   InscribeToolSchemaArgs,
 } from "../types";
 import { sha256, hashToArray } from "../utils";
+import { throwPredicted } from "../utils/anchor-errors";
 
 /**
  * @name ToolsModule
@@ -85,6 +86,34 @@ export class ToolsModule extends BaseModule {
     const [toolPda] = deriveTool(agentPda, new Uint8Array(args.toolNameHash));
     const [globalPda] = deriveGlobalRegistry();
 
+    // v0.13.0 preflights — enforce SAP v0.2.0 hardening rules
+    if (!args.toolName || args.toolName.length === 0) {
+      throwPredicted("EmptyToolName");
+    }
+    if (Buffer.byteLength(args.toolName, "utf8") > 32) {
+      throwPredicted("ToolNameTooLong", `${Buffer.byteLength(args.toolName, "utf8")} > 32 bytes`);
+    }
+    // v0.2.0 hardening: every tool MUST publish a non-empty input/output schema
+    // hash. Zero-hash tools are not callable by automated clients (LLMs/routers).
+    const isZeroHash = (h: number[]): boolean => h.length === 32 && h.every((b) => b === 0);
+    if (!args.inputSchemaHash || args.inputSchemaHash.length !== 32 || isZeroHash(args.inputSchemaHash)) {
+      throwPredicted(
+        "InvalidSchemaHash",
+        "inputSchemaHash is empty/zero — v0.2.0 requires every tool to declare a JSON-Schema. Use publishByName() or precompute sha256(schemaJson).",
+      );
+    }
+    if (!args.outputSchemaHash || args.outputSchemaHash.length !== 32 || isZeroHash(args.outputSchemaHash)) {
+      throwPredicted(
+        "InvalidSchemaHash",
+        "outputSchemaHash is empty/zero — v0.2.0 requires every tool to declare a JSON-Schema.",
+      );
+    }
+    await this.requireAccountAbsent(
+      "toolDescriptor",
+      toolPda,
+      "Tool already published with this name; use update() to change schema/version",
+    );
+
     return this.methods
       .publishTool(
         args.toolName,
@@ -138,6 +167,20 @@ export class ToolsModule extends BaseModule {
     requiredParams: number,
     isCompound: boolean,
   ): Promise<TransactionSignature> {
+    // v0.13.0 preflight — reject empty schemas BEFORE hashing (otherwise the
+    // hash of an empty string slips past the publish() schema-hash check).
+    if (!inputSchema || inputSchema.trim().length === 0) {
+      throwPredicted(
+        "InvalidSchemaHash",
+        "inputSchema string is empty — pass a valid JSON-Schema (v0.2.0 requirement)",
+      );
+    }
+    if (!outputSchema || outputSchema.trim().length === 0) {
+      throwPredicted(
+        "InvalidSchemaHash",
+        "outputSchema string is empty — pass a valid JSON-Schema (v0.2.0 requirement)",
+      );
+    }
     return this.publish({
       toolName,
       toolNameHash: hashToArray(sha256(toolName)),

package/src/modules/vault.ts

@@ -29,6 +29,8 @@ import type {
   InscribeMemoryArgs,
   CompactInscribeArgs,
 } from "../types";
+import { MAX_DELEGATE_DURATION_SECS } from "../constants/payments";
+import { throwPredicted } from "../utils/anchor-errors";
 
 /**
  * @name VaultModule
@@ -360,6 +362,29 @@ export class VaultModule extends BaseModule {
     const [vaultPda] = deriveVault(agentPda);
     const [delegatePda] = deriveVaultDelegate(vaultPda, delegatePubkey);
 
+    // v0.13.0 preflight — on-chain rejects expiry > now + MAX_DELEGATE_DURATION_SECS
+    // (365 days). Catch this client-side instead of burning the tx.
+    const exp = typeof expiresAt === "bigint" ? expiresAt : BigInt(expiresAt);
+    const nowSec = BigInt(Math.floor(Date.now() / 1000));
+    if (exp <= nowSec) {
+      throwPredicted("DelegateExpired", `expiresAt ${exp} is in the past (now ${nowSec})`);
+    }
+    const maxExp = nowSec + BigInt(MAX_DELEGATE_DURATION_SECS);
+    if (exp > maxExp) {
+      throwPredicted(
+        "DelegateExpiryInvalid",
+        `expiresAt ${exp} > now+MAX (${maxExp}); cap is ${MAX_DELEGATE_DURATION_SECS}s (365 days)`,
+      );
+    }
+    if (permissions === 0) {
+      throwPredicted("InvalidDelegate", "permissions bitmask cannot be 0");
+    }
+    await this.requireAccountAbsent(
+      "vaultDelegate",
+      delegatePda,
+      "Delegate already exists — revokeDelegate first or use a different delegate wallet",
+    );
+
     return this.methods
       .addVaultDelegate(permissions, this.bn(expiresAt))
       .accounts({