Skip to content

Commit bf8d503

Browse files
0xAleksaOpacic0xAleksaOpacic
committed
docs: add reward mechanism
1 parent e4dadd4 commit bf8d503

File tree

2 files changed

+116
-0
lines changed

2 files changed

+116
-0
lines changed

‎docs/contract-managment.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -377,6 +377,7 @@ babylond tx btcstkconsumer register-consumer \
377377
"$CONSUMER_ID" \
378378
"$CONSUMER_NAME" \
379379
"$CONSUMER_DESCRIPTION" \
380+
"$BABYLON_REWARDS_COMMISSION" \
380381
"$ROLLUP_FINALITY_CONTRACT_ADDRESS"
381382
```
382383

@@ -386,6 +387,8 @@ Required metadata for BSN registration:
386387
* `consumer_name`: Human-readable name of your rollup BSN (e.g., `"DeFi Rollup
387388
Chain"`)
388389
* `consumer_description`: Brief description of the rollup BSN's purpose
390+
* `babylon_rewards_commission`: Commission rate for Babylon Genesis protocol
391+
revenue (between 0 and 1, e.g., `"0.05"` for 5%)
389392
* `rollup_finality_contract_address`: Babylon Genesis address of the deployed
390393
Rollup BSN contract (`bbn1...` format)
391394

‎docs/reward-distribution.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Rollup BSN Reward Distribution
2+
3+
## Table of Contents
4+
5+
1. [Introduction](#introduction)
6+
2. [Reward Bridging Strategy](#1-reward-bridging-strategy)
7+
3. [Reward Distribution Process](#2-reward-distribution-process)
8+
4. [Message Structure](#3-message-structure)
9+
5. [Distribution Calculation](#4-distribution-calculation)
10+
11+
## Introduction
12+
13+
Rollup BSNs must bridge rewards to the Babylon Genesis chain, where they are
14+
distributed to finality providers, their delegators, and protocol revenue.
15+
Tokens can be bridged from any supported source and are received through the
16+
`x/bank` module.
17+
18+
> **📖 For detailed information about the reward mechanism and best practices,
19+
> see the
20+
> [Babylon Rewards Distribution Guide](https://github.com/babylonlabs-io/babylon/blob/release/v3.x/x/btcstaking/docs/rewards-distribution.md).**
21+
22+
Distribution is then handled by the
23+
[x/incentive module](https://github.com/babylonlabs-io/babylon/tree/v3.0.0-rc.2/x/incentive),
24+
which manages the allocation of rewards to finality providers, delegators, and
25+
protocol revenue.
26+
27+
> **Babylon Genesis** supports multiple bridging methods for transferring tokens
28+
> into the `x/bank` module, including: [Union](https://union.build/),
29+
> [IBCEureka](https://cosmos.network/ibc-eureka/), and standard
30+
> [IBC](https://cosmos.network/ibc/) for Cosmos chains. For the reward
31+
> mechanism, the only requirement is that tokens ultimately arrive in `x/bank`.
32+
33+
> **⚠️ Important**: CW-20 assets are *not* supported.
34+
35+
> **Important**: The only requirement is that tokens must be present in a specific account within the `x/bank` module on Babylon Genesis before distribution can occur.
36+
37+
## 1. Reward Distribution Process
38+
39+
> **Note**: The reward interval is the time period between reward distributions.
40+
> This interval is not predefined by the protocol, each BSN is responsible for
41+
> controlling their own distribution frequency and interval length.
42+
43+
The reward distribution process follows a four-step strategy:
44+
45+
1. **Bridge tokens to x/bank** on Babylon Genesis
46+
2. **Calculate total rewards** for the current reward interval
47+
3. **Calculate distribution ratios** for finality providers (you can reference
48+
voting tables from the [Rollup Finality Gadget](https://github.com/babylonlabs-io/rollup-finality-gadget)
49+
or use any distribution scheme you choose)
50+
4. **Submit MsgAddBsnRewards** message to Babylon Genesis to distribute rewards
51+
52+
> **Note**: BSNs can choose to bridge tokens in bulk (maintaining a balance) or
53+
> just-in-time (before each distribution), depending on their operational
54+
> preferences.
55+
56+
During [BSN registration](contract-management.md#5-rollup-bsn-registration), a
57+
fixed protocol commission rate is set. When distributing rewards via
58+
`MsgAddBsnRewards`, the BSN specifies the total reward amount and finality
59+
provider distribution ratios, while the protocol commission remains fixed at the
60+
registration rate.
61+
62+
> **Note**: Rewards are distributed to delegators based on their active stakes
63+
> at the time the distribution message is submitted. Delegators who unbond
64+
> before distribution may miss rewards, so **frequent distributions minimize this risk**.
65+
66+
## 3. Message Structure
67+
68+
BSN rewards are distributed through the submission of a `MsgAddBsnRewards` message to the Babylon Genesis chain.
69+
70+
**Message Format:**
71+
```go
72+
type MsgAddBsnRewards struct {
73+
// Sender is the babylon address which will pay for the rewards
74+
Sender string `protobuf:"bytes,1,opt,name=sender,proto3" json:"sender,omitempty"`
75+
// BsnConsumerId is the ID of the BSN consumer
76+
BsnConsumerId string `protobuf:"bytes,2,opt,name=bsn_consumer_id,json=bsnConsumerId,proto3" json:"bsn_consumer_id,omitempty"`
77+
// TotalRewards is the total amount of rewards to be distributed
78+
TotalRewards github_com_cosmos_cosmos_sdk_types.Coins `protobuf:"bytes,3,rep,name=total_rewards,json=totalRewards,proto3,castrepeated=github.com/cosmos/cosmos-sdk/types.Coins" json:"total_rewards"`
79+
// FpRatios is a list of finality providers and their respective reward distribution ratios
80+
FpRatios []FpRatio `protobuf:"bytes,4,rep,name=fp_ratios,json=fpRatios,proto3" json:"fp_ratios"`
81+
}
82+
```
83+
84+
### Field Explanations
85+
86+
- **`Sender`**: Babylon address (bbn...) that will pay for the rewards
87+
- Must have sufficient balance to cover `TotalRewards`
88+
- Account must be in the `x/bank` module
89+
90+
- **`BsnConsumerId`**: Unique identifier for the BSN
91+
- Must match the ID used during BSN registration
92+
- Unregistered IDs will be rejected
93+
94+
- **`TotalRewards`**: Total reward amount and denomination to be distributed
95+
- Must be available in the `Sender` account
96+
- Supports multiple coin types in a single distribution
97+
- Protocol commission is automatically deducted based on registration rate
98+
99+
- **`FpRatios`**: Finality provider distribution ratios
100+
- Maps finality provider public keys to reward portions
101+
- All portions must sum to `1.0`
102+
- All finality providers must be registered and have active delegations
103+
104+
> **Critical**: The `Sender` account must have sufficient coins to cover the
105+
> `TotalRewards` amount before submitting the message.
106+
107+
> **Note**: BSNs are responsible for calculating finality provider distribution
108+
> ratios. You can reference voting tables from the
109+
> [Rollup Finality Gadget](https://github.com/babylonlabs-io/rollup-finality-gadget) or use any
110+
> distribution method they choose.
111+
112+
113+

0 commit comments

Comments
 (0)