Module Interaction

Architecture Overview

The Bitplanet architecture bridges two distinct execution environments: the BitSDK layer (native blockchain modules) and the EVM layer (Ethereum-compatible smart contracts). This dual-layer design enables seamless interaction between Bitplanet's custom modules and EVM-based applications.

Key Components:

BitSDK Layer:

• x/brahma manages AI token economics, processing tensor contributions and distributing rewards

• x/precompile acts as the bridge, monitoring EVM events and triggering SDK actions via hooks

• x/gov handles governance proposals for core allocations and parameter updates

• BitEVM Module provides the EVM execution environment

EVM Contract Layer:

• GemCoreNFT (UUPS upgradeable) orchestrates the NFT ecosystem, managing Core and Gem tokens

• MintableERC1155 contracts (Beacon proxies) represent individual gem collections with upgrade capability

• ERC20Adapter contracts bridge ERC1155 NFTs to fungible ERC20 tokens (10^19 scaling factor)

• Precompiled Contracts expose BitSDK functionality (staking, governance, etc.) to EVM contracts

Flow Highlights:

1. Event-Driven Architecture: EVM events trigger BitSDK state changes via the precompile module's PostTxProcessing hook

2. Bidirectional Communication: x/brahma can call EVM contracts (for minting), while EVM events trigger SDK messages (for governance)

3. Governance Integration: Core allocations require governance approval, creating a trustless permission system

4. Modular Upgradeability: UUPS pattern for GemCoreNFT, Beacon pattern for token contracts enable non-disruptive upgrades

Architecture Diagram:

EVM Hook Mechanism

Implementation Location: x/precompile/keeper/evm_hooks.go

The precompile module implements the EvmHooks interface to process EVM events and trigger BitSDK state changes.

1. Event Detection (PostTxProcessing Hook)

When an EVM transaction completes, the precompile module scans emitted events:

// File: x/precompile/keeper/evm_hooks.go
func (h Hooks) PostTxProcessing(ctx sdk.Context, sender common.Address,
                                msg core.Message, receipt *ethtypes.Receipt) error {
    params := h.k.GetParams(ctx)

    // Only process if transaction has a recipient contract
    if msg.To != nil {
        // Check for Governance precompile events
        if containsPrecompileContract(receipt, params.GovPrecompile) {
            h.govPrecompile(ctx, receipt, params.GovPrecompile)
        }

        // Check for Brahma precompile events
        if containsPrecompileContract(receipt, params.BrahmaPrecompile) {
            if err := h.brahmaPrecompile(ctx, receipt, msg, params.BrahmaPrecompile); err != nil {
                return err
            }
        }

        // Check for Staking precompile events
        if containsPrecompileContract(receipt, params.StakingPrecompile) {
            h.stakingPrecompile(ctx, receipt, params.StakingPrecompile)
        }
    }

    return nil
}

Hook Registration:

• Hooks are registered in the app setup (evmd/app.go)

• Multiple precompile handlers can be chained

• Each handler processes specific contract events

2. Event Processing

Different events trigger different BitSDK actions:

CoreGrantApplicationEvent:

// Automatically creates governance proposal
func (h Hooks) handleCoreGrantApplicationEvent(ctx sdk.Context, log *ethtypes.Log) error {
    proposerAddress := common.BytesToAddress(log.Topics[1].Bytes())
	proposer := sdk.AccAddress(proposerAddress.Bytes())

    grantAmount := math.NewIntFromBigInt(log.Topics[2].Big())

    // Message only contains Authority, Requester, CoreAllocation
    msg := &brahmaTypes.MsgCoreGrantApplication{
        Authority:      "ethm10d07y265gmmuvt4z0w9aw880jnsr700jpva843",
        Requester:      proposer.String(),
        CoreAllocation: grantAmount.Uint64(),
        // Note: Title, Description, CreatedAtHeight NOT set here
    }

    // Title/summary passed to SubmitProposal, not in message
    title := "Core Grant Application"
    summary := "Request for Core grant allocation"
    messages := []sdk.Msg{msg}
    metadata := "Proposal Metadata"

    _, err := h.k.govKeeper.SubmitProposal(ctx.Context(), messages, metadata, title, summary, proposer, true)
    return err
}

Note: The MsgCoreGrantApplication created by the hook only populates Authority, Requester, and CoreAllocation. The Title, Description, and CreatedAtHeight fields are NOT set in the hook—they're passed separately to SubmitProposal or must be set when manually creating proposals.

OreRequestEvent:

// Processes tensor contribution immediately
func (h Hooks) handleOreRequestEvent(ctx sdk.Context, log *ethtypes.Log, msg core.Message) error {
    addr := common.HexToAddress(log.Topics[1].Hex())

    var event OreRequestEvent
    err := BrahmaContract.UnpackIntoInterface(&event, "OreRequestEvent", log.Data)
    if err != nil {
        return err
    }

    // Submit MsgRequestForCore directly
    return h.RequestForCore(ctx, event.Name, addr, event.Values, msg.From)
}

