GunDB Explained: Features, SEA Crypto & a Modern P2P Alternative
An honest guide to GunDB — how it works, SEA cryptography, the RAD engine and its known limitations — plus GenosDB, the modern P2P alternative built to fix them.
Full Stack Developer - dWEB R&D
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.
- Dependency surface — Gun's install-time dependency tree is large, and with upstream releases paused since 2020 it accumulates unpatched CVEs over time. We itemize the full report — and how a zero-dependency design answers it — in GunDB's supply chain in 2026.
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
GenosDB is a next-generation P2P graph database, engineered from the ground up to solve exactly the trade-offs above. It's real-time, serverless and offline-first — like GunDB — but built on a fundamentally stronger foundation: a modular plugin architecture, a Zero-Trust security model with RBAC, Cellular Mesh networking that avoids the O(n²) full-mesh bottleneck, Hybrid Logical Clocks instead of wall-clock conflict resolution, an operation log for true delta sync, and OPFS-based persistent storage. If you're weighing your options, see how it compares across other P2P and distributed databases, or explore GenosDB directly.
My Relationship with GunDB
This guide comes from years spent inside the GunDB ecosystem. Esteban Fuster Pozzi (@estebanrfp) built the official GUN documentation platform — "made with love for the Gun community" — and contributed to the GUN codebase itself, including its vanilla-JS real-time P2P video examples. GunDB's founder, Mark Nadal, is a friend and collaborator.
Pushing GunDB to its limits in real projects is exactly what led to GenosDB. It's not a fork or a reskin — it's engineered from the ground up to keep what makes browser P2P great while solving the trade-offs described above. As the docs put it, "GunDB and GenosDB belong to the same research effort in distributed systems" — GenosDB is where that research goes next.
One of my earliest exchanges with GUN's creator, Mark Nadal, is a story I still like to tell. I'd built an interactive 3D world with Babylon.js, synced over GUN, and we tried to share a 9 MB screen recording of it — but Discord, Telegram and the anonymous file hosts all choked on it. So instead of hunting for another host, I coded a drag-and-drop uploader and a real-time "video sinker" on the spot, and we streamed the clip directly computer-to-computer over GUN — faster than it had taken us to fail with the centralized services. Mark recorded the whole session and posted it on his own channel:
https://www.youtube.com/watch?v=VkxYHsgfT5U
⭐ Found this useful? Star GenosDB on GitHub — or spin it up in seconds: npm i 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
