AINEP: AI-Native Email Protocol

AINEP is an email extension for the AI-Native Network Protocol (AINP), enabling semantic, intent-driven messaging between AI agents with human-readable addresses like user@demail.ai.

🎯 Vision

demail.ai envisions a decentralized, AI-native email platform where:

• AI agents represent users with human-readable addresses (eprasad7@demail.ai)
• Semantic routing replaces location-based addressing—find agents by capability, not IP
• Multi-round negotiations enable complex interactions (e.g., service requests → offers → counters → confirmations)
• Incentive-aligned economics reduce spam and enable value sharing (e.g., 80/10/10 splits for service providers)
• No intermediaries—direct agent-to-agent communication with cryptographic security

The Problem We're Solving

Traditional email is location-based (you need an IP address or domain). AINEP is capability-based—you find agents by what they can do, not where they are.

Example: Instead of emailing plumber@example.com, you semantically query "find agents who can fix leaks within 2 hours under $200" and the network routes to matching providers.

Why This Matters

1. For Service Providers: Direct connection to customers without platform fees (Thumbtack takes 20%+; AINEP enables 80/10/10 splits)
2. For Users: AI agents handle routine email, negotiations, and scheduling automatically
3. For Developers: Open protocol for building AI-native communication apps
4. For the Ecosystem: Decentralized, interoperable agent communication

🏗️ Architecture

AINEP extends AINP with email-specific capabilities:

┌─────────────────────────────────────────────────────────┐
│                    AINEP Layer                          │
│  Email Intents | Circles | Delegation | Incentives      │
├─────────────────────────────────────────────────────────┤
│                    AINP Layer                           │
│  Envelopes | Signatures | Discovery | Negotiation       │
├─────────────────────────────────────────────────────────┤
│              Infrastructure Layer                        │
│  PostgreSQL+pgvector | NATS | Redis | DIDs             │
└─────────────────────────────────────────────────────────┘

Key Components

• Protocol: AINEP v0.1 (extends AINP v0.1.0)
• Wire Format: JSON-LD + CBOR (RFC 8785 canonicalization)
• Signatures: Ed25519 (JCS → SHA-256 → Ed25519)
• Discovery: Semantic routing via embeddings (1536-dim vectors)
• Identity: DIDs (did:key, did:web) with human-readable aliases

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn

Installation

git clone https://github.com/servesys-labs/demail.git
cd demail
npm install

Basic Usage

const { signEnvelope, verifyEnvelope, validatePayloadShape } = require('./sdk/js/ainep/helpers');
const crypto = require('node:crypto');

// Generate Ed25519 keypair
const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
const publicKeyPem = publicKey.export({ type: 'spki', format: 'pem' }).toString();
const privateKeyPem = privateKey.export({ type: 'pkcs8', format: 'pem' }).toString();

// Create an AINEP envelope (AINP-compatible)
const envelope = {
  version: '0.1.0',
  msg_type: 'INTENT',
  id: crypto.randomUUID(),
  timestamp: Date.now(),
  ttl: 600000,
  trace_id: 'thread-1',
  from_did: 'did:key:z6Mk...',
  to_did: 'did:key:z6Mk...',
  schema: 'https://demail.ai/contexts/email/v1',
  qos: { 
    urgency: 0.5, 
    importance: 0.5, 
    novelty: 0.2, 
    ethicalWeight: 0.1, 
    bid: 0 
  },
  payload: {
    '@type': 'ainep:ComposeEmail',
    subject: 'Hello',
    body: 'This is a test email',
  },
};

// Validate payload
const validation = validatePayloadShape(envelope.payload);
if (!validation.ok) {
  console.error('Validation error:', validation.error);
  process.exit(1);
}

// Sign envelope
envelope.sig = signEnvelope(envelope, privateKeyPem);

// Verify signature
const isValid = verifyEnvelope(envelope, publicKeyPem);
console.log('Signature valid:', isValid);

Run Examples

# Run Circles collaboration demo
npm run demo

# Run service economy PoC (full negotiation flow)
npm run demo:poc

# Run comprehensive verification
npm run verify

# Run tests
npm test

📋 Features

Core Email Intents

Intent	Purpose	Example
ComposeEmail	Send email with subject, body, attachments	Standard email composition
RequestService	Request services (plumbing, repairs, etc.)	"Fix leak within 2 hours under $200"
Offer	Service provider makes an offer	"Can do it for $180 in 45 minutes"
Counter	Negotiate terms	"How about $190 with warranty?"
Confirm	Accept offer	"Deal! Schedule it."
Cancel	Cancel request/offer	"No longer needed"
Settle	Release escrow, settle payment	"Job complete, release payment"

Extensions (RFC 002)

• Circles: Shared workspaces for multi-agent collaboration
• Delegation: Forward threads with policy metadata ("You may reply up to $150")
• Meeting Requests: Temporal-aware scheduling with embeddings
• Incentive Splits: Referral reward distribution (80/10/10 splits)
• Invoicing: Structured invoice payloads for service economy

Schema Validation

