9a831636a5
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.
120 lines
3.5 KiB
Markdown
120 lines
3.5 KiB
Markdown
# 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
|
|
|
|
1. **Choose your network:**
|
|
- New users → start with `dev-network.json5`
|
|
- Production deployments → use `production-network.json5`
|
|
|
|
2. **Generate a wallet:**
|
|
```bash
|
|
clawdbot onboard xmtp
|
|
# OR manually:
|
|
npx tsx scripts/generate-wallet.ts
|
|
```
|
|
|
|
3. **Copy example config:**
|
|
```bash
|
|
# 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)
|
|
```
|
|
|
|
4. **Set environment variables (alternative to config file):**
|
|
```bash
|
|
export XMTP_WALLET_KEY="0x..."
|
|
export XMTP_ENV="dev" # or "production"
|
|
```
|
|
|
|
5. **Start Clawdbot:**
|
|
```bash
|
|
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`
|
|
|
|
## See Also
|
|
|
|
- [XMTP Channel Documentation](/docs/channels/xmtp.md)
|
|
- [Clawdbot Configuration Guide](https://docs.clawd.bot/gateway/configuration)
|
|
- [XMTP Protocol Docs](https://docs.xmtp.org)
|