delta-api.md
1 # Delta Chain API Reference 2 3 **Version:** 1.0.0 4 **Domain:** delta 5 **Stability:** high_change 6 **Last Updated:** 2026-01-23 7 **Source:** components/delta/*.component.cspec 8 9 ## Overview 10 11 Delta Chain is the high-throughput exchange chain in the Alpha/Delta dual-chain architecture. It provides spot trading, perpetuals, and governance with fast 2-3 second block times. 12 13 --- 14 15 ## Architecture 16 17 ### DeltaVM 18 19 **Component ID:** D002 20 **Base:** snarkvm (fork) 21 **State Model:** Account-based 22 **Capabilities:** Full VM 23 24 **Block Time:** 2-3 seconds 25 **Ports:** 26 - P2P: 4131 27 - API: 4030 28 29 ### Modules 30 31 | Module | Purpose | 32 |--------|---------| 33 | **exchange_engine** | Spot trading (CLOB) | 34 | **perpetuals** | Futures, funding, liquidation | 35 | **governance** | Voting and proposals | 36 | **treasury** | Buyback and dividends | 37 38 --- 39 40 ## Tokens 41 42 ### DX (Delta Governance) 43 44 **Component ID:** T002 45 46 | Property | Value | 47 |----------|-------| 48 | **Name** | DELTA (DX) | 49 | **Decimals** | 0 (whole units only) | 50 | **Supply** | 1 billion (fixed) | 51 | **Minting** | Genesis only | 52 | **Privacy** | ZK holdings | 53 | **State Model** | Shielded record | 54 | **Dividend** | Yes (from trading fees) | 55 | **Transferability** | Trading only (no direct transfers) | 56 57 **Note:** DX can only be traded on Delta chain, not transferred between users. Internal distributions (dividends, fees) use system-authorized transfers. 58 59 ### sAX (Synthetic Alpha) 60 61 **Component ID:** T003 62 63 | Property | Value | 64 |----------|-------| 65 | **Name** | Synthetic AX (sAX) | 66 | **Decimals** | 4 | 67 | **Backing** | 1:1 locked AX on Alpha | 68 | **Lifetime** | Ephemeral (exists only while locked) | 69 | **Chain** | Delta only | 70 | **Purpose** | Trading base asset | 71 72 ### Restricted Functions (System Only) 73 74 **Component ID:** R006 (Genesis Security) 75 76 DX users do NOT have `transfer_private` access. The following functions are system-only: 77 78 **Authorized Callers:** 79 - `dividends.delta` - DX dividend distribution 80 - `fees.delta` - Fee collection 81 - `spot_engine.delta` - Trading settlements 82 - `perpetuals.delta` - Futures settlements 83 - `governance.delta` - Governance operations 84 85 **User Accessible:** 86 - `join` - Combine records 87 - `split` - Split records 88 - `fee_private` - Pay fees privately 89 - `fee_public` - Pay fees publicly 90 91 --- 92 93 ## Spot Trading Engine 94 95 **Component ID:** D004 96 97 ### Order Book 98 99 **Type:** Central Limit Order Book (CLOB) 100 **Matching:** Price-time priority 101 102 ### Order Types 103 104 #### Limit Order 105 106 **Parameters:** 107 - `market: string` - Trading pair (e.g., "AX/DX") 108 - `side: "Buy" | "Sell"` - Order side 109 - `price: u64` - Limit price in microcredits 110 - `quantity: u64` - Order quantity in microcredits 111 112 **Example:** 113 ```json 114 { 115 "market": "AX-DX", 116 "side": "Buy", 117 "price": 1000000, 118 "quantity": 50000000 119 } 120 ``` 121 122 --- 123 124 #### Market Order 125 126 **Parameters:** 127 - `market: string` - Trading pair 128 - `side: "Buy" | "Sell"` - Order side 129 - `quantity: u64` - Order quantity 130 131 **Execution:** Immediate at best available price 132 133 --- 134 135 #### Stop-Limit Order 136 137 **Parameters:** 138 - `market: string` - Trading pair 139 - `side: "Buy" | "Sell"` - Order side 140 - `trigger_price: u64` - Activation price 141 - `limit_price: u64` - Execution price limit 142 - `quantity: u64` - Order quantity 143 144 --- 145 146 ### Order Lifecycle 147 148 ``` 149 submit → validate → match_or_book → fill_partial_or_full → settle 150 ``` 151 152 ### Settlement 153 154 - **Timing:** T+0 (instant) 155 - **Atomicity:** Trade and balance update are atomic 156 157 ### Markets 158 159 **Phase 1:** 160 - sAX/DX (base pair) 161 162 **Phase 2:** 163 - External pairs (BTC, ETH, etc.) 164 165 --- 166 167 ## Fee Model 168 169 **Component ID:** T004 170 171 ### Formula 172 173 ``` 174 fee = base_fee + (notional * tier_rate) 175 ``` 176 177 **Base Fee:** 10 microcredits 178 179 ### Trading Tiers 180 181 | Tier | Monthly Volume | Rate | 182 |------|---------------|------| 183 | Tier 1 | < 100k sAX | 0.10% | 184 | Tier 2 | 100k - 1M sAX | 0.05% | 185 | Tier 3 | 1M - 10M sAX | 0.025% | 186 | Tier 4 | > 10M sAX | 0.01% | 187 188 ### Fee Distribution 189 190 - **Validators:** 70% 191 - **Provers:** 30% 192 193 --- 194 195 ## REST API 196 197 **Base URL:** `http://localhost:4030/delta` 198 199 ### Trading Endpoints 200 201 #### `GET /orderbook/{market}` 202 203 Get orderbook for a trading pair. 204 205 **Parameters:** 206 - `market: string` - Trading pair (e.g., "AX-DX") 207 208 **Returns:** 209 ```json 210 { 211 "market": "AX-DX", 212 "bids": [ 213 {"price": 1000000, "quantity": 5000000, "orders": 3}, 214 {"price": 999000, "quantity": 3000000, "orders": 2} 215 ], 216 "asks": [ 217 {"price": 1001000, "quantity": 4000000, "orders": 2}, 218 {"price": 1002000, "quantity": 6000000, "orders": 4} 219 ], 220 "timestamp": "2026-01-23T10:30:00Z" 221 } 222 ``` 223 224 **Example:** 225 ```bash 226 curl http://localhost:4030/delta/orderbook/AX-DX 227 ``` 228 229 --- 230 231 #### `GET /positions/{address}` 232 233 Get trading positions for an address. 234 235 **Parameters:** 236 - `address: string` - Delta address 237 238 **Returns:** 239 ```json 240 { 241 "address": "delta1...", 242 "positions": [ 243 { 244 "market": "AX-DX", 245 "side": "long", 246 "quantity": 10000000, 247 "entry_price": 1000000, 248 "unrealized_pnl": 50000 249 } 250 ] 251 } 252 ``` 253 254 --- 255 256 #### `POST /order/submit` 257 258 Submit a trading order. 259 260 **Inputs:** 261 ```json 262 { 263 "market": "AX-DX", 264 "order_type": "limit", 265 "side": "buy", 266 "price": 1000000, 267 "quantity": 5000000, 268 "signature": "..." 269 } 270 ``` 271 272 **Returns:** 273 ```json 274 { 275 "order_id": "ord_abc123...", 276 "status": "pending", 277 "timestamp": "2026-01-23T10:30:00Z" 278 } 279 ``` 280 281 --- 282 283 ### Blockchain Endpoints 284 285 #### `GET /block/{height}` 286 287 Get block by height. 288 289 **Parameters:** 290 - `height: u64` - Block height 291 292 **Returns:** 293 - `block` - Block object with transactions and metadata 294 295 --- 296 297 #### `GET /transaction/{id}` 298 299 Get transaction by ID. 300 301 **Parameters:** 302 - `id: string` - Transaction identifier 303 304 **Returns:** 305 - `transaction` - Transaction object 306 307 --- 308 309 #### `POST /transaction/broadcast` 310 311 Broadcast a transaction to the network. 312 313 **Inputs:** 314 - `tx: transaction` - Signed transaction object 315 316 **Returns:** 317 - `tx_id: string` - Transaction identifier 318 319 --- 320 321 ### Governance Endpoints 322 323 #### `GET /governance/proposals` 324 325 Get all active governance proposals. 326 327 **Returns:** 328 - Array of proposal objects 329 330 **Example:** 331 ```bash 332 curl http://localhost:4030/delta/governance/proposals 333 ``` 334 335 --- 336 337 #### `GET /governance/proposal/{id}` 338 339 Get specific governance proposal details. 340 341 **Parameters:** 342 - `id: string` - Proposal identifier 343 344 **Returns:** 345 - Proposal object with voting status 346 347 --- 348 349 ## Perpetuals 350 351 **Component ID:** D005 352 353 ### Features 354 355 - Futures contracts 356 - Funding rates 357 - Liquidation engine 358 - Position management 359 360 **Status:** Planned (Phase 3) 361 362 --- 363 364 ## Treasury & Dividends 365 366 **Component ID:** T007, T008 367 368 ### Dividend Distribution 369 370 DX holders receive dividends from Delta trading fees. 371 372 **Frequency:** Periodic (TBD) 373 **Source:** Trading fee pool 374 375 ### Treasury Buyback 376 377 **Component ID:** T008 378 379 Treasury uses accumulated fees to buy back DX from the market. 380 381 **Purpose:** Support DX price and reduce circulating supply over time 382 383 --- 384 385 ## Oracles 386 387 **Component ID:** D006 388 389 ### Price Feeds 390 391 **Mechanism:** TWAP (Time-Weighted Average Price) 392 **Sources:** Multi-source validation 393 **Security:** Oracle manipulation resistance 394 395 **Status:** Planned (Phase 3) 396 397 --- 398 399 ## Hybrid Privacy 400 401 **Component ID:** D003 402 403 ### Privacy Model 404 405 - **Holdings:** ZK-shielded (balances hidden) 406 - **Orders:** Shielded order submission 407 - **Trades:** Trade execution observable (for market transparency) 408 409 **Rationale:** Balance privacy for users, transparency for market integrity 410 411 --- 412 413 ## Governance 414 415 **Component ID:** D008 416 417 ### Proposals 418 419 DX holders vote on: 420 - Protocol upgrades 421 - Economic parameters 422 - Treasury operations 423 - Emergency actions 424 425 **Voting Power:** Proportional to DX holdings 426 427 --- 428 429 ## See Also 430 431 - [Alpha Chain API](alpha-api.md) 432 - [Node API Reference](node-api.md) 433 - [Runtime API](runtime-api.md) 434 - [Token Economics](tokens-api.md) 435 436 --- 437 438 ## Changelog 439 440 ### Version 1.0.0 - 2026-01-07 441 442 **Added:** 443 - Initial Delta Chain specification 444 - DeltaVM architecture 445 - Spot trading engine 446 - DX and sAX tokens 447 - Fee model