Building a Production Grade Testnet Faucet With Typescript, Redis and Nextjs

Whether you are a new developer or a seasoned developer, you have definitely wagged your fingers at how hard it is to get testnet tokens. From the lack of faucet solutions to strigent requirements for existing solutions. In this tutorial, I will teach you how to build your own faucet be it for your team or personal use. Okay, but I have no idea what a faucet is in crypto Thats totally okay too. Think of the traditional faucet that discharges water whenever you need it so also does crypto faucets discharge testnet tokens when you need it. A textbook definition would be A crypto faucet is a platform that provides users with small quantities of cryptocurrency for completing simple tasks. These tasks could range from viewing an ad, participating in a survey, or even just proving you're a human by completing a captcha. The quantities provided by these faucets are often small, akin to the drops from a leaky faucet, hence the name. Testnet tokens are essentially test(or fake money) we use to transact or pay for transactions on the test environments of blockchain solutions. it provides a risk free environment for developers to deploy, test and explore smart contracts on the blockchain. Sounds good, but if its a crypto faucet, why do we need Typescript, Nextjs and Redis There are different approaches to building faucets for testnet tokens. Some solutions utilize a smart contract for disbursement of tokens but his approach while good, has some limitations. The most glaring disadvantage of using a smart contract for your faucet lies in the immutable nature of smart contracts themselves. Once deployed, the contract cannot be modified and this presents a roadblock for you if you need to upgrade, change configuration or even correct errors in implementation. The best approach to building faucet, is to implement as a webApp and use web3 frameworks like EtherJs to interact with the blockchain. This gives us the necessary flexibility needed to be able to upgrade and modify our faucet in the future including setting up anti-sybil protection. In this tutorial, we will be building a nextjs application with typescript and using redis to rate-limit users and also protect our faucet from sybil attacks. Our faucet will be able to disburse testnet ETH and also, ERC20 tokens. Tech stack NextJS 13 with App Router Typescript Ether.js for blockchain interactions Redis for rate limiting and data persistence Tailwind css for styling shadcn for ui components hcaptcha for bot protection Architecture To give a brief overview of how our faucet is built: frontend: React components built with Nextjs backend: Nextjs api routes for handling claims. blockchain interactions: Ethers.js for sending transactions. data storage: Redis for storing claim history and rate limiting. Setting up your environment phew! finally, lets start hacking. The first thing we need to do is to create our working directory. So on the terminal, we run mkdir faucet

cd faucet Then initialize a nextjs project npx create-next-app@latest you can just hit enter to select all default options Next, we install shadcn and install all the components we will be using. you can check out the documentation to learn more about shadcn. npx shadcn@latest init -d npx shadcn@latest add button form input label select toast use-toast Now, we add other dependencies we will be needing. npm i ethers@5.7.2 ioredis rate-limiter-flexible Your project should look exactly like mine if you’ve followed the above steps. Building the Homepage Go to the page.tsx file in the app folder, delete the existing boilerplate code and replace it with the code below. we are keeping our homepage cutesy(depending on the year you read this, forgive the cringeness) but simple. import FaucetForm from "@/components/FaucetForm"; import { InfoIcon } from "lucide-react";

export default function Home() { return ( EVM Token Faucet Claim Testnet tokens every 24 hours for your development and testing needs.

Please note: These are testnet-only tokens with no real economic value.

); } As you could already predict, the next component we have to build is the FaucetForm component. FaucetForm.tsx In the components folder, create a new file called FaucetForm.tsx and paste in the code below. "use client";

import { useState } from "react"; import { zodResolver } from "@hookform/resolvers/zod"; import { useForm } from "react-hook-form"; import { z } from "zod"; import { Form, FormControl, FormField, FormItem, FormMessage, } from "@/components/ui/form"; import { Input } from "@/components/ui/input"; import { Button } from "./ui/button"; import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from "./ui/select";

