npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

orbitdb-storacha-bridge

v0.4.3

Published

OrbitDB database replication via Storacha/Filecoin

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

nandijinandiji

Keywords

orbitdbstorachafilecoinipfsbackupreplicationweb3decentralizeddatabasecidbridge

Readme

OrbitDB Storacha Bridge

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

License: MIT Node.js CI/CD Pipeline ESLint npm version

Table of Contents

What we want to accomplish

The Challenge of Distributed Data Persistence

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.

Architectural Considerations for Local-First Applications

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.

Use Cases for OrbitDB-Storacha-Bridge

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.

Architecture Notes

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).
  • [ ] 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

NodeJS Demo Scripts (full backup with Manifest, Identity and AccessController and entries blocks)

Svelte Components

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:

# 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:

// 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