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 WEB3PROVIDER=rpcendpoint export PRIVATEKEY=hexprivate_key

or

export WEB3PROVIDER=rpcendpoint
export KEYSTORE=keystore_path
echo "yourkeystorepassword" > 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 WEB3PROVIDER=rpcendpoint -e PRIVATEKEY=hexprivate_key chainflag/eth-faucet:1.2.0

or

docker run -d -p 8080:8080 -e WEB3PROVIDER=rpcendpoint -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.