README.md
1 # Alpha/Delta Protocol Documentation 2 3 **Last Updated:** 2026-01-23 4 **Generated from:** Component specifications (cspec) 5 6 Welcome to the Alpha/Delta Protocol documentation. This directory contains comprehensive technical documentation auto-generated from component specifications. 7 8 --- 9 10 ## Quick Navigation 11 12 | Category | Description | Status | 13 |----------|-------------|--------| 14 | [API Reference](api/) | REST APIs, CLI interfaces, programmatic access | ✅ Complete | 15 | [Interfaces](interfaces/) | Stable component interfaces and contracts | ✅ Complete | 16 | [Operations](operations/) | Network upgrade governance, node operations | ✅ Complete | 17 | [Security](security/) | Threat models, attack vectors, security patterns | ✅ Complete | 18 | [CHANGELOG](CHANGELOG.md) | Version history and breaking changes | ✅ Current | 19 20 --- 21 22 ## API Reference 23 24 Comprehensive API documentation for all public-facing interfaces. 25 26 ### [AC/DC Installer API](api/acdc-api.md) 27 28 Command-line interface for node deployment and management. 29 30 **Key topics:** 31 - Installation and configuration 32 - Service management (start/stop/restart) 33 - Monitoring and health checks 34 - Prometheus metrics 35 - System requirements 36 37 **Audience:** Node operators, DevOps engineers 38 39 --- 40 41 ### [Node API](api/node-api.md) 42 43 REST API and interfaces for Alpha/Delta node software. 44 45 **Key topics:** 46 - REST endpoints (Alpha & Delta chains) 47 - P2P protocol specification 48 - Validator, prover, and client node types 49 - CLP (Continuous Liveness Proof) system 50 - Key management 51 - Deployment configuration 52 53 **Audience:** Developers, integrators, node operators 54 55 --- 56 57 ### [Infrastructure API](api/infra-api.md) 58 59 CI/CD, repository management, and build system interfaces. 60 61 **Key topics:** 62 - Repository structure and catalog 63 - CI/CD pipeline interface 64 - Build system (Cargo, justfiles) 65 - SBOM generation 66 - Automated workflow runner 67 - MCP tools for remediation 68 69 **Audience:** Contributors, DevOps engineers, CI maintainers 70 71 --- 72 73 ### [Alpha Chain API](api/alpha-api.md) 74 75 Privacy-focused chain with credits-only model. 76 77 **Key topics:** 78 - AlphaVM architecture and instruction set 79 - AX token (native credits) 80 - Governor-gated deployment model 81 - Transfer restrictions (private-only) 82 - Fee model and lock/unlock fees 83 - Privacy model and view keys 84 - Continuous Liveness Proof (CLP) 85 86 **Audience:** Developers, smart contract authors, integrators 87 88 --- 89 90 ### [Delta Chain API](api/delta-api.md) 91 92 High-throughput exchange chain with spot trading. 93 94 **Key topics:** 95 - DeltaVM architecture 96 - DX governance token 97 - sAX synthetic token 98 - Spot trading engine (CLOB) 99 - Order types and lifecycle 100 - Fee tiers and trading fees 101 - Perpetuals (planned) 102 - Treasury and dividends 103 104 **Audience:** Traders, DEX integrators, developers 105 106 --- 107 108 ### [Runtime API](api/runtime-api.md) 109 110 Unified binary, consensus, and cross-chain coordination. 111 112 **Key topics:** 113 - adnet unified binary 114 - BFT consensus (Narwhal-Bullshark) 115 - Parallel consensus (Alpha & Delta) 116 - Block times and finality 117 - Cross-chain attestation 118 - Genesis security model 119 - Program upgradability 120 121 **Audience:** Protocol developers, node operators 122 123 --- 124 125 ### [Token Economics API](api/tokens-api.md) 126 127 Token specifications, fee models, and economic parameters. 128 129 **Key topics:** 130 - AX, DX, sAX token properties 131 - Fee calculation functions 132 - Lock/unlock fee model 133 - Validator economic model 134 - Dividends and buyback 135 - Treasury operations 136 137 **Audience:** Economists, governance participants, integrators 138 139 --- 140 141 ## Component Interfaces 142 143 Stable contracts between system components. 144 145 ### [Interface Directory](interfaces/README.md) 146 147 Overview of all available interfaces with stability guarantees. 148 149 **Infrastructure Interfaces:** 150 - `interface_repo_structure` - Repository paths and organization 151 - `interface_ci_pipeline` - CI execution and status 152 - `interface_build_system` - Build configuration 153 - `interface_adl_compiler` - ADL compilation (spec only) 154 155 **AC/DC Interfaces:** 156 - `acdc_cli_interface` - Command-line operations 157 - `acdc_monitor_interface` - Metrics and alerting 158 159 **Node Interfaces:** 160 - `validator_node_interface` - Validator lifecycle 161 - `prover_node_interface` - Prover management 162 - `p2p_protocol_interface` - Peer-to-peer networking 163 - `rest_api_interface` - REST API specification 164 - `clp_system_interface` - Liveness proofs 165 166 **Runtime Interfaces:** 167 - `bft_consensus_interface` - BFT consensus protocol 168 - `cross_chain_attestation_interface` - AX ↔ sAX bridging 169 - `genesis_security_interface` - Transfer restrictions 170 171 **Token Interfaces:** 172 - `ax_token_interface` - Alpha native token 173 - `dx_token_interface` - Delta governance token 174 - `sax_token_interface` - Synthetic AX 175 - `fee_model_interface` - Fee calculation and distribution 176 177 **Delta Interfaces:** 178 - `spot_engine_interface` - CLOB trading 179 - `perpetuals_interface` - Futures trading (planned) 180 181 **Alpha Interfaces:** 182 - `alphavm_interface` - VM instruction whitelisting 183 - `governance_interface` - Governor voting 184 185 **Stability levels:** stable | unstable | deprecated 186 187 --- 188 189 ## Operations 190 191 Guides for running and maintaining Alpha/Delta infrastructure. 192 193 ### [Network Upgrade Governance](operations/network-upgrade-governance.md) 194 195 How governors vote on network upgrades. 196 197 **Topics:** 198 - Proposal creation and voting 199 - Genesis file distribution via BFT 200 - Automatic activation at target height 201 - Dual-chain coordination (Alpha → Delta) 202 203 **Audience:** Governors, validators 204 205 --- 206 207 ## Security 208 209 Threat models, attack vectors, and security best practices. 210 211 ### [Threat Actors](security/threat-actors.md) 212 213 Classification of potential adversaries. 214 215 **Categories:** 216 - External attackers 217 - Malicious validators 218 - Compromised users 219 - Insider threats 220 221 --- 222 223 ### [Attack Vectors](security/attack-vectors.md) 224 225 Known attack surfaces and mitigations. 226 227 **Areas covered:** 228 - Network attacks (DDoS, MitM, eclipse) 229 - Consensus attacks (51%, long-range, nothing-at-stake) 230 - Smart contract vulnerabilities 231 - Infrastructure attacks 232 233 --- 234 235 ### [Consensus Security](security/consensus-security.md) 236 237 Byzantine Fault Tolerance and consensus hardening. 238 239 **Topics:** 240 - BFT requirements (2/3+1 threshold) 241 - Slashing conditions 242 - Finality gadgets 243 244 --- 245 246 ### [Contract Patterns](security/contract-patterns.md) 247 248 Secure smart contract development patterns. 249 250 **Topics:** 251 - Checks-effects-interactions 252 - Safe math and bounded types 253 - Oracle manipulation defenses 254 255 --- 256 257 ### [Network Upgrade Security](security/network-upgrade-security.md) 258 259 Security considerations for governance-driven upgrades. 260 261 **Topics:** 262 - Governor consensus requirements 263 - Genesis verification 264 - Rollback protection 265 - Compile-time safeguards 266 267 --- 268 269 ## Changelog 270 271 ### [Version History](CHANGELOG.md) 272 273 Comprehensive changelog aggregated from all component specifications. 274 275 **Latest updates:** 276 - Alpha 1.1.0: Governor-gated deployment, lock/unlock fees 277 - Token 1.1.0: Lock/unlock fee model 278 - Infrastructure 1.5.0: Automated workflow runner 279 - Security 1.1.0: External dependencies audit 280 - Runtime 1.0.0: BFT consensus, cross-chain attestation 281 - Delta 1.0.0: Spot trading engine, DX/sAX tokens 282 - Frontend 1.0.0: Initial specification 283 284 **Upcoming:** 285 - Cross-chain attestation implementation (R005) 286 - Perpetuals trading (D005) 287 - ADL compiler implementation (I005) 288 - Frontend Phase 2 deliverables 289 290 --- 291 292 ## Frontend Development 293 294 ### [Frontend Local Development](frontend-local-dev.md) 295 296 Guide for setting up local development environment for frontend applications. 297 298 **Topics:** 299 - wallet-core setup 300 - acdc-wallet development 301 - acdc-governor console 302 - Design system integration 303 - i18n workflow 304 305 --- 306 307 ## Documentation Structure 308 309 ``` 310 docs/ 311 ├── README.md # This file 312 ├── CHANGELOG.md # Aggregated version history 313 ├── frontend-local-dev.md # Frontend dev guide 314 ├── api/ # API references 315 │ ├── acdc-api.md # AC/DC installer 316 │ ├── node-api.md # Node APIs 317 │ ├── infra-api.md # Infrastructure 318 │ ├── alpha-api.md # Alpha Chain 319 │ ├── delta-api.md # Delta Chain 320 │ ├── runtime-api.md # Runtime & consensus 321 │ └── tokens-api.md # Token economics 322 ├── interfaces/ # Component interfaces 323 │ └── README.md # Interface catalog 324 ├── operations/ # Operational guides 325 │ └── network-upgrade-governance.md 326 └── security/ # Security documentation 327 ├── threat-actors.md 328 ├── attack-vectors.md 329 ├── consensus-security.md 330 ├── contract-patterns.md 331 └── network-upgrade-security.md 332 ``` 333 334 --- 335 336 ## Documentation Generation 337 338 This documentation is automatically generated from component specifications: 339 340 **Source:** `components/*.cspec` 341 **Generator:** `sync_docs` workflow (daily at 04:00 UTC) 342 **Format:** Markdown (GitHub-flavored) 343 344 ### Source Files 345 346 | Component Spec | Documentation Output | 347 |----------------|---------------------| 348 | acdc.cspec | api/acdc-api.md | 349 | nodes.cspec | api/node-api.md | 350 | infra.cspec | api/infra-api.md | 351 | alpha/*.cspec | api/alpha-api.md | 352 | delta/*.cspec | api/delta-api.md | 353 | runtime/*.cspec | api/runtime-api.md | 354 | tokens/*.cspec | api/tokens-api.md | 355 | security.cspec | security/* | 356 | frontend.cspec | frontend-local-dev.md | 357 358 **Manual edits:** Do not edit generated .md files directly. Edit the source .cspec files and regenerate. 359 360 --- 361 362 ## Contributing 363 364 To update documentation: 365 366 1. Edit source `.cspec` file in `components/` 367 2. Run `just sync-docs` (or wait for nightly workflow) 368 3. Review generated `.md` files 369 4. Commit both `.cspec` and `.md` changes 370 371 ### Documentation Standards 372 373 - **API docs:** Include examples, input/output types, error cases 374 - **Interfaces:** Specify stability level, version, consumers 375 - **Operations:** Step-by-step guides with troubleshooting 376 - **Security:** Threat → Mitigation → Verification 377 378 --- 379 380 ## External Resources 381 382 - **Main site:** [ac-dc.network](https://ac-dc.network) 383 - **Documentation portal:** [docs.ac-dc.network](https://docs.ac-dc.network) 384 - **Block explorer:** [scanner.ac-dc.network](https://scanner.ac-dc.network) 385 - **Source code:** [source.ac-dc.network](https://source.ac-dc.network) 386 - **Radicle canonical:** [rad.ac-dc.network](https://rad.ac-dc.network) 387 388 --- 389 390 ## Versioning 391 392 Documentation follows component versioning: 393 394 - **Major:** Breaking API changes 395 - **Minor:** New features, backward-compatible 396 - **Patch:** Bug fixes, clarifications 397 398 Current versions (2026-01-23): 399 - Infrastructure: 1.5.0 400 - Security: 1.1.0 401 - AC/DC: 1.0.0 402 - Nodes: 1.0.0 403 - Frontend: 1.0.0 404 - Alpha: 1.1.0 405 - Delta: 1.0.0 406 - Runtime: 1.0.0 407 - Tokens: 1.1.0 408 409 --- 410 411 ## License 412 413 All documentation is licensed under the same terms as the Alpha/Delta Protocol source code. 414 415 --- 416 417 ## Support 418 419 For questions or issues: 420 421 - **Technical support:** [GitHub Issues](https://github.com/alpha-delta-network/alpha-delta-context/issues) 422 - **Security reports:** security@ac-dc.network 423 - **General inquiries:** info@ac-dc.network 424 425 --- 426 427 **Generated:** 2026-01-23 428 **Next update:** Daily via `sync_docs` workflow 429 **Source:** Synchronized from component `.cspec` files in `components/` directory