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

• Allow to configure the funding account via private key or keystore
• Asynchronous processing Txs to achieve parallel execution of user requests
• Rate limiting by ETH address and IP address as a precaution against spam
• Prevent X-Forwarded-For spoofing by specifying the count of reverse proxies

• Go (1.16 or later)
• Node.js

1. Clone the repository and navigate to the app’s directory

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

2. Bundle Frontend web with Vite

npm run build

3. Build Go project

go build -o eth-faucet

Use private key to fund users

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

Use keystore to fund users

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

You can configure the funder by using environment variables instead of command-line flags as follows:

export WEB3_PROVIDER=rpc endpoint
export PRIVATE_KEY=hex private key

or

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):

docker run -d -p 8080:8080 -e WEB3_PROVIDER=rpc endpoint -e PRIVATE_KEY=hex private key chainflag/eth-faucet:1.1.0

or

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.1.0

heroku create
heroku buildpacks:add heroku/nodejs
heroku buildpacks:add heroku/go
heroku config:set WEB3_PROVIDER=rpc endpoint
heroku config:set PRIVATE_KEY=hex private key
git push heroku main
heroku open

or

tip: Free web dyno goes to sleep and discards in-memory rate limiting records after 30 minutes of inactivity, so faucet.minutes configuration greater than 30 doesn't work properly in the free Heroku plan.

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