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

# Gem Tokens

## Overview

Gem tokens represent AI-specific value and are the primary tradeable tokens in Bitplanet's AI economies. Each AI has its own unique Gem token, minted by burning Cores at a 1:1 ratio.

**Key Purpose:** Enable market-driven valuation of individual AIs through freely tradeable tokens.

## Token Standards

Gems exist in two formats to maximize compatibility:

### ERC-1155 (Native Format)

The native format stored in the `GemCoreNFT` contract:

**Advantages:**

* Gas-efficient multi-token standard
* Single contract manages all AI gems
* Batch operations support
* Mixed fungible/non-fungible capability

**Structure:**

```solidity
contract GemCoreNFT {
  mapping(uint256 => uint256) private _totalSupply;  // AI ID → Total Gem Supply
  mapping(uint256 => mapping(address => uint256)) private _balances;
}
```

### ERC-20 (Wrapped Format)

Wrapped format via adapter contracts for DEX compatibility:

**Advantages:**

* Standard DEX support (Uniswap, etc.)
* Familiar wallet interfaces
* Easy integration with DeFi protocols
* Wide ecosystem compatibility

**Conversion:**

* Seamless ERC-1155 ↔ ERC-20 wrapping
* 1:1 ratio maintained
* No value loss in conversion

## Minting Process

### Step 1: Obtain Cores

Creator must first receive Core allocation via governance:

* Submit `MsgCoreGrantApplication`
* Community approves proposal
* Cores allocated to creator

### Step 2: Convert Cores to Gems

Creator calls `mintGem()` function on `GemCoreNFT` contract:

```solidity
function mintGem(
  bytes calldata aiId,
  address[] calldata recipients,
  uint256[] calldata amounts
) external {
  // Burn cores from caller
  _burnCores(msg.sender, totalAmount);

  // Mint gems to recipients
  for (uint i = 0; i < recipients.length; i++) {
    _mint(recipients[i], aiId, amounts[i]);
  }
}
```

**Process:**

1. System validates creator has sufficient core allocation
2. Cores burned from creator's balance
3. Gems minted to specified recipients
4. AI total supply updated
5. Event emitted for indexing

## Market Capitalization

AI market cap determines each AI's share of BPL inflation rewards. The metric evolves in two phases:

**Current Implementation (Pre-AMM):**

```
market_cap_metric = gem_supply
```

Where `gem_supply` = ERC-1155 totalSupply.

**Future Implementation (Post-AMM):**

```
market_cap_metric = rolling_average[ (W1 × gem_supply) + (W2 × gem_market_cap) ]
```

Where:

* `gem_supply` = ERC-1155 totalSupply (count of gems)
* `gem_market_cap` = AMM\_price × gem\_supply (actual market value from DEX)
* `W1, W2` = governance-adjustable weights

**Why This Matters:**

* Determines AI's share of inflation rewards
* Reflects real user demand and engagement
* Updates every block via 30-90 day rolling average

**Why the Weighted Formula?**

* **Supply alone**: Harder to manipulate (requires burning Cores), but doesn't reflect market sentiment
* **Price alone**: Vulnerable to pump-and-dump on thin AMM liquidity
* **Weighted combination**: Governance can tune W1/W2 to balance manipulation resistance with market responsiveness

**Rolling Average Mechanism:**

* Smooths volatility from rapid supply or price changes
* Prevents reward manipulation via short-term spikes
* Stored deterministically in KVStore
* 30-90 day window provides balance between responsiveness and stability

### Market Cap Storage

```protobuf
message MarketCapHistory {
  string ai_id = 1;
  repeated string market_caps = 2;  // Rolling average history buffer
  uint32 current_index = 3;
  uint32 total_entries = 4;
}
```

## Gem Lifecycle

```
1. Core Allocation (Governance)
   ↓
2. Core Minting (via RfC)
   ↓
3. Gem Minting (burn cores)
   ↓
4. Market Trading (DEXs, transfers)
   ↓
5. Market Cap Calculation (rolling average)
   ↓
6. Inflation Reward Distribution (proportional to market cap)
```

## Use Cases

**For AI Creators:**

* Initial token distribution to early supporters
* Fundraising through gem sales
* Incentive alignment with community

**For Users:**

* Purchase gems to support favorite AIs
* Trade gems on open markets
* Earn rewards as contributors (receive gems for contributions)

**For Traders:**

* Speculate on AI growth
* Provide liquidity on DEXs
* Arbitrage between ERC-1155 and ERC-20 formats

## Token Distribution

Gems are distributed through multiple channels:

**Initial Distribution (Core Minting):**

* Creator receives cores via governance
* Creator mints gems and distributes to:
  * Early adopters
  * Team members
  * Contributors (via RfC)
  * Public sale participants

**Secondary Distribution:**

* Market trading on DEXs
* P2P transfers
* Rewards for contributions (via inflation)
* Liquidity mining programs

## Technical Implementation

### BeaconFactory Pattern

Gems use BeaconFactory for efficient deployment:

**Benefits:**

* \~90% gas savings per token deployment
* Batch upgrades across all AI gems
* Consistent logic across all tokens
* Minimal bytecode per proxy (\~200 bytes)

For details, see [EVM Compatibility - BeaconFactory Pattern](/advanced-topics/blockchain-architecture/evm-compatibility.md#beaconfactory-pattern).

### UUPS Upgradeability

Core contracts use UUPS proxy pattern:

**Benefits:**

* Bug fixes without redeployment
* Feature additions to existing contracts
* Preserved user balances and state
* Governance-controlled upgrades

For details, see [EVM Compatibility - Contract Upgradeability](/advanced-topics/blockchain-architecture/evm-compatibility.md#contract-upgradeability).

## Integration Points

**With x/brahma Module:**

* Market cap queried via EVM for reward distribution
* Total supply determines AI's inflation share
* Rolling average updated every block

**With EVM Contracts:**

* `GemCoreNFT` manages all gem operations
* Precompile addresses enable Cosmos ↔ EVM communication
* Events emitted for off-chain indexing

**With DEXs:**

* ERC-20 wrapped gems tradeable on Uniswap
* Liquidity pools for price discovery
* Standard AMM mechanics apply

## Design Rationale

**Why AI-Specific Gems?** Enables independent market valuation of each AI, rather than single shared token.

**Why ERC-1155 Native Format?** Gas efficiency for batch operations and multi-token management in single contract.

**Why Also ERC-20?** Maximum DeFi compatibility without forcing users to understand ERC-1155.

**Why Market Cap = Gem Supply?** Direct, objective measure of user engagement. More users holding gems = higher market cap = more rewards.

**Why 30-Block Rolling Average?** Balances between:

* Responsiveness to genuine growth
* Resistance to manipulation attempts
* Computational efficiency