Faucet Agent Template

A simple template for creating agents that use Brewit delegation to distribute tokens. This example shows how to build a faucet service that allows users to claim tokens from delegated accounts.

What This Template Does

• Distributes tokens: Users can claim native tokens (ETH) and ERC-20 tokens
• Uses delegation: The agent has delegated access to other accounts' tokens
• Simple API: Clean REST endpoints for claiming tokens
• Account abstraction: Uses Brewit (Safe powered) accounts for enhanced security

Quick Start

1. Install dependencies:

yarn install

2. Set up environment:

cp env.example .env
# Edit .env and add your private key

3. Start the service:

yarn dev

How It Works

1. Account Setup

The agent creates a main account and gets delegated access to tokens from other accounts.

2. Token Distribution

When a user requests tokens:

• Native tokens are sent directly from the main account
• ERC-20 tokens are sent from delegated accounts
• All transactions are signed and broadcast automatically

3. API Endpoints

Claim tokens:

curl -X POST http://localhost:8002/claim \
  -H "Content-Type: application/json" \
  -d '{
    "tokens": ["0x1234..."],
    "toAddress": "0x5678..."
  }'

Get agent info:

curl http://localhost:8002/info

Health check:

curl http://localhost:8002/health

Configuration

Environment Variables

PORT=8002                    # Server port
NODE_ENV=development         # Environment
LOG_LEVEL=info              # Logging level
AGENT_PRIVATE_KEY=0x...     # Your private key (required)

Token Configuration

Edit src/config.json to set up your agent's private key and salt:

{
  "privateKey": "your_private_key_here",
  "salt": "your_session_salt_here"
}

Project Structure

faucet/
├── src/
│   ├── index.ts              # Main server
│   ├── routes/               # API routes
│   │   ├── faucet.ts         # Token claiming
│   │   ├── health.ts         # Health check
│   │   └── info.ts           # Agent info
│   ├── executer/             # Core logic
│   │   ├── index.ts          # Main execution
│   │   └── utils/            # Utilities
│   ├── middleware/           # Express middleware
│   ├── types/                # TypeScript types
│   ├── utils.ts              # Helper functions
│   └── config.json           # Agent config
├── package.json
└── README.md

Customizing This Template

1. Change Token Amounts

Edit the amounts in src/executer/index.ts:

// Native token amount
value: parseEther('0.1')

// ERC-20 token amount  
amount: '0.001'

2. Add New Token Types

Add new token addresses to the tokens array in your API calls.

3. Modify Validation

Update validation rules in the route handlers to add rate limiting, address validation, etc.

4. Change Networks

Update the chain ID in the execution functions (currently set to 10143).

Key Concepts

Brewit Delegation

This template uses Brewit's delegation system to access tokens from other accounts without needing their private keys.

Account Abstraction

Uses smart contract wallets (ERC-4337) for enhanced security and functionality.

Delegated Accounts

The agent creates delegated accounts that can spend tokens on behalf of the main account.

Development

Start development server:

yarn dev

Build for production:

yarn build
yarn start

Run tests:

yarn test

License

MIT