X002-acdc-forge.cspec
1 # X002: ACDC Forge - Source Code Management Platform 2 # Status: complete 3 # Priority: high 4 # Dependencies: A007 (Alpha Governance), D-GOV (Delta Governance), ENS (Name Service) 5 # Created: 2026-01-15 6 # Completed: 2026-01-16 7 8 ## Implementation Notes (2026-01-16) 9 10 ### Repository: acdc-forge 11 All 7 phases implemented as MVP. 12 13 ### Architecture Implemented 14 - **On-Chain**: forge.alpha + forge.delta ADL programs 15 - **Frontend**: React 18 + Vite + TypeScript + Tailwind + TanStack Query + Zustand 16 - **Backend**: FastAPI thin cache + Radicle proxy 17 - **Mobile**: React Native + Expo with Expo Router 18 19 ### Key Components Built 20 - programs/forge_alpha/src/main.adl - Tech Governor voting 21 - programs/forge_delta/src/main.adl - Code Governor voting 22 - frontend/src/components/{auth,repos,pr,voting,rollback,emergency,notifications,analytics} 23 - frontend/src/pages/{HomePage,ReposPage,RepoDetailPage,PRDetailPage,EmergencyPage,AnalyticsPage} 24 - backend/api/{auth,repos,patches,votes,cache}.py 25 - backend/services/{radicle,chain_indexer}.py 26 - mobile/app/(tabs)/{index,repos,votes,notifications,profile}.tsx 27 - mobile/app/{auth/connect,vote/[id],repo/[id],scan}.tsx 28 29 ### Commits 30 - 78b590b: feat(forge): implement emergency systems (Phase 6) 31 - 85b712c: feat(forge): implement notifications, analytics, and mobile app (Phase 7) 32 33 ## Overview 34 35 ACDC Forge is the unified source code management platform for the ACDC Network. 36 Built as a custom frontend on Radicle, it provides GitHub-style collaboration 37 with wallet-based authentication and dual-chain governance integration. 38 39 Single platform, dual permission model: Alpha Tech Governors control Alpha + Core 40 components, Delta Code Governors control Delta components. 41 42 ## Architecture 43 44 ``` 45 ┌─────────────────────────────────────────────────────────────────┐ 46 │ ACDC Forge │ 47 │ ┌─────────────────┐ ┌─────────────────┐ │ 48 │ │ Alpha Side │ │ Delta Side │ │ 49 │ │ │ │ │ │ 50 │ │ Tech Governors │ │ DX Stakers │ │ 51 │ │ (Gov nominated) │ │ (10k+ staked) │ │ 52 │ │ │ │ │ │ 53 │ │ Controls: │ │ Controls: │ │ 54 │ │ - alphavm │ │ - deltavm │ │ 55 │ │ - alphaos │ │ - deltaos │ │ 56 │ │ - acdc-core * │ │ - DEX modules │ │ 57 │ └────────┬────────┘ └────────┬────────┘ │ 58 │ │ │ │ 59 │ │ * Shared components need │ │ 60 │ │ both Alpha AND Delta │ │ 61 │ │ approval (parallel) │ │ 62 │ └───────────────┬────────────────┘ │ 63 │ ▼ │ 64 │ ┌─────────────────────┐ │ 65 │ │ Radicle Backend │ │ 66 │ │ (Distributed Git) │ │ 67 │ └─────────────────────┘ │ 68 └─────────────────────────────────────────────────────────────────┘ 69 │ 70 ▼ 71 ┌─────────────────────────────┐ 72 │ Governance Integration │ 73 │ │ 74 │ Alpha Gov ◄── Auto-proposal│ 75 │ (90% for implementation) │ 76 │ │ 77 │ Delta Gov ◄── Auto-proposal│ 78 │ (51% for implementation) │ 79 └─────────────────────────────┘ 80 ``` 81 82 ## Repository Structure 83 84 Separate repos per component: 85 - alphavm, alphaos (Alpha-exclusive) 86 - deltavm, deltaos (Delta-exclusive) 87 - acdc-core, sdk, adl (Shared - requires both chains) 88 - DEX modules (Delta-exclusive) 89 90 ## Identity & Authentication 91 92 ### Contributor Identity 93 - Pseudonymous via paycode/ENS 94 - One seed/paycode = one platform identity 95 - Required for reward payments 96 - No multi-wallet linking to single account 97 98 ### Alpha Tech Governors 99 - Nominated by Alpha Governors (mandatory, min 1 per Governor) 100 - Maximum 5 tech reps per Governor 101 - Identified as: "Governor-Name paycode" (e.g., "Canada xyz98273...") 102 - Registered in Governor Control Interface (GCI) 103 - Changes: instant (no cooldown) 104 105 ### Delta Code Governors 106 - Any DX holder with 10,000+ DX staked (genesis value, revisable down only) 107 - Must register on ACDC Forge platform 108 - Identified as: "Delta paycode" (e.g., "Delta abc9r9erwe...") 109 - Miss 3 votes = auto de-registered 110 111 ## Voting Model 112 113 ### Alpha Side 114 - 1 vote per nominating Governor (not per tech rep) 115 - Governor's GCI specifies vote mode: 116 - "First vote counts" (any tech rep can cast) 117 - "Multi-voter required" (e.g., 2/5 tech reps must agree) 118 - Threshold: 67% of ALL Governors must vote YES 119 - Abstaining = effectively NO 120 121 ### Delta Side 122 - Minimum 50 active registered voters required (decentralization) 123 - Threshold: 67% of ALL registered active voters must vote YES 124 - Abstaining = effectively NO 125 126 ### Shared Components (acdc-core, etc.) 127 | Stage | Alpha | Delta | Logic | 128 |------------------------|----------|----------|--------------------------| 129 | ACDC Forge (tech) | 67% | 67% | Parallel, both must pass | 130 | Governance (implement) | 90% | 51% | Parallel, both must pass | 131 132 Either side rejects = change rejected. 133 134 ## PR Lifecycle 135 136 ``` 137 1. SUBMIT 138 Contributor submits PR 139 Open for comments (indefinite) 140 │ 141 ▼ 142 2. CI CHECK 143 Full CI testing required 144 Auto-governed by both chains 145 No pass = cannot be sponsored 146 │ 147 ▼ 148 3. SPONSOR 149 Voting member "pushes to vote" 150 (Each member can only sponsor 1 open vote at a time) 151 (Only CI-passing PRs can be sponsored) 152 │ 153 ▼ 154 4. VOTING PERIOD 155 7 days to reach 67% 156 Comments allowed, edits NOT allowed 157 (Close and resubmit if changes needed) 158 │ 159 ▼ 160 5. OUTCOME 161 ├── PASS (67%+) ──► Auto-create governance proposal 162 │ - Executive summary (from sponsor) 163 │ - Link to Forge page 164 │ - Embedded core message 165 │ 166 └── FAIL (<67% or timeout) ──► Closed 167 ``` 168 169 ## Governance Integration 170 171 ### Auto-Proposal Generation 172 - Created automatically on successful Forge merge vote 173 - Contains: 174 - Executive summary (written by merge proposer) 175 - Link to Forge PR page (opens in external browser for security) 176 - Embedded core message in governance UI 177 178 ### Failed Governance Resubmission 179 - Must go back through Forge approval again 180 - 7 day cooldown before resubmission 181 - OR 90% Forge governors can approve early resubmission 182 183 ## Flagging System 184 185 ### PR Flags (before/during vote) 186 Tech Governors can flag PRs as: 187 - **Security Concern** - potential vulnerability 188 - **Political Concern** - governance/policy implications 189 - **Economic Concern** - tokenomics/incentive implications 190 191 ### Vote Flags 192 - "No" vote can also flag proposal as "bad behavior" 193 - Doesn't stop vote, but warns future voters 194 195 ## Noise Control 196 197 1. Each voting member can only sponsor 1 open vote at a time 198 2. Tech Governors can flag/block noisy contributors 199 3. Hook available for future rewards/punishment system 200 201 ## Rollback System 202 203 ### Design Principles 204 - Discrete upgrade rollbacks (not version rollbacks) 205 - Each PR/merge = discrete rollback unit 206 - Rollbacks for non-technical reasons by non-technical people 207 - UI shows only SAFE rollbacks (won't break dependent code) 208 - Full history in Radicle, filtered for safety in UI 209 210 ### Rollback Availability 211 - Tech Governance prunes rollback list as dependencies accumulate 212 - Contracts CANNOT be rolled back (immutable) 213 - Some upgrades can't roll back (state changes) 214 - Unsafe rollbacks not shown in UI 215 216 ### Rollback Process 217 1. Governor proposes rollback from governance UI 218 2. Reason/justification required 219 3. Discussion + voting simultaneous (emergency nature) 220 4. Thresholds: 221 - Single chain: 67% 222 - Joint (Alpha + Delta): 67% Alpha / 51% Delta 223 5. Timing: 224 - Contracts: next epoch boundary 225 - Platform: 3 days (becomes new validator rotation epoch) 226 227 ### Vote Behavior Flag 228 - "No" vote can flag as "bad behavior" (warns voters, doesn't stop vote) 229 230 ## Distributed Emergency Quorum (DEQ) Protocol 231 232 Fallback for critical deploys when ACDC Forge is unavailable. 233 234 ### Setup (at GCI registration) 235 - Each Governor generates offline emergency signing keypair 236 - Public key registered in GCI 237 - Private key stored offline (cold storage) 238 - Separate from regular governance keys 239 240 ### Activation Conditions 241 - ACDC Forge unavailable 24+ hours, AND 242 - Critical security patch or breaking bug requires immediate action 243 244 ### Process 245 1. Emergency patch proposed via out-of-band channel 246 (secure mailing list, Signal, phone tree) 247 2. Patch includes: code hash, description, justification, proposer identity 248 3. Each Governor independently: 249 - Verifies patch code matches hash 250 - Reviews justification 251 - Signs hash with emergency key (if approved) 252 4. Signatures collected (any mechanism) 253 5. 90% of Governor signatures = validators accept deploy 254 6. Deploy executes: 255 - Contracts: next epoch boundary 256 - Platform: 3 days 257 258 ### Post-Emergency 259 - All DEQ deploys flagged for mandatory Forge review 260 - Full audit trail published 261 - Any Governor can propose rollback via normal process 262 263 ### Implementation Requirements 264 - Emergency keypair generation in GCI 265 - Offline signing tool (CLI utility) 266 - Validator signature verification for DEQ deploys 267 - DEQ deploy flag in chain state 268 - Forge recovery audit workflow 269 270 ## ACDC Forge Platform Updates 271 272 The Forge platform itself requires updates. 273 274 ### Approval Process 275 1. Tech Governance (both chains) - 67% 276 2. Chain Governors (both) - 67% 277 3. Tech proposal must certify "no risk to platform" 278 279 ### Threshold Rationale 280 - 67% (not 90%) because it's operational tools, not chain code 281 282 ## Bootstrap Mode 283 284 For initial launch period: 285 286 - Launch team has veto power 287 - System accepts whatever voters available 288 - Relaxed requirements until critical mass reached 289 - Exits bootstrap when: 290 - All Governors have nominated tech reps 291 - 50+ Delta voters registered and active 292 293 ## Notifications 294 295 All notifications via: 296 1. **ENS Messenger** (privacy-preserving) 297 2. **Website display** 298 3. **Mobile app** (GitHub App style) - nice to have 299 300 ### Notification Types 301 - New PRs in watched repos 302 - PRs pushed to vote 303 - Governance proposals from merged code 304 - Emergency DEQ activation 305 - Vote outcomes 306 - Rollback proposals 307 308 ## Analytics Dashboard 309 310 Public dashboards with extensible metrics framework. 311 312 ### Initial Metrics 313 - Contributor statistics (PRs submitted, merged, rejected) 314 - Voter participation rates (Alpha and Delta) 315 - Average time from PR to deployment 316 - Rollback frequency 317 - CI pass/fail rates 318 319 ### Design 320 - Extensible architecture for future metrics 321 - Public transparency 322 - Historical trends 323 324 ## Component Ownership 325 326 | Component Type | Controlled By | Forge Approval | Gov Approval | 327 |----------------|---------------|----------------|--------------| 328 | Alpha-only | Alpha Tech | 67% Alpha | 90% Alpha | 329 | Delta-only | Delta Code | 67% Delta | 51% Delta | 330 | Shared/Core | Both | 67% both | 90% A / 51% D| 331 | Forge Platform | Both | 67% both | 67% both | 332 333 ## Implementation Phases 334 335 ### Phase 1: Core Platform 336 - Radicle frontend with wallet auth 337 - Repository browsing and PR submission 338 - Basic CI integration 339 - Alpha Tech Governor registration via GCI 340 341 ### Phase 2: Voting System 342 - PR sponsorship and voting 343 - 7-day vote lifecycle 344 - Flag system (Security, Political, Economic) 345 - Vote tallying with proper thresholds 346 347 ### Phase 3: Governance Integration 348 - Auto-proposal generation 349 - Executive summary workflow 350 - External link security model 351 - Resubmission cooldown logic 352 353 ### Phase 4: Delta Integration 354 - DX staking verification 355 - Delta Code Governor registration 356 - 50-voter minimum enforcement 357 - Parallel voting for shared components 358 359 ### Phase 5: Rollback System 360 - Safe rollback calculation 361 - Rollback UI in governance 362 - Dependency tracking 363 - Epoch boundary scheduling 364 365 ### Phase 6: Emergency Systems 366 - DEQ keypair generation 367 - Offline signing tool 368 - Validator DEQ verification 369 - Post-emergency audit workflow 370 371 ### Phase 7: Polish 372 - ENS Messenger notifications 373 - Analytics dashboard 374 - Mobile app 375 - Bootstrap mode exit criteria 376 377 ## Security Considerations 378 379 1. **Wallet-based auth** - No passwords, cryptographic identity 380 2. **External browser links** - Governance app isolation 381 3. **CI gating** - No vote without passing tests 382 4. **Flag system** - Surface concerns early 383 5. **High thresholds** - 67%/90% prevents minority capture 384 6. **DEQ 90% threshold** - Emergency deploys require near-consensus 385 7. **Rollback safety** - Only show safe rollbacks in UI 386 8. **Audit trails** - Full history in Radicle 387 388 ## Related Components 389 390 - A007: Alpha Governance (receives proposals from Forge) 391 - D-GOV: Delta Governance (receives proposals from Forge) 392 - ENS: Name Service (identity, notifications) 393 - GCI: Governor Control Interface (tech rep registration) 394 - Radicle: Underlying distributed git infrastructure