export default function FaucetForm() { const [isLoading, setIsLoading] = useState(false);

const formSchema = z.object({ address: z .string() .regex(/^0x[a-fA-F0-9]{40}$/, "Invalid Ethereum address"), token: z.enum(["ETH", "PIRONTOKEN"]), });

const form = useForm >({ resolver: zodResolver(formSchema), defaultValues: { address: "", token: "ETH", }, });

return ( {})} className="space-y-4"> ( 0.01 ETH 10 PIRONTOKEN )} />

( )} />

{isLoading ? "Processing..." : `Send ${ form.watch("token") === "ETH" ? "0.01 ETH" : "10 PIRONTOKEN" }`} ); } This basic form utilizes the react-hook-form and zod which is provisioned for us from shadcn. The form allows users to choose between claiming ETH or our ERC20 token. On your browser, the faucet should look like below. Now, at the moment, our faucet doesnt do anything because no logic has been implemented. Lets start off by adding our environment variables. env.local In the root of the project, we create a file called env.local and we add the following environment variables. I will be using Morph’s rpc url(you can use that of any chain of your choice). Piron token is the name of the ERC20 token we are using for the sake of this tutorial. For the REDIS_URL, you can get it by creating an account on redis cloud and replacing the boiler text with your password and public endpoint. Finally for the captcha keys, visit hcaptcha and create a site, set type to bot management, captcha behaviour to always challenge and treshold to auto. MORPH_RPC_URL=https://rpc-quicknode-holesky.morphl2.io PRIVATE_KEY=your-private-key PIRON_TOKEN_ADDRESS=bleh

REDIS_URL=redis://default:your-password@your-public-endpoint

NEXT_PUBLIC_HCAPTCHA_SITE_KEY=site-public-key HCAPTCHA_SECRET_KEY=your-secret-key redis.ts Next, lets create a Redis client. In the lib folder, create a new file called redis.ts. The ioredis library helps us connect and interact with the redis server. The code below initializes the redis client and limits the amount of retries (in connecting to the server) to three while increasing the time between each retry from 50ms to 2 seconds. import Redis from "ioredis";

if (!process.env.REDIS_URL) { throw new Error("REDIS_URL is not defined in the environment variables"); }

redis.on("error", (error) => { console.error("Redis Client Error:", error); });

redis.on("connect", () => { console.log("Connected to Redis"); });

export default redis; rate-limiter.ts The next logic we need to work on, is the rate limiter. Still in the lib folder, create another file called rate-limiter.ts and paste in the code below. The rate-limiter-flexible library uses redis as the backend to limit the amount of request (8) a specific ip address can make within a specified time window (per hour). this is done to prevent abuse and also bots from draining our faucet. import { Redis } from "ioredis"; import { RateLimiterRedis } from "rate-limiter-flexible";

const redisClient = new Redis(process.env.REDIS_URL as string);

