Skip to content

Commit c41db99

Browse files
author
CloudLobster
committed
feat: v3 README, landing page, and Pro badge upgrade
README: - Complete rewrite for v3 $ATTN economy - Updated architecture diagram, feature list, API docs - Added $ATTN parameters table and endpoint list Landing page: - Hero: 'Your inbox pays you' messaging - New section: 'Your Attention Has a Price' — $ATTN visual explainer - Send/Read/Reply cards + Reject/Auto-Settle cards - Updated comparison table (ATTN replaces Attention Bonds) - Updated FAQ ($ATTN explanation) - API preview includes ATTN endpoints Dashboard: - Pro badge: SVG gold checkmark with gradient (was plain unicode)
1 parent 27c3c64 commit c41db99

File tree

3 files changed

+179
-185
lines changed

3 files changed

+179
-185
lines changed

‎README.md‎

Lines changed: 109 additions & 174 deletions
Original file line numberDiff line numberDiff line change
@@ -4,68 +4,93 @@
44

55
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.**
66

7-
BaseMail flips the model: **senders stake money to reach you.** Reply → they get it back. Ignore → you keep it. Built on Base with USDC escrow, powered by mechanism design from [Quadratic Funding](https://wtfisqf.com/).
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.
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: **Attention Bonds**.
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**.
1010

11-
> *"Basename is identity. BaseMail is **Æmail** — agentic email with humans in the loop."*
11+
> *"Good conversations are free. Spam pays you. Your inbox is a savings account."*
1212
13-
**[basemail.ai](https://basemail.ai)** · **[Contract](https://basescan.org/address/0xF5fB1bb79D466bbd6F7588Fe57B67C675844C220#code)** · **[Paper: CO-QAF](https://blog.juchunko.com/en/glen-weyl-coqaf-attention-bonds/)** · **[ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) Compatible**
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**
1414

1515
---
1616

17-
## Why This Matters
17+
## What's New in v3 — $ATTN Token Economy
1818

19-
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.
19+
> Design philosophy: *"All positive feedback, no punishment."* — Tom Lam
2020
21-
Attention Bonds fix this at the protocol level:
21+
v3 replaces USDC Attention Bonds with **$ATTN tokens** — a free, frictionless attention economy:
2222

23-
| The Problem | The Fix |
24-
|-------------|---------|
25-
| Sending is free → spam is rational | Senders **stake USDC** to reach you |
26-
| No cost to waste someone's time | Bonds are **forfeited** if you're ignored |
27-
| Legit senders treated like spammers | Bonds are **refunded** (minus 10% fee) on reply |
28-
| Sybil attacks on attention | **CO-QAF** discounts correlated senders |
29-
30-
**Spam becomes economically irrational. Genuine outreach becomes provably valuable.**
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" |
3132

32-
## How It Works
33+
### How $ATTN Works
3334

3435
```
35-
Sender BaseMail Recipient
36-
│ │ │
37-
├── Approve USDC ─────────>│ │
38-
├── Deposit Bond ─────────>│ (on-chain escrow) │
39-
├── Send Email ───────────>│───── Email arrives ───────>│
40-
│ │ │
41-
│ │ Recipient replies? ────┤
42-
│ │ │ │
43-
│ ┌─────┴─────┐ │ │
44-
│ │ YES │ │ NO (7 days) │
45-
│ │ │ │ │
46-
│<── Bond Refunded ──┤ -10% fee │ ├── Bond Forfeited │
47-
│ (90% back) └───────────┘ │ (recipient keeps)
48-
│ └──────────────────┘
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" 💰 │
4951
```
5052

51-
### On-Chain Mechanism
53+
### Key Parameters
5254

53-
- **AttentionBondEscrow** contract on Base Mainnet ([verified source](https://basescan.org/address/0xF5fB1bb79D466bbd6F7588Fe57B67C675844C220#code))
54-
- USDC escrow with 7-day response window (configurable 1–30 days)
55-
- Dynamic pricing: `p(t,s) = p₀ · (1 + α·D(t))^β · (1 - γ·R̄ₛ(t))`
56-
- Whitelist support — trusted senders skip bonding
57-
- 10% protocol fee on refunds (configurable up to 20%)
55+
| Parameter | Value |
56+
|-----------|-------|
57+
| Signup grant | 50 ATTN |
58+
| Daily drip | +10 ATTN/day |
59+
| Cold email stake | 3 ATTN |
60+
| Reply thread stake | 1 ATTN |
61+
| Reply bonus | +2 each (sender + receiver) |
62+
| Daily earn cap | 200 ATTN/day |
63+
| Escrow window | 48 hours |
64+
| USDC purchase rate | 1 USDC = 100 ATTN |
5865

59-
### Connection-Oriented QAF (CO-QAF)
66+
### ATTN Endpoints
6067

61-
BaseMail implements **CO-QAF** — a Sybil-resistant extension of Quadratic Funding for attention allocation:
68+
| Method | Endpoint | Description |
69+
|--------|----------|-------------|
70+
| GET | `/api/attn/balance` | Your balance, daily earned, next drip |
71+
| GET | `/api/attn/history` | Transaction log |
72+
| POST | `/api/attn/buy` | Purchase ATTN with USDC (on-chain verified) |
73+
| GET | `/api/attn/settings` | Your receive price |
74+
| PUT | `/api/attn/settings` | Set receive price (1–10 ATTN) |
75+
| POST | `/api/inbox/:id/reject` | Reject email → earn ATTN compensation |
76+
77+
---
6278

63-
- **α_ij estimation**: Jaccard similarity of recipient overlap between senders
64-
- **Sybil resistance**: CO-QAF bounds the Sybil premium at `1/α` (constant), vs. unbounded growth in standard QAF
65-
- **Bridging capital amplified**: Senders who connect otherwise-separate communities get full quadratic weight
66-
- **Bonding capital discounted**: Correlated senders (same social circles) receive diminished matching
79+
## Why This Matters
6780

68-
> Reference: *"Connection-Oriented Quadratic Attention Funding"* — Ko, Tang, Weyl (2026)
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.**
6994

7095
## Architecture
7196

@@ -76,9 +101,9 @@ BaseMail implements **CO-QAF** — a Sybil-resistant extension of Quadratic Fund
76101
│ React+Vite │ │ api.basemail.ai │ │ KV (nonce)│
77102
└─────────────┘ └──────────────────┘ └────────────┘
78103
│ │ │
79-
wagmi/SIWE Hono REST API AttentionBondEscrow
80-
Wallet Connect 11 attention (Base Mainnet)
81-
Basename buy endpoints USDC escrow
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)
82107
```
83108

84109
| Component | Stack |
@@ -87,11 +112,10 @@ BaseMail implements **CO-QAF** — a Sybil-resistant extension of Quadratic Fund
87112
| Frontend | React, Vite, Tailwind, wagmi |
88113
| Database | Cloudflare D1 (SQLite) |
89114
| Email Storage | Cloudflare R2 |
90-
| Auth Nonces | Cloudflare KV |
115+
| Auth | SIWE (Sign-In with Ethereum) |
91116
| Inbound Email | Cloudflare Email Routing |
92117
| Outbound Email | Resend.com API |
93-
| Smart Contract | Solidity 0.8.34, OpenZeppelin, Base Mainnet |
94-
| Token | USDC (Base) |
118+
| Attention | $ATTN off-chain points (v3), USDC on-chain bonds (v2 legacy) |
95119

96120
## Features
97121

@@ -101,81 +125,45 @@ BaseMail implements **CO-QAF** — a Sybil-resistant extension of Quadratic Fund
101125
- **Basename Integration** — Auto-detect, claim, or purchase Basenames on-chain
102126
- **Internal Email** — Free, unlimited @basemail.ai ↔ @basemail.ai
103127
- **External Email** — Via Resend.com, credit-based pricing
104-
- **Pre-storage** — Emails to unregistered 0x addresses are held for 30 days
105128

106-
### Attention Economy (v2)
107-
- **Attention Bonds** — USDC escrow for inbound emails, on-chain via `AttentionBondEscrow.sol`
108-
- **Dynamic Pricing** — Attention price adjusts based on demand and response rate
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
109137
- **CO-QAF Scoring** — Quadratic attention funding with Sybil resistance
110-
- **Compose Detection** — Auto-detects if recipient has bonds enabled, shows deposit prompt
111-
- **3-Step Deposit Flow** — Approve USDC → Deposit to Escrow → Record bond via API
112-
- **Email Activity Stats** — Dashboard shows received/sent/unique senders/reply rate
113-
- **Whitelist Management** — Exempt trusted senders from bonding
114-
115-
## Smart Contract
116-
117-
**[AttentionBondEscrow.sol](https://basescan.org/address/0xF5fB1bb79D466bbd6F7588Fe57B67C675844C220#code)** — Verified on BaseScan
118-
119-
```solidity
120-
// Core functions
121-
function deposit(address recipient, bytes32 emailId, uint256 amount) external;
122-
function reply(bytes32 emailId) external; // Recipient replies → refund sender
123-
function forfeit(bytes32 emailId) external; // No reply after window → recipient keeps bond
124-
125-
// Configuration (per-user)
126-
function setAttentionPrice(uint256 price) external;
127-
function setWhitelist(address sender, bool status) external;
128-
function setResponseWindow(uint256 window) external; // 1-30 days
129-
130-
// View
131-
function getAttentionPrice(address recipient) public view returns (uint256);
132-
function getBond(bytes32 emailId) external view returns (...);
133-
```
134138

135-
**Parameters:**
136-
- USDC: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` (Base)
137-
- Protocol fee: 10% (on refunds only)
138-
- Min bond: 0.001 USDC
139-
- Default price: 0.01 USDC
140-
- Response window: 7 days (default)
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
141143

142-
## API
143-
144-
### Quick Start (AI Agents)
144+
## Quick Start (AI Agents)
145145

146146
```bash
147147
# 1. Get SIWE message
148148
curl -X POST https://api.basemail.ai/api/auth/start \
149149
-H "Content-Type: application/json" \
150150
-d '{"address":"YOUR_WALLET_ADDRESS"}'
151151

152-
# 2. Sign message + register (returns JWT token)
152+
# 2. Sign message + register (returns JWT + 50 ATTN grant!)
153153
curl -X POST https://api.basemail.ai/api/auth/agent-register \
154154
-H "Content-Type: application/json" \
155155
-d '{"address":"...","signature":"0x...","message":"..."}'
156156

157-
# 3. Send email
157+
# 3. Send email (auto-stakes ATTN)
158158
curl -X POST https://api.basemail.ai/api/send \
159159
-H "Authorization: Bearer YOUR_TOKEN" \
160160
-H "Content-Type: application/json" \
161161
-d '{"to":"someone@basemail.ai","subject":"Hello","body":"Hi!"}'
162-
```
163162

164-
### Attention Bond Endpoints
165-
166-
| Method | Endpoint | Description |
167-
|--------|----------|-------------|
168-
| GET | `/api/attention/config` | Get your attention bond config |
169-
| PUT | `/api/attention/config` | Enable/configure attention bonds |
170-
| GET | `/api/attention/price/:handle` | Get recipient's current attention price |
171-
| POST | `/api/attention/bond` | Record a bond (after on-chain deposit) |
172-
| GET | `/api/attention/bonds` | List your bonds (sent/received) |
173-
| GET | `/api/attention/stats` | QAF score, demand, response rate |
174-
| GET | `/api/attention/qaf` | CO-QAF scoring with α_ij matrix |
175-
| POST | `/api/attention/whitelist` | Add sender to whitelist |
176-
| DELETE | `/api/attention/whitelist/:address` | Remove from whitelist |
177-
| GET | `/api/attention/whitelist` | List whitelisted addresses |
178-
| GET | `/api/attention/leaderboard` | Top accounts by QAF score |
163+
# 4. Check your ATTN balance
164+
curl -H "Authorization: Bearer YOUR_TOKEN" \
165+
https://api.basemail.ai/api/attn/balance
166+
```
179167

180168
Full API docs: `GET https://api.basemail.ai/api/docs`
181169

@@ -186,100 +174,47 @@ BaseMail/
186174
├── worker/ # Cloudflare Worker (API)
187175
│ ├── src/
188176
│ │ ├── index.ts # Routes + API docs
177+
│ │ ├── cron.ts # Daily drip + escrow settlement
189178
│ │ ├── auth.ts # JWT + SIWE verification
190179
│ │ ├── email-handler.ts # Inbound email processing
191180
│ │ └── routes/
192-
│ │ ├── attention.ts # Attention bond endpoints (11 routes)
181+
│ │ ├── attn.ts # $ATTN token endpoints (v3)
182+
│ │ ├── attention.ts # USDC attention bonds (v2 legacy)
193183
│ │ ├── auth.ts # /api/auth/*
194-
│ │ ├── register.ts # /api/register/* + Basename check
195-
│ │ ├── send.ts # /api/send
196-
│ │ ├── inbox.ts # /api/inbox/*
197-
│ │ ├── identity.ts # /api/identity/*
198-
│ │ └── credits.ts # /api/credits/*
184+
│ │ ├── send.ts # /api/send (with ATTN auto-stake)
185+
│ │ ├── inbox.ts # /api/inbox/* (with ATTN refund/reject)
186+
│ │ └── ...
199187
│ └── wrangler.toml
200188
├── web/ # Frontend (Cloudflare Pages)
201-
│ ├── src/
202-
│ │ ├── pages/
203-
│ │ │ ├── Landing.tsx # Landing + Basename availability check
204-
│ │ │ └── Dashboard.tsx # Email client + Attention Bonds UI
205-
│ │ └── wagmi.ts # Wallet config (Base Mainnet)
206-
│ └── vite.config.ts
207-
├── contracts/ # Smart contracts
208-
│ ├── contracts/
209-
│ │ └── AttentionBondEscrow.sol # USDC escrow contract
210-
│ └── hardhat.config.ts
211-
└── skill/ # OpenClaw AI agent skill
212-
└── handlers/
213-
└── index.ts # Agent email integration
189+
│ └── src/pages/
190+
│ ├── Landing.tsx # Landing page
191+
│ └── Dashboard.tsx # Email client + $ATTN dashboard
192+
├── contracts/ # Smart contracts (v2 legacy)
193+
│ └── AttentionBondEscrow.sol
194+
└── ATTN-V3-IMPLEMENTATION.md # Full implementation details
214195
```
215196

216197
## Development
217198

218-
### Prerequisites
219-
220-
- Node.js 20+
221-
- Cloudflare account (Workers, D1, R2, KV, Email Routing)
222-
- Wrangler CLI
223-
224-
### Setup
225-
226199
```bash
227-
# Install dependencies (npm workspace — must run from root)
200+
# Install (npm workspace — must run from root)
228201
npm install
229202

230-
# Configure secrets (create worker/.dev.vars)
231-
# JWT_SECRET=your-secret-here
232-
# WALLET_PRIVATE_KEY=0x...
233-
# RESEND_API_KEY=re_...
234-
235203
# Run worker locally
236204
cd worker && npx wrangler dev
237205

238206
# Run frontend locally
239207
cd web && npx vite dev
240-
```
241-
242-
### Deploy
243208

244-
```bash
245-
# Deploy worker
246-
cd worker && npx wrangler deploy
247-
248-
# Build + deploy frontend
249-
cd web && npx vite build && npx wrangler pages deploy dist --project-name=basemail-web
250-
```
251-
252-
## ERC-8004 Compatibility
253-
254-
BaseMail implements [ERC-8004 (Trustless Agents)](https://eips.ethereum.org/EIPS/eip-8004) — the emerging Ethereum standard for AI agent identity, reputation, and discovery.
255-
256-
**How it maps:**
257-
258-
| ERC-8004 Registry | BaseMail Implementation |
259-
|-------------------|------------------------|
260-
| **Identity** (ERC-721) | Basename NFT — every agent gets a portable, transferable on-chain identity |
261-
| **Reputation** | CO-QAF score — quadratic attention funding measures sender diversity and trust |
262-
| **Validation** | Attention Bonds — USDC escrow as stake-based proof of genuine intent |
263-
| **Discovery** | Registration file at `/api/agent/:handle/registration.json` |
264-
265-
**Endpoints:**
266-
267-
```bash
268-
# Agent registration file (ERC-8004 format)
269-
GET https://api.basemail.ai/api/agent/cloudlobst3r/registration.json
270-
271-
# Platform discovery
272-
GET https://api.basemail.ai/.well-known/agent-registration.json
209+
# Deploy (via CI/CD: push to main → auto deploy)
210+
git push origin main
273211
```
274212

275-
Every BaseMail agent is automatically discoverable by any ERC-8004 compatible system. The registration file includes email endpoint, wallet, Basename, attention bond config, and CO-QAF reputation data.
276-
277213
## Related Work
278214

279215
- [Quadratic Funding](https://wtfisqf.com/) — Buterin, Hitzig, Weyl (2019)
280-
- [Plural Funding](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=4712606) — Connection-Oriented Quadratic Funding
281-
- [Attention Markets](https://doi.org/10.1257/aer.96.4.1191) — Loder & Van Alstyne (2006)
282-
- [Sender-Pays Email](https://doi.org/10.1257/aer.102.3.416) — Rao & Reiley (2012)
216+
- [Connection-Oriented QAF](https://blog.juchunko.com/en/glen-weyl-coqaf-attention-bonds/) — Ko, Tang, Weyl (2026)
217+
- [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) — Agent Identity Standard
283218

284219
## License
285220

0 commit comments

Comments
 (0)