> For the complete documentation index, see [llms.txt](https://docs.bitplanet.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitplanet.ai/advanced-topics/token-economics-technical/reward-distribution.md).

# 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:**

```solidity
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.