@aztec/aztec-faucet 0.0.0-test.0

package/README.md

@@ -0,0 +1,3 @@
+# Aztec Faucet
+
+This application allows someone to obtain a small amount of eth via a http endpoint.

package/dest/bin/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env -S node --no-warnings
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dest/bin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bin/index.ts"],"names":[],"mappings":""}

package/dest/bin/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env -S node --no-warnings
+import { createLogger } from '@aztec/foundation/log';
+import { getFaucetConfigFromEnv } from '../config.js';
+import { Faucet } from '../faucet.js';
+import { createFaucetHttpServer } from '../http.js';
+const logger = createLogger('aztec:faucet:http');
+/**
+ * Create and start a new Aztec Node HTTP Server
+ */ async function main() {
+    const config = getFaucetConfigFromEnv();
+    const faucet = await Faucet.create(config);
+    const httpServer = createFaucetHttpServer(faucet, '/', logger);
+    const port = parseInt(process.env?.AZTEC_PORT ?? '', 10) || 8080;
+    httpServer.listen(port);
+    logger.info(`Aztec Faucet listening on port ${port}`);
+    await Promise.resolve();
+}
+main().catch((err)=>{
+    logger.error(err);
+    process.exit(1);
+});

package/dest/config.d.ts

@@ -0,0 +1,17 @@
+import { type L1ReaderConfig } from '@aztec/ethereum';
+import { type ConfigMappingsType } from '@aztec/foundation/config';
+import { EthAddress } from '@aztec/foundation/eth-address';
+export type L1AssetConfig = {
+    address: EthAddress;
+    amount: bigint;
+};
+export type FaucetConfig = L1ReaderConfig & {
+    l1Mnemonic: string;
+    mnemonicAccountIndex: number;
+    interval: number;
+    ethAmount: string;
+    l1Assets: L1AssetConfig[];
+};
+export declare const faucetConfigMapping: ConfigMappingsType<FaucetConfig>;
+export declare function getFaucetConfigFromEnv(): FaucetConfig;
+//# sourceMappingURL=config.d.ts.map

package/dest/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAA0B,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EAAE,KAAK,kBAAkB,EAA6C,MAAM,0BAA0B,CAAC;AAC9G,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAE3D,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,UAAU,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,kBAAkB,CAAC,YAAY,CAoChE,CAAC;AAEF,wBAAgB,sBAAsB,IAAI,YAAY,CAErD"}

package/dest/config.js

@@ -0,0 +1,48 @@
+import { l1ReaderConfigMappings } from '@aztec/ethereum';
+import { getConfigFromMappings, numberConfigHelper } from '@aztec/foundation/config';
+import { EthAddress } from '@aztec/foundation/eth-address';
+export const faucetConfigMapping = {
+    ...l1ReaderConfigMappings,
+    l1Mnemonic: {
+        env: 'MNEMONIC',
+        description: 'The mnemonic for the faucet account'
+    },
+    mnemonicAccountIndex: {
+        env: 'FAUCET_MNEMONIC_ACCOUNT_INDEX',
+        description: 'The account to use',
+        ...numberConfigHelper(0)
+    },
+    interval: {
+        env: 'FAUCET_INTERVAL_MS',
+        description: 'How often the faucet can be dripped',
+        ...numberConfigHelper(1 * 60 * 60 * 1000)
+    },
+    ethAmount: {
+        env: 'FAUCET_ETH_AMOUNT',
+        description: 'How much eth the faucet should drip per call',
+        defaultValue: '1.0'
+    },
+    l1Assets: {
+        env: 'FAUCET_L1_ASSETS',
+        description: 'Which other L1 assets the faucet is able to drip',
+        defaultValue: '',
+        parseEnv (val) {
+            const assetConfigs = val.split(',');
+            return assetConfigs.flatMap((assetConfig)=>{
+                if (!assetConfig) {
+                    return [];
+                }
+                const [address, amount = '1e9'] = assetConfig.split(':');
+                return [
+                    {
+                        address: EthAddress.fromString(address),
+                        amount: BigInt(amount)
+                    }
+                ];
+            });
+        }
+    }
+};
+export function getFaucetConfigFromEnv() {
+    return getConfigFromMappings(faucetConfigMapping);
+}

package/dest/faucet.d.ts

