The Radicle protocol, in contrast, extends Git's capabilities with a

decentralized identity system, novel gossip protocol, and integrated social

locates, serves, and replicates Git repositories -- including artifacts --

across a [peer-to-peer] network while maintaining data authenticity via

cryptographic signatures, so peers can directly exchange data without the need

## Nodes

Radicle is a [peer-to-peer] system, which means that there is no traditional

and are indistinguishable from users at the protocol level. Nodes, identified

by their [Node ID](#node-identifier-nid) (NID) -- an [Ed25519] public

key -- are responsible for seeding Git repositories, each identified by a unique

**seed node**, offering their infrastructure to the wider

Radicle network or to their community. Seed nodes significantly enhance the

network's capacity to provide continuous access to a broad range of

seed repositories from a group of trusted peers.

<aside> For more details on how to run a seed node, refer to the <a

</aside>

### Node Identifiers (NIDs)

href="https://www.rust-lang.org/">Rust</a>, a high-performance, memory-safe

language. </aside>

interface (CLI), which can be optionally supplemented with a web frontend.

Radicle is released under the open source MIT and Apache 2.0 licenses, to

encourage the development of diverse clients and applications. All client

Peer connections in Radicle are secured thanks to a [Noise protocol][noise]

handshake. Radicle uses the [Noise XK][noise-xk] pattern specifically, just

nodes to know the Node IDs of their peers before connecting to them, which

takes place through the exchange of peer information over the gossip protocol.

message types, each fulfilling a distinct role:

**Node Announcements** are used for broadcasting Node IDs and physical

| Node Announcement

| -----------------

**Inventory Announcements** are used for broadcasting repository inventories

| Inventory Announcement

| ----------------------

| **`inventory`** | `RepoID[]` | Repository inventory

**Reference Announcements** are used for broadcasting updates to

| Refs Announcement

| -----------------

<aside> <code>OID</code> stands for <em>Object ID</em> and represents the SHA-1

hashes used by Git to identify objects.</aside>

may be temporarily stored and replayed to nodes joining the network for the

first time, or after a long period of being offline.

verify the authenticity of messages before relaying them to peers.

<figure>

of the connection.

Radicle uses the [XK][noise-xk] handshake pattern, which requires the

`NodeAnnouncement` message, since the static key is simply the Node ID.

<aside> The Noise framework calls the node that is receiving an inbound

While gossip is used to exchange metadata, actual repository data is

transferred via replication using the [Git protocol][git-pack]. The process

begins with a node establishing a secure connection to one or more of the

interest.

negotiating which objects should be sent or skipped by the remote node. The

objects are then downloaded into the node's storage, making them accessible to

other nodes via the same process.

A node joining the network for the first time will not know any peers. Hence,

it's useful to pre-configure network clients with addresses of well-known nodes

an address book.

Radicle's reference implementation is pre-configured with two [bootstrap

policies, but user experience and identity are ultimately tied and mediated by

these nodes' administrators rather than by the users themselves.

>

> nodes operate under a common set of standards and protocols, allowing them to

> share data, resources, and functionalities across boundaries while

> maintaining autonomy. This model enables interoperability and collective

### Delegates

is an individual, group, or bot, identified by a [DID][did]. Delegates are

responsible for critical tasks such as merging patches, addressing issues, and

modifying repository permissions. A repository always begins with one delegate,

### Identity Document

Before a repository can be published on Radicle, it needs to be initialized

reference in Git, encapsulates key metadata such as the repository’s name,

description, and default branch. It also includes the DIDs of the

authorize changes to the repository's default branch.

<aside> The identity document is stored in Canonical JSON form. Canonical JSON

  }

}

```

### Private Repositories

Radicle supports **private repositories** where access is restricted to a

designated group of trusted peers. This is achieved by setting the `visibility`

attribute in the identity document. For example, the following snippet sets

access to the repository.

```json

This ensures only nodes in the privacy set can replicate and access the data,

maintaining confidentiality. While the data is not encrypted at rest, these

privacy, which renders them invisible and inaccessible to other nodes in the

Radicle network.

repositories.

### Repository Identifier (RID)

  <figcaption>Example Repository ID for the heartwood project.</figcaption>

</figure>

document, the document is able to change while the RID remains the same.

[urn]: https://datatracker.ietf.org/doc/html/rfc8141

