Back to Details

chess-payout-claims

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Chess Payout Claims Integration Skill

Chess 支付申领集成Skill

This skill is written for teams integrating with deployed contracts, not for editing contract source code.
本Skill面向与已部署合约集成的团队，而非用于编辑合约源代码。

Scope

适用范围

Use this skill when you need to:
  • Integrate a MiniPay app with signed claim endpoints
  • Build backend signing for daily check-ins and leaderboard rewards
  • Operate token funding and withdrawals safely
  • Integrate platform revenue collection and treasury sweeps
  • Monitor claim and treasury events
当你需要以下操作时，可使用本Skill：
  • 将MiniPay应用与签名申领端点集成
  • 为每日签到和排行榜奖励构建后端签名机制
  • 安全地进行代币资金注入与提取操作
  • 集成平台营收归集与国库资金归集功能
  • 监控申领与国库相关事件

Contract Roles

合约角色

Claims Contract

申领合约

The claims contract has two user claim paths:
  • Daily check-in claims: fixed payout, one per user per day, global daily cap
  • Leaderboard claims: variable payout, one-time claim ID
It verifies backend-issued EIP-712 signatures and transfers ERC20 payouts to users.
Nonce model:
  • Check-in claims use checkInNonces(user)
  • Leaderboard claims use leaderboardNonces(user)
  • Nonce spaces are independent per claim type
申领合约提供两种用户申领路径：
  • 每日签到申领：固定支付额度，每位用户每日限领一次，设有全局每日上限
  • 排行榜申领：支付额度可变，使用一次性申领ID
该合约会验证后端签发的EIP-712签名，并将ERC20代币支付给用户。
Nonce机制：
  • 签到申领使用checkInNonces(user)
  • 排行榜申领使用leaderboardNonces(user)
  • 不同申领类型的Nonce空间相互独立

Sponsored Transaction Model

赞助交易机制

Claims are designed for gasless execution:
  • User intent is proven by backend-issued EIP-712 signature
  • A relayer submits the on-chain transaction and pays gas
  • Contract authorization is based on signed payload fields, not caller identity
Claim methods accept an explicit user argument:
  • claimDailyCheckIn(address user, uint256 day, uint256 nonce, uint256 deadline, bytes signature)
  • claimLeaderboardPayout(address user, uint256 amount, bytes32 claimId, uint256 nonce, uint256 deadline, bytes signature)
The relayer address is emitted in claim events for analytics and reconciliation.
申领流程支持无Gas费执行：
  • 用户意图通过后端签发的EIP-712签名验证
  • 由中继器提交链上交易并支付Gas费
  • 合约授权基于签名的负载字段，而非调用者身份
申领方法接受明确的用户参数：
  • claimDailyCheckIn(address user, uint256 day, uint256 nonce, uint256 deadline, bytes signature)
  • claimLeaderboardPayout(address user, uint256 amount, bytes32 claimId, uint256 nonce, uint256 deadline, bytes signature)
申领事件中会包含中继器地址，用于分析与对账。

Revenue Collector Contract

营收归集合约

The revenue collector contract accepts ERC20 deposits and supports owner-managed withdrawals.
Typical usage:
  • Application collects token revenue into collector contract
  • Operator sweeps funds to treasury wallet
  • Treasury funds claims contract for user payouts
营收归集合约接收ERC20代币存款，并支持由所有者管理的提取操作。
典型使用流程：
  • 应用将代币营收归集至归集合约
  • 运营人员将资金归集至国库钱包
  • 为国库资金提供申领合约的用户支付资金

Integration Prerequisites

集成前置条件

Collect and store these values in your backend config:
  • claimsContract: deployed claims contract address
  • revenueCollectorContract: deployed revenue collector address
  • payoutToken: ERC20 token address used for payouts and/or revenue
  • chainId: Celo Mainnet 42220 or Celo Sepolia 11142220
  • serverSignerPrivateKey: backend signing key for claims
  • relayerKeyOrService: key/service used to submit sponsored transactions
  • ownerOperatorKey: privileged key for admin operations
收集并在后端配置中存储以下值：
  • claimsContract：已部署的申领合约地址
  • revenueCollectorContract：已部署的营收归集合约地址
  • payoutToken：用于支付和/或营收的ERC20代币地址
  • chainId：Celo主网42220或Celo Sepolia测试网11142220
  • serverSignerPrivateKey：用于申领的后端签名密钥
  • relayerKeyOrService：用于提交赞助交易的密钥/服务
  • ownerOperatorKey：用于管理员操作的特权密钥

Daily Check-In Flow