export const rateLimiter = new RateLimiterRedis({ storeClient: redisClient, keyPrefix: "ratelimit", points: 8, // Number of requests duration: 60 * 60, // Per hour });

export async function limitRate(ip: string): Promise { try { await rateLimiter.consume(ip); return true; // Request allowed } catch (rejRes) { return false; // Request blocked } } route.ts After setting up our redis client and rate limiter, we can finally start building the backend for our faucet. In the app folder, create a folder named api and append a file called route.ts. This is where we will be building the api routes for handling claims. In the route.ts file, paste the code below. import { NextRequest } from "next/server"; import { ethers } from "ethers"; import redis from "../../lib/redis"; import { limitRate } from "../../lib/rate-limiter";

const ETH_FAUCET_AMOUNT = ethers.utils.parseEther("0.03"); const PIRON_FAUCET_AMOUNT = ethers.utils.parseUnits("10", 18); const COOLDOWN_PERIOD = 12 * 60 * 60; // 12 hours in seconds

const provider = new ethers.providers.JsonRpcProvider({ url: process.env.MORPH_RPC_URL as string, skipFetchSetup: true, });

const wallet = new ethers.Wallet(process.env.PRIVATE_KEY as string, provider);

const PIRON_TOKEN_ADDRESS = process.env.PIRON_TOKEN_ADDRESS as string;

const pironTokenABI = [ "function transfer(address to, uint256 amount) returns (bool)", ]; const pironTokenContract = new ethers.Contract( PIRON_TOKEN_ADDRESS, pironTokenABI, wallet );

let lastNonce = -1;

async function getNextNonce() { const currentNonce = await wallet.getTransactionCount("pending"); lastNonce = Math.max(lastNonce, currentNonce - 1); return lastNonce + 1; }

async function verifyCaptcha(captchaResponse: string): Promise { const verifyUrl = `https://hcaptcha.com/siteverify`; const response = await fetch(verifyUrl, { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: `response=${captchaResponse}&secret=${process.env.HCAPTCHA_SECRET_KEY}`, }); const data = await response.json(); return data.success; }

export async function POST(request: NextRequest) { const ip = request.ip || "unknown"; const isAllowed = await limitRate(ip); if (!isAllowed) { return Response.json({ error: "Rate limit exceeded" }, { status: 429 }); } const { address, token, captcha } = await request.json();

if (!ethers.utils.isAddress(address)) { return Response.json( { error: "Invalid Ethereum address" }, { status: 400 } ); }

if (!["ETH", "PIRONTOKEN"].includes(token)) { return Response.json({ error: "Invalid token selection" }, { status: 400 }); }

const isCaptchaValid = await verifyCaptcha(captcha); if (!isCaptchaValid) { return Response.json({ error: "Invalid captcha" }, { status: 400 }); }

try { const lastClaimTime = await redis.get(`lastClaim:${address}`); const now = Math.floor(Date.now() / 1000);

if (lastClaimTime) { const timeSinceLastClaim = now - parseInt(lastClaimTime); if (timeSinceLastClaim < COOLDOWN_PERIOD) { const remainingTime = Math.ceil( (COOLDOWN_PERIOD - timeSinceLastClaim) / 60 ); return Response.json( { error: `Please wait ${remainingTime} minutes before claiming again`, }, { status: 429 } ); } }

const nonce = await getNextNonce();

let tx; if (token === "ETH") { tx = await wallet.sendTransaction({ to: address, value: ETH_FAUCET_AMOUNT, nonce: nonce, gasPrice: await provider.getGasPrice(), gasLimit: 21000, }); } else if (token === "PIRONTOKEN") { tx = await pironTokenContract.transfer(address, PIRON_FAUCET_AMOUNT, { nonce: nonce, gasPrice: await provider.getGasPrice(), gasLimit: 100000, }); }

await tx.wait(1);

// Record the claim in Redis with automatic expiration await redis.set(`lastClaim:${address}`, now, "EX", COOLDOWN_PERIOD);

return Response.json({ success: true, txHash: tx.hash }); } catch (error) { console.error("Error processing claim:", error);

if (error instanceof Error) { if (error.message.includes("already known")) { return Response.json( { error: "Transaction already submitted. Please wait and try again later.", }, { status: 409 } ); } if (error.message.includes("replacement fee too low")) { return Response.json( { error: "Network is busy. Please try again later." }, { status: 503 } ); } }

return Response.json( { error: "An unexpected error occurred" }, { status: 500 } ); } } The code above allows a user to claim once every 12 hours. it creates an instance of a wallet by using our rpc_url(we are using morph in this example) and private key. Next, we create an instance of the piron token contract(our ERC20 token) by using ethers and passing in the contract address, abi and the wallet we just created as arguments. for the getNextNonce function, Ethereum transactions require a nonce to prevent replay attacks. This function ensures that the correct nonce is used for transactions by tracking the last nonce and incrementing it. It is also useful in situations where there is network congestion. The verifyCaptcha function sends a post request to hCaptcha to verify the user’s captcha response. The function returns a boolean value. The main function which handles the claim, performs a number of checks before allowing the user to claim any token. First, it takes the ip address of the user to check if the user's IP has exceeded the rate limit. If they have, the request is rejected with a 429 Too Many Requests status. next, it takes the data sent over from the frontend and ensures they’re valid before calling the verifyCaptcha function which we talked about earlier. If the captcha is verified, it checks for the lastClaimTime of the user by calling our redis database to ensure that the user is not abusing the faucet. If the time has exceeded the cooldown period , it proceeds to send the testnet tokens. Sending native ETH and ERC20 tokens require different methods as demonstrated in the code above. finally, we set the last claim time for the user to the current time and add some error handling. After this is done, your file structure should look like this. FaucetForm.tsx Back in our faucet form component, its time to connect the UI to the api. we start by installing one more dependency npm i @hcaptcha/react-hcaptcha Next we create a captcha ref and destructure toast from the use-toast hook. import { useToast } from "@/hooks/use-toast"; import { useForm } from "react-hook-form"; import { z } from "zod"; import { Form, FormControl, FormField, FormItem, FormMessage, } from "@/components/ui/form"; import { Input } from "@/components/ui/input"; import { ToastAction } from "./ui/toast"; import HCaptcha from "@hcaptcha/react-hcaptcha"; import { Button } from "./ui/button"; import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from "./ui/select";

export default function FaucetForm() { const [isLoading, setIsLoading] = useState(false); const { toast } = useToast(); const captchaRef = useRef (null); const executeCaptcha = () => { if (captchaRef.current) { captchaRef.current.execute(); } };

const onCaptchaVerify = async (token: string) => { if (!token) { toast({ variant: "destructive", title: "Captcha verification failed", description: "Please try again.", }); return; }

const result = await response.json();

if (response.ok) { toast({ variant: "success", title: "Faucet claim successful!", action: ( { window.open( `https://explorer-holesky.morphl2.io/tx/${result.txHash}` ); }} > View transaction on Explorer ), }); } else { toast({ variant: "destructive", title: "Could not process your claim", description: `${result.error}`, }); } } catch (error) { toast({ variant: "destructive", description: error instanceof Error ? error.message : "An error occurred. Please try again.", }); } finally { setIsLoading(false); if (captchaRef.current) { captchaRef.current.resetCaptcha(); } } }; The handleSubmit function takes in an argument called data which contains both the form data and also the token from captcha. Next, it sends a POST request to the api route, passing in the data as the request body. if the request is successful, it displays a success modal. The toast component was modified to include a success variant so in your components/ui/toast replace the existing code with this "use client";

import * as React from "react"; import * as ToastPrimitives from "@radix-ui/react-toast"; import { cva, type VariantProps } from "class-variance-authority"; import { X } from "lucide-react";

import { cn } from "@/lib/utils";

const ToastProvider = ToastPrimitives.Provider;

const ToastViewport = React.forwardRef , React.ComponentPropsWithoutRef >(({ className, ...props }, ref) => ( )); ToastViewport.displayName = ToastPrimitives.Viewport.displayName;

const toastVariants = cva( "group pointer-events-auto relative flex w-full items-center justify-between space-x-4 overflow-hidden rounded-md border p-6 pr-8 shadow-lg transition-all data-[swipe=cancel]:translate-x-0 data-[swipe=end]:translate-x-[var(--radix-toast-swipe-end-x)] data-[swipe=move]:translate-x-[var(--radix-toast-swipe-move-x)] data-[swipe=move]:transition-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[swipe=end]:animate-out data-[state=closed]:fade-out-80 data-[state=closed]:slide-out-to-right-full data-[state=open]:slide-in-from-top-full data-[state=open]:sm:slide-in-from-bottom-full", { variants: { variant: { default: "border bg-background text-foreground", destructive: "destructive group border-destructive bg-destructive text-destructive-foreground", success: "border border-green-600 bg-green-100 text-green-800 dark:border-green-500 dark:bg-green-900 dark:text-green-200", }, }, defaultVariants: { variant: "default", }, } );

const Toast = React.forwardRef , React.ComponentPropsWithoutRef & VariantProps >(({ className, variant, ...props }, ref) => { return ( ); }); Toast.displayName = ToastPrimitives.Root.displayName;

const ToastAction = React.forwardRef , React.ComponentPropsWithoutRef >(({ className, ...props }, ref) => ( <ToastPrimitives.Action ref={ref} className={cn( "inline-flex h-8 shrink-0 items-center justify-center rounded-md border bg-transparent px-3 text-sm font-medium ring-offset-background transition-colors hover:bg-opacity-10 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 group-[.destructive]:border-muted/40 group-[.destructive]:hover:border-destructive/30 group-[.destructive]:hover:bg-destructive group-[.destructive]:hover:text-destructive-foreground group-[.destructive]:focus:ring-destructive", className )} {...props} /> )); ToastAction.displayName = ToastPrimitives.Action.displayName;

const ToastClose = React.forwardRef , React.ComponentPropsWithoutRef >(({ className, ...props }, ref) => ( <ToastPrimitives.Close ref={ref} className={cn( "absolute right-2 top-2 rounded-md p-1 text-foreground/50 opacity-0 transition-opacity hover:text-foreground focus:opacity-100 focus:outline-none focus:ring-2 group-hover:opacity-100 group-[.destructive]:text-red-300 group-[.destructive]:hover:text-red-50 group-[.destructive]:focus:ring-red-400 group-[.destructive]:focus:ring-offset-red-600", className )} toast-close="" {...props} > )); ToastClose.displayName = ToastPrimitives.Close.displayName;

const ToastTitle = React.forwardRef , React.ComponentPropsWithoutRef >(({ className, ...props }, ref) => ( )); ToastTitle.displayName = ToastPrimitives.Title.displayName;

const ToastDescription = React.forwardRef , React.ComponentPropsWithoutRef >(({ className, ...props }, ref) => ( )); ToastDescription.displayName = ToastPrimitives.Description.displayName;

type ToastProps = React.ComponentPropsWithoutRef ;

type ToastActionElement = React.ReactElement ;

export { type ToastProps, type ToastActionElement, ToastProvider, ToastViewport, Toast, ToastTitle, ToastDescription, ToastClose, ToastAction, }; Finally, your updated FaucetForm should look like this "use client";

import { useRef, useState } from "react"; import { zodResolver } from "@hookform/resolvers/zod"; import { useForm } from "react-hook-form"; import { useToast } from "@/hooks/use-toast"; import { z } from "zod"; import { Form, FormControl, FormField, FormItem, FormMessage, } from "@/components/ui/form"; import { Input } from "@/components/ui/input"; import { Button } from "./ui/button"; import { ToastAction } from "./ui/toast"; import HCaptcha from "@hcaptcha/react-hcaptcha"; import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from "./ui/select";

export default function FaucetForm() { const [isLoading, setIsLoading] = useState(false); const { toast } = useToast(); const captchaRef = useRef (null);

const formSchema = z.object({ address: z .string() .regex(/^0x[a-fA-F0-9]{40}$/, "Invalid Ethereum address"), token: z.enum(["ETH", "PIRONTOKEN"]), });

const form = useForm >({ resolver: zodResolver(formSchema), defaultValues: { address: "", token: "ETH", }, });

const executeCaptcha = () => { if (captchaRef.current) { captchaRef.current.execute(); } };

const onCaptchaVerify = async (token: string) => { if (!token) { toast({ variant: "destructive", title: "Captcha verification failed", description: "Please try again.", }); return; }

const formData = form.getValues(); await handleSubmit({ ...formData, captcha: token }); };

const handleSubmit = async ( data: z.infer & { captcha: string } ) => { setIsLoading(true); try { const response = await fetch("/api/claim", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify(data), });

const result = await response.json();

if (response.ok) { toast({ variant: "success", title: "Faucet claim successful!", action: ( { window.open( `https://explorer-holesky.morphl2.io/tx/${result.txHash}` ); }} > View transaction on Explorer ), }); } else { toast({ variant: "destructive", title: "Could not process your claim", description: `${result.error}`, }); } } catch (error) { toast({ variant: "destructive", description: error instanceof Error ? error.message : "An error occurred. Please try again.", }); } finally { setIsLoading(false); if (captchaRef.current) { captchaRef.current.resetCaptcha(); } } };

return ( ( 0.03 ETH 10 PIRON TOKEN )} />

( )} />

{isLoading ? "Processing..." : `Send ${ form.watch("token") === "ETH" ? "0.01 ETH" : "10 PIRON TOKEN" }`}

); } whew! now lets test our faucet to ensure all is working well. Conclusion Building a production grade faucet takes a lot of work and considerations(eg security) and in this tutorial, we have covered basically all aspects of building one. You could modify this faucet to serve whatever need you have whether as a chain, project or for personal use. If you have any issues while replicating this project, reach out to me (or drop a comment) on telegram @ernestelijah. Whether you are a new developer or a seasoned developer, you have definitely wagged your fingers at how hard it is to get testnet tokens. From the lack of faucet solutions to strigent requirements for existing solutions. In this tutorial, I will teach you how to build your own faucet be it for your team or personal use. Okay, but I have no idea what a faucet is in crypto Thats totally okay too. Think of the traditional faucet that discharges water whenever you need it so also does crypto faucets discharge testnet tokens when you need it. A textbook definition would be A crypto faucet is a platform that provides users with small quantities of cryptocurrency for completing simple tasks. These tasks could range from viewing an ad, participating in a survey, or even just proving you're a human by completing a captcha. The quantities provided by these faucets are often small, akin to the drops from a leaky faucet, hence the name. A crypto faucet is a platform that provides users with small quantities of cryptocurrency for completing simple tasks. These tasks could range from viewing an ad, participating in a survey, or even just proving you're a human by completing a captcha. The quantities provided by these faucets are often small, akin to the drops from a leaky faucet, hence the name. Testnet tokens are essentially test(or fake money) we use to transact or pay for transactions on the test environments of blockchain solutions. it provides a risk free environment for developers to deploy, test and explore smart contracts on the blockchain. Sounds good, but if its a crypto faucet, why do we need Typescript, Nextjs and Redis There are different approaches to building faucets for testnet tokens. Some solutions utilize a smart contract for disbursement of tokens but his approach while good, has some limitations. The most glaring disadvantage of using a smart contract for your faucet lies in the immutable nature of smart contracts themselves. Once deployed, the contract cannot be modified and this presents a roadblock for you if you need to upgrade, change configuration or even correct errors in implementation. The best approach to building faucet, is to implement as a webApp and use web3 frameworks like EtherJs to interact with the blockchain. This gives us the necessary flexibility needed to be able to upgrade and modify our faucet in the future including setting up anti-sybil protection. In this tutorial, we will be building a nextjs application with typescript and using redis to rate-limit users and also protect our faucet from sybil attacks. Our faucet will be able to disburse testnet ETH and also, ERC20 tokens. Tech stack NextJS 13 with App Router Typescript Ether.js for blockchain interactions Redis for rate limiting and data persistence Tailwind css for styling shadcn for ui components hcaptcha for bot protection NextJS 13 with App Router Typescript Ether.js for blockchain interactions Redis for rate limiting and data persistence Tailwind css for styling shadcn for ui components hcaptcha for bot protection Architecture To give a brief overview of how our faucet is built: frontend: React components built with Nextjs backend: Nextjs api routes for handling claims. blockchain interactions: Ethers.js for sending transactions. data storage: Redis for storing claim history and rate limiting. frontend: React components built with Nextjs backend: Nextjs api routes for handling claims. blockchain interactions: Ethers.js for sending transactions. data storage: Redis for storing claim history and rate limiting. Setting up your environment phew! finally, lets start hacking. The first thing we need to do is to create our working directory. So on the terminal, we run mkdir faucet

