misaradmin/synor
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 4

docs: Add Phase 2 milestone for REST APIs, WebSockets, RPC, and CLI

Browse source 
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 2026-01-28 14:45:30 +05:30
parent cf5130d9e4
commit b9f1f013b3
1 changed files with 471 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

471
docs/milestones/phase-2-apis-cli.md Normal file
View 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