Solana 合约定义

权威定义: 本文档是 Microcosm Solana 合约的单一真相源。

最后更新: 2026-02-02

状态: ✅ 8 个合约全部主网部署完成，Token 使用 SPL Token + Metaplex Metadata，MCC Mint Authority 已放弃 (None)，MCD Mint Authority 保留

2026-02-02: 🔄 SPL Token + Metaplex 迁移完成 - MCC/MCD 从 Token-2022 切换到 SPL Token，解决 Solscan/钱包 Logo 显示问题

2026-01-30: Reincarnation 合约添加 USDT 支持 - 所有稳定币视为等价 (1 USDC = 1 USDT = 1 USD)

2026-01-29: 主网部署完成 - 8 个合约部署

2026-01-23: MCD Token 合约新增账户关闭指令 - close_user_mcd_account 支持僵尸账户租金回收

2026-01-21: MCD Token 合约新增白名单功能 - 3 个白名单管理指令 + consume_mcd 自动验证

2026-01-20: Reincarnation 合约升级完成 - 新增 execute_mining + execute_monthly_cycle 指令

一、已部署合约

1.1 合约概览

⚠️ 重要概念区分：

• Token Mint = 代币本身的账户地址，由 SPL Token 程序管理
• 业务合约 Program ID = 我们开发的 Anchor 程序（铸造/分发/消费等业务逻辑）
• 两者完全不同！Token Mint 重新部署会变，业务合约升级时 Program ID 不变

业务合约 (我们开发的 Anchor 程序)

Token 层 (由 Solana 官方 SPL Token 程序管理)

Token Program: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA (Solana SPL Token)

2026-02-02: MCC/MCD 切换到 SPL Token + Metaplex Metadata，Solscan/钱包完美支持

1.2 关键地址 (主网)

1.3 钱包管理

主网 Authority 地址:

查询主网余额:

