@oobe-protocol-labs/synapse-sap-sdk 0.7.0 → 0.9.1

package/src/types/accounts.ts

@@ -11,7 +11,7 @@
 
 import type { PublicKey } from "@solana/web3.js";
 import type BN from "bn.js";
-import type { ToolHttpMethodKind, ToolCategoryKind, SettlementSecurityKind, DisputeOutcomeKind, BillingIntervalKind } from "./enums";
+import type { ToolHttpMethodKind, ToolCategoryKind, SettlementSecurityKind, DisputeOutcomeKind, BillingIntervalKind, ResolutionLayerKind } from "./enums";
 import type { Capability, PricingTier, PluginRef, VolumeCurveBreakpoint } from "./common";
 
 // ═══════════════════════════════════════════════════════════════════
@@ -652,9 +652,12 @@ export interface EscrowAccountV2Data {
   readonly disputeWindowSlots: BN;
   readonly settlementIndex: BN;
   readonly coSigner: PublicKey | null;
+  /** @deprecated Since v0.7.0 — arbiter role replaced by automatic receipt verification */
   readonly arbiter: PublicKey | null;
   readonly pendingAmount: BN;
   readonly pendingCalls: BN;
+  /** @since v0.7.0 — Number of receipt batches inscribed against this escrow */
+  readonly receiptBatchCount: number;
 }
 
 // ═══════════════════════════════════════════════════════════════════
@@ -682,6 +685,8 @@ export interface PendingSettlementData {
   readonly isFinalized: boolean;
   readonly isDisputed: boolean;
   readonly outcome: DisputeOutcomeKind;
+  /** @since v0.7.0 — Merkle root of receipts backing this settlement */
+  readonly receiptMerkleRoot: number[]; // [u8; 32]
 }
 
 // ═══════════════════════════════════════════════════════════════════
