OrbitDB Storacha Bridge

> OrbitDB database backup, restoration, replication, UCANs and more via Storacha/Filecoin


Table of Contents

- OrbitDB Storacha Bridge
- Table of Contents
- What we want to accomplish
- The Challenge of Distributed Data Persistence
- Architectural Considerations for Local-First Applications
- Use Cases for OrbitDB-Storacha-Bridge
- Architecture Notes
- What This Does
- Roadmap (Current version: 0.4.2, as of 21.01.2026)
- Installation
- Environment Setup
- Demo
- NodeJS Demo Scripts (full backup with Manifest, Identity and AccessController and entries blocks)
- Svelte Components
- How It Works
- Restore Mechanism
- Logging
- Testing
- Contributing
- License

What we want to accomplish

$3

In local-first, peer-to-peer applications built on OrbitDB, data naturally replicates across participating peers through libp2p network connections. Under ideal conditions, this distributed architecture provides inherent redundancy—if one peer loses data, they can resynchronize from other active peers in the network. This peer-to-peer replication model represents the current state of OrbitDB technology.

While relay nodes and pinning services (running Helia and OrbitDB instances) can provide additional decentralized persistence for database entries and IPFS-referenced content, the ecosystem still lacks comprehensive infrastructure for long-term archival of large-scale OrbitDB deployments.

$3

OrbitDB's data model differs fundamentally from traditional centralized databases. In local-first architectures, users typically host their own data locally and selectively replicate with specific peers based on collaboration requirements—not with the entire network. This selective replication is essential for scalability and user experience.

However, as OrbitDB instances grow (consider a blog database accumulating years of posts), replication times increase proportionally. At scale, databases require archival strategies and potential sharding to maintain performant synchronization and optimal user experience.

$3

This bridge addresses several critical scenarios:

1. Long-term Archival
Archive large OrbitDB instances to Storacha/Filecoin storage, enabling efficient cold storage for historical data while maintaining fast replication of active datasets.

2. Disaster Recovery
Provides recovery options when all active peers lose data simultaneously. Users can restore databases from Storacha using either their original identity or a new identity, ensuring business continuity beyond the peer-to-peer network's availability.

3. Network Resilience
Historically, various network environments (corporate networks, ISPs, regional restrictions) have blocked critical protocols including WebRTC and WebSocket/WebTransport. While libp2p's multi-transport architecture provides numerous fallback options, having an additional restoration pathway through IPFS/Storacha offers defense-in-depth for network-hostile environments. Users can restore databases directly from IPFS and maintain incremental backups after each database mutation.

4. Access Control & Delegation
The bridge supports UCAN (User Controlled Authorization Networks) authentication with planned delegation capabilities between OrbitDB instances. This enables fine-grained, time-bound access control for Storacha backup spaces, allowing users to securely share access with collaborators or recovery agents.

$3

Currently, Storacha backup and restore operations utilize Storacha's gateway infrastructure to interface with Filecoin's decentralized storage network. This hybrid approach balances accessibility with decentralization during the current phase of the Filecoin ecosystem's evolution.

What This Does

Backup and restore between OrbitDB databases and Storacha/Filecoin with full hash and identity preservation. Works in both Node.js and browser environments. See Storacha Integration Widget in Simple Todo Example

The project includes Svelte components for browser-based demos and integration (see SVELTE-COMPONENTS.md for detailed documentation).

Features:

- backup/restore between OrbitDB and Storacha in browsers and NodeJS via Storacha key and proof credential
- full backup per space
- timestamped backups (multiple backups per space - restore last backup by default)
- Storacha Svelte components for integration into Svelte projects
- UCAN authentication
- Backup/restore functionality with hash and identity preservation
- OrbitDB CAR file storage OrbitDB CustomStorage

Roadmap (Current version: 0.4.2, as of 21.01.2026)