@@ -0,0 +1,28 @@
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import { type LocalAccount } from 'viem';
+import type { FaucetConfig, L1AssetConfig } from './config.js';
+export declare class Faucet {
+    private config;
+    private account;
+    private timeFn;
+    private log;
+    private walletClient;
+    private publicClient;
+    private dripHistory;
+    private l1Assets;
+    constructor(config: FaucetConfig, account: LocalAccount, timeFn?: () => number, log?: import("@aztec/foundation/log").Logger);
+    static create(config: FaucetConfig): Promise<Faucet>;
+    send(to: EthAddress, assetName: string): Promise<void>;
+    sendEth(to: EthAddress): Promise<void>;
+    sendERC20(to: EthAddress, assetName: string): Promise<void>;
+    addL1Asset(l1AssetConfig: L1AssetConfig): Promise<void>;
+    private checkThrottle;
+    private updateThrottle;
+}
+export declare class ThrottleError extends Error {
+    constructor(address: string, asset: string);
+}
+export declare class UnknownAsset extends Error {
+    constructor(asset: string);
+}
+//# sourceMappingURL=faucet.d.ts.map

package/dest/faucet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"faucet.d.ts","sourceRoot":"","sources":["../src/faucet.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAIhE,OAAO,EAKL,KAAK,YAAY,EAQlB,MAAM,MAAM,CAAC;AAGd,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAO/D,qBAAa,MAAM;IAQf,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,GAAG;IAVb,OAAO,CAAC,YAAY,CAAmB;IACvC,OAAO,CAAC,YAAY,CAAmB;IAEvC,OAAO,CAAC,WAAW,CAA0C;IAC7D,OAAO,CAAC,QAAQ,CAA8B;gBAGpC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,YAAY,EACrB,MAAM,GAAE,MAAM,MAAiB,EAC/B,GAAG,yCAA+B;WAgBxB,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAe1D,IAAI,CAAC,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQhD,OAAO,CAAC,EAAE,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IActC,SAAS,CAAC,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB3D,UAAU,CAAC,aAAa,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBpE,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,cAAc;CASvB;AAED,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAG3C;AAED,qBAAa,YAAa,SAAQ,KAAK;gBACzB,KAAK,EAAE,MAAM;CAG1B"}

package/dest/faucet.js

