ethora-team/bnb-faucet
GitHub: ethora-team/bnb-faucet
BNB Smart Chain 上的生产级 BEP-20 测试网代币水龙头，为开发者提供 SDK、REST API 和 CLI 三种方式快速领取测试代币。
Stars: 3 | Forks: 0
# Ethora RPC
[](./packages) [](https://www.npmjs.com/package/@ethora/faucet-sdk) [](./LICENSE) [](./audits) **BNB Smart Chain 上最可靠的 BEP-20 水龙头。** 立即领取 USDT、USDC、ETH、WBNB、CAKE 及其他 21 种测试网 token。 对开发者、审计员和区块链学习者免费。 [**→ 在线水龙头**](https://ethora.org) · [**→ API 文档**](https://ethora.org/api-docs) · [**→ SDK 参考**](./packages/sdk) · [**→ Bug 报告**](https://github.com/ethora-team/bnb-faucet/issues/new?template=bug_report.md)
## 概述
Ethora BNB Faucet 是一个开源的、生产级的 BNB Smart Chain token 分发器。它专为构建 DeFi 协议的开发者、验证合约逻辑的审计员以及探索区块链开发的学习者设计 —— 无需触及真实资产。
本项目以 **monorepo** 的形式提供，包含：
| 包名 | 描述 |
|---------|-------------|
| [`@ethora/contracts`](./packages/contracts) | Solidity 水龙头及模拟 token 合约 |
| [`@ethora/faucet-sdk`](./packages/sdk) | 用于通过编程方式请求 token 的 TypeScript SDK |
| [`@ethora/api`](./packages/api) | Node.js REST API (Fastify + Redis) |
| [`@ethora/cli`](./packages/cli) | CLI 工具 — 从终端领取 token |
| [`@ethora/indexer`](./packages/indexer) | 链上事件 indexer (ethers.js + PostgreSQL) |
| [`apps/web`](./apps/web) | 前端 — 水龙头 UI |
| [`apps/docs`](./apps/docs) | 开发者文档网站 |
## 架构
```
┌─────────────────────────────────────────────────────────────────┐
│ BNB Smart Chain (BSC Mainnet) │
│ │
│ ┌──────────────────┐ ┌─────────────────────────────┐ │
│ │ FaucetController│ │ MockToken (ERC-20 × 24) │ │
│ │ (upgradeable) │──mint─▶│ USDT / USDC / WBNB / ... │ │
│ └──────────┬───────┘ └─────────────────────────────┘ │
│ │ events │
└──────────────┼──────────────────────────────────────────────────┘
│
┌──────────▼──────────┐
│ @ethora/indexer │ ethers.js · PostgreSQL · BullMQ
│ (event pipeline) │
└──────────┬──────────┘
│ REST
┌──────────▼──────────┐ ┌────────────────────┐
│ @ethora/api │◀───────▶│ Redis (cooldown, │
│ (Fastify + Zod) │ │ rate-limit, cache) │
└──────────┬──────────┘ └────────────────────┘
│
┌──────────┴────────────────────┐
│ │
▼ ▼
┌──────────────────┐ ┌─────────────────────┐
│ apps/web │ │ @ethora/faucet-sdk │
│ (Vanilla JS) │ │ (npm package) │
└──────────────────┘ └─────────────────────┘
│
┌──────────▼──────────┐
│ @ethora/cli │
│ (Node.js CLI) │
└─────────────────────┘
```
## 快速开始
### 前置条件
- Node.js ≥ 18
- pnpm ≥ 8
- Docker（用于本地 API + Redis + Postgres 技术栈）
- Foundry 或 Hardhat（用于合约开发）
### 安装
```
git clone https://github.com/ethora-labs/bnb-faucet.git
cd bnb-faucet
# 安装所有 workspace 依赖
pnpm install
# 复制环境变量
cp .env.example .env
```
### 本地运行
```
# 启动基础设施 (Redis, Postgres)
docker compose up -d
# 构建所有 packages
pnpm build
# 以 dev 模式运行 API
pnpm --filter @ethora/api dev
# 运行 frontend
pnpm --filter web dev
```
### 使用 SDK
```
npm install @ethora/faucet-sdk
```
```
import { EthoraFaucet } from '@ethora/faucet-sdk';
const faucet = new EthoraFaucet({ apiKey: process.env.ETHORA_API_KEY });
const result = await faucet.request({
walletAddress: '0xYourWalletAddress',
tokens: ['USDT', 'USDC', 'WBNB'],
captchaToken: turnstileToken,
});
console.log(result.txHash);
// → 0x3f9d2a...
```
### 使用 CLI
```
npm install -g @ethora/cli
ethora-faucet claim \
--address 0xYourWalletAddress \
--tokens USDT,USDC,LINK \
--api-key $ETHORA_API_KEY
```
## 包
### `@ethora/contracts`
使用 Hardhat 编译的 Solidity 智能合约。包括：
- `FaucetController.sol` — 可升级 (UUPS) 的 drip 控制器，具有冷却强制执行和基于 token 的速率限制
- `MockToken.sol` — 最小化的 ERC-20，`mint()` 仅限 `MINTER_ROLE` 使用
- `FaucetRegistry.sol` — 带有元数据的链上 token 注册表
- 用于 BSC Testnet 的 Hardhat 部署脚本
- 完整的测试套件 (Mocha + Chai + Waffle)
- Slither & Mythril CI 集成
[→ contracts README](./packages/contracts/README.md)
### `@ethora/faucet-sdk`
TypeScript 优先的 SDK。除 `ethers` 外零运行时依赖。支持 ESM 和 CJS。
[→ SDK README](./packages/sdk/README.md)
### `@ethora/api`
基于 Fastify 的 REST API。特性：
- Zod 请求验证
- Cloudflare Turnstile 验证码验证
- 基于 Redis 的冷却和速率限制
- Webhook 派发（HMAC-SHA256 签名）
- 自动生成的 OpenAPI 3.1 规范
- 位于 `/metrics` 的 Prometheus 指标
[→ API README](./packages/api/README.md)
### `@ethora/cli`
适用于 CI pipeline 和高级用户的终端工具。
```
ethora-faucet
Commands:
claim Request testnet tokens
status Check cooldown for an address
tokens List available tokens
balance Query faucet reserve balance
```
[→ CLI README](./packages/cli/README.md)
### `@ethora/indexer`
后台 worker，监听链上的 `Drip` 事件并将丰富后的记录写入 PostgreSQL。为 `/wallet/history` endpoint 提供支持。
[→ Indexer README](./packages/indexer/README.md)
## 部署
| 合约 | 网络 | 地址 |
|----------|---------|---------|
| `FaucetController` | BSC Testnet | [`0x41228B7b...`](https://testnet.bscscan.com/address/0x41228B7b96150BB7760087786bC93E6f6f2B8f0f) |
| `FaucetRegistry` | BSC Testnet | [`0xAb5801a7...`](https://testnet.bscscan.com/address/0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B) |
| `MockUSDT` | BSC Testnet | [`0x337610d2...`](https://testnet.bscscan.com/address/0x337610d27c682E347C9cD60BD4b3b107C9d34dDd) |
| `MockUSDC` | BSC Testnet | [`0x64544969...`](https://testnet.bscscan.com/address/0x64544969ed7EBf5f083679233325356EbE738930) |
完整部署清单：[`deployments/bsc-testnet.json`](./deployments/bsc-testnet.json)
## 安全
Ethora BNB Faucet 合约已由 [Halborn Security](https://halborn.com) 审查。审计报告可在 [`./audits`](./audits) 中查看。
**负责任的披露：** 请勿针对安全漏洞发布公开的 GitHub issue。请改为发送邮件至 `security@ethora.io`。
## 许可证
MIT © [Ethora 团队](https://github.com/ethora-team)
[](./packages) [](https://www.npmjs.com/package/@ethora/faucet-sdk) [](./LICENSE) [](./audits) **BNB Smart Chain 上最可靠的 BEP-20 水龙头。** 立即领取 USDT、USDC、ETH、WBNB、CAKE 及其他 21 种测试网 token。 对开发者、审计员和区块链学习者免费。 [**→ 在线水龙头**](https://ethora.org) · [**→ API 文档**](https://ethora.org/api-docs) · [**→ SDK 参考**](./packages/sdk) · [**→ Bug 报告**](https://github.com/ethora-team/bnb-faucet/issues/new?template=bug_report.md)
标签：BEP-20, MITM代理, REST API, Solidity, TypeScript SDK, Web3工具, 区块链开发, 后端开发, 搜索引擎查询, 测试用例, 测试网水龙头, 网络测绘, 请求拦截