/ README.md
README.md
1 # ACDC Forge 2 3 > Governance through code review. 4 5 [](LICENSE) 6 [](https://typescriptlang.org) 7 [](https://python.org) 8 9 ## Why Governance Requires Code Review 10 11 Open-source projects face a dilemma: how to coordinate changes without central authority. Pull requests became the answer - structured code review enabling distributed collaboration. But who decides which PRs merge? In centralized systems: repository owners. In decentralized protocols: no one, or everyone. 12 13 ACDC Forge implements **on-chain governance for code changes**. Pull requests become proposals. Code reviewers become voters. Repository state becomes verifiable checkpoints stored on-chain. Merge decisions emerge from cryptographic consensus, not GitHub permissions. 14 15 Two governance layers mirror the dual-chain architecture: 16 - **Tech Governors** (Alpha chain): Economic stake holders vote on protocol upgrades 17 - **Code Governors** (Delta chain): Reputation-weighted developers vote on implementations 18 19 The result: code review as governance, pull requests as proposals, merges as on-chain events. No centralized gatekeepers. No permissioned repositories. Just transparent, verifiable coordination among equals. 20 21 ## What ACDC Forge Is 22 23 ACDC Forge is a source code management platform integrating Radicle distributed version control with on-chain voting mechanisms. It provides a web/mobile interface for browsing repositories, reviewing pull requests, and casting governance votes that execute on Alpha/Delta chains. 24 25 **Key Components:** 26 - **On-Chain Programs**: `forge.alpha` (Tech Governor voting), `forge.delta` (Code Governor voting) 27 - **Backend**: Python FastAPI serving as read cache for on-chain state 28 - **Frontend**: React/TypeScript web application (Vite + Tailwind) 29 - **Mobile**: React Native app (Expo) for iOS/Android 30 - **VCS**: Radicle integration for distributed git hosting 31 32 **Architecture**: 33 ``` 34 ┌─────────────────────────────────────────────────────────────┐ 35 │ ACDC Forge │ 36 │ │ 37 │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ 38 │ │ Web UI │ │ Mobile App │ │ Backend │ │ 39 │ │ React/Vite │ │ React Native│ │ FastAPI │ │ 40 │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ 41 │ │ │ │ │ 42 │ └──────────────────┼──────────────────┘ │ 43 │ │ │ 44 │ ┌────────▼────────┐ │ 45 │ │ Radicle Repos │ │ 46 │ │ (Git over P2P) │ │ 47 │ └────────┬────────┘ │ 48 │ │ │ 49 └────────────────────────────┼────────────────────────────────┘ 50 │ 51 ┌────────────────┼────────────────┐ 52 │ │ │ 53 ┌────▼────┐ ┌────▼────┐ ┌───▼────┐ 54 │ Alpha │ │ Delta │ │ ADNET │ 55 │ Chain │ │ Chain │ │ Node │ 56 └─────────┘ └─────────┘ └────────┘ 57 ``` 58 59 ## Prerequisites 60 61 - **Backend**: Python 3.12+, pip, Radicle CLI (`rad`) 62 - **Frontend**: Node.js 20+, npm/yarn 63 - **Mobile**: Node.js 20+, Expo CLI 64 - **Deployment**: Docker + Docker Compose 65 66 ## Installation 67 68 ### Clone Repository 69 70 ```bash 71 git clone https://source.ac-dc.network/alpha-delta-network/acdc-forge.git 72 cd acdc-forge 73 ``` 74 75 ### Backend Setup 76 77 ```bash 78 cd backend 79 80 # Install dependencies 81 pip install -r requirements.txt 82 83 # Initialize database cache 84 python -m db.init_cache 85 86 # Start FastAPI server 87 uvicorn main:app --reload --port 8000 88 ``` 89 90 **Environment Variables** (`.env`): 91 ```bash 92 ALPHA_RPC_URL=http://localhost:3030 93 DELTA_RPC_URL=http://localhost:4030 94 RADICLE_NODE=https://seed.radicle.xyz 95 DATABASE_URL=postgresql://forge:password@localhost/forge_cache 96 ``` 97 98 ### Frontend Setup 99 100 ```bash 101 cd frontend 102 103 # Install dependencies 104 npm install 105 106 # Start development server 107 npm run dev 108 ``` 109 110 **Open**: http://localhost:5173 111 112 ### Mobile Setup 113 114 ```bash 115 cd mobile 116 117 # Install dependencies 118 npm install 119 120 # Start Expo dev server 121 npx expo start 122 ``` 123 124 Scan QR code with Expo Go app (iOS/Android) to run. 125 126 ## Quick Start 127 128 ### Browse Repositories 129 130 ```bash 131 # Web UI 132 open http://localhost:5173 133 134 # Browse repositories 135 # View pull requests 136 # Check vote status 137 ``` 138 139 ### Cast Vote (as Governor) 140 141 **Tech Governor** (Alpha chain): 142 ```typescript 143 import { AlphaClient } from '@alpha-delta/sdk'; 144 145 const alpha = new AlphaClient('mainnet'); 146 147 // Vote on PR (requires Tech Governor registration) 148 await alpha.execute({ 149 program: 'forge.alpha', 150 function: 'vote_on_pr', 151 inputs: [prId, 'approve', 'Looks good to me'], 152 }); 153 ``` 154 155 **Code Governor** (Delta chain): 156 ```typescript 157 import { DeltaClient } from '@alpha-delta/sdk'; 158 159 const delta = new DeltaClient('mainnet'); 160 161 // Vote on PR (requires Code Governor registration + reputation) 162 await delta.execute({ 163 program: 'forge.delta', 164 function: 'vote_on_pr', 165 inputs: [prId, 'approve', weight], 166 }); 167 ``` 168 169 ### Register as Governor 170 171 **Tech Governor** (requires stake): 172 ```bash 173 # Via web UI: Profile → Register as Tech Governor 174 # Requires: 10,000 AX stake (locked during governance) 175 ``` 176 177 **Code Governor** (requires contributions): 178 ```bash 179 # Via web UI: Profile → Register as Code Governor 180 # Requires: 100+ reputation points from merged PRs 181 ``` 182 183 ## On-Chain Programs 184 185 ### forge.alpha (Tech Governor Voting) 186 187 **Purpose**: Economic stakeholders vote on protocol upgrades 188 **Voting Power**: 1 AX = 1 vote (stake-weighted) 189 **Quorum**: 50% of registered Tech Governors must vote 190 **Threshold**: 66% approval required for merge 191 192 **State**: 193 ```adl 194 program forge.alpha; 195 196 mapping tech_governors: address => TechGovernor; 197 mapping pr_registry: u64 => PullRequest; 198 mapping votes: (u64, address) => Vote; 199 ``` 200 201 ### forge.delta (Code Governor Voting) 202 203 **Purpose**: Developers vote on implementation PRs 204 **Voting Power**: Reputation-weighted (earned through contributions) 205 **Quorum**: 5+ Code Governors must vote 206 **Threshold**: 60% approval required for merge 207 208 **State**: 209 ```adl 210 program forge.delta; 211 212 mapping code_governors: address => CodeGovernor; 213 mapping contributors: address => ContributorStats; 214 mapping pr_registry: u64 => PullRequest; 215 mapping votes: (u64, address) => Vote; 216 ``` 217 218 ## Development 219 220 ### Running Tests 221 222 **Backend**: 223 ```bash 224 cd backend 225 pytest 226 ``` 227 228 **Frontend**: 229 ```bash 230 cd frontend 231 npm test 232 ``` 233 234 **On-Chain Programs**: 235 ```bash 236 cd programs/forge_alpha 237 adl test 238 239 cd ../forge_delta 240 adl test 241 ``` 242 243 ### Building for Production 244 245 **Backend (Docker)**: 246 ```bash 247 cd backend 248 docker build -t acdc-forge-backend . 249 docker run -p 8000:8000 acdc-forge-backend 250 ``` 251 252 **Frontend (Static Build)**: 253 ```bash 254 cd frontend 255 npm run build 256 # Output in dist/ 257 ``` 258 259 **Mobile (APK/IPA)**: 260 ```bash 261 cd mobile 262 263 # Android 264 eas build --platform android 265 266 # iOS 267 eas build --platform ios 268 ``` 269 270 ### Linting 271 272 ```bash 273 # Backend 274 cd backend && ruff check . 275 276 # Frontend 277 cd frontend && npm run lint 278 279 # Mobile 280 cd mobile && npm run lint 281 ``` 282 283 ## Project Structure 284 285 ``` 286 acdc-forge/ 287 ├── programs/ 288 │ ├── forge_alpha/ # Alpha chain voting program 289 │ │ ├── src/main.adl 290 │ │ └── tests/ 291 │ └── forge_delta/ # Delta chain voting program 292 │ ├── src/main.adl 293 │ └── tests/ 294 ├── backend/ 295 │ ├── main.py # FastAPI entry point 296 │ ├── api/ 297 │ │ ├── repos.py # Repository endpoints 298 │ │ ├── auth.py # Governor authentication 299 │ │ └── cache.py # Chain state cache 300 │ ├── services/ 301 │ │ ├── radicle.py # Radicle integration 302 │ │ └── chain_indexer.py # On-chain state sync 303 │ ├── db/ 304 │ │ └── cache_schema.sql # PostgreSQL schema 305 │ └── requirements.txt 306 ├── frontend/ 307 │ ├── src/ 308 │ │ ├── App.tsx # Main app component 309 │ │ ├── components/ # React components 310 │ │ ├── pages/ # Route pages 311 │ │ ├── services/ # API clients 312 │ │ └── store/ # State management 313 │ ├── package.json 314 │ └── vite.config.ts 315 ├── mobile/ 316 │ ├── app/ # Expo Router pages 317 │ ├── src/ 318 │ │ ├── components/ # React Native components 319 │ │ ├── services/ # API clients 320 │ │ └── store/ # State management 321 │ └── app.json 322 └── docker-compose.yml # Full stack deployment 323 ``` 324 325 ## API Reference 326 327 ### Backend Endpoints 328 329 **Repositories**: 330 ``` 331 GET /repos # List repositories 332 GET /repos/{id} # Repository details 333 GET /repos/{id}/pulls # List pull requests 334 GET /repos/{id}/pulls/{pr} # PR details 335 ``` 336 337 **Voting**: 338 ``` 339 GET /votes/{pr_id} # Vote status for PR 340 POST /votes/{pr_id}/cast # Cast vote (proxies to chain) 341 GET /votes/{pr_id}/results # Vote tally 342 ``` 343 344 **Governors**: 345 ``` 346 GET /governors/tech # List Tech Governors 347 GET /governors/code # List Code Governors 348 GET /governors/{address} # Governor profile 349 ``` 350 351 ### Chain RPC Queries 352 353 **Tech Governor Status**: 354 ```bash 355 curl -X POST http://localhost:3030/rpc \ 356 -d '{ 357 "jsonrpc": "2.0", 358 "method": "forge_alpha_get_governor", 359 "params": ["<address>"], 360 "id": 1 361 }' 362 ``` 363 364 **PR Vote Tally**: 365 ```bash 366 curl -X POST http://localhost:4030/rpc \ 367 -d '{ 368 "jsonrpc": "2.0", 369 "method": "forge_delta_get_pr_votes", 370 "params": [<pr_id>], 371 "id": 1 372 }' 373 ``` 374 375 ## Governance Workflows 376 377 ### 1. Create Pull Request 378 379 ```bash 380 # Clone Radicle repo 381 rad clone rad:z3...abc 382 383 # Create branch 384 git checkout -b feature/new-feature 385 386 # Commit changes 387 git commit -m "Add feature" 388 389 # Push to Radicle 390 git push origin feature/new-feature 391 392 # Create PR via web UI or CLI 393 rad pr create --target main --title "Add feature" 394 ``` 395 396 ### 2. Tech Governor Vote 397 398 **Prerequisites**: 399 - Registered as Tech Governor (10,000 AX stake) 400 - Pull request targets protocol upgrade 401 402 **Voting**: 403 ```typescript 404 // Via web UI or SDK 405 await alpha.execute({ 406 program: 'forge.alpha', 407 function: 'vote_on_pr', 408 inputs: [ 409 prId, // u64: PR identifier 410 'approve', // string: 'approve' | 'reject' | 'abstain' 411 'Rationale', // string: vote reasoning 412 ], 413 }); 414 ``` 415 416 ### 3. Code Governor Vote 417 418 **Prerequisites**: 419 - Registered as Code Governor (100+ reputation) 420 - Pull request targets implementation 421 422 **Voting**: 423 ```typescript 424 // Via web UI or SDK 425 await delta.execute({ 426 program: 'forge.delta', 427 function: 'vote_on_pr', 428 inputs: [ 429 prId, // u64: PR identifier 430 'approve', // string: vote decision 431 weight, // u64: voting power (reputation-derived) 432 ], 433 }); 434 ``` 435 436 ### 4. Automatic Merge 437 438 When quorum + threshold met: 439 - Backend monitors vote tallies via chain indexer 440 - Triggers merge on Radicle repository 441 - Creates checkpoint on Alpha/Delta chains 442 - Notifies voters via acdc-messenger 443 444 ## Security Considerations 445 446 **Stake Slashing** (Tech Governors): 447 - Voting for malicious PRs results in 50% stake slash 448 - Slashed funds distributed to opposing voters 449 - Requires 75% consensus to execute slash 450 451 **Reputation Decay** (Code Governors): 452 - Voting against consensus reduces reputation 453 - Consistent poor judgement → loss of voting rights 454 - Reputation recovers through successful contributions 455 456 **Sybil Resistance**: 457 - Tech Governors: Economic cost (10,000 AX stake) 458 - Code Governors: Work proof (merged contributions) 459 - Both: Address reputation tracked on-chain 460 461 ## Troubleshooting 462 463 ### Backend Not Syncing Chain State 464 465 **Problem**: Backend cache outdated compared to chain 466 467 **Solution**: 468 ```bash 469 # Force re-sync from genesis 470 cd backend 471 python -m db.rebuild_cache --from-genesis 472 ``` 473 474 ### Radicle Clone Fails 475 476 **Problem**: Cannot clone repository from Radicle network 477 478 **Solutions**: 479 - Check Radicle node connectivity: `rad node status` 480 - Verify seed nodes: `rad config --list` 481 - Fallback to Forgejo mirror: `git clone http://source.ac-dc.network/...` 482 483 ### Vote Transaction Fails 484 485 **Problem**: Vote submission rejected by chain 486 487 **Common Causes**: 488 - Not registered as Governor → Register first 489 - Insufficient stake (Tech Governors) → Add stake 490 - Low reputation (Code Governors) → Earn reputation 491 - PR already closed → Cannot vote on merged PRs 492 493 ## Contributing 494 495 Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. 496 497 ### Becoming a Code Governor 498 499 1. **Contribute code**: Submit PRs to Alpha/Delta repositories 500 2. **Build reputation**: Earn points for merged contributions 501 3. **Register**: Once 100+ reputation, register as Code Governor 502 4. **Vote**: Participate in governance on implementation PRs 503 504 Reputation formula: 505 ``` 506 reputation = (lines_merged * 0.1) + (prs_merged * 10) + (reviews * 2) 507 ``` 508 509 ## Related Projects 510 511 - [alpha-delta-context](../alpha-delta-context) - Protocol specifications 512 - [adl](../adl) - ADL programming language (for on-chain programs) 513 - [sdk](../sdk) - TypeScript SDK (for voting transactions) 514 - [acdc-messenger](../acdc-messenger) - Notification system (vote alerts) 515 516 ## License 517 518 Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details. 519 520 ## Attribution 521 522 Radicle integration builds on [Radicle](https://radicle.xyz) distributed VCS. Governance model inspired by on-chain coordination research.