feat: publish @clevercon/vault-sdk — reusable typed SDK for CleverVault

packages/vault-sdk/README.md

@@ -0,0 +1,134 @@
+# @clevercon/vault-sdk
+
+Reusable typed SDK for the CleverVault Soroban smart contract.
+
+## Features
+
+- **Typed methods** for every contract entrypoint (deposit, withdraw, register/update orchestrator, create/complete/cancel task, release payment, all `get_*` views)
+- **Structured errors** — `VaultContractError` with `code`, `codeName`, and `known` flag; unknown/newer codes are preserved, never swallowed
+- **Event subscription** — helper over Soroban RPC `getEvents` with typed payloads and cursor handling
+- **Mock mode** — dependency-free deterministic responses for local development and testing
+- **Network config** — mainnet/testnet selection, contract ID, RPC URL
+
+## Quick Start
+
+```ts
+import { VaultClient } from '@clevercon/vault-sdk';
+
+const vault = new VaultClient({
+  contractId: process.env.AGENT_VAULT_CONTRACT_ID!,
+  rpcUrl: process.env.STELLAR_RPC_URL,
+  network: 'testnet',
+  usdcSac: process.env.USDC_SAC,
+});
+
+// Read-only views
+const balance = await vault.getBalance(userAddress);
+const account = await vault.getAccount(userAddress);
+const task = await vault.getTask(taskId);
+const status = await vault.getTaskStatus(taskId);
+
+// State-changing calls (returns unsigned XDR for Freighter)
+const xdr = await vault.buildDepositXdr(userAddress, 100);
+// ... user signs in Freighter ...
+await vault.submitSignedXdr(signedXdr);
+
+// Server-side calls (signed with keypair)
+const newTaskId = await vault.createTask(orchestratorKeypair, 50);
+await vault.releasePayment(orchestratorKeypair, newTaskId, 1n, 10);
+await vault.completeTask(orchestratorKeypair, newTaskId);
+```
+
+## Mock Mode
+
+For testing without RPC connectivity:
+
+```ts
+import { createMockVaultClient } from '@clevercon/vault-sdk';
+
+const mock = createMockVaultClient();
+
+// Simulate operations
+await mock.mockDeposit(userAddress, 100);
+await mock.mockRegisterOrchestrator(userAddress, orchAddress, 'MyOrch');
+const taskId = await mock.mockCreateTask(orchAddress, 10);
+
+// Read state
+const balance = await mock.getBalance(userAddress);
+const task = await mock.getTask(taskId);
+```
+
+## Error Handling
+
+```ts
+import { VaultContractError, VaultErrorCode } from '@clevercon/vault-sdk';
+
+try {
+  await vault.releasePayment(keypair, taskId, 1n, 100);
+} catch (err) {
+  if (err instanceof VaultContractError) {
+    switch (err.code) {
+      case VaultErrorCode.ExceedsPlanCost:
+        // Handle over-budget
+        break;
+      case VaultErrorCode.TaskAlreadyCompleted:
+        // Handle completed task
+        break;
+      default:
+        if (!err.known) {
+          // Unknown error code — contract may have been upgraded
+        }
+    }
+  }
+}
+```
+
+## Event Subscription
+
+```ts
+import { subscribeEvents } from '@clevercon/vault-sdk';
+
+const sub = subscribeEvents(
+  {
+    rpcUrl: 'https://soroban-testnet.stellar.org',
+    contractId: 'C...',
+    topics: ['release', 'task_done'],
+    pollIntervalMs: 5000,
+  },
+  (event) => {
+    switch (event.type) {
+      case 'release':
+        console.log(`Released ${event.payload.amount} for task ${event.payload.task_id}`);
+        break;
+      case 'task_done':
+        console.log(`Task ${event.payload.task_id} done, spent ${event.payload.spent}`);
+        break;
+    }
+  },
+);
+
+// Stop later
+sub.stop();
+```
+
+## Architecture
+
+```
+packages/vault-sdk/
+├── src/
+│   ├── index.ts          # Barrel exports
+│   ├── client.ts         # VaultClient — wraps every contract entrypoint
+│   ├── errors.ts         # VaultError model (mirrors lib.rs)
+│   ├── types.ts          # TypeScript interfaces for contract data
+│   ├── events.ts         # Event subscription with cursor handling
+│   ├── mock.ts           # Dependency-free mock mode
+│   ├── vault-errors.test.ts  # Divergence test against lib.rs
+│   └── client.test.ts    # Unit tests for client and mock
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Error Sync
+
+The `vault-errors.test.ts` file reads `contracts/agent-vault/src/lib.rs` at test time and verifies that `VaultErrorCode` matches every variant and discriminant. If the contract adds a new error variant, the test fails until the SDK is updated.

packages/vault-sdk/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@clevercon/vault-sdk",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@stellar/stellar-sdk": "^14.6.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.9"
+  }
+}

packages/vault-sdk/src/client.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect } from 'vitest';
+import { VaultClient } from './client.js';
+import { createMockVaultClient } from './mock.js';
+import { VaultErrorCode, VaultContractError } from './errors.js';
+
+describe('VaultClient.usdcToStroops / stroopsToUsdc', () => {
+  it('converts 1 USDC to 10_000_000 stroops', () => {
+    expect(VaultClient.usdcToStroops(1)).toBe(10_000_000n);
+  });
+
+  it('converts 0.5 USDC to 5_000_000 stroops', () => {
+    expect(VaultClient.usdcToStroops(0.5)).toBe(5_000_000n);
+  });
+
+  it('converts 10_000_000 stroops to 1 USDC', () => {
+    expect(VaultClient.stroopsToUsdc(10_000_000n)).toBe(1);
+  });
+
+  it('round-trips through USDC ↔ stroops', () => {
+    const usdc = 42.1234567;
+    const stroops = VaultClient.usdcToStroops(usdc);
+    expect(VaultClient.stroopsToUsdc(stroops)).toBeCloseTo(usdc, 1);
+  });
+});
+
+describe('createMockVaultClient', () => {
+  it('is in mock mode', () => {
+    const mock = createMockVaultClient();
+    expect(mock.mock).toBe(true);
+    expect(mock.active).toBe(true);
+  });
+
+  it('returns zeroed account for unknown user', async () => {
+    const mock = createMockVaultClient();
+    const acct = await mock.getAccount('GUNKNOWN');
+    expect(acct).toBeNull();
+  });
+
+  it('returns version 5', async () => {
+    const mock = createMockVaultClient();
+    expect(await mock.version()).toBe(5);
+  });
+
+  it('returns 1800 for stale threshold', async () => {
+    const mock = createMockVaultClient();
+    expect(await mock.getStaleThreshold()).toBe(1800);
+  });
+
+  it('returns 50 for max active tasks', async () => {
+    const mock = createMockVaultClient();
+    expect(await mock.getMaxActiveTasks()).toBe(50);
+  });
+
+  it('returns zero fee config by default', async () => {
+    const mock = createMockVaultClient();
+    const fee = await mock.getFee();
+    expect(fee.bps).toBe(0);
+    expect(fee.recipient).toBeNull();
+  });
+
+  it('mockDeposit increases user balance', async () => {
+    const mock = createMockVaultClient();
+    const user = 'GAAAAAAAABBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB';
+    const before = await mock.getBalance(user);
+    await mock.mockDeposit(user, 100);
+    const after = await mock.getBalance(user);
+    expect(after - before).toBe(1_000_000_000n);
+  });
+
+  it('mockRegisterOrchestrator records the mapping', async () => {
+    const mock = createMockVaultClient();
+    const user = 'GAAAAAAAABBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB';
+    const orch = 'GCCCCCCCDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD';
+    await mock.mockRegisterOrchestrator(user, orch, 'TestOrch');
+    const config = await mock.getUserConfig(user);
+    expect(config?.orchestrator).toBe(orch);
+    expect(config?.orchestrator_name).toBe('TestOrch');
+  });
+
+  it('mockRegisterOrchestrator throws OrchestratorAlreadyRegistered', async () => {
+    const mock = createMockVaultClient();
+    const user = 'GAAAAAAAABBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB';
+    const orch = 'GCCCCCCCDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD';
+    await mock.mockRegisterOrchestrator(user, orch, 'TestOrch');
+    await expect(mock.mockRegisterOrchestrator(user, orch, 'TestOrch')).rejects.toThrow(
+      VaultContractError,
+    );
+  });
+
+  it('mockCreateTask returns sequential task IDs', async () => {
+    const mock = createMockVaultClient();
+    const user = 'GAAAAAAAABBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB';
+    const orch = 'GCCCCCCCDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD';
+    await mock.mockRegisterOrchestrator(user, orch, 'TestOrch');
+    await mock.mockDeposit(user, 100);
+
+    const id1 = await mock.mockCreateTask(orch, 10);
+    const id2 = await mock.mockCreateTask(orch, 10);
+    expect(id2).toBe(id1 + 1n);
+  });
+
+  it('mockCreateTask throws OrchestratorNotRegistered for unknown orchestrator', async () => {
+    const mock = createMockVaultClient();
+    await expect(mock.mockCreateTask('GUNKNOWN', 10)).rejects.toThrow(VaultContractError);
+  });
+
+  it('mockCreateTask throws InsufficientAvailable when balance too low', async () => {
+    const mock = createMockVaultClient();
+    const user = 'GAAAAAAAABBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB';
+    const orch = 'GCCCCCCCDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD';
+    await mock.mockRegisterOrchestrator(user, orch, 'TestOrch');
+    // Don't deposit — balance is 0
+    await expect(mock.mockCreateTask(orch, 10)).rejects.toThrow(VaultContractError);
+  });
+
+  it('getTask returns task info after mockCreateTask', async () => {
+    const mock = createMockVaultClient();
+    const user = 'GAAAAAAAABBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB';
+    const orch = 'GCCCCCCCDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD';
+    await mock.mockRegisterOrchestrator(user, orch, 'TestOrch');
+    await mock.mockDeposit(user, 100);
+
+    const taskId = await mock.mockCreateTask(orch, 10);
+    const task = await mock.getTask(taskId);
+    expect(task).not.toBeNull();
+    expect(task?.user).toBe(user);
+    expect(task?.orchestrator).toBe(orch);
+    expect(task?.plan_cost).toBe(100_000_000n);
+    expect(task?.completed).toBe(false);
+    expect(task?.disputed).toBe(false);
+  });
+
+  it('getTaskStatus returns Active for a new task', async () => {
+    const mock = createMockVaultClient();
+    const user = 'GAAAAAAAABBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB';
+    const orch = 'GCCCCCCCDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD';
+    await mock.mockRegisterOrchestrator(user, orch, 'TestOrch');
+    await mock.mockDeposit(user, 100);
+
+    const taskId = await mock.mockCreateTask(orch, 10);
+    const status = await mock.getTaskStatus(taskId);
+    expect(status).toBe('Active');
+  });
+
+  it('taskCount increments after mockCreateTask', async () => {
+    const mock = createMockVaultClient();
+    const user = 'GAAAAAAAABBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB';
+    const orch = 'GCCCCCCCDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD';
+    await mock.mockRegisterOrchestrator(user, orch, 'TestOrch');
+    await mock.mockDeposit(user, 100);
+
+    expect(await mock.taskCount()).toBe(0n);
+    await mock.mockCreateTask(orch, 10);
+    expect(await mock.taskCount()).toBe(1n);
+    await mock.mockCreateTask(orch, 5);
+    expect(await mock.taskCount()).toBe(2n);
+  });
+});