cd faucet mkdir faucet

cd faucet Then initialize a nextjs project npx create-next-app@latest npx create-next-app@latest you can just hit enter to select all default options you can just hit enter to select all default options Next, we install shadcn and install all the components we will be using. you can check out the documentation to learn more about shadcn. documentation npx shadcn@latest init -d npx shadcn@latest init -d npx shadcn@latest add button form input label select toast use-toast npx shadcn@latest add button form input label select toast use-toast Now, we add other dependencies we will be needing. npm i ethers@5.7.2 ioredis rate-limiter-flexible npm i ethers@5.7.2 ioredis rate-limiter-flexible Your project should look exactly like mine if you’ve followed the above steps. Building the Homepage Go to the page.tsx file in the app folder, delete the existing boilerplate code and replace it with the code below. we are keeping our homepage cutesy(depending on the year you read this, forgive the cringeness) but simple. import FaucetForm from "@/components/FaucetForm"; import { InfoIcon } from "lucide-react";

export default function Home() { return ( EVM Token Faucet Claim Testnet tokens every 24 hours for your development and testing needs.

Please note: These are testnet-only tokens with no real economic value.

); } import FaucetForm from "@/components/FaucetForm"; import { InfoIcon } from "lucide-react";

export default function Home() { return ( EVM Token Faucet Claim Testnet tokens every 24 hours for your development and testing needs.

Please note: These are testnet-only tokens with no real economic value.

); } As you could already predict, the next component we have to build is the FaucetForm component. FaucetForm FaucetForm.tsx In the components folder, create a new file called FaucetForm.tsx and paste in the code below. FaucetForm.tsx "use client";

