返佣系统概述
ZTDX 返佣系统允许用户通过邀请交易者加入平台来赚取佣金。推荐人创建唯一的邀请码，分享给交易者，并从被推荐人产生的交易手续费中赚取一定比例的返佣。
工作原理
推荐人（Referrer）
├── 创建推荐码（POST /referral/codes）
└── 将推荐码分享给交易者
交易者（Referee）
├── 绑定推荐码（POST /referral/bind）
└── 每次交易产生手续费 → 推荐人获得返佣
返佣流程
交易者执行交易
→ 后端计算返佣（trade_fee × tier_rate）
→ 写入 referral_earnings（链下记录）
→ 每小时批量同步至链上合约（batchSyncRebates）
推荐人提现（两种方式）：
A. 链下：POST /referral/claim → 即时到账至账户余额
B. 链上：POST /referral/on-chain/claim-signature → 获取签名后调用合约 claimRebate
等级体系
返佣比例由推荐人等级决定，升级条件为邀请人数 AND 被推荐人累计交易量，两个条件必须同时满足：
| 等级 | 名称 | 返佣比例 | BPS | ≥ 邀请人数 | ≥ 被推荐人累计交易量 |
|---|---|---|---|---|---|
| 0 | Starter | 10% | 1000 | 1 | $1,000 |
| 1 | Bronze | 12% | 1200 | 5 | $10,000 |
| 2 | Silver | 17% | 1700 | 20 | $100,000 |
| 3 | Gold | 22% | 2200 | 50 | $500,000 |
| 4 | Diamond | 25% | 2500 | 100 | $2,000,000 |
升级条件为 AND 关系，两个条件必须同时满足。未达 Starter 门槛的用户无有效等级。 等级由后端根据被推荐人实时交易情况自动重算更新。
智能合约
返佣系统在 Arbitrum 上部署了两个合约：
| 合约 | 功能 |
|---|---|
ReferralStorage | 存储推荐码映射、推荐关系和等级信息 |
ReferralRebate | 记录链上累计返佣、签发 Claim 签名、处理链上提现 |
合约地址可通过 GET /referral/on-chain/operator-status 获取。
认证方式
所有受保护接口需要 JWT Bearer Token：
Authorization: Bearer <token>
Token 通过 EIP-712 登录流程获取，详见认证文档。
API 接口列表
公开接口（无需认证）
| 方法 | 接口 | 说明 |
|---|---|---|
| GET | /referral/leaderboard | 返佣排行榜（前 N 名） |
| GET | /referral/on-chain/user-rebate/:address | 查询用户链上返佣信息 |
| GET | /referral/on-chain/referral-info/:address | 查询交易者链上推荐配置 |
| GET | /referral/on-chain/claimed/:address | 查询链上已领取金额 |
| GET | /referral/on-chain/operator-status | 查询后端 Signer 运营状态 |
受保护接口（需 JWT）
| 方法 | 接口 | 说明 |
|---|---|---|
| POST | /referral/codes | 创建推荐码 |
| POST | /referral/bind | 绑定推荐码 |
| POST | /referral/unbind | 解绑推荐码 |
| GET | /referral/status | 查询推荐状态（推荐人和被推荐人双向） |
| GET | /referral/dashboard | 获取收益仪表盘 |
| GET | /referral/logs | 查询操作日志 |
| POST | /referral/claim | 领取链下返佣 |
| POST | /referral/on-chain/claim-signature | 生成链上 Claim 签名 |
EIP-712 签名类型
| 操作 | TypeHash |
|---|---|
| 创建推荐码 | CreateReferralCode(address wallet,uint256 timestamp) |
| 绑定推荐码 | BindReferralCode(address wallet,string code,uint256 timestamp) |
| 解绑推荐码 | UnbindReferralCode(address wallet,uint256 timestamp) |
EIP-712 Domain 可从 GET /auth/nonce/:address → typed_data.domain 获取。