```
	⠀⠀⠀⠀⠀⠀⠀⠀⠀⠄⠀⡀⠀⠀⠀⠀⠀⠀⢀⠀⠀⡀⠀⢀⠀⢀⡀⣤⡢⣤⡤⡀⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⡄⡄⠐⡀⠈⣀⠀⡠⡠⠀⣢⣆⢌⡾⢙⠺⢽⠾⡋⣻⡷⡫⢵⣭⢦⣴⠦⠀⢠⠀⠀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⢠⣤⣽⣥⡈⠧⣂⢧⢾⠕⠞⠡⠊⠁⣐⠉⠀⠉⢍⠀⠉⠌⡉⠀⠂⠁⠱⠉⠁⢝⠻⠎⣬⢌⡌⣬⣡⣀⣢⣄⡄⠀⡀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⢀⢸⣿⣿⢿⣾⣯⣑⢄⡂⠀⠄⠂⠀⠀⢀⠀⠀⠐⠀⠀⠀⠀⠀⠀⠀⠀⠄⠐⠀⠀⠀⠀⣄⠭⠂⠈⠜⣩⣿⢝⠃⠀⠁⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⢀⣻⡟⠏⠀⠚⠈⠚⡉⡝⢶⣱⢤⣅⠈⠀⠄⠀⠀⠀⠀⠀⠠⠀⠀⡂⠐⣤⢕⡪⢼⣈⡹⡇⠏⠏⠋⠅⢃⣪⡏⡇⡍⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠺⣻⡄⠀⠀⠀⢠⠌⠃⠐⠉⢡⠱⠧⠝⡯⣮⢶⣴⣤⡆⢐⣣⢅⣮⡟⠦⠍⠉⠀⠁⠐⠀⠀⠀⠄⠐⠡⣽⡸⣎⢁⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⢈⡻⣧⠀⠁⠐⠀⠀⠀⠀⠀⠀⠊⠀⠕⢀⡉⠈⡫⠽⡿⡟⠿⠟⠁⠀⠀⠄⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⠬⠥⣋⡯⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⡀⣾⡍⠕⡀⠀⠀⠀⠄⠠⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠥⣤⢌⠀⠀⠀⠀⠀⠀⠀⠀⠀⠁⠀⠀⠄⢀⠀⢝⢞⣫⡆⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⣽⡶⡄⠐⡀⠀⠀⠀⠀⠀⠀⢀⠀⠄⠀⠀⠀⠄⠁⠇⣷⡆⠀⠀⠀⢀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⡸⢝⣮⠍⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⢀⠀⢾⣷⠀⠠⡀⠀⠀⠀⠀⢀⠀⠀⠀⠀⠀⠁⡁⠀⠀⣾⡥⠖⠀⠀⠀⠂⠀⠀⠀⠀⠀⠁⠀⡀⠁⠀⠀⠻⢳⣻⢄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⣞⡙⠨⣀⠠⠄⠀⠂⠀⠀⠀⠈⢀⠀⠀⠀⠀⠀⠤⢚⢢⣟⠀⠀⠀⠀⡐⠀⠀⡀⠀⠀⠀⠀⠁⠈⠌⠊⣯⣮⡏⠡⠂⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⣻⡟⡄⡡⣄⠀⠠⠀⠀⡅⠀⠐⠀⡀⠀⡀⠀⠄⠈⠃⠳⠪⠤⠀⠀⠀⠀⡀⠀⠂⠀⠀⠀⠁⠈⢠⣠⠒⠻⣻⡧⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠪⡎⠠⢌⠑⡀⠂⠀⠄⠠⠀⠠⠀⠁⡀⠠⠠⡀⣀⠜⢏⡅⠀⠀⡀⠁⠀⠀⠁⠁⠐⠄⡀⢀⠂⠀⠄⢑⣿⣿⣿⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠼⣻⠧⣣⣀⠐⠨⠁⠕⢈⢀⢀⡁⠀⠈⠠⢀⠀⠐⠜⣽⡗⡤⠀⠂⠀⠠⠀⢂⠠⠀⠁⠄⠀⠔⠀⠑⣨⣿⢯⠋⡅⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⡚⣷⣭⠎⢃⡗⠄⡄⢀⠁⠀⠅⢀⢅⡀⠠⠀⢠⡀⡩⠷⢇⠀⡀⠄⡠⠤⠆⣀⡀⠄⠉⣠⠃⠴⠀⠈⢁⣿⡛⡯⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠘⡬⡿⣿⡏⡻⡯⠌⢁⢛⠠⠓⠐⠐⠐⠌⠃⠋⠂⡢⢰⣈⢏⣰⠂⠈⠀⠠⠒⠡⠌⠫⠭⠩⠢⡬⠆⠿⢷⢿⡽⡧⠉⠊⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠺⣷⣺⣗⣿⡶⡎⡅⣣⢎⠠⡅⣢⡖⠴⠬⡈⠂⡨⢡⠾⣣⣢⠀⠀⡹⠄⡄⠄⡇⣰⡖⡊⠔⢹⣄⣿⣭⣵⣿⢷⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠩⣿⣿⣲⣿⣷⣟⣼⠟⣬⢉⡠⣪⢜⣂⣁⠥⠓⠚⡁⢶⣷⣠⠂⡄⡢⣀⡐⠧⢆⣒⡲⡳⡫⢟⡃⢪⡧⣟⡟⣯⠐⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⢺⠟⢿⢟⢻⡗⡮⡿⣲⢷⣆⣏⣇⡧⣄⢖⠾⡷⣿⣤⢳⢷⣣⣦⡜⠗⣭⢂⠩⣹⢿⡲⢎⡧⣕⣖⣓⣽⡿⡖⡿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠉⠂⠂⠏⠿⢻⣥⡪⢽⣳⣳⣥⡶⣫⣍⢐⣥⣻⣾⡻⣅⢭⡴⢭⣿⠕⣧⡭⣞⣻⣣⣻⢿⠟⠛⠙⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠄⠋⠫⠯⣍⢻⣿⣿⣷⣕⣵⣹⣽⣿⣷⣇⡏⣿⡿⣍⡝⠵⠯⠁⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠐⠠⠁⠋⢣⠓⡍⣫⠹⣿⣿⣷⡿⠯⠺⠁⠁⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠋⢀⠋⢈⡿⠿⠁⠉⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
```

