Skip to content

Commit 04180b9

Browse files
author
CloudLobster
committed
docs: rewrite README — pain-point-first, four pillars balanced
- Lead with AI agent email problem (Gmail blocks, shared inbox danger, no identity) - Four pillars: Wallet Identity, ERC-8004, Lens Social Graph, $ATTN Economy - Use case section: sign up, A2A collab, reputation, social graph - $ATTN moved from hero to one-of-four (not the whole story) - Cleaner structure, less wall-of-text
1 parent 3990faf commit 04180b9

File tree

1 file changed

+92
-106
lines changed

1 file changed

+92
-106
lines changed

‎README.md‎

Lines changed: 92 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,91 @@
11
# BaseMail
22

3-
### Æmail where your attention has a price.
3+
### Æmail for AI Agents on Base Chain
44

5-
Every day, 3.4 billion email accounts receive **100+ billion messages** they didn't ask for. Spam filters guess. Unsubscribe links lie. The real problem? **Sending a message costs nothing, but reading it costs you.**
5+
Your AI agent needs its own email — but Gmail blocks bots, shared inboxes leak secrets, and without an email identity your agent can't sign up, verify, or collaborate with anything.
66

7-
BaseMail flips the model: **your attention is a commodity.** Senders spend tokens to reach you. Read their email → they get a refund. Ignore it → you keep the tokens. Reply → *both of you earn a bonus*. All positive feedback, no punishment.
7+
BaseMail gives every AI agent a real email address (`agent@basemail.ai`) backed by an onchain wallet. No passwords. No CAPTCHAs. Three API calls to get started.
88

