区块链后端前端【免费下载链接】PoWFaucetModularized faucet for EVM chains with different protection methods (Captcha, Mining, IP, Mainnet Balance, Gitcoin Passport and more)项目地址https://gitcode.com/gh_mirrors/po/PoWFaucet点击查看免费下载导读PoWFaucet 是一个模块化的 EVM 链水龙头Faucet通过 Captcha、PoW 挖矿、IP 限制、主网余额、Gitcoin Passport 等多种防护手段防止资金被滥用。本文以仓库内 src/modules/MODULE_HOOKS.md 为核心骨架深入讲解 PoWFaucet 的模块钩子Module Hooks机制——即 11 个会话生命周期事件点与各保护模块按优先级prio注册回调的完整协作图谱。读完本文你将掌握每个钩子事件在会话中的触发时机、各模块注册了哪些钩子、优先级数字如何决定执行顺序以及如何利用skip.modules与奖励因子机制设计出组合化的防护策略。一、钩子机制概览为什么需要模块钩子PoWFaucet 的核心是一个普通的水龙头会话流程用户提交地址 → 会话开始经历各种防护检查→ 可能附带挖矿等任务 → 任务完成后会话变为可领取claimable→ 用户领取转账。难点在于不同防护模块captcha、github、pow、passport……需要在同一流程的不同阶段介入且互不干扰。钩子Hook机制就是为了解决平台核心与业务模块解耦的问题核心代码在固定的生命周期节点抛出事件ModuleHookAction各模块在启动时通过moduleManager.addActionHook(...)注册自己的回调函数并声明优先级prio。核心在触发事件时按照优先级从低到高依次调用回调同一优先级内并行执行。完整的钩子事件枚举定义在 src/modules/ModuleManager.tsexport enum ModuleHookAction { ClientConfig, // 下发客户端配置 SessionStart, // 会话开始核心校验点 SessionRestore, // 会话恢复重启后自动恢复 SessionInfo, // 会话信息聚合 SessionRewardFactor,// 奖励因子计算 SessionRewarded, // 奖励已累加 SessionIpChange, // 客户端 IP 变化 SessionComplete, // 会话完成可领取 SessionClaim, // 发起领取 SessionClaimed, // 领取已确认 SessionClose, // 会话关闭 }执行引擎processActionHookssrc/modules/ModuleManager.ts会同时合并本地函数核心自身在特定 prio 插入的内置检查与模块注册的钩子按 prio 排序后分组执行同一 prio 的回调通过Promise.all并行执行全部完成后再进入下一优先级从而保证跨模块的检查不会阻塞彼此而同阶段内的检查并行高效。与模块生命周期管理的关系钩子的注册/注销由BaseModule抽象基类src/modules/BaseModule.ts与ModuleManager配合完成每个模块类通过startModule()在启动时注册钩子disableModule()/removeModuleHooks在模块被停用时移除其全部钩子src/modules/ModuleManager.ts。模块的启用与否完全由faucet-config.yaml中modules.name.enabled决定见 src/modules/ModuleManager.ts内置模块注册表见 src/modules/modules.ts。二、MODULE_HOOKS.md 全文官方钩子优先级总表以下是仓库文档 src/modules/MODULE_HOOKS.md 的完整内容它定义了每个钩子事件上各模块的优先级注册表ClientConfig prio 1: authenticatoor, captcha, ensname, github, passport, pow, zupass SessionStart prio 1: captcha, *maintenance_mode_check prio 2: authenticatoor, whitelist, zupass prio 3: ensname prio 5: *eth_address_check prio 6: passport prio 7: concurrency-limit, ethinfo, ipinfo, mainnet-wallet, recurring-limits prio 10: pow SessionRestore prio 10: pow SessionInfo prio 1: passport, pow SessionRewardFactor prio 5: authenticatoor, faucet-outflow, github, passport prio 6: faucet-balance, ipinfo, whitelist SessionRewarded prio 5: faucet-outflow SessionIpChange prio 2: whitelist prio 6: concurrency-limit, ipinfo SessionComplete prio 5: authenticatoor, github prio 10: pow SessionClaim prio 1: captcha SessionClaimed 无模块注册 SessionClose 无模块注册其中带*前缀的项*maintenance_mode_check、*eth_address_check是核心faucet core自身在钩子流程中插入的本地检查函数而非模块注册的回调——它们在 src/session/FaucetSession.ts 的startSession()中直接以localfns传入。三、按钩子事件逐项深度剖析3.1 ClientConfig下发客户端配置prio 1会话尚未开始时水龙头前端需要知道每个模块的运行参数例如 captcha 的 siteKey、pow 的挖矿参数、passport 的 stamp 评分表。所有参与模块都以prio 1注册此钩子将配置写入clientConfig对象最终下发到浏览器端window.PoWFaucet配置块。模块下发内容对应源码captchaprovider、siteKey、requiredForStart、requiredForClaimsrc/modules/captcha/CaptchaModule.tspowpowTimeout、powIdleTimeout、powParams按算法分支拼装 scrypt/cryptonight/argon2/nickminer 参数、powDifficulty、powHashrateLimitsrc/modules/pow/PoWModule.tspassportrefreshTimeout、manualVerification、stampScoring、boostFactor、overrideScores、guestRefreshsrc/modules/passport/PassportModule.tsauthenticatoorauthUrl、requireLogin、loginLabel、userLabel、infoHtml、loginLogosrc/modules/authenticatoor/AuthenticatoorModule.tsgithubclientId、authTimeout、redirectUrl、callbackStatesrc/modules/github/GithubModule.tszupassurl、api、redirectUrl、event、watermark、nullifier等src/modules/zupass/ZupassModule.tsensnamerequired布尔值src/modules/ensname/EnsNameModule.ts3.2 SessionStart会话开始——防护检查的主战场prio 1~10这是最复杂的钩子事件承载了绝大部分防护逻辑。核心在 src/session/FaucetSession.ts 的startSession()中执行优先级执行顺序如下prio 1*maintenance_mode_check核心内置——检查faucetConfig.denyNewSessions若设置了维护模式则抛出FAUCET_DISABLED随后是captcha模块的验证若checkSessionStart开启验证userInput.captchaToken并可通过自定义 provider 返回captcha.ident身份标识见 src/modules/captcha/CaptchaModule.ts。prio 2*start_module核心内置——即applyStartModulesrc/session/FaucetSession.ts校验userInput.module是否为已启用模块、params是否为扁平字符串映射并存入module.params会话数据同层还有authenticatoor登录态校验 并发限制 grant 权益授予src/modules/authenticatoor/AuthenticatoorModule.ts、whitelistIP 白名单匹配命中则写入whitelist与skip.modulessrc/modules/whitelist/WhitelistModule.ts、zupassZupass PCD 票据校验src/modules/zupass/ZupassModule.ts。prio 3ensname——若用户提交的是.eth域名则解析为地址required: true时强制要求 ENS 名称src/modules/ensname/EnsNameModule.ts。prio 5*eth_address_check核心内置——校验目标地址格式为0x 40 位十六进制且非全零地址。prio 6passport——拉取 Gitcoin Passport 并计算评分可设置requireMinScore门槛、或按评分豁免 IP 托管/代理限制写入ipinfo.override_hosting/ipinfo.override_proxy见 src/modules/passport/PassportModule.tsgithub——按checks列表逐项验证账号年龄/仓库数/关注者数等不满足required项则抛错同时检查restrictions周期限额src/modules/github/GithubModule.ts。prio 7concurrency-limit同 IP/同地址并发会话数限制、ethinfo目标地址余额上限 拒绝合约地址、ipinfoIP 情报查询与托管/代理/国家码限制、mainnet-wallet主网余额/交易数/ERC20 余额门槛、recurring-limits按 IP/地址的周期会话数与金额限额。这些模块的核心实现分别见 src/modules/concurrency-limit/ConcurrencyLimitModule.ts、src/modules/ethinfo/EthInfoModule.ts、src/modules/ipinfo/IPInfoModule.ts、src/modules/mainnet-wallet/MainnetWalletModule.ts、src/modules/recurring-limits/RecurringLimitsModule.ts。prio 10pow——添加阻塞任务miningaddBlockingTask阻止会话提前结束、重置奖励为 0、生成随机pow.preimage并创建 PoW 服务器会话src/modules/pow/PoWModule.ts。优先级最高意味着挖矿是会话启动流程的收尾动作前面所有防护检查都通过后才会开始挖矿。提示SessionStart 钩子抛出的FaucetError会直接导致会话失败setSessionFailed因此任何required型检查都发生在此事件内。而skip.modules机制由 authenticatoor/zupass/whitelist 等模块写入可以让会话跳过后续某些模块的检查——被跳过的模块在processSessionStart开头统一判断并直接 return如 src/modules/pow/PoWModule.ts。3.3 SessionRestore会话恢复prio 10: pow当水龙头重启后客户端可通过faucetSecret签名的会话数据自动恢复进行中的会话。restoreSession()src/session/FaucetSession.ts会触发 SessionRestore 事件。目前只有pow注册此钩子prio 10用于在恢复后重建 PoW 服务器端会话src/modules/pow/PoWModule.ts使挖矿中的用户可以无缝续挖。3.4 SessionInfo会话信息聚合prio 1: passport, pow前端轮询会话状态时getSessionInfo()见 src/session/FaucetSession.ts需要各模块补充自己的状态信息。passport与pow都以 prio 1 注册pow 返回lastNonce、preImage、shareCountsrc/modules/pow/PoWModule.tspassport 返回当前 Passport 评分与 boost 因子src/modules/passport/PassportModule.ts。3.5 SessionRewardFactor奖励因子计算prio 5/6水龙头最终发放的金额 基础金额 × 所有模块奖励因子的乘积见 src/session/FaucetSession.ts 的addReward()遍历rewardFactors数组累乘再乘以基础amount。该事件即各模块向rewardFactors数组追加因子的地方prio 5authenticatoor登录用户加成AuthenticatoorModule.ts、github高质量账号加成GithubModule.ts、passportPassport 评分 boostPassportModule.ts、faucet-outflow资金流出速率限制因子prio 6faucet-balance水龙头钱包余额限制见 FaucetBalanceModule.ts支持fixedRestriction固定阶梯与dynamicRestriction线性限制、ipinfoIP 限制因子IPInfoModule.ts、whitelist白名单奖励WhitelistModule.ts。因子为factor如 1.1 表示 10%0.5 表示减半实现接口见 src/session/SessionRewardFactor.ts。同一事件内因子按乘法叠加因此多模块可共同放大或缩减最终奖励。3.6 SessionRewarded奖励已累加prio 5: faucet-outflow每次矿工提交有效 share 产生奖励时触发addReward末尾调用processActionHooks([], ModuleHookAction.SessionRewarded, [this, rewardAmount, rewardFactors])。目前只有faucet-outflow注册此钩子prio 5将已发放金额从内部outflow 余额中扣除src/modules/faucet-outflow/FaucetOutflowModule.ts实现按时间窗口允许的流出速率限制挖矿总量的动态调节。3.7 SessionIpChange客户端 IP 变化prio 2/6会话建立后若客户端 WebSocket 连接的 IP 与记录不一致例如挖矿期间切换网络updateRemoteIP()src/session/FaucetSession.ts会触发此事件IP 相关检查需重新执行prio 2whitelist——重新匹配白名单prio 6concurrency-limit 与 ipinfo——重新检查并发限制与 IP 情报限制。任一钩子抛错都会让 IP 更新回滚this.remoteIP oldRemoteIP保证会话数据一致性。3.8 SessionComplete会话完成prio 5/10当所有阻塞任务如挖矿完成后completeSession()src/session/FaucetSession.ts将会话状态置为CLAIMABLE并触发prio 5authenticatoor 与 github——将会话关联到用户 ID 并写入各自的模块数据库供周期限额统计见 AuthenticatoorModule.ts 与 GithubModule.tsprio 10pow——销毁 PoW 服务器上的挖矿会话并停止相关客户端连接src/modules/pow/PoWModule.ts。3.9 SessionClaim领取检查prio 1: captcha用户点击领取时EthClaimManager.createSessionClaim()src/eth/EthClaimManager.ts在处理转账前触发此事件。目前仅有captcha注册prio 1若配置checkBalanceClaim: true则领取前必须再次通过验证码校验src/modules/captcha/CaptchaModule.ts。3.10 SessionClaimed / SessionClose预留扩展点SessionClaimed在链上交易被确认后触发src/eth/EthClaimManager.ts目前仓库中无模块注册回调但faucet-outflow会借此机会顺带扣除交易手续费updateState(null, txFee)属于核心与模块的隐式协作SessionClose钩子枚举中已定义但当前无模块注册属于为未来模块如会话关闭后的统计/审计预留的扩展点。四、优先级与执行语义同 prio 并行、低 prio 先行理解钩子机制需要记住三个关键语义均可从 src/modules/ModuleManager.ts 源码确认注册即排序addActionHook按 prio 将回调插入有序链表prio 相同的按注册先后排列。分组执行processActionHooks每一轮取出当前最小 prio 的所有回调含核心本地函数Promise.all并行执行全部 resolve 后才进入下一 prio。低 prio 永远先于高 prio 完成。抛出即中断任一钩子抛出异常会向上传播。在 SessionStart 中表现为会话失败FAUCET_DISABLED、INVALID_CAPTCHA、BALANCE_LIMIT、GITHUB_CHECK、CONCURRENCY_LIMIT、RECURRING_LIMIT、PASSPORT_SCORE等均为典型错误码在 SessionIpChange 中则表现为 IP 更新回滚。由此可以推导出各模块的设计定位prio 越小越接近基础合法性检查验证码、登录、地址格式prio 越大越接近资源与额度类检查并发、余额、周期限额prio 10 的 pow 作为最后一道启动步骤承载需要前述全部通过才能开始的长时间任务。五、配置视角如何在 faucet-config.yaml 中组合使用钩子是否生效完全取决于 faucet-config.example.yaml 中modules:段各模块的enabled开关。示例配置默认启用了 captcha、ensname、ipinfo、ethinfo、faucet-balance、faucet-outflow、recurring-limits、concurrency-limit、pow 等模块并将 authenticatoor、github、mainnet-wallet、passport、zupass 设为enabled: false需自行接入对应服务方可启用。配置示例中的关键联动示例对应钩子事件captchacheckSessionStart: false、checkBalanceClaim: false控制 SessionStart / SessionClaim 两个事件上的验证开关默认均为 false即验证码仅作前端展示recurring-limitslimits数组的每一项在 SessionStartprio 7时执行支持byAddrOnly/byIPOnly/ip4Subnet作用域与rewards奖励削减配合 SessionRewardFactorconcurrency-limitconcurrencyLimit: 1表示同 IP 或同地址同时只允许 1 个 running 状态会话SessionStart SessionIpChange 双重检查authenticatoor / zupass 的 grantsrewardFactor作用于 SessionRewardFactor与skipModules作用于 SessionStart 的模块跳过、overrideMaxDrop在 SessionStart 时通过setDropAmount直接覆盖基础奖励见 AuthenticatoorModule.ts三者组合实现登录用户免挖矿 翻倍奖励等高级玩法。需要说明本文涉及的 pow 模块内部参数powShareReward、powDifficulty、powHashAlgo等已在示例配置中给出参考值完整参数说明以仓库文档与模块自身文档为准。六、测试与验证从测试用例印证钩子行为仓库测试目录提供了钩子机制的直接验证依据读者可按需深入tests/modules/PoWModule.spec.ts验证 pow 模块的 SessionStart阻塞任务、preimage 生成、SessionComplete服务器销毁等钩子行为tests/modules/AuthenticatoorModule.spec.ts 与 tests/modules/GithubModule.spec.ts验证登录类模块的 SessionStart 检查与 SessionRewardFactor 因子注入tests/modules/ConcurrencyLimitModule.spec.ts验证并发限制在 SessionStart / SessionIpChange 上的抛错行为tests/modules/IpInfoModule.spec.ts验证 IP 限制因子与blocked关闭/终止语义tests/FaucetSession.spec.ts验证会话状态机与奖励因子累乘逻辑。对于自行开发新模块的开发者还可参考 docs/modules.md模块包 manifest、backend.cjs 结构、SDK 注入方式与测试夹具 tests/fixtures/echo通过sdk.registerModuleaddActionHook接入本套钩子体系。七、总结一张表看懂模块-钩子矩阵钩子事件核心含义注册模块按 prioClientConfig下发前端配置prio 1: captcha / ensname / github / passport / pow / authenticatoor / zupassSessionStart会话开始全量检查prio 1: captcha 维护模式prio 2: authenticatoor / whitelist / zupassprio 3: ensnameprio 5: 地址校验prio 6: passport / githubprio 7: concurrency-limit / ethinfo / ipinfo / mainnet-wallet / recurring-limitsprio 10: powSessionRestore会话恢复prio 10: powSessionInfo状态信息聚合prio 1: passport / powSessionRewardFactor奖励因子注入prio 5: authenticatoor / faucet-outflow / github / passportprio 6: faucet-balance / ipinfo / whitelistSessionRewarded奖励已入账prio 5: faucet-outflowSessionIpChangeIP 变更复查prio 2: whitelistprio 6: concurrency-limit / ipinfoSessionComplete会话完成收尾prio 5: authenticatoor / githubprio 10: powSessionClaim领取前校验prio 1: captchaSessionClaimed交易确认暂无模块注册供扩展SessionClose会话关闭暂无模块注册供扩展这套机制的价值在于新增一种防护手段只需实现一个BaseModule子类并注册对应钩子无需改动会话核心代码而优先级系统则让必过检查、加分检查、资源限制、长任务启动在同一个生命周期内井然有序地分层执行。对想要为 EVM 水龙头设计抗滥用方案的开发者而言PoWFaucet 的 MODULE_HOOKS 体系是一个可直接借鉴的模块化范本。赞分享区块链后端前端【免费下载链接】PoWFaucetModularized faucet for EVM chains with different protection methods (Captcha, Mining, IP, Mainnet Balance, Gitcoin Passport and more)项目地址https://gitcode.com/gh_mirrors/po/PoWFaucet点击查看免费下载相关推荐Tether 模块扩展机制详解自定义 position 钩子、initialize 生命周期与内置模块源码剖析Tether 模块扩展机制详解自定义 position 钩子、initialize 生命周期与内置模块源码剖析 本篇基于 Tether一个用于悬浮层、Too前端UI组件终极SeedVR教程5个简单步骤实现视频画质无损修复的完整指南终极SeedVR教程5个简单步骤实现视频画质无损修复的完整指南 还在为模糊不清的老视频而苦恼吗那些珍贵的家庭录像、毕业典礼、旅行记录因为画质问题而失去了原基础模型计算机视觉深度学习lspsaga.nvim代码操作完全解析从灯泡提示到智能修复lspsaga.nvim代码操作完全解析从灯泡提示到智能修复 lspsaga.nvim是一款功能强大的Neovim LSP增强插件为开发者提供了从代码提示到上一篇Kubernetes Checkpoint/Restore 工作组章程全解读从容器级快照到调度协同下一篇Home Assistant Netatmo 离家标记动作 netatmo.set_person_away 完整使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考