Skip to content

Commit 04f8036

Browse files
Samuel1-onaSamuel1-ona
committed
updated Readme.md with the new changes
1 parent 30f673d commit 04f8036

File tree

1 file changed

+246
-0
lines changed

1 file changed

+246
-0
lines changed

‎README.md‎

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,12 +78,22 @@ Earn rewards for completing specific milestones:
7878
- Encourages regular player engagement
7979
- Configurable reward amounts
8080

81+
### Cross-Chain Architecture
82+
- **Horizontal Scaling**: Application runs on multiple Linera chains simultaneously
83+
- **Global State Synchronization**: Players, markets, and guilds synchronized across all chains
84+
- **Idempotent Messaging**: Safe message retries with duplicate detection
85+
- **Conflict Resolution**: Timestamp-based ordering prevents stale updates
86+
- **Global Leaderboards**: Aggregated rankings across all chains
87+
- **Reliable Broadcasting**: Messages use authentication and tracking for guaranteed delivery
88+
8189
## Technical Stack
8290

8391
- **Blockchain**: Linera Protocol v0.15.4
8492
- **Smart Contract Language**: Rust
8593
- **State Management**: Linera Views (persistent storage)
8694
- **Oracle Integration**: External price feed from crypto APIs
95+
- **Cross-Chain Messaging**: Linera's native message system with idempotency and conflict resolution
96+
- **Development Tools**: Docker, Docker Compose, Makefile for streamlined development
8797

8898
## Getting Started
8999

@@ -165,6 +175,11 @@ Earn rewards for completing specific milestones:
165175
- **Level Requirements**: Market creation and selling restricted by level
166176
- **Balance Checks**: Prevent overdraft on all transactions
167177
- **Fee Validation**: Market fees capped at 100%
178+
- **Cross-Chain Security**:
179+
- Message deduplication prevents replay attacks
180+
- Timestamp-based conflict resolution prevents race conditions
181+
- Idempotent operations safe to retry
182+
- Message authentication ensures integrity
168183

169184
## Economic Model
170185

@@ -1189,6 +1204,235 @@ Achievements: O(7) fixed (7 predefined achievements)
11891204
- Periodic leaderboard snapshots (reduce recalculation frequency)
11901205
- Lazy resolution (resolve on-demand vs. batch resolution)
11911206

