Smart Contract Integration

Overview

Bitplanet's smart contract ecosystem manages AI-generated content tokens through a coordinated system of upgradeable contracts. The architecture centers around the GemCoreNFT orchestrator contract, which coordinates Core token allocation (via governance) and Gem NFT creation (for AI contributions), while adapter contracts enable seamless interoperability with DeFi protocols through ERC20 conversions.

Contract Locations:

• Brahma contracts: contracts_brahma/ directory

• Main contracts:

  • GemCoreNFTUpgradeable.sol

  • ERC1155TokenToERC20AdapterUpgradeable.sol

  • MintableERC1155Upgradeable.sol

  • BeaconFactory.sol

• Solidity version: ^0.8.22 (OpenZeppelin 5.x)

• Note: Interface definitions are embedded within the main contract files, not in separate interface files

GemCoreNFTUpgradeable Contract

Location: contracts_brahma/GemCoreNFTUpgradeable.sol

Purpose: The GemCoreNFTUpgradeable contract is the central orchestrator of the Bitplanet token ecosystem. It manages two types of NFTs:

• Core tokens: Fundamental reward tokens allocated through governance, representing the base economic unit

• Gem tokens: User-generated content NFTs created by burning Core tokens, representing contributions to AIs

This contract acts as the single source of truth for all token operations, coordinating between BitSDK (via x/brahma module) and the EVM layer. It uses the UUPS (Universal Upgradeable Proxy Standard) pattern for upgradeability while maintaining a single contract instance for gas efficiency.

How It Works:

1. The x/brahma module calls the contract to allocate Core tokens to users based on AI contribution tensors

2. Users claim their allocated Core tokens via claimCore(), which mints the ERC1155 NFTs

3. Users burn Core tokens to create Gem NFTs representing their contributions to specific AIs

4. The contract manages conversion between ERC1155 (NFT) and ERC20 (fungible) representations through adapter contracts

5. All child contracts (ERC1155 gems, ERC20 adapters) report transfers back to this contract for centralized event tracking

Key Interface Methods:

interface IGemCoreNFTUpgradeable {
    function onTransferErc20(
        address from,
        address to,
        uint256 devaId,
        uint256 amount
    ) external;

    function onTransferErc1155(
        address from,
        address to,
        uint256 devaId,
        uint256[] memory postIds
    ) external;

    function selectIndexes(
        uint256 min,
        uint256 max,
        uint256 amt
    ) external pure returns (uint256[] memory);
}

Key Implementation Notes:

• Core Minting: mintCore() populates redemption matrix (no direct minting)

• Core Claiming: claimCore() mints allocated tokens to caller

• Gem Creation: mintGem() burns 1 core, creates gem NFT

• Token IDs: Core = keccak256("core"), Gems = keccak256(devaId)

• Conversions: Use GemCoreNFT methods, not adapter directly

Conversion Methods (on GemCoreNFT):

// Convert ERC1155 gems to ERC20 tokens
function convertToErc20(string memory devaId, uint256 amount) public;

// Convert ERC20 tokens back to ERC1155 gems
function convertToErc1155(string memory devaId, uint256 amount) public;

// Convert core ERC1155 to ERC20
function convertCoreToErc20(uint256 amount) public;

// Redeem ERC20 core tokens back to ERC1155
function redeemCore(uint256 amount) public;

MintableERC1155Upgradeable Contract

Location: contracts_brahma/MintableERC1155Upgradeable.sol

Purpose: MintableERC1155Upgradeable provides the core NFT functionality for Gem tokens. Each AI (identified by a devaId) gets its own instance of this contract, deployed as a Beacon Proxy for efficient batch upgrades across all AI contracts.

How It Works: This contract extends the standard ERC1155 multi-token implementation with two critical enhancements:

1. Transfer Hooks: Every transfer operation calls back to the parent GemCoreNFT contract via onTransferErc1155(), enabling centralized event tracking for external indexers

