HeresMyGit 9a831636a5 feat(xmtp): add Web3 messaging channel via XMTP protocol

Add new XMTP channel extension for decentralized messaging:
- Direct messages (DMs) and group conversations
- Text messages, reactions, and attachments
- ENS address resolution for human-readable names
- Quantum-resistant encryption (MLS protocol)
- Multi-account support with per-account configuration
- Database isolation and network selection (dev/production)
- Comprehensive onboarding with wallet generation

Includes wallet generation scripts, example configurations,
troubleshooting guide, and test coverage for schemas, ENS
resolution, multi-account handling, and onboarding flows.

Note: Tests use Node's test runner format (node:test) and
should be converted to Vitest format in follow-up work.

2026-01-26 21:18:10 -08:00

3.5 KiB

Raw Blame History

XMTP Configuration Examples

This directory contains example configurations for different XMTP deployment scenarios.

Available Examples

1. Development Network (`dev-network.json5`)

Use when:

Testing XMTP integration locally
Development and debugging
Free to use, no gas costs
Messages don't persist long-term

Best for: First-time setup, experimentation, CI/CD testing.

2. Production Network (`production-network.json5`)

Use when:

Deploying to production
Real user conversations
Permanent message storage required

Cost: ~$5 USDC per 100k messages (one-time setup cost for identity registration).

Important: Production network data is permanent and cannot be migrated to dev network.

3. Multi-Account (Coming Soon)

Status: Not yet implemented. XMTP plugin currently supports single wallet only.

Planned features:

Multiple bot wallets in one Clawdbot instance
Per-wallet DM policies
Wallet-specific authorization rules

Quick Start

Choose your network:
- New users → start with dev-network.json5
- Production deployments → use production-network.json5

Generate a wallet:

clawdbot onboard xmtp
# OR manually:
npx tsx scripts/generate-wallet.ts

Copy example config:

# For dev network:
cp examples/dev-network.json5 my-config.json5

# Edit and add your wallet key:
# walletKey: "0x..." (64 hex characters from wallet generation)

Set environment variables (alternative to config file):

export XMTP_WALLET_KEY="0x..."
export XMTP_ENV="dev"  # or "production"

Start Clawdbot:
```
clawdbot gateway start
```

Configuration Precedence

Config file > Environment variables

If both are set:

channels.xmtp.walletKey in config overrides XMTP_WALLET_KEY
channels.xmtp.env in config overrides XMTP_ENV

Important Notes

Network Isolation

Dev and production networks are completely separate
A wallet's messages on dev won't appear on production
Choose carefully before deploying to production

Wallet Security

Never commit wallet keys to git
Store production keys in secure environment variables or secrets manager
Use separate wallets for dev and production

Database Paths

Each wallet needs its own database directory
Default: .xmtp/db (relative to working directory)
Production: use absolute paths for reliability
Multi-account: different dbPath per wallet required

DM Policies

open: Anyone can message (commands restricted to authorized users)
pairing: Requires approval via clawdbot pairing approve xmtp <code>
allowlist: Only addresses in allowFrom can message

Recommendation: Start with pairing for security, switch to open only if needed.

Troubleshooting

"Wallet key validation failed"

Key must be 66 characters: 0x + 64 hex digits
Check for typos, missing 0x prefix, or extra whitespace

"Network mismatch detected"

Database was created on a different network
Solution: Use different dbPath or delete old database

"DB path not writable"

Ensure directory exists and has write permissions
Don't use /tmp (cleared on reboot)
Use persistent paths like ~/.xmtp/db or /var/lib/xmtp/db

3.5 KiB Raw Blame History