> 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/core-tokens.md).

# Core Tokens

## Overview

Core tokens are genesis allocations granted through governance proposals that bootstrap new AIs with initial token supply. They serve as one-time permissions to mint Gems and are burned upon conversion.

**Key Purpose:** Enable community-controlled AI bootstrapping without centralized token issuance.

## Lifecycle

{% @mermaid/diagram content="graph LR
A\[Creator Submits Proposal via Platform] --> B\[Community Votes]
B -->|Approved| C\[Cores Allocated]
B -->|Rejected| D\[No Allocation]
C --> E\[Creator Burns Cores]
E --> F\[Gems Minted 1:1]" %}

### Step-by-Step Process

1. **Proposal Submission**
   * Platform (e.g., Deva) submits `MsgCoreGrantApplication` via governance on behalf of AI creators
   * Specifies requested core allocation amount
   * Provides title and description
2. **Community Voting**
   * Token holders vote on proposal
   * Standard BitSDK governance process
   * Requires majority approval
3. **Core Allocation**
   * If approved → Cores allocated to creator's address
   * Permission recorded on-chain with expiry block height
   * Creator can now request cores via `MsgRequestForCore` via Platform
4. **Gem Minting**
   * Platform converts Cores to Gems via `GemCoreNFT` contract on behalf of users
   * 1 Core = 1 Gem (1:1 ratio)
   * Cores are burned in the process
   * Gems become tradeable AI-specific tokens
   * Users receive Gems without directly interacting with the blockchain

## Core Grant Application

### Data Structure

```protobuf
message MsgCoreGrantApplication {
  string authority = 1;              // Governance module account
  string requester = 2;              // Address receiving permission
  uint64 core_allocation = 3;        // Total cores granted
  int64 created_at_height = 6;       // For expiry tracking
  string title = 4;
  string description = 5;
}
```

### Key Properties

**Governance-Controlled:**

* All allocations require community approval
* No centralized control over core issuance
* Transparent on-chain process

**Expiring Permissions:**

* Core Grant Applications expire after configured block height
* Default: 1,000 blocks from creation
* Prevents indefinite core minting permissions

**Accumulative:**

* Multiple approved proposals increase total allocation
* Creator can submit new proposals for additional cores
* Each approval resets expiry timer

**Removable:**

* Governance can revoke permissions via `MsgRemoveCoreGrantApplication`
* Requires mandatory reason field for audit trail
* Useful for addressing security concerns or policy violations

## Parameters

| Parameter                              | Default | Description                       |
| -------------------------------------- | ------- | --------------------------------- |
| `max_core_grant_allocation`            | 100     | Maximum cores per single proposal |
| `core_grant_application_expiry_height` | 1,000   | Blocks before CGA expires         |

## Usage Flow Example

**Scenario:** Creator wants to launch "AlphaAI" with 50 initial gems on Deva platform

```
1. Platform Submits Proposal (on behalf of creator)
   - Deva submits: Request 50 cores for AlphaAI
   - Title: "Bootstrap AlphaAI - AI Language Model"
   - Description: "Request 50 cores to mint initial gem supply..."

2. Governance Vote
   - Voting period: 7 days
   - Result: 65% Yes, 35% No
   - Status: APPROVED

3. Core Allocation
   - Deva platform receives permission for 50 cores
   - Expiry: Current block + 1,000 blocks
   - Deva can now request cores via RfC

4. Request Cores (RfC)
   - Deva submits contribution tensor documenting creator's work
   - System validates and deducts from allocation
   - Cores minted to creator's address

5. Convert to Gems (Automatic)
   - Deva automatically calls mintGem() on GemCoreNFT contract
   - Burn 50 cores → Mint 50 AlphaAI gems
   - Creator receives 50 gems in their wallet
   - Gems now tradeable on markets
   - Creator never directly interacted with blockchain
```

## Security Features

**Quota System:**

* Each CGA has fixed core allocation
* System deducts from quota on each RfC
* Prevents unlimited core minting

**Expiry Mechanism:**

* Permissions automatically expire
* Prevents stale permissions from being exploited
* Governance can extend by approving new proposal

**Authorization Checks:**

* Only governance can approve CGAs
* Only approved platform (e.g., Deva) can submit RfCs
* AI App address must match the approved platform's address
* Ensures only authorized platforms can submit contributions on behalf of users

## Integration with x/brahma Module

Core tokens are managed by the x/brahma module:

* **Storage:** Stored in module state by requester address
* **Validation:** Checked on every `MsgRequestForCore`
* **Minting:** Executed via EVM contract call to `GemCoreNFT`

For detailed technical implementation, see [x/brahma Module - Core Grant Application](/advanced-topics/blockchain-architecture/custom-modules/brahma-module.md#core-grant-application).

## Design Rationale

**Why Governance-Controlled?** Prevents spam and ensures only legitimate AIs receive initial token supply.

**Why Expiring Permissions?** Reduces long-term risk of compromised accounts minting unlimited cores.

**Why 1:1 Core-to-Gem Ratio?** Simplifies mental model and ensures predictable initial supply.

**Why Burn Cores?** Cores are a scarce, freely tradeable reserve commodity token. Burning on conversion enforces the 1:1 Core-to-Gem issuance path and keeps the bootstrap process predictable.