feat: improve performance BTC reward distribution

.github/workflows/ci.yml

@@ -138,6 +138,28 @@ jobs:
         run: |
           make test-e2e-cache-btc-staking
 
+  e2e-run-btc-rewards:
+    needs: [e2e-docker-build-babylon]
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Download babylon artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: babylond-${{ github.sha }}
+          path: /tmp
+      - name: Docker load babylond
+        run: |
+          docker load < /tmp/docker-babylond.tar.gz
+      - name: Cache Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: 1.23
+      - name: Run e2e TestBTCRewardsDistribution
+        run: |
+          make test-e2e-cache-btc-rewards
+
   e2e-run-btc-staking-pre-approval:
     needs: [e2e-docker-build-babylon]
     runs-on: ubuntu-22.04

CHANGELOG.md

@@ -39,6 +39,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ### Improvements
 
+- [#306](https://github.com/babylonlabs-io/babylon/pull/306) feat: improve BTC reward distribution with
+virtual block periods for each finality provider that has delegations and reward tracker structures.
 - [#338](https://github.com/babylonlabs-io/babylon/pull/338) Add print BIP-340 in
 `debug pubkey-raw` subcommand
 - [#316](https://github.com/babylonlabs-io/babylon/pull/316) Add testnet upgrade data
@@ -95,6 +97,7 @@ to relay on UnbondingTime in delegation
 ## v0.17.2
 
 ### Improvements
+
 - [#311](https://github.com/babylonlabs-io/babylon/pull/311) Enforce version 2
 for unbonding transactions
 

Makefile

@@ -280,6 +280,9 @@ test-e2e-cache-btc-timestamping-phase-2-rly:
 test-e2e-cache-btc-staking:
 	go test -run TestBTCStakingTestSuite -mod=readonly -timeout=60m -v $(PACKAGES_E2E) --tags=e2e
 
+test-e2e-cache-btc-rewards:
+	go test -run TestBTCRewardsDistribution -mod=readonly -timeout=60m -v $(PACKAGES_E2E) --tags=e2e
+
 test-e2e-cache-btc-staking-pre-approval:
 	go test -run TestBTCStakingPreApprovalTestSuite -mod=readonly -timeout=60m -v $(PACKAGES_E2E) --tags=e2e
 

proto/babylon/btcstaking/v1/btcstaking.proto

@@ -167,8 +167,8 @@ message BTCDelegatorDelegationIndex {
 
 // BTCDelegationStatus is the status of a delegation.
 // There are two possible valid state transition paths for a BTC delegation:
-// - PENDING -> ACTIVE -> UNBONDED
-// - PENDING -> VERIFIED -> ACTIVE -> UNBONDED
+// - PENDING -> ACTIVE -> UNBONDED -> EXPIRED
+// - PENDING -> VERIFIED -> ACTIVE -> UNBONDED/EXPIRED
 // and one invalid state transition path:
 // - PENDING -> VERIFIED -> UNBONDED i.e the staker unbonded before
 // activating delegation on Babylon chain.
@@ -183,12 +183,14 @@ enum BTCDelegationStatus {
     VERIFIED = 1;
     // ACTIVE defines a delegation that has voting power
     ACTIVE = 2;
-    // UNBONDED defines a delegation no longer has voting power:
-    // - either reaching the end of staking transaction timelock
-    // - or receiving unbonding tx with signatures from staker and covenant committee
+    // UNBONDED defines a delegation no longer has voting power
+    // by receiving unbonding tx with signatures from staker and covenant committee
     UNBONDED = 3;
+    // EXPIRED defines a delegation no longer has voting power
+    // for reaching the end of staking transaction timelock
+    EXPIRED = 4;
     // ANY is any of the above status
-    ANY = 4;
+    ANY = 5;
 }
 
 // SignatureInfo is a BIP-340 signature together with its signer's BIP-340 PK

proto/babylon/finality/v1/finality.proto

@@ -36,31 +36,16 @@ message FinalityProviderDistInfo {
     ];
     // total_bonded_sat is the total amount of bonded BTC stake (in Satoshi) of the finality provider
     uint64 total_bonded_sat = 4;
-    // btc_dels is a list of BTC delegations' voting power information under this finality provider
-    repeated BTCDelDistInfo btc_dels = 5;
     // is_timestamped indicates whether the finality provider
     // has timestamped public randomness committed
     // if no, it should not be assigned voting power
-    bool is_timestamped = 6;
+    bool is_timestamped = 5;
     // is_jailed indicates whether the finality provider
     // is jailed, if so, it should not be assigned voting power
-    bool is_jailed = 7;
+    bool is_jailed = 6;
     // is_slashed indicates whether the finality provider
     // is slashed, if so, it should not be assigned voting power
-    bool is_slashed = 8;
-}
-
-// BTCDelDistInfo contains the information related to voting power distribution for a BTC delegation
-message BTCDelDistInfo {
-    // btc_pk is the Bitcoin secp256k1 PK of this BTC delegation
-    // the PK follows encoding in BIP-340 spec
-    bytes btc_pk = 1 [ (gogoproto.customtype) = "github.com/babylonlabs-io/babylon/types.BIP340PubKey" ];
-    // staker_addr is the address to receive rewards from BTC delegation.
-    string staker_addr = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
-    // staking_tx_hash is the staking tx hash of the BTC delegation
-    string staking_tx_hash = 3;
-    // total_sat is the amount of BTC stake (in Satoshi) of the BTC delegation
-    uint64 total_sat = 4;
+    bool is_slashed = 7;
 }
 
 // IndexedBlock is the necessary metadata and finalization status of a block

proto/babylon/incentive/rewards.proto

@@ -0,0 +1,76 @@
+syntax = "proto3";
+package babylon.incentive;
+
+import "gogoproto/gogo.proto";
+import "cosmos/base/v1beta1/coin.proto";
+import "cosmos_proto/cosmos.proto";
+
+option go_package = "github.com/babylonlabs-io/babylon/x/incentive/types";
+
+// FinalityProviderHistoricalRewards represents the cumulative rewards ratio of the
+// finality provider per sat in that period.
+// The period is ommited here and should be part of the key used to store this structure.
+// Key: Prefix + Finality provider bech32 address + Period.
+message FinalityProviderHistoricalRewards {
+    // The cumulative rewards of that finality provider per sat until that period
+    // This coins will aways increase the value, never be reduced due to keep acumulation
+    // and when the cumulative rewards will be used to distribute rewards, 2 periods will
+    // be loaded, calculate the difference and multiplied by the total sat amount delegated
+    // https://github.com/cosmos/cosmos-sdk/blob/e76102f885b71fd6e1c1efb692052173c4b3c3a3/x/distribution/keeper/delegation.go#L47
+    repeated cosmos.base.v1beta1.Coin cumulative_rewards_per_sat = 1 [
+        (gogoproto.nullable) = false,
+        (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"
+    ];
+    // TODO(rafilx): add reference count for state prunning
+    // https://github.com/cosmos/cosmos-sdk/blob/d9c53bfefc1e75a3c6b09065ea8b3a836cda0d18/x/distribution/types/distribution.pb.go#L98
+}
+
+// FinalityProviderCurrentRewards represents the current rewards of the pool of
+// BTC delegations that delegated for this finality provider is entitled to.
+// Note: This rewards are for the BTC delegators that delegated to this FP
+// the FP itself is not the owner or can withdraw this rewards.
+// If a slash event happens with this finality provider, all the delegations need
+// to withdraw to the RewardGauge and the related scrutures should be deleted.
+// Key: Prefix + Finality provider bech32 address.
+message FinalityProviderCurrentRewards {
+    // CurrentRewards is the current rewards that the finality provider have and it was not
+    // yet stored inside the FinalityProviderHistoricalRewards. Once something happens that
+    // modifies the amount of satoshis delegated to this finality provider or the delegators
+    // starting period (activation, unbonding or btc rewards withdraw)
+    // a new period must be created, accumulate this rewards to FinalityProviderHistoricalRewards
+    // with a new period and zero out the Current Rewards.
+    repeated cosmos.base.v1beta1.Coin current_rewards = 1 [
+        (gogoproto.nullable) = false,
+        (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"
+    ];
+    // Period stores the current period that serves as a reference for
+    // creating new historical rewards and correlate with BTCDelegationRewardsTracker
+    // StartPeriodCumulativeReward.
+    uint64 period = 2;
+    // TotalActiveSat is the total amount of active satoshi delegated
+    // to this finality provider.
+    bytes total_active_sat = 3 [
+        (cosmos_proto.scalar)  = "cosmos.Int",
+        (gogoproto.customtype) = "cosmossdk.io/math.Int",
+        (gogoproto.nullable)   = false
+    ];
+}
+
+// BTCDelegationRewardsTracker represents the structure that holds information
+// from the last time this BTC delegator withdraw the rewards or modified his
+// active staked amount to one finality provider.
+// The finality provider address is ommitted here but should be part of the
+// key used to store this structure together with the BTC delegator address.
+message BTCDelegationRewardsTracker {
+    // StartPeriodCumulativeReward the starting period the the BTC delegator
+    // made his last withdraw of rewards or modified his active staking amount
+    // of satoshis.
+    uint64 start_period_cumulative_reward = 1;
+    // TotalActiveSat is the total amount of active satoshi delegated
+    // to one specific finality provider.
+    bytes total_active_sat = 2 [
+        (cosmos_proto.scalar)  = "cosmos.Int",
+        (gogoproto.customtype) = "cosmossdk.io/math.Int",
+        (gogoproto.nullable)   = false
+    ];
+}

proto/babylon/incentive/tx.proto

@@ -44,13 +44,13 @@ message MsgWithdrawRewardResponse {
 // MsgUpdateParams defines a message for updating incentive module parameters.
 message MsgUpdateParams {
     option (cosmos.msg.v1.signer) = "authority";
-  
+
     // authority is the address of the governance account.
     // just FYI: cosmos.AddressString marks that this field should use type alias
     // for AddressString instead of string, but the functionality is not yet implemented
     // in cosmos-proto
     string authority = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
-  
+
     // params defines the incentive parameters to update.
     //
     // NOTE: All parameters must be supplied.