synor/docs/milestones/phase-2-apis-cli.md

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

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

{
  "success": true,
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z",
    "latency_ms": 45
  }
}

Error Format

{
  "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:

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

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

// 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

// 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

{
  "jsonrpc": "2.0",
  "method": "synor_getBlock",
  "params": ["latest"],
  "id": 1
}

Batch Requests

[
  {"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)

// 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

# 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

# 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

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

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

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

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

synor bridge chains                     # List supported chains
synor bridge transfer --from cosmos --to synor --amount 1 ATOM
synor bridge status <id>                # Check transfer status

ZK

synor zk compile <circuit.circom>       # Compile circuit
synor zk prove <circuit> <witness>      # Generate proof
synor zk verify <proof>                 # Verify proof

Interactive Mode

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

# 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