/ README.md
README.md
1 # ADNET - Alpha/Delta Unified Binary 2 3 > Two chains, one binary. Consensus among equals. 4 5 [](LICENSE) 6 [](https://rust-lang.org) 7 [](https://source.ac-dc.network/alpha-delta-network/adnet/actions) 8 9 ## Why ADNET Exists 10 11 Most "layer 2" solutions are afterthoughts - bolt-ons attempting to scale blockchains never designed for composition. The result: bridge exploits (billions lost to wrapped token vulnerabilities), cross-chain latency (seconds or minutes for "atomic" operations), trust assumptions (relying on bridge validators or threshold signatures). 12 13 The fundamental problem: **treating dual-chain systems as separate networks connected by bridges**. This forces inter-chain operations through network gossip, introducing latency, failure modes, and attack surfaces. 14 15 ADNET inverts this paradigm. Alpha and Delta were designed together, from first principles, as complementary systems unified in a single process. Privacy (Alpha) and exchange (Delta) as fundamental duals, not layered patches. **The architecture enables what others call "atomic cross-chain operations" but we consider internal function calls** - microsecond IPC instead of network gossip. 16 17 One deployment. One upgrade. One consensus set. Validators run both chains simultaneously with shared networking, storage, and state verification. The result: the efficiency of a monolithic system with the separation of concerns of a modular architecture. 18 19 ## What ADNET Does 20 21 ADNET is the unified runtime binary for the Alpha/Delta Protocol, containing both AlphaVM (privacy layer) and DeltaVM (exchange layer) in a single executable. It implements dual-chain consensus, shared peer-to-peer networking, unified storage backend, and microsecond inter-process communication for cross-chain attestations. 22 23 **Core Capabilities:** 24 - **Dual Runtime**: Runs AlphaVM and DeltaVM simultaneously in separate threads with shared infrastructure 25 - **Unified Networking**: Single P2P stack for both chains - one peer discovery, one gossip protocol, two message streams 26 - **Microsecond IPC**: Cross-chain attestations via internal channels (<1μs latency), not bridge transactions 27 - **Single Deployment**: One binary, one configuration, one upgrade process for both chains 28 - **Node Types**: Validator (full consensus), Prover (proof generation), Client (query only) 29 30 ## Architecture Context 31 32 The Alpha/Delta Protocol implements monetary sovereignty through a tri-layer architecture: 33 34 ``` 35 ┌─────────────────────────────────────────────────────────────────────┐ 36 │ ALPHA/DELTA PROTOCOL │ 37 │ │ 38 │ ALPHA Chain (Privacy Layer) DELTA Chain (Exchange Layer) │ 39 │ ┌─────────────────────────┐ ┌─────────────────────────┐ │ 40 │ │ AlphaVM │ │ DeltaVM │ │ 41 │ │ ┌──────────────────┐ │ │ ┌──────────────────┐ │ │ 42 │ │ │ credits.alpha │ │ │ │ Turing-Complete │ │ │ 43 │ │ │ (13 instructions)│ │ │ │ (60+ instructions│ │ │ 44 │ │ │ UTXO/Records │ │ │ │ Account-based │ │ │ 45 │ │ └──────────────────┘ │ │ └──────────────────┘ │ │ 46 │ │ │ │ │ │ 47 │ │ Full ZK Privacy │◄─────┤ Shielded Holdings │ │ 48 │ │ Governor-minted AX │ IPC │ Public Trading DX/sAX │ │ 49 │ │ 15s blocks, Port 3030 │(<1μs)│ 3s blocks, Port 4030 │ │ 50 │ └─────────────────────────┘ └─────────────────────────┘ │ 51 │ │ │ │ 52 │ └────────────┬────────────────────┘ │ 53 │ │ │ 54 │ ┌────▼────┐ │ 55 │ │ ADNET │ │ 56 │ │(unified │ │ 57 │ │ binary) │ │ 58 │ └─────────┘ │ 59 └─────────────────────────────────────────────────────────────────────┘ 60 ``` 61 62 ### Components 63 64 **AlphaVM** - Privacy-preserving virtual machine with restricted instruction set. Executes only `credits.alpha`, the hardcoded program for private peer-to-peer exchange. Zero-knowledge proofs ensure transaction validity without revealing amounts, parties, or graph structure. 65 66 **DeltaVM** - Turing-complete virtual machine for exchange and governance. Supports arbitrary program deployment, account-based state, and public/shielded asset trading. Enables decentralized exchange (DX), governance votes, and central bank operations (sAX minting). 67 68 **ADNET** - Unified binary runtime containing both AlphaVM and DeltaVM. Single deployment, shared networking, microsecond inter-chain communication. Validators run both chains simultaneously with atomic cross-chain operations via IPC. 69 70 ### Design Rationale 71 72 **Why two VMs?** Separation of concerns at the execution layer enables freedom at the application layer. Privacy-first monetary transactions on Alpha. Open trading and governance on Delta. Neither compromises the other. 73 74 **Why unified binary?** Eliminates bridge exploits, wrapped tokens, and cross-chain latency. What others call "atomic cross-chain operations" are internal function calls in ADNET - microsecond IPC instead of network gossip. 75 76 **Why restricted Alpha?** Turing-completeness sacrificed for certainty. No smart contracts means no exploits, no governance attacks on deployed code, no censorship vectors beyond the base protocol. Simple, auditable, sovereign money. 77 78 ## Component Specification 79 80 Full technical details: [R001-unified_binary.component.cspec](https://source.ac-dc.network/alpha-delta-network/alpha-delta-context/src/branch/main/components/runtime/R001-unified_binary.component.cspec) 81 82 ## Node Types 83 84 ADNET supports three node types, each with different resource requirements and capabilities: 85 86 | Type | Description | CPU | RAM | Storage | Network | 87 |------|-------------|-----|-----|---------|---------| 88 | **Validator** | Full consensus participant - validates both chains, participates in BFT rounds, earns staking rewards | 8+ cores | 32GB+ | 1TB SSD | 100Mbps+ | 89 | **Prover** | Generates zero-knowledge proofs for Alpha transactions - CPU-intensive, earns proof fees | 16+ cores | 64GB+ | 100GB SSD | 50Mbps+ | 90 | **Client** | Query-only node - syncs both chains, serves RPC API, no consensus participation | 4 cores | 16GB | 500GB SSD | 25Mbps+ | 91 92 ## Prerequisites 93 94 - Rust 1.87+ (stable toolchain) 95 - Ubuntu 22.04+ or macOS 13+ 96 - Sufficient hardware (see Node Types table above) 97 - Open firewall ports: 4130 (Alpha P2P), 4131 (Delta P2P), 3030 (Alpha API), 4030 (Delta API) 98 99 ## Installation 100 101 ### Binary Installation (Recommended) 102 103 ```bash 104 # Using the unified installer 105 curl -sSf https://source.ac-dc.network/install.sh | sh 106 ac-dc install adnet 107 ``` 108 109 ### Build from Source 110 111 ```bash 112 git clone https://source.ac-dc.network/alpha-delta-network/adnet.git 113 cd adnet 114 cargo build --release --bin adnet 115 ``` 116 117 The compiled binary will be in `target/release/adnet`. 118 119 ## Quick Start 120 121 ### Running a Validator 122 123 ```bash 124 # Initialize configuration 125 adnet init --node-type validator 126 127 # Start the node 128 adnet start 129 130 # Or run directly 131 adnet --config ~/.adnet/config.toml 132 ``` 133 134 Configuration file: `~/.adnet/config.toml` 135 136 ### Key Configuration Options 137 138 ```toml 139 [network] 140 alpha_p2p_port = 4130 141 delta_p2p_port = 4131 142 alpha_api_port = 3030 143 delta_api_port = 4030 144 145 [node] 146 type = "validator" # or "prover" or "client" 147 data_dir = "~/.adnet/data" 148 149 [consensus] 150 # Block times (conservative launch config) 151 alpha_block_time = "10s" # Target: 15s post-launch 152 delta_block_time = "10s" # Target: 3s post-launch 153 154 [validator] 155 # Only required if type = "validator" 156 private_key_path = "~/.adnet/validator.key" 157 stake_address = "aleo1..." 158 ``` 159 160 ## Network Ports 161 162 | Port | Protocol | Chain | Purpose | 163 |------|----------|-------|---------| 164 | 3030 | HTTP/REST | Alpha | RPC API (queries, transaction broadcast) | 165 | 4030 | HTTP/REST | Delta | RPC API (queries, transaction broadcast) | 166 | 4130 | TCP | Alpha | P2P gossip (block propagation, mempool) | 167 | 4131 | TCP | Delta | P2P gossip (block propagation, mempool) | 168 169 **Note**: Despite dual chains, ADNET uses a unified P2P layer internally. The separate ports exist for protocol compatibility and load balancing. 170 171 ## Operations 172 173 ### Starting the Node 174 175 ```bash 176 # Foreground (logs to stdout) 177 adnet start 178 179 # Background (systemd) 180 systemctl start adnet 181 182 # Docker 183 docker run -d -p 3030:3030 -p 4030:4030 -p 4130:4130 -p 4131:4131 \ 184 -v ~/.adnet:/root/.adnet \ 185 ghcr.io/alpha-delta-network/adnet:latest 186 ``` 187 188 ### Stopping the Node 189 190 ```bash 191 # Graceful shutdown 192 adnet stop 193 194 # Systemd 195 systemctl stop adnet 196 197 # Docker 198 docker stop adnet 199 ``` 200 201 ### Monitoring 202 203 ```bash 204 # Node status (both chains) 205 adnet status 206 207 # Chain-specific status 208 adnet status --chain alpha 209 adnet status --chain delta 210 211 # Peer count 212 adnet peers 213 214 # Block height 215 adnet info | grep height 216 217 # Validator metrics 218 adnet metrics --validator 219 ``` 220 221 ### Health Checks 222 223 ```bash 224 # Alpha RPC health 225 curl http://localhost:3030/health 226 227 # Delta RPC health 228 curl http://localhost:4030/health 229 230 # Both chains 231 adnet healthcheck 232 ``` 233 234 ## Binary Layout 235 236 ``` 237 adnet/ 238 ├── src/ 239 │ ├── main.rs # Entry point, CLI parsing 240 │ ├── node/ 241 │ │ ├── mod.rs # Unified orchestration 242 │ │ ├── alpha_runtime.rs # Alpha chain runtime 243 │ │ ├── delta_runtime.rs # Delta chain runtime 244 │ │ └── attestation.rs # Cross-chain IPC 245 │ ├── consensus/ 246 │ │ ├── mod.rs # ADNET BFT consensus 247 │ │ ├── alpha_consensus.rs # Alpha consensus rounds 248 │ │ └── delta_consensus.rs # Delta consensus rounds 249 │ ├── network/ 250 │ │ ├── p2p.rs # Unified P2P networking 251 │ │ └── gossip.rs # Transaction/block propagation 252 │ ├── storage/ 253 │ │ ├── ledger.rs # Dual-chain storage 254 │ │ └── rocksdb.rs # RocksDB backend 255 │ └── api/ 256 │ ├── alpha_api.rs # Alpha RPC (port 3030) 257 │ └── delta_api.rs # Delta RPC (port 4030) 258 ``` 259 260 ## Process Model 261 262 ADNET runs both chains as separate threads within a single process: 263 264 ``` 265 Main Process (adnet) 266 ├── Alpha Runtime Thread 267 │ ├── AlphaVM (credits.alpha execution) 268 │ ├── Consensus (BFT rounds, 15s blocks) 269 │ └── Storage (record-based UTXO) 270 ├── Delta Runtime Thread 271 │ ├── DeltaVM (Turing-complete execution) 272 │ ├── Consensus (BFT rounds, 3s blocks) 273 │ └── Storage (account-based state) 274 ├── Shared Infrastructure 275 │ ├── P2P Networking (unified peer discovery) 276 │ ├── Block Cache (shared memory) 277 │ └── IPC Channels (< 1μs attestation) 278 ``` 279 280 **Benefits of Single-Process Design:** 281 - **Zero bridge exploits** - no external validators, no wrapped tokens 282 - **Microsecond cross-chain** - internal function calls, not network RPC 283 - **Simplified operations** - one binary, one config, one deployment 284 - **Resource efficiency** - shared memory, unified networking 285 286 ## Development 287 288 ### Running Tests 289 290 ```bash 291 cargo test --all 292 ``` 293 294 ### Integration Tests 295 296 ```bash 297 # Start local testnet (both chains) 298 ./scripts/start-testnet.sh 299 300 # Run integration tests 301 cargo test --test integration -- --test-threads=1 302 ``` 303 304 ### Building Release Binary 305 306 ```bash 307 cargo build --release --bin adnet 308 strip target/release/adnet # Reduce binary size 309 ``` 310 311 ## Troubleshooting 312 313 ### Common Issues 314 315 **Port conflicts** 316 ``` 317 Error: Address already in use (port 3030) 318 ``` 319 Solution: Check for existing adnet instances (`pkill adnet`) or change ports in config.toml 320 321 **Insufficient peers** 322 ``` 323 Warn: Only 2 peers connected, need 4 for consensus 324 ``` 325 Solution: Check firewall rules, ensure ports 4130/4131 are open, verify network connectivity 326 327 **Chain sync stalled** 328 ``` 329 Error: Alpha chain height stuck at 1234 330 ``` 331 Solution: Check logs (`journalctl -u adnet -f`), verify peer connectivity, consider `adnet reset --chain alpha` 332 333 **Out of memory** 334 ``` 335 Error: Failed to allocate memory for proof generation 336 ``` 337 Solution: Increase RAM (provers need 64GB+), reduce concurrent proof generation, or run as client node 338 339 ## Related Projects 340 341 - [alphavm](../alphavm) - Privacy-preserving virtual machine 342 - [deltavm](../deltavm) - Turing-complete exchange VM 343 - [alphaos](../alphaos) - Alpha full node (legacy standalone) 344 - [deltaos](../deltaos) - Delta full node (legacy standalone) 345 - [acdc-core](../acdc-core) - Shared core library 346 347 **Note**: alphaos and deltaos are legacy standalone implementations. Current deployments use ADNET. 348 349 ## Contributing 350 351 The Alpha/Delta Protocol is an open-source project building monetary sovereignty through peer-to-peer cryptographic systems. Contributions are welcome from anyone aligned with the mission of privacy, freedom, and state-resistant money. 352 353 ### How to Contribute 354 355 1. **Read the specs** - Component specifications live in [alpha-delta-context/components](https://source.ac-dc.network/alpha-delta-network/alpha-delta-context/src/branch/main/components) 356 2. **Follow conventions** - See [CLAUDE.md](https://source.ac-dc.network/alpha-delta-context/src/branch/main/CLAUDE.md) for development guidelines 357 3. **Test thoroughly** - All code changes require passing tests 358 4. **Submit PRs** - Open pull requests against the `main` branch 359 360 ### Development Environment 361 362 See the [Installation](#installation) section for setting up your local environment. 363 364 ### Code of Conduct 365 366 We maintain a respectful, inclusive community focused on building excellent software. Harassment, discrimination, and bad-faith participation are not tolerated. 367 368 ### License 369 370 By contributing, you agree that your contributions will be licensed under Apache 2.0. 371 372 ### Community 373 374 - **Source code**: [source.ac-dc.network/alpha-delta-network](https://source.ac-dc.network/alpha-delta-network) 375 - **Documentation**: [alpha-delta-context](https://source.ac-dc.network/alpha-delta-network/alpha-delta-context) 376 - **Issues**: Open issues in the respective repository 377 378 ### Questions? 379 380 For technical questions, open an issue. For architectural discussions, see the component specifications in alpha-delta-context. 381 382 ## License 383 384 Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.