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

package/src/utils/anchor-errors.ts

@@ -0,0 +1,461 @@
+/**
+ * @module utils/anchor-errors
+ * @description Full SAP program error table (147 entries, codes 6000-6146)
+ *   plus decoder utilities. Mirrors `programs/synapse-agent-sap/src/errors.rs`.
+ *
+ *   Use {@link decodeAnchorError} to extract a structured error from any
+ *   thrown RPC / simulation error. Use {@link SAP_ERRORS} for direct lookups.
+ *
+ * @category Utils
+ * @since v0.13.0
+ */
+
+export interface SapErrorEntry { readonly code: number; readonly name: string; readonly msg: string; }
+export const SAP_ERRORS: Readonly<Record<number, SapErrorEntry>> = Object.freeze({
+  6000: { code: 6000, name: "NameTooLong", msg: "name>64" },
+  6001: { code: 6001, name: "DescriptionTooLong", msg: "desc>256" },
+  6002: { code: 6002, name: "UriTooLong", msg: "uri>256" },
+  6003: { code: 6003, name: "TooManyCapabilities", msg: "caps>10" },
+  6004: { code: 6004, name: "TooManyPricingTiers", msg: "tiers>5" },
+  6005: { code: 6005, name: "TooManyProtocols", msg: "protos>5" },
+  6006: { code: 6006, name: "TooManyPlugins", msg: "plugins>5" },
+  6007: { code: 6007, name: "AlreadyActive", msg: "already active" },
+  6008: { code: 6008, name: "AlreadyInactive", msg: "already inactive" },
+  6009: { code: 6009, name: "InvalidFeedbackScore", msg: "score 0-1000" },
+  6010: { code: 6010, name: "TagTooLong", msg: "tag>32" },
+  6011: { code: 6011, name: "SelfReviewNotAllowed", msg: "self review" },
+  6012: { code: 6012, name: "FeedbackAlreadyRevoked", msg: "already revoked" },
+  6013: { code: 6013, name: "CapabilityIndexFull", msg: "cap idx full" },
+  6014: { code: 6014, name: "ProtocolIndexFull", msg: "proto idx full" },
+  6015: { code: 6015, name: "AgentNotInIndex", msg: "not in idx" },
+  6016: { code: 6016, name: "InvalidCapabilityHash", msg: "cap hash" },
+  6017: { code: 6017, name: "InvalidProtocolHash", msg: "proto hash" },
+  6018: { code: 6018, name: "InvalidPluginType", msg: "bad plugin type" },
+  6019: { code: 6019, name: "ChunkDataTooLarge", msg: "chunk>900" },
+  6020: { code: 6020, name: "ContentTypeTooLong", msg: "ctype>max" },
+  6021: { code: 6021, name: "IpfsCidTooLong", msg: "cid>max" },
+  6022: { code: 6022, name: "EmptyName", msg: "empty name" },
+  6023: { code: 6023, name: "ControlCharInName", msg: "ctrl char" },
+  6024: { code: 6024, name: "EmptyDescription", msg: "empty desc" },
+  6025: { code: 6025, name: "AgentIdTooLong", msg: "agentid>128" },
+  6026: { code: 6026, name: "InvalidCapabilityFormat", msg: "cap format" },
+  6027: { code: 6027, name: "DuplicateCapability", msg: "dup cap" },
+  6028: { code: 6028, name: "EmptyTierId", msg: "empty tier" },
+  6029: { code: 6029, name: "DuplicateTierId", msg: "dup tier" },
+  6030: { code: 6030, name: "InvalidRateLimit", msg: "rate=0" },
+  6031: { code: 6031, name: "SplRequiresTokenMint", msg: "spl needs mint" },
+  6032: { code: 6032, name: "InvalidX402Endpoint", msg: "x402 https" },
+  6033: { code: 6033, name: "InvalidVolumeCurve", msg: "curve order" },
+  6034: { code: 6034, name: "TooManyVolumeCurvePoints", msg: "curve>5" },
+  6035: { code: 6035, name: "MinPriceExceedsMax", msg: "min>max price" },
+  6036: { code: 6036, name: "InvalidUptimePercent", msg: "uptime 0-100" },
+  6037: { code: 6037, name: "SessionClosed", msg: "session closed" },
+  6038: { code: 6038, name: "InvalidSequence", msg: "bad seq" },
+  6039: { code: 6039, name: "InvalidFragmentIndex", msg: "frag idx" },
+  6040: { code: 6040, name: "InscriptionTooLarge", msg: "data>750" },
+  6041: { code: 6041, name: "EmptyInscription", msg: "empty data" },
+  6042: { code: 6042, name: "InvalidTotalFragments", msg: "frags<1" },
+  6043: { code: 6043, name: "EpochMismatch", msg: "epoch mismatch" },
+  6044: { code: 6044, name: "VaultNotClosed", msg: "vault open" },
+  6045: { code: 6045, name: "SessionNotClosed", msg: "session open" },
+  6046: { code: 6046, name: "DelegateExpired", msg: "delegate expired" },
+  6047: { code: 6047, name: "InvalidDelegate", msg: "bad delegate" },
+  6048: { code: 6048, name: "ToolNameTooLong", msg: "tool>32" },
+  6049: { code: 6049, name: "EmptyToolName", msg: "empty tool" },
+  6050: { code: 6050, name: "InvalidToolNameHash", msg: "tool hash" },
+  6051: { code: 6051, name: "InvalidToolHttpMethod", msg: "bad method" },
+  6052: { code: 6052, name: "InvalidToolCategory", msg: "bad category" },
+  6053: { code: 6053, name: "ToolAlreadyInactive", msg: "tool inactive" },
+  6054: { code: 6054, name: "ToolAlreadyActive", msg: "tool active" },
+  6055: { code: 6055, name: "InvalidSchemaHash", msg: "schema hash" },
+  6056: { code: 6056, name: "InvalidSchemaType", msg: "schema type" },
+  6057: { code: 6057, name: "InvalidCheckpointIndex", msg: "cp index" },
+  6058: { code: 6058, name: "FeedbackNotRevoked", msg: "not revoked" },
+  6059: { code: 6059, name: "IndexNotEmpty", msg: "idx not empty" },
+  6060: { code: 6060, name: "SessionStillOpen", msg: "session open" },
+  6061: { code: 6061, name: "NoFieldsToUpdate", msg: "no fields" },
+  6062: { code: 6062, name: "InsufficientEscrowBalance", msg: "low balance" },
+  6063: { code: 6063, name: "EscrowMaxCallsExceeded", msg: "max calls" },
+  6064: { code: 6064, name: "EscrowEmpty", msg: "escrow empty" },
+  6065: { code: 6065, name: "EscrowNotEmpty", msg: "escrow!=0" },
+  6066: { code: 6066, name: "InvalidSettlementCalls", msg: "calls<1" },
+  6067: { code: 6067, name: "AttestationTypeTooLong", msg: "atype>32" },
+  6068: { code: 6068, name: "EmptyAttestationType", msg: "empty atype" },
+  6069: { code: 6069, name: "SelfAttestationNotAllowed", msg: "self attest" },
+  6070: { code: 6070, name: "AttestationAlreadyRevoked", msg: "already revoked" },
+  6071: { code: 6071, name: "AttestationNotRevoked", msg: "not revoked" },
+  6072: { code: 6072, name: "ToolCategoryIndexFull", msg: "cat idx full" },
+  6073: { code: 6073, name: "ToolNotInCategoryIndex", msg: "not in cat" },
+  6074: { code: 6074, name: "ToolCategoryMismatch", msg: "cat mismatch" },
+  6075: { code: 6075, name: "ArithmeticOverflow", msg: "overflow" },
+  6076: { code: 6076, name: "EscrowExpired", msg: "escrow expired" },
+  6077: { code: 6077, name: "AgentInactive", msg: "agent inactive" },
+  6078: { code: 6078, name: "AttestationExpired", msg: "attest expired" },
+  6079: { code: 6079, name: "BufferFull", msg: "buf full" },
+  6080: { code: 6080, name: "BufferDataTooLarge", msg: "buf>750" },
+  6081: { code: 6081, name: "Unauthorized", msg: "unauthorized" },
+  6082: { code: 6082, name: "InvalidSession", msg: "bad session" },
+  6083: { code: 6083, name: "EmptyDigestHash", msg: "empty hash" },
+  6084: { code: 6084, name: "LedgerDataTooLarge", msg: "ledger>750" },
+  6085: { code: 6085, name: "LedgerRingEmpty", msg: "ring empty" },
+  6086: { code: 6086, name: "BatchEmpty", msg: "batch empty" },
+  6087: { code: 6087, name: "BatchTooLarge", msg: "batch>10" },
+  6088: { code: 6088, name: "SplTokenRequired", msg: "spl accts" },
+  6089: { code: 6089, name: "InvalidTokenAccount", msg: "bad token" },
+  6090: { code: 6090, name: "InvalidTokenProgram", msg: "bad prog" },
+  6091: { code: 6091, name: "InvalidSettlementSecurity", msg: "bad security" },
+  6092: { code: 6092, name: "CoSignerRequired", msg: "cosigner" },
+  6093: { code: 6093, name: "InvalidCoSigner", msg: "bad cosigner" },
+  6094: { code: 6094, name: "InvalidArbiter", msg: "bad arbiter" },
+  6095: { code: 6095, name: "ArbiterRequired", msg: "arbiter=0" },
+  6096: { code: 6096, name: "EscrowNonceReused", msg: "nonce reused" },
+  6097: { code: 6097, name: "SettlementNotPending", msg: "not pending" },
+  6098: { code: 6098, name: "SettlementAlreadyFinalized", msg: "already final" },
+  6099: { code: 6099, name: "DisputeWindowNotExpired", msg: "too early" },
+  6100: { code: 6100, name: "DisputeWindowExpired", msg: "window closed" },
+  6101: { code: 6101, name: "NotDepositor", msg: "not depositor" },
+  6102: { code: 6102, name: "DisputeAlreadyFiled", msg: "dup dispute" },
+  6103: { code: 6103, name: "DisputeStillOpen", msg: "dispute open" },
+  6104: { code: 6104, name: "NotArbiter", msg: "not arbiter" },
+  6105: { code: 6105, name: "InvalidDisputeOutcome", msg: "bad outcome" },
+  6106: { code: 6106, name: "StakeBelowMinimum", msg: "stake<min" },
+  6107: { code: 6107, name: "NoStakeAccount", msg: "no stake" },
+  6108: { code: 6108, name: "UnstakeAlreadyPending", msg: "unstake pending" },
+  6109: { code: 6109, name: "UnstakeCooldownNotMet", msg: "cooldown" },
+  6110: { code: 6110, name: "NoUnstakePending", msg: "no unstake" },
+  6111: { code: 6111, name: "SlashExceedsStake", msg: "slash>stake" },
+  6112: { code: 6112, name: "SubscriptionAlreadyActive", msg: "sub active" },
+  6113: { code: 6113, name: "SubscriptionCancelled", msg: "sub cancelled" },
+  6114: { code: 6114, name: "NoIntervalDue", msg: "no due" },
+  6115: { code: 6115, name: "SubscriptionInsufficientBalance", msg: "sub low bal" },
+  6116: { code: 6116, name: "InvalidBillingInterval", msg: "bad interval" },
+  6117: { code: 6117, name: "InvalidShardIndex", msg: "bad shard" },
+  6118: { code: 6118, name: "IndexPageFull", msg: "page full" },
+  6119: { code: 6119, name: "InvalidPageIndex", msg: "bad page" },
+  6120: { code: 6120, name: "IndexPageNotEmpty", msg: "page≠empty" },
+  6121: { code: 6121, name: "AlreadyMigrated", msg: "already v2" },
+  6122: { code: 6122, name: "MigrationV1Only", msg: "v1 only" },
+  6123: { code: 6123, name: "SettlementDisputed", msg: "disputed" },
+  6124: { code: 6124, name: "InvalidAgentWallet", msg: "bad agent wallet" },
+  6125: { code: 6125, name: "StakeAgentMismatch", msg: "stake agent mismatch" },
+  6126: { code: 6126, name: "NotAuthority", msg: "not authority" },
+  6127: { code: 6127, name: "UnstakeBelowRent", msg: "unstake below rent" },
+  6128: { code: 6128, name: "InsufficientStake", msg: "insufficient stake" },
+  6129: { code: 6129, name: "SelfReportDeprecated", msg: "SelfReport deprecated" },
+  6130: { code: 6130, name: "ArbiterDeprecated", msg: "arbiter deprecated" },
+  6131: { code: 6131, name: "InvalidBatchIndex", msg: "bad batch idx" },
+  6132: { code: 6132, name: "InvalidPeriod", msg: "bad period" },
+  6133: { code: 6133, name: "InvalidDisputeType", msg: "bad dispute type" },
+  6134: { code: 6134, name: "ProofDeadlineExpired", msg: "proof expired" },
+  6135: { code: 6135, name: "ProofDeadlineNotExpired", msg: "proof not expired" },
+  6136: { code: 6136, name: "InvalidReceiptProof", msg: "bad receipt proof" },
+  6137: { code: 6137, name: "SettlementReplay", msg: "settlement replay" },
+  6138: { code: 6138, name: "PaymentTokenNotAllowed", msg: "token not allowed" },
+  6139: { code: 6139, name: "AgentStakeRequired", msg: "agent stake required" },
+  6140: { code: 6140, name: "DelegateExpiryInvalid", msg: "delegate expiry invalid" },
+  6141: { code: 6141, name: "EscrowNotClosed", msg: "escrow not closed" },
+  6142: { code: 6142, name: "VolumeCurveNotDescending", msg: "curve not descending" },
+  6143: { code: 6143, name: "DuplicateServiceHash", msg: "dup service hash" },
+  6144: { code: 6144, name: "StakeBelowCoverage", msg: "stake under coverage" },
+  6145: { code: 6145, name: "StakeNotClosable", msg: "stake not closable" },
+  6146: { code: 6146, name: "AgentStakeAccountMissing", msg: "agent stake account missing" },
+});
+export const SAP_ERROR_BY_NAME: Readonly<Record<string, number>> = Object.freeze({
+  NameTooLong: 6000,
+  DescriptionTooLong: 6001,
+  UriTooLong: 6002,
+  TooManyCapabilities: 6003,
+  TooManyPricingTiers: 6004,
+  TooManyProtocols: 6005,
+  TooManyPlugins: 6006,
+  AlreadyActive: 6007,
+  AlreadyInactive: 6008,
+  InvalidFeedbackScore: 6009,
+  TagTooLong: 6010,
+  SelfReviewNotAllowed: 6011,
+  FeedbackAlreadyRevoked: 6012,
+  CapabilityIndexFull: 6013,
+  ProtocolIndexFull: 6014,
+  AgentNotInIndex: 6015,
+  InvalidCapabilityHash: 6016,
+  InvalidProtocolHash: 6017,
+  InvalidPluginType: 6018,
+  ChunkDataTooLarge: 6019,
+  ContentTypeTooLong: 6020,
+  IpfsCidTooLong: 6021,
+  EmptyName: 6022,
+  ControlCharInName: 6023,
+  EmptyDescription: 6024,
+  AgentIdTooLong: 6025,
+  InvalidCapabilityFormat: 6026,
+  DuplicateCapability: 6027,
+  EmptyTierId: 6028,
+  DuplicateTierId: 6029,
+  InvalidRateLimit: 6030,
+  SplRequiresTokenMint: 6031,
+  InvalidX402Endpoint: 6032,
+  InvalidVolumeCurve: 6033,
+  TooManyVolumeCurvePoints: 6034,
+  MinPriceExceedsMax: 6035,
+  InvalidUptimePercent: 6036,
+  SessionClosed: 6037,
+  InvalidSequence: 6038,
+  InvalidFragmentIndex: 6039,
+  InscriptionTooLarge: 6040,
+  EmptyInscription: 6041,
+  InvalidTotalFragments: 6042,
+  EpochMismatch: 6043,
+  VaultNotClosed: 6044,
+  SessionNotClosed: 6045,
+  DelegateExpired: 6046,
+  InvalidDelegate: 6047,
+  ToolNameTooLong: 6048,
+  EmptyToolName: 6049,
+  InvalidToolNameHash: 6050,
+  InvalidToolHttpMethod: 6051,
+  InvalidToolCategory: 6052,
+  ToolAlreadyInactive: 6053,
+  ToolAlreadyActive: 6054,
+  InvalidSchemaHash: 6055,
+  InvalidSchemaType: 6056,
+  InvalidCheckpointIndex: 6057,
+  FeedbackNotRevoked: 6058,
+  IndexNotEmpty: 6059,
+  SessionStillOpen: 6060,
+  NoFieldsToUpdate: 6061,
+  InsufficientEscrowBalance: 6062,
+  EscrowMaxCallsExceeded: 6063,
+  EscrowEmpty: 6064,
+  EscrowNotEmpty: 6065,
+  InvalidSettlementCalls: 6066,
+  AttestationTypeTooLong: 6067,
+  EmptyAttestationType: 6068,
+  SelfAttestationNotAllowed: 6069,
+  AttestationAlreadyRevoked: 6070,
+  AttestationNotRevoked: 6071,
+  ToolCategoryIndexFull: 6072,
+  ToolNotInCategoryIndex: 6073,
+  ToolCategoryMismatch: 6074,
+  ArithmeticOverflow: 6075,
+  EscrowExpired: 6076,
+  AgentInactive: 6077,
+  AttestationExpired: 6078,
+  BufferFull: 6079,
+  BufferDataTooLarge: 6080,
+  Unauthorized: 6081,
+  InvalidSession: 6082,
+  EmptyDigestHash: 6083,
+  LedgerDataTooLarge: 6084,
+  LedgerRingEmpty: 6085,
+  BatchEmpty: 6086,
+  BatchTooLarge: 6087,
+  SplTokenRequired: 6088,
+  InvalidTokenAccount: 6089,
+  InvalidTokenProgram: 6090,
+  InvalidSettlementSecurity: 6091,
+  CoSignerRequired: 6092,
+  InvalidCoSigner: 6093,
+  InvalidArbiter: 6094,
+  ArbiterRequired: 6095,
+  EscrowNonceReused: 6096,
+  SettlementNotPending: 6097,
+  SettlementAlreadyFinalized: 6098,
+  DisputeWindowNotExpired: 6099,
+  DisputeWindowExpired: 6100,
+  NotDepositor: 6101,
+  DisputeAlreadyFiled: 6102,
+  DisputeStillOpen: 6103,
+  NotArbiter: 6104,
+  InvalidDisputeOutcome: 6105,
+  StakeBelowMinimum: 6106,
+  NoStakeAccount: 6107,
+  UnstakeAlreadyPending: 6108,
+  UnstakeCooldownNotMet: 6109,
+  NoUnstakePending: 6110,
+  SlashExceedsStake: 6111,
+  SubscriptionAlreadyActive: 6112,
+  SubscriptionCancelled: 6113,
+  NoIntervalDue: 6114,
+  SubscriptionInsufficientBalance: 6115,
+  InvalidBillingInterval: 6116,
+  InvalidShardIndex: 6117,
+  IndexPageFull: 6118,
+  InvalidPageIndex: 6119,
+  IndexPageNotEmpty: 6120,
+  AlreadyMigrated: 6121,
+  MigrationV1Only: 6122,
+  SettlementDisputed: 6123,
+  InvalidAgentWallet: 6124,
+  StakeAgentMismatch: 6125,
+  NotAuthority: 6126,
+  UnstakeBelowRent: 6127,
+  InsufficientStake: 6128,
+  SelfReportDeprecated: 6129,
+  ArbiterDeprecated: 6130,
+  InvalidBatchIndex: 6131,
+  InvalidPeriod: 6132,
+  InvalidDisputeType: 6133,
+  ProofDeadlineExpired: 6134,
+  ProofDeadlineNotExpired: 6135,
+  InvalidReceiptProof: 6136,
+  SettlementReplay: 6137,
+  PaymentTokenNotAllowed: 6138,
+  AgentStakeRequired: 6139,
+  DelegateExpiryInvalid: 6140,
+  EscrowNotClosed: 6141,
+  VolumeCurveNotDescending: 6142,
+  DuplicateServiceHash: 6143,
+  StakeBelowCoverage: 6144,
+  StakeNotClosable: 6145,
+  AgentStakeAccountMissing: 6146,
+});
+
+/**
+ * @name DecodedAnchorError
+ * @description Structured error extracted from a thrown RPC/simulation error.
+ * @since v0.13.0
+ */
+export interface DecodedAnchorError {
+  readonly code: number;
+  readonly name: string;
+  readonly msg: string;
+  readonly friendly: string;
+  readonly logs?: readonly string[];
+}
+
+const FRIENDLY_OVERRIDES: Readonly<Record<string, string>> = Object.freeze({
+  Unauthorized: "Unauthorized — wallet does not match the on-chain authority for this PDA.",
+  AgentInactive: "Agent is inactive (deactivated). Reactivate before publishing tools or accepting escrows.",
+  AgentStakeRequired: "Agent stake account missing or below MIN_STAKE (0.1 SOL). Initialize stake first.",
+  StakeBelowMinimum: "Stake below minimum (0.1 SOL). Top up before requesting unstake or accepting escrows.",
+  StakeBelowCoverage: "Stake below coverage requirement for outstanding escrow. Increase stake or wait for escrows to settle.",
+  PaymentTokenNotAllowed: "Token mint not in allowlist. Use SOL (null) or USDC (mainnet/devnet).",
+  DelegateExpiryInvalid: "Delegate expiry exceeds MAX_DELEGATE_DURATION_SECS (365 days) from now.",
+  EscrowNotEmpty: "Escrow balance != 0. Withdraw or settle remaining funds before closing.",
+  EscrowEmpty: "Escrow balance is zero — cannot settle.",
+  InsufficientEscrowBalance: "Insufficient escrow balance for the requested settlement amount.",
+  ArithmeticOverflow: "Arithmetic overflow — likely an orphan PendingSettlement, mismatched amount, or unsigned subtraction. Run `escrowV2.diagnoseOrphanPending()` to inspect.",
+  EscrowNonceReused: "Escrow nonce already used by this depositor. Pick a fresh nonce.",
+  SettlementNotPending: "PendingSettlement is not in pending state (already finalized or never created).",
+  SettlementAlreadyFinalized: "PendingSettlement already finalized — cannot finalize twice.",
+  DisputeWindowNotExpired: "Dispute window still open. Wait until escrow.dispute_window_slots elapse before finalizing.",
+  DisputeWindowExpired: "Dispute window already closed. Cannot file dispute.",
+  CoSignerRequired: "Settlement security mode requires a co-signer. Pass the co-signer keypair.",
+  InvalidCoSigner: "Co-signer pubkey does not match the on-chain `escrow.co_signer`.",
+  InvalidSettlementSecurity: "Settlement security mode mismatch with on-chain escrow config.",
+  SettlementReplay: "Settlement receipt PDA already exists for this serviceHash/batchRoot. Replay blocked.",
+  DuplicateServiceHash: "Two settlements in the same batch share the same serviceHash. Make each call unique.",
+  BatchTooLarge: "Batch settle exceeds 10 entries. Split across multiple transactions.",
+  BatchEmpty: "Batch settle requires at least 1 settlement.",
+  InscriptionTooLarge: "Inscription chunk exceeds 750 bytes. Split into more fragments.",
+  InvalidSchemaHash: "Tool schema hash is empty / invalid. v0.2.0+ requires every tool to publish a JSON schema (or schema_hash).",
+  EmptyToolName: "Tool name cannot be empty.",
+  ToolNameTooLong: "Tool name exceeds 32 bytes.",
+  EscrowExpired: "Escrow expired (expiresAt passed). Create a new escrow.",
+  UnstakeCooldownNotMet: "Unstake cooldown not elapsed. Wait for the cooldown window before completing unstake.",
+  UnstakeBelowRent: "Resulting stake balance would fall below the rent-exempt minimum. Reduce unstake amount.",
+});
+
+/**
+ * @name decodeAnchorError
+ * @description Pull an Anchor / SAP error out of any caught value.
+ *   Handles: AnchorError, raw RPC SimulateError, `0x...` hex codes,
+ *   nested `error.errorCode.number`, and direct `code` numbers.
+ * @returns Structured {@link DecodedAnchorError} or `null` if not a SAP error.
+ * @since v0.13.0
+ */
+export function decodeAnchorError(err: unknown): DecodedAnchorError | null {
+  if (err == null || typeof err !== "object") return null;
+
+  const code = extractCode(err);
+  if (code == null) return null;
+
+  const entry = SAP_ERRORS[code];
+  if (!entry) {
+    return {
+      code,
+      name: "Unknown",
+      msg: `custom program error 0x${code.toString(16)}`,
+      friendly: `Unknown SAP error (code ${code}). Check IDL.`,
+      logs: extractLogs(err),
+    };
+  }
+
+  return {
+    code: entry.code,
+    name: entry.name,
+    msg: entry.msg,
+    friendly: FRIENDLY_OVERRIDES[entry.name] ?? `${entry.name}: ${entry.msg}`,
+    logs: extractLogs(err),
+  };
+}
+
+function extractCode(err: unknown): number | null {
+  if (typeof err !== "object" || err == null) return null;
+  const e = err as Record<string, unknown>;
+  if (typeof e.code === "number") return e.code;
+
+  const nested = e.error;
+  if (nested && typeof nested === "object") {
+    const errorCode = (nested as Record<string, unknown>).errorCode;
+    if (errorCode && typeof errorCode === "object") {
+      const num = (errorCode as Record<string, unknown>).number;
+      if (typeof num === "number") return num;
+    }
+  }
+
+  const msg = (err as Error).message;
+  if (typeof msg === "string") {
+    const hex = msg.match(/custom program error:\s*0x([0-9a-fA-F]+)/);
+    if (hex?.[1]) return parseInt(hex[1], 16);
+    const dec = msg.match(/Error Number:\s*(\d+)/);
+    if (dec?.[1]) return parseInt(dec[1], 10);
+  }
+  return null;
+}
+
+function extractLogs(err: unknown): string[] | undefined {
+  if (typeof err !== "object" || err == null) return undefined;
+  const logs = (err as Record<string, unknown>).logs;
+  if (Array.isArray(logs)) return logs as string[];
+  const nested = (err as Record<string, unknown>).simulationResponse;
+  if (nested && typeof nested === "object") {
+    const inner = (nested as Record<string, unknown>).logs;
+    if (Array.isArray(inner)) return inner as string[];
+  }
+  return undefined;
+}
+
+/**
+ * @name SapPreflightError
+ * @description Thrown by SDK preflights when an on-chain check is guaranteed
+ *   to fail. Carries the predicted error code/name so callers can branch
+ *   without parsing strings.
+ * @since v0.13.0
+ */
+export class SapPreflightError extends Error {
+  readonly preflight = true as const;
+  constructor(
+    message: string,
+    readonly predictedCode: number,
+    readonly predictedName: string,
+    readonly hint?: string,
+  ) {
+    super(message);
+    this.name = "SapPreflightError";
+  }
+}
+
+/**
+ * @name throwPredicted
+ * @description Helper for SDK preflights. Throws a {@link SapPreflightError}
+ *   carrying the on-chain error name + friendly message.
+ * @since v0.13.0
+ */
+export function throwPredicted(name: keyof typeof SAP_ERROR_BY_NAME, hint?: string): never {
+  const code = SAP_ERROR_BY_NAME[name as string] ?? -1;
+  const entry = code >= 0 ? SAP_ERRORS[code] : undefined;
+  const friendly = FRIENDLY_OVERRIDES[name as string] ?? `${String(name)}: ${entry?.msg ?? ""}`;
+  const full = hint ? `${friendly} (${hint})` : friendly;
+  throw new SapPreflightError(full, code, name as string, hint);
+}

