// GoodSDKs/packages/citizen-sdk/src/utils/triggerFaucet.ts import type { Address, PublicClient, WalletClient, Chain, Account } from "viem" import { waitForTransactionReceipt } from "viem/actions" import { Envs, faucetABI, chainConfigs } from "../constants" import { SupportedChains } from "../types" export type TriggerFaucetResult = | "skipped" // throttled, not eligible, or balance sufficient | "topped_via_contract" // success via on-chain call | "topped_via_api" // success via backend fallback | "error" // tried and failed export interface TriggerFaucetParams { chainId: SupportedChains account: Address publicClient: PublicClient walletClient: WalletClient faucetAddress: Address env: string // "production" | "staging" | etc. throttleMs?: number // default 1h } /** * Checks if the user has sufficient gas balance to claim UBI. * @param chainId - The chain ID * @param account - User's wallet address * @param publicClient - Viem public client * @param faucetAddress - Faucet contract address * @param toppingAmount - Amount the faucet tops up * @param minTopping - Minimum topping percentage * @returns True if the user can claim, false otherwise. * @throws If gas price cannot be determined or balance check fails. */ async function canClaim( chainId: SupportedChains, account: Address, publicClient: PublicClient, faucetAddress: Address, toppingAmount: bigint, minTopping: number, ): Promise { const fees = await publicClient .estimateFeesPerGas() .catch((error) => console.log("Error estimating fees per gas:", error)) const gasPrice = fees?.maxFeePerGas ?? fees?.gasPrice ?? chainConfigs[chainId]?.defaultGasPrice if (!gasPrice) { throw new Error( "Cannot determine gasPrice for the current connected chain.", ) } const claimGasBuffer = chainConfigs[chainId]?.claimGasBuffer ?? undefined if (claimGasBuffer == null) { throw new Error( "Cannot determine gas buffer requirement for the current connected chain.", ) } const minBalance = claimGasBuffer * gasPrice const minThreshold = (toppingAmount * (100n - BigInt(minTopping))) / 100n || minBalance const balance = await publicClient.getBalance({ address: account, }) return balance >= minThreshold } /** * Contract-first faucet top-up with API fallback and throttling. * 1) Check if user already has sufficient balance to claim * 2) If eligible (canTop && balance < toppingAmount), try on-chain top-up (user signs). * 3) Guard against gas > toppingAmount and insufficient gas to publish tx. * 4) If on-chain path fails or cannot publish/sign, fallback to backend /verify/topWallet. * 5) Throttle tops to once per chain per throttleMs via localStorage. */ export async function triggerFaucet({ chainId, account, publicClient, walletClient, faucetAddress, env, throttleMs = 60 * 60 * 1000, }: TriggerFaucetParams): Promise { // Throttle via localStorage (browser env only) if (typeof localStorage !== "undefined") { const key = `goodDollarFaucetLastToppedUtcMs_${chainId}` const last = localStorage.getItem(key) if (last && Date.now() < Number(last) + throttleMs) { return "skipped" } } try { // Read wallet balance + faucet eligibility/amount const [balance, canTop, toppingAmount, minTopping] = await Promise.all([ publicClient.getBalance({ address: account }), publicClient.readContract({ address: faucetAddress, abi: faucetABI, functionName: "canTop", args: [account], account, } as any) as Promise, publicClient.readContract({ address: faucetAddress, abi: faucetABI, functionName: "getToppingAmount", args: [], account, }) as Promise, publicClient.readContract({ address: faucetAddress, abi: faucetABI, functionName: "minTopping", args: [], account, } as any) as Promise, ]) // Check if user already has sufficient balance using the canClaim logic const hasGoodBalance = await canClaim( chainId, account, publicClient, faucetAddress, toppingAmount, minTopping, ) // Skip if faucet won't top, already above threshold, or has sufficient balance for claiming if (!canTop || balance >= toppingAmount || hasGoodBalance) { if (typeof localStorage !== "undefined") { localStorage.setItem( `goodDollarFaucetLastToppedUtcMs_${chainId}`, String(Date.now()), ) } return "skipped" } // Simulate faucet call for revert check + write request preparation const { request } = await publicClient.simulateContract({ address: faucetAddress, abi: faucetABI, functionName: "topWallet", args: [account], account, chain: walletClient.chain, }) // Estimate tx fee in wei using gas units * per-gas price. const estimatedGas = await publicClient.estimateContractGas({ address: faucetAddress, abi: faucetABI, functionName: "topWallet", args: [account], account, }) const fees = await publicClient.estimateFeesPerGas().catch(() => undefined) const perGasWei = fees?.maxFeePerGas ?? fees?.gasPrice ?? chainConfigs[chainId]?.defaultGasPrice if (typeof perGasWei !== "bigint") { throw new Error("Unable to determine per-gas price for faucet top-up") } const estimatedTxFeeWei = estimatedGas * perGasWei if (balance < estimatedTxFeeWei) { throw new Error("Not enough balance to pay for estimated gas fee") } if (estimatedTxFeeWei > toppingAmount) { throw new Error("Estimated gas fee exceeds topping amount") } // Send tx (user signs) const hash = await walletClient.writeContract(request) // Small delay before polling await new Promise((r) => setTimeout(r, 2000)) await waitForTransactionReceipt(publicClient, { hash, retryDelay: 3000, }) if (typeof localStorage !== "undefined") { localStorage.setItem( `goodDollarFaucetLastToppedUtcMs_${chainId}`, String(Date.now()), ) } return "topped_via_contract" } catch (err) { // Fallback to backend API console.error("Faucet topWallet error, falling back to API", err) try { const { backend } = Envs[env as keyof typeof Envs] || {} if (!backend) return "error" const response = await fetch(`${backend}/verify/topWallet`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ chainId, account }), }) if (!response.ok) return "error" if (typeof localStorage !== "undefined") { localStorage.setItem( `goodDollarFaucetLastToppedUtcMs_${chainId}`, String(Date.now()), ) } return "topped_via_api" } catch { return "error" } } }