Skip to content

Commit 6da690f

Browse files
TheNewAutonomyTheNewAutonomy
committed
Added tokenomics
1 parent 8ec5c30 commit 6da690f

5 files changed

Lines changed: 141 additions & 0 deletions

File tree

‎site/docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ Official links:
2020
- **Wallet users**: start with **[Use the wallet](/docs/quickstarts/i-want-to-use-the-wallet)**.
2121
- **dApp builders**: start with **[Deploy a contract](/docs/quickstarts/i-want-to-deploy-a-contract)**, then **[RPC: transaction lifecycle](/docs/rpc-reference/transaction-lifecycle)**.
2222
- **Explorer / faucet operators**: start with **[Explorer operator guide](/docs/explorer/operator-guide)** and **[Faucet operator guide](/docs/faucet/operator-guide)**.
23+
- **Anyone reviewing economics**: read **[Tokenomics (v1 baseline)](/docs/overview/tokenomics)**.
2324

2425
## Stability labels
2526

‎site/docs/overview/key-concepts.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,3 +47,14 @@ Canonical references:
4747

4848
See **[RPC: transaction lifecycle](/docs/rpc-reference/transaction-lifecycle)** for end-to-end examples.
4949

50+
## Tokenomics (v1 baseline)
51+
52+
- Fair launch: `0 KAT` at genesis.
53+
- Fixed issuance: `1 KAT` per successful cycle (target ~20s).
54+
- Unit scale: `1 KAT = 1_000_000_000 atoms` (`block_reward_atoms = 1_000_000_000`).
55+
- Fee routing: `70%` burn, `30%` reward pool, `0%` treasury.
56+
- Reward split baseline: producer set gets larger share; eligible waiting workers also receive rewards.
57+
- Fee credits: only for eligible waiting workers, non-transferable, and never a replacement for mandatory transaction fees.
58+
59+
See **[Overview: tokenomics](/docs/overview/tokenomics)** for parameters, rationale, and verification.
60+

