alpha-api.md
1 # Alpha Chain API Reference 2 3 **Version:** 1.1.0 4 **Domain:** alpha 5 **Stability:** high_change 6 **Last Updated:** 2026-01-23 7 **Source:** components/alpha/*.component.cspec 8 9 ## Overview 10 11 Alpha Chain is the privacy-focused chain in the Alpha/Delta dual-chain architecture. It uses a credits-only model with governor-gated contract deployment for maximum security and simplicity. 12 13 --- 14 15 ## Architecture 16 17 ### AlphaVM 18 19 **Component ID:** A002 20 **Base:** snarkvm (fork) 21 **State Model:** Record-based (UTXO-like) + Sparse Merkle Tree 22 23 **Block Time:** 15 seconds 24 **Ports:** 25 - P2P: 4130 26 - API: 3030 27 28 ### Instruction Set 29 30 **Philosophy:** Minimal attack surface through instruction whitelisting 31 32 **Allowed Instructions:** 33 - **Arithmetic:** add, sub 34 - **Comparison:** gte, gt, lte, lt, is.eq, is.neq 35 - **Logic:** and, or, nor 36 - **Control:** ternary, async, cast 37 38 **Type System:** 39 - `address` - 256-bit ownership identifier 40 - `u64` - 64-bit unsigned (amounts, timestamps) 41 - `u32` - 32-bit unsigned (counters, indices) 42 - `u8` - 8-bit unsigned (flags) 43 - `boolean` - 1-bit (conditionals) 44 45 **Disabled Features:** 46 - Program deployment (user-initiated) 47 - Program imports 48 - Package management 49 - File operations 50 - Complex structs 51 - Arbitrary mappings 52 - ~60 unused Aleo instructions 53 54 --- 55 56 ## Token: AX (Alpha Credits) 57 58 **Component ID:** A001 59 60 ### Properties 61 62 | Property | Value | 63 |----------|-------| 64 | **Name** | ALPHA (AX) | 65 | **Decimals** | 4 | 66 | **Microcredits** | 10,000 per AX | 67 | **Supply** | Variable | 68 | **Minting** | Governor-only (90% approval) | 69 | **Privacy** | Full ZK (all transfers private) | 70 | **State Model** | Record-based UTXO | 71 72 ### Functions 73 74 #### `transfer_private` 75 76 Transfer AX between users privately. 77 78 **Inputs:** 79 - `recipient: address` - Recipient address 80 - `amount: u64` - Amount in microcredits 81 - `record: Record` - Sender's record 82 83 **Returns:** 84 - `tx_id: string` - Transaction identifier 85 86 **Privacy:** Fully shielded (sender, recipient, amount hidden) 87 88 **Example:** 89 ```aleo 90 transfer_private: 91 input r0 as credits.aleo/credits.record; 92 input r1 as address.private; 93 input r2 as u64.private; 94 call credits.aleo/transfer_private r0 r1 r2 into r3; 95 ``` 96 97 --- 98 99 #### `join` 100 101 Combine multiple records into one. 102 103 **Inputs:** 104 - `record1: Record` - First record 105 - `record2: Record` - Second record 106 107 **Returns:** 108 - `merged_record: Record` - Combined record 109 110 --- 111 112 #### `split` 113 114 Split a record into two smaller records. 115 116 **Inputs:** 117 - `record: Record` - Record to split 118 - `amount: u64` - Amount for first output record 119 120 **Returns:** 121 - `record1: Record` - First output record 122 - `record2: Record` - Second output record 123 124 --- 125 126 ### Restricted Functions (System Only) 127 128 **Component ID:** R006 (Genesis Security) 129 130 The following functions are **NOT** accessible to users directly. They can only be called by authorized system programs. 131 132 #### `transfer_public` 133 134 **Authorized Callers:** 135 - `rewards.alpha` - Validator/prover rewards distribution 136 - `fees.alpha` - Fee collection 137 - `governance.alpha` - Governance operations 138 - `clp.alpha` - Continuous liveness proof rewards 139 140 **Enforcement:** Caller check at function entry via `system_callers` mapping 141 142 **Security Rationale:** User privacy is non-negotiable; all user transfers must be private. 143 144 --- 145 146 #### `transfer_public_as_signer` 147 148 **Authorized Callers:** Same as `transfer_public` 149 150 --- 151 152 #### `transfer_private_to_public` 153 154 **Authorized Callers:** Same as `transfer_public` 155 156 --- 157 158 #### `transfer_public_to_private` 159 160 **Authorized Callers:** Same as `transfer_public` 161 162 --- 163 164 ## Contract Deployment Model 165 166 **Component ID:** A001 (Credits Only) 167 168 ### User Deployment 169 170 **Status:** Disabled 171 172 All user-initiated contract deployment is blocked at the VM level. 173 174 **Implementation:** 175 ```rust 176 // In verify.rs 177 Transaction::Deploy => Error::DeploymentDisabled 178 ``` 179 180 ### Governor-Gated Deployment 181 182 **Approval Threshold:** 90% 183 **Quorum:** 67% 184 **Timelock:** 7 days 185 186 **Process:** 187 1. Governor submits contract deployment proposal 188 2. Includes: contract source, audit report, security rationale 189 3. 90% of governors must approve 190 4. 7-day timelock begins 191 5. Deployment executed by consensus after timelock 192 193 ### Genesis Contracts 194 195 Deployed at genesis, available from block 0: 196 197 - `credits.alpha` - Native token operations 198 - `governance.alpha` - Governor voting 199 - `rewards.alpha` - Validator/prover rewards 200 - `fees.alpha` - Fee collection 201 - `clp.alpha` - Continuous liveness proofs 202 203 ### Deployable Contracts (Future) 204 205 **Examples:** 206 - `name_service.alpha` - If needed on Alpha (currently Delta) 207 - `recovery.alpha` - Social recovery if needed 208 209 **Requirement:** Governor proposal with 90% approval 210 211 --- 212 213 ## Fee Model 214 215 **Component ID:** T004 216 217 ### Formula 218 219 ``` 220 fee = base_fee + (proof_weight * prover_rate) 221 ``` 222 223 **Base Fee:** 100 microcredits (0.01 AX) 224 **Prover Rate:** 50 microcredits per weight unit 225 226 ### Example Costs 227 228 | Operation | Proof Weight | Fee (microcredits) | Fee (AX) | 229 |-----------|-------------|-------------------|----------| 230 | Transfer | 1.0 | 150 | 0.015 | 231 | Join | 0.8 | 140 | 0.014 | 232 | Split | 0.8 | 140 | 0.014 | 233 234 ### Lock/Unlock Fees (Cross-Chain) 235 236 **Lock Fee (AX → sAX):** 237 - **Multiplier:** 2x 238 - **Program:** `locked_pool.alpha` 239 - **Function:** `lock_for_sax` 240 - **Calculation:** `standard_execution_cost * 2` 241 242 **Unlock Fee (sAX → AX):** 243 - **Multiplier:** 0 (FREE) 244 - **Program:** `locked_pool.alpha` 245 - **Function:** `process_unlock` 246 - **Calculation:** 0 247 248 **Rationale:** Users unlocking AX earned on Delta shouldn't pay twice. Lock prepays unlock fee upfront. 249 250 ### Fee Distribution 251 252 - **Validators:** 70% 253 - **Provers:** 30% 254 - **Burn:** 0% 255 - **Treasury:** 0% 256 257 --- 258 259 ## Governance 260 261 **Component ID:** A007 262 263 ### Network Upgrade Proposals 264 265 Governors vote on: 266 - Protocol upgrades 267 - New contract deployments (90% threshold) 268 - Economic parameter changes 269 - Emergency actions 270 271 ### API Endpoints 272 273 See [Node API Reference](node-api.md#governance) for REST API details. 274 275 --- 276 277 ## Privacy Model 278 279 **Component ID:** A006 280 281 ### Record-Based Privacy 282 283 All user transactions use ZK records: 284 - **Sender:** Hidden 285 - **Recipient:** Hidden 286 - **Amount:** Hidden 287 288 ### View Keys 289 290 Users can generate view keys to: 291 - Decrypt their own records 292 - Share transaction history selectively 293 - Comply with audit requirements (optional) 294 295 **Type:** 296 ```rust 297 struct ViewKey { 298 algo: "bls12_377", 299 purpose: "decrypt_own_alpha_records" 300 } 301 ``` 302 303 --- 304 305 ## Security Guarantees 306 307 **Component ID:** A001, R006 308 309 ### Attack Surface Reduction 310 311 - **Instruction count:** 13 (vs 85+ in full Aleo) 312 - **Type count:** 5 (vs 20+ in full Aleo) 313 - **Codebase reduction:** 60% 314 315 ### Eliminated Attack Vectors 316 317 - Reentrancy attacks (no arbitrary user contracts) 318 - Logic bombs (no untrusted code) 319 - Arbitrary execution exploits 320 321 ### Formal Verification 322 323 **Feasibility:** High (due to simplified instruction set) 324 **Status:** Planned for pre-mainnet audit 325 326 --- 327 328 ## Continuous Liveness Proof (CLP) 329 330 **Component ID:** N004 331 332 ### Mechanism 333 334 - **Interval:** Per epoch 335 - **Attestation:** Signed liveness proof 336 - **Broadcast:** To all validators 337 338 ### Requirements 339 340 - **Uptime:** >= 95% 341 - **Consensus Participation:** >= 99% 342 343 ### Failure Consequences 344 345 - **During earn-in:** Extended period or removal 346 - **After full status:** Reduced rewards → eventual removal 347 348 --- 349 350 ## See Also 351 352 - [Delta Chain API](delta-api.md) 353 - [Node API Reference](node-api.md) 354 - [Runtime API](runtime-api.md) 355 - [Token Economics](tokens-api.md) 356 - [Security Specifications](../security/) 357 358 --- 359 360 ## Changelog 361 362 ### Version 1.1.0 - 2026-01-15 363 364 **Added:** 365 - Governor-gated deployment model (90% approval for new contracts) 366 - Lock/unlock fee model (2x lock, free unlock) 367 368 ### Version 1.0.0 - 2026-01-07 369 370 **Added:** 371 - Initial Alpha Chain specification 372 - Credits-only model 373 - AlphaVM architecture 374 - Privacy model