irsb-sdk 0.1.0

package/README.md

@@ -0,0 +1,251 @@
+# @irsb/sdk
+
+TypeScript SDK for the IRSB Protocol (Intent Receipts & Solver Bonds).
+
+## Installation
+
+```bash
+npm install @irsb/sdk ethers
+```
+
+## Quick Start
+
+```typescript
+import { IRSBClient } from '@irsb/sdk';
+import { ethers } from 'ethers';
+
+// Connect to Sepolia
+const provider = new ethers.JsonRpcProvider('https://rpc.sepolia.org');
+const signer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
+
+const client = new IRSBClient({
+  chain: 'sepolia',
+  signer,
+});
+
+// Check if registered
+const isActive = await client.isActiveSolver(signer.address);
+console.log('Active solver:', isActive);
+```
+
+## Solver Registration
+
+```typescript
+// Register with minimum bond (0.1 ETH)
+const tx = await client.register({
+  value: ethers.parseEther('0.1'),
+});
+await tx.wait();
+console.log('Registered as solver');
+
+// Deposit more bond
+await client.depositBond({
+  value: ethers.parseEther('0.5'),
+});
+
+// Check bond balance
+const bond = await client.getSolverBond(signer.address);
+console.log('Total bond:', ethers.formatEther(bond), 'ETH');
+```
+
+## Posting Receipts
+
+After executing an intent off-chain, post a receipt:
+
+```typescript
+import { IRSBClient, PostReceiptParams } from '@irsb/sdk';
+
+// Prepare receipt data
+const intentHash = ethers.keccak256(ethers.toUtf8Bytes('intent-data'));
+const constraintsHash = ethers.keccak256(ethers.toUtf8Bytes('constraints'));
+const outcomeHash = ethers.keccak256(ethers.toUtf8Bytes('outcome'));
+const evidenceHash = ethers.ZeroHash; // or IPFS hash of proof
+const deadline = BigInt(Math.floor(Date.now() / 1000) + 3600); // 1 hour
+
+// Sign the receipt
+const solverSig = await client.signReceipt({
+  intentHash,
+  constraintsHash,
+  outcomeHash,
+  evidenceHash,
+  deadline,
+});
+
+// Post on-chain
+const tx = await client.postReceipt({
+  intentHash,
+  constraintsHash,
+  outcomeHash,
+  evidenceHash,
+  deadline,
+  solverSig,
+});
+await tx.wait();
+console.log('Receipt posted:', tx.hash);
+```
+
+## Challenging Receipts
+
+If you observe a violation:
+
+```typescript
+import { DisputeReason } from '@irsb/sdk';
+
+// Calculate required bond (10% of potential slash)
+const slashAmount = ethers.parseEther('0.1');
+const challengerBond = client.calculateChallengerBond(slashAmount);
+
+// Submit challenge
+const tx = await client.challengeReceipt(
+  intentHash,
+  DisputeReason.MinOutViolation,
+  { value: challengerBond }
+);
+await tx.wait();
+console.log('Challenge submitted');
+```
+
+## Withdrawing Bond
+
+```typescript
+// Request withdrawal (starts 7-day cooldown)
+await client.requestWithdrawal(ethers.parseEther('0.1'));
+
+// After 7 days, execute withdrawal
+await client.executeWithdrawal();
+
+// Or cancel if needed
+await client.cancelWithdrawal();
+```
+
+## Reading State
+
+```typescript
+// Get solver info
+const solver = await client.getSolver('0x...');
+console.log('Status:', solver.status);
+console.log('Bond:', ethers.formatEther(solver.bondAmount));
+console.log('Reputation:', solver.reputation);
+console.log('Jail count:', solver.jailCount);
+
+// Get receipt
+const receipt = await client.getReceipt(intentHash);
+if (receipt) {
+  console.log('Solver:', receipt.solver);
+  console.log('Status:', receipt.status);
+}
+
+// Get challenge
+const challenge = await client.getChallenge(intentHash);
+if (challenge) {
+  console.log('Challenger:', challenge.challenger);
+  console.log('Reason:', challenge.reason);
+}
+```
+
+## Types
+
+```typescript
+import {
+  SolverStatus,
+  ReceiptStatus,
+  DisputeReason,
+  SolverInfo,
+  IntentReceipt,
+  CONSTANTS,
+} from '@irsb/sdk';
+
+// Enums
+SolverStatus.Active    // 1
+ReceiptStatus.Posted   // 1
+DisputeReason.Timeout  // 0x01
+
+// Constants
+CONSTANTS.MINIMUM_BOND         // 0.1 ETH
+CONSTANTS.WITHDRAWAL_COOLDOWN  // 7 days
+CONSTANTS.CHALLENGE_WINDOW     // 1 hour
+```
+
+## Custom Chain Config
+
+```typescript
+const client = new IRSBClient({
+  chain: {
+    chainId: 1,
+    rpcUrl: 'https://mainnet.infura.io/v3/...',
+    solverRegistry: '0x...',
+    intentReceiptHub: '0x...',
+    disputeModule: '0x...',
+  },
+  signer,
+});
+```
+
+## Contract Addresses
+
+### Sepolia Testnet
+
+| Contract | Address |
+|----------|---------|
+| SolverRegistry | `0xB6ab964832808E49635fF82D1996D6a888ecB745` |
+| IntentReceiptHub | `0xD66A1e880AA3939CA066a9EA1dD37ad3d01D977c` |
+| DisputeModule | `0x144DfEcB57B08471e2A75E78fc0d2A74A89DB79D` |
+
+## API Reference
+
+### IRSBClient
+
+#### Constructor
+
+```typescript
+new IRSBClient(options: {
+  chain: string | ChainConfig;
+  signer?: Signer;
+  provider?: Provider;
+})
+```
+
+#### Solver Registry Methods
+
+| Method | Description |
+|--------|-------------|
+| `getSolver(address)` | Get solver info |
+| `isActiveSolver(address)` | Check if active |
+| `getSolverBond(address)` | Get total bond |
+| `getAvailableBond(address)` | Get unlocked bond |
+| `register({ value })` | Register as solver |
+| `depositBond({ value })` | Add to bond |
+| `requestWithdrawal(amount)` | Start withdrawal |
+| `executeWithdrawal()` | Complete withdrawal |
+| `cancelWithdrawal()` | Cancel withdrawal |
+| `unjail({ value })` | Pay to unjail |
+
+#### Receipt Hub Methods
+
+| Method | Description |
+|--------|-------------|
+| `getReceipt(intentHash)` | Get receipt |
+| `getChallenge(intentHash)` | Get challenge |
+| `postReceipt(params)` | Post receipt |
+| `challengeReceipt(hash, reason, { value })` | Challenge |
+| `finalizeReceipt(intentHash)` | Finalize |
+
+#### Dispute Module Methods
+
+| Method | Description |
+|--------|-------------|
+| `getDispute(intentHash)` | Get dispute |
+| `submitEvidence(hash, evidenceHash)` | Submit evidence |
+| `escalateToArbitration(intentHash)` | Escalate |
+
+#### Utilities
+
+| Method | Description |
+|--------|-------------|
+| `signReceipt(params)` | Sign receipt data |
+| `calculateChallengerBond(slashAmount)` | Calculate bond |
+| `getAddresses()` | Get contract addresses |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,290 @@
+import { Provider, Signer, TransactionResponse } from 'ethers';
+
+/**
+ * IRSB Protocol Types
+ * Matches Solidity contracts in src/libraries/Types.sol
+ */
+declare enum SolverStatus {
+    Inactive = 0,
+    Active = 1,
+    Jailed = 2,
+    Banned = 3
+}
+declare enum ReceiptStatus {
+    None = 0,
+    Posted = 1,
+    Challenged = 2,
+    Finalized = 3,
+    Slashed = 4
+}
+declare enum DisputeReason {
+    None = 0,
+    Timeout = 1,
+    MinOutViolation = 2,
+    WrongToken = 3,
+    WrongChain = 4,
+    WrongRecipient = 5,
+    ReceiptForgery = 6,
+    InvalidSignature = 7
+}
+declare enum DisputeStatus {
+    None = 0,
+    Open = 1,
+    EvidenceSubmitted = 2,
+    Escalated = 3,
+    Resolved = 4
+}
+declare enum DisputeResolution {
+    None = 0,
+    SolverWins = 1,
+    ChallengerWins = 2,
+    Split = 3,
+    Timeout = 4
+}
+interface SolverInfo {
+    bondAmount: bigint;
+    lockedAmount: bigint;
+    reputation: bigint;
+    registrationTime: bigint;
+    lastActiveTime: bigint;
+    totalIntents: bigint;
+    successfulIntents: bigint;
+    jailCount: number;
+    status: SolverStatus;
+    pendingWithdrawal: bigint;
+    withdrawalRequestTime: bigint;
+}
+interface IntentReceipt {
+    solver: string;
+    intentHash: string;
+    constraintsHash: string;
+    outcomeHash: string;
+    evidenceHash: string;
+    postedAt: bigint;
+    deadline: bigint;
+    solverSig: string;
+    status: ReceiptStatus;
+}
+interface Challenge {
+    challenger: string;
+    reason: DisputeReason;
+    bond: bigint;
+    timestamp: bigint;
+}
+interface Dispute {
+    intentHash: string;
+    challenger: string;
+    solver: string;
+    reason: DisputeReason;
+    solverEvidence: string;
+    challengerEvidence: string;
+    createdAt: bigint;
+    evidenceDeadline: bigint;
+    status: DisputeStatus;
+    resolution: DisputeResolution;
+}
+interface PostReceiptParams {
+    intentHash: string;
+    constraintsHash: string;
+    outcomeHash: string;
+    evidenceHash: string;
+    deadline: bigint;
+    solverSig: string;
+}
+interface ChallengeParams {
+    intentHash: string;
+    reason: DisputeReason;
+}
+interface ChainConfig {
+    chainId: number;
+    rpcUrl: string;
+    solverRegistry: string;
+    intentReceiptHub: string;
+    disputeModule: string;
+}
+declare const CHAIN_CONFIGS: Record<string, ChainConfig>;
+declare const CONSTANTS: {
+    readonly MINIMUM_BOND: bigint;
+    readonly WITHDRAWAL_COOLDOWN: bigint;
+    readonly MAX_JAILS: 3;
+    readonly CHALLENGE_WINDOW: bigint;
+    readonly CHALLENGER_BOND_BPS: 1000;
+    readonly EVIDENCE_WINDOW: bigint;
+    readonly ARBITRATION_TIMEOUT: bigint;
+};
+
+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...',
+ * });
+ * ```
+ */
+declare class IRSBClient {
+    readonly config: ChainConfig;
+    readonly provider: Provider;
+    readonly signer?: Signer;
+    private solverRegistry;
+    private intentReceiptHub;
+    private disputeModule;
+    constructor(options: IRSBClientConfig);
+    /**
+     * Get solver information
+     */
+    getSolver(address: string): Promise<SolverInfo>;
+    /**
+     * Check if address is an active solver
+     */
+    isActiveSolver(address: string): Promise<boolean>;
+    /**
+     * Get solver's total bond amount
+     */
+    getSolverBond(address: string): Promise<bigint>;
+    /**
+     * Get solver's available (unlocked) bond
+     */
+    getAvailableBond(address: string): Promise<bigint>;
+    /**
+     * Get minimum bond required for registration
+     */
+    getMinimumBond(): Promise<bigint>;
+    /**
+     * Register as a solver with initial bond
+     * @param options.value - ETH to deposit as bond (must be >= MINIMUM_BOND)
+     */
+    register(options: {
+        value: bigint;
+    }): Promise<TransactionResponse>;
+    /**
+     * Deposit additional bond
+     * @param options.value - ETH to deposit
+     */
+    depositBond(options: {
+        value: bigint;
+    }): Promise<TransactionResponse>;
+    /**
+     * Request withdrawal of bond (starts cooldown)
+     * @param amount - Amount to withdraw
+     */
+    requestWithdrawal(amount: bigint): Promise<TransactionResponse>;
+    /**
+     * Cancel pending withdrawal
+     */
+    cancelWithdrawal(): Promise<TransactionResponse>;
+    /**
+     * Execute withdrawal after cooldown
+     */
+    executeWithdrawal(): Promise<TransactionResponse>;
+    /**
+     * Unjail solver by paying penalty
+     * @param options.value - Unjail penalty amount
+     */
+    unjail(options: {
+        value: bigint;
+    }): Promise<TransactionResponse>;
+    /**
+     * Get receipt by intent hash
+     */
+    getReceipt(intentHash: string): Promise<IntentReceipt | null>;
+    /**
+     * Get challenge for an intent
+     */
+    getChallenge(intentHash: string): Promise<Challenge | null>;
+    /**
+     * Get challenge window duration
+     */
+    getChallengeWindow(): Promise<bigint>;
+    /**
+     * Post a receipt for an executed intent
+     */
+    postReceipt(params: PostReceiptParams): Promise<TransactionResponse>;
+    /**
+     * Challenge a receipt
+     * @param intentHash - Hash of the intent to challenge
+     * @param reason - Dispute reason code
+     * @param options.value - Challenger bond (must meet minimum)
+     */
+    challengeReceipt(intentHash: string, reason: DisputeReason, options: {
+        value: bigint;
+    }): Promise<TransactionResponse>;
+    /**
+     * Finalize a receipt after challenge window
+     */
+    finalizeReceipt(intentHash: string): Promise<TransactionResponse>;
+    /**
+     * Get dispute details
+     */
+    getDispute(intentHash: string): Promise<any | null>;
+    /**
+     * Submit evidence for a dispute
+     */
+    submitEvidence(intentHash: string, evidenceHash: string): Promise<TransactionResponse>;
+    /**
+     * Escalate dispute to arbitration
+     */
+    escalateToArbitration(intentHash: string): Promise<TransactionResponse>;
+    /**
+     * Create a signed receipt for posting
+     */
+    signReceipt(params: {
+        intentHash: string;
+        constraintsHash: string;
+        outcomeHash: string;
+        evidenceHash: string;
+        deadline: bigint;
+    }): Promise<string>;
+    /**
+     * Calculate required challenger bond for a slash amount
+     */
+    calculateChallengerBond(slashAmount: bigint): bigint;
+    /**
+     * Get contract addresses
+     */
+    getAddresses(): {
+        solverRegistry: string;
+        intentReceiptHub: string;
+        disputeModule: string;
+    };
+    private requireSigner;
+}
+
+/**
+ * Contract ABIs for IRSB Protocol
+ * Simplified to essential functions for SDK usage
+ */
+declare const SOLVER_REGISTRY_ABI: readonly ["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)", "function register() payable", "function depositBond() payable", "function requestWithdrawal(uint256 amount)", "function cancelWithdrawal()", "function executeWithdrawal()", "function unjail() payable", "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)"];
+declare const INTENT_RECEIPT_HUB_ABI: readonly ["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)", "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)", "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)"];
+declare const DISPUTE_MODULE_ABI: readonly ["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))", "function submitEvidence(bytes32 intentHash, bytes32 evidenceHash)", "function escalateToArbitration(bytes32 intentHash)", "function resolveArbitration(bytes32 intentHash, uint8 resolution, uint16 solverShareBps)", "function resolveByTimeout(bytes32 intentHash)", "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)"];
+
+export { CHAIN_CONFIGS, CONSTANTS, type ChainConfig, type Challenge, type ChallengeParams, DISPUTE_MODULE_ABI, type Dispute, DisputeReason, DisputeResolution, DisputeStatus, INTENT_RECEIPT_HUB_ABI, IRSBClient, type IRSBClientConfig, type IntentReceipt, type PostReceiptParams, ReceiptStatus, SOLVER_REGISTRY_ABI, type SolverInfo, SolverStatus };