@@ -0,0 +1,132 @@
+import { createEthereumChain } from '@aztec/ethereum';
+import { createLogger } from '@aztec/foundation/log';
+import { TestERC20Abi } from '@aztec/l1-artifacts';
+import { createPublicClient, createWalletClient, fallback, getContract, parseEther, http as viemHttp } from 'viem';
+import { mnemonicToAccount } from 'viem/accounts';
+export class Faucet {
+    config;
+    account;
+    timeFn;
+    log;
+    walletClient;
+    publicClient;
+    dripHistory;
+    l1Assets;
+    constructor(config, account, timeFn = Date.now, log = createLogger('aztec:faucet')){
+        this.config = config;
+        this.account = account;
+        this.timeFn = timeFn;
+        this.log = log;
+        this.dripHistory = new Map();
+        this.l1Assets = new Map();
+        const chain = createEthereumChain(config.l1RpcUrls, config.l1ChainId);
+        this.walletClient = createWalletClient({
+            account: this.account,
+            chain: chain.chainInfo,
+            transport: fallback(chain.rpcUrls.map((url)=>viemHttp(url)))
+        });
+        this.publicClient = createPublicClient({
+            chain: chain.chainInfo,
+            transport: fallback(chain.rpcUrls.map((url)=>viemHttp(url)))
+        });
+    }
+    static async create(config) {
+        if (!config.l1Mnemonic) {
+            throw new Error('Missing faucet mnemonic');
+        }
+        const account = mnemonicToAccount(config.l1Mnemonic, {
+            addressIndex: config.mnemonicAccountIndex
+        });
+        const faucet = new Faucet(config, account);
+        for (const asset of config.l1Assets){
+            await faucet.addL1Asset(asset);
+        }
+        return faucet;
+    }
+    send(to, assetName) {
+        if (assetName.toUpperCase() === 'ETH') {
+            return this.sendEth(to);
+        } else {
+            return this.sendERC20(to, assetName);
+        }
+    }
+    async sendEth(to) {
+        this.checkThrottle(to, 'ETH');
+        const hash = await this.walletClient.sendTransaction({
+            account: this.account,
+            to: to.toString(),
+            value: parseEther(this.config.ethAmount)
+        });
+        await this.publicClient.waitForTransactionReceipt({
+            hash
+        });
+        this.updateThrottle(to, 'ETH');
+        this.log.info(`Sent ETH ${this.config.ethAmount} to ${to} in tx ${hash}`);
+    }
+    async sendERC20(to, assetName) {
+        const asset = this.l1Assets.get(assetName);
+        if (!asset) {
+            throw new UnknownAsset(assetName);
+        }
+        this.checkThrottle(to, assetName);
+        const hash = await asset.contract.write.mint([
+            to.toString(),
+            asset.amount
+        ]);
+        await this.publicClient.waitForTransactionReceipt({
+            hash
+        });
+        this.updateThrottle(to, assetName);
+        this.log.info(`Sent ${assetName} ${asset.amount} to ${to} in tx ${hash}`);
+    }
+    async addL1Asset(l1AssetConfig) {
+        const contract = getContract({
+            abi: TestERC20Abi,
+            address: l1AssetConfig.address.toString(),
+            client: this.walletClient
+        });
+        const [name, owner] = await Promise.all([
+            contract.read.name(),
+            contract.read.owner()
+        ]);
+        if (owner !== this.account.address) {
+            throw new Error(`Owner mismatch. Expected contract ${name} to be owned by ${this.account.address}, received ${owner}`);
+        }
+        if (this.l1Assets.has(name) && this.l1Assets.get(name).contract.address.toLowerCase() !== l1AssetConfig.address.toString().toLowerCase()) {
+            this.log.warn(`Updating asset ${name} to address=${contract.address}`);
+        }
+        this.l1Assets.set(name, {
+            contract,
+            amount: l1AssetConfig.amount
+        });
+    }
+    checkThrottle(address, asset = 'ETH') {
+        const addressHistory = this.dripHistory.get(address.toString());
+        if (!addressHistory) {
+            return;
+        }
+        const now = this.timeFn();
+        const last = addressHistory.get(asset);
+        if (typeof last === 'number' && last + this.config.interval > now) {
+            throw new ThrottleError(address.toString(), asset);
+        }
+    }
+    updateThrottle(address, asset = 'ETH') {
+        const addressStr = address.toString();
+        if (!this.dripHistory.has(addressStr)) {
+            this.dripHistory.set(addressStr, new Map());
+        }
+        const addressHistory = this.dripHistory.get(addressStr);
+        addressHistory.set(asset, this.timeFn());
+    }
+}
+export class ThrottleError extends Error {
+    constructor(address, asset){
+        super(`Not funding ${asset}: throttled ${address}`);
+    }
+}
+export class UnknownAsset extends Error {
+    constructor(asset){
+        super(`Unknown asset: ${asset}`);
+    }
+}

package/dest/http.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="node" resolution-mode="require"/>
+import { type ApiSchemaFor } from '@aztec/foundation/schemas';
+import { type Faucet } from './faucet.js';
+export declare function createFaucetHttpServer(faucet: Faucet, apiPrefix?: string, logger?: import("@aztec/foundation/log").Logger): import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;
+export declare const FaucetSchema: ApiSchemaFor<Faucet>;
+//# sourceMappingURL=http.d.ts.map

package/dest/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,KAAK,YAAY,EAAW,MAAM,2BAA2B,CAAC;AASvE,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,aAAa,CAAC;AAEzD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,SAAK,EAAE,MAAM,yCAAoC,sGA6DhH;AAED,eAAO,MAAM,YAAY,EAAE,YAAY,CAAC,MAAM,CAQ7C,CAAC"}

package/dest/http.js

