gopher-faucet

Overview

This service receives faucet requests and transfers tokens accordingly. It uses multiple wallets to ensure that tokens are transferred in a timely manner.

It will create NUM_WORKERS wallets persistently. If you later reduce NUM_WORKERS it will use the first NUM_WORKERS of those wallets, but will keep the extra wallets' private keys for future growth. If you increase NUM_WORKERS it will create the additional number of wallets that you need. The wallet IDs are logged on startup.

Requests are rate-limited based on wallet ID and IP address.

Endpoints

There is a single endpoint, /api/v1/faucet?wallet=xxxxxxxx&client_ip=a.b.c.d. Both query parameters are mandatory. It will send one of the following responses:

• 200 OK - Successful request, the request has been queued and the tokens will be eventually transferred.
• 429 Too Many Requests - Wallet or IP address is rate limited.
• 500 Internal Server Error - Some error happened during request processing.

Health Checks

• /healthz - Liveness probe. Returns 200 OK if the service is running.
• /readyz - Readiness probe. Returns 200 OK if the service is connected to NATS and the Cosmos RPC endpoint is responding. Otherwise, returns 503 Service Unavailable.

Monitoring and Debug

• /debug/wallets - Returns a JSON array with all worker wallet addresses, their current balances, and funding status. Example response: [{"wallet": "gopher1...", "balance": 1000000, "denom": "ugoai", "isFunded": true}]
• /debug/metrics - Prometheus metrics endpoint.
• /debug/loglevel - GET returns the current log level as JSON (e.g., {"level": "INFO"}). PUT with a ?level=<level> query parameter sets the log level (valid values: debug, info, warn, error). PUT without parameters resets to the configured default from LOG_LEVEL env var.
• /debug/pprof/* - Go pprof profiling endpoints.

Dependencies

This service has the following dependencies:

• NATS - It uses NATS to ensure exactly-once token delivery even if the service goes down, and for persistence. This dependency is mandatory.
• Slack - If a Slack webhook URL is provided, it uses a Slack webhook to post alerts when the wallet balance falls below a threshold.

Configuration

All configuration is done using environment variables.

• FAUCET_HOME - Directory to store local persistent state such as wallet private keys. This is mandatory.
• LISTEN_ADDR - The address to listen on for HTTP requests. The default is :8080.
• FAUCET_AMOUNT - The amount of DENOM tokens that will be transferred in each transaction (e.g. 1000000). This is mandatory.
• WALLET_LOW_WATER_AMOUNT - The minimum numeric amount of DENOM tokens for a wallet. If a wallet's balance falls below this value and SLACK_WEBHOOK_URL is set, the service will send an alert to Slack. If unset no notifications will be sent.
• DENOM - The denomination of the token being sent (e.g., ugoai). This is mandatory.
• RATE_LIMIT_INTERVAL - A wallet or IP address will not be allowed more than one request during this interval. The format is Go Duration. The default is 24h.
• NUM_WORKERS - Number of workers to use (== number of parallel requests === number of wallets). Default is 10.
• LOG_LEVEL - The log level. Can be debug, info, warn, or error. Default is info.

Transaction batches and retries

• MAX_RETRIES - The maximum number of times to retry a transaction in case of an account sequence mismatch. Default is 5.
• RETRY_DELAY - The initial duration to wait before the first retry. Default is 1s.
• BACKOFF_FACTOR - A multiplier to increase the delay for each subsequent retry. Default is 2.0.
• MAX_RETRY_DELAY - The maximum delay between retries to prevent excessively long waits. Default is 30s.
• BATCH_SIZE - How many transactions to batch together. Default is 10.
• BATCH_TIMEOUT- How long to wait to send transactions to the validator, if there are less than BATCH_SIZE transactions queued. Must be larger or equal to MIN_TXN_WAIT. Default is 5s.
• MIN_TXN_WAIT- How long to wait between sending transactions to the validator as a minimum, to allow the validator time to confirm them. If the batch is filled before this time elapses, the worker will sleep until the appropriate time. Default is 3s.
• CONCURRENT_BROADCASTS - The maximum number of workers that can broadcast transactions concurrently. Default is 10.
• TXN_POLL_FREQUENCY - The frequency at which to poll the blockchain for transaction confirmation. Default is 1s.
• TXN_POLL_TIMEOUT - The maximum time to wait for a transaction to be confirmed on the blockchain. Default is 10m.

Cosmos

• BECH32_PREFIX - The bech32 prefix for wallet addresses. Default is gopher.
• COSMOS_HOST - The gRPC endpoint of a Cosmos node to connect to (e.g., localhost). This is mandatory.
• COSMOS_BFT_PORT - The Tendermint RPC port of the Cosmos node to connect to. Default is 26657.
• COSMOS_RPC_PORT - The gRPC port of the Cosmos node to connect to. Default is 9090.
• COSMOS_REST_PORT - The REST/LCD port of the Cosmos node to connect to. Default is 1317.
• CHAIN_ID - The chain ID of the Cosmos network. This is mandatory.
• GAS_LIMIT - The maximum amount of gas to use for a transaction, in DENOM. Default is 200000.
• GAS_ADJUSTMENT - The gas adjustment factor. Default is 1.5.
• GAS_PRICES - The gas prices to use for transactions. Default is 0.025.

Other external systems

• SLACK_WEBHOOK_URL - URL for Slack alerts when a wallet runs low. Optional.
• NATS_URL - URL of the NATS API. This is mandatory.
• NATS_TOPIC - Topic to use for sending/receiving in NATS. Default is gopher-faucet.
• NATS_BUCKET - Bucket to use for storing faucet data (mainly rate limiting). Default is gopher-faucet.