Collect - Receiver-Pays Messaging Protocol

Decentralized messaging with EIP-4844 blob storage and ERC-4337 account abstraction

Overview

Collect is a receiver-pays messaging protocol that leverages Ethereum's EIP-4844 blob storage for cost-effective encrypted message delivery. Recipients pay to decrypt messages, creating a spam-resistant communication system.

Key Features

• 📦 EIP-4844 Blob Storage: Store up to 125 KB messages in blob transactions
• 🔐 End-to-End Encryption: AES-256-GCM encryption with ECDH key exchange
• 💰 Receiver-Pays Model: Recipients pay fees to decrypt messages
• ⛽ Account Abstraction: ERC-4337 paymaster for gasless posting
• 📊 Dynamic Pricing: Fees adjust based on blob base fee and congestion
• 🚀 Production Ready: Comprehensive test suite with 100% passing tests

Quick Start

# Clone the repository
git clone https://github.com/douglance/collect.git
cd collect

# Check prerequisites
./check-prerequisites.sh

# Run complete test suite
./test-all.sh

# Try the interactive demo
./demo.js

Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Sender    │────▶│  MessageHub  │────▶│   Blobs     │
└─────────────┘     └──────────────┘     └─────────────┘
                            │
                            ▼
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  Receiver   │────▶│  FeeOracle   │     │ Paymaster   │
└─────────────┘     └──────────────┘     └─────────────┘

Smart Contracts

• MessageHub: Core messaging contract for posting and opening messages
• FeeOracle: Dynamic fee calculation based on blob base fees
• CollectPaymaster: ERC-4337 paymaster for sponsored transactions

Backend Services

• API Gateway: RESTful endpoints for message operations
• Blob Service: Handles blob storage and retrieval
• Relayer: Manages transaction submission
• Cost Oracle: Monitors blob base fees

Frontend

• React/Next.js 14 inbox application
• Wallet integration with wagmi
• Real-time message display

Installation

Prerequisites

• Node.js 18+
• Foundry
• Docker & Docker Compose
• MetaMask or compatible wallet

Setup

1. Install dependencies

   npm install
   cd client && npm install

2. Configure environment

   cp .env.example .env
   # Edit .env with your settings

3. Deploy contracts locally

   # Start local blockchain
   anvil
   
   # Deploy contracts
   forge script script/Deploy.s.sol:DeployScript --rpc-url http://localhost:8545 --broadcast

4. Start services

   docker-compose up

5. Start frontend

   cd client
   npm run dev

Testing

Unit Tests

# Run all smart contract tests
forge test --gas-report

# Run specific test suite
forge test --match-contract MessageHubTest -vvv

Integration Tests

# Run complete test suite
./test-all.sh

# Interactive demo
./demo.js

# Load testing (50 messages)
./load-test.js

Test Coverage

• ✅ 68 smart contract tests (100% passing)
• ✅ Service integration tests
• ✅ End-to-end flow tests
• ✅ Load testing (>5 msg/sec throughput)

Deployment

Base Sepolia Testnet

1. Set environment variables

   export PRIVATE_KEY=<your-private-key>
   export BASE_SEPOLIA_RPC=https://sepolia.base.org

2. Deploy contracts

   make deploy-testnet

3. Verify deployment

   forge script script/Verify.s.sol:VerifyScript --rpc-url $BASE_SEPOLIA_RPC

See DEPLOYMENT.md for detailed instructions.

Usage Example

// Send encrypted message
const messageId = await messageHub.post(
  blobHash,           // Blob transaction hash
  encryptedKey,       // Encrypted AES key
  sizeKB,            // Message size
  recipientAddress   // Recipient
);

// Recipient opens message
await messageHub.open(messageId, { value: fee });

// Decrypt with retrieved key
const decryptedMessage = decrypt(encryptedData, key);

Gas Costs

Operation	Gas Used	Cost (at 30 gwei)
Post Message	~180,000	~0.0054 ETH
Open Message	~50,000	~0.0015 ETH
Update Fee	~35,000	~0.0011 ETH

Security

• AES-256-GCM encryption for message content
• ECDH key exchange for secure key sharing
• Keys stored only in memory, never persisted
• Comprehensive access controls
• Pausable contracts for emergency response

Documentation

• Testing Guide - Complete testing documentation
• Deployment Guide - Production deployment instructions
• PRD Specification - Product requirements document
• API Reference - API documentation

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run tests (forge test)
4. Commit changes (git commit -m 'Add amazing feature')
5. Push to branch (git push origin feature/amazing-feature)
6. Open a Pull Request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

• Built on Foundry
• Leverages EIP-4844 blob transactions
• Implements ERC-4337 account abstraction
• Deployed on Base Layer 2

---

Built with ❤️ for the Ethereum ecosystem