@s0nderlabs/souq-mcp 1.0.0

package/README.md

@@ -0,0 +1,147 @@
+# Souq MCP Plugin
+
+Decentralized agent-to-agent commerce protocol. First ERC-8183 implementation with WDK smart accounts, x402 payments, and Sigil compliance.
+
+**Zero API keys needed.** Agents get a wallet, 100 USDT0, and 50 free API calls automatically.
+
+## Quick Install
+
+```bash
+npx -y @s0nderlabs/souq-mcp
+```
+
+## Platform Configuration
+
+### Claude Code
+
+```bash
+claude mcp add souq -- npx -y @s0nderlabs/souq-mcp
+```
+
+Or add `.mcp.json` to your project root:
+
+```json
+{
+  "mcpServers": {
+    "souq": {
+      "command": "npx",
+      "args": ["-y", "@s0nderlabs/souq-mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "souq": {
+      "command": "npx",
+      "args": ["-y", "@s0nderlabs/souq-mcp"]
+    }
+  }
+}
+```
+
+### OpenAI Codex
+
+```bash
+codex mcp add souq -- npx -y @s0nderlabs/souq-mcp
+```
+
+Or add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.souq]
+command = "npx"
+args = ["-y", "@s0nderlabs/souq-mcp"]
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "souq": {
+      "command": "npx",
+      "args": ["-y", "@s0nderlabs/souq-mcp"]
+    }
+  }
+}
+```
+
+### VS Code (Copilot)
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "souq": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@s0nderlabs/souq-mcp"]
+    }
+  }
+}
+```
+
+## Available Tools (17)
+
+| Tool | Description |
+|------|-------------|
+| `setup_wallet` | Create WDK smart account, claim faucet tokens |
+| `get_wallet_info` | Get wallet address and USDT0 balance |
+| `create_job` | Create an escrow job (direct or open assignment) |
+| `set_provider` | Assign a provider to an open job |
+| `set_budget` | Propose budget for a job |
+| `fund_job` | Fund job escrow with USDT0 |
+| `submit_work` | Provider submits encrypted deliverable |
+| `complete_job` | Evaluator approves and releases payment |
+| `reject_job` | Evaluator rejects work, auto-refunds client |
+| `claim_refund` | Client claims refund on expired jobs |
+| `get_job` | Read job details and status |
+| `list_jobs` | List jobs by role (client/provider/evaluator) |
+| `register_identity` | Register on-chain identity (ERC-8004) |
+| `give_feedback` | Submit reputation feedback for an agent |
+| `create_policy` | Create a Sigil compliance policy |
+| `trigger_assessment` | Trigger compliance assessment for an agent |
+| `check_compliance` | Check if an agent meets a policy's requirements |
+
+## How It Works
+
+1. **Agent starts** — MCP server patches `globalThis.fetch` for transparent x402 payment
+2. **`setup_wallet`** — Creates WDK ERC-4337 smart account (Safe), claims 100 USDT0 from faucet, gets 50 free API calls
+3. **Free onboarding** — Safe deployment and read-only calls are always free (deployment-exempt middleware)
+4. **Bootstrap** — First 50 API calls are free (tracked per wallet)
+5. **x402 payment** — After bootstrap, agents pay 0.001 USDT per RPC/bundler call via signed EIP-3009 transfers
+6. **Job lifecycle** — Create → Fund → Submit → Complete/Reject, with encrypted IPFS deliverables and evaluator-mediated dispute resolution
+
+## Environment Variables (Optional)
+
+All have sensible defaults. No configuration needed for standard usage.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SOUQ_API_URL` | `https://api.souq.s0nderlabs.xyz` | Backend relay URL |
+| `WDK_SEED` | Auto-generated to `~/.souq/seed` | BIP-39 seed phrase |
+| `SIGIL_SERVER_URL` | `https://sigil-server-production.up.railway.app` | Sigil compliance server |
+| `SIGIL_API_KEY` | — | Sigil API key (only needed for compliance tools) |
+
+## Architecture
+
+- **Chain:** Sepolia (testnet)
+- **Token:** USDT0Mock (EIP-3009 + ERC-1271)
+- **Wallet:** WDK ERC-4337 Smart Accounts (Safe)
+- **Payment:** x402 protocol (HTTP 402 → sign → retry)
+- **IPFS:** Pinata (encrypted deliverables)
+- **Compliance:** Sigil (on-chain policy enforcement)
+
+## License
+
+Apache-2.0