import { useState } from "react"; import { zodResolver } from "@hookform/resolvers/zod"; import { useForm } from "react-hook-form"; import { z } from "zod"; import { Form, FormControl, FormField, FormItem, FormMessage, } from "@/components/ui/form"; import { Input } from "@/components/ui/input"; import { Button } from "./ui/button"; import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from "./ui/select";

export default function FaucetForm() { const [isLoading, setIsLoading] = useState(false);

const formSchema = z.object({ address: z .string() .regex(/^0x[a-fA-F0-9]{40}$/, "Invalid Ethereum address"), token: z.enum(["ETH", "PIRONTOKEN"]), });

const form = useForm >({ resolver: zodResolver(formSchema), defaultValues: { address: "", token: "ETH", }, });

return ( {})} className="space-y-4"> ( 0.01 ETH 10 PIRONTOKEN )} />

( )} />

{isLoading ? "Processing..." : `Send ${ form.watch("token") === "ETH" ? "0.01 ETH" : "10 PIRONTOKEN" }`} ); } "use client";

import { useState } from "react"; import { zodResolver } from "@hookform/resolvers/zod"; import { useForm } from "react-hook-form"; import { z } from "zod"; import { Form, FormControl, FormField, FormItem, FormMessage, } from "@/components/ui/form"; import { Input } from "@/components/ui/input"; import { Button } from "./ui/button"; import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from "./ui/select";

