理财服务概述 (Earn Service)

AXBlade 理财服务提供定期理财产品，用户可通过链上智能合约申购，使用 ERC-1155 NFT 进行确权。

核心特性

产品类型: 定期理财，7天一期（可配置）
年化收益率: 130%-250%（显示 3-5% 期限利率）
额度限制: 总额度 20 万 U，个人限额可配置
申购方式: 链上智能合约，ERC-1155 NFT 确权
到期处理: 自动赎回本金+利息，不支持提前赎回

合约地址

Testnet (Arbitrum Sepolia)

合约	地址	说明
AXBladeEarn v3	`0x26763848400E108bd3095e548a6de2D01dadDCaB`	✅ 当前使用 (v3)
AXBladeEarn v2	`0xe97ec2cb6B735d791ee253f86343782d41F6FA0a`	旧版本 (durationDays)
AXBladeEarn v1	`0xCB97Ea921170718ED8AD076f40Cd868775B912bD`	旧版本
Platform USDT	`0x572E474C3Cf364D085760784F938A1Aa397a8B9b`	平台统一 USDT，用户需授权给 Earn 合约

USDT 授权: 用户申购前需将 USDT (0x572E...) 授权 (approve) 给 Earn 合约 (0x2676...)

v3 版本新特性

特性	说明
durationSeconds	锁定期改为秒，支持灵活时长 (如10分钟、1小时、7天)
动态 APR	`maxAnnualRateBps` 定义上限，实际利率可为 0% ~ max%
actualTotalInterest	`depositReturns(productId, actualTotalInterest)` - 指定实际利息
比例分配	用户 claim 时按比例分配实际存入的利息

v2 版本特性 (已保留)

特性	说明
自定义 Product ID	`createProduct(productId, ...)` - ID 由调用者指定
资金取出/存回	`withdrawPrincipal()` / `depositReturns()` - 支持投资运营
多次申购	用户可多次购买同一产品，金额累加

Mainnet (Arbitrum One)

合约	地址	说明
AXBladeEarn	⚠️ 待部署	-

Chain ID: 421614 (Sepolia) / 42161 (Mainnet) RPC URL: https://sepolia-rollup.arbitrum.io/rpc 合约源码: https://github.com/AXBladeStudio/AXBlade/tree/main/contracts Arbiscan: https://sepolia.arbiscan.io/address/0x26763848400E108bd3095e548a6de2D01dadDCaB

角色配置

角色	地址	说明
ADMIN_ROLE	`0x6538469807e019E05c9ec4Bd158b12afB1DA50F3`	管理员，可创建/取消产品
OPERATOR_ROLE	`0x6538469807e019E05c9ec4Bd158b12afB1DA50F3`	运营者，可开启/结算产品
SIGNER_ROLE	`0xEBB3F1be60Fe1924448ca73F127984DbE9383443`	后端签名者，用于生成申购签名

产品状态流转

已创建 (Created) → 申购中 (Subscribing) → 进行中 (Active) → 已结算 (Settled)
                                              ↓
                                    [可选] withdrawPrincipal() 取出本金到 Treasury
                                              ↓
                                    [必须] depositReturns() 存入本金+利息
                                              ↓
                                         settleProduct()

资金管理: v2 版本支持在 Active 状态下取出本金进行投资，结算前需存回本金+利息

状态	说明
`created`	产品已创建，等待开放申购
`subscribing`	申购期，用户可以申购
`active`	申购结束，产品运行中
`settled`	已结算，用户可领取本息
`cancelled`	已取消（紧急情况）

NFT 生命周期

Mint (申购成功) → Active (持有中) → Matured (到期可赎回) → Burned (已销毁)

状态	说明
`active`	申购成功，持有中
`matured`	产品到期，可赎回
`burned`	已赎回，NFT 销毁

合约数据结构

为避免 Solidity "stack too deep" 错误，产品数据拆分为三个结构体：

ProductConfig

struct ProductConfig {
    string name;
    uint256 maxAnnualRateBps;    // v3: 最大年化收益率 (BPS, 实际可为 0% ~ max%)
    uint256 durationSeconds;      // v3: 期限秒数 (支持灵活时长)
    uint256 maxPeriodRateBps;     // v3: 最大期限收益率 (自动计算)
    uint256 totalQuota;          // 总额度
    uint256 minAmount;           // 最小申购
    uint256 maxAmountPerUser;    // 个人限额
}

ProductTiming

struct ProductTiming {
    uint256 subscribeStartTime;  // 申购开始时间
    uint256 subscribeEndTime;    // 申购结束时间
    uint256 settleTime;          // 预计结算时间
    uint256 actualSettleTime;    // 实际结算时间
}

ProductStats

struct ProductStats {
    uint256 subscribedAmount;    // 已申购金额
    uint256 totalInterestPaid;   // 已支付利息
    uint256 participantCount;    // 参与人数
    ProductStatus status;        // 产品状态
    address creator;             // 创建者
}

Subscription

struct Subscription {
    uint256 amount;              // 申购金额
    uint256 expectedReturn;      // 预期收益
    uint256 actualReturn;        // 实际收益
    uint256 subscribedAt;        // 申购时间
    bool claimed;                // 是否已领取
}

合约安全特性