curl -s https://api.mainnet-beta.solana.com -X POST -H "Content-Type: application/json" -d '{
  "jsonrpc": "2.0", "id": 1,
  "method": "getBalance",
  "params": ["MCWe3gEYqTjRCShEkhqbMXhcR4xP2dz29gurSpLbk4A"]
}' | python -c "import sys,json; d=json.load(sys.stdin); print(f'{d[\"result\"][\"value\"]/1e9:.4f} SOL')"

获取密钥:

# 主网 Authority
gcloud secrets versions access latest --secret=solana-mainnet-authority --project=double-helix-9f030

二、MCC Token 合约

2.1 基本信息 (主网 - SPL Token + Metaplex)

⚠️ 区分：MCC Program (业务合约) ≠ Token Program (Solana 官方 SPL Token)

业务合约 (我们开发的)

Token 层 (由 SPL Token 管理)

2026-02-02: MCC Token 切换到 SPL Token + Metaplex Metadata，全部 10 亿枚铸造到 Genesis ATA，Mint Authority 已放弃 (None)。Logo 可在 Solscan 和钱包中正常显示。

2.2 指令列表

2026-01-20 更新: 移除 initialize_user_vault 和 withdraw，User PDA 托管设计已废弃

2.3 分配规则

详见 distribution-ratios.md

三、MCD Token 合约

3.1 基本信息 (主网 - SPL Token + Metaplex)

⚠️ 区分：MCD Program (业务合约) ≠ Token Program (Solana 官方 SPL Token)

业务合约 (我们开发的)

Token 层 (由 SPL Token 管理)

2026-02-02: MCD Token 切换到 SPL Token + Metaplex Metadata，解决 Solscan/钱包 Logo 显示问题。MCD Config PDA 已初始化完成。

3.2 关键 PDA (主网)

Station MCD Vault (待重新初始化)

Territory ID 规范: Station 使用 stations.id 生成 Territory ID（如 S-00001），不使用 units.id

⚠️ 2026-02-02: MCD 切换到 SPL Token 后，Station Vault ATA 需要重新初始化

PDA 计算公式:

# Station Vault PDA
seeds = [b"station_vault", station_id.to_le_bytes()]  # station_id 是 u64
vault_pda, bump = Pubkey.find_program_address(seeds, MCD_PROGRAM_ID)

# Station Vault ATA (SPL Token)
vault_ata = get_associated_token_address(MCD_MINT, vault_pda, TOKEN_PROGRAM_ID)

3.3 PDA Seeds（重要！）

# Python 和 Rust 代码必须使用相同的 seeds
MCD_CONFIG_SEED = b"mcd_config"
MCD_GENESIS_POOL_SEED = b"mcd_genesis_pool"
MCD_RECYCLE_POOL_SEED = b"mcd_recycle_pool"
STATION_VAULT_SEED = b"station_vault"      # 没有 mcd_ 前缀！
USER_MCD_SEED = b"user_mcd"                 # 不是 user_mcd_account！
MCD_WHITELIST_SEED = b"mcd_whitelist"       # 白名单 PDA (2026-01-21 新增)

3.4 指令列表

2026-01-23 更新: 新增 close_user_mcd_account 账户关闭指令，支持僵尸账户租金回收

2026-01-21 更新: 新增白名单管理指令（add_to_whitelist, remove_from_whitelist, update_whitelist_status）

3.5 MCD 白名单机制（2026-01-21 新增）

设计目的: 确保 MCD 保持为系统控制的积分，而非自由流通的代币。

白名单 PDA 结构:

pub struct McdWhitelist {
    pub project_id: u64,           // 项目 ID
    pub wallet_address: Pubkey,    // 项目方 MCD 钱包地址
    pub project_name: [u8; 64],    // 项目名称（最多 64 字节）
    pub registered_at: i64,        // 注册时间戳
    pub status: u8,                // 0=active, 1=suspended
    pub updated_at: i64,           // 最后更新时间戳
    pub bump: u8,                  // PDA bump
}

白名单验证流程:

1. 用户调用 consume_mcd 消费 MCD
2. 合约自动验证目标项目是否在白名单中（通过 PDA seeds 查找）
3. 验证项目方钱包地址是否匹配白名单记录
4. 验证项目状态是否为 active（未被暂停）
5. 验证通过后执行 MCD 转账（用户 PDA → 项目方钱包）

白名单管理:

• 管理员通过 add_to_whitelist 添加项目，提供 project_id、wallet_address、project_name
• 管理员通过 update_whitelist_status 暂停（suspend）或激活（active）项目
• 管理员通过 remove_from_whitelist 完全移除项目（关闭 PDA 账户）

状态常量:

pub const STATUS_ACTIVE: u8 = 0;      // 激活状态，可接收 MCD
pub const STATUS_SUSPENDED: u8 = 1;   // 暂停状态，拒绝 MCD 转账

3.6 账户关闭与租金回收（2026-01-23 新增）

设计目的: 关闭僵尸 MCD 账户，回收链上 SOL 租金到 Genesis Authority。

3.6.1 close_user_mcd_account 指令

pub fn close_user_mcd_account(ctx: Context<CloseUserMcdAccount>) -> Result<()> {
    // 1. 验证 Token Account 余额为 0
    // 2. 关闭 User Token Account (ATA)，租金返回 rent_receiver
    // 3. 关闭 UserMcdAccount PDA，租金返回 rent_receiver
}

#[derive(Accounts)]
pub struct CloseUserMcdAccount<'info> {
    #[account(mut)]
    pub authority: Signer<'info>,  // MCD 管理员

    #[account(
        mut,
        seeds = [USER_MCD_SEED, &user_mcd_account.uid.to_le_bytes()],
        bump,
        close = rent_receiver
    )]
    pub user_mcd_account: Account<'info, UserMcdAccount>,

    #[account(
        mut,
        associated_token::mint = mcd_mint,
        associated_token::authority = user_mcd_account,
        constraint = user_token_account.amount == 0 @ McdError::AccountNotEmpty
    )]
    pub user_token_account: Account<'info, TokenAccount>,

    /// CHECK: rent_receiver 接收回收的租金 (Genesis Authority)
    #[account(mut)]
    pub rent_receiver: AccountInfo<'info>,

    pub mcd_mint: Account<'info, Mint>,
    pub token_program: Program<'info, Token>,
    pub system_program: Program<'info, System>,
}

