合约方法模块
合约方法模块汇总了前端与后端常用的链上调用入口，包含方法签名、参数说明以及返回数据结构，便于在集成钱包或后台任务时快速查阅。
方法清单
deposit
签名: function deposit(uint256 roundId, address referrer) payable
说明: 向指定轮次存入 ETH，允许携带推荐人地址。调用方需确保 msg.value 等于本次参与的金额。
请求字段
| Name | Required | Type | Description |
|---|---|---|---|
| round_id | Yes | number | 开放状态的轮次 ID。 |
| referrer | No | string | 推荐人地址；如果为空地址则不记录推荐关系。 |
返回字段
无返回值，成功会触发 MultipleRoundsDeposited 或 Deposited 等事件以便追踪结果。
batchDeposit
签名: function batchDeposit(uint256 startingRoundId, uint256[] amounts, address referrer) payable
说明: 一次性向连续轮次批量存入 ETH，适合预购多个回合。msg.value 需要等于 amounts 数组之和。
请求字段
| Name | Required | Type | Description |
|---|---|---|---|
| starting_round_id | Yes | number | 第一笔存入的轮次 ID，必须是开放状态。 |
| amounts | Yes | number[] | 每个轮次的存入金额（wei）；数组长度等于参与轮次数。 |
| referrer | No | string | 推荐人地址；为空地址时不记录推荐关系。 |
返回字段
方法无直接返回值；结果可通过 MultipleRoundsDeposited、Rollover 等事件确认。
drawWinner
签名: function drawWinner()
说明: 触发当前可开奖轮次的开奖流程，内部会请求随机数并在完成后结算。
请求字段
| Name | Required | Type | Description |
|---|---|---|---|
| - | - | - | 无需传入参数。 |
返回字段
无直接返回值；开奖流程完成后会触发 RandomnessRequested、PrizeAwarded 等事件。
withdraw
签名: function withdraw()
说明: 提取调用者在合约中的可取余额，通常来自退款或中奖奖励。
请求字段
| Name | Required | Type | Description |
|---|---|---|---|
| - | - | - | 无需传入参数。 |
返回字段
无直接返回值；余额提取成功后会触发 PrizeAwarded 或 ReferrerRewarded 等事件以供追踪。
getWithdrawableBalance
签名: function getWithdrawableBalance(address depositor) external view returns (uint256)
说明: 查询指定地址当前可提现的余额（wei），常用于展示用户可提额度或在调用 withdraw 前进行校验。
请求字段
| Name | Required | Type | Description |
|---|---|---|---|
| depositor | Yes | string | 需查询的用户地址。 |
返回字段
| Name | Required | Type | Description |
|---|---|---|---|
| withdrawable_balance | Yes | string | 可立即提取的余额（wei）。 |
rollover
签名: function rollover(uint256 roundId, uint256 rolloverAmount)
说明: 将调用者在合约中的余额滚入指定轮次，便于继续参与下一轮。
请求字段
| Name | Required | Type | Description |
|---|---|---|---|
| round_id | Yes | number | 目标轮次 ID。 |
| rollover_amount | Yes | string | 要滚入的金额（wei）。 |
返回字段
无直接返回值；滚入成功后会通过 Rollover、RoundStatusUpdated 等事件反映状态。
getRound
签名: function getRound(uint256 roundId) view returns (RoundStatus status, uint40 maximumNumberOfParticipants, uint16 roundProtocolFeeBp, uint40 cutoffTime, uint40 drawnAt, uint40 numberOfParticipants, address winner, uint96 roundValuePerEntry, Deposit[] deposits)
说明: 查询指定轮次的详细状态与参与记录，可在服务端缓存供前端读取。
请求字段
| Name | Required | Type | Description |
|---|---|---|---|
| round_id | Yes | number | 要查询的轮次 ID。 |
返回字段
| Name | Required | Type | Description |
|---|---|---|---|
| status | Yes | RoundStatus | 轮次当前状态。 |
| maximum_number_of_participants | Yes | number | 轮次允许的最大参与人数。 |
| round_protocol_fee_bp | Yes | number | 轮次使用的协议费基点。 |
| cutoff_time | Yes | number | 存款截止时间戳（秒）。 |
| drawn_at | No | number | 开奖完成时间戳（秒），若尚未开奖则为 0。 |
| number_of_participants | Yes | number | 当前参与人数。 |
| winner | No | string | 获胜者地址，开奖前为零地址。 |
| round_value_per_entry | Yes | string | 每次参与的金额（wei）。 |
| deposits | Yes | Deposit[] | 轮次的存款明细数组。 |
相关类型
RoundStatus 枚举
| Name | Type | Description |
|---|---|---|
| none | string | 轮次不存在。 |
| open | string | 正在开放，允许新的存款。 |
| drawing | string | 开奖中，等待随机数完成。 |
| drawn | string | 已开奖并记录结果。 |
| cancelled | string | 被取消，后续等待退款。 |
Deposit 对象
| Name | Type | Description |
|---|---|---|
| amount | string | 存款金额（wei）。 |
| depositor | string | 存款人地址。 |
| current_entry_index | number | 存款对应的参与索引，用于计算抽奖份额。 |
集成建议
- 带
payable的方法必须通过钱包或后端签名交易，并设置合适的 gas 限制。 nonReentrant和whenNotPaused修饰器意味着方法在合约暂停或重入保护触发时会 revert，调用前应拉取最新OutflowAllowedUpdated、RoundStatusUpdated等事件做前置校验。- 推荐在服务端缓存
getRound返回结果，并通过事件监听实现增量更新，降低链上请求次数。