@@ -0,0 +1,73 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { createLogger } from '@aztec/foundation/log';
+import { schemas } from '@aztec/foundation/schemas';
+import cors from '@koa/cors';
+import { createServer } from 'http';
+import Koa from 'koa';
+import bodyParser from 'koa-bodyparser';
+import Router from 'koa-router';
+import { z } from 'zod';
+import { ThrottleError } from './faucet.js';
+export function createFaucetHttpServer(faucet, apiPrefix = '', logger = createLogger('aztec:faucet:http')) {
+    const router = new Router({
+        prefix: `${apiPrefix}`
+    });
+    router.get('/drip/:address', async (ctx)=>{
+        const { address } = ctx.params;
+        const { asset } = ctx.query;
+        if (typeof asset !== 'string') {
+            throw new Error(`Bad asset: [${asset}]`);
+        }
+        await faucet.send(EthAddress.fromString(address), asset);
+        ctx.status = 200;
+    });
+    const L1AssetRequestSchema = z.object({
+        address: z.string().transform((str)=>EthAddress.fromString(str)),
+        amount: z.string().transform((str)=>BigInt(str))
+    });
+    router.post('/l1-asset', async (ctx)=>{
+        if (!ctx.request.body) {
+            throw new Error('Invalid request body');
+        }
+        const result = L1AssetRequestSchema.safeParse(ctx.request.body);
+        if (!result.success) {
+            throw new Error(`Invalid request: ${result.error.message}`);
+        }
+        const { address, amount } = result.data;
+        await faucet.addL1Asset({
+            address,
+            amount
+        });
+        ctx.status = 200;
+    });
+    const app = new Koa();
+    app.on('error', (error)=>{
+        logger.error(`Error on API handler: ${error}`);
+    });
+    app.use(async (ctx, next)=>{
+        try {
+            await next();
+        } catch (err) {
+            logger.error(err);
+            ctx.status = err instanceof ThrottleError ? 429 : 400;
+            ctx.body = {
+                error: err.message
+            };
+        }
+    });
+    app.use(cors());
+    app.use(bodyParser());
+    app.use(router.routes());
+    app.use(router.allowedMethods());
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises
+    return createServer(app.callback());
+}
+export const FaucetSchema = {
+    send: z.function().args(schemas.EthAddress, z.string()).returns(z.void()),
+    sendERC20: z.function().args(schemas.EthAddress, z.string()).returns(z.void()),
+    sendEth: z.function().args(schemas.EthAddress).returns(z.void()),
+    addL1Asset: z.function().args(z.object({
+        address: schemas.EthAddress,
+        amount: z.bigint()
+    })).returns(z.void())
+};

package/dest/index.d.ts

@@ -0,0 +1,4 @@
+export * from './faucet.js';
+export * from './http.js';
+export * from './config.js';
+//# sourceMappingURL=index.d.ts.map

package/dest/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC"}

package/dest/index.js

@@ -0,0 +1,3 @@
+export * from './faucet.js';
+export * from './http.js';
+export * from './config.js';

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@aztec/aztec-faucet",
+  "version": "0.0.0-test.0",
+  "main": "dest/bin/index.js",
+  "type": "module",
+  "bin": "./dest/bin/index.js",
+  "exports": {
+    ".": "./dest/index.js",
+    "./config": "./dest/config.js"
+  },
+  "typedocOptions": {
+    "entryPoints": [
+      "./src/bin/index.ts"
+    ],
+    "name": "Aztec Faucet",
+    "tsconfig": "./tsconfig.json"
+  },
+  "scripts": {
+    "start": "node --no-warnings ./dest/bin",
+    "build": "yarn clean && tsc -b",
+    "build:dev": "tsc -b --watch",
+    "clean": "rm -rf ./dest .tsbuildinfo",
+    "formatting": "run -T prettier --check ./src && run -T eslint ./src",
+    "formatting:fix": "run -T eslint --fix ./src && run -T prettier -w ./src",
+    "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
+  },
+  "inherits": [
+    "../package.common.json"
+  ],
+  "jest": {
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.[cm]?js$": "$1"
+    },
+    "testRegex": "./src/.*\\.test\\.(js|mjs|ts)$",
+    "rootDir": "./src",
+    "transform": {
+      "^.+\\.tsx?$": [
+        "@swc/jest",
+        {
+          "jsc": {
+            "parser": {
+              "syntax": "typescript",
+              "decorators": true
+            },
+            "transform": {
+              "decoratorVersion": "2022-03"
+            }
+          }
+        }
+      ]
+    },
+    "extensionsToTreatAsEsm": [
+      ".ts"
+    ],
+    "reporters": [
+      "default"
+    ],
+    "testTimeout": 120000,
+    "setupFiles": [
+      "../../foundation/src/jest/setup.mjs"
+    ]
+  },
+  "dependencies": {
+    "@aztec/ethereum": "0.0.0-test.0",
+    "@aztec/foundation": "0.0.0-test.0",
+    "@aztec/l1-artifacts": "0.0.0-test.0",
+    "@koa/cors": "^5.0.0",
+    "koa": "^2.14.2",
+    "koa-bodyparser": "^4.4.1",
+    "koa-router": "^12.0.0",
+    "viem": "2.22.8",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.5.0",
+    "@types/jest": "^29.5.0",
+    "@types/koa-bodyparser": "^4.3.12",
+    "@types/node": "^18.7.23",
+    "jest": "^29.5.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.0.4"
+  },
+  "files": [
+    "dest",
+    "src",
+    "!*.test.*"
+  ],
+  "types": "./dest/index.d.ts",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/bin/index.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env -S node --no-warnings
+import { createLogger } from '@aztec/foundation/log';
+
+import { getFaucetConfigFromEnv } from '../config.js';
+import { Faucet } from '../faucet.js';
+import { createFaucetHttpServer } from '../http.js';
+
+const logger = createLogger('aztec:faucet:http');
+
+/**
+ * Create and start a new Aztec Node HTTP Server
+ */
+async function main() {
+  const config = getFaucetConfigFromEnv();
+  const faucet = await Faucet.create(config);
+  const httpServer = createFaucetHttpServer(faucet, '/', logger);
+  const port = parseInt(process.env?.AZTEC_PORT ?? '', 10) || 8080;
+  httpServer.listen(port);
+  logger.info(`Aztec Faucet listening on port ${port}`);
+  await Promise.resolve();
+}
+
+main().catch(err => {
+  logger.error(err);
+  process.exit(1);
+});