3.6.2 账户租金明细

3.6.3 僵尸账户判定条件

管理员可关闭同时满足以下条件的账户：

1. MCD 余额 = 0
2. 未加入任何 Station (station_id IS NULL)
3. 超过 180 天未登录

3.6.4 租金回收地址

3.6.5 安全约束

• 只有 MCD 管理员 (authority) 可以执行关闭
• 只能关闭余额为 0 的账户（合约强制校验）
• 所有关闭操作记录到数据库（mcd_account_closures 表）

3.6.6 链上租金验证机制（2026-01-24 新增）

设计目的: 确保数据库记录的租金与链上实际回收金额一致，避免预估值与实际值不符。

验证流程:

1. 查询 Authority SOL 余额 (balance_before)
2. 执行 close_user_mcd_account 交易
3. 查询 Authority SOL 余额 (balance_after)
4. 计算实际回收租金 = balance_after - balance_before
5. 将实际值写入数据库（非预估值）

Python 实现:

# mcd_solana_client.py

async def close_user_mcd_account(self, uid: int) -> dict:
    # 🔍 链上验证 Step 1: 记录关闭前 Authority 余额
    balance_before = await self.solana_client.get_balance(self.authority.pubkey())

    # 构建并发送关闭交易...
    signature = await self.solana_client.send_transaction(tx, self.authority)
    await self.solana_client.confirm_transaction(signature)

    # 🔍 链上验证 Step 2: 记录关闭后 Authority 余额
    balance_after = await self.solana_client.get_balance(self.authority.pubkey())

    # 🔍 链上验证 Step 3: 计算实际回收租金
    rent_recovered_lamports = balance_after - balance_before
    rent_recovered_sol = rent_recovered_lamports / 1e9

    return {
        'signature': str(signature),
        'rent_recovered_lamports': rent_recovered_lamports,
        'rent_recovered_sol': rent_recovered_sol
    }

降级策略:

为什么预估值是 0.00361 而不是 0.00293:

• 理论计算值: Token Account (~0.00204) + PDA (~0.00089) = ~0.00293 SOL
• 实际测试值: 0.00361 SOL（包含链上交易的额外租金返还）
• 链上验证确保使用实际值，预估值仅作为降级兜底

3.6.7 后端 API

四、Lending 合约

4.1 基本信息

4.2 已初始化账户（2026-01-15）

4.3 PDA Seeds

const LENDING_POOL_SEED = "mcc_lending_pool";
const LP_MINT_SEED = "mcc_lp_mint";
const NFT_PRICE_ORACLE_SEED = "nft_price_oracle";
// Vault 是 ATA，不使用 seeds

4.4 Vault 地址计算（重要！）

import { getAssociatedTokenAddressSync } from "@solana/spl-token";

// Vault 是 ATA，不是自定义 PDA！
// allowOwnerOffCurve = true，因为 owner 是 PDA
const vault = getAssociatedTokenAddressSync(MCC_MINT, lendingPool, true);

4.5 初始化参数

{
  pool_name: "mcc-lending-pool",
  base_rate: 1000,           // 10% APR
  optimal_utilization: 8000, // 80%
  slope1: 1000,              // 10%
  slope2: 8000,              // 80%
}

4.6 贷款规则

4.7 指令 Discriminator（已验证）

const DISCRIMINATORS = {
  initializeLendingPool: [236, 76, 136, 68, 196, 14, 9, 177],
  initializeLpMint: [205, 250, 9, 201, 188, 220, 164, 60],     // IDL 自动生成值错误！
  initializeVault: [48, 191, 163, 44, 71, 129, 63, 164],
  initializeNftOracle: [6, 80, 1, 161, 115, 198, 249, 112],
};

