docs: Add Phase 2 milestone for REST APIs, WebSockets, RPC, and CLI
Comprehensive planning document covering: - REST API design with OpenAPI 3.1 specs - WebSocket pub/sub architecture for real-time events - JSON-RPC 2.0 implementation with batch support - CLI tool (synor) with interactive mode - Docker port assignments for all services - Implementation timeline and success criteria
This commit is contained in:
Gulshan Yadav
parent
cf5130d9e4
commit
b9f1f013b3
1 changed files with 471 additions and 0 deletions
471
docs/milestones/phase-2-apis-cli.md
Normal file
471
docs/milestones/phase-2-apis-cli.md
Normal file
|
|
@ -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 <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
|
||||||
Loading…
Add table
Reference in a new issue