diff --git a/docs/milestones/phase-2-apis-cli.md b/docs/milestones/phase-2-apis-cli.md new file mode 100644 index 0000000..b4eb1c4 --- /dev/null +++ b/docs/milestones/phase-2-apis-cli.md @@ -0,0 +1,471 @@ +# Phase 2: REST APIs, WebSockets, RPC, and CLI + +## Overview + +Build production-ready API layers and CLI tools for all Synor services, enabling developers to interact with the blockchain through multiple interfaces. + +**Scope**: REST endpoints, WebSocket subscriptions, JSON-RPC 2.0, CLI tools +**Services**: All 11 services (Wallet, RPC, Storage, Database, Hosting, Bridge, Mining, Economics, Governance, Privacy, Contract) + +--- + +## Architecture + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ API Gateway Layer │ +├──────────────────────────────────────────────────────────────────────┤ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ REST API │ │ WebSocket │ │ JSON-RPC │ │ CLI │ │ +│ │ │ │ │ │ 2.0 │ │ │ │ +│ │ - OpenAPI │ │ - Pub/Sub │ │ - Batch │ │ - synor │ │ +│ │ - Rate Limit│ │ - Events │ │ - Methods │ │ - Commands │ │ +│ │ - Auth │ │ - Heartbeat │ │ - Subscribe │ │ - Interactive│ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ +└──────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌──────────────────────────────────────────────────────────────────────┐ +│ Service Layer │ +├──────────────────────────────────────────────────────────────────────┤ +│ Wallet │ RPC │ Storage │ Database │ Hosting │ Bridge │ Mining │ ... │ +└──────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Component 1: REST APIs + +### Endpoint Structure + +``` +https://api.synor.io/v1/{service}/{resource} + +Examples: + POST /v1/wallet/create + GET /v1/wallet/{address}/balance + POST /v1/rpc/send-transaction + GET /v1/storage/{cid} + POST /v1/database/kv/set +``` + +### Authentication + +```http +Authorization: Bearer {api_key} +X-API-Key: {api_key} # Alternative header +``` + +### Rate Limiting + +| Tier | Requests/min | Burst | Concurrent | +|------------|--------------|-------|------------| +| Free | 60 | 10 | 5 | +| Developer | 600 | 100 | 20 | +| Pro | 6000 | 1000 | 100 | +| Enterprise | Unlimited | N/A | N/A | + +### Response Format + +```json +{ + "success": true, + "data": { ... }, + "meta": { + "request_id": "req_abc123", + "timestamp": "2024-01-15T10:30:00Z", + "latency_ms": 45 + } +} +``` + +### Error Format + +```json +{ + "success": false, + "error": { + "code": "INSUFFICIENT_BALANCE", + "message": "Account balance too low for transaction", + "details": { + "required": "1000000", + "available": "500000" + } + }, + "meta": { ... } +} +``` + +### OpenAPI Specification + +Generate OpenAPI 3.1 specs for all services: + +```yaml +openapi: 3.1.0 +info: + title: Synor API + version: 1.0.0 +paths: + /v1/wallet/create: + post: + summary: Create a new wallet + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateWalletRequest' + responses: + '200': + description: Wallet created + content: + application/json: + schema: + $ref: '#/components/schemas/Wallet' +``` + +--- + +## Component 2: WebSocket API + +### Connection + +```javascript +const ws = new WebSocket('wss://ws.synor.io/v1'); + +// Authenticate on connect +ws.send(JSON.stringify({ + type: 'auth', + api_key: 'your-api-key' +})); +``` + +### Subscription Model + +```javascript +// Subscribe to events +ws.send(JSON.stringify({ + type: 'subscribe', + channel: 'blocks', + params: { chain: 'synor-mainnet' } +})); + +// Receive events +ws.onmessage = (event) => { + const msg = JSON.parse(event.data); + // { type: 'event', channel: 'blocks', data: { ... } } +}; + +// Unsubscribe +ws.send(JSON.stringify({ + type: 'unsubscribe', + channel: 'blocks' +})); +``` + +### Available Channels + +| Channel | Description | Params | +|---------|-------------|--------| +| `blocks` | New blocks | `chain` | +| `transactions` | Transaction updates | `txid` or `address` | +| `address` | Address activity | `address` | +| `orders` | Order book updates | `market` | +| `trades` | Trade executions | `market` | +| `positions` | Position changes | `account` | +| `transfers` | IBC transfers | `channel` | +| `packets` | IBC packets | `channel` | + +### Heartbeat + +```javascript +// Server sends ping every 30s +{ "type": "ping", "timestamp": 1705312200 } + +// Client must respond with pong +{ "type": "pong" } +``` + +--- + +## Component 3: JSON-RPC 2.0 + +### Endpoint + +``` +POST https://rpc.synor.io/v1 +Content-Type: application/json +``` + +### Request Format + +```json +{ + "jsonrpc": "2.0", + "method": "synor_getBlock", + "params": ["latest"], + "id": 1 +} +``` + +### Batch Requests + +```json +[ + {"jsonrpc": "2.0", "method": "synor_getBlock", "params": [100], "id": 1}, + {"jsonrpc": "2.0", "method": "synor_getBlock", "params": [101], "id": 2}, + {"jsonrpc": "2.0", "method": "synor_getBlock", "params": [102], "id": 3} +] +``` + +### Method Namespaces + +| Namespace | Service | Example Methods | +|-----------|---------|-----------------| +| `synor_` | Core RPC | `getBlock`, `sendTransaction`, `getBalance` | +| `wallet_` | Wallet | `create`, `sign`, `getAddress` | +| `storage_` | Storage | `upload`, `download`, `pin` | +| `db_` | Database | `kvGet`, `kvSet`, `query` | +| `bridge_` | Bridge | `lock`, `mint`, `burn`, `unlock` | +| `mining_` | Mining | `getTemplate`, `submitWork` | +| `gov_` | Governance | `createProposal`, `vote` | +| `zk_` | ZK Proofs | `prove`, `verify`, `compile` | + +### Subscriptions (via WebSocket) + +```json +// Subscribe +{"jsonrpc": "2.0", "method": "synor_subscribe", "params": ["newBlocks"], "id": 1} + +// Notification +{"jsonrpc": "2.0", "method": "synor_subscription", "params": {"subscription": "0x1", "result": {...}}} + +// Unsubscribe +{"jsonrpc": "2.0", "method": "synor_unsubscribe", "params": ["0x1"], "id": 2} +``` + +--- + +## Component 4: CLI Tool + +### Installation + +```bash +# npm +npm install -g @synor/cli + +# Homebrew +brew install synor/tap/synor + +# Cargo +cargo install synor-cli + +# Binary download +curl -fsSL https://synor.io/install.sh | sh +``` + +### Configuration + +```bash +# Initialize with API key +synor init --api-key YOUR_API_KEY + +# Set network +synor config set network mainnet + +# Config file: ~/.synor/config.toml +``` + +### Command Structure + +``` +synor [options] + +Examples: + synor wallet create + synor wallet balance 0x123... + synor rpc block latest + synor storage upload ./file.txt + synor dex order place --market ETH-USDC --side buy --price 3000 --qty 0.1 +``` + +### Service Commands + +#### Wallet +```bash +synor wallet create # Create new wallet +synor wallet import --mnemonic "..." # Import from mnemonic +synor wallet balance
# Get balance +synor wallet send # Send tokens +synor wallet sign --message "..." # Sign message +``` + +#### RPC +```bash +synor rpc block # Get block +synor rpc tx # Get transaction +synor rpc send # Send transaction +synor rpc subscribe blocks # Subscribe to blocks +``` + +#### Storage +```bash +synor storage upload # Upload file +synor storage download -o # Download file +synor storage pin # Pin content +synor storage ls # List directory +``` + +#### DEX +```bash +synor dex markets # List markets +synor dex orderbook ETH-USDC # Get orderbook +synor dex order place ... # Place order +synor dex order cancel # Cancel order +synor dex positions # List positions +``` + +#### Bridge +```bash +synor bridge chains # List supported chains +synor bridge transfer --from cosmos --to synor --amount 1 ATOM +synor bridge status # Check transfer status +``` + +#### ZK +```bash +synor zk compile # Compile circuit +synor zk prove # Generate proof +synor zk verify # Verify proof +``` + +### Interactive Mode + +```bash +synor --interactive + +synor> wallet balance +? Select address: 0x123...abc +Balance: 1,234.56 SYNOR + +synor> dex order place +? Market: ETH-USDC +? Side: buy +? Type: limit +? Price: 3000 +? Quantity: 0.1 +Order placed: ord_abc123 + +synor> exit +``` + +### Output Formats + +```bash +# JSON (default for scripts) +synor wallet balance 0x123 --format json + +# Table (default for humans) +synor dex markets --format table + +# YAML +synor rpc block latest --format yaml + +# Quiet (just values) +synor wallet balance 0x123 --quiet +``` + +--- + +## Implementation Plan + +### Phase 2.1: REST API Foundation (2 weeks) +- [ ] API gateway setup with rate limiting +- [ ] Authentication middleware +- [ ] OpenAPI spec generation +- [ ] Error handling standardization +- [ ] Request/response logging + +### Phase 2.2: Core Service APIs (3 weeks) +- [ ] Wallet REST endpoints +- [ ] RPC REST endpoints +- [ ] Storage REST endpoints +- [ ] Contract REST endpoints + +### Phase 2.3: WebSocket Infrastructure (2 weeks) +- [ ] WebSocket server setup +- [ ] Pub/sub channel system +- [ ] Connection management +- [ ] Heartbeat/reconnection logic + +### Phase 2.4: JSON-RPC Layer (2 weeks) +- [ ] JSON-RPC 2.0 implementation +- [ ] Batch request handling +- [ ] Subscription support +- [ ] Method routing + +### Phase 2.5: CLI Development (3 weeks) +- [ ] CLI framework setup (clap for Rust) +- [ ] Configuration management +- [ ] Core commands implementation +- [ ] Interactive mode +- [ ] Shell completions + +### Phase 2.6: Platform APIs (2 weeks) +- [ ] Database REST/RPC +- [ ] Hosting REST/RPC +- [ ] Bridge REST/RPC +- [ ] Mining REST/RPC + +### Phase 2.7: DeFi APIs (2 weeks) +- [ ] DEX REST/WebSocket +- [ ] Economics REST +- [ ] Governance REST/RPC +- [ ] Privacy REST/RPC + +### Phase 2.8: Documentation & Testing (2 weeks) +- [ ] API documentation site +- [ ] Integration tests +- [ ] Load testing +- [ ] Security audit + +--- + +## Success Criteria + +1. **API Coverage**: All 11 services accessible via REST, WebSocket, and RPC +2. **Performance**: <100ms p95 latency for REST, <10ms for WebSocket events +3. **Reliability**: 99.9% uptime, graceful degradation +4. **Documentation**: Complete OpenAPI specs, CLI help, tutorials +5. **Developer Experience**: Quick start possible in <5 minutes + +--- + +## Docker Ports + +| Service | REST Port | WebSocket Port | RPC Port | +|---------|-----------|----------------|----------| +| Gateway | 8000 | 8001 | 8002 | +| Wallet | 8010 | - | 8012 | +| RPC | 8020 | 8021 | 8022 | +| Storage | 8030 | - | 8032 | +| Database| 8040 | 8041 | 8042 | +| Hosting | 8050 | - | 8052 | +| Bridge | 8060 | 8061 | 8062 | +| Mining | 8070 | 8071 | 8072 | +| Economics| 8080 | - | 8082 | +| Governance| 8090 | 8091 | 8092 | +| Privacy | 8100 | - | 8102 | +| Contract| 8110 | 8111 | 8112 | +| DEX | 8120 | 8121 | 8122 | +| ZK | 8130 | - | 8132 | +| IBC | 8140 | 8141 | 8142 | +| Compiler| 8150 | - | 8152 | + +--- + +## Next Steps + +After Phase 2 completion: +- Phase 3: SDK code generation from OpenAPI specs +- Phase 4: Developer portal and playground +- Phase 5: Monitoring and analytics dashboard