每日签到流程

  1. Backend computes the current day as Unix days: floor(timestamp / 86400).
  2. Backend reads on-chain checkInNonces(user) from the claims contract.
  3. Backend creates a payload with user, day, nonce, deadline.
  4. Backend signs the payload with EIP-712 typed data.
  5. Frontend sends signed payload to backend or relayer service.
  6. Relayer submits on-chain daily claim transaction.
  7. App listens for claim event confirmation and updates UI.
Required payload fields:
  • user: claimant address
  • day: UTC day number
  • nonce: exact current on-chain checkInNonces(user)
  • deadline: Unix timestamp expiry
  1. 后端将当前日期计算为Unix天数：floor(timestamp / 86400)。
  2. 后端从申领合约读取链上的checkInNonces(user)。
  3. 后端创建包含user、day、nonce、deadline的负载。
  4. 后端使用EIP-712类型数据对负载进行签名。
  5. 前端将签名后的负载发送至后端或中继器服务。
  6. 中继器提交链上每日申领交易。
  7. 应用监听申领事件确认并更新UI。
必需的负载字段：
  • user：申领人地址
  • day：UTC天数
  • nonce：当前链上checkInNonces(user)的准确值
  • deadline：Unix时间戳形式的过期时间

Leaderboard Claim Flow

排行榜申领流程

  1. Backend computes user reward amount and claim ID.
  2. Backend reads on-chain leaderboardNonces(user) from the claims contract.
  3. Backend creates payload with user, amount, claimId, nonce, deadline.
  4. Backend signs with EIP-712 typed data.
  5. Relayer submits on-chain leaderboard claim.
  6. Backend marks claim ID as consumed in off-chain records after success.
Required payload fields:
  • user: claimant address
  • amount: payout token amount in base units
  • claimId: unique identifier for payout record
  • nonce: exact current on-chain leaderboardNonces(user)
  • deadline: Unix timestamp expiry
Nonce notes:
  • checkInNonces and leaderboardNonces are separate mappings
  • Daily check-ins increment checkInNonces(user) only
  • Leaderboard claims increment leaderboardNonces(user) only
  • Signatures must be generated from the correct nonce domain for the claim type
  1. 后端计算用户奖励金额和申领ID。
  2. 后端从申领合约读取链上的leaderboardNonces(user)。
  3. 后端创建包含user、amount、claimId、nonce、deadline的负载。
  4. 后端使用EIP-712类型数据进行签名。
  5. 中继器提交链上排行榜申领交易。
  6. 成功后，后端在链下记录中将该申领ID标记为已使用。
必需的负载字段：
  • user：申领人地址
  • amount：支付代币的基础单位数量
  • claimId：支付记录的唯一标识符
  • nonce：当前链上leaderboardNonces(user)的准确值
  • deadline：Unix时间戳形式的过期时间
Nonce注意事项：
  • checkInNonces和leaderboardNonces是独立的映射表
  • 每日签到仅会递增checkInNonces(user)
  • 排行榜申领仅会递增leaderboardNonces(user)
  • 签名必须针对对应申领类型的正确Nonce域生成

Revenue Collector Flow

营收归集流程

Recommended operations model:
  1. Revenue intake: user approves token allowance, then calls deposit(token, amount).
  2. Balance checks: operator reads tokenBalance(token).
  3. Treasury routing: owner calls withdrawAllToTreasury(token) on schedule.
  4. Controlled payouts: owner can use withdraw(token, to, amount) for manual transfers.
  5. Treasury updates: owner rotates treasury using setTreasury(newTreasury).
Operational guardrails:
  • Enforce allowed token list in backend and app UI
  • Require multisig ownership for production treasury control
  • Emit and index deposit/withdraw events for accounting
推荐操作模式：
  1. 营收归集：用户批准代币额度，然后调用deposit(token, amount)。
  2. 余额检查：运营人员读取tokenBalance(token)。
  3. 国库划转：所有者定期调用withdrawAllToTreasury(token)。
  4. 受控支付：所有者可使用withdraw(token, to, amount)进行手动转账。
  5. 国库更新：所有者使用setTreasury(newTreasury)更换国库地址。
操作防护措施：
  • 在后端和应用UI中强制执行允许的代币列表
  • 生产环境中国库控制需使用多签所有权
  • 触发并索引存款/提取事件用于会计核算

EIP-712 Signing Reference

EIP-712签名参考

Domain values must match deployment exactly:
  • name: MiniPayPayoutClaims
  • version: 1
  • chainId: active chain ID
  • verifyingContract: claims contract address
Typed data definitions:
  • CheckInClaim(address user,uint256 day,uint256 nonce,uint256 deadline)
  • LeaderboardClaim(address user,uint256 amount,bytes32 claimId,uint256 nonce,uint256 deadline)
域值必须与部署完全匹配：
  • name: MiniPayPayoutClaims
  • version: 1
  • chainId: 当前链ID
  • verifyingContract: 申领合约地址