4.8 后端集成状态（2026-01-16）

API 端点：

Open API 端点 (/v1/lending):

五、构建与部署规范

5.1 版本要求

5.2 Cargo.toml 必须配置

[dependencies]
anchor-lang = { version = "0.30.1", features = ["init-if-needed"] }
anchor-spl = { version = "0.30.1", features = ["token", "associated_token", "metadata"] }

# 关键！固定 blake3 版本避免 edition2024 问题
blake3 = "=1.7.0"

5.3 Cloud Build 命令

必须使用 --region=asia-northeast1，禁止使用 global 区域！

# 构建
gcloud builds submit --config=cloudbuild.yaml --project=double-helix-9f030 --region=asia-northeast1

# 部署
gcloud builds submit --config=cloudbuild-deploy.yaml --project=double-helix-9f030 --region=asia-northeast1

5.4 密钥管理

所有密钥存储在 GCP Secret Manager：

# 获取密钥
gcloud secrets versions access latest --secret=solana-genesis-keypair --project=double-helix-9f030

六、已知问题与解决方案

6.1 Anchor 0.30.1 TypeScript 客户端 Bug

问题: 使用 program.methods.xxx().accounts().rpc() 初始化 PDA 时出现 "writable privilege escalated" 错误。

解决方案: 绕过 Anchor 客户端，使用原生 TransactionInstruction：