export default function FaucetForm() { const [isLoading, setIsLoading] = useState(false);

const formSchema = z.object({ address: z .string() .regex(/^0x[a-fA-F0-9]{40}$/, "Invalid Ethereum address"), token: z.enum(["ETH", "PIRONTOKEN"]), });

const form = useForm >({ resolver: zodResolver(formSchema), defaultValues: { address: "", token: "ETH", }, });

return ( {})} className="space-y-4"> ( 0.01 ETH 10 PIRONTOKEN )} />

( )} />

{isLoading ? "Processing..." : `Send ${ form.watch("token") === "ETH" ? "0.01 ETH" : "10 PIRONTOKEN" }`} ); } This basic form utilizes the react-hook-form and zod which is provisioned for us from shadcn. The form allows users to choose between claiming ETH or our ERC20 token. On your browser, the faucet should look like below. Now, at the moment, our faucet doesnt do anything because no logic has been implemented. Lets start off by adding our environment variables. env.local In the root of the project, we create a file called env.local and we add the following environment variables. I will be using Morph’s rpc url(you can use that of any chain of your choice). Piron token is the name of the ERC20 token we are using for the sake of this tutorial. env.local For the REDIS_URL , you can get it by creating an account on redis cloud and replacing the boiler text with your password and public endpoint. REDIS_URL redis cloud Finally for the captcha keys, visit hcaptcha and create a site, set type to bot management, captcha behaviour to always challenge and treshold to auto. hcaptcha MORPH_RPC_URL=https://rpc-quicknode-holesky.morphl2.io PRIVATE_KEY=your-private-key PIRON_TOKEN_ADDRESS=bleh

