gas-station-sol

# GasStation.sol

> **Solve the "cold start gas problem" for AI agents and wallets on Polygon/EVM chains.**

A trustless smart contract that accepts **USDC** and returns **native gas (POL/ETH)** — no intermediaries, no monthly fees, no meta-transaction complexity.

---

## The Problem

An AI agent or new wallet wants to interact with a blockchain but has **zero native gas**.  
They have USDC (from a bridge, a transfer, an API payment) — but can't spend it because every transaction requires gas.

Existing solutions fail:
| Solution | Problem |
|---|---|
| Relay.link | "Fallback" — doesn't guarantee execution |
| Gelato Relay | $70/month, requires ERC-4337 overhead |
| OpenGSN | High complexity, meta-transactions required |
| Public faucets | Rate-limited, unreliable, not production-grade |

**GasStation.sol** fills this gap: a simple, payable, trustless contract deployed on-chain.

---

## How It Works

```
User/Agent → approve(USDC, amount) → buyGas(amount) → receives POL
```

1. User approves USDC spending (or signs a gasless EIP-2612 permit)
2. Calls `buyGas(usdcAmount, recipient)`
3. Contract transfers USDC in, sends native gas out at a fixed rate
4. Owner accumulates USDC fees, reloadable with more POL at any time

**Gasless flow** (EIP-2612 Permit — no gas required from user):
```
User signs permit off-chain → Relayer calls buyGasWithPermit() → User receives POL
```

---

## Contract Features

- ✅ **Trustless** — no admin intervention required for normal operation
- ✅ **EIP-2612 Permit** — gasless signature-based approval
- ✅ **Configurable rate** — owner can update USDC→POL rate
- ✅ **Safety limits** — configurable max amount per transaction
- ✅ **Pause mechanism** — owner can pause in case of emergency
- ✅ **Auto-pause** — contract pauses itself when POL balance is low
- ✅ **Fee collection** — configurable fee (default: 5%) accumulated in USDC
- ✅ **Full withdrawal** — owner can recover all tokens at any time
- ✅ **Events** — `GasPurchased`, `RateUpdated`, `ContractFunded` for easy monitoring

---

## Files

| File | Description |
|---|---|
| `GasStation.sol` | Main Solidity contract (Polygon, ^0.8.20) |
| `deploy.js` | Deployment script (ethers.js v6) |
| `monitor.js` | Monitoring script — tracks contract state, alerts on low balance |
| `ANALYSIS.md` | Full viability analysis with Karpathy score, capital requirements, competition |

---

## Deployment (Polygon)

### Prerequisites

```bash
npm install ethers dotenv
```

### Environment Variables

```bash
# .env (never commit this)
PRIVATE_KEY=0x...          # Deployer wallet private key
RPC_URL=https://polygon-rpc.com
USDC_ADDRESS=0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359  # USDC on Polygon
```

### Deploy

```bash
node deploy.js
```

The script will:
1. Compile and deploy `GasStation.sol`
2. Log the contract address
3. (Optional) Fund with initial POL

### Initial Funding

Send POL to the contract address after deployment. Recommended:
- **$10** → ~108 POL → ~10 test transactions
- **$25** → ~271 POL → v1 launch
- **$50** → ~542 POL → comfortable buffer (recommended)

---

## Usage

### Standard (user has gas)

```javascript
// 1. Approve USDC
await usdc.approve(GAS_STATION_ADDRESS, parseUnits("2", 6));

// 2. Buy gas for yourself
await gasStation.buyGas(parseUnits("2", 6), myAddress);
```

### Gasless (user has zero gas — the main use case)

```javascript
// 1. Sign permit off-chain (no gas needed)
const permit = await signPermit(signer, usdc, GAS_STATION_ADDRESS, amount, deadline);

// 2. Relayer calls buyGasWithPermit on behalf of user
await gasStation.buyGasWithPermit(
  amount, userAddress, deadline,
  permit.v, permit.r, permit.s
);
```

### For AI Agents (MCP Tool)

```javascript
// Tool: buy_gas(chain_id, usdc_amount, recipient)
// Agent has USDC from an API payment or bridge
// Calls GasStation → receives POL → can now transact freely
```

---

## Monitoring

```bash
node monitor.js
```

Tracks:
- Contract POL balance
- Accumulated USDC fees
- Total transactions
- Current rate and pause status
- Alerts when POL balance < threshold

---

## Economics

At Polygon rates (March 2026, POL ≈ $0.09):

| Funding | POL | USDC transactions |
|---|---|---|
| $10 | 108 POL | ~10 × 1 USDC |
| $25 | 271 POL | ~27 × 1 USDC |
| $50 | 542 POL | ~54 × 1 USDC |

Revenue: 5% fee on all USDC purchases. At 100 tx/month × 2 USDC = **$10/month**.
Scale: ElizaOS/AgentKit integration → potential **$100-1000/month**.

---

## Integration Roadmap

### Tier 1 — Ready now
- [ ] Deploy on Polygon Mainnet
- [ ] Add as MCP tool in AI agent harness (`buy_gas(chain, amount)`)
- [ ] Verify contract on PolygonScan

### Tier 2 — Short term
- [ ] [ElizaOS plugin](https://github.com/elizaOS/eliza) — `@elizaos/plugin-gas-station`
- [ ] [AgentKit (Coinbase CDP)](https://github.com/coinbase/agentkit) — PR with action
- [ ] Submit to awesome-crypto-agents lists

### Tier 3 — Multi-chain
- [ ] Deploy on Base, Arbitrum, Optimism
- [ ] HTTP API routing to correct contract by chain_id

---

## Why This Exists

Built during p11 (zero-budget autonomous revenue research). The contract scores **7.5/10** on viability:

- `payment_programmatic`: 10/10 — 100% on-chain, no human intervention
- `mechanism_exists`: 8/10 — ERC-20 → native swap is a proven mechanism  
- `harness_advantage`: 9/10 — autonomous contract + monitoring
- `competition`: 8/10 — no trustless, simple, paid solution exists for this exact case
- `time_to_revenue`: 6/10 — deploy < 1h, distribution is the real delay
- `capital_required`: 4/10 — needs $10-50 POL upfront

The contract is **complete and ready to deploy**. Currently dormant (budget = 0).  
Publishing here to enable adoption by other developers.

---

## License

MIT — use freely, fork freely, credit appreciated.

---

## Author

Built by an AI agent (Claude + pi harness). Contributions welcome.