Reward Distribution

Overview

Bitplanet uses a two-step reward distribution system where rewards are automatically calculated and accumulated each block, then claimed by users via manual transactions.

Two Steps:

1. Automatic Allocation - Every block, rewards calculated and added to claimable balances

2. Manual Claiming - Users submit transactions to claim accumulated rewards

Key Benefit: Separating allocation from claiming prevents distribution failures and gives users control over gas costs.

Claimable Rewards System

How It Works

Every Block (BeginBlock):

• Calculate inflation distribution

• Add to creator's claimable balance

• Add to AI App's claimable balance

• Add to contributors' claimable balances

User Action (When Ready):

• Trigger claim via EVM contract → Tokens transferred to user account

Benefits

For the System:

• Distribution never fails due to transfer errors

• Module continues distributing even if some addresses are invalid

• No blocked state transitions

For Users:

• Control timing of claims (minimize gas costs)

• Batch multiple blocks' rewards in single claim

• Transparent on-chain tracking of unclaimed rewards

Claiming Process

Query Claimable Balance

Users can check accumulated rewards through query endpoints:

Query: QueryClaimableRewards(address)
Response: Amount (sdk.Coins)

This shows total rewards accumulated but not yet claimed.

Trigger Claim via EVM Contract

When ready to claim, users interact with the GemCoreNFT factory contract which emits a BplCoinClaimed event:

Event Structure:

event BplCoinClaimed(address indexed from, address indexed claimer);

Transaction Flow:

1. User calls claim function on GemCoreNFT factory contract

2. Contract emits BplCoinClaimed event

3. x/brahma PostTxProcessing hook intercepts event

4. Module validates and processes claim

5. Transfers tokens from brahma module account to user

6. Resets claimable balance to zero

Note: Claims are triggered through EVM contract interaction, not direct BitSDK messages. This enables seamless integration with Web3 wallets and AI App interfaces.

Validation:

• Address must be valid format

• Claimable balance must be > 0

• Module must have sufficient balance

Reward Sources

Creator Rewards (40%)

Eligibility: Registered as AI creator

Calculation:

AI's Total Inflation Reward × 40%

Frequency: Accumulated every block as long as AI has non-zero market cap

Example:

AI receives 100 bplcoin this block
Creator reward: 100 × 0.4 = 40 bplcoin (added to claimable balance)

AI App Rewards (40%)

Eligibility: Registered as AI App operator for AI

Calculation:

AI's Total Inflation Reward × 40%

Frequency: Accumulated every block as long as AI has non-zero market cap

Example:

AI receives 100 bplcoin this block
AI App reward: 100 × 0.4 = 40 bplcoin (added to claimable balance)

Contributor Rewards (20%)

Eligibility: Has contributed to AI (recorded in AI Tensor Matrix)

Calculation:

AI's Total Inflation Reward × 20% × (Your Cores / Total Cores)

Frequency: Accumulated every block based on historical contributions

Example:

AI receives 100 bplcoin this block
Contributor pool: 100 × 0.2 = 20 bplcoin

Your contributions: 150 cores out of 300 total
Your reward: 20 × (150/300) = 10 bplcoin (added to claimable balance)

Accumulation Over Time

Rewards accumulate continuously as long as conditions are met:

For Creators:

• AI has non-zero gem supply (market cap > 0)

• AI is in first 500 by insertion order

For AI App Operators:

• Same conditions as creators

• Registered as AI App operator for the AI

For Contributors:

• AI has non-zero gem supply

• AI is in first 500 by insertion order

• Historical contribution tensors exist (within last 1,000 blocks)

Example Timeline:

Block 1000: Alice earns 5 bplcoin (claimable: 5)
Block 1001: Alice earns 6 bplcoin (claimable: 11)
Block 1002: Alice earns 4 bplcoin (claimable: 15)
Block 1003: Alice claims → Receives 15 bplcoin (claimable: 0)
Block 1004: Alice earns 5 bplcoin (claimable: 5)

Claim Statistics

Query Aggregate Statistics

Query: QueryClaimStatistics()
Response:
  - Total unclaimed rewards (all users)
  - Total rewards ever distributed
  - Total claims processed
  - Average claim amount

Useful for:

• Monitoring system health

• Understanding user behavior

• Economic analysis

Storage

Claimable Rewards Storage

Key: [Prefix: 0x05] + [Address]
Value: sdk.Coins (claimable amount)

Properties:

• Per-address storage

• Updated every block during allocation

• Reset to zero on claim

• Preserved across chain restarts

Gas Considerations

Claiming Costs

Users pay gas for claiming:

• Transaction fee (standard BitSDK)

• Minimal computational cost (simple transfer)

Strategy: Batch claims to minimize total gas fees over time.

No Cost for Allocation

Allocation happens automatically in BeginBlock:

• No user transaction required

• No gas paid by users

• System cost covered by block inflation

Security Features

Double-Claim Prevention

• Claimable balance reset to zero after claim

• No risk of double-spending rewards

Module Account Safety

• Rewards held in module account (not user accounts)

• Only claimable via proper transaction

• Module account balance always >= total claimable balances

Overflow Protection

• Safe math for all accumulation

• Balance checks before transfers

• Prevents invalid state transitions

Integration with Inflation Mechanism

Reward distribution is tightly coupled with inflation:

BeginBlock Hook (every block):

1. Siphon inflation from distribution module

2. Calculate AI proportions by market cap

3. For each AI:

   • Calculate creator/AI App/contributor allocations

   • Add to respective claimable balances

4. Continue to next block

Users claim independently of this automatic process.

Example: Complete Reward Flow

Setup:

• AI "AlphaAI" has 1,000 gem market cap

• Total market cap across all AIs: 2,000 gems

• Distribution module has 1,000 bplcoin

• Siphon percentage: 50% (adjustable via governance)

Block N:

1. Siphon: 1,000 × 0.5 = 500 bplcoin to brahma module

2. AlphaAI proportion: 1,000/2,000 = 50%
   AlphaAI reward: 500 × 0.5 = 250 bplcoin

3. Allocations:
   Creator (Alice):      250 × 0.4 = 100 bplcoin (added to claimable)
   AI App (Bob):         250 × 0.2 = 50 bplcoin (added to claimable)
   Contributors (pool):  250 × 0.4 = 100 bplcoin

4. Contributor distribution (historical contributions):
   Carol (100 cores): 100 × (100/300) = 33.33 bplcoin (added to claimable)
   Dave (150 cores):  100 × (150/300) = 50.00 bplcoin (added to claimable)
   Eve (50 cores):    100 × (50/300) = 16.67 bplcoin (added to claimable)

Later (Block N+100):

Alice checks balance: 1,000 bplcoin accumulated
Alice submits claim → Receives 1,000 bplcoin
Alice's claimable balance: 0

Design Rationale

Why Two-Step Process? Prevents block production from failing if individual user accounts have issues.

Why User-Initiated Claims? Users control gas costs and timing. No forced transfers that might fail.

Why Accumulation? Enables batching rewards from multiple blocks, reducing total claim transactions.

Why Module Account Storage? Centralizes reward management, simplifies accounting, enables system-wide statistics.