@@ -690,7 +695,7 @@ export interface PendingSettlementData {
 
 /**
  * @interface DisputeRecordData
- * @description On-chain dispute with arbiter resolution.
+ * @description On-chain dispute with automatic receipt-based resolution (v0.7).
  * @category Types
  * @since v0.5.0
  */
@@ -702,12 +707,56 @@ export interface DisputeRecordData {
   readonly agent: PublicKey;
   readonly evidenceHash: number[]; // [u8; 32]
   readonly agentEvidenceHash: number[]; // [u8; 32]
+  /** @deprecated Since v0.7.0 — arbiter role replaced by automatic resolution */
   readonly arbiter: PublicKey;
   readonly outcome: DisputeOutcomeKind;
   readonly createdAt: BN;
   readonly resolvedAt: BN;
   readonly resolutionHash: number[]; // [u8; 32]
   readonly slashAmount: BN;
+  /** @since v0.7.0 — Category of dispute (NonDelivery=0, PartialDelivery=1, Overcharge=2, Quality=3) */
+  readonly disputeType: number;
+  /** @since v0.7.0 — How the dispute was resolved (Pending/Auto/Governance) */
+  readonly resolutionLayer: ResolutionLayerKind;
+  /** @since v0.7.0 — Bond deposited by the disputer (lamports) */
+  readonly disputeBond: BN;
+  /** @since v0.7.0 — Number of calls the agent proved via merkle proofs */
+  readonly provenCalls: BN;
+  /** @since v0.7.0 — Number of calls the agent originally claimed */
+  readonly claimedCalls: BN;
+  /** @since v0.7.0 — Unix timestamp by which agent must submit proof */
+  readonly proofDeadline: BN;
+}
+
+// ═══════════════════════════════════════════════════════════════════
+//  Receipt Batch (v0.7)
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @interface ReceiptBatchData
+ * @description Merkle root of a batch of call receipts inscribed by an agent.
+ *
+ * Seeds: `["sap_receipt", escrow_v2_pda, batch_index_u32_le]`
+ *
+ * @category Types
+ * @since v0.7.0
+ */
+export interface ReceiptBatchData {
+  readonly bump: number;
+  /** Parent escrow V2 PDA */
+  readonly escrow: PublicKey;
+  /** Zero-based batch index */
+  readonly batchIndex: number;
+  /** Merkle root of the receipt batch */
+  readonly merkleRoot: number[]; // [u8; 32]
+  /** Number of calls in the batch */
+  readonly callCount: BN;
+  /** Unix timestamp for the start of the period covered */
+  readonly periodStart: BN;
+  /** Unix timestamp for the end of the period covered */
+  readonly periodEnd: BN;
+  /** Unix timestamp when the batch was inscribed */
+  readonly inscribedAt: BN;
 }
 
 // ═══════════════════════════════════════════════════════════════════

package/src/types/enums.ts

@@ -221,7 +221,7 @@ export type ToolCategoryKind =
  * @name SettlementSecurity
  * @description Anchor-compatible enum variants for V2 escrow settlement security levels.
  *
- * - `SelfReport` — Agent settles unilaterally (v1 compatible).
+ * - `SelfReport` — **DEPRECATED in v0.7** — Agent settles unilaterally (abuse vector).
  * - `CoSigned` — Agent + client must co-sign every settlement.
  * - `DisputeWindow` — Settlement enters pending state, depositor can dispute.
  *
@@ -229,6 +229,7 @@ export type ToolCategoryKind =
  * @since v0.5.0
  */
 export const SettlementSecurity = {
+  /** @deprecated Removed in v0.7 — returns SelfReportDeprecated error */
   SelfReport: { selfReport: {} },
   CoSigned: { coSigned: {} },
   DisputeWindow: { disputeWindow: {} },
@@ -253,11 +254,64 @@ export const DisputeOutcome = {
   AutoReleased: { autoReleased: {} },
   DepositorWins: { depositorWins: {} },
   AgentWins: { agentWins: {} },
+  /** @since v0.7.0 — Proportional refund based on proven vs claimed calls */
+  PartialRefund: { partialRefund: {} },
+  /** @since v0.7.0 — 50/50 split for irresolvable quality disputes */
+  Split: { split: {} },
 } as const;
 
 export type DisputeOutcomeKind =
   (typeof DisputeOutcome)[keyof typeof DisputeOutcome];
 
+// ═══════════════════════════════════════════════════════════════════
+//  Dispute Type (v0.7)
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @name DisputeType
+ * @description Categories of disputes that can be filed against a pending settlement.
+ *
+ * - `NonDelivery` — Agent took payment but delivered nothing.
+ * - `PartialDelivery` — Agent delivered fewer calls than claimed.
+ * - `Overcharge` — Agent charged more than the agreed price.
+ * - `Quality` — Agent delivered but output quality is disputed.
+ *
+ * @category Types
+ * @since v0.7.0
+ */
+export const DisputeType = {
+  NonDelivery: 0,
+  PartialDelivery: 1,
+  Overcharge: 2,
+  Quality: 3,
+} as const;
+
+export type DisputeTypeValue = (typeof DisputeType)[keyof typeof DisputeType];
+
+// ═══════════════════════════════════════════════════════════════════
+//  Resolution Layer (v0.7)
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * @name ResolutionLayer
+ * @description How a dispute was resolved.
+ *
+ * - `Pending` — Not yet resolved.
+ * - `Auto` — Resolved automatically via receipt merkle proofs.
+ * - `Governance` — Resolved via protocol governance (quality disputes).
+ *
+ * @category Types
+ * @since v0.7.0
+ */
+export const ResolutionLayer = {
+  Pending: { pending: {} },
+  Auto: { auto: {} },
+  Governance: { governance: {} },
+} as const;
+
+export type ResolutionLayerKind =
+  (typeof ResolutionLayer)[keyof typeof ResolutionLayer];
+
 // ═══════════════════════════════════════════════════════════════════
 //  Billing Interval (V2.1)
 // ═══════════════════════════════════════════════════════════════════

package/src/types/index.ts

@@ -30,6 +30,8 @@ export {
   SettlementSecurity,
   DisputeOutcome,
   BillingInterval,
+  DisputeType,
+  ResolutionLayer,
 } from "./enums";
 
 export type {
@@ -41,6 +43,8 @@ export type {
   SettlementSecurityKind,
   DisputeOutcomeKind,
   BillingIntervalKind,
+  DisputeTypeValue,
+  ResolutionLayerKind,
 } from "./enums";
 
 // ── Common Structs ───────────────────────────────────
@@ -74,6 +78,7 @@ export type {
   EscrowAccountV2Data,
   PendingSettlementData,
   DisputeRecordData,
+  ReceiptBatchData,
   AgentStakeData,
   SubscriptionData,
   CounterShardData,