> For the complete documentation index, see [llms.txt](https://whitepaper.litho.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whitepaper.litho.ai/docs/faucet_setup_instructions.md).

# Faucet Setup Instructions — Validator Team

**Priority:** Required for Makalu testnet faucet to function\
**Component:** `litho-faucet` Docker container on EC2 indexer\
**Status:** Faucet UI is live at <https://makalu.litho.ai/faucet> but claims fail with "Could not send tokens" because no faucet wallet is configured.

***

## Problem

The faucet service (`litho-faucet`) needs a funded EVM wallet to send test LITHO to users. The `FAUCET_PRIVATE_KEY` environment variable is currently empty, so all faucet claims fail with a 500 error.

***

## Step-by-Step Setup

### 1. Generate a new faucet wallet

On any machine with `cast` (Foundry) or `node`:

**Option A — Using Foundry (`cast`):**

```bash
cast wallet new
```

This outputs an address and private key. Save both.

**Option B — Using Node.js:**

```bash
node -e "const w = require('ethers').Wallet.createRandom(); console.log('Address:', w.address); console.log('Private Key:', w.privateKey);"
```

**Option C — Using any EVM wallet (MetaMask, etc.):**\
Create a new account and export the private key.

> **Save the output — you need both:**
>
> * **Address**: `0x...` (the faucet's public address)
> * **Private Key**: `0x...` (64 hex chars after `0x`)

***

### 2. Fund the faucet wallet

Send LITHO to the faucet address from a funded account (e.g., a genesis account or validator account).

**Recommended initial funding:** 100,000 LITHO (enough for 10,000 claims at 10 LITHO each)

**Using `litho` CLI (Cosmos SDK):**

```bash
lithod tx bank send <funded-account> <faucet-0x-address> 100000000000000000000000ulitho \
  --chain-id lithosphere_700777-2 \
  --gas auto --gas-adjustment 1.5 \
  --fees 1000ulitho \
  --node https://rpc.litho.ai:26657
```

**Or using cast (EVM):**

```bash
cast send <faucet-address> --value 100000ether \
  --private-key <funded-wallet-private-key> \
  --rpc-url http://localhost:8545
```

> Note: `100000ether` = 100,000 LITHO (both use 18 decimals)

***

### 3. Configure the environment variable

SSH to the EC2 indexer via bastion:

```bash
ssh -o ProxyJump="ec2-user@44.218.142.100" ec2-user@10.0.10.16
```

Edit the `.env` file in the Makalu directory:

```bash
cd /opt/lithosphere/Makalu
sudo nano .env
```

Add or update these lines:

```env
# Faucet wallet (REQUIRED - private key of the funded wallet from Step 1)
FAUCET_PRIVATE_KEY=0x<your-64-char-hex-private-key>

# EVM JSON-RPC endpoint the faucet uses to send transactions
# Use localhost if the Ethermint node runs on this machine, otherwise use the NLB
FAUCET_RPC_URL=http://localhost:8545

# Optional overrides (defaults are fine)
# FAUCET_DRIP_AMOUNT=10        # Default LITHO per claim when amount is omitted
# FAUCET_COOLDOWN_HOURS=24     # Hours between claims per address (default: 24)
# FAUCET_CHAIN_ID=700777       # EVM chain ID (default: 700777)
```

The public faucet supports claims of **10 / 25 / 50 LITHO**. If no amount is supplied, the faucet defaults to **10 LITHO**.

***

### 4. Restart the faucet container

```bash
cd /opt/lithosphere/Makalu
sudo docker compose up -d faucet
```

***

### 5. Verify it's working

**Check the container is running:**

```bash
sudo docker ps | grep faucet
```

**Check the faucet logs for startup confirmation:**

```bash
sudo docker logs litho-faucet --tail 20
```

You should see:

```
[faucet] Listening on http://0.0.0.0:8081
[faucet] RPC: http://localhost:8545 | Chain: 700777
[faucet] Drip: 10 LITHO | Cooldown: 24h
```

**Check the health endpoint:**

```bash
curl http://localhost:8081/health
```

**Test a drip manually:**

```bash
curl -X POST http://localhost:8081/drip \
  -H "Content-Type: application/json" \
  -d '{"address": "0xba2b6fA3758296c5237235b2aF3Ba2a96D36A860", "amount": "10"}'
```

Expected success response:

```json
{
  "success": true,
  "txHash": "0x...",
  "amount": "10 LITHO",
  "recipient": "0xba2b6fA3758296c5237235b2aF3Ba2a96D36A860",
  "cooldownHours": 24
}
```

**Test from the public API:**

```bash
curl -X POST https://makalu.litho.ai/api/faucet/claim \
  -H "Content-Type: application/json" \
  -d '{"address": "0xba2b6fA3758296c5237235b2aF3Ba2a96D36A860", "walletType": "WEB3", "amount": "10 LITHO"}'
```

***

### 6. Verify via the UI

1. Open <https://makalu.litho.ai/faucet>
2. Connect a wallet (MetaMask / WalletConnect)
3. Click "Add Makalu Network" if prompted
4. Enter an address or use the connected wallet address
5. Select amount and click "Claim Testnet LITHO"
6. Should see a success message with a transaction hash

***

## Troubleshooting

| Symptom                              | Cause                          | Fix                                                                              |
| ------------------------------------ | ------------------------------ | -------------------------------------------------------------------------------- |
| `FAUCET_PRIVATE_KEY not set` in logs | Missing env var                | Add to `.env` and restart                                                        |
| `insufficient funds` in logs         | Faucet wallet has no LITHO     | Fund the address from Step 2                                                     |
| `connection refused` or timeout      | Wrong RPC URL                  | Check `FAUCET_RPC_URL` — try `http://localhost:8545` or the NLB URL              |
| `chain ID mismatch`                  | Wrong chain ID                 | Ensure `FAUCET_CHAIN_ID=700777`                                                  |
| Container not starting               | Redis not running              | Check `sudo docker ps \| grep redis` — faucet depends on Redis for rate limiting |
| 502 from API                         | Faucet container not reachable | Check container is on `litho-network` Docker network                             |

***

## Security Notes

* The faucet private key should **only** exist in the `.env` file on the server — never commit it to git
* The faucet wallet should **only** hold test tokens — never use a wallet that holds real assets
* Rate limiting is enforced: 1 claim per address per 24 hours (configurable via `FAUCET_COOLDOWN_HOURS`)
* The faucet only accepts EVM (`0x...`) addresses

***

## Architecture Reference

```
User Browser
    |
    | POST /api/faucet/claim
    v
litho-api (Express, port 3010)
    |
    | POST /drip (internal Docker network)
    v
litho-faucet (Fastify, port 8081)
    |
    | sendTransaction via viem
    v
Lithosphere EVM (port 8545)
```

**Docker service name:** `faucet` (aliased as `litho-faucet`)\
**Internal URL used by API:** `http://faucet:8081`\
**Env file location:** `/opt/lithosphere/Makalu/.env`\
**Docker compose file:** `/opt/lithosphere/Makalu/docker-compose.yaml`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://whitepaper.litho.ai/docs/faucet_setup_instructions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.