tokenomics: scale reward units to atom precision.

Use 1 KAT = 1_000_000_000 atoms in runtime/reward defaults so producer and waiting-pool payouts do not floor to zero under deterministic integer splits. Align RPC/doc surfaces and the warmup reward test with the updated unit scale.

Made-with: Cursor

Author: TheNewAutonomy

crates/catalyst-cli/src/node.rs

@@ -210,7 +210,8 @@ const META_PROTOCOL_NETWORK_ID: &str = "protocol:network_id";
 const META_PROTOCOL_GENESIS_HASH: &str = "protocol:genesis_hash";
 
 // Tokenomics v1 constants (aligned with docs/tokenomics-spec.md).
-const TOKENOMICS_BLOCK_REWARD_ATOMS: u64 = 1;
+// 1 KAT = 1_000_000_000 atoms so reward splits don't floor to zero.
+const TOKENOMICS_BLOCK_REWARD_ATOMS: u64 = 1_000_000_000;
 const TOKENOMICS_FEE_BURN_BPS: u64 = 7_000;
 const TOKENOMICS_FEE_TO_REWARD_POOL_BPS: u64 = 3_000;
 const TOKENOMICS_FEE_TO_TREASURY_BPS: u64 = 0;
@@ -318,7 +319,15 @@ mod tokenomics_tests {
         distribute_waiting_pool_rewards_and_fee_credits(&store, &mk_lsu(at)).await;
         let bal_at = get_fee_credit_balance_u64(&store, &worker).await;
         assert_eq!(bal_at, TOKENOMICS_FEE_CREDITS_ACCRUAL_ATOMS_PER_DAY);
-        assert_eq!(get_balance_i64(&store, &worker).await, bal0.saturating_add(1));
+        let reward_from_fees = 10u64.saturating_mul(TOKENOMICS_FEE_TO_REWARD_POOL_BPS) / 10_000;
+        let expected_waiting_reward = TOKENOMICS_BLOCK_REWARD_ATOMS
+            .saturating_add(reward_from_fees)
+            .saturating_mul(TOKENOMICS_WAITING_POOL_REWARD_BPS)
+            / 10_000;
+        assert_eq!(
+            get_balance_i64(&store, &worker).await,
+            bal0.saturating_add(expected_waiting_reward as i64)
+        );
     }
 
     #[tokio::test]

crates/catalyst-consensus/src/phases.rs

@@ -1112,7 +1112,8 @@ pub struct RewardConfig {
 impl Default for RewardConfig {
     fn default() -> Self {
         Self {
-            block_reward: 1,
+            // 1 KAT in atom units (1 KAT = 1_000_000_000 atoms).
+            block_reward: 1_000_000_000,
             fee_to_reward_pool_bps: 3000,
             producer_set_reward_bps: 7000,
             waiting_pool_reward_bps: 3000,

crates/catalyst-rpc/src/lib.rs

@@ -22,7 +22,8 @@ const META_PROTOCOL_CHAIN_ID: &str = "protocol:chain_id";
 const META_PROTOCOL_NETWORK_ID: &str = "protocol:network_id";
 const META_PROTOCOL_GENESIS_HASH: &str = "protocol:genesis_hash";
 const META_SNAPSHOT_LATEST: &str = "snapshot:latest";
-const TOKENOMICS_BLOCK_REWARD_ATOMS: u64 = 1;
+// 1 KAT = 1_000_000_000 atoms.
+const TOKENOMICS_BLOCK_REWARD_ATOMS: u64 = 1_000_000_000;
 const TOKENOMICS_FEE_BURN_BPS: u64 = 7_000;
 const TOKENOMICS_FEE_TO_REWARD_POOL_BPS: u64 = 3_000;
 const TOKENOMICS_FEE_TO_TREASURY_BPS: u64 = 0;

docs/tokenomics-explainer-handoff.md

@@ -23,6 +23,7 @@ Catalyst v1 uses a fair-launch model with `0 KAT` at genesis and fixed issuance
 
 - `genesis_supply = 0 KAT`
 - `fixed_block_reward = 1 KAT` per successful cycle
+- `atoms_per_kat = 1_000_000_000`
 - `cycle_target = 20s`
 - `fee_burn_bps = 7000` (70%)
 - `fee_to_reward_pool_bps = 3000` (30%)

docs/tokenomics-model.md

@@ -26,6 +26,7 @@ It does **not** define future adaptive/dynamic monetary policy.
 - **Issuance start**: first successful cycle after genesis
 - **Cycle target**: `20 seconds`
 - **Fixed block reward**: `1 KAT` per successful cycle
+- **Unit scale**: `1 KAT = 1_000_000_000 atoms`
 
 Rationale:
 
@@ -46,7 +47,7 @@ Per successful cycle:
 ### Parameters
 
 - `fee_burn_bps = 7000` (70% of fees)
-- `block_reward_atoms = 1`
+- `block_reward_atoms = 1_000_000_000`
 - `fee_to_reward_pool_bps = 3000` (30% of fees)
 - `fee_to_treasury_bps = 0`
 - `producer_set_reward_bps = 7000`

docs/tokenomics-spec.md

@@ -11,6 +11,7 @@ If you are writing long-form/public docs, use `docs/tokenomics-model.md` as the
 - No premine / no token sale
 - Issuance starts on successful post-genesis cycles
 - Fixed issuance: `1 KAT` per successful cycle
+- Unit scale: `1 KAT = 1_000_000_000 atoms`
 - Reward split includes:
   - selected producer set
   - eligible waiting worker pool
@@ -31,7 +32,7 @@ If you are writing long-form/public docs, use `docs/tokenomics-model.md` as the
 
 - `crates/catalyst-consensus/src/phases.rs`
   - `RewardConfig` defaults:
-    - `block_reward = 1`
+    - `block_reward = 1_000_000_000` (1 KAT in atoms)
     - `fee_to_reward_pool_bps = 3000`
     - `producer_set_reward_bps = 7000`
     - `waiting_pool_reward_bps = 3000`

docs/tokenomics-testnet-validation.md

@@ -63,7 +63,7 @@ curl -s -X POST http://127.0.0.1:8545 -H 'content-type: application/json' \
 Expected outcome:
 
 - `applied_cycle` is non-zero and increasing over time
-- `block_reward_atoms` matches configured fixed reward (`1`)
+- `block_reward_atoms` matches configured fixed reward (`1000000000`)
 - `estimated_issued_atoms` increases as `applied_cycle` increases
 - `fee_burn_bps = 7000`, `fee_to_reward_pool_bps = 3000`, `fee_to_treasury_bps = 0`
 - `producer_set_reward_bps = 7000`, `waiting_pool_reward_bps = 3000`