Feat/add web UI

.env.example

@@ -0,0 +1,12 @@
+NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=
+
+# Sepolia
+NEXT_PUBLIC_FAUCET_ADDRESS_SEPOLIA=
+
+# Anvil (local dev) - run `./docker/deploy-faucet.sh` to get the address
+# NIL token is pre-deployed at 0x5FbDB2315678afecb367f032d93F642f64180aa3
+NEXT_PUBLIC_FAUCET_ADDRESS_ANVIL=
+
+# Optional: Your wallet address to fund with ETH on Anvil for gas
+# Used by deploy-faucet.sh: DEV_WALLET=0x... pnpm docker:deploy
+DEV_WALLET=

.github/workflows/ci.yaml

@@ -0,0 +1,44 @@
+name: CI
+
+on: [push, pull_request]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check-web:
+    name: Check Web
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+      - uses: pnpm/action-setup@v4
+      - run: pnpm install
+      - run: pnpm fmt --check
+      - run: pnpm lint
+      - run: pnpm typecheck
+      - run: pnpm build
+
+  check-contracts:
+    name: Check Contracts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: "recursive"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+      - uses: pnpm/action-setup@v4
+      - uses: foundry-rs/foundry-toolchain@v1
+      - run: pnpm install
+      - run: forge fmt --check
+        working-directory: contracts
+      - run: pnpm exec solhint 'contracts/src/**/*.sol'
+      - run: forge build
+        working-directory: contracts
+      - run: forge test
+        working-directory: contracts

.gitignore

@@ -1,6 +1,9 @@
-# Include your project-specific ignores in this file
-# Read about how to use .gitignore: https://help.github.com/articles/ignoring-files
-# Useful .gitignore templates: https://github.com/github/gitignore
 node_modules
 dist
-.cache
+.cache
+.idea
+.vscode
+.DS_Store
+.next
+tsconfig.tsbuildinfo
+.env

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "contracts/lib/forge-std"]
+	path = contracts/lib/forge-std
+	url = https://github.com/foundry-rs/forge-std
+[submodule "contracts/lib/openzeppelin-contracts"]
+	path = contracts/lib/openzeppelin-contracts
+	url = https://github.com/OpenZeppelin/openzeppelin-contracts

.oxfmtrc.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "printWidth": 120,
+  "experimentalSortImports": {
+    "groups": ["builtin", "external", "internal", ["parent", "sibling", "index"]],
+    "internalPattern": ["@/"],
+    "newlinesBetween": true
+  }
+}

.oxlintrc.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "ignorePatterns": ["next-env.d.ts", "contracts/"],
+  "plugins": ["typescript", "import", "unicorn", "react", "vitest"],
+  "categories": {
+    "correctness": "error",
+    "suspicious": "error"
+  },
+  "rules": {
+    "max-lines": [
+      "error",
+      {
+        "max": 1000,
+        "skipComments": true,
+        "skipBlankLines": true
+      }
+    ],
+    "max-lines-per-function": [
+      "error",
+      {
+        "max": 400,
+        "skipComments": true,
+        "skipBlankLines": true
+      }
+    ],
+    "no-nested-ternary": "error",
+    "no-unneeded-ternary": "error",
+    "no-restricted-imports": [
+      "error",
+      {
+        "patterns": [
+          {
+            "regex": "^\\.\\./\\.\\./",
+            "message": "Use absolute imports with @/* alias instead of relative paths"
+          }
+        ]
+      }
+    ],
+    "typescript/no-explicit-any": "error",
+    "typescript/explicit-function-return-type": "warn",
+    "typescript/no-floating-promises": "off",
+    "typescript/unbound-method": "off",
+    "unicorn/prefer-node-protocol": "error",
+    "react/react-in-jsx-scope": "off",
+    "import/no-unassigned-import": [
+      "error",
+      {
+        "allow": ["**/*.css"]
+      }
+    ]
+  }
+}

.prettierignore

@@ -0,0 +1 @@
+contracts/lib/

.solhint.json

@@ -0,0 +1,13 @@
+{
+  "extends": "solhint:recommended",
+  "rules": {
+    "func-visibility": ["warn", { "ignoreConstructors": true }],
+    "max-line-length": ["warn", 120],
+    "import-path-check": "off",
+    "use-natspec": "off",
+    "gas-custom-errors": "error",
+    "gas-indexed-events": "error",
+    "gas-increment-by-one": "error",
+    "immutable-vars-naming": "error"
+  }
+}

README.md