1207+
---
1208+
1209+
## 10. Cross-Chain Architecture
1210+
1211+
### 10.1 Overview
1212+
1213+
Roxy Price implements a robust cross-chain messaging system that enables the application to scale horizontally across multiple Linera chains while maintaining global state consistency.
1214+
1215+
### 10.2 Architecture
1216+
1217+
```
1218+
┌─────────────────────────────────────────────────────────────┐
1219+
│ Chain 1 (Roxy Instance) │
1220+
│ ┌────────────────────────────────────────────────────────┐ │
1221+
│ │ Local State: Players, Markets, Guilds (Chain 1) │ │
1222+
│ └────────────────────────────────────────────────────────┘ │
1223+
│ ┌────────────────────────────────────────────────────────┐ │
1224+
│ │ Global State: Cross-Chain Registry │ │
1225+
│ │ - global_players: All players across all chains │ │
1226+
│ │ - global_markets: All markets across all chains │ │
1227+
│ │ - global_guilds: All guilds across all chains │ │
1228+
│ │ - subscribed_chains: Chain registry │ │
1229+
│ └────────────────────────────────────────────────────────┘ │
1230+
└───────────────────┬───────────────────────────────────────────┘
1231+
│ Messages
1232+
▼
1233+
┌───────────────────────┐
1234+
│ Linera Message Bus │
1235+
│ (Authenticated & │
1236+
│ Tracked Messages) │
1237+
└───────────────────────┘
1238+
▲
1239+
│ Messages
1240+
┌───────────────────┴───────────────────────────────────────────┐
1241+
│ Chain 2 (Roxy Instance) │
1242+
│ ┌────────────────────────────────────────────────────────┐ │
1243+
│ │ Local State: Players, Markets, Guilds (Chain 2) │ │
1244+
│ └────────────────────────────────────────────────────────┘ │
1245+
│ ┌────────────────────────────────────────────────────────┐ │
1246+
│ │ Global State: Cross-Chain Registry (Synced) │ │
1247+
│ └────────────────────────────────────────────────────────┘ │
1248+
└─────────────────────────────────────────────────────────────────┘
1249+
```
1250+
1251+
### 10.3 Key Features
1252+
1253+
#### Message Deduplication
1254+
- **Unique Message IDs**: Each cross-chain message includes a unique ID based on content, chain, and timestamp
1255+
- **Processed Message Tracking**: `processed_message_ids` MapView tracks all processed messages
1256+
- **Idempotent Operations**: Messages can be safely retried without side effects
1257+
1258+
#### Conflict Resolution
1259+
- **Timestamp-Based Ordering**: `GlobalPlayerUpdated` messages include timestamps
1260+
- **Last-Write-Wins**: Only newer updates are applied (timestamp > existing `last_updated`)
1261+
- **Price Validation**: `GlobalPriceUpdate` only applies if incoming timestamp is newer
1262+
1263+
#### Idempotency Checks
1264+
- **Player Registration**: Only registers if player doesn't already exist
1265+
- **Market Creation**: Only creates if market doesn't already exist
1266+
- **Guild Creation**: Only creates if guild doesn't already exist
1267+
1268+
### 10.4 Message Types
1269+
1270+
All cross-chain messages include:
1271+
- `message_id`: Unique identifier for deduplication
1272+
- `chain_id`: Source chain identifier
1273+
- `timestamp`: For conflict resolution (where applicable)
1274+
1275+
**Message Types:**
1276+
- `GlobalPlayerRegistered`: Broadcast player registration
1277+
- `GlobalPlayerUpdated`: Broadcast player state changes (with timestamp)
1278+
- `GlobalMarketCreated`: Broadcast market creation
1279+
- `GlobalGuildCreated`: Broadcast guild creation
1280+
- `GlobalPriceUpdate`: Broadcast price updates (with timestamp validation)
1281+
- `ChainRegistered`: Chain discovery and registration
1282+
1283+
### 10.5 State Synchronization
1284+
1285+
**Global Registries:**
1286+
- `global_players`: All players across all chains with their current chain location
1287+
- `global_markets`: All markets with their origin chain
1288+
- `global_guilds`: All guilds with their origin chain
1289+
- `global_leaderboard`: Aggregated leaderboard across all chains
1290+
1291+
**Update Flow:**
1292+
1. Local operation occurs on Chain A
1293+
2. Chain A updates its local state
1294+
3. Chain A broadcasts message to all subscribed chains
1295+
4. Receiving chains update their global registries
1296+
5. Global leaderboard recalculated on each chain
1297+
1298+
### 10.6 Reliability
1299+
1300+
- **Message Authentication**: All messages use `.with_authentication()`
1301+
- **Message Tracking**: All messages use `.with_tracking()` for delivery guarantees
1302+
- **Error Handling**: Proper error propagation and state consistency
1303+
- **Network Resilience**: Safe to retry on network failures
1304+
1305+
---
1306+
1307+
## 11. Development Setup
1308+
1309+
### 11.1 Prerequisites
1310+
1311+
- Docker and Docker Compose installed
1312+
- (Optional) Rust 1.86.0+ for local development
1313+
- Git for version control
1314+
1315+
### 11.2 Quick Start with Docker (Recommended)
1316+
1317+
```bash
1318+
# Clone the repository
1319+
git clone <repository-url>
1320+
cd roxy/roxy
1321+
1322+
# Start development container
1323+
docker-compose up -d roxy-dev
1324+
1325+
# Access container shell
1326+
docker-compose exec roxy-dev bash
1327+
1328+
# Build and test
1329+
cargo build --release
1330+
cargo test --jobs 1
1331+
```
1332+
1333+
### 11.3 Docker Services
1334+
1335+
- **roxy-dev**: Development container with all build tools
1336+
- Rust 1.86.0
1337+
- wasm32-unknown-unknown target
1338+
- clippy, rustfmt tools
1339+
- Volume-mounted for live code editing
1340+
1341+
- **roxy**: Production container with built binaries
1342+
- Minimal runtime image
1343+
- Optimized WASM binaries
1344+
- Production-ready deployment
1345+
1346+
### 11.4 Available Commands
1347+
1348+
Using Makefile:
1349+
```bash
1350+
make build # Build the project
1351+
make test # Run tests
1352+
make docker-dev # Start dev container
1353+
make docker-shell # Access container shell
1354+
```
1355+
1356+
Using Docker Compose:
1357+
```bash
1358+
docker-compose exec roxy-dev cargo build
1359+
docker-compose exec roxy-dev cargo test --jobs 1
1360+
docker-compose exec roxy-dev cargo clippy
1361+
docker-compose exec roxy-dev cargo fmt --check
1362+
```
1363+
1364+
### 11.5 Memory Management
1365+
1366+
For large builds, the container is configured with:
1367+
- `CARGO_BUILD_JOBS=2`: Limits parallel compilation
1368+
- `CARGO_INCREMENTAL=1`: Enables incremental compilation
1369+
- `.cargo/config.toml`: Build job limits
1370+
1371+
If you encounter linker errors (signal 9), try:
1372+
```bash
1373+
# Run with single job
1374+
docker-compose exec roxy-dev cargo test --jobs 1
1375+
1376+
# Or increase Docker Desktop memory limit to 6-8GB
1377+
```
1378+
1379+
### 11.6 Local Development (Without Docker)
1380+
1381+
```bash
1382+
# Install Rust 1.86.0
1383+
rustup install 1.86.0
1384+
rustup default 1.86.0
1385+
1386+
# Install wasm32 target
1387+
rustup target add wasm32-unknown-unknown
1388+
1389+
# Install tools
1390+
rustup component add clippy rustfmt rust-src
1391+
1392+
# Install system dependencies (Ubuntu/Debian)
1393+
sudo apt-get install -y pkg-config libssl-dev protobuf-compiler
1394+
1395+
# Build and test
1396+
cargo build --release
1397+
cargo build --release --target wasm32-unknown-unknown
1398+
cargo test
1399+
```
1400+
1401+
See `QUICK_START.md` for detailed Docker setup instructions.
1402+
1403+
---
1404+
1405+
## 9. Scalability Considerations
1406+
1407+
### 9.1 Storage Optimization
1408+
1409+
**Key Strategies**:
1410+
- Use composite keys for predictions: `"{player_id}_{period}_{period_start}"`
1411+
- Limit leaderboard to top 50 players and top 20 guilds
1412+
- Period prices stored per period (not per player)
1413+
- Achievements stored globally (not duplicated per player)
1414+
- Message deduplication tracking to prevent unbounded growth
1415+
1416+
**Storage Growth**:
1417+
```
1418+
Players: O(n) where n = number of players
1419+
Markets: O(m) where m = number of markets
1420+
Predictions: O(n × p × t) where:
1421+
- n = number of players
1422+
- p = prediction periods (3: daily/weekly/monthly)
1423+
- t = time periods (grows continuously)
1424+
Guilds: O(g) where g = number of guilds
1425+
Achievements: O(7) fixed (7 predefined achievements)
1426+
Processed Messages: O(m) where m = cross-chain messages sent
1427+
```
1428+
1429+
**Mitigation Strategies**:
1430+
- Implement prediction archival (move old predictions to cold storage)
1431+
- Set max active markets per player (currently unlimited)
1432+
- Periodic leaderboard snapshots (reduce recalculation frequency)
1433+
- Lazy resolution (resolve on-demand vs. batch resolution)
1434+
- Message ID expiration (TTL for old message IDs - future enhancement)
1435+
11921436
### 9.2 Computational Complexity
11931437

11941438
**Operation Complexities**:
@@ -1203,6 +1447,8 @@ Achievements: O(7) fixed (7 predefined achievements)
12031447
| ResolveExpiredPredictions | O(n × p) | n players, p periods |
12041448
| UpdateLeaderboard | O(n log n) | Sort all players/guilds |
12051449
| CheckAchievements | O(a) | a = number of achievements (fixed 7) |
1450+
| BroadcastCrossChainMessage | O(c) | c = number of subscribed chains |
1451+
| ProcessCrossChainMessage | O(1) | Message deduplication check + state update |
12061452

12071453
**Performance Bottlenecks**:
12081454

0 commit comments

Comments
 (0)