simply Git repositories stored in a special location on disk. Peer data

is stored within the same repository using Git [namespaces][gns], where Node

IDs are used as the namespace. This allows storage to be managed through a

repository, as well as any other forks they have an interest in, all within the

same Git repository. These forks are then shared among users across the

network.

permitted to make changes to their respective forks.

### Working vs. Stored Copy

Storage is accessed directly by the node to report its inventory to other

nodes, and by the end user through either specialized tooling or the `git`

command line tool. Users are typically interacting with two repository copies:

push` and `git fetch`, using Radicle's [git-remote-helper][grh].

This workflow is akin to what most developers are used to, when synchronizing

  <figcaption>Synchronizing the working copy with the stored copy of a repository.</figcaption>

</figure>

### Storage Layout

Radicle's storage layout is designed to support multiple repositories and

stored under a common base directory, identified uniquely with its Repository

ID or RID. Instead of each of the repository's peers storing data in a separate

Git repository with a separate [object database][git-odb] (ODB), peer data is

root, or top-level directory under which all repositories are stored on a

user's device. For every repository, each peer associated with that repository

must have a separate, logical Git source tree -- which contains all the usual

same physical repository.

```

    ...

```

Though this storage tree is browsable by the user with standard file system

commands, it is not meant to be interacted with directly by users, for risk of

corrupting the data. Additionally, Git is free to pack the objects, which means

  references.</figcaption>

</figure>

## Trust through Self-Certification

Unlike centralized forges such as GitHub, where repositories are deemed

authentic based on their location (e.g. `https://github.com/bitcoin/bitcoin`),

in a decentralized network like Radicle, location is not enough. Instead, we

This is because peers in a decentralized network may be dishonest. Radicle's

approach hinges on the self-certifying nature of its repositories, anchored in

the repository [identity document](#identity-document).

of maintainers, and any one maintainer is allowed to update the branch.

In Radicle, lacking a central location where repositories are hosted, the

**threshold** defined in the repository's identity document. For example, if a

threshold of two out of three delegates is set, with the default branch set to

`master`, and two delegates have pushed the same commit to their `master`

Together, a repository's RID and its identity document create a cryptographic

proof that serves as the basis for verifying all repository states leading

up to its current state. For this reason, we say that Radicle repositories

inputs other than the repository itself.

For repositories to be self-certifying, delegates authenticate every change to

and cryptographically signed.

Radicle includes three predefined collaborative object types to support code

control to customize them or extend Radicle with entirely new COB types.

  requests, and support discussions, labeling and assigning.

  branch, and support reviews, versioning of changes and discussions.

<aside> The repository's identity document is entirely defined and managed

through an <em>id</em> COB. </aside>

It may be useful to think of Radicle's usage of Git commit histories as a

form of [conflict-free replicated data type][crdt] (CRDT). When the histories

each other in a non-destructive, idempotent way.

<aside> <strong>Idempotence</strong> is the property of certain operations in

</figure>

Then, to materialize the state that is displayed to the user, this new graph is

going up to the tips. This ordering happens to be [causally

consistent][causality], ensuring that changes that have observed other changes

orders in the face of concurrency, a merge function is also defined, the

simplest of which is to traverse the partially-ordered graph vertices sorted by

their commit hash. If a merge function cannot be defined, a COB may be

<aside> A <em>reduce</em> or <em>fold</em> operation is a way of getting a

single value by applying a function to a list of values. </aside>

In summary, this mechanism supports multiple users independently interacting

without coordination. Each COB records the initial version of an object and

tracks all subsequent modifications made across the network. Each modification

graph is compatible with Git's fetch protocol. To retrieve the current state of

an object, the system replays all the changes to the object in a deterministic

and causally-consistent order.

[rips]: https://app.radicle.xyz/nodes/seed.radicle.xyz/rad:z3trNYnLWS11cJWC6BbxDs5niGo82

[heartwood]: https://app.radicle.xyz/nodes/seed.radicle.xyz/rad:z3gqcJUoA1n9HaHKufZs5FCSGazv5

[did]: https://www.w3.org/TR/did-core/

[peer-to-peer]: https://en.wikipedia.org/wiki/Peer-to-peer

[forges]: https://en.wikipedia.org/wiki/Forge_(software)

[local-first]: https://www.inkandswitch.com/local-first/