‎site/docs/overview/tokenomics.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
sidebar_position: 4
3+
title: Tokenomics (v1 baseline)
4+
---
5+
6+
This page explains Catalyst v1 tokenomics in plain language and gives operator-facing verification steps.
7+
8+
Canonical source of truth:
9+
10+
- `catalyst-node-rust/docs/tokenomics-model.md`
11+
- `catalyst-node-rust/docs/tokenomics-spec.md`
12+
- RPC: `catalyst_getTokenomicsInfo`
13+
14+
## One-paragraph explainer
15+
16+
Catalyst v1 uses a fair-launch model with `0 KAT` at genesis and fixed issuance of `1 KAT` per successful cycle (target ~20 seconds). Unit scale is fixed at `1 KAT = 1_000_000_000 atoms`. Transaction fees are mandatory and split deterministically: `70%` is burned, `30%` goes into the reward pool, and `0%` goes to treasury. Each cycle, rewards are shared between selected producers and eligible waiting workers, with the larger share to active producers and a meaningful share to waiting participants. Waiting workers can also accrue non-transferable fee credits (after warmup and eligibility checks) that offset only their own transaction fees.
17+
18+
## v1 parameters
19+
20+
Publish these values exactly:
21+
22+
- `genesis_supply = 0 KAT`
23+
- `no_premine_no_sale = true`
24+
- `fixed_block_reward = 1 KAT` per successful cycle
25+
- `atoms_per_kat = 1_000_000_000`
26+
- `block_reward_atoms = 1_000_000_000`
27+
- `cycle_target = 20s`
28+
- `fee_burn_bps = 7000` (70%)
29+
- `fee_to_reward_pool_bps = 3000` (30%)
30+
- `fee_to_treasury_bps = 0`
31+
- `producer_set_reward_bps = 7000`
32+
- `waiting_pool_reward_bps = 3000`
33+
- Fee credits:
34+
- `fee_credits_enabled = true`
35+
- `fee_credits_warmup_days = 14`
36+
- `fee_credits_accrual_atoms_per_day = 200`
37+
- `fee_credits_max_balance_atoms = 6000`
38+
- `fee_credits_daily_spend_cap_atoms = 300`
39+
- `waiting_eligibility_churn_penalty_days = 3`
40+
41+
## Why these decisions
42+
43+
- **`0 KAT` at genesis**: reinforces fair launch (no premine/no sale) and aligns issuance with participation.
44+
- **Fixed `1 KAT` issuance**: predictable baseline for wallets, operators, and explorers.
45+
- **Burn 70% of fees**: keeps anti-spam cost non-recoverable and avoids treasury governance/custody complexity at launch.
46+
47+
## Atom unit interpretation (RPC and tooling)
48+
49+
- RPC integer amounts are atom-denominated unless otherwise labeled.
50+
- `block_reward_atoms = 1000000000` means `1 KAT` per successful cycle.
51+
- Convert atoms to KAT with: `KAT = atoms / 1_000_000_000`.
52+
- Prefer storing and comparing integer atom values in automation; render KAT as a UI/display conversion.
53+
54+
## Reward flow per successful cycle
55+
56+
1. Mint fixed issuance (`1 KAT`).
57+
2. Route 30% of cycle fees into reward pool (70% burned, 0% treasury).
58+
3. Split reward pool between selected producer set (larger share) and eligible waiting worker pool (smaller share).
59+
4. Accrue fee credits for eligible waiting workers (subject to warmup, max-balance cap, daily spend cap, and churn-penalty eligibility window).
60+
61+
## Fee credits (correct wording)
62+
63+
Use this wording in user docs:
64+
65+
- Fee credits accrue to eligible waiting workers (not selected producers for that cycle).
66+
- Fee credits are non-transferable and only pay the sender's own fees.
67+
- Credits have warmup, max-balance, daily spend caps, and a churn-penalty eligibility window.
68+
69+
Avoid this wording:
70+
71+
- All participants always accrue fee credits.
72+
- Fee credits are transferable.
73+
- Fee credits remove the need for transaction fees (fees remain mandatory).
74+
75+
## Verify on a running node
76+
77+
```bash
78+
curl -s -X POST http://127.0.0.1:8545 -H 'content-type: application/json' \
79+
-d '{"jsonrpc":"2.0","id":1,"method":"catalyst_getTokenomicsInfo","params":[]}' | jq
80+
```
81+
82+
Check that the response includes:
83+
84+
- `applied_cycle`
85+
- `block_reward_atoms`
86+
- `estimated_issued_atoms`
87+
- `fee_burn_bps`
88+
- `fee_to_reward_pool_bps`
89+
- `fee_to_treasury_bps`
90+
- `producer_set_reward_bps`
91+
- `waiting_pool_reward_bps`
92+
93+
## FAQ
94+
95+
### Is Catalyst deflationary?
96+
97+
Not always. v1 has fixed issuance (`1 KAT` per successful cycle) and also burns 70% of fees. Net supply direction depends on activity and total fees over time.
98+
99+
### Why not send fees to a treasury?
100+
101+
v1 sets treasury routing to zero to avoid launch-time custody and governance complexity. Treasury routing can be revisited in a future protocol upgrade.
102+
103+
### Do waiting nodes receive anything?
104+
105+
Yes. Eligible waiting workers receive a share of cycle rewards and can accrue fee credits that offset their own transaction fees.
106+
107+
### Are fee credits transferable?
108+
109+
No. Fee credits are non-transferable and scoped to the same sender identity.
110+
111+
### Could Catalyst run out of tokens quickly?
112+
113+
No. At `1 KAT` minted every `20s`, the theoretical numeric supply ceiling (from `u64` atom representation) is extremely far out, roughly `11,699 years` of continuous successful cycles.

‎site/docs/overview/what-is-catalyst.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,15 @@ Catalyst is a blockchain stack (node + RPC + SDK + apps) focused on running a pr
3131
- **`pubkey32`**: 32-byte hex public key used as the account identifier in protocol transactions (example: `0x<64 hex>`).
3232
- **`address20`**: 20-byte hex EVM address used for contracts and EVM account derivations (example: `0x<40 hex>`).
3333

34+
## Economics at a glance
35+
36+
- Fair launch baseline: `0 KAT` at genesis.
37+
- Fixed issuance baseline: `1 KAT` per successful cycle.
38+
- Unit scale baseline: `1 KAT = 1_000_000_000 atoms`.
39+
- Fee policy baseline: fees are mandatory; 70% burned and 30% routed to rewards.
40+
41+
For current parameters and operator verification, see **[Overview: tokenomics](/docs/overview/tokenomics)**.
42+
3443
## Verify (quick sanity checks)
3544

3645
If you have an RPC URL, you can confirm basic chain identity:

‎site/docs/rpc-reference/methods.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,13 @@ Canonical source of truth:
5656
- **Experimental**: `catalyst_peerCount()` → `u64`
5757
- **Stable**: `catalyst_version()` → string
5858

59+
## Tokenomics
60+
61+
- **Stable**: `catalyst_getTokenomicsInfo()` → tokenomics parameters (issuance, fee routing, reward split)
62+
- includes `block_reward_atoms` (`1000000000` for `1 KAT`) and `estimated_issued_atoms`
63+
- includes `fee_burn_bps`, `fee_to_reward_pool_bps`, `fee_to_treasury_bps`
64+
- includes `producer_set_reward_bps`, `waiting_pool_reward_bps`
65+
5966
## EVM helpers
6067

6168
- **Stable**: `catalyst_getCode(address20)` → `0x...` (empty `0x` if none)

0 commit comments

Comments
 (0)