@oobe-protocol-labs/synapse-sap-sdk 0.11.0 → 0.12.5

package/dist/types/utils/priority-fee.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"priority-fee.d.ts","sourceRoot":"","sources":["../../../src/utils/priority-fee.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,iBAAiB,CAAC;AAMzB;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,SAAU,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC,SAAU,CAAC;AAM1D;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAE3C;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IAEjC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;IAE9D;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAMD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,aAAa,CAKtD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,aAAa,CAK5D,CAAC;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,CAAC,EAAE,iBAAiB,GACzB,sBAAsB,EAAE,CAwB1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,IAAI,CAAC,EAAE,aAAa,GACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAgBrC"}
+{"version":3,"file":"priority-fee.d.ts","sourceRoot":"","sources":["../../../src/utils/priority-fee.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,iBAAiB,CAAC;AAMzB;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,SAAU,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC,SAAU,CAAC;AA8B1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAM/D;AAMD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAE3C;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IAEjC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;IAE9D;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAMD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,aAAa,CAKtD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,aAAa,CAK5D,CAAC;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,CAAC,EAAE,iBAAiB,GACzB,sBAAsB,EAAE,CAwB1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,IAAI,CAAC,EAAE,aAAa,GACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAgBrC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oobe-protocol-labs/synapse-sap-sdk",
-  "version": "0.11.0",
+  "version": "0.12.5",
   "description": "TypeScript SDK for the Synapse Agent Protocol (SAP v2) on Solana Mainnet/Devnet",
   "license": "MIT",
   "main": "dist/cjs/index.js",

package/src/constants/payments.ts

@@ -55,6 +55,59 @@ export const USDC_MINT_DEVNET = new PublicKey(
  */
 export const MIN_AGENT_STAKE_LAMPORTS = BigInt(100_000_000);
 
+/**
+ * Slash share applied on a lost dispute, in basis points.
+ * Mirrors `AgentStake::SLASH_BPS` on-chain (`5_000` = 50%).
+ *
+ * @name SLASH_BPS
+ * @category Constants
+ * @since v0.11.0
+ */
+export const SLASH_BPS = 5_000n;
+
+/**
+ * Stake coverage ratio enforced at `createEscrowV2` (basis points).
+ * Mirrors `AgentStake::STAKE_COVERAGE_BPS` on-chain. Currently equal to
+ * {@link SLASH_BPS} so the slash on a lost dispute is fully collateralised.
+ *
+ * @name STAKE_COVERAGE_BPS
+ * @category Constants
+ * @since v0.11.0
+ */
+export const STAKE_COVERAGE_BPS = SLASH_BPS;
+
+/**
+ * Unstake cooldown in seconds. Mirrors `AgentStake::UNSTAKE_COOLDOWN_SECONDS`
+ * on-chain (`604_800` = 7 days). Replaces the misnamed pre-v0.11
+ * `UNSTAKE_COOLDOWN_SLOTS` constant which was never used by handlers.
+ *
+ * @name UNSTAKE_COOLDOWN_SECONDS
+ * @category Constants
+ * @since v0.11.0
+ */
+export const UNSTAKE_COOLDOWN_SECONDS = 604_800;
+
+/**
+ * Required `staked_amount` (lamports) for an agent to accept an escrow of
+ * `escrowLamports`. Equal to `max(MIN_AGENT_STAKE_LAMPORTS,
+ *  escrowLamports * STAKE_COVERAGE_BPS / 10_000)`.
+ *
+ * Mirrors the on-chain check enforced in `create_escrow_v2` (v0.11 H-1).
+ * Use this to preflight an escrow create call and surface an actionable
+ * error before paying tx fees.
+ *
+ * @name computeRequiredStakeLamports
+ * @category Constants
+ * @since v0.11.0
+ */
+export function computeRequiredStakeLamports(escrowLamports: bigint): bigint {
+  if (escrowLamports < 0n) {
+    throw new RangeError("escrowLamports must be ≥ 0");
+  }
+  const coverage = (escrowLamports * STAKE_COVERAGE_BPS) / 10_000n;
+  return coverage > MIN_AGENT_STAKE_LAMPORTS ? coverage : MIN_AGENT_STAKE_LAMPORTS;
+}
+
 /**
  * Maximum delegate duration (seconds) accepted by `add_vault_delegate`.
  * Mirrors `VaultDelegate::MAX_DELEGATE_DURATION_SECS` on-chain

package/src/idl/synapse_agent_sap.json

@@ -598,6 +598,38 @@
               }
             ]
           }
+        },
+        {
+          "name": "agent_stake",
+          "docs": [
+            "v0.11 H-3: AgentStake is now a typed required account so the slash on",
+            "DepositorWins outcomes is guaranteed instead of silently skipped when",
+            "the caller forgets to pass it via remaining_accounts."
+          ],
+          "writable": true,
+          "pda": {
+            "seeds": [
+              {
+                "kind": "const",
+                "value": [
+                  115,
+                  97,
+                  112,
+                  95,
+                  115,
+                  116,
+                  97,
+                  107,
+                  101
+                ]
+              },
+              {
+                "kind": "account",
+                "path": "escrow.agent",
+                "account": "EscrowAccountV2"
+              }
+            ]
+          }
         }
       ],
       "args": []
@@ -2504,10 +2536,16 @@
         {
           "name": "wallet",
           "writable": true,
-          "signer": true
+          "signer": true,
+          "relations": [
+            "agent"
+          ]
         },
         {
           "name": "agent",
+          "docs": [
+            "v0.11 M-2: typed agent account."
+          ],
           "pda": {
             "seeds": [
               {
@@ -3647,10 +3685,16 @@
         {
           "name": "wallet",
           "writable": true,
-          "signer": true
+          "signer": true,
+          "relations": [
+            "agent"
+          ]
         },
         {
           "name": "agent",
+          "docs": [
+            "v0.11 M-2: typed agent account."
+          ],
           "pda": {
             "seeds": [
               {
@@ -4671,10 +4715,16 @@
         {
           "name": "wallet",
           "writable": true,
-          "signer": true
+          "signer": true,
+          "relations": [
+            "agent"
+          ]
         },
         {
           "name": "agent",
+          "docs": [
+            "v0.11 M-2: typed agent account — stake cannot be opened for a non-existent agent."
+          ],
           "pda": {
             "seeds": [
               {
@@ -6476,10 +6526,16 @@
       "accounts": [
         {
           "name": "wallet",
-          "signer": true
+          "signer": true,
+          "relations": [
+            "agent"
+          ]
         },
         {
           "name": "agent",
+          "docs": [
+            "v0.11 M-2: typed agent account."
+          ],
           "pda": {
             "seeds": [
               {
@@ -9256,6 +9312,19 @@
         198
       ]
     },
+    {
+      "name": "StakeClosedEvent",
+      "discriminator": [
+        212,
+        204,
+        207,
+        181,
+        185,
+        249,
+        134,
+        59
+      ]
+    },
     {
       "name": "StakeDepositedEvent",
       "discriminator": [
@@ -9412,6 +9481,19 @@
         57
       ]
     },
+    {
+      "name": "UnstakeCancelledEvent",
+      "discriminator": [
+        57,
+        228,
+        7,
+        42,
+        227,
+        64,
+        93,
+        51
+      ]
+    },
     {
       "name": "UnstakeCompletedEvent",
       "discriminator": [
@@ -10211,6 +10293,21 @@
       "code": 6143,
       "name": "DuplicateServiceHash",
       "msg": "dup service hash"
+    },
+    {
+      "code": 6144,
+      "name": "StakeBelowCoverage",
+      "msg": "stake under coverage"
+    },
+    {
+      "code": 6145,
+      "name": "StakeNotClosable",
+      "msg": "stake not closable"
+    },
+    {
+      "code": 6146,
+      "name": "AgentStakeAccountMissing",
+      "msg": "agent stake account missing"
     }
   ],
   "types": [
@@ -13436,6 +13533,33 @@
         ]
       }
     },
+    {
+      "name": "StakeClosedEvent",
+      "docs": [
+        "v0.11 L-3: emitted when an agent's stake account is closed and rent reclaimed."
+      ],
+      "type": {
+        "kind": "struct",
+        "fields": [
+          {
+            "name": "agent",
+            "type": "pubkey"
+          },
+          {
+            "name": "wallet",
+            "type": "pubkey"
+          },
+          {
+            "name": "returned_lamports",
+            "type": "u64"
+          },
+          {
+            "name": "timestamp",
+            "type": "i64"
+          }
+        ]
+      }
+    },
     {
       "name": "StakeDepositedEvent",
       "docs": [
@@ -14196,6 +14320,34 @@
         ]
       }
     },
+    {
+      "name": "UnstakeCancelledEvent",
+      "docs": [
+        "v0.11 L-2: emitted when a `deposit_stake` clears a previously requested",
+        "unstake (top-up = implicit cancel of the pending withdrawal)."
+      ],
+      "type": {
+        "kind": "struct",
+        "fields": [
+          {
+            "name": "agent",
+            "type": "pubkey"
+          },
+          {
+            "name": "wallet",
+            "type": "pubkey"
+          },
+          {
+            "name": "cancelled_amount",
+            "type": "u64"
+          },
+          {
+            "name": "timestamp",
+            "type": "i64"
+          }
+        ]
+      }
+    },
     {
       "name": "UnstakeCompletedEvent",
       "docs": [

package/src/index.ts

@@ -252,6 +252,7 @@ export {
   DEFAULT_SETTLE_PRIORITY_FEE,
   DEFAULT_SETTLE_COMPUTE_UNITS,
   DEFAULT_BATCH_SETTLE_COMPUTE_UNITS,
+  computeBatchSettleCu,
 } from "./utils";
 export type {
   PriorityFeeConfig,

package/src/modules/escrow-v2.ts

@@ -37,7 +37,7 @@ import {
   buildRpcOptions,
 } from "../utils/priority-fee";
 import type { SettleOptions } from "../utils/priority-fee";
-import { isAcceptedPaymentToken } from "../constants/payments";
+import { isAcceptedPaymentToken, computeRequiredStakeLamports } from "../constants/payments";
 
 /**
  * @name EscrowV2Module
@@ -97,6 +97,54 @@ export class EscrowV2Module extends BaseModule {
     const [agentPda] = deriveAgent(agentWallet);
     const [escrowPda] = this.deriveEscrow(agentPda, undefined, args.escrowNonce);
     const [stakePda] = deriveStake(agentPda);
+    // v0.11 H-1 preflight: surface an actionable error if the agent's stake
+    // does not cover the slashable share of the new escrow. Saves a failed
+    // tx fee and gives the caller a clear top-up amount.
+    try {
+      const stakeAccount = await this.fetchAccountNullable<{ stakedAmount: BN }>("agentStake", stakePda);
+      if (stakeAccount) {
+        const escrowLamports = BigInt(this.bn(args.initialDeposit).toString());
+        const required = computeRequiredStakeLamports(escrowLamports);
+        const have = BigInt(stakeAccount.stakedAmount.toString());
+        if (have < required) {
+          throw new Error(
+            `createEscrowV2: agent stake ${have} lamports < required ${required} ` +
+            `lamports for escrow of ${escrowLamports} lamports. Top up via stakingModule.deposit.`,
+          );
+        }
+      }
+      // If no stake account exists at all, on-chain will reject with
+      // AccountNotInitialized — we let that bubble up unchanged.
+    } catch (err) {
+      // Preflight is advisory; rethrow only the explicit coverage error.
+      if (err instanceof Error && err.message.startsWith("createEscrowV2: agent stake")) {
+        throw err;
+      }
+    }
+    // v0.11 H-1 preflight: surface an actionable error if the agent's stake
+    // does not cover the slashable share of the new escrow. Saves a failed
+    // tx fee and gives the caller a clear top-up amount.
+    try {
+      const stakeAccount = await this.fetchAccountNullable<{ stakedAmount: BN }>("agentStake", stakePda);
+      if (stakeAccount) {
+        const escrowLamports = BigInt(this.bn(args.initialDeposit).toString());
+        const required = computeRequiredStakeLamports(escrowLamports);
+        const have = BigInt(stakeAccount.stakedAmount.toString());
+        if (have < required) {
+          throw new Error(
+            `createEscrowV2: agent stake ${have} lamports < required ${required} ` +
+            `lamports for escrow of ${escrowLamports} lamports. Top up via stakingModule.deposit.`,
+          );
+        }
+      }
+      // If no stake account exists at all, on-chain will reject with
+      // AccountNotInitialized — we let that bubble up unchanged.
+    } catch (err) {
+      // Preflight is advisory; rethrow only the explicit coverage error.
+      if (err instanceof Error && err.message.startsWith("createEscrowV2: agent stake")) {
+        throw err;
+      }
+    }
 
     return this.methods
       .createEscrowV2(

package/src/modules/escrow.ts

@@ -33,6 +33,7 @@ import type {
 } from "../types";
 import {
   buildPriorityFeeIxs,
+  computeBatchSettleCu,
   buildRpcOptions,
 } from "../utils/priority-fee";
 import type { SettleOptions } from "../utils/priority-fee";
@@ -305,12 +306,22 @@ export class EscrowModule extends BaseModule {
     const rootArr = hashToArray(rootBytes);
     const [receiptPda] = deriveSettlementReceipt(escrowPda, rootBytes);
 
-    const preIxs = buildPriorityFeeIxs(opts);
-    const rpcOpts = buildRpcOptions(opts);
+    // Auto-size CU to the batch length so callers don't have to think
+    // about it. The default Solana cap (200k) overflows past ~8
+    // settlements; we compute a tight ceiling and let the caller
+    // override via `opts.computeUnits` if they want.
+    // Setting the CU limit is FREE — it doesn't add lamports, only
+    // caps the maximum the runtime is allowed to charge.
+    const effectiveOpts: SettleOptions = {
+      ...opts,
+      computeUnits: opts?.computeUnits ?? computeBatchSettleCu(settlements.length),
+    };
+    const preIxs = buildPriorityFeeIxs(effectiveOpts);
+    const rpcOpts = buildRpcOptions(effectiveOpts);
 
     let builder = this.methods
       .settleBatch(settlements, rootArr)
-      .accounts({
+      .accountsPartial({
         wallet: this.walletPubkey,
         agent: agentPda,
         agentStats: statsPda,

package/src/modules/receipt.ts

@@ -25,6 +25,7 @@ import {
   derivePendingSettlement as derivePendingPda,
   deriveDispute as deriveDisputePda,
   deriveReceiptBatch as deriveReceiptPda,
+  deriveStake,
 } from "../pda";
 import type { ReceiptBatchData } from "../types";
 
@@ -172,6 +173,9 @@ export class ReceiptModule extends BaseModule {
     const [pendingPda] = derivePendingPda(escrowPda, this.toNum(settlementIndex));
     const [disputePda] = deriveDisputePda(pendingPda);
     const [statsPda] = deriveAgentStats(agentPda);
+    // v0.11 H-3: AgentStake is now a typed required account so the slash on
+    // DepositorWins is guaranteed instead of silently skipped.
+    const [stakePda] = deriveStake(agentPda);
 
     return this.methods
       .autoResolveDispute()
@@ -183,6 +187,7 @@ export class ReceiptModule extends BaseModule {
         pendingSettlement: pendingPda,
         dispute: disputePda,
         agentStats: statsPda,
+        agentStake: stakePda,
       })
       .rpc();
   }

package/src/modules/staking.ts

@@ -17,6 +17,10 @@ import { BN } from "@coral-xyz/anchor";
 import { BaseModule } from "./base";
 import { deriveAgent, deriveStake } from "../pda";
 import type { AgentStakeData } from "../types";
+import {
+  MIN_AGENT_STAKE_LAMPORTS,
+  computeRequiredStakeLamports,
+} from "../constants/payments";
 
 /**
  * @name StakingModule
@@ -119,4 +123,35 @@ export class StakingModule extends BaseModule {
   async fetchByPda(stakePda: PublicKey): Promise<AgentStakeData> {
     return this.fetchAccount<AgentStakeData>("agentStake", stakePda);
   }
+
+  // ── v0.11 helpers ────────────────────────────────────────────
+
+  /**
+   * Compute the maximum amount that can be requested via `requestUnstake`
+   * without breaching the on-chain {@link MIN_AGENT_STAKE_LAMPORTS} floor.
+   *
+   * Returns 0 if the agent is already at (or below) the floor.
+   *
+   * @since v0.11.0
+   */
+  getMaxUnstakeLamports(stake: AgentStakeData): bigint {
+    const staked = BigInt(stake.stakedAmount.toString());
+    if (staked <= MIN_AGENT_STAKE_LAMPORTS) return 0n;
+    return staked - MIN_AGENT_STAKE_LAMPORTS;
+  }
+
+  /**
+   * Returns the lamport delta the agent must `deposit` to satisfy the
+   * per-escrow stake-coverage requirement for `escrowLamports`. 0 if already
+   * sufficient. Useful for a UI "top up to open this escrow" button.
+   *
+   * Mirrors the on-chain check in `create_escrow_v2` (v0.11 H-1).
+   *
+   * @since v0.11.0
+   */
+  getRequiredTopUp(stake: AgentStakeData, escrowLamports: bigint): bigint {
+    const required = computeRequiredStakeLamports(escrowLamports);
+    const have = BigInt(stake.stakedAmount.toString());
+    return have >= required ? 0n : required - have;
+  }
 }

package/src/registries/x402.ts

@@ -88,6 +88,7 @@ import type {
 } from "../types";
 import {
   buildPriorityFeeIxs,
+  computeBatchSettleCu,
   buildRpcOptions,
 } from "../utils/priority-fee";
 import type { SettleOptions } from "../utils/priority-fee";
@@ -856,13 +857,19 @@ export class X402Registry {
       totalCalls,
     );
 
-    // Build priority fee instructions (empty array if no opts)
-    const preIxs = buildPriorityFeeIxs(opts);
-    const rpcOpts = buildRpcOptions(opts);
+    // Auto-size CU to the batch length when the caller didn't pin one.
+    // Default Solana cap (200k) is tight past ~8 entries; a CU limit
+    // costs nothing extra (only caps the maximum charge).
+    const effectiveOpts: SettleOptions = {
+      ...opts,
+      computeUnits: opts?.computeUnits ?? computeBatchSettleCu(settlements.length),
+    };
+    const preIxs = buildPriorityFeeIxs(effectiveOpts);
+    const rpcOpts = buildRpcOptions(effectiveOpts);
 
     let builder = this.methods
       .settleBatch(settlements)
-      .accounts({
+      .accountsPartial({
         wallet: this.wallet,
         agent: agentPda,
         agentStats: statsPda,

package/src/utils/index.ts

@@ -66,6 +66,7 @@ export {
   DEFAULT_SETTLE_PRIORITY_FEE,
   DEFAULT_SETTLE_COMPUTE_UNITS,
   DEFAULT_BATCH_SETTLE_COMPUTE_UNITS,
+  computeBatchSettleCu,
 } from "./priority-fee";
 export type {
   PriorityFeeConfig,

package/src/utils/priority-fee.ts

@@ -59,6 +59,61 @@ export const DEFAULT_SETTLE_COMPUTE_UNITS = 100_000;
  */
 export const DEFAULT_BATCH_SETTLE_COMPUTE_UNITS = 300_000;
 
+/**
+ * Per-settlement CU cost observed for `settle_batch` (sha256 of the
+ * service hash, dedup scan, volume-curve math, account writes).
+ *
+ * @since v0.11.0
+ * @internal
+ */
+const BATCH_SETTLE_CU_PER_ENTRY = 25_000;
+
+/**
+ * Fixed CU overhead for a `settle_batch` transaction independent of
+ * the entry count (signature verify, account loads, transfer, event).
+ *
+ * @since v0.11.0
+ * @internal
+ */
+const BATCH_SETTLE_CU_BASE = 60_000;
+
+/**
+ * Hard ceiling — Solana caps a single instruction at 1.4M CU. We
+ * stay below that so a transaction with extra preInstructions
+ * (priority-fee, ATA creation) still fits.
+ *
+ * @since v0.11.0
+ * @internal
+ */
+const BATCH_SETTLE_CU_MAX = 1_200_000;
+
+/**
+ * @name computeBatchSettleCu
+ * @description Compute the CU limit needed by `settle_batch` for a
+ * given entry count. Returned value is safe to pass to
+ * `ComputeBudgetProgram.setComputeUnitLimit`.
+ *
+ * Formula: `60_000 + n * 25_000`, clamped to 1.2M.
+ *
+ * @param entryCount - Number of settlements in the batch (1..N).
+ * @returns CU limit suitable for `setComputeUnitLimit`.
+ *
+ * @example
+ * ```ts
+ * const cu = computeBatchSettleCu(20); // 560_000
+ * ```
+ *
+ * @category Utils
+ * @since v0.11.0
+ */
+export function computeBatchSettleCu(entryCount: number): number {
+  if (!Number.isFinite(entryCount) || entryCount <= 0) {
+    return DEFAULT_BATCH_SETTLE_COMPUTE_UNITS;
+  }
+  const raw = BATCH_SETTLE_CU_BASE + Math.ceil(entryCount) * BATCH_SETTLE_CU_PER_ENTRY;
+  return Math.min(raw, BATCH_SETTLE_CU_MAX);
+}
+
 // ═══════════════════════════════════════════════════════════════════
 //  Types
 // ═══════════════════════════════════════════════════════════════════