# plcbundle

> A Transparent and Verifiable Way to Sync the AT Protocol's PLC Directory

plcbundle is an ecosystem of tools and specifications for archiving [AT Protocol](https://atproto.com/)'s [PLC Directory](https://plc.directory/) into verifiable, distributed bundles. Operations are grouped into immutable bundles of 10,000 each, cryptographically chained together, enabling anyone to host mirrors, verify data integrity, and analyze the DID ecosystem.

**Why plcbundle?**
- 🔒 **Verifiable** - Cryptographic chain ensures data integrity
- 🌐 **Distributed** - Host your own mirror, reduce central dependencies
- 📦 **Efficient** - ~2.5x compression, optimized for storage and transfer
- 🔍 **Transparent** - Open format, reproducible by anyone
- 🛠️ **Ecosystem** - Multiple implementations, tools, and libraries

## Current Implementations

| Repository | Status | Features | Maintainer |
|-----------|--------|----------|-------------|
| **[plcbundle-rs](https://tangled.org/atscan.net/plcbundle-rs)** (Rust) | ✅ Active (unstable) | Library, CLI, Server, Sync | [@tree.fail](https://bsky.app/profile/tree.fail) |
| [plcbundle-go](https://tangled.org/atscan.net/plcbundle-go) (Go) | *Deprecated* | Library, CLI, Server, Sync | [@tree.fail](https://bsky.app/profile/tree.fail) |
| [plcbundle-bun](https://tangled.org/atscan.net/plcbundle-bun) (Bun/TypeScript) | *Experiment* | Library, CLI | [@tree.fail](https://bsky.app/profile/tree.fail) |
| [plcbundle-ref](https://tangled.org/atscan.net/plcbundle-ref) (*various*) | - | Examples in TypeScript, Python, Ruby | [@tree.fail](https://bsky.app/profile/tree.fail) |

## Quick Start

### Installation

```bash
# Rust
cargo install plcbundle

# Docker
docker pull atscan/plcbundle:latest
```

### Basic Usage

```bash
# Sync bundles from plc.directory
plcbundle sync

# Verify chain integrity
plcbundle verify

# Get information
plcbundle info

# Get DID Document
plcbundle resolve tree.fail
plcbundle audit did:plc:524tuhdhh3m7li5gycdn6boe

# Run as HTTP mirror
plcbundle server --sync --resolver --port 8080
```

[Full getting started guide →](./docs/getting-started.md)

## How It Works

```
PLC Directory          Bundle Chain                    Your Mirror
    │                       │                               │
    │   Operations     ┌────▼────┐                          │
    │   0-9,999  ────▶ │Bundle #0│                          │
    │                  │Hash: abc│──┐                       │
    │                  └─────────┘  │                       │
    │   Operations                  │   Cryptographically   │
    │   10,000-19,999 ─────────────▶│   Linked              │
    │                  ┌────▼────┐  │                       │
    │                  │Bundle #1│◀─┘                       │
    │                  │Prev: abc│────────── Sync ────────▶ │
    │                  │Hash: def│                          │
    │                  └─────────┘                          │
    ▼                       ▼                               ▼
```

Each bundle is:
- 📦 Exactly 10,000 operations
- 🔗 Linked to previous bundle via hash
- 🗜️ Compressed with zstd
- ✅ Independently verifiable
- 🔄 Reproducible from source

[Technical details →](./spec/format.md)

## Use Cases

### 🪞 Host a Mirror
Run your own PLC directory mirror to reduce dependency on central infrastructure and improve availability.

### 🗄️ Archive & Backup
Create verifiable backups with cryptographic proof of integrity. Perfect for compliance and long-term archival.

### 🔬 Research & Analytics
Analyze historical DID creation patterns, migrations, and network growth over time.

### 📊 Monitoring & Detection
Track operations, detect anomalies, identify spam patterns, monitor network health.

## Specifications

### Core Specifications
- **[Bundle Format](./spec/format.md)** - Bundle structure, encoding, and compression (v1.0)
- **[HTTP API](./spec/http-api.md)** - Server API for hosting mirrors (v1.0)

### Future Specifications
- WebSocket API - Real-time operation streaming
- P2P Protocol - Peer-to-peer bundle distribution

[All specifications →](./spec/)

## Related Tools

*Building something? [Add it here](https://tangled.org/atscan.net/plcbundle/pulls)*

## Public Instances

You can view all public instances on [plcbundle-watch.pages.dev](https://plcbundle-watch.pages.dev/)

*Host a mirror? [Submit a PR](https://tangled.org/atscan.net/plcbundle/pulls) to add it here*

## Security & Trust

plcbundle provides cryptographic verification but requires external validation:

**✅ Guarantees:**
- Bundle integrity via SHA-256 hashing
- Chain continuity via previous bundle links
- Reproducibility from source operations

**⚠️ You must verify:**
- Operations against original plc.directory
- Bundles from multiple independent sources
- Published root and head hashes

**Never trust a single source.** Always verify.

[Full security model →](./docs/security.md)

## Contributing

We welcome contributions of all kinds:

- 🔨 **Implementations** - Create clients in new languages ([guide](./docs/contributing.md))
- 📖 **Documentation** - Improve guides, fix typos, add examples
- 🐛 **Issues** - [Report bugs](https://tangled.org/atscan/plcbundle/issues) or suggest features
- 🧪 **Test Vectors** - Help ensure implementation compatibility
- 🪞 **Mirrors** - Host bundles and share your endpoint
- 💬 **Discussion** - Share your ideas

[Contributing guide →](./docs/contributing.md)

## Community & Support

- 🐛 [Issue Tracker](https://github.com/yourusername/plcbundle/issues) - Report bugs
- 📰 [Announcement Article](https://leaflet.pub/feb982b4-64cb-4549-9d25-d7e68cecb11a) - Background and motivation

## Resources

- 📐 [AT Protocol Documentation](https://atproto.com/)
- 🆔 [DID PLC Specification](https://web.plc.directory/)

## License

MIT License - See [LICENSE](./LICENSE) for details.

Individual implementations may have different licenses - check their repositories.