合约事件模块

合约事件模块列出了 Pikpok 主合约在运行过程中可能触发的链上事件，方便前端监听链上日志并向用户展示最新状态，也便于后端服务构建同步任务。

事件列表

ProtocolFeeBpUpdated

签名: event ProtocolFeeBpUpdated(uint16 protocolFeeBp)
说明: 协议费率（基点）被合约管理员更新时触发。

参数

Name	Required	Type	Description
protocol_fee_bp	Yes	number	新的协议费用基点，对应合约参数 `protocolFeeBp`，基点转换比例为 1bp = 0.01%。

ReferrerRewardBpUpdated

签名: event ReferrerRewardBpUpdated(uint16 referrerRewardBp)
说明: 推荐人奖励基点发生变更时触发，前端可更新奖励提示文案。

参数

Name	Required	Type	Description
referrer_reward_bp	Yes	number	新的推荐人奖励基点，对应合约参数 `referrerRewardBp`。

ProtocolFeeRecipientUpdated

签名: event ProtocolFeeRecipientUpdated(address protocolFeeRecipient)
说明: 协议费收益地址调整时发出，用于监控收益归属。

参数

Name	Required	Type	Description
protocol_fee_recipient	Yes	string	最新的协议费接收地址，对应合约参数 `protocolFeeRecipient`。

RandomnessRequested

签名: event RandomnessRequested(uint256 roundId, uint256 requestId)
说明: 合约向随机数服务发起开奖请求时触发，可用于追踪开奖状态。

参数

Name	Required	Type	Description
round_id	Yes	number	触发请求的轮次 ID。
request_id	Yes	number	随机数请求标识，用于与返回结果匹配。

RoundDurationUpdated

签名: event RoundDurationUpdated(uint40 roundDuration)
说明: 管理员更新每轮持续时长后触发。

参数

Name	Required	Type	Description
round_duration	Yes	number	最新的轮次持续时长（秒）。

RoundsCancelled

签名: event RoundsCancelled(uint256 startingRoundId, uint256 numberOfRounds)
说明: 一次性取消多轮游戏时触发，便于前端批量更新轮次状态。

参数

Name	Required	Type	Description
starting_round_id	Yes	number	第一个被取消的轮次 ID。
number_of_rounds	Yes	number	本次取消的轮次数量。

RoundStatusUpdated

签名: event RoundStatusUpdated(uint256 roundId, RoundStatus status)
说明: 单轮状态变更时触发，前端可依据状态更新页面展示。

参数

Name	Required	Type	Description
round_id	Yes	number	发生状态变更的轮次 ID。
status	Yes	RoundStatus	更新后的轮次状态。

ValuePerEntryUpdated

签名: event ValuePerEntryUpdated(uint256 valuePerEntry)
说明: 单次参与所需金额变动时触发。

参数

Name	Required	Type	Description
value_per_entry	Yes	string	新的参与金额（以 wei 计）。

OutflowAllowedUpdated

签名: event OutflowAllowedUpdated(bool isAllowed)
说明: 管理员切换是否允许合约资金外流时触发，常用于紧急措施提示。

参数

Name	Required	Type	Description
is_allowed	Yes	boolean	当前是否允许资金外流。

ReferrerAssigned

签名: event ReferrerAssigned(address depositor, address referrer)
说明: 系统为存款人分配或更新推荐人时触发。

参数

Name	Required	Type	Description
depositor	Yes	string	存款人地址。
referrer	Yes	string	推荐人地址。

DepositRefunded

签名: event DepositRefunded(uint256 roundId, address depositor, uint256 amount)
说明: 轮次取消或退款发生时触发，用于提醒用户领取退款。

参数

Name	Required	Type	Description
round_id	Yes	number	退款对应的轮次 ID。
depositor	Yes	string	获得退款的地址。
amount	Yes	string	退款金额（wei）。

PrizeAwarded

签名: event PrizeAwarded(uint256 roundId, address depositor, uint256 amount)
说明: 某轮开奖后向获胜者发放奖金时触发，可用于构建中奖通知。

参数

Name	Required	Type	Description
round_id	Yes	number	奖励对应的轮次 ID。
depositor	Yes	string	获奖者地址。
amount	Yes	string	发放的奖金金额（wei）。

ReferrerRewarded

签名: event ReferrerRewarded(uint256 roundId, address referrer, uint256 amount)
说明: 推荐人奖励下发时触发，可同步推荐奖励看板。

参数

Name	Required	Type	Description
round_id	Yes	number	产生奖励的轮次 ID。
referrer	Yes	string	获奖的推荐人地址。
amount	Yes	string	奖励金额（wei）。

FeePayment

签名: event FeePayment(uint256 roundId, uint256 amount, address recipient)
说明: 协议费支付给指定接收地址时触发，可用于对账和收益预警。

参数

Name	Required	Type	Description
round_id	Yes	number	完成协议费结算的轮次 ID。
amount	Yes	string	支付的协议费用金额（wei）。
recipient	Yes	string	收款的协议费接收地址。

Name	Type	Description
none	string	轮次不存在或尚未创建。
open	string	正常开放中，可接受新的参与。
drawing	string	正在开奖，等待随机数结果。
drawn	string	已开奖，结果已出。
cancelled	string	已取消，参与者需等待退款。