Feature roadmap: auth, rate limits, x402 payments, accounting

[crtahlin]

Overview

Plan and prioritize additional gateway features beyond basic Swarm operations.

Current State

The gateway provides:

• Stamp management (list, purchase, extend)
• Data upload/download
• Wallet/chequebook info
• Health checks

Proposed Features (Prioritized)

Priority 1: Rate Limiting & Quotas

Why: Prevent abuse, manage costs, fair usage

Implementation:

• Per-IP rate limits (requests/minute)
• Per-user quotas (if auth enabled)
• Upload size limits (already suggested in docs)
• Configurable via environment

Endpoints affected: All

Priority 2: Authentication

Why: Enable user-specific features, billing, access control

Options:

Method	Pros	Cons
API Keys	Simple, stateless	Manual management
JWT	Standard, claims	Token refresh needed
Wallet signature	Web3 native, no passwords	UX complexity
OAuth2	Enterprise-ready	Complex setup

Suggested: Start with API keys, add wallet auth later

New endpoints:

• POST /api/v1/auth/register - Create account
• POST /api/v1/auth/keys - Generate API key
• DELETE /api/v1/auth/keys/{id} - Revoke key

Priority 3: Cryptographic Signing

Status: Issue #2 exists

Summary: Sign uploads with user's key or gateway notary service

Priority 4: Usage Tracking & Accounting

Why: Foundation for billing, analytics, quotas

Data to track:

• Uploads: count, bytes, stamps used
• Downloads: count, bytes
• Stamp purchases: count, BZZ spent
• Per-user if auth enabled

Storage: PostgreSQL or similar

New endpoints:

• GET /api/v1/usage - Current usage stats
• GET /api/v1/usage/history - Historical usage

Priority 5: X402 Payment Support

Why: Enable pay-per-use for AI agents, monetization

Spec: HTTP 402 Payment Required flow

Flow:

1. Client requests resource
2. Gateway returns 402 + payment details
3. Client pays (on-chain or L2)
4. Gateway verifies payment
5. Gateway serves resource

Components needed:

• Payment verification (Base L2, USDC)
• Pricing configuration
• Receipt generation
• Integration with accounting layer

New headers:

• X-Payment-Required: true
• X-Payment-Address: 0x...
• X-Payment-Amount: 0.01 USDC

Priority 6: Webhook Notifications

Why: Async notifications for long operations

Events:

• Stamp purchased
• Stamp becoming unusable (low TTL)
• Upload complete
• Large download complete

Priority 7: Admin Dashboard

Why: Operational visibility

Features:

• Usage metrics
• Active users
• Stamp inventory
• Error rates

Implementation Phases

Phase 1 (MVP)

• Rate limiting (IP-based)
• Upload size limits
• Basic usage logging

Phase 2 (Auth)

• API key authentication
• Per-user rate limits
• Usage tracking per user

Phase 3 (Monetization)

• X402 payment flow
• Accounting/billing
• Pricing tiers

Phase 4 (Enterprise)

• Wallet authentication
• Webhooks
• Admin dashboard

Related Issues

• Implement Cryptographically Signed Document Manifests with Optional Gateway Notary Service #2 - Cryptographic signing

Questions

1. Which auth method to start with?
2. X402 on mainnet or testnet first?
3. Self-hosted vs managed accounting?
4. Open source the full stack or keep billing private?

[crtahlin]

Detailed Design: Three-Tier Access Model with x402

Building on the x402 payment flow outlined above, here's a more detailed design for authentication and rate limiting that supports testing, partner onboarding, and public access.

---

Access Tiers

Tier	Auth	Rate Limit	Cost	Use Case
Public	None (anonymous)	10 req/min, 100/day	Free	Demos, testing, casual users
Partner	x402 (whitelisted wallet)	10,000 req/min	Free	Energonx, partners
Paid	x402 (any wallet)	Unlimited	Pay per use	Production users

---

Request Flow

Request arrives
      ↓
Has X-Payment header?
├─ Yes → Verify signature → Extract wallet
│                                ↓
│                         Wallet in whitelist?
│                         ├─ Yes → PARTNER TIER (high limits, free)
│                         └─ No → PAID TIER (unlimited, pay per use)
│
└─ No → PUBLIC TIER (anonymous, heavily rate limited)

---

Why x402 Signature Matters (Even at $0)

The x402 signature provides cryptographic identity verification:

• Proves request comes from wallet 0xEnergonx...
• Can't be spoofed without private key
• Enables per-wallet usage tracking
• Smooth transition: free → paid (just remove from whitelist)

Even when payment is $0, you get authenticated identity for rate limiting and billing.

---

Public Tier (No x402)

For users without x402 integration, rate limit by IP:

Method	Pros	Cons
IP address	Simple	Shared IPs, VPN bypass
IP + User-Agent	Slightly harder to bypass	Still bypassable

Limits:

• 10 requests/minute
• 100 requests/day
• 1MB max file size

This allows casual testing without requiring x402 setup.

---

Whitelist/Blacklist Management

Whitelist (Partner tier):

{
  "0xEnergonx...": {"tier": "partner", "rate_limit": 10000, "cost": 0},
  "0xDatafund...": {"tier": "partner", "rate_limit": 5000, "cost": 0}
}

Blacklist (Always reject):

{
  "0xSpammer...": {"blocked": true, "reason": "abuse"},
  "0xAbuser...": {"blocked": true, "reason": "TOS violation"}
}

Storage options:

• Config file (simple, needs redeploy)
• Database (dynamic, admin API)
• On-chain (decentralized, complex)

---

Response Headers

Help users understand their tier and limits:

HTTP/1.1 200 OK
X-RateLimit-Tier: public
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1704931200
X-Upgrade-To: x402

---

Rollout Phases

Phase 1 (Testing): BYPASS mode

• Accept all requests
• Log usage for cost projections
• No payment verification

Phase 2 (Pilot): WHITELIST mode

• Only whitelisted wallets (Energonx) + public tier
• Track usage per wallet
• Free for partners

Phase 3 (Production): ENFORCE mode

• Real x402 payments
• Partners remain free (whitelisted)
• Public tier for anonymous access
• Blacklist for abuse prevention

---

Questions to Resolve

1. Where does whitelist/blacklist live? (config file vs database)
2. How to add/remove wallets? (admin API vs manual)
3. What rate limits for each tier?
4. Pricing for paid tier?