# GUN

GUN is a decentralized graph database with a conflict resolution algorithm (CRDT) and synchronization protocol. It includes a library of tools for merging conflicting data and handling routing, security, and storage.

In GUN's graph store, entries are [javascript objects under UUID keys](https://gun.eco/docs/Porting-GUN). Objects can be data of any type, including files, JSON, or other documents. Data is stored in the browser by default, with backup "superpeers" to ensure persistence. Peers connect to other peers, and choose what data to synchronize and persist.

There is a public space, and a subset of that is the user space. In the public space are all graphs without a public key as their ID. In the user space, graphs are signed with the user's keys, and their IDs must include the user's public key.

### Identity

Gun's [User System](https://gun.eco/docs/Auth) creates a username and password. Usernames are global but not unique.

[Multi-device login](https://gun.eco/docs/Auth) is handled by encrypting a user's crytographic keypair, which is stored in the GUN graph. Keypairs are not derived from the password. PBKDF2 proof is derived from the password, and AES keys are derived from that to encrypt the keypair. GUN treats this method as "secure enough" for applications in which private keys do not control financial information. "Auth" is doing a GUN query for that account, subscribing to it, and then attempting to brute force decrypt the keys of all accounts that match that username. Once an account has been loaded once, it's cached on that device, loading from localstorage or the local harddrive.

GUN's SEA (Security, Encryption, Authorization) module provides the capability to directly create a [public/private keypair](https://gun.eco/docs/SEA) for a user, without a username and account.

### Network structure

GUN uses a gossip protocol along with a topic-based PubSub protocol to sync data between peers. GUN peers fall back to the [gossip-based protocol](https://gun.eco/docs/DAM) when the more optimized PubSub [routing](https://gun.eco/docs/Routing) protocol fails. Messages can be routed across different transport layers (websockets, WebRTC, multicast UDP etc).

Peers subscribe to graphs relevant to their application's logic, although the global GUN graph is accessible to all peers.

Planned future network upgrades include the addition of a DHT. A [tokenized incentivized mesh proposal](https://web.stanford.edu/~nadal/A-Decentralized-Data-Synchronization-Protocol.pdf) is also on the roadmap.

### Data Storage

Peers subscribe to the data they need and the network retrieves it from any peer (including browsers, where GUN stores data in localStorage). Running always-online peers, a "superpeer", is recommended for most applications to ensure availability of data when most browser-based peers may be offline. A superpeer is an IP addressable machine running node.js that persists data to disk. [RAD](https://gun.eco/docs/RAD), GUN's storage adaptor, saves data to disk.

GUN uses a CRDT (Conflict-free Replicated Data Type) to merge data. Conflicts are handled by a [conflict resolution algorithm](https://gun.eco/docs/Conflict-Resolution-with-Guns) that uses lexical sort. GUN is [strongly eventually consistent](https://pages.lip6.fr/Marc.Shapiro/slides/CRDTs%20Google%20Zurich-2011-09.pdf), meaning that peers will eventually converge upon the last updated value when nodes that are offline eventually receive updates.

GUN focuses on mutability by not using an append-only log, which implements updates, insertions, and deletion as a layer on top. [Deletion](https://stackoverflow.com/questions/37758618/how-to-delete-data-in-gun-db) in GUN works by overwriting bytes with `null`, or by de-referencing portions of a graph. A content-addressed graph space is used to implement immutable, append-only data.

### Privacy and Access Control

Access control is built into the [User system](https://gun.eco/docs/Auth) and can be combined with [SEA](https://gun.eco/docs/SEA), GUN's encryption utilities, for more advanced use cases.

Cryptographic keypairs are assigned to roles, groups, or data points. This information is either used to derive a shared ECDH secret to decrypt (read), or to load collaborative multi-writer edits (signed).

[Iris-lib](https://github.com/irislib/iris-lib) provides an API for end-to-end encrypted chat channels and private contact list management.

### Interoperablity

Plugins, such as backup storage on centralized databases or file systems, can be used to extend GUN.

### Scalability

Test relays (superpeers) on GUN can handle about 10k simultaneous connections: http://guntest.herokuapp.com/stats.html

### Metrics

- 10M ~ 30M monthly [downloads](https://www.jsdelivr.com/package/npm/gun)

### Monetization

The GUN protocol is developed by a [VC-funded company](https://era.eco/#step1), which funds the development of Iris as well. The business model is based on consulting and integrations. Future business models include a proposed paid service through a blockchain-based [tokenized bandwidth incentive network](https://web.stanford.edu/~nadal/A-Decentralized-Data-Synchronization-Protocol.pdf).

### Implementations

GUN is used for p2p chat/social apps, encrypted video conferencing, realtime GPS tracking, and AR/VR multiplayer games, among other applications.

- [Internet Archive](https://news.ycombinator.com/item?id=17685682) uses GUN for their [dWeb library](https://github.com/internetarchive/dweb-transports) metadata
- [HackerNoon](https://hackernoon.com/state-of-hacker-noon-2019-2020-8w1ls3axx) integrated GUN for annotations
- [Meething](https://meething.space/) is a Mozilla backed secure & decentralized video conferencing that uses GUN
- [Party](https://party.lol/) and [Maskbook](https://maskbook.com/), encrypted browser extensions, use GUN
- [Notabug](https://notabug.io/t/notabug/comments/59382d2a08b7d7073415b5b6ae29dfe617690d74/welcome-to-notabug), a decentralized Reddit clone, uses GUN
- [Unstoppable Domains](https://unstoppabledomains.com/chat) and [DTube](https://d.tube/) use GUN for messaging
- [Iris](https://irislib.github.io/), is a web-of-trust based social network built on GUN

### Links

- [Site](gun.eco)
- [3box comparison of p2p DBs](https://medium.com/3box/3box-research-comparing-distributed-databases-gun-orbitdb-and-scuttlebutt-2e3b5da34ef3)