eth-faucet

The faucet is a web application with the goal of distributing small amounts of Ether in private and test networks.

Features

Configure the funding account using a private key or keystore
Implement CAPTCHA verification to prevent abuse
Rate-limit requests by ETH address and IP address to prevent spam
Prevent X-Forwarded-For spoofing by specifying the number of reverse proxies

Get started

Prerequisites

Go (version 1.17 or later)
Node.js

Installation

Clone the repository and navigate to the app’s directory

git clone https://github.com/chainflag/eth-faucet.git
cd eth-faucet

Bundle frontend with Vite

go generate

Build Go project

go build -o eth-faucet

Usage

Use a private key

./eth-faucet -httpport 8080 -wallet.provider http://localhost:8545 -wallet.privkey privkey

Use a keystore

./eth-faucet -httpport 8080 -wallet.provider http://localhost:8545 -wallet.keyjson keystore -wallet.keypass password.txt

Configuration

You can configure the funding account by using environment variables instead of command-line flags:

export WEB3_PROVIDER=rpc_endpoint
export PRIVATE_KEY=hex_private_key

export WEB3_PROVIDER=rpc_endpoint
export KEYSTORE=keystore_path
echo "your_keystore_password" > `pwd`/password.txt

Then run the faucet application without the wallet command-line flags:

./eth-faucet -httpport 8080

Optional Flags

The following are the available command-line flags(excluding above wallet flags):

Flag	Description	Default Value
-httpport	Listener port to serve HTTP connection	8080
-proxycount	Count of reverse proxies in front of the server	0
-faucet.amount	Number of Ethers to transfer per user request	1.0
-faucet.minutes	Number of minutes to wait between funding rounds	1440
-faucet.name	Network name to display on the frontend	testnet
-faucet.symbol	Token symbol to display on the frontend	ETH
-hcaptcha.sitekey	hCaptcha sitekey
-hcaptcha.secret	hCaptcha secret

Docker deployment

docker run -d -p 8080:8080 -e WEB3_PROVIDER=rpc_endpoint -e PRIVATE_KEY=hex_private_key chainflag/eth-faucet:1.2.0

docker run -d -p 8080:8080 -e WEB3_PROVIDER=rpc_endpoint -e KEYSTORE=keystore_path -v `pwd`/keystore:/app/keystore -v `pwd`/password.txt:/app/password.txt chainflag/eth-faucet:1.2.0

License

Distributed under the MIT License. See LICENSE for more information.