Soulbound NFT: 重写 _update() 禁止转让（仅允许 mint/burn）
AccessControl: 角色分离 (ADMIN_ROLE / OPERATOR_ROLE / SIGNER_ROLE)
ReentrancyGuard: 防重入攻击
Pausable: 紧急暂停功能
SafeERC20: 安全代币操作
签名防重放: usedSignatures mapping

API 接口概览

功能	方法	路径	认证
EIP-712 Domain	GET	`/earn/domain`	否
产品列表	GET	`/earn/products`	否
产品详情	GET	`/earn/products/:id`	否
历史表现	GET	`/earn/performance`	否
我的申购	GET	`/earn/subscriptions`	是
准备申购	POST	`/earn/subscribe/prepare`	是

申购流程

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  查看产品  │────▶│ 准备申购  │────▶│ Approve  │────▶│ 链上申购  │
│          │     │ 获取签名  │     │  USDT    │     │ subscribe │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
                      │                                  │
                      ▼                                  ▼
                ┌──────────┐                       ┌──────────┐
                │ EIP-712  │                       │ 获得 NFT  │
                │  签名    │                       │  确权    │
                └──────────┘                       └──────────┘

领取流程

┌──────────┐     ┌──────────┐     ┌──────────┐
│ 产品结算  │────▶│ 调用 claim │────▶│ 销毁 NFT  │
│          │     │  合约     │     │ 获得本息  │
└──────────┘     └──────────┘     └──────────┘

收益计算

期限收益率计算:

期限收益率 = 年化收益率 × (期限天数 / 365)

示例:

年化收益率: 190.36%
期限: 7 天
期限收益率: 190.36% × (7/365) = 3.65%
申购 10,000 USDT，到期获得 10,365 USDT

合约事件

event ProductCreated(uint256 indexed productId, string name, uint256 annualRateBps, uint256 durationDays, uint256 totalQuota);
event ProductStatusChanged(uint256 indexed productId, ProductStatus oldStatus, ProductStatus newStatus);
event Subscribed(uint256 indexed productId, address indexed user, uint256 amount, uint256 expectedReturn);
event ProductSettled(uint256 indexed productId, uint256 totalPrincipal, uint256 totalInterest);
event Claimed(uint256 indexed productId, address indexed user, uint256 principal, uint256 interest);
event TreasuryUpdated(address indexed oldTreasury, address indexed newTreasury);

安全注意事项

签名有效期: 申购签名的 deadline 必须在有效期内
额度限制: 每个用户有最大申购限额
不可提前赎回: 申购后必须等待产品结算才能领取
NFT 不可转让: Soulbound 设计，防止二级市场交易
紧急赎回: 产品取消时可调用 emergencyClaim() 赎回本金

部署状态

Testnet (Arbitrum Sepolia)

组件	状态	说明
后端服务	✅ 运行中	8a27.xyz 测试环境
数据库迁移	✅ 已应用	`0018_earn_service.sql`
Earn API	✅ 可用	https://api.8a27.xyz/api/v1/earn/*
AXBladeEarn v3 合约	✅ 当前使用	`0x26763848400E108bd3095e548a6de2D01dadDCaB`
Platform USDT	✅ 配置完成	`0x572E474C3Cf364D085760784F938A1Aa397a8B9b`

Mainnet (Arbitrum One)

组件	状态
AXBladeEarn 合约	⚠️ 待部署
后端 Earn 服务	⚠️ 待部署

合约部署历史 (Arbitrum Sepolia)

版本	合约地址	USDT	状态
v1 (旧)	`0x00Dc882Ae807BECf0865DFF76f34910e31e24B10`	MockUSDT	已弃用
v2 (旧)	`0xCB97Ea921170718ED8AD076f40Cd868775B912bD`	平台 USDT	已废弃
v2.1 (旧)	`0xe97ec2cb6B735d791ee253f86343782d41F6FA0a`	平台 USDT	已废弃 (durationDays)
v3 (当前)	`0x26763848400E108bd3095e548a6de2D01dadDCaB`	平台 USDT	✅ 当前使用

理财服务概述 (Earn Service)

核心特性​

合约地址​

Testnet (Arbitrum Sepolia)​

v3 版本新特性​

v2 版本特性 (已保留)​

Mainnet (Arbitrum One)​

角色配置​

产品状态流转​

NFT 生命周期​

合约数据结构​

ProductConfig​

ProductTiming​

ProductStats​

Subscription​

合约安全特性​

API 接口概览​

申购流程​

领取流程​

收益计算​

合约事件​

安全注意事项​

部署状态​

Testnet (Arbitrum Sepolia)​

Mainnet (Arbitrum One)​

合约部署历史 (Arbitrum Sepolia)​

核心特性

合约地址

Testnet (Arbitrum Sepolia)

v3 版本新特性

v2 版本特性 (已保留)

Mainnet (Arbitrum One)

角色配置

产品状态流转

NFT 生命周期

合约数据结构

ProductConfig

ProductTiming

ProductStats

Subscription

合约安全特性

API 接口概览

申购流程

领取流程

收益计算

合约事件

安全注意事项

部署状态

Testnet (Arbitrum Sepolia)

Mainnet (Arbitrum One)

合约部署历史 (Arbitrum Sepolia)