3. BeginBlock Reward Distribution

Every block, the Brahma module siphons inflation and distributes rewards:

func (k *Keeper) BeginBlock(ctx sdk.Context) error {
    const baseDenom = "bplcoin"

    // 1. Get reward split parameters (all return math.LegacyDec)
    creatorSplit, _ := k.GetCreatorSplit(ctx)
    applicationSplit, _ := k.GetApplicationSplit(ctx)
    contributorSplit, _ := k.GetContributorSplit(ctx)
    siphonPercentage, _ := k.GetSiphonPercentage(ctx)

    // 2. Calculate AI reward proportions based on market cap
    aiToSplitOfRewards := k.SplitInflationPerAI(ctx)  // returns map[string]math.LegacyDec

    // 3. Get distribution module account and balance
    distributionModuleAccount := k.accountKeeper.GetModuleAccount(ctx, distributiontypes.ModuleName)
    if distributionModuleAccount == nil {
        return nil  // No module account
    }

    // Get all balances and extract the base denomination amount
    distributionBalances := k.bankKeeper.GetAllBalances(ctx, distributionModuleAccount.GetAddress())
    distributionBalance := distributionBalances.AmountOf(baseDenom)

    if !distributionBalance.IsPositive() {
        return nil  // No tokens to distribute
    }

    // 4. Siphon tokens: Convert to Dec, multiply, truncate back to Int
    toSiphon := math.LegacyNewDecFromInt(distributionBalance).Mul(siphonPercentage).TruncateInt()

    if !toSiphon.IsPositive() {
        return nil
    }

    // Get brahma module account
    brahmaModuleAccount := k.accountKeeper.GetModuleAccount(ctx, types.ModuleName)
    if brahmaModuleAccount == nil {
        return nil
    }

    // Transfer siphoned tokens
    siphonedCoins := sdk.NewCoins(sdk.NewCoin(baseDenom, toSiphon))
    err := k.bankKeeper.SendCoinsFromModuleToAccount(ctx, distributiontypes.ModuleName,
                                                      brahmaModuleAccount.GetAddress(), siphonedCoins)
    if err != nil {
        return err
    }

    // 5. Allocate to each AI's participants
    for aiID, proportion := range aiToSplitOfRewards {
        ai, found := k.GetAI(ctx, aiID)
        if !found {
            continue
        }

        // Convert siphoned Int to Dec, multiply by proportion
        toAllocateForAI := math.LegacyNewDecFromInt(toSiphon).Mul(proportion)

        // Allocate using Dec amounts (methods accept math.LegacyDec)
        k.AllocateToCreator(ctx, toAllocateForAI.Mul(creatorSplit), ai)
        k.AllocateToApplication(ctx, toAllocateForAI.Mul(applicationSplit), ai)
        k.AllocateToContributors(ctx, toAllocateForAI.Mul(contributorSplit), ai)
    }

    return nil
}

Critical implementation details:

• Must fetch module account first: GetModuleAccount(ctx, distributiontypes.ModuleName)

• Use GetAllBalances() then .AmountOf(baseDenom) (not GetBalance())

• Check for nil module accounts and zero balances before proceeding

• math.LegacyNewDecFromInt() converts sdk.Int → math.LegacyDec for multiplication

• .TruncateInt() converts math.LegacyDec → sdk.Int after multiplication

• This pattern prevents precision loss during percentage calculations

Complete Workflow Example

Scenario: Core Grant Application → Approval → Minting

1. User submits grant application via smart contract:

   brahmaPrecompile.CoreGrantApplication(1000000); // Request 1M cores

2. Precompile hook detects event and creates governance proposal:

   CoreGrantApplicationEvent emitted
   → PostTxProcessing hook triggered
   → MsgCoreGrantApplication created (with title, description, height)
   → Governance proposal submitted automatically

3. Governance voting and execution:

   Validators vote on proposal
   → Proposal passes
   → MsgCoreGrantApplication executed
   → CoreGrantApplication stored in state (keyed by requester address)

4. User contributes AI tensors:

   brahmaPrecompile.submitOreRequest("my-ai", [addr], [contributions]);

5. Ore minting and Core NFT distribution:

   OreRequestEvent emitted
   → handleOreRequestEvent processes contributions
   → CalculateOresToMint returns map[address]amount
   → IssueCores batches and calls GemCoreNFT.mintCore()
   → Users can claim Core NFTs via claimCore()

6. Automated reward distribution each block:

   BeginBlock executes
   → SplitInflationPerAI calculates proportions
   → Rewards distributed to creator, Application, contributors
   → Claimable balances updated

Next Steps

• Review module APIs for detailed transaction types in Module API

• Explore smart contract implementations in Smart Contract Integration

• Learn about security patterns in Security Considerations

• Begin development with Quick Start