REDIS_URL=redis://default:your-password@your-public-endpoint

NEXT_PUBLIC_HCAPTCHA_SITE_KEY=site-public-key HCAPTCHA_SECRET_KEY=your-secret-key MORPH_RPC_URL=https://rpc-quicknode-holesky.morphl2.io PRIVATE_KEY=your-private-key PIRON_TOKEN_ADDRESS=bleh

REDIS_URL=redis://default:your-password@your-public-endpoint

NEXT_PUBLIC_HCAPTCHA_SITE_KEY=site-public-key HCAPTCHA_SECRET_KEY=your-secret-key redis.ts Next, lets create a Redis client. In the lib folder, create a new file called redis.ts . The ioredis library helps us connect and interact with the redis server. The code below initializes the redis client and limits the amount of retries (in connecting to the server) to three while increasing the time between each retry from 50ms to 2 seconds. redis.ts import Redis from "ioredis";

if (!process.env.REDIS_URL) { throw new Error("REDIS_URL is not defined in the environment variables"); }

redis.on("error", (error) => { console.error("Redis Client Error:", error); });

redis.on("connect", () => { console.log("Connected to Redis"); });

export default redis; import Redis from "ioredis";

if (!process.env.REDIS_URL) { throw new Error("REDIS_URL is not defined in the environment variables"); }