package/src/utils/index.ts

@@ -100,3 +100,19 @@ export type {
   SettlementPayload,
   GetX402DirectOptions,
 } from "./x402-direct";
+
+// ── v0.13.0  Full SAP error table + preflight helpers ─
+export {
+  SAP_ERRORS,
+  SAP_ERROR_BY_NAME,
+  decodeAnchorError,
+  SapPreflightError,
+  throwPredicted,
+} from "./anchor-errors";
+export type {
+  SapErrorEntry,
+  DecodedAnchorError,
+} from "./anchor-errors";
+
+// ── v0.13.0  Volume-curve mirror for client-side amount preview ──
+export { calculateSettleAmount } from "./volume-curve";

package/src/utils/volume-curve.ts

@@ -0,0 +1,131 @@
+/**
+ * @module volume-curve
+ * @description Client-side mirror of the on-chain `calculate_settle_amount`
+ * function from `programs/synapse-agent-sap/src/instructions/escrow_v2.rs`.
+ *
+ * Used by {@link EscrowV2Module.settle} to pre-compute the settlement
+ * `amount` so it can chain `createPendingSettlement` in the same transaction
+ * as `settleCallsV2` (DisputeWindow flow). Keeping the math in one place
+ * here ensures the SDK stays byte-for-byte aligned with the program; if the
+ * on-chain curve algorithm ever changes, this file is the single source of
+ * truth on the client.
+ *
+ * @category Utilities
+ * @since v0.13.0
+ * @packageDocumentation
+ */
+
+import { BN } from "@coral-xyz/anchor";
+import type { VolumeCurveBreakpoint } from "../types/common";
+
+const U64_MAX = new BN("18446744073709551615");
+
+function checkedMul(a: BN, b: BN): BN {
+  const r = a.mul(b);
+  if (r.gt(U64_MAX)) {
+    throw new Error(
+      `volume-curve: u64 overflow on multiply (${a.toString()} * ${b.toString()})`,
+    );
+  }
+  return r;
+}
+
+function checkedAdd(a: BN, b: BN): BN {
+  const r = a.add(b);
+  if (r.gt(U64_MAX)) {
+    throw new Error(
+      `volume-curve: u64 overflow on add (${a.toString()} + ${b.toString()})`,
+    );
+  }
+  return r;
+}
+
+/**
+ * @function calculateSettleAmount
+ * @description Compute the lamport (or token base-unit) amount the on-chain
+ * `settle_calls_v2` handler will charge for `calls` calls, given the escrow's
+ * `pricePerCall`, `volumeCurve`, and the current settled+pending counter.
+ *
+ * Mirrors the exact algorithm of `calculate_settle_amount` in
+ * `escrow_v2.rs` (v0.7+):
+ *
+ * ```rust
+ * if curve.is_empty() { calls * base_price } else { walk-the-curve }
+ * ```
+ *
+ * Walks the curve from `cursor = totalCallsBefore` and at each cursor
+ * position picks the breakpoint price whose `afterCalls` threshold the
+ * cursor has passed. Calls are charged at the active price up to the next
+ * threshold, then the cursor advances and the loop repeats until all
+ * `calls` are accounted for.
+ *
+ * @param basePrice - Escrow's `pricePerCall` (BN, u64 lamports/base-units).
+ * @param curve - The escrow's `volumeCurve` array (may be empty).
+ * @param totalCallsBefore - `escrow.totalCallsSettled + escrow.pendingCalls`
+ *   AT THE MOMENT `settleCallsV2` runs on-chain.
+ * @param calls - Number of calls being settled in this batch.
+ * @returns The amount the on-chain handler will compute (BN, u64).
+ *
+ * @example
+ * ```ts
+ * import { calculateSettleAmount } from "@oobe-protocol-labs/synapse-sap-sdk";
+ *
+ * const amount = calculateSettleAmount(
+ *   escrow.pricePerCall,
+ *   escrow.volumeCurve,
+ *   escrow.totalCallsSettled.add(escrow.pendingCalls),
+ *   new BN(5),
+ * );
+ * ```
+ *
+ * @since v0.13.0
+ */
+export function calculateSettleAmount(
+  basePrice: BN,
+  curve: VolumeCurveBreakpoint[],
+  totalCallsBefore: BN,
+  calls: BN,
+): BN {
+  if (calls.isZero()) return new BN(0);
+  if (!curve || curve.length === 0) {
+    return checkedMul(calls, basePrice);
+  }
+
+  let amount = new BN(0);
+  let remaining = calls.clone();
+  let cursor = totalCallsBefore.clone();
+
+  while (remaining.gtn(0)) {
+    let currentPrice = basePrice;
+    let nextThreshold: BN | null = null;
+
+    for (const bp of curve) {
+      const threshold = new BN(bp.afterCalls);
+      if (cursor.gte(threshold)) {
+        currentPrice = bp.pricePerCall;
+      } else {
+        nextThreshold = threshold;
+        break;
+      }
+    }
+
+    let callsAtPrice: BN;
+    if (nextThreshold) {
+      const room = nextThreshold.sub(cursor);
+      callsAtPrice = BN.min(remaining, room.isNeg() ? new BN(0) : room);
+      if (callsAtPrice.isZero()) {
+        // Defensive: shouldn't happen because cursor < nextThreshold by
+        // the `else` branch above, but guard anyway.
+        callsAtPrice = remaining;
+      }
+    } else {
+      callsAtPrice = remaining;
+    }
+
+    amount = checkedAdd(amount, checkedMul(callsAtPrice, currentPrice));
+    remaining = remaining.sub(callsAtPrice);
+    cursor = cursor.add(callsAtPrice);
+  }
+
+  return amount;
+}