类型数据定义：
  • CheckInClaim(address user,uint256 day,uint256 nonce,uint256 deadline)
  • LeaderboardClaim(address user,uint256 amount,bytes32 claimId,uint256 nonce,uint256 deadline)

Error Handling Expectations

错误处理预期

Client and backend should handle these contract reverts as product states:
  • SignatureExpired: claim link/request expired
  • InvalidSigner: backend signature mismatch or wrong signer key
  • InvalidNonce: signed nonce does not match current checkInNonces(user) or leaderboardNonces(user)
  • AlreadyClaimedToday: daily claim already used by this user
  • DailyLimitReached: first-N daily cap exhausted
  • LeaderboardClaimAlreadyUsed: payout already consumed
  • DigestAlreadyUsed: typed-data digest replay attempted
  • InsufficientContractBalance: claims contract needs funding
客户端和后端应将这些合约回退视为产品状态进行处理：
  • SignatureExpired：申领链接/请求已过期
  • InvalidSigner：后端签名不匹配或签名密钥错误
  • InvalidNonce：签名的Nonce与当前checkInNonces(user)或leaderboardNonces(user)不匹配
  • AlreadyClaimedToday：该用户今日已完成申领
  • DailyLimitReached：每日前N名的上限已耗尽
  • LeaderboardClaimAlreadyUsed：该支付已被领取
  • DigestAlreadyUsed：尝试重放类型数据摘要
  • InsufficientContractBalance：申领合约需要注入资金

Security Expectations for Integrators

集成方安全预期

  • Keep signing key in KMS/HSM and never in frontend apps
  • Use short signature validity windows
  • Use unique claim IDs and always source nonce from the correct on-chain nonce mapping
  • Rotate signer key periodically and on suspicion
  • Apply relayer rate limits and idempotency controls
  • Monitor unusually large leaderboard amounts
  • Require multisig for owner-level treasury actions
  • 将签名密钥存储在KMS/HSM中，绝不可放在前端应用里
  • 使用较短的签名有效期窗口
  • 使用唯一的申领ID，并始终从正确的链上Nonce映射获取Nonce
  • 定期轮换签名密钥，如有疑虑立即轮换
  • 对中继器应用速率限制和幂等性控制
  • 监控异常大额的排行榜奖励金额
  • 所有者级别的国库操作需使用多签

Read API Notes

读取API说明

  • The payout token immutable getter is PAYOUT_TOKEN() (uppercase) in the current claims contract version.
  • 在当前版本的申领合约中，支付代币的不可变获取方法为PAYOUT_TOKEN()（大写）。

Code Examples

代码示例

Use these bundled examples for integration templates:
  • Typed-data signing example: scripts/sign-typed-data.mjs
  • Claim submission and collector operations with cast: scripts/cast-operations.sh
These files are templates for integrators and should be adapted to your backend policies and deployment addresses.
使用以下附带的示例作为集成模板：
  • 类型数据签名示例：scripts/sign-typed-data.mjs
  • 使用cast进行申领提交和归集合约操作的示例：scripts/cast-operations.sh
这些文件是为集成方提供的模板，需根据你的后端策略和部署地址进行调整。

Event Monitoring Checklist

事件监控清单

Index these events for product and accounting systems:
  • Daily check-in claim event (includes relayer)
  • Leaderboard claim event (includes relayer)
  • Signer update and payout parameter update events
  • Revenue deposit and withdrawal events
  • Treasury address update event
为产品和会计系统索引以下事件：
  • 每日签到申领事件（包含中继器）
  • 排行榜申领事件（包含中继器）
  • 签名者更新和支付参数更新事件
  • 营收存款和提取事件
  • 国库地址更新事件

Quick Validation Steps

快速验证步骤

After integration is wired:
  1. Generate a short-lived check-in signature and submit through relayer.
  2. Verify second same-day claim fails.
  3. Submit with stale nonce and verify InvalidNonce.
  4. Submit a leaderboard claim, then attempt claim ID replay.
  5. Confirm claim events include user and relayer addresses.
  6. Confirm revenue deposit and treasury sweep emit expected events.
  7. Simulate low-balance claims contract and verify graceful error handling.
集成完成后：
  1. 生成一个短期有效的签到签名，并通过中继器提交。
  2. 验证同一用户当日第二次申领会失败。
  3. 使用过期的Nonce提交，验证会触发InvalidNonce错误。
  4. 提交一次排行榜申领，然后尝试重放该申领ID。
  5. 确认申领事件中包含用户和中继器地址。
  6. 确认营收存款和国库归集操作会触发预期事件。
  7. 模拟申领合约余额不足的情况，验证错误处理是否优雅。