What Is GunDB?
GunDB (also known as Gun.js) is an open-source, real-time, distributed graph database written in JavaScript. Designed with an Offline-First approach and a keep-it-simple philosophy, it enables developers to build encrypted, community-run, peer-to-peer applications directly in the browser.
GunDB is used in production by Internet Archive and HackerNoon, and decentralized alternatives to platforms like Reddit, YouTube, and Wikipedia push terabytes of daily P2P traffic through the GUN network.
Key Features
- Real-time data synchronization
- Decentralized and distributed architecture with cryptographically secure data replication
- Scalability without relying on central servers or a continuous internet connection
Default servers act as backup and propagation checkpoints. Among available adapters, you can use Amazon S3, among others.
When a client-side app (browser) requests data, it merges responses with its local state using a CRDT, then caches the result.
This means:
- Next time, the data loads instantly — even offline.
- Data is replicated across all browsers that requested it.
- If your server goes down, data can still be recovered from other peers.
Losing important information becomes nearly impossible, since all copies would have to disappear simultaneously.
%[https://www.youtube.com/watch?v=b09pXG_wiVQ]
Core Concepts
- Real-Time synchronization across peers
- Distributed peer-to-peer architecture
- Decentralized — no single point of failure
- Offline-First with local state merge
- Graph Database with CRDT conflict resolution
- Radix Storage Engine (RAD)
- Standalone JavaScript — no external dependencies
- Small bundle size
SEA: Security, Encryption, and Authorization
GunDB's cryptographic layer is called SEA (Security, Encryption, Authorization). It provides:
- User authentication with public/private key pairs generated via the Web Crypto API
- Data signing — every write operation can be cryptographically signed by its author
- Data encryption — end-to-end encryption between users using ECDH key exchange
- Proof of work — optional computational proof for rate limiting
SEA is the foundation for building trusted, authenticated applications on top of GunDB. It uses browser-native cryptographic primitives (ECDSA for signing, ECDH for shared secrets, AES-GCM for encryption) rather than external libraries.
Known Limitations
GunDB has been in development for many years — a remarkable achievement for an open-source P2P project. But with that longevity comes accumulated technical debt, which is natural in any long-lived codebase. Some areas where this is most visible:
-
localStorage as default storage — The default persistence layer uses
localStorage, a synchronous API with a ~5MB cap that blocks the main thread. Modern alternatives like OPFS and IndexedDB offer significantly better performance. The RAD (Radix) adapter improves this but adds complexity. - HAM conflict resolution — GunDB uses a Hypothetical Amnesia Machine based on wall-clock timestamps. In distributed systems, clock drift between devices can lead to unpredictable conflict resolution. Newer approaches like Hybrid Logical Clocks (HLC) solve this without relying on synchronized clocks.
- Sync after extended disconnections — Prolonged offline periods can result in difficult-to-debug synchronization states, as there is no operation log to replay missed mutations. Without an oplog, there is no way to send only the delta of what changed.
- Relay infrastructure — While GunDB is decentralized, it relies on relay servers for peer discovery and data propagation. The default public relays can become bottlenecks under heavy load.
- Codebase complexity — Years of incremental development have resulted in a codebase that can be challenging for new contributors to navigate. This is a common pattern in projects that have evolved organically over a long period.
These are engineering trade-offs, not defects — every distributed system makes them. For projects that need different trade-offs (OPFS storage, hybrid delta sync, Cellular Mesh topology), next-generation alternatives like GenosDB were designed from scratch to address these specific challenges.
Plugins and Modules
- Users (SEA) — Security, Encryption, Authorization
- Storage adapters — file, LevelDB, RAD, and more
- Integration — Vue.js, React, and community adapters
Gun Recommended Links
Beyond GunDB: The Next Generation
Inspired by the GunDB ecosystem, GenosDB was created to push P2P databases further — with a modular plugin architecture, zero-trust security model with RBAC, Cellular Mesh networking for scalability, and OPFS-based persistent storage. If you're building decentralized applications and want a modern, actively maintained alternative, explore GenosDB.
This article is part of the official documentation of GenosDB (GDB).
GenosDB is a distributed, modular, peer-to-peer graph database built with a Zero-Trust Security Model, created by Esteban Fuster Pozzi (estebanrfp).
📄 Whitepaper | overview of GenosDB design and architecture
🛠 Roadmap | planned features and future updates
💡 Examples | code snippets and usage demos
📖 Documentation | full reference guide
🔍 API Reference | detailed API methods
📚 Wiki | additional notes and guides
💬 GitHub Discussions | community questions and feedback
🗂 Repository | Minified production-ready files
📦 Install via npm | quick setup instructions
Top comments (0)