# GunDB Explained: Features, SEA Crypto & a Modern P2P Alternative

## 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](https://genosdb.com/gundb-supply-chain-security).

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](https://genosdb.com/building-genosdb-p2p-database) 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

- [Documentation](https://gun.eco/docs)
- [Gun on GitHub](https://github.com/amark/gun)
- [Whitepaper](https://gun.eco/docs/Whitepaper.pdf)
- [Distributed Matters](https://gun.eco/docs/Distributed-Matters)

## 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**](https://genosdb.com/genosdb-cellular-mesh-p2p-scalability) 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](https://genosdb.com/popular-p2p-distributed-databases), or [explore GenosDB directly](https://genosdb.com).

## My Relationship with GunDB

This guide comes from years spent inside the GunDB ecosystem. **Esteban Fuster Pozzi ([@estebanrfp](https://github.com/estebanrfp))** built the [official GUN documentation platform](https://gun.eco/docs) — *"made with love for the Gun community"* — and contributed to the [GUN codebase](https://github.com/amark/gun) 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](https://github.com/estebanrfp/gdb)** — 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](https://github.com/estebanrfp))**.

📄 [Whitepaper](https://github.com/estebanrfp/gdb/blob/main/WHITEPAPER.md) | overview of GenosDB design and architecture

🛠 [Roadmap](https://github.com/estebanrfp/gdb/blob/main/ROADMAP.md) | planned features and future updates

💡 [Examples](https://github.com/estebanrfp/gdb/blob/main/docs/genosdb-examples.md) | code snippets and usage demos

📖 [Documentation](https://github.com/estebanrfp/gdb/blob/main/docs/index.md) | full reference guide

🔍 [API Reference](https://github.com/estebanrfp/gdb/blob/main/docs/genosdb-api-reference.md) | detailed API methods

📚 [Wiki](https://github.com/estebanrfp/gdb/wiki) | additional notes and guides

💬 [GitHub Discussions](https://github.com/estebanrfp/gdb/discussions) | community questions and feedback

🗂 [Repository](https://github.com/estebanrfp/gdb) | Minified production-ready files

📦 [Install via npm](https://www.npmjs.com/package/genosdb) | quick setup instructions

🌐 [Website](https://estebanrfp.com/) | [GitHub](https://github.com/estebanrfp) | [LinkedIn](https://www.linkedin.com/in/estebanrfp/)