Skip to content

Commit 4bc8313

Browse files
echobtechobt
committed
docs: update README to reflect centralized architecture
- Replace P2P/gossipsub references with platform-server HTTP/WebSocket - Update ports (8080 API, 8090 broker instead of 9000/8545) - Add missing env vars (PLATFORM_SERVER_URL, DATABASE_URL, etc.) - Document WebSocket endpoints (/ws, /ws/challenge) - Document bridge proxy (/api/v1/bridge/{challenge_id}/*) - Add unified platform binary documentation
1 parent e662a48 commit 4bc8313

File tree

1 file changed

+62
-37
lines changed

1 file changed

+62
-37
lines changed

‎README.md‎

Lines changed: 62 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@
3030
- **Challenge-Based Architecture**: Modular Docker containers define custom evaluation logic
3131
- **Byzantine Fault Tolerance**: PBFT consensus with $2f+1$ threshold ensures correctness
3232
- **Secure Weight Submission**: Weights submitted to Bittensor at epoch boundaries
33-
- **Merkle State Sync**: Verifiable distributed database with optimistic execution
33+
- **Centralized Coordination**: Platform-server provides HTTP/WebSocket APIs for validators
3434
- **Multi-Mechanism Support**: Each challenge maps to a Bittensor mechanism for independent weight setting
3535
- **Stake-Weighted Security**: Minimum 1000 TAO stake required for validator participation
3636

@@ -61,8 +61,8 @@ The coordination between validators ensures that only verified, consensus-valida
6161
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
6262
│ │
6363
│ ┌───────────────────────────────────────────────────────────────────────┐ │
64-
│ │ Distributed Database (Merkle Trie) │ │
65-
│ │ Evaluation Results • Scores • Agent Data │ │
64+
│ │ Platform Server (chain.platform.network) │ │
65+
│ │ PostgreSQL Database • HTTP API • WebSocket Events │ │
6666
│ └───────────────────────────────────────────────────────────────────────┘ │
6767
└─────────────────────────────────┬───────────────────────────────────────────┘
6868
│
@@ -106,14 +106,14 @@ The coordination between validators ensures that only verified, consensus-valida
106106
2. **Submission**:
107107

108108
- Submit to any validator via HTTP API
109-
- Submission is stored in distributed database and synced across all validators
109+
- Submission is stored in PostgreSQL database at platform-server
110110
- Submission includes: source code, miner hotkey, metadata
111111

112112
3. **Evaluation**:
113113

114114
- All validators independently evaluate the submission
115115
- Evaluation runs in isolated Docker containers (challenge-specific logic)
116-
- Results are stored in Merkle-verified distributed database
116+
- Results are stored in PostgreSQL database at platform-server
117117

118118
4. **Weight Distribution**:
119119
- At epoch end, validators aggregate scores
@@ -139,15 +139,15 @@ The coordination between validators ensures that only verified, consensus-valida
139139

140140
2. **Submission Evaluation**:
141141

142-
- Receive submissions via P2P gossipsub
142+
- Receive submissions via platform-server HTTP API
143143
- Execute evaluation in sandboxed Docker environment
144144
- Compute score $s \in [0, 1]$ based on challenge criteria
145145

146146
3. **Result Sharing**:
147147

148-
- Broadcast `EvaluationResult` to all peers via P2P
149-
- Store results in distributed Merkle-verified database
150-
- Verify state root matches across validators
148+
- Submit `EvaluationResult` to platform-server via HTTP API
149+
- Results stored in PostgreSQL database at platform-server
150+
- Platform-server broadcasts events to validators via WebSocket
151151

152152
4. **Score Aggregation**:
153153

@@ -239,18 +239,13 @@ $$\text{threshold} = 2f + 1 = \left\lfloor \frac{2n}{3} \right\rfloor + 1$$
239239
- `SudoAction::SetRequiredVersion` - Mandatory version update
240240
- `NewBlock` - State checkpoint
241241

242-
### Distributed Database Consensus
242+
### Centralized State Management
243243

244-
State synchronization uses Merkle trie verification:
244+
Platform-server (run by subnet owner at `chain.platform.network`) maintains authoritative state:
245245

246-
```
247-
StateRoot = MerkleRoot({(k_i, v_i) : ∀ entries})
248-
```
249-
250-
Validators periodically compare state roots:
251-
252-
- **In Consensus**: $\geq 2/3$ validators share same root
253-
- **Diverged**: Minority validators must sync from majority
246+
- **PostgreSQL Database**: Stores all submissions, evaluations, and scores
247+
- **HTTP API (port 8080)**: Validators submit and retrieve data
248+
- **WebSocket Events**: Real-time notifications to connected validators
254249

255250
---
256251

@@ -290,7 +285,7 @@ Low confidence (high variance) may exclude submission from weights.
290285

291286
- **Minimum Stake**: 1000 TAO required for validator participation
292287
- **Sybil Resistance**: Creating fake validators requires significant capital
293-
- **Stake Validation**: All P2P messages verified against metagraph stakes
288+
- **Stake Validation**: All API requests verified against metagraph stakes
294289

295290
### Network Protection
296291

@@ -309,9 +304,9 @@ Low confidence (high variance) may exclude submission from weights.
309304

310305
### Data Integrity
311306

312-
- **Merkle Verification**: All data changes update state root
313-
- **Signature Verification**: All messages signed by validator keys
314-
- **Optimistic Execution**: Immediate local apply, confirmed at block
307+
- **Centralized Database**: Platform-server maintains authoritative PostgreSQL state
308+
- **Signature Verification**: All API requests signed by validator keys
309+
- **WebSocket Sync**: Validators receive real-time state updates
315310

316311
---
317312

@@ -352,7 +347,7 @@ Each Bittensor epoch (~360 blocks, ~72 minutes):
352347

353348
- Receive and process submissions from challenges
354349
- Execute evaluations in Docker containers
355-
- Sync results via P2P to distributed database
350+
- Submit results to platform-server via HTTP API
356351
- Aggregate scores from all validators
357352

358353
### Weight Submission
@@ -371,7 +366,7 @@ cp .env.example .env
371366
docker compose up -d
372367
```
373368

374-
The validator will auto-connect to `bootnode.platform.network` and sync.
369+
The validator will auto-connect to platform-server at `chain.platform.network` and sync.
375370

376371
## Hardware Requirements
377372

@@ -386,21 +381,51 @@ The validator will auto-connect to `bootnode.platform.network` and sync.
386381
387382
## Network Requirements
388383

389-
**Port 9000/tcp must be open** for P2P communication.
384+
| Port | Protocol | Usage |
385+
| -------- | --------- | ------------------------------------------ |
386+
| 8080/tcp | HTTP | Platform-server API |
387+
| 8090/tcp | WebSocket | Container Broker (challenge communication) |
388+
389+
## API Endpoints
390+
391+
### HTTP API (port 8080)
392+
393+
Standard REST endpoints for submissions, evaluations, and challenges.
390394

391-
| Port | Protocol | Usage |
392-
| -------- | ------------ | ---------------------------------- |
393-
| 9000/tcp | P2P (libp2p) | Validator communication (required) |
394-
| 8545/tcp | HTTP | JSON-RPC API (optional) |
395+
### WebSocket Endpoints
396+
397+
| Endpoint | Description |
398+
| ---------------------------------- | --------------------------------- |
399+
| `/ws` | Validator events |
400+
| `/ws/challenge` | Challenge container events |
401+
402+
### Bridge Proxy
403+
404+
| Endpoint | Description |
405+
| ---------------------------------- | --------------------------------- |
406+
| `/api/v1/bridge/{challenge_id}/*` | Proxy to challenge containers |
395407

396408
## Configuration
397409

398-
| Variable | Description | Default |
399-
| ---------------------- | ------------------------- | ------------------------------------------- |
400-
| `VALIDATOR_SECRET_KEY` | BIP39 mnemonic or hex key | Required |
401-
| `SUBTENSOR_ENDPOINT` | Bittensor RPC endpoint | `wss://entrypoint-finney.opentensor.ai:443` |
402-
| `NETUID` | Subnet UID | `100` |
403-
| `RUST_LOG` | Log level | `info` |
410+
| Variable | Description | Default |
411+
| ---------------------- | ------------------------------------ | ------------------------------------------- |
412+
| `VALIDATOR_SECRET_KEY` | BIP39 mnemonic or hex key | Required |
413+
| `SUBTENSOR_ENDPOINT` | Bittensor RPC endpoint | `wss://entrypoint-finney.opentensor.ai:443` |
414+
| `NETUID` | Subnet UID | `100` |
415+
| `RUST_LOG` | Log level | `info` |
416+
| `PLATFORM_SERVER_URL` | Platform server URL | `https://chain.platform.network` |
417+
| `PLATFORM_PUBLIC_URL` | Public URL for challenge containers | Required |
418+
| `DATABASE_URL` | PostgreSQL connection (server only) | Required for platform-server |
419+
| `OWNER_HOTKEY` | Subnet owner hotkey | Required for platform-server |
420+
| `BROKER_WS_PORT` | Container broker WebSocket port | `8090` |
421+
| `BROKER_JWT_SECRET` | JWT secret for broker authentication | Required |
422+
423+
## Binary
424+
425+
The unified `platform` binary supports two subcommands:
426+
427+
- `platform server` - Run the platform-server (subnet owner only)
428+
- `platform validator` - Run a validator node
404429

405430
---
406431

@@ -425,7 +450,7 @@ Platform creates a trustless, decentralized framework for evaluating miner submi
425450
- **PBFT Consensus** for Byzantine fault tolerance
426451
- **Stake-Weighted Aggregation** for Sybil resistance
427452
- **Docker Isolation** for deterministic evaluation (challenge-specific logic)
428-
- **Merkle State Sync** for verifiable distributed storage
453+
- **Centralized Platform Server** for authoritative state management
429454

430455
The system ensures that only genuine, high-performing submissions receive rewards, while making manipulation economically infeasible. Validators are incentivized to provide accurate evaluations through reputation mechanics, and miners are incentivized to submit quality solutions through the weight distribution mechanism.
431456

0 commit comments

Comments
 (0)