All payloads are validated against JSON Schema (schemas/ainep-intents.json) using AJV:

const { validatePayloadShape } = require('./sdk/js/ainep/helpers');

const result = validatePayloadShape({
  '@type': 'ainep:ComposeEmail',
  subject: 'Hello',
  body: 'World',
});

if (!result.ok) {
  console.error('Validation errors:', result.errors);
}

📁 Project Structure

demail/
├── docs/
│   ├── rfcs/
│   │   ├── 001-AINEP-SPEC.md          # Core AINEP specification
│   │   └── 002-AINEP-Extensions.md    # Extensions (Circles, etc.)
│   └── vision/
│       └── brainstorm.md              # Implementation plan & roadmap
├── schemas/
│   └── ainep-intents.json             # JSON Schema for all payload types
├── contexts/
│   └── email/
│       └── v1.jsonld                  # JSON-LD context
├── sdk/
│   └── js/
│       └── ainep/
│           ├── helpers.js             # Core helpers (sign, verify, validate)
│           ├── helpers.test.js        # Test suite (24 tests)
│           └── examples/
│               └── circles_demo.js    # Collaboration demo
└── examples/
    └── prototypes/
        ├── auto_action_extraction.py  # Python prototype
        └── requirements.txt           # Python dependencies

🔗 Integration with AINP

AINEP is fully compatible with AINP v0.1.0:

• ✅ Uses AINP envelope structure
• ✅ Follows AINP signing rules (JCS → SHA-256 → Ed25519)
• ✅ Reuses AINP QoS parameters
• ✅ Compatible with AINP discovery and routing
• ✅ RFC 8785 compliant canonicalization (via json-canonicalize)

AINP Envelope Structure

interface AINEPEnvelope {
  version: "0.1.0";
  msg_type: "INTENT" | "NEGOTIATE" | "RESULT" | "ERROR";
  id: string;                    // UUID v4
  timestamp: number;             // epoch ms
  ttl: number;                   // ms
  trace_id: string;              // thread ID
  from_did: string;              // did:key / did:web
  to_did?: string;               // direct recipient
  to_query?: CapabilityQuery;    // semantic discovery
  schema: "https://demail.ai/contexts/email/v1";
  qos: QoSParameters;
  payload?: AINEPPayload;        // Email-specific payload
  sig: string;                   // base64 Ed25519 signature
}

🧪 Testing

Comprehensive test suite covering all helper functions:

npm test

Test Coverage (24 tests, all passing ✅):

• Canonicalization (RFC 8785 compliance)
• Envelope signing and verification
• Schema validation for all payload types
• Priority computation
• Error handling

📚 Documentation

• RFC 001: AINEP Specification: Core protocol specification
• RFC 002: AINEP Extensions: Collaboration features (Circles, delegation)
• Vision & Roadmap: Implementation plan, timeline, and goals
• PoC Status: What's working vs what's pending
• Quick Wins: Fastest ways to complete PoC

🐍 Python Support

Python prototype available in examples/prototypes/:

cd examples/prototypes
pip install -r requirements.txt
export OPENAI_API_KEY=your-key
python auto_action_extraction.py

🛣️ Roadmap

Phase 0.1 (Current) ✅

• Core protocol specification (RFC 001)
• Extensions specification (RFC 002)
• JavaScript SDK with signing/verification
• Schema validation
• Test suite

Phase 0.2 (Next)

• Alias resolution service (mock resolver: scripts/mock-resolver.js) ✅
• Inbox management (sdk/js/ainep/inbox.js) ✅
• DID generation (sdk/js/ainep/did-helpers.js) ✅
• Auto-response rules
• Discovery integration with AINP
• AINP broker integration

Phase 1.0 (MVP - Q2 2026)

• Full negotiation engine
• Web/mobile client
• Service economy flows (plumber example)
• 1,000+ users/agents

See Vision Document for detailed timeline.

🤝 Contributing

We welcome contributions! Areas where help is needed:

1. Protocol Implementation: Complete alias resolution, inbox management
2. SDKs: Python SDK, TypeScript SDK improvements
3. Examples: More demo applications
4. Documentation: Tutorials, API docs, integration guides
5. Testing: More test coverage, integration tests

Development Setup

# Clone repository
git clone https://github.com/servesys-labs/demail.git
cd demail

# Install dependencies
npm install

# Run tests
npm test

# Run demo
npm run demo

Code Style

• JavaScript: Follow Node.js conventions
• Use json-canonicalize for canonicalization (RFC 8785)
• Validate all payloads with AJV
• Write tests for new features

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Built on AINP - AI-Native Network Protocol
• Uses json-canonicalize for RFC 8785 compliance
• Inspired by decentralized email and AI agent communication protocols

🔗 Related Projects

• AINP: Base protocol for AI agent communication
• demail.ai: Planned email service (future)

📧 Contact

• Repository: https://github.com/servesys-labs/demail
• Issues: https://github.com/servesys-labs/demail/issues
• Organization: Servesys Labs

---

Status: Draft (Phase 0.1) - Active development
Last Updated: 2025-01-24