@@ -1 +1,55 @@
-# NIL Faucet
+# Nillion Faucet
+
+A testnet faucet for requesting NIL tokens for development and testing on the Nillion network.
+
+## Live
+
+The faucet is available at [faucet.sepolia.nillion.network](https://faucet.sepolia.nillion.network).
+
+## Getting Started
+
+If you're unsure where to start, head over to [docs.nillion.com](https://docs.nillion.com).
+
+## Dependencies
+
+- [Node.js](https://nodejs.org/) 24+
+- [pnpm](https://pnpm.io/) 10+
+- [Foundry](https://book.getfoundry.sh/) (for smart contracts)
+
+## Development
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to view the faucet locally.
+
+### Commands
+
+| Command              | Description                |
+| -------------------- | -------------------------- |
+| `pnpm dev`           | Start development server   |
+| `pnpm build`         | Build for production       |
+| `pnpm fix`           | Format and lint everything |
+| `pnpm fix:web`       | Format and lint web app    |
+| `pnpm fix:contracts` | Format and lint Solidity   |
+
+## Contributing
+
+We welcome contributions! Here's how you can get involved:
+
+- 🐛 Report bugs and submit feature requests
+- 🔧 Submit pull requests
+- 📖 Improve documentation
+- 💬 Join discussions
+- ⭐ Star the repository
+
+## Getting Help
+
+- [Create an Issue](https://github.com/NillionNetwork/nil-anvil/issues/new/choose)
+- [Join our Discord](https://discord.com/invite/nillionnetwork)
+
+## License
+
+This project is licensed under the [MIT License](./LICENSE).

components.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "registries": {}
+}

contracts/README.md

@@ -1,21 +1,91 @@
 # NIL Faucet Smart Contract
 
-## Usage
+## Build
 
-### Build
+```shell
+forge build
+```
+
+## Test
+
+```shell
+forge test
+```
+
+## Format
+
+```shell
+forge fmt
+```
+
+## Deploy to Sepolia
+
+### 1. Set Environment Variables
+
+```shell
+# Required
+export PRIVATE_KEY=your_private_key_without_0x_prefix
+export NIL_TOKEN_ADDRESS=0x...  # NIL token address on Sepolia
+
+# Optional (defaults shown)
+export DRIP_AMOUNT=1000000      # 1 NIL (6 decimals)
+export COOLDOWN_SECONDS=3600   # 1 hour
+```
+
+### 2. Deploy and Verify
 
 ```shell
-$ forge build
+forge script script/DeployFaucet.s.sol:DeployFaucet \
+  --rpc-url https://sepolia.infura.io/v3/YOUR_INFURA_KEY \
+  --broadcast \
+  --verify \
+  --etherscan-api-key YOUR_ETHERSCAN_API_KEY
+```
+
+The script will output the deployed faucet address.
+
+### 3. Update Frontend Config
+
+Add the deployed address to your `.env`:
+
+```
+NEXT_PUBLIC_FAUCET_ADDRESS_SEPOLIA=0x...deployed_address...
 ```
 
-### Format
+### 4. Fund the Faucet
+
+Transfer NIL tokens to the faucet contract address. The faucet needs tokens to distribute.
+
+## Admin Functions
+
+The deployer becomes the contract owner and can call these functions:
+
+| Function                     | Description                   |
+| ---------------------------- | ----------------------------- |
+| `setDripAmount(uint256)`     | Change tokens per claim       |
+| `setCooldown(uint256)`       | Change seconds between claims |
+| `pause()`                    | Pause all claims              |
+| `unpause()`                  | Resume claims                 |
+| `withdraw(address, uint256)` | Withdraw tokens from faucet   |
+
+Example using cast:
 
 ```shell
-$ forge fmt
+# Pause the faucet
+cast send $FAUCET_ADDRESS "pause()" --private-key $PRIVATE_KEY --rpc-url $RPC_URL
+
+# Change drip amount to 5 NIL
+cast send $FAUCET_ADDRESS "setDripAmount(uint256)" 5000000 --private-key $PRIVATE_KEY --rpc-url $RPC_URL
 ```
 
-### Deploy
+## Security
+
+For production deployments, consider using a hardware wallet:
 
 ```shell
-$ forge script script/DeployFaucet.s.sol:DeployFaucet --rpc-url <your_rpc_url> --private-key <your_private_key>
+forge script script/DeployFaucet.s.sol:DeployFaucet \
+  --rpc-url $RPC_URL \
+  --ledger \
+  --broadcast \
+  --verify
 ```

contracts/foundry.toml

@@ -4,6 +4,4 @@ out = "out"
 libs = ["lib"]
 
 # See more config options https://github.com/foundry-rs/foundry/blob/master/crates/config/README.md#all-options
-remappings = [
-  "@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/"
-]
+remappings = ["@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/"]