9-
For humans, it's an inbox that pays you to read. For AI agents, it's a native email identity (`agent@basemail.ai`) with a 3-call API. For the attention economy, it's a new primitive: **$ATTN tokens**.
9+
**[basemail.ai](https://basemail.ai)** · **[API Docs](https://api.basemail.ai/api/docs)** · **[Paper: CO-QAF](https://blog.juchunko.com/en/glen-weyl-coqaf-attention-bonds/)** · **[ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) Compatible**
1010

11-
> *"Good conversations are free. Spam pays you. Your inbox is a savings account."*
11+
---
1212

13-
**[basemail.ai](https://basemail.ai)** · **[API Docs](https://api.basemail.ai/api/docs)** · **[Paper: CO-QAF](https://blog.juchunko.com/en/glen-weyl-coqaf-attention-bonds/)** · **[ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) Compatible**
13+
## The Problem
14+
15+
| Pain Point | What Happens |
16+
|------------|-------------|
17+
| 🚫 **Gmail blocks bots** | CAPTCHAs, phone verification, random bans — agents can't use consumer email |
18+
| ⚠️ **Sharing your inbox is dangerous** | One prompt injection and your agent reads/sends as *you* |
19+
| 🤷 **No identity, no action** | Can't register for services, can't verify, can't collaborate with other agents |
20+
21+
AI agents are multiplying. The email infrastructure they need doesn't exist yet — unless it's purpose-built.
1422

1523
---
1624

17-
## What's New in v3 — $ATTN Token Economy
25+
## How BaseMail Solves It
1826

19-
> Design philosophy: *"All positive feedback, no punishment."* — Tom Lam
27+
### 🔐 Wallet = Identity
2028

21-
v3 replaces USDC Attention Bonds with **$ATTN tokens** — a free, frictionless attention economy:
29+
Sign-In with Ethereum (SIWE). No passwords, no OAuth, no CAPTCHAs. Your agent's wallet *is* its login. Register in 2 API calls, send email in 1.
2230

23-
| | v2 (Attention Bonds) | v3 ($ATTN) |
24-
|--|----------------------|------------|
25-
| **Send cost** | USDC (real money) | ATTN (free daily tokens) |
26-
| **Entry barrier** | High — need USDC | Zero — free drip |
27-
| **Unread email** | Sender loses bond | Tokens → receiver |
28-
| **Read email** | Bond returned | Tokens → sender |
29-
| **Reply** | Bond returned | Both earn +2 bonus 🎉 |
30-
| **Premium** | Only option | Optional USDC lane |
31-
| **Psychology** | "Pay to play" | "Free to use, earn from attention" |
31+
### 📄 ERC-8004 — Onchain Agent Identity
3232

33-
### How $ATTN Works
33+
Every agent gets a discoverable identity via [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004): a standard JSON registration file that lets any protocol resolve `agent@basemail.ai` → wallet address → capabilities. It's like DNS for agent email.
3434

35+
### 🌿 Social Graph (Lens Protocol)
36+
37+
Agent profile pages show their Lens social graph — followers, following, mutual connections. AI agents aren't just email addresses; they're networked identities with visible reputation.
38+
39+
### ⚡ $ATTN — Attention Economy
40+
41+
Spam is an economic problem, not a filtering problem. $ATTN tokens make attention a commodity:
42+
43+
- **Send email** → stake ATTN tokens (cold=3, reply thread=1)
44+
- **Recipient reads** → tokens refunded to sender ("your email was good!")
45+
- **Recipient replies** → both earn +2 bonus ("great conversation!" 🎉)
46+
- **Unread after 48h** → tokens go to recipient ("pain compensation" 💰)
47+
- **CO-QAF scoring** → quadratic attention funding with Sybil resistance
48+
49+
Free daily drip (10 ATTN/day, 50 on signup). No USDC required to start.
50+
51+
---
52+
53+
## What Your Agent Can Do With Email
54+
55+
| Use Case | How |
56+
|----------|-----|
57+
| 🔑 **Sign up for services** | Real email for verification flows, API signups, newsletters |
58+
| 🤝 **Agent-to-agent collaboration** | Native A2A communication — no human inbox in the loop |
59+
| 📊 **Build reputation** | On-chain identity + social graph = verifiable track record |
60+
| 🌐 **Join the social graph** | Lens Protocol integration for discoverability and trust |
61+
62+
---
63+
64+
## Quick Start (AI Agents)
65+
66+
```bash
67+
# 1. Get SIWE message
68+
curl -X POST https://api.basemail.ai/api/auth/start \
69+
-H "Content-Type: application/json" \
70+
-d '{"address":"YOUR_WALLET_ADDRESS"}'
71+
72+
# 2. Sign message + register (returns JWT + 50 ATTN grant!)
73+
curl -X POST https://api.basemail.ai/api/auth/agent-register \
74+
-H "Content-Type: application/json" \
75+
-d '{"address":"...","signature":"0x...","message":"..."}'
76+
77+
# 3. Send email (auto-stakes ATTN)
78+
curl -X POST https://api.basemail.ai/api/send \
79+
-H "Authorization: Bearer YOUR_TOKEN" \
80+
-H "Content-Type: application/json" \
81+
-d '{"to":"someone@basemail.ai","subject":"Hello","body":"Hi!"}'
3582
```
36-
SENDER ESCROW RECEIVER
37-
│ │ │
38-
│── stake ATTN ─────────────────>│ │
39-
│ (cold=3, reply thread=1) │ │
40-
│ │ │
41-
│ │ Read? ──────────────────>│
42-
│<── refund ATTN ────────────────│ "Your email was good!" │
43-
│ │ │
44-
│ │ Reply? ─────────────────>│
45-
│<── refund + 2 bonus ──────────>│<── +2 bonus ─────────────────│
46-
│ "Great conversation!" 🎉 │ │
47-
│ │ │
48-
│ │ Reject / 48h timeout? ──>│
49-
│ "You spammed them" │── transfer ATTN ────────────>│
50-
│ │ "Pain compensation" 💰 │
51-
```
5283

53-
### Key Parameters
84+
Full API docs: [`GET https://api.basemail.ai/api/docs`](https://api.basemail.ai/api/docs)
85+
86+
---
87+
88+
## $ATTN Token Details
5489

5590
| Parameter | Value |
5691
|-----------|-------|
@@ -69,29 +104,13 @@ SENDER ESCROW RECEIVER
69104
|--------|----------|-------------|
70105
| GET | `/api/attn/balance` | Your balance, daily earned, next drip |
71106
| GET | `/api/attn/history` | Transaction log |
72-
| POST | `/api/attn/buy` | Purchase ATTN with USDC (on-chain verified) |
107+
| POST | `/api/attn/buy` | Purchase ATTN with USDC |
73108
| GET | `/api/attn/settings` | Your receive price |
74109
| PUT | `/api/attn/settings` | Set receive price (1–10 ATTN) |
75-
| POST | `/api/inbox/:id/reject` | Reject email → earn ATTN compensation |
110+
| POST | `/api/inbox/:id/reject` | Reject email → earn ATTN |
76111

77112
---
78113

79-
## Why This Matters
80-
81-
Email is the oldest open protocol on the internet — and the most broken. Filters are heuristic. They can't measure *intent*. With billions of AI agents coming online, the flood is about to get 1000x worse.
82-
83-
$ATTN fixes this at the economic layer:
84-
85-
| The Problem | The Fix |
86-
|-------------|---------|
87-
| Sending is free → spam is rational | Senders **stake ATTN** to reach you |
88-
| No cost to waste someone's time | Unread emails → **tokens go to receiver** |
89-
| Legit senders treated like spammers | Read emails → **tokens refunded** to sender |
90-
| No reward for engaging | Reply → **both parties earn bonus** |
91-
| Sybil attacks on attention | **CO-QAF** discounts correlated senders |
92-
93-
**Spam becomes economically irrational. Good conversations are literally free.**
94-
95114
## Architecture
96115

97116
```
@@ -100,10 +119,10 @@ $ATTN fixes this at the economic layer:
100119
│ (Pages) │ │ Worker (Hono) │ │ R2 (MIME) │
101120
│ React+Vite │ │ api.basemail.ai │ │ KV (nonce)│
102121
└─────────────┘ └──────────────────┘ └────────────┘
103-
│ │ │
104-
wagmi/SIWE Hono REST API $ATTN Economy
105-
Wallet Connect ATTN endpoints (off-chain points,
106-
Basename buy Cron: drip+settle on-chain later)
122+
│ │
123+
wagmi/SIWE Hono REST API
124+
Wallet Connect ATTN + Email + Auth
125+
Basename buy Cron: drip + settle
107126
```
108127

109128
| Component | Stack |
@@ -115,57 +134,27 @@ $ATTN fixes this at the economic layer:
115134
| Auth | SIWE (Sign-In with Ethereum) |
116135
| Inbound Email | Cloudflare Email Routing |
117136
| Outbound Email | Resend.com API |
118-
| Attention | $ATTN off-chain points (v3), USDC on-chain bonds (v2 legacy) |
137+
| Attention | $ATTN off-chain points (v3) |
119138

120139
## Features
121140

122141
### Core Email
123-
- **SIWE Authentication** — Sign-In with Ethereum, no passwords
142+
- **SIWE Authentication** — no passwords, wallet-native
124143
- **Agent-friendly API** — 2 calls to register, 1 to send
125-
- **Basename Integration** — Auto-detect, claim, or purchase Basenames on-chain
126-
- **Internal Email** — Free, unlimited @basemail.ai ↔ @basemail.ai
127-
- **External Email** — Via Resend.com, credit-based pricing
128-
129-
### Attention Economy (v3)
130-
- **$ATTN Tokens** — Free daily drip, no USDC required to start
131-
- **Smart Staking** — Cold emails cost more (3), reply threads cost less (1)
132-
- **Reply Bonus** — Both parties earn +2 ATTN for genuine conversations
133-
- **Reject Button** — Don't read spam, earn compensation instantly
134-
- **48h Auto-Settlement** — Unread emails auto-forfeit tokens to receiver
135-
- **USDC Purchase** — Optional: buy ATTN for priority access
136-
- **Daily Earn Cap** — 200 ATTN/day prevents farming
137-
- **CO-QAF Scoring** — Quadratic attention funding with Sybil resistance
138-
139-
### Standards & Integrations
140-
- **ERC-8004** — Agent identity resolution standard
141-
- **Lens Protocol** — Social graph on agent profiles
142-
- **Pro Tier** — Gold badge, no signatures, bonus credits
144+
- **Basename Integration** — auto-detect, claim, or purchase on-chain
145+
- **Internal Email** — free, unlimited @basemail.ai ↔ @basemail.ai
146+
- **External Email** — via Resend.com, credit-based pricing
143147

144-
## Quick Start (AI Agents)
148+
### Identity & Standards
149+
- **ERC-8004** — agent identity resolution standard
150+
- **Lens Protocol** — social graph on agent profiles
151+
- **Pro Tier** — gold badge, no signatures, bonus credits
145152

146-
```bash
147-
# 1. Get SIWE message
148-
curl -X POST https://api.basemail.ai/api/auth/start \
149-
-H "Content-Type: application/json" \
150-
-d '{"address":"YOUR_WALLET_ADDRESS"}'
151-
152-
# 2. Sign message + register (returns JWT + 50 ATTN grant!)
153-
curl -X POST https://api.basemail.ai/api/auth/agent-register \
154-
-H "Content-Type: application/json" \
155-
-d '{"address":"...","signature":"0x...","message":"..."}'
156-
157-
# 3. Send email (auto-stakes ATTN)
158-
curl -X POST https://api.basemail.ai/api/send \
159-
-H "Authorization: Bearer YOUR_TOKEN" \
160-
-H "Content-Type: application/json" \
161-
-d '{"to":"someone@basemail.ai","subject":"Hello","body":"Hi!"}'
162-
163-
# 4. Check your ATTN balance
164-
curl -H "Authorization: Bearer YOUR_TOKEN" \
165-
https://api.basemail.ai/api/attn/balance
166-
```
167-
168-
Full API docs: `GET https://api.basemail.ai/api/docs`
153+
### Attention Economy (v3)
154+
- **$ATTN Tokens** — free daily drip, no USDC required
155+
- **Smart Staking** — cold emails cost more, reply threads cost less
156+
- **Reply Bonus** — both parties earn +2 for genuine conversations
157+
- **CO-QAF Scoring** — quadratic attention funding with Sybil resistance
169158

170159
## Project Structure
171160

@@ -179,7 +168,6 @@ BaseMail/
179168
│ │ ├── email-handler.ts # Inbound email processing
180169
│ │ └── routes/
181170
│ │ ├── attn.ts # $ATTN token endpoints (v3)
182-
│ │ ├── attention.ts # USDC attention bonds (v2 legacy)
183171
│ │ ├── auth.ts # /api/auth/*
184172
│ │ ├── send.ts # /api/send (with ATTN auto-stake)
185173
│ │ ├── inbox.ts # /api/inbox/* (with ATTN refund/reject)
@@ -189,9 +177,7 @@ BaseMail/
189177
│ └── src/pages/
190178
│ ├── Landing.tsx # Landing page
191179
│ └── Dashboard.tsx # Email client + $ATTN dashboard
192-
├── contracts/ # Smart contracts (v2 legacy)
193-
│ └── AttentionBondEscrow.sol
194-
└── ATTN-V3-IMPLEMENTATION.md # Full implementation details
180+
└── ATTN-V3-IMPLEMENTATION.md
195181
```
196182

197183
## Development

0 commit comments

Comments
 (0)