Skip to content

Commit 6a96396

Browse files
0xAleksaOpacic0xAleksaOpacic
authored
docs: add reward mechanism (#120)
## Description This PR add reward mechanism doc
1 parent e4dadd4 commit 6a96396

File tree

4 files changed

+122
-0
lines changed

4 files changed

+122
-0
lines changed

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
3737

3838
## Unreleased
3939

40+
### Improvements
41+
42+
* [#120](https://github.com/babylonlabs-io/rollup-bsn-contracts/pull/120) docs:
43+
add reward mechanism
44+
4045
## v1.0.0-rc.1
4146

4247
### Improvements

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

‎rust-toolchain.toml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[toolchain]
2+
channel = "1.82.0"
3+
components = ["clippy", "rustfmt"]

0 commit comments

Comments
 (0)