Hooks & Lifecycle

Bitplanet's block lifecycle includes standard BitSDK hooks (BeginBlock, EndBlock) and custom EVM hooks (PostTxProcessing) that execute at specific points in block processing. This page explains when these hooks run and what operations they perform.

Block Lifecycle Overview

Each block follows this execution flow:

1. BeginBlock (all modules in order)

2. Transaction Execution

   • Validate transaction

   • Execute message handlers

   • PostTxProcessing hooks (after each EVM tx)

3. EndBlock (all modules in order)

4. Commit (state finalized)

BeginBlock Hooks

Module Execution Order

BeginBlock hooks execute in this sequence:

1. mint

2. ibc

3. erc20

4. feemarket

5. evm

6. brahma

7. precompile

Why Order Matters:

• Mint must run first (creates new tokens for distribution)

• EVM must run after feemarket (gas price updates)

• Brahma must run after EVM (queries EVM state for market caps)

• Feemarket runs last in EndBlock (updates base fee)

x/brahma BeginBlock

The primary custom hook in Bitplanet's BeginBlock.

Purpose: Distributes inflation rewards to AI creators, AI Apps, and contributors.

Operations:

1. Query distribution module balance

2. Calculate siphon amount

3. Transfer tokens to brahma module

4. Query AI market caps from EVM contracts

5. Distribute proportionally to stakeholders

6. Update claimable reward balances

Performance: O(n) where n = number of AIs (limited by max_ais_for_rewards parameter)

For detailed technical implementation, see Inflation Mechanism and Reward Distribution.

EndBlock Hooks

Module Execution Order

EndBlock hooks execute in this sequence:

1. gov

2. staking

3. auth

4. bank

5. evm

6. erc20

7. feemarket

Key Operations:

• gov: Tally proposal votes, execute passed proposals

• staking: Update validator set, process unbonding

• feemarket: Update EIP-1559 base fee (must run last)

Note: Most Bitplanet-specific logic runs in BeginBlock. EndBlock primarily handles standard BitSDK operations.

PostTxProcessing Hooks

Custom hooks that execute after each EVM transaction completes.

Hook Registration

Hooks are registered in reverse order of execution:

evmKeeper.SetHooks(
  NewMultiEvmHooks(
    precompileKeeper.Hooks(),  // Executes first
    brahmaKeeper.Hooks(),      // Executes second
  )
)

x/precompile PostTxProcessing

Purpose: Bridge EVM events to BitSDK operations.

Flow:

1. EVM Transaction → Receipt with Logs

2. PostTxProcessing Hook

3. Check logs for precompile addresses

4. Match event signatures

5. Execute BitSDK operations

Supported Events:

• CoreGrantApplication: Creates governance proposal for core grant - see Core Tokens

• OreRequest: Processes contribution tensors, mints cores - see AI Tensor Matrix

• ContributionTypes: Updates contribution type parameters

See x/precompile Module - Event Processing for implementation details.

x/brahma PostTxProcessing

Purpose: Process reward claim events from EVM contracts.

Operation:

• Listens for BplCoinClaimed events

• Validates claim data

• Transfers rewards to claimant

For detailed claiming process, see Reward Distribution.

Event Emission

Event Types

Bitplanet modules emit events for indexing and external monitoring:

x/brahma Events:

EventTypeCoreGrantApplication
EventTypeRemoveCoreGrantApplication
EventTypeRequestForCore
EventTypeClaimRewards

x/precompile Events:

EventTypeTurnstileRegister
EventTypeTurnstileUpdate
EventTypeParamChange

Standard Cosmos Events:

• message: Module and action

• transfer: Token movements

• delegate: Staking operations

Event Structure

Events include typed attributes:

sdk.NewEvent(
  "core_grant_application",
  sdk.NewAttribute("requester", requester),
  sdk.NewAttribute("allocation", amount),
  sdk.NewAttribute("height", height),
)

Use Cases:

• Block explorers index events for queries

• AI Apps subscribe to specific event types

• Analytics track on-chain activity

Module Dependencies

BeginBlock Dependencies

1. mint (creates tokens)

2. brahma (distributes tokens)

3. evm (queries contract state)

Brahma depends on mint running first and queries EVM state for market caps.

PostTxProcessing Dependencies

1. EVM transaction completes

2. precompile hook (processes events)

3. brahma hook (processes claims)

Both hooks depend on EVM transaction execution completing successfully.

Performance Considerations

BeginBlock Limits

Governance parameters prevent unbounded processing:

Parameter	Default	Purpose
max_ais_for_rewards	500	Limits AIs processed per block
max_ai_block_heights	1,000	Limits historical data processed
max_tensor_rows_per_block	1,000	Limits contributor rows processed

Why: Ensures BeginBlock completes within block time (~6 seconds).

For how these parameters affect reward calculations, see Inflation Mechanism.

PostTxProcessing Overhead

Each EVM transaction triggers hooks:

• Iterates through transaction logs

• Checks for registered precompile addresses

• Minimal overhead if no matching events

Optimization: Hooks exit early if no relevant events detected.

Hook Execution Guarantees

Atomicity

BeginBlock/EndBlock operations are atomic:

• All operations succeed or entire block fails

• State changes committed together

• No partial execution

Determinism

All hooks must be deterministic:

• Same inputs → same outputs

• No randomness or external dependencies

• Consistent ordering across validators

Example: Brahma uses rolling averages stored in state (not memory) to ensure deterministic reward calculations.