const ix = new TransactionInstruction({
  keys: [
    { pubkey: authority.publicKey, isSigner: true, isWritable: true },
    { pubkey: lendingPool, isSigner: false, isWritable: true },
    { pubkey: MCC_MINT, isSigner: false, isWritable: false },
    { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
  ],
  programId: PROGRAM_ID,
  data: Buffer.concat([discriminator, ...args]),
});

6.2 IDL Discriminator 不正确

问题: anchor build 生成的 IDL 中 discriminator 可能错误。

解决方案: 手动计算验证：

const crypto = require('crypto');
const hash = crypto.createHash('sha256');
hash.update('global:initialize_lp_mint');  // snake_case
const discriminator = [...hash.digest().slice(0, 8)];
// [205, 250, 9, 201, 188, 220, 164, 60]

6.3 edition2024 兼容性

问题: blake3 >= 1.8 需要 edition2024，但 Solana platform-tools 的 Cargo 是 1.84。

解决方案: 在 Cargo.toml 中固定 blake3 = "=1.7.0"。

七、Territory NFT 合约

7.1 基本信息

7.2 已初始化账户（2026-01-16）

7.3 PDA Seeds

const COLLECTION_SEED = "territory_collection";
const TERRITORY_NFT_SEED = "territory_nft";

7.4 指令列表

7.5 领地 NFT 类型

7.6 栈溢出问题与解决方案

问题: 在 Devnet/Mainnet 上执行 InitializeCollection 时出现 Access violation in stack frame 错误。

原因: Solana 程序栈限制 4KB，多个 init 约束 + CPI 调用导致栈溢出。特性 EenyoWx9UMXYKpR8mW5Jmfmy2fRjzUtM7NduYMY8bx33 在 devnet/mainnet 未启用。

解决方案:

1. 将初始化拆分为两步（initialize_config + initialize_collection_nft）
2. 使用 Box<Account<>> 将账户移到堆上
3. 使用 #[inline(never)] 将 CPI 调用拆分到独立函数

7.7 后端集成状态（2026-01-16）

API 端点:

• GET /api/territory/config - 获取 Collection 配置
• GET /api/territory/holdings/<wallet> - 获取 NFT 持有量
• GET /api/territory/nft/<mint> - 获取 NFT 详情
• GET /api/territory/list/<wallet> - 获取用户 NFT 列表
• POST /api/territory/mint - 铸造 NFT [管理员]
• POST /api/territory/transfer/prepare - 准备 NFT 转移
• POST /api/territory/burn/prepare - 准备 NFT 销毁

Open API 端点 (/v1/territory):

八、Auction 合约

8.1 基本信息

8.2 已初始化账户（2026-01-16）

8.3 PDA Seeds

const AUCTION_CONFIG_SEED = "auction_config";
const AUCTION_SEED = "auction";
const BID_SEED = "bid";
const MCC_ESCROW_SEED = "mcc_escrow";

8.4 初始化参数

{
  min_bid_increment_percent: 5,  // 5%
  auction_duration: 604800,       // 7 天
  extension_duration: 600,        // 10 分钟
  extension_threshold: 300,       // 5 分钟
}

8.5 指令列表

8.6 收益分配规则

8.7 后端集成状态（2026-01-16）

API 端点：

Open API 端点 (/v1/auction-solana):

九、Level Verifier 合约

9.1 基本信息

9.2 已初始化账户（2026-01-16）

9.3 PDA Seeds

const VERIFIER_CONFIG_SEED = "verifier_config";
const USER_PROFILE_SEED = "user_profile";
const MINING_RECORD_SEED = "mining_record";

9.4 初始化参数

{
  territory_nft_program: "ipYLo2aitVyNXGzCgpiaKKA2JLvtbBvMHiV7qKZTPVZ",  // Territory NFT 合约
  mcc_token_program: "FDRy2jpKqXD5pp8Xj2arEbEm78nCEcRnKCmGxBTiFWxr",     // MCC Token 合约
}

9.5 指令列表

9.6 用户级别体系

详见 user-levels.md

9.7 后端集成 (2026-01-16 完成)

详见 Level-Verifier后端集成方案.md

服务版本:

API 端点 (organization-service):

CronJob: k8s/level-sync-cronjob.yaml

• 执行时间: UTC 00:20 (每日)
• 功能: 记录铸造日、检查降级、同步等级

十、Fragment 合约

10.1 基本信息

10.2 已初始化账户（2026-01-16）

10.3 PDA Seeds

const FRAGMENT_CONFIG_SEED = "fragment_config";
const FRAGMENT_VAULT_SEED = "fragment_vault";
const FRAGMENT_MINT_SEED = "fragment_mint";
const BUYOUT_SEED = "buyout";
const BUYOUT_VAULT_SEED = "buyout_vault";

10.4 初始化参数（默认值）

{
  min_fragments: 100,            // 最小碎片数量
  max_fragments: 10000,          // 最大碎片数量
  buyout_duration: 604800,       // 买断期限: 7天
}

10.5 指令列表

10.6 碎片化流程

10.7 买断机制

10.8 后端集成状态（2026-01-16）

API 端点：

Open API 端点 (/v1/fragment):

十一、Reincarnation 合约（轮回/回购）

2026-02-02 迁移: MCC/MCD 切换到 SPL Token，Vault 已重新初始化，使用 InterfaceAccount 和 TokenInterface 支持双标准

2026-01-30 升级: 添加 USDT 铸造支持，所有稳定币视为等价 (1 USDC = 1 USDT = 1 USD)

2026-01-29 主网部署: 合约已部署到主网，Pool 和 Vaults 已初始化完成

2026-01-20 升级: 新增 execute_mining 和 execute_monthly_cycle 指令，实现铸造分发和月度轮回功能

11.1 基本信息

11.1.1 已初始化账户 (主网)

2026-01-30 更新: 添加 USDT Vault 支持

2026-01-29 主网部署完成: Pool 和所有 Vaults 已初始化。

11.1.2 支持的稳定币 (2026-01-30 新增)

设计原则: 所有稳定币视为等价 (1 USDC = 1 USDT = 1 USD)，base_price 代表 MCC 的美元价格

11.1.3 初始化参数 (主网)

11.1.4 硬编码创世地址 (constants.rs - 主网)

2026-02-02 更新: MCC/MCD 切换到 SPL Token + Metaplex，Genesis ATA 地址已更新

安全设计: 创世地址硬编码在合约常量中，编译后不可修改，防止资金被转移到错误地址

11.2 功能概述

轮回合约（Reincarnation）是 MCC 回购协议的链上实现：

• 核心功能: 用户使用 MCC 换取 USDC（回购）
• 回购价格: base_price × 1.05（+5% 溢价）
• 价格来源: 预言机服务（Oracle）
• MCC 处理: 回购的 MCC 进入 burn vault，后续可销毁

11.2.1 价格架构

价格数据流向:

1. 价格来源层: 市场价格 (Pyth/Raydium) [优先级1] / 管理员价格 (Open API) [优先级2]
2. 预言机服务 (每4小时): 计算 30天 x 4小时收盘价均值 (180数据点)，调用 contract.update_price(base_price)
3. Reincarnation 合约 (价格唯一真实来源): 存储 base_price, premium_bps=500 (5%)，计算 buyback_price = base_price x 1.05
4. 下游消费者:
   • 数据库缓存 (每小时同步): 用途为前端展示，非交易用途
   • 用户回购 (x402实时): 直接从合约读取价格，钱包签名执行交易

核心原则:

1. 合约是价格的唯一真实来源 (Single Source of Truth)
2. 轮回合约不关心价格来源，只认预言机
3. 用户交易从合约读取价格，不从数据库

预言机价格来源优先级:

更新频率:

11.3 PDA Seeds

const REINCARNATION_POOL_SEED = "reincarnation_pool";
const USDC_VAULT_SEED = "usdc_vault";
const MCC_BURN_VAULT_SEED = "mcc_burn_vault";
const BUYBACK_RECORD_SEED = "buyback_record";

11.4 指令列表

11.4.1 execute_mining 指令详情

用途: 执行铸造 MCC/MCD 分发

分配比例 (50-10-10-30):

• 50% MCC → 用户外部钱包 ATA
• 10% MCC → Team Vault
• 10% MCC → 4级政务官代管钱包 (4%+3%+2%+1%)
• 30% MCD → Station Vault

MCC 分发目标地址 (Mainnet - 2026-02-02 SPL Token 更新):

注意: 4级政务官使用独立代管钱包，便于未来政务官拍卖后资金追溯和转移。

首次拍卖收款钱包 (2026-01-24 新增):

账户参数:

pub struct ExecuteMining<'info> {
    pub authority: Signer<'info>,           // Genesis Authority 签名
    pub reincarnation_pool: Account<'info>, // Pool PDA
    pub user_mcc_account: Account<'info>,   // 用户外部钱包 ATA
    pub team_vault: Account<'info>,         // Team Vault
    pub magistrate_pool: Account<'info>,    // Magistrate Pool
    pub station_vault: Account<'info>,      // Station MCD Vault
    pub mcc_genesis_ata: Account<'info>,    // MCC 创世 ATA
    pub mcd_genesis_pool: Account<'info>,   // MCD 创世池
    pub token_program: Program<'info>,
}