2. Duplicate Post ID Support: Multiple gems with the same post ID increment the balance rather than creating separate token instances, allowing users to own multiple copies of the same content NFT

The Beacon Proxy pattern means all gem NFT contracts share the same implementation contract. When you upgrade the beacon, all gem NFTs are upgraded simultaneously without individual transactions.

Usage Pattern:

• Users don't interact with this contract directly

• All operations go through GemCoreNFTUpgradeable, which manages the gem contracts

• The contract is automatically deployed when the first gem for a new AI is minted

Implementation:

• Standard ERC1155 functions: mint(), burn(), balanceOf(), safeTransferFrom()

• Transfer hooks call parent's onTransferErc1155()

• Supports duplicate post IDs (balance > 1 for same token ID)

• No setMaster() function - owner set during initialization

ERC1155TokenToERC20AdapterUpgradeable

Location: contracts_brahma/ERC1155TokenToERC20AdapterUpgradeable.sol

Purpose: The ERC20 Adapter bridges the gap between non-fungible ERC1155 tokens and fungible ERC20 tokens, enabling seamless interoperability with DeFi protocols, decentralized exchanges, and other ERC20-compatible applications.

How It Works: Each gem NFT collection (one per AI) has a corresponding ERC20 adapter contract that allows users to convert their unique NFTs into fungible tokens and back:

1. ERC1155 → ERC20 Conversion: When users convert gems to ERC20, the adapter:

   • Burns the specified number of ERC1155 tokens from the user's balance

   • Mints equivalent ERC20 tokens at a 10^19 scaling factor (1 NFT = 10^19 ERC20 tokens)

   • Allows the ERC20 tokens to be traded, staked, or used in DeFi

2. ERC20 → ERC1155 Redemption: When users redeem ERC20 tokens back to NFTs:

   • Burns the ERC20 tokens from the user's balance

   • Transfers ERC1155 tokens back to the user from the adapter's reserve

   • Restores the original NFT representation

The scaling factor (10^19) provides sufficient precision for fractional ownership while maintaining compatibility with standard ERC20 expectations.

Deployment Pattern:

• Like MintableERC1155, these adapters use the Beacon Proxy pattern

• Each AI gets one adapter contract, deployed automatically when needed

• All adapters share the same implementation via the beacon, enabling batch upgrades

Key Interface Methods:

interface IERC1155TokenToERC20AdapterUpgradeable {
    function initialize(
        string memory symbol,
        string memory ticker,
        uint256 _devaId,
        address _operator,
        address initialOwner
    ) external;

    function redeem(uint256 amount) external;

    function redeemFor(address recipient, uint256 amount) external;

    function balanceOf(address account) external view returns (uint256);

    function transfer(address to, uint256 amount) external returns (bool);

    function transferFrom(address from, address to, uint256 amount) external returns (bool);

    function approve(address spender, uint256 amount) external returns (bool);

    function allowance(address owner, address spender) external view returns (uint256);

    function totalSupply() external view returns (uint256);

    function devaId() external view returns (uint256);

    function operator() external view returns (address);
}

Scaling Factor: 10^19 (10 × 10^18), NOT 10^22

Usage (via GemCoreNFT, not adapter directly):

// Convert 5 gem ERC1155 NFTs to 5e19 ERC20 tokens
nft.convertToErc20("devaId", 5);  // Called on GemCoreNFT

// Redeem 2.5e19 ERC20 tokens back to 2.5 ERC1155 NFTs
nft.convertToErc1155("devaId", 2.5e19);  // Called on GemCoreNFT

// For core tokens
nft.convertCoreToErc20(2);      // Convert cores to ERC20
nft.redeemCore(2e19);           // Redeem ERC20 back to cores

// Direct adapter method (owner-only, called internally)
adapter.redeemFor(recipient, amount);  // Only callable by GemCoreNFT owner

Next Steps

• Explore module APIs that power these contracts in Module API

• See how contracts and modules interact in Module Interaction

• Review smart contract security in Security Considerations

• Start building with Quick Start