A Transparent and Verifiable Way to Sync the AT Protocol's PLC Directory
atscan.net
tree.fail
1```
2 ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠄⠀⡀⠀⠀⠀⠀⠀⠀⢀⠀⠀⡀⠀⢀⠀⢀⡀⣤⡢⣤⡤⡀⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
3⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⡄⡄⠐⡀⠈⣀⠀⡠⡠⠀⣢⣆⢌⡾⢙⠺⢽⠾⡋⣻⡷⡫⢵⣭⢦⣴⠦⠀⢠⠀⠀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
4⠀⠀⠀⠀⠀⠀⠀⠀⢠⣤⣽⣥⡈⠧⣂⢧⢾⠕⠞⠡⠊⠁⣐⠉⠀⠉⢍⠀⠉⠌⡉⠀⠂⠁⠱⠉⠁⢝⠻⠎⣬⢌⡌⣬⣡⣀⣢⣄⡄⠀⡀⠀⠀⠀⠀⠀⠀⠀⠀
5⠀⠀⠀⠀⠀⠀⠀⢀⢸⣿⣿⢿⣾⣯⣑⢄⡂⠀⠄⠂⠀⠀⢀⠀⠀⠐⠀⠀⠀⠀⠀⠀⠀⠀⠄⠐⠀⠀⠀⠀⣄⠭⠂⠈⠜⣩⣿⢝⠃⠀⠁⠀⠀⠀⠀⠀⠀⠀⠀
6⠀⠀⠀⠀⠀⠀⠀⢀⣻⡟⠏⠀⠚⠈⠚⡉⡝⢶⣱⢤⣅⠈⠀⠄⠀⠀⠀⠀⠀⠠⠀⠀⡂⠐⣤⢕⡪⢼⣈⡹⡇⠏⠏⠋⠅⢃⣪⡏⡇⡍⠀⠀⠀⠀⠀⠀⠀⠀⠀
7⠀⠀⠀⠀⠀⠀⠀⠀⠺⣻⡄⠀⠀⠀⢠⠌⠃⠐⠉⢡⠱⠧⠝⡯⣮⢶⣴⣤⡆⢐⣣⢅⣮⡟⠦⠍⠉⠀⠁⠐⠀⠀⠀⠄⠐⠡⣽⡸⣎⢁⠀⠀⠀⠀⠀⠀⠀⠀⠀
8⠀⠀⠀⠀⠀⠀⠀⢈⡻⣧⠀⠁⠐⠀⠀⠀⠀⠀⠀⠊⠀⠕⢀⡉⠈⡫⠽⡿⡟⠿⠟⠁⠀⠀⠄⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⠬⠥⣋⡯⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
9⠀⠀⠀⠀⠀⠀⠀⡀⣾⡍⠕⡀⠀⠀⠀⠄⠠⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠥⣤⢌⠀⠀⠀⠀⠀⠀⠀⠀⠀⠁⠀⠀⠄⢀⠀⢝⢞⣫⡆⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀
10⠀⠀⠀⠀⠀⠀⠀⠀⣽⡶⡄⠐⡀⠀⠀⠀⠀⠀⠀⢀⠀⠄⠀⠀⠀⠄⠁⠇⣷⡆⠀⠀⠀⢀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⡸⢝⣮⠍⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
11⠀⠀⠀⠀⠀⠀⢀⠀⢾⣷⠀⠠⡀⠀⠀⠀⠀⢀⠀⠀⠀⠀⠀⠁⡁⠀⠀⣾⡥⠖⠀⠀⠀⠂⠀⠀⠀⠀⠀⠁⠀⡀⠁⠀⠀⠻⢳⣻⢄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
12⠀⠀⠀⠀⠀⠀⠀⠀⣞⡙⠨⣀⠠⠄⠀⠂⠀⠀⠀⠈⢀⠀⠀⠀⠀⠀⠤⢚⢢⣟⠀⠀⠀⠀⡐⠀⠀⡀⠀⠀⠀⠀⠁⠈⠌⠊⣯⣮⡏⠡⠂⠀⠀⠀⠀⠀⠀⠀⠀
13⠀⠀⠀⠀⠀⠀⠀⠀⣻⡟⡄⡡⣄⠀⠠⠀⠀⡅⠀⠐⠀⡀⠀⡀⠀⠄⠈⠃⠳⠪⠤⠀⠀⠀⠀⡀⠀⠂⠀⠀⠀⠁⠈⢠⣠⠒⠻⣻⡧⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
14⠀⠀⠀⠀⠀⠀⠀⠀⠪⡎⠠⢌⠑⡀⠂⠀⠄⠠⠀⠠⠀⠁⡀⠠⠠⡀⣀⠜⢏⡅⠀⠀⡀⠁⠀⠀⠁⠁⠐⠄⡀⢀⠂⠀⠄⢑⣿⣿⣿⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀
15⠀⠀⠀⠀⠀⠀⠀⠀⠼⣻⠧⣣⣀⠐⠨⠁⠕⢈⢀⢀⡁⠀⠈⠠⢀⠀⠐⠜⣽⡗⡤⠀⠂⠀⠠⠀⢂⠠⠀⠁⠄⠀⠔⠀⠑⣨⣿⢯⠋⡅⠀⠀⠀⠀⠀⠀⠀⠀⠀
16⠀⠀⠀⠀⠀⠀⠀⠀⡚⣷⣭⠎⢃⡗⠄⡄⢀⠁⠀⠅⢀⢅⡀⠠⠀⢠⡀⡩⠷⢇⠀⡀⠄⡠⠤⠆⣀⡀⠄⠉⣠⠃⠴⠀⠈⢁⣿⡛⡯⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
17⠀⠀⠀⠀⠀⠀⠀⠘⡬⡿⣿⡏⡻⡯⠌⢁⢛⠠⠓⠐⠐⠐⠌⠃⠋⠂⡢⢰⣈⢏⣰⠂⠈⠀⠠⠒⠡⠌⠫⠭⠩⠢⡬⠆⠿⢷⢿⡽⡧⠉⠊⠀⠀⠀⠀⠀⠀⠀⠀
18⠀⠀⠀⠀⠀⠀⠀⠀⠺⣷⣺⣗⣿⡶⡎⡅⣣⢎⠠⡅⣢⡖⠴⠬⡈⠂⡨⢡⠾⣣⣢⠀⠀⡹⠄⡄⠄⡇⣰⡖⡊⠔⢹⣄⣿⣭⣵⣿⢷⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀
19⠀⠀⠀⠀⠀⠀⠀⠀⠩⣿⣿⣲⣿⣷⣟⣼⠟⣬⢉⡠⣪⢜⣂⣁⠥⠓⠚⡁⢶⣷⣠⠂⡄⡢⣀⡐⠧⢆⣒⡲⡳⡫⢟⡃⢪⡧⣟⡟⣯⠐⠀⠀⠀⠀⠀⠀⠀⠀⠀
20⠀⠀⠀⠀⠀⠀⠀⠀⢺⠟⢿⢟⢻⡗⡮⡿⣲⢷⣆⣏⣇⡧⣄⢖⠾⡷⣿⣤⢳⢷⣣⣦⡜⠗⣭⢂⠩⣹⢿⡲⢎⡧⣕⣖⣓⣽⡿⡖⡿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
21⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠉⠂⠂⠏⠿⢻⣥⡪⢽⣳⣳⣥⡶⣫⣍⢐⣥⣻⣾⡻⣅⢭⡴⢭⣿⠕⣧⡭⣞⣻⣣⣻⢿⠟⠛⠙⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
22⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠄⠋⠫⠯⣍⢻⣿⣿⣷⣕⣵⣹⣽⣿⣷⣇⡏⣿⡿⣍⡝⠵⠯⠁⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
23⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠐⠠⠁⠋⢣⠓⡍⣫⠹⣿⣿⣷⡿⠯⠺⠁⠁⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
24⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠋⢀⠋⢈⡿⠿⠁⠉⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
25```
26
27# plcbundle
28
29> A Transparent and Verifiable Way to Sync the AT Protocol's PLC Directory
30
31plcbundle 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.
32
33**Why plcbundle?**
34- 🔒 **Verifiable** - Cryptographic chain ensures data integrity
35- 🌐 **Distributed** - Host your own mirror, reduce central dependencies
36- 📦 **Efficient** - ~2.5x compression, optimized for storage and transfer
37- 🔍 **Transparent** - Open format, reproducible by anyone
38- 🛠️ **Ecosystem** - Multiple implementations, tools, and libraries
39
40## Current Implementations
41
42| Repository | Status | Features | Maintainer |
43|-----------|--------|----------|-------------|
44| **[plcbundle-rs](https://tangled.org/atscan.net/plcbundle-rs)** (Rust) | ✅ Active (unstable) | Library, CLI, Server, Sync | [@tree.fail](https://bsky.app/profile/tree.fail) |
45| [plcbundle-go](https://tangled.org/atscan.net/plcbundle-go) (Go) | *Deprecated* | Library, CLI, Server, Sync | [@tree.fail](https://bsky.app/profile/tree.fail) |
46| [plcbundle-bun](https://tangled.org/atscan.net/plcbundle-bun) (Bun/TypeScript) | *Experiment* | Library, CLI | [@tree.fail](https://bsky.app/profile/tree.fail) |
47| [plcbundle-ref](https://tangled.org/atscan.net/plcbundle-ref) (*various*) | - | Examples in TypeScript, Python, Ruby | [@tree.fail](https://bsky.app/profile/tree.fail) |
48
49## Quick Start
50
51### Installation
52
53```bash
54# Rust
55cargo install plcbundle
56
57# Docker
58docker pull atscan/plcbundle:latest
59```
60
61### Basic Usage
62
63```bash
64# Sync bundles from plc.directory
65plcbundle sync
66
67# Verify chain integrity
68plcbundle verify
69
70# Get information
71plcbundle info
72
73# Get DID Document
74plcbundle resolve tree.fail
75plcbundle audit did:plc:524tuhdhh3m7li5gycdn6boe
76
77# Run as HTTP mirror
78plcbundle server --sync --resolver --port 8080
79```
80
81[Full getting started guide →](./docs/getting-started.md)
82
83## How It Works
84
85```
86PLC Directory Bundle Chain Your Mirror
87 │ │ │
88 │ Operations ┌────▼────┐ │
89 │ 0-9,999 ────▶ │Bundle #0│ │
90 │ │Hash: abc│──┐ │
91 │ └─────────┘ │ │
92 │ Operations │ Cryptographically │
93 │ 10,000-19,999 ─────────────▶│ Linked │
94 │ ┌────▼────┐ │ │
95 │ │Bundle #1│◀─┘ │
96 │ │Prev: abc│────────── Sync ────────▶ │
97 │ │Hash: def│ │
98 │ └─────────┘ │
99 ▼ ▼ ▼
100```
101
102Each bundle is:
103- 📦 Exactly 10,000 operations
104- 🔗 Linked to previous bundle via hash
105- 🗜️ Compressed with zstd
106- ✅ Independently verifiable
107- 🔄 Reproducible from source
108
109[Technical details →](./spec/format.md)
110
111## Use Cases
112
113### 🪞 Host a Mirror
114Run your own PLC directory mirror to reduce dependency on central infrastructure and improve availability.
115
116### 🗄️ Archive & Backup
117Create verifiable backups with cryptographic proof of integrity. Perfect for compliance and long-term archival.
118
119### 🔬 Research & Analytics
120Analyze historical DID creation patterns, migrations, and network growth over time.
121
122### 📊 Monitoring & Detection
123Track operations, detect anomalies, identify spam patterns, monitor network health.
124
125## Specifications
126
127### Core Specifications
128- **[Bundle Format](./spec/format.md)** - Bundle structure, encoding, and compression (v1.0)
129- **[HTTP API](./spec/http-api.md)** - Server API for hosting mirrors (v1.0)
130
131### Future Specifications
132- WebSocket API - Real-time operation streaming
133- P2P Protocol - Peer-to-peer bundle distribution
134
135[All specifications →](./spec/)
136
137## Related Tools
138
139*Building something? [Add it here](https://tangled.org/atscan.net/plcbundle/pulls)*
140
141## Public Instances
142
143You can view all public instances on [plcbundle-watch.pages.dev](https://plcbundle-watch.pages.dev/)
144
145*Host a mirror? [Submit a PR](https://tangled.org/atscan.net/plcbundle/pulls) to add it here*
146
147## Security & Trust
148
149plcbundle provides cryptographic verification but requires external validation:
150
151**✅ Guarantees:**
152- Bundle integrity via SHA-256 hashing
153- Chain continuity via previous bundle links
154- Reproducibility from source operations
155
156**⚠️ You must verify:**
157- Operations against original plc.directory
158- Bundles from multiple independent sources
159- Published root and head hashes
160
161**Never trust a single source.** Always verify.
162
163[Full security model →](./docs/security.md)
164
165## Contributing
166
167We welcome contributions of all kinds:
168
169- 🔨 **Implementations** - Create clients in new languages ([guide](./docs/contributing.md))
170- 📖 **Documentation** - Improve guides, fix typos, add examples
171- 🐛 **Issues** - [Report bugs](https://tangled.org/atscan/plcbundle/issues) or suggest features
172- 🧪 **Test Vectors** - Help ensure implementation compatibility
173- 🪞 **Mirrors** - Host bundles and share your endpoint
174- 💬 **Discussion** - Share your ideas
175
176[Contributing guide →](./docs/contributing.md)
177
178## Community & Support
179
180- 🐛 [Issue Tracker](https://github.com/yourusername/plcbundle/issues) - Report bugs
181- 📰 [Announcement Article](https://leaflet.pub/feb982b4-64cb-4549-9d25-d7e68cecb11a) - Background and motivation
182
183## Resources
184
185- 📐 [AT Protocol Documentation](https://atproto.com/)
186- 🆔 [DID PLC Specification](https://web.plc.directory/)
187
188## License
189
190MIT License - See [LICENSE](./LICENSE) for details.
191
192Individual implementations may have different licenses - check their repositories.