11.4.2 execute_monthly_cycle 指令详情

用途: 月度轮回 - 将 MCC/MCD Vault 中的余额转回创世地址

执行条件:

• 只有 authority 可以调用
• 合约内校验：只允许每月 1 日执行
• 防重放：检查距上次执行是否超过 25 天

CronJob: k8s/monthly-cycle-cronjob.yaml

• Schedule: "30 0 1 * *" (每月 1 日 UTC 00:30)

安全保障:

11.5 回购流程

11.6 参数配置（默认值）

注意: 以下是合约默认值，主网实际初始化值请参见 11.1.2 初始化参数 (主网)

11.6.1 ReincarnationPool 结构体解析（重要！）

⚠️ 2026-01-29 修复: Anchor String 使用 4字节长度 + 实际内容，不是固定 32 字节！

ReincarnationPool 结构体布局:

正确的 Python 解析示例:

offset = 8  # 跳过 discriminator

# name: Anchor String = 4字节长度 + 实际内容
name_len = struct.unpack_from('<I', raw, offset)[0]
offset += 4
pool_name = raw[offset:offset + name_len].decode('utf-8')
offset += name_len  # ✅ 只跳过实际长度，不是固定 32 字节！

# 7 个 Pubkeys
offset += 224

# base_price, premium_bps
base_price = struct.unpack_from('<Q', raw, offset)[0]
offset += 8
premium_bps = struct.unpack_from('<Q', raw, offset)[0]
offset += 8

