docs(faucet): the faucet service (#1975)

Co-authored-by: alvarius <[email protected]>

docs/pages/cli/faucet.mdx

@@ -1,3 +1,5 @@
 # mud faucet
 
-**Coming soon**
+This command is currently used to interact with the deprecated faucet service on the deprecated "lattice testnet". Once the new Redstone devnet is available, it will be updated to interact with the new [faucet service](/services/faucet).
+
+In the meantime, we recommend to use the [Redstone Holesky testnet](https://redstone.xyz) and self-hosted [faucet service](/services/faucet). See [the sample client program](https://github.com/latticexyz/mud/tree/main/examples/faucet-client) for a usage example.

docs/pages/services/faucet.mdx

@@ -1,3 +1,40 @@
 # Faucet
 
-**Coming soon**
+A minimal Typescript faucet to drip native tokens on Ethereum chains
+
+## Usage
+
+1. Install the faucet.
+
+   ```sh copy
+   pnpm install @latticexyz/faucet@next
+   ```
+
+1. Specify the environment variables.
+   Note that you need to [`export`](https://linuxconfig.org/export) these variables for the faucet service to get them.
+
+   | Variable             | Description                                           | Default   |
+   | -------------------- | ----------------------------------------------------- | --------- |
+   | `HOST`               | Host that the indexer server listens on               | `0.0.0.0` |
+   | `PORT`               | Port that the indexer server listens on               | `3002`    |
+   | `RPC_HTTP_URL`       | HTTP URL for Ethereum RPC                             |           |
+   | `FAUCET_PRIVATE_KEY` | Private key of wallet to distribute faucet funds from |           |
+   | `DRIP_AMOUNT_ETHER`  | Drip amount in ether                                  |
+
+1. Start the server.
+
+   ```sh copy
+   pnpm faucet-server
+   ```
+
+   For example, you can use these values to drip 1 ETH for a local [`anvil`](https://book.getfoundry.sh/anvil/) instance:
+
+   | Variable             | Value                                                              | Comments                           |
+   | -------------------- | ------------------------------------------------------------------ | ---------------------------------- |
+   | `RPC_HTTP_URL`       | http://127.0.0.1:8545                                              | `localhost` sometimes doesn't work |
+   | `FAUCET_PRIVATE_KEY` | 0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d | One of the default accounts        |
+   | `DRIP_AMOUNT_ETHER`  | 1                                                                  |
+
+## Getting ETH from a faucet
+
+[This sample program](https://github.com/latticexyz/mud/tree/main/examples/faucet-client) shows how to obtain ETH from a faucet.

examples/faucet-client/README.md

@@ -0,0 +1 @@
+Drip some ETH from a [faucet](https://mud.dev/services/faucet).

examples/faucet-client/index.ts

@@ -0,0 +1,13 @@
+import { createClient as createFaucetClient } from "@latticexyz/faucet";
+
+const faucetClient = createFaucetClient({
+  url: "http://127.0.0.1:3002/trpc",
+});
+
+const address = "0x5FbDB2315678afecb367f032d93F642f64180aa3";
+
+const tx = await faucetClient.drip.mutate({
+  address: address,
+});
+
+console.log(`Transaction hash: ${tx}`);

examples/faucet-client/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "mud-example-faucer-client",
+  "version": "0.0.0",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "drip": "tsx index.ts"
+  },
+  "dependencies": {
+    "@latticexyz/faucet": "2.0.0-next.14",
+    "tsx": "^3.12.7"
+  }
+}