- [ ] v0.4.3 (Jan 2026): Latest-backup pointer (single CID) to avoid listing via the Storacha SDK and restore from the IPFS network for initial OrbitDB syncs.
- [ ] After each backup, write a small pointer record (JSON) that stores the latest metadata CID, CAR CID, and last heads (block CID).
- [ ] Store that pointer in a user-controlled place (local storage, QR/share link, WebAuthN largetBlog extension or file download).
- [ ] v0.5.0 (Feb 2026): OrbitDB CustomStorage (StorachaStorage) (issue 23).
- [ ] v0.6.0 (Mar 2026): WebAuthN + varsig signing/verification (Ed25519 and P-256) for OrbitDB oplog. https://github.com/ChainAgnostic/varsig/blob/main/README.md
- [ ] v0.6.1 (Mar 2026): WebAuthN + SimpleEncryption example that uses WebAuthN+PRF key material for encrypted backups and restore.
- [ ] v0.7.0 (Apr 2026): WebAuthN + OrbitDB AccessController (store a UCAN instead of only a DID for admin/write access).
- [ ] Alice (authenticated via UCAN or Storacha credentials) can delegate/revoke access for Bob with custom/default capabilities (issue 16). See WebAuthN Upload Wall and the live demo.
- [ ] v0.7.1 (May 2026): Storacha Backup & Restore Svelte widget with WebAuthN-varsig UCAN signing/verification (Ed25519/P-256).
- [ ] v0.7.2 (May 2026): Storacha Backup & Restore React widget with WebAuthN-varsig UCAN signing/verification (Ed25519/P-256).
- [ ] v0.7.3 (May 2026): Storacha Backup & Restore React widget with WebAuthN-varsig UCAN delegation (Ed25519/P-256).
- [ ] v0.7.4 (May 2026): UI enhancement for the Storacha Backup & Restore widget (timestamped backup restore and management).
- [ ] v0.8.0 (Jun 2026): Upgrade to UCAN 1.0 support.
- [ ] v0.9.0 (Jul 2026): Social backup between devices with DKG (decentralized key generation).
- [ ] v0.10.0 (Aug 2027): WebAuthN + Roaming Credentials: Have a browser and a mobile with one Yubikey creating one and the same DID and replicating the same OrbitDB

Read more on Medium: Bridging OrbitDB with Storacha: Decentralized Database Backups

Installation

Install the package via npm. ``npm install orbitdb-storacha-bridge`

Environment Setup

Get Storacha credentials from storacha.network quickstart, install w3 for the console, get storacha key and proof then set up your environment variables (.env) for STORACHA_KEY and STORACHA_PROOF.

Demo

$3

- node examples/demo.js - Complete backup/restore cycle
- node examples/backup-demo.js - Backup demonstration only
- node examples/restore-demo.js - Restore demonstration only
- node examples/car-backup-demo.js - CAR-based timestamped backups (efficient multi-version backups)
- node examples/demo-different-identity.js - Different identities with access control enforcement
- node examples/demo-shared-identities.js - Shared identity backup/restore scenarios
- node examples/simple-todo-restore-demo.js - Simple todo database restore demonstration
- node examples/ucan-demo.js - Complete UCAN-based authentication backup/restore
- node examples/simple-ucan-auth.js - UCAN authentication with existing delegation token
- node examples/test-ucan-bridge.js - Test UCAN bridge integration
- node examples/test-ucan-list.js - Test UCAN file listing after upload
- node examples/clear-space.js - Clear all files from Storacha space (utility script)
- node examples/timestamped-backup-example.js - Timestamped backup implementation helper

$3

For browser-based integration, this project includes Svelte components for authentication, backup/restore, P2P replication, and WebAuthn biometric authentication. See SVELTE-COMPONENTS.md for complete documentation of all available components and demonstrations.

How It Works

1. Extract Blocks - Separates OrbitDB database into individual components (log entries, manifest, identities, access controls)
2. Upload to Storacha - Each block is uploaded separately to IPFS/Filecoin via Storacha
3. Block Discovery - Lists all files in Storacha space using Storacha SDK APIs
4. CID Bridging - Converts between Storacha CIDs (bafkre) and OrbitDB CIDs (zdpu)
5. Reconstruct Database - Reassembles blocks and opens database with original identity

Restore Mechanism

The restore process uses a ipfs-p2p-first approach with ipfs-http-gateway fallback for downloading backups for restore. File listing and metadata discovery are currently performed via the Storacha SDK (using Storacha gateway API). We are working on an IPNS-based mechanism to find the latest heads blocks and OrbitDB address directly from the IPFS network via IPNS, eliminating the need to list all files via the centralized Storacha gateway API.

Logging

The library uses @libp2p/logger for consistent logging across the libp2p ecosystem. Control logging with the DEBUG environment variable:

Node.js:
`bash


Enable all OrbitDB Storacha Bridge logs

DEBUG=libp2p:orbitdb-storacha:* node your-script.js

Enable specific components

DEBUG=libp2p:orbitdb-storacha:bridge node your-script.js

Enable all libp2p logs (includes this library + libp2p internals)

DEBUG=libp2p:* node your-script.js
`

Browser:
`javascript
// In browser console or before loading the application
localStorage.setItem('debug', 'libp2p:orbitdb-storacha:*')
// Then refresh the page
`

The logger supports printf-style formatting:
- %s - string
- %d - number
- %o - object
- %p - peer ID
- %b - base58btc encoded data
- %t - base32 encoded data

Testing

See test/README.md` for detailed test documentation, modes (in-memory vs production),
and how to run each suite.

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

License

MIT License