irsb-sdk 0.1.0

package/src/client.ts

@@ -0,0 +1,392 @@
+import { ethers, Signer, Provider, Contract, TransactionResponse } from 'ethers';
+import {
+  ChainConfig,
+  CHAIN_CONFIGS,
+  SolverInfo,
+  SolverStatus,
+  IntentReceipt,
+  ReceiptStatus,
+  Challenge,
+  DisputeReason,
+  PostReceiptParams,
+  CONSTANTS,
+} from './types';
+import {
+  SOLVER_REGISTRY_ABI,
+  INTENT_RECEIPT_HUB_ABI,
+  DISPUTE_MODULE_ABI,
+} from './contracts/abis';
+
+export interface IRSBClientConfig {
+  /** Chain name ('sepolia') or custom config */
+  chain: string | ChainConfig;
+  /** Ethers signer for write operations */
+  signer?: Signer;
+  /** Ethers provider for read operations (optional if signer provided) */
+  provider?: Provider;
+}
+
+/**
+ * IRSB Protocol SDK Client
+ *
+ * @example
+ * ```ts
+ * import { IRSBClient } from '@irsb/sdk';
+ * import { ethers } from 'ethers';
+ *
+ * const provider = new ethers.JsonRpcProvider('https://rpc.sepolia.org');
+ * const signer = new ethers.Wallet(PRIVATE_KEY, provider);
+ *
+ * const client = new IRSBClient({
+ *   chain: 'sepolia',
+ *   signer,
+ * });
+ *
+ * // Register as solver
+ * await client.register({ value: ethers.parseEther('0.1') });
+ *
+ * // Post a receipt
+ * await client.postReceipt({
+ *   intentHash: '0x...',
+ *   constraintsHash: '0x...',
+ *   outcomeHash: '0x...',
+ *   evidenceHash: '0x...',
+ *   deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
+ *   solverSig: '0x...',
+ * });
+ * ```
+ */
+export class IRSBClient {
+  readonly config: ChainConfig;
+  readonly provider: Provider;
+  readonly signer?: Signer;
+
+  private solverRegistry: Contract;
+  private intentReceiptHub: Contract;
+  private disputeModule: Contract;
+
+  constructor(options: IRSBClientConfig) {
+    // Resolve chain config
+    if (typeof options.chain === 'string') {
+      const config = CHAIN_CONFIGS[options.chain];
+      if (!config) {
+        throw new Error(`Unknown chain: ${options.chain}. Available: ${Object.keys(CHAIN_CONFIGS).join(', ')}`);
+      }
+      this.config = config;
+    } else {
+      this.config = options.chain;
+    }
+
+    // Set up provider
+    if (options.signer) {
+      this.signer = options.signer;
+      this.provider = options.signer.provider!;
+    } else if (options.provider) {
+      this.provider = options.provider;
+    } else {
+      this.provider = new ethers.JsonRpcProvider(this.config.rpcUrl);
+    }
+
+    // Initialize contracts
+    const signerOrProvider = this.signer || this.provider;
+    this.solverRegistry = new Contract(
+      this.config.solverRegistry,
+      SOLVER_REGISTRY_ABI,
+      signerOrProvider
+    );
+    this.intentReceiptHub = new Contract(
+      this.config.intentReceiptHub,
+      INTENT_RECEIPT_HUB_ABI,
+      signerOrProvider
+    );
+    this.disputeModule = new Contract(
+      this.config.disputeModule,
+      DISPUTE_MODULE_ABI,
+      signerOrProvider
+    );
+  }
+
+  // ============ Solver Registry - Read ============
+
+  /**
+   * Get solver information
+   */
+  async getSolver(address: string): Promise<SolverInfo> {
+    const data = await this.solverRegistry.solvers(address);
+    return {
+      bondAmount: data.bondAmount,
+      lockedAmount: data.lockedAmount,
+      reputation: data.reputation,
+      registrationTime: data.registrationTime,
+      lastActiveTime: data.lastActiveTime,
+      totalIntents: data.totalIntents,
+      successfulIntents: data.successfulIntents,
+      jailCount: Number(data.jailCount),
+      status: Number(data.status) as SolverStatus,
+      pendingWithdrawal: data.pendingWithdrawal,
+      withdrawalRequestTime: data.withdrawalRequestTime,
+    };
+  }
+
+  /**
+   * Check if address is an active solver
+   */
+  async isActiveSolver(address: string): Promise<boolean> {
+    return this.solverRegistry.isActiveSolver(address);
+  }
+
+  /**
+   * Get solver's total bond amount
+   */
+  async getSolverBond(address: string): Promise<bigint> {
+    return this.solverRegistry.getSolverBond(address);
+  }
+
+  /**
+   * Get solver's available (unlocked) bond
+   */
+  async getAvailableBond(address: string): Promise<bigint> {
+    return this.solverRegistry.getAvailableBond(address);
+  }
+
+  /**
+   * Get minimum bond required for registration
+   */
+  async getMinimumBond(): Promise<bigint> {
+    return this.solverRegistry.MINIMUM_BOND();
+  }
+
+  // ============ Solver Registry - Write ============
+
+  /**
+   * Register as a solver with initial bond
+   * @param options.value - ETH to deposit as bond (must be >= MINIMUM_BOND)
+   */
+  async register(options: { value: bigint }): Promise<TransactionResponse> {
+    this.requireSigner();
+    return this.solverRegistry.register({ value: options.value });
+  }
+
+  /**
+   * Deposit additional bond
+   * @param options.value - ETH to deposit
+   */
+  async depositBond(options: { value: bigint }): Promise<TransactionResponse> {
+    this.requireSigner();
+    return this.solverRegistry.depositBond({ value: options.value });
+  }
+
+  /**
+   * Request withdrawal of bond (starts cooldown)
+   * @param amount - Amount to withdraw
+   */
+  async requestWithdrawal(amount: bigint): Promise<TransactionResponse> {
+    this.requireSigner();
+    return this.solverRegistry.requestWithdrawal(amount);
+  }
+
+  /**
+   * Cancel pending withdrawal
+   */
+  async cancelWithdrawal(): Promise<TransactionResponse> {
+    this.requireSigner();
+    return this.solverRegistry.cancelWithdrawal();
+  }
+
+  /**
+   * Execute withdrawal after cooldown
+   */
+  async executeWithdrawal(): Promise<TransactionResponse> {
+    this.requireSigner();
+    return this.solverRegistry.executeWithdrawal();
+  }
+
+  /**
+   * Unjail solver by paying penalty
+   * @param options.value - Unjail penalty amount
+   */
+  async unjail(options: { value: bigint }): Promise<TransactionResponse> {
+    this.requireSigner();
+    return this.solverRegistry.unjail({ value: options.value });
+  }
+
+  // ============ Intent Receipt Hub - Read ============
+
+  /**
+   * Get receipt by intent hash
+   */
+  async getReceipt(intentHash: string): Promise<IntentReceipt | null> {
+    try {
+      const data = await this.intentReceiptHub.getReceipt(intentHash);
+      if (data.solver === ethers.ZeroAddress) return null;
+      return {
+        solver: data.solver,
+        intentHash: data.intentHash,
+        constraintsHash: data.constraintsHash,
+        outcomeHash: data.outcomeHash,
+        evidenceHash: data.evidenceHash,
+        postedAt: data.postedAt,
+        deadline: data.deadline,
+        solverSig: data.solverSig,
+        status: Number(data.status) as ReceiptStatus,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get challenge for an intent
+   */
+  async getChallenge(intentHash: string): Promise<Challenge | null> {
+    try {
+      const data = await this.intentReceiptHub.getChallenge(intentHash);
+      if (data.challenger === ethers.ZeroAddress) return null;
+      return {
+        challenger: data.challenger,
+        reason: Number(data.reason) as DisputeReason,
+        bond: data.bond,
+        timestamp: data.timestamp,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get challenge window duration
+   */
+  async getChallengeWindow(): Promise<bigint> {
+    return this.intentReceiptHub.challengeWindow();
+  }
+
+  // ============ Intent Receipt Hub - Write ============
+
+  /**
+   * Post a receipt for an executed intent
+   */
+  async postReceipt(params: PostReceiptParams): Promise<TransactionResponse> {
+    this.requireSigner();
+    return this.intentReceiptHub.postReceipt(
+      params.intentHash,
+      params.constraintsHash,
+      params.outcomeHash,
+      params.evidenceHash,
+      params.deadline,
+      params.solverSig
+    );
+  }
+
+  /**
+   * Challenge a receipt
+   * @param intentHash - Hash of the intent to challenge
+   * @param reason - Dispute reason code
+   * @param options.value - Challenger bond (must meet minimum)
+   */
+  async challengeReceipt(
+    intentHash: string,
+    reason: DisputeReason,
+    options: { value: bigint }
+  ): Promise<TransactionResponse> {
+    this.requireSigner();
+    return this.intentReceiptHub.challengeReceipt(intentHash, reason, {
+      value: options.value,
+    });
+  }
+
+  /**
+   * Finalize a receipt after challenge window
+   */
+  async finalizeReceipt(intentHash: string): Promise<TransactionResponse> {
+    this.requireSigner();
+    return this.intentReceiptHub.finalizeReceipt(intentHash);
+  }
+
+  // ============ Dispute Module - Read ============
+
+  /**
+   * Get dispute details
+   */
+  async getDispute(intentHash: string): Promise<any | null> {
+    try {
+      const data = await this.disputeModule.getDispute(intentHash);
+      if (data.challenger === ethers.ZeroAddress) return null;
+      return data;
+    } catch {
+      return null;
+    }
+  }
+
+  // ============ Dispute Module - Write ============
+
+  /**
+   * Submit evidence for a dispute
+   */
+  async submitEvidence(
+    intentHash: string,
+    evidenceHash: string
+  ): Promise<TransactionResponse> {
+    this.requireSigner();
+    return this.disputeModule.submitEvidence(intentHash, evidenceHash);
+  }
+
+  /**
+   * Escalate dispute to arbitration
+   */
+  async escalateToArbitration(intentHash: string): Promise<TransactionResponse> {
+    this.requireSigner();
+    return this.disputeModule.escalateToArbitration(intentHash);
+  }
+
+  // ============ Utilities ============
+
+  /**
+   * Create a signed receipt for posting
+   */
+  async signReceipt(params: {
+    intentHash: string;
+    constraintsHash: string;
+    outcomeHash: string;
+    evidenceHash: string;
+    deadline: bigint;
+  }): Promise<string> {
+    this.requireSigner();
+
+    const message = ethers.solidityPackedKeccak256(
+      ['bytes32', 'bytes32', 'bytes32', 'bytes32', 'uint64'],
+      [
+        params.intentHash,
+        params.constraintsHash,
+        params.outcomeHash,
+        params.evidenceHash,
+        params.deadline,
+      ]
+    );
+
+    return this.signer!.signMessage(ethers.getBytes(message));
+  }
+
+  /**
+   * Calculate required challenger bond for a slash amount
+   */
+  calculateChallengerBond(slashAmount: bigint): bigint {
+    return (slashAmount * BigInt(CONSTANTS.CHALLENGER_BOND_BPS)) / BigInt(10000);
+  }
+
+  /**
+   * Get contract addresses
+   */
+  getAddresses() {
+    return {
+      solverRegistry: this.config.solverRegistry,
+      intentReceiptHub: this.config.intentReceiptHub,
+      disputeModule: this.config.disputeModule,
+    };
+  }
+
+  private requireSigner(): void {
+    if (!this.signer) {
+      throw new Error('Signer required for write operations');
+    }
+  }
+}

package/src/contracts/abis.ts

@@ -0,0 +1,80 @@
+/**
+ * Contract ABIs for IRSB Protocol
+ * Simplified to essential functions for SDK usage
+ */
+
+export const SOLVER_REGISTRY_ABI = [
+  // Read functions
+  'function MINIMUM_BOND() view returns (uint256)',
+  'function WITHDRAWAL_COOLDOWN() view returns (uint64)',
+  'function MAX_JAILS() view returns (uint8)',
+  'function solvers(address) view returns (uint256 bondAmount, uint256 lockedAmount, uint256 reputation, uint64 registrationTime, uint64 lastActiveTime, uint64 totalIntents, uint64 successfulIntents, uint8 jailCount, uint8 status, uint256 pendingWithdrawal, uint64 withdrawalRequestTime)',
+  'function isActiveSolver(address solver) view returns (bool)',
+  'function getSolverBond(address solver) view returns (uint256)',
+  'function getAvailableBond(address solver) view returns (uint256)',
+  'function owner() view returns (address)',
+
+  // Write functions
+  'function register() payable',
+  'function depositBond() payable',
+  'function requestWithdrawal(uint256 amount)',
+  'function cancelWithdrawal()',
+  'function executeWithdrawal()',
+  'function unjail() payable',
+
+  // Events
+  'event SolverRegistered(address indexed solver, uint256 bondAmount)',
+  'event BondDeposited(address indexed solver, uint256 amount, uint256 newTotal)',
+  'event WithdrawalRequested(address indexed solver, uint256 amount)',
+  'event WithdrawalExecuted(address indexed solver, uint256 amount)',
+  'event WithdrawalCancelled(address indexed solver)',
+  'event SolverSlashed(address indexed solver, uint256 amount, bytes32 reason)',
+  'event SolverJailed(address indexed solver, uint8 jailCount)',
+  'event SolverUnjailed(address indexed solver)',
+  'event SolverBanned(address indexed solver)',
+] as const;
+
+export const INTENT_RECEIPT_HUB_ABI = [
+  // Read functions
+  'function challengeWindow() view returns (uint64)',
+  'function challengerBondBps() view returns (uint16)',
+  'function receipts(bytes32) view returns (address solver, bytes32 intentHash, bytes32 constraintsHash, bytes32 outcomeHash, bytes32 evidenceHash, uint64 postedAt, uint64 deadline, bytes solverSig, uint8 status)',
+  'function challenges(bytes32) view returns (address challenger, uint8 reason, uint256 bond, uint64 timestamp)',
+  'function getReceipt(bytes32 intentHash) view returns (tuple(address solver, bytes32 intentHash, bytes32 constraintsHash, bytes32 outcomeHash, bytes32 evidenceHash, uint64 postedAt, uint64 deadline, bytes solverSig, uint8 status))',
+  'function getChallenge(bytes32 intentHash) view returns (tuple(address challenger, uint8 reason, uint256 bond, uint64 timestamp))',
+  'function solverRegistry() view returns (address)',
+
+  // Write functions
+  'function postReceipt(bytes32 intentHash, bytes32 constraintsHash, bytes32 outcomeHash, bytes32 evidenceHash, uint64 deadline, bytes solverSig)',
+  'function challengeReceipt(bytes32 intentHash, uint8 reason) payable',
+  'function finalizeReceipt(bytes32 intentHash)',
+  'function resolveDeterministic(bytes32 intentHash, bytes settlementProof)',
+
+  // Events
+  'event ReceiptPosted(bytes32 indexed intentHash, address indexed solver, uint64 deadline)',
+  'event ReceiptChallenged(bytes32 indexed intentHash, address indexed challenger, uint8 reason, uint256 bond)',
+  'event ReceiptFinalized(bytes32 indexed intentHash)',
+  'event ReceiptSlashed(bytes32 indexed intentHash, address indexed solver, uint256 slashAmount)',
+  'event ChallengeResolved(bytes32 indexed intentHash, bool solverWins)',
+] as const;
+
+export const DISPUTE_MODULE_ABI = [
+  // Read functions
+  'function evidenceWindow() view returns (uint64)',
+  'function arbitrationTimeout() view returns (uint64)',
+  'function arbitrator() view returns (address)',
+  'function disputes(bytes32) view returns (bytes32 intentHash, address challenger, address solver, uint8 reason, bytes32 solverEvidence, bytes32 challengerEvidence, uint64 createdAt, uint64 evidenceDeadline, uint8 status, uint8 resolution)',
+  'function getDispute(bytes32 intentHash) view returns (tuple(bytes32 intentHash, address challenger, address solver, uint8 reason, bytes32 solverEvidence, bytes32 challengerEvidence, uint64 createdAt, uint64 evidenceDeadline, uint8 status, uint8 resolution))',
+
+  // Write functions
+  'function submitEvidence(bytes32 intentHash, bytes32 evidenceHash)',
+  'function escalateToArbitration(bytes32 intentHash)',
+  'function resolveArbitration(bytes32 intentHash, uint8 resolution, uint16 solverShareBps)',
+  'function resolveByTimeout(bytes32 intentHash)',
+
+  // Events
+  'event DisputeCreated(bytes32 indexed intentHash, address indexed challenger, address indexed solver, uint8 reason)',
+  'event EvidenceSubmitted(bytes32 indexed intentHash, address indexed submitter, bytes32 evidenceHash)',
+  'event DisputeEscalated(bytes32 indexed intentHash)',
+  'event DisputeResolved(bytes32 indexed intentHash, uint8 resolution)',
+] as const;

package/src/index.ts

@@ -0,0 +1,39 @@
+/**
+ * IRSB Protocol SDK
+ *
+ * SDK for interacting with the IRSB (Intent Receipts & Solver Bonds) Protocol.
+ *
+ * @packageDocumentation
+ */
+
+// Main client
+export { IRSBClient, type IRSBClientConfig } from './client';
+
+// Types
+export {
+  // Enums
+  SolverStatus,
+  ReceiptStatus,
+  DisputeReason,
+  DisputeStatus,
+  DisputeResolution,
+  // Structs
+  type SolverInfo,
+  type IntentReceipt,
+  type Challenge,
+  type Dispute,
+  // Input types
+  type PostReceiptParams,
+  type ChallengeParams,
+  // Config
+  type ChainConfig,
+  CHAIN_CONFIGS,
+  CONSTANTS,
+} from './types';
+
+// ABIs (for advanced usage)
+export {
+  SOLVER_REGISTRY_ABI,
+  INTENT_RECEIPT_HUB_ABI,
+  DISPUTE_MODULE_ABI,
+} from './contracts/abis';

package/src/types.ts

@@ -0,0 +1,145 @@
+/**
+ * IRSB Protocol Types
+ * Matches Solidity contracts in src/libraries/Types.sol
+ */
+
+// ============ Enums ============
+
+export enum SolverStatus {
+  Inactive = 0,
+  Active = 1,
+  Jailed = 2,
+  Banned = 3,
+}
+
+export enum ReceiptStatus {
+  None = 0,
+  Posted = 1,
+  Challenged = 2,
+  Finalized = 3,
+  Slashed = 4,
+}
+
+export enum DisputeReason {
+  None = 0x00,
+  Timeout = 0x01,
+  MinOutViolation = 0x02,
+  WrongToken = 0x03,
+  WrongChain = 0x04,
+  WrongRecipient = 0x05,
+  ReceiptForgery = 0x06,
+  InvalidSignature = 0x07,
+}
+
+export enum DisputeStatus {
+  None = 0,
+  Open = 1,
+  EvidenceSubmitted = 2,
+  Escalated = 3,
+  Resolved = 4,
+}
+
+export enum DisputeResolution {
+  None = 0,
+  SolverWins = 1,
+  ChallengerWins = 2,
+  Split = 3,
+  Timeout = 4,
+}
+
+// ============ Structs ============
+
+export interface SolverInfo {
+  bondAmount: bigint;
+  lockedAmount: bigint;
+  reputation: bigint;
+  registrationTime: bigint;
+  lastActiveTime: bigint;
+  totalIntents: bigint;
+  successfulIntents: bigint;
+  jailCount: number;
+  status: SolverStatus;
+  pendingWithdrawal: bigint;
+  withdrawalRequestTime: bigint;
+}
+
+export interface IntentReceipt {
+  solver: string;
+  intentHash: string;
+  constraintsHash: string;
+  outcomeHash: string;
+  evidenceHash: string;
+  postedAt: bigint;
+  deadline: bigint;
+  solverSig: string;
+  status: ReceiptStatus;
+}
+
+export interface Challenge {
+  challenger: string;
+  reason: DisputeReason;
+  bond: bigint;
+  timestamp: bigint;
+}
+
+export interface Dispute {
+  intentHash: string;
+  challenger: string;
+  solver: string;
+  reason: DisputeReason;
+  solverEvidence: string;
+  challengerEvidence: string;
+  createdAt: bigint;
+  evidenceDeadline: bigint;
+  status: DisputeStatus;
+  resolution: DisputeResolution;
+}
+
+// ============ Input Types ============
+
+export interface PostReceiptParams {
+  intentHash: string;
+  constraintsHash: string;
+  outcomeHash: string;
+  evidenceHash: string;
+  deadline: bigint;
+  solverSig: string;
+}
+
+export interface ChallengeParams {
+  intentHash: string;
+  reason: DisputeReason;
+}
+
+// ============ Config ============
+
+export interface ChainConfig {
+  chainId: number;
+  rpcUrl: string;
+  solverRegistry: string;
+  intentReceiptHub: string;
+  disputeModule: string;
+}
+
+export const CHAIN_CONFIGS: Record<string, ChainConfig> = {
+  sepolia: {
+    chainId: 11155111,
+    rpcUrl: 'https://rpc.sepolia.org',
+    solverRegistry: '0xB6ab964832808E49635fF82D1996D6a888ecB745',
+    intentReceiptHub: '0xD66A1e880AA3939CA066a9EA1dD37ad3d01D977c',
+    disputeModule: '0x144DfEcB57B08471e2A75E78fc0d2A74A89DB79D',
+  },
+  // mainnet: { ... } // Add after mainnet deployment
+};
+
+// ============ Constants ============
+
+export const CONSTANTS = {
+  MINIMUM_BOND: BigInt('100000000000000000'), // 0.1 ETH
+  WITHDRAWAL_COOLDOWN: BigInt(7 * 24 * 60 * 60), // 7 days
+  MAX_JAILS: 3,
+  CHALLENGE_WINDOW: BigInt(60 * 60), // 1 hour
+  CHALLENGER_BOND_BPS: 1000, // 10%
+  EVIDENCE_WINDOW: BigInt(24 * 60 * 60), // 24 hours
+  ARBITRATION_TIMEOUT: BigInt(7 * 24 * 60 * 60), // 7 days
+} as const;