package/src/config.ts

@@ -0,0 +1,58 @@
+import { type L1ReaderConfig, l1ReaderConfigMappings } from '@aztec/ethereum';
+import { type ConfigMappingsType, getConfigFromMappings, numberConfigHelper } from '@aztec/foundation/config';
+import { EthAddress } from '@aztec/foundation/eth-address';
+
+export type L1AssetConfig = {
+  address: EthAddress;
+  amount: bigint;
+};
+
+export type FaucetConfig = L1ReaderConfig & {
+  l1Mnemonic: string;
+  mnemonicAccountIndex: number;
+  interval: number;
+  ethAmount: string;
+  l1Assets: L1AssetConfig[];
+};
+
+export const faucetConfigMapping: ConfigMappingsType<FaucetConfig> = {
+  ...l1ReaderConfigMappings,
+  l1Mnemonic: {
+    env: 'MNEMONIC',
+    description: 'The mnemonic for the faucet account',
+  },
+  mnemonicAccountIndex: {
+    env: 'FAUCET_MNEMONIC_ACCOUNT_INDEX',
+    description: 'The account to use',
+    ...numberConfigHelper(0),
+  },
+  interval: {
+    env: 'FAUCET_INTERVAL_MS',
+    description: 'How often the faucet can be dripped',
+    ...numberConfigHelper(1 * 60 * 60 * 1000), // 1 hour
+  },
+  ethAmount: {
+    env: 'FAUCET_ETH_AMOUNT',
+    description: 'How much eth the faucet should drip per call',
+    defaultValue: '1.0',
+  },
+  l1Assets: {
+    env: 'FAUCET_L1_ASSETS',
+    description: 'Which other L1 assets the faucet is able to drip',
+    defaultValue: '',
+    parseEnv(val): L1AssetConfig[] {
+      const assetConfigs = val.split(',');
+      return assetConfigs.flatMap(assetConfig => {
+        if (!assetConfig) {
+          return [];
+        }
+        const [address, amount = '1e9'] = assetConfig.split(':');
+        return [{ address: EthAddress.fromString(address), amount: BigInt(amount) }];
+      });
+    },
+  },
+};
+
+export function getFaucetConfigFromEnv(): FaucetConfig {
+  return getConfigFromMappings(faucetConfigMapping);
+}

package/src/faucet.ts

