1  # ADNet Rewards & Fees System
  2  
  3  Complete documentation for the ADNet rewards and fees infrastructure implementing T004 Fee Model.
  4  
  5  ## Overview
  6  
  7  The ADNet rewards system implements a comprehensive infrastructure for tracking, distributing, and claiming rewards for validators and provers across both ALPHA and DELTA chains. The system ensures fair compensation based on actual work performed while maintaining strict pool isolation between chains.
  8  
  9  ## Architecture
 10  
 11  ### Core Components
 12  
 13  ```
 14  ┌─────────────────────────────────────────────────────────────┐
 15  │                    ADNet Node Process                        │
 16  ├─────────────────────────────────────────────────────────────┤
 17  │                                                               │
 18  │  ┌─────────────────┐          ┌──────────────────┐         │
 19  │  │ ALPHA Runtime   │          │ DELTA Runtime    │         │
 20  │  │                 │          │                  │         │
 21  │  │ ConsensusAdapter│          │ ConsensusAdapter │         │
 22  │  └────────┬────────┘          └────────┬─────────┘         │
 23  │           │                             │                    │
 24  │           └──────────┬──────────────────┘                   │
 25  │                      ▼                                       │
 26  │           ┌────────────────────┐                            │
 27  │           │ RewardsIntegration │                            │
 28  │           └─────────┬──────────┘                            │
 29  │                     ▼                                        │
 30  │           ┌────────────────────┐                            │
 31  │           │  RewardsTracker    │                            │
 32  │           │  (Epoch-based)     │                            │
 33  │           └─────────┬──────────┘                            │
 34  │                     ▼                                        │
 35  │    ┌────────────────┴────────────────┐                     │
 36  │    ▼                                  ▼                     │
 37  │ ┌─────────────────┐         ┌──────────────────┐          │
 38  │ │ WorkTracker     │         │ RewardDistributor│          │
 39  │ │ (Per-chain)     │         │ (23/77 split)    │          │
 40  │ └─────────────────┘         └──────────────────┘          │
 41  │                                                              │
 42  │  ┌──────────────────────────────────────────────┐          │
 43  │  │           REST API (Port 3000)               │          │
 44  │  │  /api/v1/rewards/{balance,claim,summary,...} │          │
 45  │  └──────────────────────────────────────────────┘          │
 46  └──────────────────────────────────────────────────────────────┘
 47  ```
 48  
 49  ### Module Structure
 50  
 51  | Crate | Purpose |
 52  |-------|---------|
 53  | `adnet-rewards` | Core rewards logic (work tracking, distribution, claiming) |
 54  | `adnet-runtime` | Runtime integration with consensus hooks |
 55  | `adnet` | Orchestrator, API server, and CLI |
 56  | `adnet-prover` | Proof generation tracking |
 57  
 58  ## T004 Fee Model
 59  
 60  ### Fee Split
 61  
 62  **Infrastructure rewards: 23% to validators, 77% to provers**
 63  
 64  | Role | ALPHA Share | DELTA Share | Justification |
 65  |------|-------------|-------------|---------------|
 66  | **Validators** | 23% | 23% | Block production, consensus, finality |
 67  | **Provers** | 77% | 77% | Heavy cryptographic work, circuit proving |
 68  
 69  ### Pool Isolation
 70  
 71  - **ALPHA fees** → ALPHA validator/prover pools only
 72  - **DELTA fees** → DELTA validator/prover pools only
 73  - **No cross-subsidization** between chains
 74  
 75  ### Cost-Weighted Distribution
 76  
 77  Prover rewards are distributed based on circuit complexity:
 78  
 79  ```rust
 80  reward_weight = base_weight * circuit_cost_multiplier
 81  
 82  Examples:
 83  - Simple transaction:     1.0x weight
 84  - Governance proposal:    3.5x weight
 85  - Bridge operation:       5.2x weight
 86  - ZK seed voting (50):   45.8x weight
 87  ```
 88  
 89  ## Work Tracking
 90  
 91  ### Validator Work
 92  
 93  ```rust
 94  // Automatically recorded when blocks finalize
 95  rewards_integration.on_alpha_block_finalized(
 96      height: u64,
 97      validator: String,  // hex-encoded address
 98      fees: u64,          // total fees in block
 99  );
100  ```
101  
102  ### Prover Work
103  
104  ```rust
105  // Automatically recorded when proofs generate
106  prover_pools.record_proof_with_circuit(
107      prover: String,
108      time: Duration,
109      is_alpha: bool,
110      circuit_id: ChainCircuitId,
111  );
112  ```
113  
114  ## Distribution
115  
116  ### Epoch-Based System
117  
118  - **Epoch duration**: 1 hour (configurable)
119  - **Automatic advancement**: Background task in orchestrator
120  - **Distribution trigger**: On epoch advancement
121  
122  ### Distribution Flow
123  
124  ```
125  1. Epoch N ends
126     ↓
127  2. Collect all fees from epoch N
128     ↓
129  3. Split: 23% validators, 77% provers
130     ↓
131  4. Distribute validator pool by block count
132     ↓
133  5. Distribute prover pool by cost-weighted work
134     ↓
135  6. Record rewards for claiming
136     ↓
137  7. Advance to epoch N+1
138  ```
139  
140  ### Example Distribution
141  
142  **Input**:
143  - Total ALPHA fees: 1,000,000 microcredits
144  - Validators: `val1` (10 blocks), `val2` (5 blocks)
145  - Provers: `prover1` (100 work units), `prover2` (50 work units)
146  
147  **Output**:
148  ```
149  Validator pool: 230,000 (23%)
150  ├─ val1: 153,333 (10/15 blocks)
151  └─ val2:  76,667 ( 5/15 blocks)
152  
153  Prover pool: 770,000 (77%)
154  ├─ prover1: 513,333 (100/150 work)
155  └─ prover2: 256,667 ( 50/150 work)
156  ```
157  
158  ## Claiming
159  
160  ### Atomic Cross-Chain Claims
161  
162  Claims are **atomic** across ALPHA and DELTA:
163  
164  ```rust
165  let request = ClaimRequest::claim_all(
166      participant: "validator1".to_string(),
167      epoch: 42,
168  );
169  
170  let receipt = tracker.claim_rewards(request)?;
171  // Receives both AX and sAX in single transaction
172  ```
173  
174  ### Claim Windows
175  
176  - **Window**: 90 days (configurable)
177  - **Expiry**: After 90 days, rewards return to pool
178  - **Pruning**: Automatic cleanup of expired claims
179  
180  ### Claim Receipt
181  
182  ```rust
183  ClaimReceipt {
184      participant: "validator1",
185      epoch: 42,
186      alpha_claimed: 153_333,     // microcredits
187      delta_claimed: 89_440,      // microcredits
188      claimed_at_epoch: 43,       // when claimed
189  }
190  ```
191  
192  ## CLI Usage
193  
194  ### Prerequisites
195  
196  Start your node with API enabled:
197  ```bash
198  adnet start --api --api-port 3000
199  ```
200  
201  ### Query Balance
202  
203  ```bash
204  # Check unclaimed rewards
205  adnet rewards balance validator1
206  
207  # Output:
208  # Rewards Balance for validator1:
209  # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
210  #   ALPHA:  153.3333 AX
211  #   DELTA:   89.4400 sAX
212  # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
213  ```
214  
215  ### Claim Rewards
216  
217  ```bash
218  # Claim all rewards for an epoch
219  adnet rewards claim validator1 42
220  
221  # Output:
222  # ✓ Rewards claimed successfully!
223  # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
224  #   Participant:     validator1
225  #   Epoch:           42
226  #   ALPHA claimed:   153.3333 AX
227  #   DELTA claimed:   89.4400 sAX
228  #   Claimed at epoch: 43
229  # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
230  ```
231  
232  ### Query Epoch Summary
233  
234  ```bash
235  # View distribution summary for an epoch
236  adnet rewards summary 42
237  
238  # Output:
239  # Epoch 42 Distribution Summary:
240  # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
241  #
242  #   Validators:
243  #     Count:        2
244  #     ALPHA total:  230.0000 AX
245  #     DELTA total:  134.0000 sAX
246  #
247  #   Provers:
248  #     Count:        3
249  #     ALPHA total:  770.0000 AX
250  #     DELTA total:  449.0000 sAX
251  # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
252  ```
253  
254  ### View Claim History
255  
256  ```bash
257  # View all past claims
258  adnet rewards history validator1
259  
260  # Output:
261  # Claim History for validator1:
262  # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
263  #
264  #   Epoch 40:
265  #     ALPHA:   150.2500 AX
266  #     DELTA:   87.1200 sAX
267  #     Claimed at epoch: 41
268  #
269  #   Epoch 42:
270  #     ALPHA:   153.3333 AX
271  #     DELTA:   89.4400 sAX
272  #     Claimed at epoch: 43
273  #
274  #   Total claims: 2
275  # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
276  ```
277  
278  ### Check Current Epoch
279  
280  ```bash
281  # View current epoch number
282  adnet rewards epoch
283  
284  # Output:
285  # Current Epoch: 43
286  ```
287  
288  ### Custom API Endpoint
289  
290  ```bash
291  # Override default API URL
292  export ADNET_API_URL=http://192.168.1.100:3000
293  adnet rewards balance validator1
294  ```
295  
296  ## REST API
297  
298  ### Endpoints
299  
300  | Method | Path | Description |
301  |--------|------|-------------|
302  | GET | `/api/v1/rewards/balance/:participant` | Query unclaimed balance |
303  | POST | `/api/v1/rewards/claim` | Claim rewards for epoch |
304  | GET | `/api/v1/rewards/summary/:epoch` | Epoch distribution summary |
305  | GET | `/api/v1/rewards/history/:participant` | Claim history |
306  | GET | `/api/v1/rewards/epoch` | Current epoch number |
307  | POST | `/api/v1/rewards/advance-epoch` | Advance to next epoch (admin) |
308  
309  ### Examples
310  
311  #### Query Balance
312  
313  ```bash
314  curl http://localhost:3000/api/v1/rewards/balance/validator1
315  ```
316  
317  Response:
318  ```json
319  {
320    "participant": "validator1",
321    "alpha_microcredits": 153333,
322    "delta_microcredits": 89440
323  }
324  ```
325  
326  #### Claim Rewards
327  
328  ```bash
329  curl -X POST http://localhost:3000/api/v1/rewards/claim \
330    -H 'Content-Type: application/json' \
331    -d '{"participant":"validator1","epoch":42}'
332  ```
333  
334  Response:
335  ```json
336  {
337    "participant": "validator1",
338    "epoch": 42,
339    "alpha_claimed": 153333,
340    "delta_claimed": 89440,
341    "claimed_at_epoch": 43
342  }
343  ```
344  
345  #### Epoch Summary
346  
347  ```bash
348  curl http://localhost:3000/api/v1/rewards/summary/42
349  ```
350  
351  Response:
352  ```json
353  {
354    "epoch": 42,
355    "validator_count": 2,
356    "prover_count": 3,
357    "total_alpha_distributed": 1000000,
358    "total_delta_distributed": 583000,
359    "validator_rewards": {
360      "validator1": {
361        "alpha_microcredits": 153333,
362        "delta_microcredits": 89440
363      }
364    },
365    "prover_rewards": {
366      "prover1": {
367        "alpha_microcredits": 513333,
368        "delta_microcredits": 299195
369      }
370    }
371  }
372  ```
373  
374  ## Integration Guide
375  
376  ### For Validators
377  
378  1. **Start node with API**:
379     ```bash
380     adnet start --api --node-type validator
381     ```
382  
383  2. **Monitor rewards**:
384     ```bash
385     # Check balance periodically
386     adnet rewards balance $(adnet alpha account address)
387     ```
388  
389  3. **Claim periodically**:
390     ```bash
391     # Claim when balance is substantial
392     adnet rewards claim $(adnet alpha account address) $EPOCH
393     ```
394  
395  ### For Provers
396  
397  1. **Ensure proof tracking is enabled** (automatic in adnet)
398  
399  2. **Record proofs via ProverPools**:
400     ```rust
401     prover_pools.record_proof_with_circuit(
402         prover_id,
403         duration,
404         is_alpha,
405         circuit_id,
406     );
407     ```
408  
409  3. **Query rewards same as validators**:
410     ```bash
411     adnet rewards balance prover1
412     ```
413  
414  ### For Operators
415  
416  1. **Monitor epoch advancement**:
417     ```bash
418     # Check current epoch
419     adnet rewards epoch
420     ```
421  
422  2. **Manual epoch advance** (if needed):
423     ```bash
424     curl -X POST http://localhost:3000/api/v1/rewards/advance-epoch
425     ```
426  
427  3. **View system-wide summary**:
428     ```bash
429     adnet rewards summary $CURRENT_EPOCH
430     ```
431  
432  ## Testing
433  
434  ### Unit Tests
435  
436  ```bash
437  # Core rewards logic
438  cargo test -p adnet-rewards  # 34 tests
439  
440  # Runtime integration
441  cargo test -p adnet-runtime  # 55 tests
442  ```
443  
444  ### E2E Tests
445  
446  ```bash
447  # Comprehensive reward cycles
448  cargo test -p adnet-e2e --test rewards_e2e  # 7 tests
449  ```
450  
451  ### Test Coverage
452  
453  - ✅ Full reward cycle (record → distribute → claim)
454  - ✅ Cross-chain atomic claims
455  - ✅ Epoch advancement
456  - ✅ Partial claims
457  - ✅ Zero rewards edge cases
458  - ✅ Pool isolation verification
459  - ✅ Cost-weighted distribution
460  - ✅ Claim window expiry
461  
462  ## Configuration
463  
464  ### Epoch Duration
465  
466  Default: 3600 seconds (1 hour)
467  
468  Modify in `NodeOrchestrator::start()`:
469  ```rust
470  let epoch_interval = Duration::from_secs(3600);
471  ```
472  
473  ### Claim Window
474  
475  Default: 90 days
476  
477  Modify in `adnet-rewards/src/claiming.rs`:
478  ```rust
479  const CLAIM_WINDOW_EPOCHS: u64 = 2160; // 90 days at 1hr/epoch
480  ```
481  
482  ### Fee Split
483  
484  Default: 23% validators, 77% provers
485  
486  Modify in `adnet-rewards/src/distribution.rs`:
487  ```rust
488  pub const VALIDATOR_SHARE_BPS: u16 = 2300;  // 23%
489  pub const PROVER_SHARE_BPS: u16 = 7700;     // 77%
490  ```
491  
492  ## Troubleshooting
493  
494  ### "Failed to connect to node API"
495  
496  **Cause**: Node not running or API not enabled.
497  
498  **Solution**:
499  ```bash
500  adnet start --api --api-port 3000
501  ```
502  
503  ### "No rewards found"
504  
505  **Cause**: No work recorded in the specified epoch.
506  
507  **Solution**: Verify block production or proof generation is occurring.
508  
509  ### "Insufficient balance"
510  
511  **Cause**: Trying to claim more than available.
512  
513  **Solution**: Use `claim_all()` request or query balance first.
514  
515  ### Epoch not advancing
516  
517  **Cause**: Orchestrator epoch task not running.
518  
519  **Solution**: Check logs for:
520  ```
521  INFO adnet::orchestrator: Starting epoch advancement task (interval: 1h)
522  ```
523  
524  ## Performance Considerations
525  
526  ### Memory Usage
527  
528  - Work tracking: ~100 bytes per participant per epoch
529  - Claim receipts: ~80 bytes per claim
530  - Expected: <1 MB for 1000 participants across 100 epochs
531  
532  ### Computation
533  
534  - Distribution: O(n) where n = number of participants
535  - Claiming: O(1) with hash map lookups
536  - Pruning: O(e) where e = expired epochs
537  
538  ### Database
539  
540  Currently **in-memory**. For persistence:
541  
542  1. Add `sled` or `rocksdb` backend
543  2. Serialize `RewardsTracker` state
544  3. Load on node restart
545  
546  ## Future Enhancements
547  
548  ### Planned
549  
550  - [ ] Persistent storage backend
551  - [ ] Rewards pool rebalancing
552  - [ ] Dynamic fee split governance
553  - [ ] Prover performance bonuses
554  - [ ] Slashing integration
555  
556  ### Under Consideration
557  
558  - [ ] Delegation support
559  - [ ] Staking rewards
560  - [ ] Multi-epoch claim batching
561  - [ ] Reward streaming
562  
563  ## References
564  
565  - [T004 Fee Model Specification](../components/T004-fee-model.cspec)
566  - [Staged Startup Documentation](./STAGED_STARTUP.md)
567  - [API Server Implementation](../crates/adnet/src/api/)
568  - [Rewards Crate Source](../crates/adnet-rewards/src/)
569  
570  ---
571  
572  **Version**: 1.0.0
573  **Last Updated**: 2026-02-13
574  **Status**: Production Ready ✅