github.com/tirogen/go-ethereum@v1.10.12-0.20221226051715-250cfede41b6/cmd/faucet/README.md (about)

     1  # Faucet
     2  
     3  The `faucet` is a simplistic web application with the goal of distributing small amounts of Ether in private and test networks.
     4  
     5  Users need to post their Ethereum addresses to fund in a Twitter status update or public Facebook post and share the link to the faucet. The faucet will in turn deduplicate user requests and send the Ether. After a funding round, the faucet prevents the same user from requesting again for a pre-configured amount of time, proportional to the amount of Ether requested.
     6  
     7  ## Operation
     8  
     9  The `faucet` is a single binary app (everything included) with all configurations set via command line flags and a few files.
    10  
    11  First things first, the `faucet` needs to connect to an Ethereum network, for which it needs the necessary genesis and network infos. Each of the following flags must be set:
    12  
    13  - `-genesis` is a path to a file containing the network `genesis.json`. or using:
    14    - `-goerli` with the faucet with Görli network config
    15    - `-rinkeby` with the faucet with Rinkeby network config
    16    - `-sepolia` with the faucet with Sepolia network config
    17  - `-network` is the devp2p network id used during connection
    18  - `-bootnodes` is a list of `enode://` ids to join the network through
    19  
    20  The `faucet` will use the `les` protocol to join the configured Ethereum network and will store its data in `$HOME/.faucet` (currently not configurable).
    21  
    22  ## Funding
    23  
    24  To be able to distribute funds, the `faucet` needs access to an already funded Ethereum account. This can be configured via:
    25  
    26  - `-account.json` is a path to the Ethereum account's JSON key file
    27  - `-account.pass` is a path to a text file with the decryption passphrase
    28  
    29  The faucet is able to distribute various amounts of Ether in exchange for various timeouts. These can be configured via:
    30  
    31  - `-faucet.amount` is the number of Ethers to send by default
    32  - `-faucet.minutes` is the time to wait before allowing a rerequest
    33  - `-faucet.tiers` is the funding tiers to support  (x3 time, x2.5 funds)
    34  
    35  ## Sybil protection
    36  
    37  To prevent the same user from exhausting funds in a loop, the `faucet` ties requests to social networks and captcha resolvers.
    38  
    39  Captcha protection uses Google's invisible ReCaptcha, thus the `faucet` needs to run on a live domain. The domain needs to be registered in Google's systems to retrieve the captcha API token and secrets. After doing so, captcha protection may be enabled via:
    40  
    41  - `-captcha.token` is the API token for ReCaptcha
    42  - `-captcha.secret` is the API secret for ReCaptcha
    43  
    44  Sybil protection via Twitter requires an API key as of 15th December, 2020. To obtain it, a Twitter user must be upgraded to developer status and a new Twitter App deployed with it. The app's `Bearer` token is required by the faucet to retrieve tweet data:
    45  
    46  - `-twitter.token` is the Bearer token for `v2` API access
    47  - `-twitter.token.v1` is the Bearer token for `v1` API access
    48  
    49  Sybil protection via Facebook uses the website to directly download post data thus does not currently require an API configuration. 
    50  
    51  ## Miscellaneous
    52  
    53  Beside the above - mostly essential - CLI flags, there are a number that can be used to fine-tune the `faucet`'s operation. Please see `faucet --help` for a full list.