@@ -0,0 +1,168 @@
+import { type ViemPublicClient, type ViemWalletClient, createEthereumChain } from '@aztec/ethereum';
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import { createLogger } from '@aztec/foundation/log';
+import { TestERC20Abi } from '@aztec/l1-artifacts';
+
+import {
+  type Account,
+  type Chain,
+  type GetContractReturnType,
+  type HttpTransport,
+  type LocalAccount,
+  type WalletClient,
+  createPublicClient,
+  createWalletClient,
+  fallback,
+  getContract,
+  parseEther,
+  http as viemHttp,
+} from 'viem';
+import { mnemonicToAccount } from 'viem/accounts';
+
+import type { FaucetConfig, L1AssetConfig } from './config.js';
+
+type L1Asset = {
+  contract: GetContractReturnType<typeof TestERC20Abi, WalletClient<HttpTransport, Chain, Account>>;
+  amount: bigint;
+};
+
+export class Faucet {
+  private walletClient: ViemWalletClient;
+  private publicClient: ViemPublicClient;
+
+  private dripHistory = new Map<string, Map<string, number>>();
+  private l1Assets = new Map<string, L1Asset>();
+
+  constructor(
+    private config: FaucetConfig,
+    private account: LocalAccount,
+    private timeFn: () => number = Date.now,
+    private log = createLogger('aztec:faucet'),
+  ) {
+    const chain = createEthereumChain(config.l1RpcUrls, config.l1ChainId);
+
+    this.walletClient = createWalletClient({
+      account: this.account,
+      chain: chain.chainInfo,
+      transport: fallback(chain.rpcUrls.map(url => viemHttp(url))),
+    });
+
+    this.publicClient = createPublicClient({
+      chain: chain.chainInfo,
+      transport: fallback(chain.rpcUrls.map(url => viemHttp(url))),
+    });
+  }
+
+  public static async create(config: FaucetConfig): Promise<Faucet> {
+    if (!config.l1Mnemonic) {
+      throw new Error('Missing faucet mnemonic');
+    }
+
+    const account = mnemonicToAccount(config.l1Mnemonic, { addressIndex: config.mnemonicAccountIndex });
+    const faucet = new Faucet(config, account);
+
+    for (const asset of config.l1Assets) {
+      await faucet.addL1Asset(asset);
+    }
+
+    return faucet;
+  }
+
+  public send(to: EthAddress, assetName: string): Promise<void> {
+    if (assetName.toUpperCase() === 'ETH') {
+      return this.sendEth(to);
+    } else {
+      return this.sendERC20(to, assetName);
+    }
+  }
+
+  public async sendEth(to: EthAddress): Promise<void> {
+    this.checkThrottle(to, 'ETH');
+
+    const hash = await this.walletClient.sendTransaction({
+      account: this.account,
+      to: to.toString(),
+      value: parseEther(this.config.ethAmount),
+    });
+    await this.publicClient.waitForTransactionReceipt({ hash });
+
+    this.updateThrottle(to, 'ETH');
+    this.log.info(`Sent ETH ${this.config.ethAmount} to ${to} in tx ${hash}`);
+  }
+
+  public async sendERC20(to: EthAddress, assetName: string): Promise<void> {
+    const asset = this.l1Assets.get(assetName);
+    if (!asset) {
+      throw new UnknownAsset(assetName);
+    }
+
+    this.checkThrottle(to, assetName);
+
+    const hash = await asset.contract.write.mint([to.toString(), asset.amount]);
+    await this.publicClient.waitForTransactionReceipt({ hash });
+
+    this.updateThrottle(to, assetName);
+
+    this.log.info(`Sent ${assetName} ${asset.amount} to ${to} in tx ${hash}`);
+  }
+
+  public async addL1Asset(l1AssetConfig: L1AssetConfig): Promise<void> {
+    const contract = getContract({
+      abi: TestERC20Abi,
+      address: l1AssetConfig.address.toString(),
+      client: this.walletClient,
+    });
+
+    const [name, owner] = await Promise.all([contract.read.name(), contract.read.owner()]);
+
+    if (owner !== this.account.address) {
+      throw new Error(
+        `Owner mismatch. Expected contract ${name} to be owned by ${this.account.address}, received ${owner}`,
+      );
+    }
+
+    if (
+      this.l1Assets.has(name) &&
+      this.l1Assets.get(name)!.contract.address.toLowerCase() !== l1AssetConfig.address.toString().toLowerCase()
+    ) {
+      this.log.warn(`Updating asset ${name} to address=${contract.address}`);
+    }
+
+    this.l1Assets.set(name, { contract, amount: l1AssetConfig.amount });
+  }
+
+  private checkThrottle(address: EthAddress, asset = 'ETH') {
+    const addressHistory = this.dripHistory.get(address.toString());
+    if (!addressHistory) {
+      return;
+    }
+
+    const now = this.timeFn();
+    const last = addressHistory.get(asset);
+    if (typeof last === 'number' && last + this.config.interval > now) {
+      throw new ThrottleError(address.toString(), asset);
+    }
+  }
+
+  private updateThrottle(address: EthAddress, asset = 'ETH') {
+    const addressStr = address.toString();
+    if (!this.dripHistory.has(addressStr)) {
+      this.dripHistory.set(addressStr, new Map());
+    }
+
+    const addressHistory = this.dripHistory.get(addressStr)!;
+    addressHistory.set(asset, this.timeFn());
+  }
+}
+
+export class ThrottleError extends Error {
+  constructor(address: string, asset: string) {
+    super(`Not funding ${asset}: throttled ${address}`);
+  }
+}
+
+export class UnknownAsset extends Error {
+  constructor(asset: string) {
+    super(`Unknown asset: ${asset}`);
+  }
+}