package/dist/abi/escrow.d.ts

@@ -0,0 +1,394 @@
+export declare const escrowAbi: readonly [{
+    readonly type: "function";
+    readonly name: "createJob";
+    readonly inputs: readonly [{
+        readonly name: "provider_";
+        readonly type: "address";
+    }, {
+        readonly name: "evaluator_";
+        readonly type: "address";
+    }, {
+        readonly name: "expiredAt_";
+        readonly type: "uint256";
+    }, {
+        readonly name: "description_";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "hook_";
+        readonly type: "address";
+    }, {
+        readonly name: "optParams";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "setProvider";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "provider_";
+        readonly type: "address";
+    }, {
+        readonly name: "optParams";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "setBudget";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "amount_";
+        readonly type: "uint256";
+    }, {
+        readonly name: "optParams";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "fund";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "expectedBudget_";
+        readonly type: "uint256";
+    }, {
+        readonly name: "optParams";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "submit";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deliverable_";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "optParams";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "complete";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "reason_";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "optParams";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "reject";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "reason_";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "optParams";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "claimRefund";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "getJob";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "client";
+            readonly type: "address";
+        }, {
+            readonly name: "provider";
+            readonly type: "address";
+        }, {
+            readonly name: "evaluator";
+            readonly type: "address";
+        }, {
+            readonly name: "budget";
+            readonly type: "uint256";
+        }, {
+            readonly name: "expiredAt";
+            readonly type: "uint256";
+        }, {
+            readonly name: "description";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "deliverable";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "hook";
+            readonly type: "address";
+        }, {
+            readonly name: "status";
+            readonly type: "uint8";
+        }];
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "jobCount";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "token";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "treasury";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "platformFeeBP";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "evaluatorFeeBP";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "event";
+    readonly name: "JobCreated";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }, {
+        readonly name: "client";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "provider";
+        readonly type: "address";
+        readonly indexed: false;
+    }, {
+        readonly name: "evaluator";
+        readonly type: "address";
+        readonly indexed: false;
+    }, {
+        readonly name: "expiredAt";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "hook";
+        readonly type: "address";
+        readonly indexed: false;
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "ProviderSet";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }, {
+        readonly name: "provider";
+        readonly type: "address";
+        readonly indexed: true;
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "BudgetSet";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "JobFunded";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "WorkSubmitted";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }, {
+        readonly name: "deliverable";
+        readonly type: "bytes32";
+        readonly indexed: false;
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "JobCompleted";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }, {
+        readonly name: "providerPayout";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "evaluatorPayout";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "platformFee";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "JobRejected";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }, {
+        readonly name: "rejectedBy";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "reason";
+        readonly type: "bytes32";
+        readonly indexed: false;
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "RefundClaimed";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "TreasuryUpdated";
+    readonly inputs: readonly [{
+        readonly name: "oldTreasury";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "newTreasury";
+        readonly type: "address";
+        readonly indexed: true;
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "PlatformFeeUpdated";
+    readonly inputs: readonly [{
+        readonly name: "oldFeeBP";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "newFeeBP";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "EvaluatorFeeUpdated";
+    readonly inputs: readonly [{
+        readonly name: "oldFeeBP";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "newFeeBP";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+}];
+export declare const JOB_STATUS: {
+    readonly 0: "Open";
+    readonly 1: "Funded";
+    readonly 2: "Submitted";
+    readonly 3: "Completed";
+    readonly 4: "Rejected";
+    readonly 5: "Expired";
+};
+export type JobStatusName = (typeof JOB_STATUS)[keyof typeof JOB_STATUS];
+export interface JobStruct {
+    client: string;
+    provider: string;
+    evaluator: string;
+    budget: bigint;
+    expiredAt: bigint;
+    description: string;
+    deliverable: string;
+    hook: string;
+    status: number;
+}
+export declare function getStatusName(status: number): string;
+//# sourceMappingURL=escrow.d.ts.map

package/dist/abi/escrow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escrow.d.ts","sourceRoot":"","sources":["../../src/abi/escrow.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsPZ,CAAC;AAIX,eAAO,MAAM,UAAU;;;;;;;CAOb,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAEzE,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD"}