# price_updated_at - 不要漏掉！
price_updated_at = struct.unpack_from('<q', raw, offset)[0]
offset += 8

# paused - 不要漏掉！
paused = raw[offset] != 0
offset += 1

# daily_limit
daily_limit = struct.unpack_from('<Q', raw, offset)[0]

常见错误:

11.7 Token 地址 (2026-02-02 SPL Token + Metaplex 升级)

重要: MCC/MCD 已切换到 SPL Token + Metaplex Metadata，Solscan/钱包完美支持

SPL Token + Metaplex 特性:

• MCC: 供应量 10 亿，名称 "Microcosm Coin"，符号 "MCC"
• MCD: 供应量 100 亿，名称 "Microcosm Dollar"，符号 "MCD"
• MCC Mint Authority: 已放弃 (None)，MCD Mint Authority: 保留 (MCWe3gEYqTjRCShEkhqbMXhcR4xP2dz29gurSpLbk4A)
• Metadata: 通过 Metaplex Token Metadata V3 管理 (name/symbol/uri)

11.8 部署步骤

cd solana-contracts/reincarnation

# 1. 安装依赖
yarn install

# 2. 构建合约
anchor build

# 3. 获取 Program ID
solana address -k target/deploy/reincarnation-keypair.json

# 4. 更新 Anchor.toml 和 lib.rs 中的 Program ID

# 5. 重新构建
anchor build

# 6. 部署到 Devnet
anchor deploy --provider.cluster devnet

# 7. 运行初始化脚本
yarn init

11.9 集成状态（2026-01-20 更新）

前端集成: ✅ 已完成（使用 Solana Wallet Adapter 直接调用链上合约）

后端集成: ✅ 已完成 (2026-01-20)

后端关键功能:

• execute_mining() - 执行链上 MCC/MCD 分发
• execute_monthly_cycle() - 执行月度轮回
• get_pool_info() - 获取轮回池状态

x402 非托管铸造流程:

1. 用户 USDC 支付是独立交易（用户签名）
2. 后端验证链上交易
3. 后端调用 execute_mining（只需 authority 签名）
4. 链上分发 MCC/MCD (50-10-10-30)

x402 非托管回购流程:

• 回购操作使用 x402 非托管支付协议
• 用户钱包直接与链上合约交互，平台不托管用户资金
• 前端使用 Solana Wallet Adapter（支持 Phantom、Solflare 等）
• execute_buyback 指令将用户 MCC 转入 MCC Vault，从 USDC Vault 支付 USDC 给用户

十二、合约部署状态汇总

🎉 2026-01-29 主网部署完成: 所有 8 个合约已部署到主网！

Token Mint 汇总 (主网) - 2026-02-02 SPL Token + Metaplex 升级

版本历史

Token-2022 → SPL Token 迁移记录 (2026-02-02)

重要: Token-2022 版本已废弃，以下旧地址仅作记录，不再使用！

废弃原因:

• Token-2022 的 Metaplex Metadata 支持不完善
• Solscan/钱包显示 Logo/Name 需要 Metaplex，而 Metaplex 不支持 Token-2022
• 切换到 SPL Token + Metaplex Metadata 标准

旧 Token-2022 地址（已废弃）:

新 SPL Token 地址（当前使用）:

SOL 回收:

• 详见 docs/SOL回收指南.md
• 总计回收约 3.36 SOL（Program Buffer + 旧 ATA 租金）

⚠️⚠️⚠️ ATA 地址计算问题 (2026-02-02 重要修复) ⚠️⚠️⚠️