package/src/http.ts

@@ -0,0 +1,85 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { createLogger } from '@aztec/foundation/log';
+import { type ApiSchemaFor, schemas } from '@aztec/foundation/schemas';
+
+import cors from '@koa/cors';
+import { createServer } from 'http';
+import Koa from 'koa';
+import bodyParser from 'koa-bodyparser';
+import Router from 'koa-router';
+import { z } from 'zod';
+
+import { type Faucet, ThrottleError } from './faucet.js';
+
+export function createFaucetHttpServer(faucet: Faucet, apiPrefix = '', logger = createLogger('aztec:faucet:http')) {
+  const router = new Router({ prefix: `${apiPrefix}` });
+  router.get('/drip/:address', async ctx => {
+    const { address } = ctx.params;
+    const { asset } = ctx.query;
+
+    if (typeof asset !== 'string') {
+      throw new Error(`Bad asset: [${asset}]`);
+    }
+
+    await faucet.send(EthAddress.fromString(address), asset);
+
+    ctx.status = 200;
+  });
+
+  const L1AssetRequestSchema = z.object({
+    address: z.string().transform(str => EthAddress.fromString(str)),
+    amount: z.string().transform(str => BigInt(str)),
+  });
+
+  router.post('/l1-asset', async ctx => {
+    if (!ctx.request.body) {
+      throw new Error('Invalid request body');
+    }
+
+    const result = L1AssetRequestSchema.safeParse(ctx.request.body);
+
+    if (!result.success) {
+      throw new Error(`Invalid request: ${result.error.message}`);
+    }
+
+    const { address, amount } = result.data;
+
+    await faucet.addL1Asset({ address, amount });
+
+    ctx.status = 200;
+  });
+
+  const app = new Koa();
+
+  app.on('error', error => {
+    logger.error(`Error on API handler: ${error}`);
+  });
+
+  app.use(async (ctx, next) => {
+    try {
+      await next();
+    } catch (err: any) {
+      logger.error(err);
+      ctx.status = err instanceof ThrottleError ? 429 : 400;
+      ctx.body = { error: err.message };
+    }
+  });
+
+  app.use(cors());
+  app.use(bodyParser());
+  app.use(router.routes());
+  app.use(router.allowedMethods());
+
+  // eslint-disable-next-line @typescript-eslint/no-misused-promises
+  return createServer(app.callback());
+}
+
+export const FaucetSchema: ApiSchemaFor<Faucet> = {
+  send: z.function().args(schemas.EthAddress, z.string()).returns(z.void()),
+  sendERC20: z.function().args(schemas.EthAddress, z.string()).returns(z.void()),
+  sendEth: z.function().args(schemas.EthAddress).returns(z.void()),
+  addL1Asset: z
+    .function()
+    .args(z.object({ address: schemas.EthAddress, amount: z.bigint() }))
+    .returns(z.void()),
+};

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './faucet.js';
+export * from './http.js';
+export * from './config.js';