# 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 <service> <command> [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 <address>          # Get balance
synor wallet send <to> <amount>         # Send tokens
synor wallet sign --message "..."       # Sign message
```

#### RPC
```bash
synor rpc block <height|hash|latest>    # Get block
synor rpc tx <txid>                     # Get transaction
synor rpc send <signed-tx>              # Send transaction
synor rpc subscribe blocks              # Subscribe to blocks
```

#### Storage
```bash
synor storage upload <file>             # Upload file
synor storage download <cid> -o <path>  # Download file
synor storage pin <cid>                 # Pin content
synor storage ls <cid>                  # 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 <id>             # 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 <id>                # Check transfer status
```

#### ZK
```bash
synor zk compile <circuit.circom>       # Compile circuit
synor zk prove <circuit> <witness>      # Generate proof
synor zk verify <proof>                 # 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