核心问题: 不同的 Token Program ID 会导致相同的 owner + mint 计算出完全不同的 ATA 地址！

ATA 地址计算公式:

# ATA = PDA([owner, token_program, mint], ATA_PROGRAM_ID)
# 关键：token_program 参与 seeds 计算！

# SPL Token ATA (正确)
ata_spl = get_associated_token_address(mint, owner, TOKEN_PROGRAM_ID)
# TOKEN_PROGRAM_ID = TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA

# Token-2022 ATA (错误 - 会计算出不同地址)
ata_2022 = get_associated_token_address(mint, owner, TOKEN_2022_PROGRAM_ID)
# TOKEN_2022_PROGRAM_ID = TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb

实际案例 - Station 1 MCD Vault:

后端修复 (2026-02-02):

修复代码示例:

def get_associated_token_address(mint: Pubkey, owner: Pubkey, token_program: Pubkey = None) -> Pubkey:
    # ⚠️ 关键：默认使用 SPL Token (2026-02-02 切换到 SPL Token + Metaplex)
    if token_program is None:
        token_program = TOKEN_PROGRAM_ID  # 不是 TOKEN_2022_PROGRAM_ID！

    seeds = [bytes(owner), bytes(token_program), bytes(mint)]
    return Pubkey.find_program_address(seeds, ASSOCIATED_TOKEN_PROGRAM_ID)[0]

开发注意事项:

1. MCC/MCD 使用 SPL Token，所有 ATA 计算必须使用 TOKEN_PROGRAM_ID
2. 不要假设 ATA 地址在不同 Token Program 间相同 - 它们完全不同
3. 链上交易中的 token_program AccountMeta 必须与 ATA 计算时使用的一致
4. 后端代码中搜索 TOKEN_2022_PROGRAM_ID，确保所有涉及 MCC/MCD 的地方都已切换到 TOKEN_PROGRAM_ID

十二、前端页面集成状态

12.1 集成概览

12.2 页面修复详情

12.3 新增前端文件

12.4 x402 API 类型定义

新增类型 (lib/types/api.ts):

• MiningRequest - 铸造请求
• MiningRequestResponse - 铸造请求响应
• PaymentConfirmRequest - 支付确认请求
• PaymentConfirmResponse - 支付确认响应
• MiningRatioInfo - 铸造产值比例信息

新增 API 函数 (lib/api/services.ts):

• createMiningRequest() - 创建铸造请求
• confirmMiningPayment() - 确认铸造支付
• getMiningRatio() - 获取产值比例
• getMiningRequestStatus() - 获取请求状态

十三、Redis 缓存架构 (2026-01-20 新增)

重要: 链上数据不直接从 Solana RPC 获取，而是通过 Redis 缓存层优化性能。

13.1 架构概述

blockchain-service 实现了工业标准的 Cache-Aside Pattern（旁路缓存模式）。

数据流: Frontend (Portal) --> blockchain-service --> Redis Cache (命中时直接返回) --> 若 cache miss 则查询 Solana RPC (Helius)

13.2 缓存 API 端点

13.3 缓存 Key 格式

# 钱包全量余额
f"blockchain:balance:all:{wallet_address}"

# MCC 单独余额
f"blockchain:balance:mcc:{wallet_address}"

# MCD 单独余额
f"blockchain:balance:mcd:{wallet_address}"

# 轮回池状态
"blockchain:pool:reincarnation"

13.4 缓存策略

13.5 前端集成

// 获取钱包余额（自动缓存）
const balance = await fetch(`/api/blockchain/balance/wallet/${address}`)

// 强制刷新余额
const fresh = await fetch(`/api/blockchain/balance/wallet/${address}?force=true`)

// 交易后失效缓存
await fetch(`/api/blockchain/balance/invalidate/${address}`, { method: 'POST' })

13.6 代码位置

13.7 Token 精度

此文档是 Solana 合约的权威定义，其他文档应引用而非重复定义。