txplain

Blockchain transaction explainer — understand any Bitcoin or Ethereum transaction in plain English.

Fully static frontend + a thin Cloudflare Worker proxy (for Ethereum only).

---

Repo Structure

txplain/
├── frontend/               # Static site — deploy to Cloudflare Pages
│   ├── index.html
│   ├── css/style.css
│   └── js/
│       ├── app.js          # UI, state, chain routing
│       ├── providers.js    # Claude / OpenAI / Gemini streaming
│       ├── mempool.js      # Bitcoin: mempool.space API client
│       ├── ethereum.js     # Ethereum: calls the proxy worker
│       └── summary.js      # Deterministic summaries (BTC + ETH)
│
└── proxy/                  # Cloudflare Worker — deploy separately
    ├── worker.js           # Rate limiting + Etherscan key proxy
    └── wrangler.toml       # Worker config

---

How It Works

Bitcoin — fully client-side, no proxy needed:

Browser → mempool.space API (free, no key, CORS-enabled)

Ethereum — routes through the Worker:

Browser → Cloudflare Worker (rate limiter + key holder) → Etherscan API

The Worker enforces 3 requests per IP per 5 minutes using Cloudflare KV.

---

Deploy: Frontend (Cloudflare Pages)

1. Push this repo to GitHub
2. In Cloudflare Pages → Connect repo
3. Settings:
   • Root directory: frontend
   • Build command: (leave empty)
   • Output directory: frontend

---

Deploy: Worker Proxy (Cloudflare Workers)

1. Install Wrangler

npm install -g wrangler
wrangler login

2. Set the Etherscan API key as a secret

wrangler secret put ETHERSCAN_API_KEY
# paste the key when prompted

3. Deploy

cd proxy
wrangler deploy

The Worker will be live at https://txplain-proxy.YOUR-SUBDOMAIN.workers.dev.

4. Update the frontend

Paste that URL into frontend/index.html as shown above, then redeploy the frontend.

---

Local Development

Frontend:

cd frontend
python3 -m http.server 8080
# open http://localhost:8080

Worker (local):

cd proxy
wrangler dev
# runs on http://localhost:8787

For local testing with the Worker, temporarily set in index.html:

window.ETH_PROXY_BASE = 'http://localhost:8787';

---

Rate Limiting

The Worker enforces per-IP limits using Cloudflare KV:

• 3 requests per 5-minute window per IP
• Returns HTTP 429 with a retryAfter field on breach
• The frontend surfaces a clear message to the user
• Configurable via RATE_LIMIT_MAX and RATE_LIMIT_WINDOW constants in worker.js

---

AI Keys

Click AI in the top-right. Select a provider and paste the key. Session-only — cleared on tab close.

• Claude: console.anthropic.com
• OpenAI: platform.openai.com
• Gemini: aistudio.google.com

---

Shareable URLs

Every lookup updates the URL:

• Bitcoin: /?chain=btc&tx=<txid>
• Ethereum: /?chain=eth&tx=<hash>

The Copy link button copies the full URL. Shared links load the transaction directly.

---

Extending

Add a new chain

1. Create frontend/js/<chain>.js following the pattern of mempool.js or ethereum.js
2. Add a build<Chain>SummaryRows() function
3. Add a chain button in index.html
4. Wire it into app.js

Add a new AI provider

Add an entry to window.AI_PROVIDERS in providers.js and a button in the settings panel.

---

License

MIT