diff --git a/.agents/AGENTS.md b/.agents/AGENTS.md index 30dc184f2..d8878c4f4 100644 --- a/.agents/AGENTS.md +++ b/.agents/AGENTS.md @@ -182,7 +182,7 @@ Read subagents on-demand. Full index: `subagent-index.toon`. | Content/Video/Voice | `content.md`, `tools/video/video-prompt-design.md`, `tools/voice/speech-to-speech.md` | | SEO | `seo/dataforseo.md`, `seo/google-search-console.md` | | WordPress | `tools/wordpress/wp-dev.md`, `tools/wordpress/mainwp.md` | -| Communications | `services/communications/matterbridge.md`, `services/communications/simplex.md`, `services/communications/matrix-bot.md` | +| Communications | `services/communications/matterbridge.md`, `services/communications/simplex.md`, `services/communications/matrix-bot.md`, `services/communications/bitchat.md`, `services/communications/xmtp.md` | | Email | `tools/ui/react-email.md`, `services/email/email-testing.md`, `services/email/email-agent.md` | | Payments | `services/payments/revenuecat.md`, `services/payments/stripe.md`, `services/payments/procurement.md` | | Security/Encryption | `tools/security/tirith.md`, `tools/security/opsec.md`, `tools/credentials/encryption-stack.md` | diff --git a/.agents/services/communications/bitchat.md b/.agents/services/communications/bitchat.md new file mode 100644 index 000000000..467b6723e --- /dev/null +++ b/.agents/services/communications/bitchat.md @@ -0,0 +1,282 @@ +--- +description: Bitchat — decentralized peer-to-peer messaging over Bluetooth mesh networks, no internet required, Noise Protocol encryption, multi-hop relay, iOS/Android/macOS +mode: subagent +tools: + read: true + write: false + edit: false + bash: true + glob: false + grep: false + webfetch: false + task: false +--- + +# Bitchat + + + +## Quick Reference + +- **Type**: Decentralized P2P messaging over Bluetooth mesh — no internet, no servers, no phone numbers +- **License**: Unlicense (public domain) +- **Apps**: iOS 16.0+, Android 8.0+ (API 26), macOS 13.0+ +- **Protocol**: Noise_XX_25519_ChaChaPoly_SHA256 (E2E encrypted) +- **Transport**: Bluetooth Low Energy (BLE), extensible to Wi-Fi Direct +- **Repo**: [github.com/permissionlesstech/bitchat](https://github.com/permissionlesstech/bitchat) (iOS/macOS, Swift) +- **Android repo**: [github.com/permissionlesstech/bitchat-android](https://github.com/permissionlesstech/bitchat-android) +- **Website**: [bitchat.free](https://bitchat.free/) +- **Whitepaper**: [WHITEPAPER.md](https://github.com/permissionlesstech/bitchat/blob/main/WHITEPAPER.md) + +**Key differentiator**: Bitchat operates entirely without internet infrastructure. Devices form ad-hoc Bluetooth mesh networks, relaying messages across multiple hops. This makes it uniquely suited for protests, natural disasters, remote areas, or any scenario where internet connectivity is unavailable, monitored, or disabled. + +**When to use Bitchat vs other protocols**: + +| Criterion | Bitchat | SimpleX | Matrix | XMTP | +|-----------|---------|---------|--------|------| +| Internet required | No | Yes | Yes | Yes | +| Transport | BLE mesh | SMP relays | Client-server | Decentralized nodes | +| User identifiers | Fingerprint (pubkey hash) | None | `@user:server` | Wallet/DID | +| Range | Physical proximity (~100m per hop, multi-hop relay) | Global | Global | Global | +| Best for | Offline/local comms, censorship resistance | Maximum privacy | Team collaboration | Web3/agent messaging | + + + +## Architecture + +```text +┌──────────────────────┐ ┌──────────────────────┐ +│ Device A │ │ Device B │ +│ (iOS/Android/macOS) │ │ (iOS/Android/macOS) │ +│ │ │ │ +│ ┌──────────────────┐ │ │ ┌──────────────────┐ │ +│ │ Application Layer│ │ │ │ Application Layer│ │ +│ │ BitchatMessage │ │ │ │ BitchatMessage │ │ +│ ├──────────────────┤ │ │ ├──────────────────┤ │ +│ │ Session Layer │ │ │ │ Session Layer │ │ +│ │ BitchatPacket │ │ │ │ BitchatPacket │ │ +│ ├──────────────────┤ │ │ ├──────────────────┤ │ +│ │ Encryption Layer │ │ │ │ Encryption Layer │ │ +│ │ Noise XX │ │ │ │ Noise XX │ │ +│ ├──────────────────┤ │ │ ├──────────────────┤ │ +│ │ Transport Layer │ │ │ │ Transport Layer │ │ +│ │ BLE │ │ │ │ BLE │ │ +│ └──────────────────┘ │ │ └──────────────────┘ │ +└──────────┬───────────┘ └──────────┬───────────┘ + │ │ + │ Bluetooth Low Energy │ + │ (multi-hop mesh relay) │ + └────────────────────────────┘ + │ + ┌────────▼────────┐ + │ Device C (relay) │ + │ Decrements TTL, │ + │ forwards packet │ + └─────────────────┘ +``` + +**Message flow**: + +1. Sender composes message, serialized as `BitchatPacket` (compact binary format) +2. Noise XX handshake establishes E2E encrypted session (if not already active) +3. Packet encrypted with ChaCha20-Poly1305 via Noise transport cipher +4. Packet padded to standard block size (256/512/1024/2048 bytes) to resist traffic analysis +5. Transmitted over BLE to nearby peers +6. Relay peers decrement TTL and forward to their neighbors (multi-hop) +7. Recipient decrypts with their Noise session cipher +8. Delivery acknowledgment sent back through the mesh + +## Protocol + +### Noise Protocol + +Bitchat uses **Noise_XX_25519_ChaChaPoly_SHA256**: + +- **XX pattern**: Mutual authentication without prior key knowledge — ideal for ad-hoc P2P +- **Curve25519**: Diffie-Hellman key exchange +- **ChaCha20-Poly1305**: AEAD cipher for transport encryption +- **SHA-256**: Cryptographic hashing + +The XX handshake is a 3-message exchange providing: + +- **Forward secrecy**: Compromise of long-term keys does not compromise past sessions +- **Mutual authentication**: Both parties verify each other's identity +- **Deniability**: Difficult to cryptographically prove a specific user sent a message + +### Identity and Keys + +Each device generates two persistent key pairs on first launch, stored in the device Keychain: + +| Key | Algorithm | Purpose | +|-----|-----------|---------| +| Noise static key | Curve25519 | Long-term identity for Noise handshake | +| Signing key | Ed25519 | Signing announcements, binding pubkey to nickname | + +**Fingerprint**: `SHA256(StaticPublicKey_Curve25519)` — used for out-of-band identity verification (QR code, read aloud). + +### Packet Format + +Compact binary format minimizing bandwidth: + +| Field | Size | Description | +|-------|------|-------------| +| Version | 1 byte | Protocol version (currently `1`) | +| Type | 1 byte | Message type (message, deliveryAck, handshake, etc.) | +| TTL | 1 byte | Time-to-live for mesh routing, decremented per hop | +| Timestamp | 8 bytes | Millisecond timestamp | +| Flags | 1 byte | Bitmask: hasRecipient, hasSignature, isCompressed | +| Payload Length | 2 bytes | Length of payload | +| Sender ID | 8 bytes | Truncated peer ID | +| Recipient ID | 8 bytes (optional) | Truncated peer ID, or `0xFF..FF` for broadcast | +| Payload | Variable | Message content | +| Signature | 64 bytes (optional) | Ed25519 signature | + +All packets padded to next block size (PKCS#7-style) to obscure true message length. + +### Social Trust Layer + +- **Peer verification**: Out-of-band fingerprint comparison, marked as "verified" locally +- **Favorites**: Prioritize trusted/frequent contacts +- **Blocking**: Discard packets from blocked fingerprints at earliest stage + +## Installation + +### iOS / macOS + +**App Store**: [Bitchat Mesh](https://apps.apple.com/us/app/bitchat-mesh/id6748219622) + +**Build from source**: + +```bash +git clone https://github.com/permissionlesstech/bitchat.git +cd bitchat + +# Build with Xcode (requires Xcode 15+) +# Open in Xcode or use xcodegen/SPM +xcodebuild -scheme BitChat -destination 'platform=iOS Simulator' +``` + +Requires iOS 16.0+ or macOS 13.0+. + +### Android + +**Play Store**: [Bitchat](https://play.google.com/store/apps/details?id=com.bitchat.droid) + +**APK releases**: [GitHub Releases](https://github.com/permissionlesstech/bitchat-android/releases) + +**Build from source**: + +```bash +git clone https://github.com/permissionlesstech/bitchat-android.git +cd bitchat-android + +# Build with Gradle (requires Android SDK, API 26+) +./gradlew assembleDebug +``` + +Requires Android 8.0+ (API 26). Full protocol compatibility with iOS version. + +## Usage + +### Basic Operation + +1. Install the app on two or more devices +2. Enable Bluetooth on all devices +3. Devices automatically discover peers via BLE advertising +4. Tap a discovered peer to initiate Noise handshake +5. Exchange messages — they relay through intermediate devices if needed + +### Mesh Networking + +- Each device acts as both client and relay +- Messages hop through intermediate devices to extend range +- TTL field prevents infinite relay loops +- No central coordinator — fully ad-hoc topology +- Network forms and dissolves as devices enter/leave proximity + +### Broadcast vs Direct + +- **Direct message**: Recipient ID set to target peer's truncated ID +- **Broadcast**: Recipient ID set to `0xFF..FF`, delivered to all peers in range + +## Limitations + +### Range + +BLE range is approximately 100 meters per hop in open air, significantly less indoors or in dense environments. Multi-hop relay extends effective range but adds latency. + +### Bandwidth + +BLE throughput is limited (~1 Mbps theoretical, lower in practice). Bitchat is designed for text messaging, not file transfer. Packet padding further reduces effective throughput. + +### Availability + +Communication requires physical proximity. Unlike internet-based protocols, messages cannot be delivered when the recipient is out of mesh range. There is no store-and-forward mechanism for offline recipients. + +### Platform + +- iOS/macOS: Swift, requires Xcode to build +- Android: Kotlin/Java, requires Android SDK +- No desktop Linux/Windows client currently +- No CLI or bot API (native app only) + +### No Bot API + +Unlike SimpleX or Matrix, Bitchat has no WebSocket/REST API for programmatic access. Integration with aidevops would require building a native bridge or waiting for upstream API support. + +## Security Considerations + +### Threat Model + +Bitchat protects against: + +- **Internet surveillance**: No internet traffic to monitor +- **Server compromise**: No servers exist +- **Network censorship**: Cannot block Bluetooth mesh without physical jamming +- **Traffic analysis**: Packet padding and uniform sizes resist analysis +- **Identity correlation**: Fingerprints are pubkey hashes, no phone/email required + +Bitchat does **not** protect against: + +- **Physical proximity attacks**: Attacker within BLE range can observe encrypted traffic +- **Device compromise**: Local Keychain contains all keys +- **Bluetooth jamming**: Physical-layer denial of service +- **Relay manipulation**: Malicious relay nodes can drop (but not read) packets +- **Sybil attacks**: No cost to creating multiple identities in the mesh + +### Operational Security + +- Verify peer fingerprints out-of-band before trusting +- Use blocking to silence unwanted peers +- Be aware that BLE advertising reveals device presence to nearby observers +- Bitchat does not hide the fact that you are running the app from nearby BLE scanners + +## Integration with aidevops + +### Current Status + +Bitchat has no programmatic API — it is a native mobile/desktop app only. Direct integration with aidevops runners is not currently possible. + +### Future Possibilities + +- **Native bridge**: A macOS app could bridge Bitchat messages to a local WebSocket, similar to how SimpleX CLI exposes its bot API +- **Matterbridge adapter**: If Bitchat adds a CLI or API, a Matterbridge adapter could bridge it to Matrix/SimpleX/etc. +- **Offline dispatch**: For field scenarios, Bitchat could relay task results between devices when internet is unavailable + +### Use Cases for aidevops + +| Scenario | Value | +|----------|-------| +| Field operations | Relay AI-generated reports between devices without internet | +| Protest/disaster comms | Censorship-resistant messaging for coordination | +| Air-gapped environments | Communicate between devices in secure facilities | +| Local mesh notifications | Alert nearby team members of deployment status | + +## Related + +- `services/communications/simplex.md` — SimpleX Chat (zero-knowledge, internet-based) +- `services/communications/matrix-bot.md` — Matrix bot integration (federated, internet-based) +- `services/communications/xmtp.md` — XMTP (Web3 messaging, internet-based) +- `services/communications/matterbridge.md` — Multi-platform chat bridge +- `tools/security/opsec.md` — Operational security guidance +- Bitchat Whitepaper: https://github.com/permissionlesstech/bitchat/blob/main/WHITEPAPER.md diff --git a/.agents/services/communications/matterbridge.md b/.agents/services/communications/matterbridge.md index f9c938725..fd8332a68 100644 --- a/.agents/services/communications/matterbridge.md +++ b/.agents/services/communications/matterbridge.md @@ -464,5 +464,7 @@ See `tools/security/opsec.md` for full platform trust matrix and threat modeling - `services/communications/matrix-bot.md` — Matrix bot for aidevops runner dispatch - `services/communications/simplex.md` — SimpleX install, bot API, self-hosted servers +- `services/communications/bitchat.md` — Bitchat (Bluetooth mesh, offline P2P) +- `services/communications/xmtp.md` — XMTP (Web3 messaging, agent SDK, payments) - `tools/security/opsec.md` — Platform trust matrix, E2E status, metadata warnings - `tools/ai-assistants/headless-dispatch.md` — Headless dispatch patterns diff --git a/.agents/services/communications/xmtp.md b/.agents/services/communications/xmtp.md new file mode 100644 index 000000000..2aabb9c87 --- /dev/null +++ b/.agents/services/communications/xmtp.md @@ -0,0 +1,429 @@ +--- +description: XMTP — decentralized messaging protocol with quantum-resistant E2E encryption, MLS-based group chats, wallet/DID identity, agent SDK (TypeScript), native payments, spam consent +mode: subagent +tools: + read: true + write: false + edit: false + bash: true + glob: false + grep: false + webfetch: false + task: false +--- + +# XMTP + + + +## Quick Reference + +- **Type**: Decentralized messaging protocol — wallet/DID identity, quantum-resistant E2E encryption, native payments +- **License**: MIT (SDKs), open-source protocol +- **SDKs**: Agent SDK (Node.js), Browser SDK, Node SDK, React Native, Android (Kotlin), iOS (Swift) +- **Agent SDK**: `@xmtp/agent-sdk` (npm) — event-driven middleware architecture +- **Protocol**: MLS (Messaging Layer Security, IETF RFC 9420) with post-quantum hybrid encryption +- **Network**: Decentralized node operators, ~$5 per 100K messages +- **Environments**: `local` (Docker), `dev` (test network), `production` +- **Repo**: [github.com/xmtp](https://github.com/xmtp) (org) | [github.com/xmtp/xmtp-js](https://github.com/xmtp/xmtp-js) (SDKs) +- **Website**: [xmtp.org](https://xmtp.org/) | **Docs**: [docs.xmtp.org](https://docs.xmtp.org/) +- **Playground**: [xmtp.chat](https://xmtp.chat/) (test agents and chat) +- **MCP server**: [github.com/xmtp/xmtp-docs-mcp](https://github.com/xmtp/xmtp-docs-mcp) (AI-ready docs) + +**Key differentiator**: XMTP is identity-agnostic (wallets, passkeys, DIDs, social accounts) with native digital currency support. Messages and payments flow in the same conversation. The protocol uses MLS (the same standard behind Signal and WhatsApp group encryption) with post-quantum extensions, audited by NCC Group. + +**When to use XMTP vs other protocols**: + +| Criterion | XMTP | SimpleX | Matrix | Bitchat | +|-----------|------|---------|--------|---------| +| Identity model | Wallet/DID/passkey | None | `@user:server` | Pubkey fingerprint | +| Encryption | MLS + post-quantum hybrid | Double ratchet (X3DH) | Megolm (optional) | Noise XX | +| Native payments | Yes (in-conversation) | No | No | No | +| Spam protection | Protocol-level consent | Per-connection | Server-side | Physical proximity | +| Agent/bot SDK | First-class (`@xmtp/agent-sdk`) | WebSocket JSON API | `matrix-bot-sdk` | None | +| Decentralization | Node operators (paid) | Stateless relays | Federated servers | BLE mesh (no internet) | +| Best for | Web3 apps, AI agents, payments | Maximum privacy | Team collaboration | Offline/local comms | + + + +## Architecture + +```text +┌──────────────────────┐ ┌──────────────────────┐ +│ Chat App / Agent │ │ Chat App / Agent │ +│ (Browser, Node, RN, │ │ (Browser, Node, RN, │ +│ Android, iOS) │ │ Android, iOS) │ +│ │ │ │ +│ ┌────────────────────┐ │ │ ┌────────────────────┐ │ +│ │ XMTP SDK │ │ │ │ XMTP SDK │ │ +│ │ ├─ MLS encryption │ │ │ │ ├─ MLS encryption │ │ +│ │ ├─ Content types │ │ │ │ ├─ Content types │ │ +│ │ ├─ Consent mgmt │ │ │ │ ├─ Consent mgmt │ │ +│ │ └─ Local SQLite DB │ │ │ │ └─ Local SQLite DB │ │ +│ └────────────────────┘ │ │ └────────────────────┘ │ +└──────────┬─────────────┘ └──────────┬─────────────┘ + │ │ + │ E2E encrypted (MLS) │ + │ │ + ┌──────▼──────────────────────────────▼──────┐ + │ XMTP Network (Decentralized) │ + │ │ + │ ┌────────┐ ┌────────┐ ┌────────┐ │ + │ │ Node 1 │ │ Node 2 │ │ Node 3 │ ... │ + │ └────────┘ └────────┘ └────────┘ │ + │ │ + │ Independent operators, globally distributed│ + │ ~$5 per 100K messages │ + └────────────────────────────────────────────┘ +``` + +**Message flow**: + +1. Sender's SDK encrypts message client-side using MLS group state +2. Encrypted message sent to XMTP network nodes +3. Nodes relay and store messages for offline recipients +4. Recipient's SDK retrieves and decrypts messages locally +5. Content types (text, reactions, attachments, transactions) decoded by SDK +6. Consent system filters spam at protocol level (allow/block per sender) + +## Protocol + +### MLS (Messaging Layer Security) + +XMTP implements [IETF RFC 9420 (MLS)](https://www.rfc-editor.org/rfc/rfc9420) for group encryption: + +- **Post-quantum hybrid encryption**: Protects against "harvest now, decrypt later" attacks +- **Perfect forward secrecy**: Past messages cannot be decrypted if current keys are compromised +- **Post-compromise security**: Security recovers after a key compromise +- **Scalable groups**: Tree-based key management (O(log n) operations per member change) +- **Audited**: NCC Group reviewed XMTP's MLS implementation (same firm that audits Signal and WhatsApp) + +### Identity + +XMTP works with any decentralized identifier (DID): + +| Identity type | Example | +|---------------|---------| +| EOA wallet | `0x1234...abcd` | +| Smart contract wallet | Account abstraction wallets | +| ENS | `alice.eth` | +| Passkey | Device-bound credential | +| Social account | Via DID resolver | +| Custom DID | Any DID method | + +No platform lock-in — developers connect their existing identity model to XMTP. + +### Content Types + +Rich content beyond plain text: + +| Content type | Package | Description | +|-------------|---------|-------------| +| Text | `content-type-text` | Plain text messages | +| Reaction | `content-type-reaction` | Emoji reactions to messages | +| Reply | `content-type-reply` | Threaded replies | +| Read receipt | `content-type-read-receipt` | Read confirmations | +| Remote attachment | `content-type-remote-attachment` | Files stored off-network | +| Transaction reference | `content-type-transaction-reference` | On-chain transaction links | +| Group updated | `content-type-group-updated` | Group membership changes | + +Custom content types can be built using `content-type-primitives`. + +### Consent and Spam Protection + +Protocol-level consent system: + +- Users explicitly allow or block senders across the entire XMTP network +- All consent state is encrypted and user-controlled +- Developers get network-level view of allowed/blocked senders +- No server-side filtering — consent enforced client-side by SDK + +## Installation + +### Agent SDK (Recommended for Bots) + +```bash +# Create project +mkdir my-agent && cd my-agent +npm init --init-type=module -y + +# Install SDK and TypeScript tooling +npm i @xmtp/agent-sdk +npm i -D typescript tsx @types/node +``` + +### Browser SDK + +```bash +npm i @xmtp/browser-sdk +``` + +### Node SDK + +```bash +npm i @xmtp/node-sdk +``` + +### React Native SDK + +```bash +npm i @xmtp/react-native-sdk +``` + +### Mobile SDKs + +- **Android**: [docs.xmtp.org/chat-apps/sdks/android](https://docs.xmtp.org/chat-apps/sdks/android) +- **iOS**: [docs.xmtp.org/chat-apps/sdks/ios](https://docs.xmtp.org/chat-apps/sdks/ios) + +## Agent SDK Usage + +### Environment Variables + +```bash +# .env +XMTP_ENV=dev # local | dev | production +XMTP_WALLET_KEY=0x... # EOA wallet private key +XMTP_DB_ENCRYPTION_KEY=0x... # 64 hex chars (32 bytes) for local SQLite +``` + +### Basic Agent + +```typescript +import { Agent, getTestUrl } from "@xmtp/agent-sdk"; + +// Create agent from .env +const agent = await Agent.createFromEnv(); + +// Respond to text messages +agent.on("text", async (ctx) => { + await ctx.conversation.sendText("Hello from XMTP agent!"); +}); + +// Log when ready +agent.on("start", () => { + console.log(`Address: ${agent.address}`); + console.log(`Test: ${getTestUrl(agent.client)}`); +}); + +await agent.start(); +``` + +### Event-Driven Middleware + +The Agent SDK uses an event-driven architecture with middleware: + +```typescript +// Handle different content types +agent.on("text", async (ctx) => { + const text = ctx.content; + // Process text message +}); + +agent.on("reaction", async (ctx) => { + // Handle reaction +}); + +agent.on("reply", async (ctx) => { + // Handle threaded reply +}); + +// Group chat events +agent.on("group_updated", async (ctx) => { + // Handle member changes +}); +``` + +### Sending Messages + +```typescript +// Send text +await ctx.conversation.sendText("Hello!"); + +// Send to a specific address +const conversation = await agent.client.conversations.newDm( + "0xRecipientAddress" +); +await conversation.sendText("Direct message"); + +// Group chats +const group = await agent.client.conversations.newGroup([ + "0xMember1", + "0xMember2", +]); +await group.sendText("Group message"); +``` + +### Local Database + +Each agent maintains a local SQLite database for device identity and message history: + +- Created in `dbPath` (default: `./`) +- **Must persist across restarts and deployments** +- Limited to 10 installations per inbox — losing the DB creates a new installation +- Encrypted with `XMTP_DB_ENCRYPTION_KEY` + +### Key Constraints + +- **Wallet key required**: Agent needs an EOA wallet private key for identity +- **Local DB persistence**: Database files must survive restarts (use persistent volumes in Docker) +- **Installation limit**: 10 installations per inbox — do not recreate DBs unnecessarily +- **Network cost**: ~$5 per 100K messages on production network +- **Consent**: New conversations require recipient consent before messages are visible + +## Deployment + +### Process Management + +Use PM2 or similar for production: + +```bash +npm i -g pm2 +pm2 start src/agent.ts --interpreter tsx --name xmtp-agent +pm2 save +pm2 startup +``` + +### Docker + +```dockerfile +FROM node:20-slim +WORKDIR /app +COPY package*.json ./ +RUN npm ci +COPY . . +# Persist database files +VOLUME /app/data +ENV XMTP_DB_PATH=/app/data +CMD ["npx", "tsx", "src/agent.ts"] +``` + +### Security + +- Store wallet key and DB encryption key in secure secret management (gopass, env vars) +- Never expose wallet private key in logs or output +- Use `dev` environment for testing, `production` for live agents +- Rate limits apply per agent — see [docs.xmtp.org/agents/deploy/rate-limits](https://docs.xmtp.org/agents/deploy/rate-limits) + +## Production Apps Using XMTP + +| App | Description | +|-----|-------------| +| [Base App](https://base.app/) | Coinbase L2 messaging | +| [World App](https://world.org/) | World (formerly Worldcoin) verified human messaging | +| [Convos](https://converse.xyz/) | XMTP-native messenger | +| [Zora](https://zora.co/) | NFT marketplace messaging | +| [xmtp.chat](https://xmtp.chat/) | Developer playground | + +55M+ connected users, 4,500+ developers, 1,700+ production mini-apps. + +## Comparison with Signal Protocol + +| Aspect | XMTP (MLS) | Signal (Double Ratchet) | SimpleX | +|--------|-----------|------------------------|---------| +| Group encryption | MLS tree (O(log n)) | Sender keys | Per-member ratchet | +| Post-quantum | Hybrid PQ/classical | Not yet | Not yet | +| Identity | Wallet/DID | Phone number | None | +| Payments | Native | No | No | +| Decentralization | Node operators | Centralized | Stateless relays | +| Spam protection | Protocol-level consent | Phone verification | Per-connection | +| Bot/agent SDK | First-class | No official SDK | WebSocket API | +| Audit | NCC Group (MLS) | Multiple audits | Multiple audits | + +## Limitations + +### Wallet Requirement + +Agents and users need a wallet (EOA) or DID for identity. This is a barrier for non-crypto users, though passkey support reduces friction. + +### Network Cost + +Production messaging costs ~$5 per 100K messages, paid to node operators. Free on `dev` network for testing. + +### Installation Limit + +Each inbox is limited to 10 installations (devices/instances). Losing the local database and recreating counts as a new installation. This is a hard limit. + +### No Offline/Mesh Support + +XMTP requires internet connectivity. Unlike Bitchat, there is no offline or mesh networking capability. + +### Ecosystem Maturity + +While growing rapidly (55M users), the ecosystem is younger than Matrix. Some content types and features are still evolving. + +### Web3 Dependency + +The protocol is designed around blockchain identity. Non-Web3 use cases may find the wallet requirement unnecessary overhead, though passkey-based identity reduces this friction. + +## Integration with aidevops + +### Bot/Agent Integration + +XMTP's Agent SDK is well-suited for aidevops runner dispatch: + +```typescript +import { Agent } from "@xmtp/agent-sdk"; + +const agent = await Agent.createFromEnv(); + +agent.on("text", async (ctx) => { + const prompt = ctx.content; + + // Dispatch to aidevops runner + // Similar pattern to Matrix bot dispatch + const result = await dispatchToRunner(prompt); + await ctx.conversation.sendText(result); +}); + +await agent.start(); +``` + +### Potential Architecture + +```text +┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ +│ XMTP Chat │ │ XMTP Agent │ │ aidevops Runner │ +│ (Base, World, │ │ (Node.js) │ │ │ +│ Convos, etc.) │ │ │ │ runner-helper.sh │ +│ │────▶│ 1. Receive msg │────▶│ → AI session │ +│ User sends: │ │ 2. Check consent │ │ → response │ +│ "Review auth.ts" │◀────│ 3. Dispatch │◀────│ │ +│ │ │ 4. Reply │ │ │ +│ AI response │ │ │ │ │ +└──────────────────┘ └──────────────────┘ └──────────────────┘ +``` + +### Matterbridge Integration + +XMTP does not have a native Matterbridge adapter. A custom adapter could be built using the Node SDK and Matterbridge's REST API, following the same pattern as the SimpleX adapter. + +### Use Cases for aidevops + +| Scenario | Value | +|----------|-------| +| Web3 project support | AI agents in Base/World/Convos for developer support | +| Payment-integrated bots | Accept payments for premium AI services in-conversation | +| Multi-agent coordination | XMTP group chats for agent-to-agent communication | +| Cross-platform dispatch | Bridge XMTP messages to aidevops runners via agent SDK | +| Spam-resistant public bots | Protocol-level consent prevents bot abuse | + +## AI-Ready Documentation + +XMTP provides tools for AI-assisted development: + +- **MCP server**: [github.com/xmtp/xmtp-docs-mcp](https://github.com/xmtp/xmtp-docs-mcp) — use with Claude, ChatGPT, or other AI coding assistants +- **llms.txt**: Use-case-based documentation files for LLM context +- **Agent examples**: [github.com/xmtplabs/xmtp-agent-examples](https://github.com/xmtplabs/xmtp-agent-examples) +- **Starter template**: [github.com/xmtp/agent-sdk-starter](https://github.com/xmtp/agent-sdk-starter) + +## Related + +- `services/communications/simplex.md` — SimpleX Chat (zero-knowledge, no identifiers) +- `services/communications/matrix-bot.md` — Matrix bot integration (federated) +- `services/communications/bitchat.md` — Bitchat (Bluetooth mesh, offline) +- `services/communications/matterbridge.md` — Multi-platform chat bridge +- `tools/security/opsec.md` — Operational security guidance +- XMTP Docs: https://docs.xmtp.org/ +- XMTP GitHub: https://github.com/xmtp +- XMTP Agent Examples: https://github.com/xmtplabs/xmtp-agent-examples +- XMTP MLS Audit: https://www.nccgroup.com/research-blog/public-report-xmtp-mls-implementation-review/ diff --git a/.agents/subagent-index.toon b/.agents/subagent-index.toon index 57e4d8ad0..5e116bb9e 100644 --- a/.agents/subagent-index.toon +++ b/.agents/subagent-index.toon @@ -71,7 +71,7 @@ services/accessibility/,Unified web and email accessibility auditing - WCAG comp services/hosting/,Hosting providers - DNS and cloud servers and local dev,local-hosting|localhost|hostinger|hetzner|cloudflare|cloudflare-platform|cloudron|closte services/networking/,Networking - mesh VPN and secure device connectivity,tailscale|netbird services/email/,Email services - transactional email deliverability testing and autonomous mission communication,ses|email-agent|email-health-check|email-testing|email-delivery-test|email-design-test|email-delivery-testing|email-design-testing -services/communications/,Communications - SMS voice Matrix bot and multi-platform chat bridging,twilio|telfon|matrix-bot|matterbridge|simplex +services/communications/,Communications - SMS voice Matrix bot multi-platform chat bridging Bluetooth mesh and Web3 messaging,twilio|telfon|matrix-bot|matterbridge|simplex|bitchat|xmtp services/crm/,CRM integration - contact management,fluentcrm services/analytics/,Website analytics - GA4 reporting,google-analytics services/monitoring/,Error monitoring and debugging,sentry|socket