popupfaucet

💧popupfaucet is an attempt at a pain-free way to get workshop participants some testnet ether in order to participate.

Current options leave something to be desired:

1. Ask users to navigate to and use a 3rd-party faucet

   • cons: external point of failure, sales pitches, hoops (account creation/PoW), exhausted daily limits

2. Create and pre-seed wallets then distribute, e.g., print and hand out QR codes

• cons: physical/in-person only, manual process, guessing the right amount

1. Collect addresses, then use a script to distribute tokens

• cons: if manual, interruptions with latecomers; if automated, one more thing to run and maintain

💧 popupfaucet introduces another option: pre-seeded faucets accessible to anyone that can install a Python package and knows your code phrase. 🦄

🛠️ How it works:

popupfaucet can be installed via pip or pipx. Anyone with testnet ether to share can create and fund a faucet from the command line, gated by a custom code phrase. Once funded, users claim faucet funds using that custom code. No 3rd-party faucets or scripting required. If the faucet starts to run low, anyone can top it up from the same CLI app.

A Solidity contract (https://github.com/wolovim/popupfaucet-contract) keeps track of event codes and their respective available funds. Event codes are keccak hashed, as not to be readily reverse engineered. A drip function just requires knowledge of a particular event code, then disburses 0.0001 testnet ether. The arbitrarily small amount is proving the concept; a follow-on feature is to enable a faucet creator to configure the drip amount. We used the Ape framework to compile, test, and deploy contracts to Sepolia, OP Sepolia, and Base Sepolia.

The CLI app (https://github.com/wolovim/popupfaucet) is a Python project using Rye for dependency management and deployment. Dependencies include click, rich, and InquirerPy libraries to provide a dynamic CLI experience. The requests library is used to communicate with our server, eth_account is used to create ephemeral accounts, and eth-utils handles address validation.

The server (https://github.com/wolovim/popupfaucet-server) is a Flask app deployed to Render and is responsible for coordinating (and hiding away) interactions with the smart contract. It uses the ephemeral accounts sent by the CLI to know which event code to pair with which deposit, and send off the transaction. The server also manages an admin account to sponsor drip transactions. Not yet implemented is a small percentage of each faucet deployment being retained by the admin account for this purpose.

Let's step through an example user experience. A workshop host may "create" a new faucet. They choose a network and provide an "event code" of their choice. The CLI app then generates a throw-away account and instructs the host to send testnet ether there. The app sends the event code and ephemeral private key to the server, which then creates a transaction to register their event code and ether amount.

The host can verify the specific event has been funded using the "status" function. This sends off the network and event code to the server, which queries the contract. It returns whether the event code exists on that network, and if so, how much ether is available for distribution.

Workshop attendees can then request funds via the "drip" function. The network name, event code, and validated receiving address are passed to the server. Assuming the event exists and is funded, an amount of 0.0001 ether is sent.

The last function is "topup", which allows a host (or anyone else) to add more funds to an existing faucet. The technical details are similar to the create function.