redis.on("error", (error) => { console.error("Redis Client Error:", error); });

redis.on("connect", () => { console.log("Connected to Redis"); });

export default redis; rate-limiter.ts The next logic we need to work on, is the rate limiter. Still in the lib folder, create another file called rate-limiter.ts and paste in the code below. The rate-limiter-flexible library uses redis as the backend to limit the amount of request (8) a specific ip address can make within a specified time window (per hour). this is done to prevent abuse and also bots from draining our faucet. rate-limiter.ts rate-limiter-flexible import { Redis } from "ioredis"; import { RateLimiterRedis } from "rate-limiter-flexible";

const redisClient = new Redis(process.env.REDIS_URL as string);

export const rateLimiter = new RateLimiterRedis({ storeClient: redisClient, keyPrefix: "ratelimit", points: 8, // Number of requests duration: 60 * 60, // Per hour });

export async function limitRate(ip: string): Promise { try { await rateLimiter.consume(ip); return true; // Request allowed } catch (rejRes) { return false; // Request blocked } } import { Redis } from "ioredis"; import { RateLimiterRedis } from "rate-limiter-flexible";

const redisClient = new Redis(process.env.REDIS_URL as string);

export const rateLimiter = new RateLimiterRedis({ storeClient: redisClient, keyPrefix: "ratelimit", points: 8, // Number of requests duration: 60 * 60, // Per hour });

export async function limitRate(ip: string): Promise { try { await rateLimiter.consume(ip); return true; // Request allowed } catch (rejRes) { return false; // Request blocked } } route.ts After setting up our redis client and rate limiter, we can finally start building the backend for our faucet. In the app folder, create a folder named api and append a file called route.ts . This is where we will be building the api routes for handling claims. In the route.ts file, paste the code below. api route.ts route.ts import { NextRequest } from "next/server"; import { ethers } from "ethers"; import redis from "../../lib/redis"; import { limitRate } from "../../lib/rate-limiter";