_site/

.jekyll-cache/

_cache/

.DS_Store

node_modules/

vendor/

notes/

.vercel

source "https://rubygems.org"

gem "jekyll", "~> 4.2"

gem "webrick"

gem "rouge"

GEM

  remote: https://rubygems.org/

  specs:

    addressable (2.8.6)

      public_suffix (>= 2.0.2, < 6.0)

    colorator (1.1.0)

    concurrent-ruby (1.2.3)

    em-websocket (0.5.3)

      eventmachine (>= 0.12.9)

      http_parser.rb (~> 0)

    eventmachine (1.2.7)

    ffi (1.16.3)

    forwardable-extended (2.6.0)

    google-protobuf (3.25.2-x86_64-linux)

    http_parser.rb (0.8.0)

    i18n (1.14.1)

      concurrent-ruby (~> 1.0)

    jekyll (4.3.3)

      addressable (~> 2.4)

      colorator (~> 1.0)

      em-websocket (~> 0.5)

      i18n (~> 1.0)

      jekyll-sass-converter (>= 2.0, < 4.0)

      jekyll-watch (~> 2.0)

      kramdown (~> 2.3, >= 2.3.1)

      kramdown-parser-gfm (~> 1.0)

      liquid (~> 4.0)

      mercenary (>= 0.3.6, < 0.5)

      pathutil (~> 0.9)

      rouge (>= 3.0, < 5.0)

      safe_yaml (~> 1.0)

      terminal-table (>= 1.8, < 4.0)

      webrick (~> 1.7)

    jekyll-sass-converter (3.0.0)

      sass-embedded (~> 1.54)

    jekyll-watch (2.2.1)

      listen (~> 3.0)

    kramdown (2.4.0)

      rexml

    kramdown-parser-gfm (1.1.0)

      kramdown (~> 2.0)

    liquid (4.0.4)

    listen (3.8.0)

      rb-fsevent (~> 0.10, >= 0.10.3)

      rb-inotify (~> 0.9, >= 0.9.10)

    mercenary (0.4.0)

    pathutil (0.16.2)

      forwardable-extended (~> 2.6)

    public_suffix (5.0.4)

    rb-fsevent (0.11.2)

    rb-inotify (0.10.1)

      ffi (~> 1.0)

    rexml (3.2.6)

    rouge (4.2.0)

    safe_yaml (1.0.5)

    sass-embedded (1.69.5-x86_64-linux-gnu)

      google-protobuf (~> 3.23)

    terminal-table (3.0.2)

      unicode-display_width (>= 1.1.1, < 3)

    unicode-display_width (2.5.0)

    webrick (1.8.1)

PLATFORMS

  x86_64-linux-gnu

DEPENDENCIES

  jekyll (~> 4.2)

  rouge

  webrick

BUNDLED WITH

   2.5.4

default: _site

	jekyll build

serve:

	jekyll serve --port 3000

dependencies:

	gem install jekyll bundler aws-sdk-s3

svgs:

	scripts/cleanup-svgs.sh assets/images/*.svg

publish:

	vercel --prod

.PHONY: publish

url: "https://docs.radicle.xyz"

baseurl: "/"

title: "docs.radicle.xyz"

highlighter: rouge

markdown: kramdown

kramdown:

  syntax_highlighter: rouge

collections:

  guides:

    output: true

    permalink: /guides/:path/

---

title: Radicle Protocol Guide

subtitle: How Radicle works under the hood

layout: guide

---

Heartwood, the latest release of the [Radicle][] protocol establishes a

sovereign data network for code collaboration and publishing, built on top of

[Git][]. In Radicle, users maintain local copies of their interested

repositories and related social artifacts such as issues and patches. Instead

of depending on a centralized service like GitHub, each participant in Radicle

operates a node that is capable of running on a personal computer, and is

connected via a peer-to-peer network.

Nodes, identified by [public keys][pkc], host and synchronize Git repositories

across the network, using a novel gossip protocol for peer and repository

discovery, alongside Git's [protocol][git-v2] for data replication. In

combination, this allows nodes to locate, replicate, and verify any repository

published to the network, provided at least one other peer seeding the

repository is online. Since Radicle is built on Git, it can easily interoperate

with existing tools and workflows.

Radicle's architecture is [local-first][], ensuring continuous access to one's

repositories directly from their device, regardless of internet connectivity.

Repositories have unique identifiers and are self-certifying, meaning all

actions, from committing code to adding a comment to an issue, are performed

locally and [cryptographically signed][signing], allowing peers to verify

authenticity and data provenance once propagated to the network. This allows

trust to be established without reliance on a centralized authority.

Radicle is designed for extensibility, allowing for diverse use cases without

necessitating modifications at the protocol level. This guide delves into the

capabilities of Radicle’s initial release, which has a focus on code

collaboration and code publishing. Nonetheless, a range of other applications

is foreseen in the future and possible today, including knowledge sharing,

project coordination, and data set collaboration.

## Introduction

Git, the most widely-used distributed version control system, enables users to

maintain and modify personal copies of data repositories, commonly for source

code control. Its structure for direct user-to-user collaboration, while

feasible, is often cumbersome due to Git's primary focus on version control

rather than collaboration. As a result, users frequently opt for centralized

[forges][] like GitHub or GitLab, which offer enhanced interfaces and

collaborative tools on top of Git, such as project management and code review.

This dependency, however, can result in vendor lock-in since it places a

project's social artifacts (e.g. issues, comments, pull requests) out of user

control, potentially compromising data sovereignty and other user freedoms.

Traditional self-hosted options like [Gitea][] or [Forgejo][] provide more

sovereignty but often lead to fragmented collaboration environments, as users

must create separate profiles for each hosted instance. This simultaneously

limits a project's exposure to the wider open source community, a key advantage

of platforms like GitHub, which have grown significantly due to network

effects. This isolation can impact the visibility and collaborative potential

of projects that choose traditional self-hosted solutions.

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

decentralized identity system, novel gossip protocol, and integrated social

artifacts, forming a *self-hosted network for code collaboration*. Radicle

locates, serves, and replicates Git repositories across a [peer-to-peer][]

network while maintaining data authenticity via cryptographic signatures, so

peers can directly exchange data without the need for a trusted third party.

This enables communities to both self-host and share their repositories across

a distributed protocol, contributing to the emergence of a new sovereign

network for code collaboration and more.

## Nodes

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

client-server model. Peers on the Radicle network are referred to as *nodes*,

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

[Repository ID](#repository-identifier-rid) (RID). The seeding process involves

both hosting the repository data and synchronizing changes with other nodes.

Every Radicle user, irrespective of their role or activity, operates a node by

installing a [Radicle Node](#Radicle-Node) on their device. No specialized

equipment is necessary for operating a node as a typical end-user; nodes can

run on a personal computer without requiring an always-on server.

<aside> In the peer-to-peer model, nodes act as <em>both clients and

servers</em>. </aside>

<img src="#" class="placeholder" />

### Seeding Repositories

Users configure nodes with a *seeding policy* which specifies the list of

repositories they are interested in seeding, in addition to retention rules.

This means that nodes aren't just seeding random repositories, users have an

active role in deciding which repositories should be stored on their device.

The typical end-user may choose to only seed the repositories they are actively

collaborating on. However, more dedicated users may opt to run an always-on

**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

repositories. They can vary in their seeding policies, from *public seed nodes*

that openly seed all repositories to *community seed nodes* that selectively

seed repositories from a group of trusted peers.

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

href="https://docs.radicle.xyz/guides/seeder">Radicle Seeder's Guide</a>

</aside>

### Node Identifiers (NIDs)

<aside class="kicker"> DIDs are a new identifier standard established by the

W3C. </aside>

Radicle node identity is based on [public-key cryptography][pkc], which makes

it easy to verify the authenticity of messages within the network through

[digital signatures][signing]. This also allows for consistent identification

even as a user's physical address varies. When setting up a node, users

generate their unique key pair, an [Ed25519][] public and private key, the

public part of which is encoded and shared as a [Decentralized Identifier][did]

(DID). Creating a node identity requires no permission or coordination: the key

pair can be created while offline without providing an email address or any

personal identifying information.

<aside> DIDs enable verifiable, self-sovereign digital identities that are

fully under the control of the DID subject, independent of any centralized

registry, identity provider, or certificate authority. </aside>

<figure>

  <pre class="center">did:key:<span class="highlight">z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK</span></pre>

  <figcaption>Example Node ID encoded as a DID using the <a

  href="https://w3c-ccg.github.io/did-method-key/"><code>did:key</code>

  method</a>.</figcaption>

</figure>

It is important to safeguard one's private key, as if it is either lost or

compromised, one will have to generate a new node identity. A changeable,

non-unique **alias** can optionally be associated to each node, for easier

human identification across the network.

<aside> In the Radicle protocol, the terms "Node ID", "Peer ID", and "Public

Key" all refer to the same thing and can be used interchangeably. </aside>

### Running a Node

To run a node and connect to the network, users install a Radicle *client*.

Client software is lightweight and suitable for use on both end-user devices

and seed nodes. The reference implementation can be found in the Radicle

[heartwood][] repository, and is actively maintained by a small team of

engineers.

<aside> Radicle's reference implementation is written in <a

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

language. </aside>

The Radicle *stack* is comprised of both the network client and a command line

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

software adheres to the Radicle protocol specification, as outlined in the

[Radicle Improvement Proposals][rips] (RIPs) repository, ensuring consistent

functionality across implementations.

<aside> For a guided install of the Radicle stack, check out the <a

href="#">user guide</a>. </aside>

## Peer-to-peer Protocol

Radicle adopts a local-first, peer-to-peer (P2P) architecture, which draws

inspiration from Secure Scuttlebutt (SSB) and Bitcoin's [Lightning

Network][ln].

Nodes on the Radicle network subscribe to repository data they are interested

in, and peers announce updates that in turn trigger fetches for the underlying

content. Just like SSB and Lightning, updates are [gossiped][gossip] on the

network until they reach all interested peers.

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

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

like the Lightning Network with the Node ID as the *static key*. This requires

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.

Unlike SSB's focus on social networking via append-only logs, Radicle focuses

on code collaboration by incorporating Git's [object model][git-odb] and

[transfer protocol][git-pack] into a peer-to-peer context. This architecture

not only leverages Git's proven efficiency and reliability but also gives users

complete autonomy over their social artifacts. Radicle's peer-to-peer

architecture, in contrast to federated systems, ensures no centralized points

of failure, allowing the network to persist as long as users operate nodes.

<figure class="diagram">

  <object type="image/svg+xml" data="/assets/images/p2p-network.svg"></object>

  <figcaption>A set of connected peers forming a gossip network.</figcaption>

</figure>

### Gossip Protocol

The Radicle networking layer is designed as a gossip protocol, where messages

are sent relayed between peers to build routing tables that aid in repository

discovery and replication. The core functionality is achieved with three

message types, each fulfulling a distinct role:

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

   addresses on which a node is publicly reachable, to facilitate peer

   discovery.

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

   and constructing the routing table which maps out what repositories are

   hosted where.

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

   repositories, relayed only to nodes interested in the relevant repository.

To prevent endless propagation, nodes drop any message already encountered.

However, for the sake of broadcasting messages to new nodes, gossip messages

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

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

> **Tip**: Refer to [RIP-1][rip-1] to learn more details about Radicle's

> networking protocol.

Each announcement includes the originating *Node ID* along with a

*cryptographic signature* and *timestamp*, allowing network participants to

verify the authenticity of messages before relaying them to peers.

<figure>

  <img src="#" class="placeholder" />

  <figcaption>The three gossip message types.</figcaption>

</figure>

### Transport Encryption & Privacy

Connections between peers in the Radicle network are encrypted using the Noise

protocol. This begins with two peers performing a [Diffie-Hellman][ecdh] key

exchange to agree on a shared session key that is used for the duration

of the connection.

<figure>

  <img src="#" class="placeholder" />

  <figcaption>Noise XK handshake example.</figcaption>

</figure>

After the handshake phase is completed, all data exchanged between peers is

fully encrypted and benefits from strong [forward secrecy][fs], ensuring

secure and private communications across the network.

> **Tip**: Radicle also supports [Tor][] addresses. Users can leverage Tor to

> hide their IP address from peers, and connect to `.onion` addresses on the

> Tor network.

### Replication via Git

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

repository's seeds, upon receiving a *reference* or *inventory* announcement of

interest.

Once connected, the node initiates a Git *fetch* protocol, which involves

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.

Since Radicle uses a [framing][] protocol for all its sessions, the fetch

protocol is able to take place over the same physical connection between nodes

as the gossip protocol. This allows for a more efficient use of resources

and avoids certain problems with [NATs][nat]. Although Git's protocols are

typically connection-based, Radicle's design allows for multiple concurrent

Git fetches to take place over a single connection.

<aside> The idea of re-using a network connection for multiple concurrent

protocols is called <a

href="https://en.wikipedia.org/wiki/Multiplexing">multiplexing</a>. </aside>

<figure class="diagram">

  <object type="image/svg+xml" data="/assets/images/multiplexing.svg"></object>

  <figcaption>Connection multiplexing in Radicle.</figcaption>

</figure>

### Bootstrap Nodes

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

that can be used to bootstrap the peer discovery process and build an address

book.

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

nodes][bootstrap] that are connected to if the address book is empty:

[seed.radicle.garden][] and [seed.radicle.xyz][]. These are nodes run by the

Radicle team and have large address books that are shared with connecting

peers.

In the bootstrapping process, nodes connect to an initial set of bootrap nodes

and once they establish a connection, use the regular peer discovery mechanism

to find more peers.

<figure>

  <img src="#" class="placeholder" />

  <figcaption>Bootstrapping process.</figcaption>

</figure>

[bootstrap]: https://en.wikipedia.org/wiki/Bootstrapping_node

### Federation vs. Peer-to-peer

Federation allows for a degree of sovereignty, as each node can set its content

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

these nodes' administrators rather than by the users themselves.

> **federation** /ˌfɛdəˈreɪʃn/ *n.*

>

> *(Computing)* A system architecture where multiple independent servers or

> 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

> services among diverse systems without fully centralizing control, thereby

> enhancing privacy, scalability, and resilience. Each node in a federated

> network can set its policies, manage its users, and control its data.

<aside> Examples of federated systems include <a href="https://atproto.com">AT

Protocol</a>, <a href="https://joinmastodon.org/">Mastodon</a> and plain old

E-mail. </aside>

Although federated models promote a level of decentralization, they face unique

challenges, such as when node operators decide to block other nodes, taking

that choice away from its users and restricting the free flow of information.

Federated systems also face challenges related to incentives; specifically,

when the operational costs of maintaining a node exceed the perceived benefits,

node operators are often compelled to shut down. This can disrupt access for

users, undermining the platform's reliability and the continuity of service.

While Radicle seed nodes face similar challenges, this has little bearing on

the end user: seed nodes are interchangeable and offer an undifferentiated

service; they are not tied to a user's identity or access to the network.

<figure class="diagram">

  <object type="image/svg+xml" data="/assets/images/federation-vs-p2p.svg"></object>

  <figcaption>Federation (left) vs. peer-to-peer (right).</figcaption>

</figure>

## Repositories

**Repositories** are central to the Radicle network, serving as the primary

data abstraction and object shared between peers. A repository in Radicle is

fundamentally a Git repository, supplemented with a unique repository

identifier (RID) and metadata essential for validating the authenticity of its

contents.

Radicle repositories, which can be either public or private, can accommodate

diverse content including source code, documentation, and arbitrary data sets.

All repositories are initialized with an [identity

document](#identity-document) from which a unique Repository ID (RID) is

derived.

The identity document is where repository permissions and ownership are defined,

as well as identifying metadata such as name and description.

### Delegates

Repositories are managed and owned by what are called *delegates*. A delegate

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,

its creator, and can eventually grow to multiple delegates.

### Identity Document

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

with an *identity document*. This JSON document, stored under the `refs/rad/id`

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

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

repository's delegates and the *threshold* of delegate signatures required to

authorize changes to the repository's default branch.

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

form standardizes JSON encoding to ensure identical byte representation for the

same data structures, making it particularly useful for cryptographic

operations like hashing. </aside>

Here's an example of the identity document for the [heartwood][] repository:

```json

{

  "delegates": ["did:key:z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi"],

  "threshold": 1,

  "payload": {

    "xyz.radicle.project": {

      "name": "heartwood",

      "description": "Radicle Heartwood Protocol & Stack ❤️🪵",

      "defaultBranch": "master"

    }

  }

}

```

### 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

the visibility to *private*, while also allowing a specific peer to have

access to the repository.

```json

{

  ...

  "visibility": {

    "type": "private",

    "allow": ["did:key:z6Mkt67GdsW7715MEfRuP4pSZxJRJh6kj6Y48WRqVv4N1tRk"]

  }

}

```

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

repositories rely on selective replication through the *allow list* for

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

Radicle network.

Note that repository delegates *always* have access to their private

repositories.

### Repository Identifier (RID)

To ensure uniqueness and easy identification of repositories, a stable and

globally unique identifier, known as the Repository Identifier (RID), is

assigned to each repository. The RID is deterministically derived from the

initial version of the repository's identity document. This process involves

using Git’s `hash-object` function to produce a 160-bit SHA-1 digest of the

document. This is then encoded using [multibase][mb] encoding with the

`base-58-btc` alphabet, and prefixed with `rad:`, making it a valid [URN][urn]:

<figure>

  <pre class="center">rad:<span class="highlight">z3gqcJUoA1n9HaHKufZs5FCSGazv5</span></pre>

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

</figure>

Since the RID is derived from the *initial* verison of the repository's identity

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

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

[mb]: https://w3c-ccg.github.io/multibase/

> **Tip**: Refer to [RIP-2][rip-2] for more details about how repository

> identity works in the Radicle protocol.

<!-- TODO: Add info about self-certifying updates -->

## Local-First Storage

Storage is designed in such a way that it's easy to transfer data between peers

over the network using an unmodified Git protocol. Radicle repositories are

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

partitioned approach where each user maintains their own *local fork* of 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.

Each repository fork has a *single owner and writer*, and users are only

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:

the *working copy*, and a remote "stored" copy that is interacted with via `git

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

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

changes between their working copy, and the `origin` remote, which is typically

a repository on a hosted Git forge.

Changes to the stored copy are automatically propagated to the network when the

user is connected to the internet, but can also be made while offline. This

local-first design not only enhances the user experience by making offline work

frictionless, but also eliminates the need for centralized servers.

<figure class="diagram">

  <object type="image/svg+xml" data="/assets/images/working-vs-stored.svg"></object>

  <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

multiple peers per repository. Each repository is a *bare* Git repository,

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

stored within the same Git repository using Git [namespaces][gns].

<aside> A <em>bare</em> Git repository is a repository stripped of its working

directory, containing only the version history (the contents of the

<code>.git</code> directory). It's used primarily as a remote repository that

developers can push to and pull from, but cannot directly edit files or commit

changes in. </aside>

For each peer, including the local peer, their unique Node ID (NID) is used as

the namespace. Thus, each peer has its own namespaced references (eg.

`refs/heads`, and `refs/tags`), while sharing the underlying objects (i.e.

commits and blobs) with other namespaces via a shared object database. This

design ensures only one copy of each object is stored across all repository

forks.

Since the underlying storage uses Git, the storage layout below is represented

as a file tree on the file-system, with `<storage>` representing the storage

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

reference categories. This *logical repository* is also known as the repository

*fork* or *view*, and allows nodes to maintain local data for all peers in the

same physical repository.

```

<storage>                     # Storage root containing all repositories

├─ <rid>                      # Storage for first repository

│  └─ refs                    # All Git references locally stored

│     └─ namespaces           # All peer source trees or "forks"

│        ├─ <nid>             # First node's source tree

│        │  └─ refs           # First node's Git references

│        │     ├─ heads       # First node's branches

│        │     │   └─ master  # First node's master branch

│        │     └─ tags        # First node's tags

│        │

│        └─ <nid>             # Second node's source tree

│           ├─ refs           # Second node's references

│           └─ ...

├─ <rid>                      # Storage for second repository

│   ...

└─ <rid>                      # etc.

    ...

```

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

they may not always appear as individual files.

> **Tip**: Refer to [RIP-3][rip-3] to learn more about storage in the Radicle

> protocol.

### Git URL Scheme

The Radicle protocol uses its own URL scheme to point to specific repository

forks in the network. This allows the Git `fetch` and `push` commands to

operate on the correct namespace when fetching or pushing code.

<figure>

  <pre class="center">rad://<span class="highlight">z42hL2jL4XNk6K8oHQaSWfMgCL7ji</span>/<span class="highlight-secondary">z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi</span></pre>

  <figcaption> Example URL for repository <code>z42hL2jL4XNk6K8oHQaSWfMgCL7ji</code> and

  peer <code>z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi</code>. </figcaption>

</figure>

The Radicle [remote helper][grh] is what allows Git to interpret URLs with the

`rad://` scheme. By using this scheme, the user instructs Git to

invoke the `git-remote-rad` executable during `git push` or `git fetch`, which

allows the user to interact with the network through the storage layer.

For example, the above URL would map a push to the `master` branch to the following

path under the local storage root:

<pre>

/<span class="highlight">z42hL2jL4XNk6K8oHQaSWfMgCL7ji</span>/refs/namespaces/<span class="highlight-secondary">z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi</span>/refs/heads/master

</pre>

If a Node ID is not specified in the URL, Git will interact with the

repository's [canonical references](#Canonical-Repository-Version), also know

as the authoritative repository state. This is the state agreed on by the

repository [delegates](#delegates).

<figure>

  <pre class="center">rad://<span class="highlight">z42hL2jL4XNk6K8oHQaSWfMgCL7ji</span></pre>

  <figcaption> Example URL for repository

  <code>z42hL2jL4XNk6K8oHQaSWfMgCL7ji</code>'s canonical

  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

need a way to automatically verify the data we get from *any given location*.

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).

### Canonical Branches

When repositories are hosted in a known, trusted location, updating the

repository's canonical branch (eg. `master`) is simply a matter of pushing

to that repository's branch. Permission to push is granted to a small set

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

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

canonical branch is established *dynamically* based on the signature

**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`

branches, that commit is recognized as the authoritative, canonical state of

the repository.

> **Note**: Currently, only the branch specified under the `defaultBranch`

> attribute of the identity document is set automatically based on a signature

> threshold. In the future, additional branches may be supported.

### Self-certifying Repositories

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

are *self-certifying*: the process of verification doesn't require any

inputs other than the repository itself.

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

the repository data and metadata via cryptographic signatures. This includes

all Git references published to the network.

<!-- TODO: Copy section from RIP-2 -->

#### Signed Refs

To enable the verification of Git references beyond commits to the source code,

Radicle automatically signs the entirety of a node's references everytime they

change. This signature is then placed in a Git blob under a special branch

referenced under `refs/rad/sigrefs`, along with the references that were signed.

<figure>

  <pre>9767b485c2aad1e23097d2b5165287ba84cfa452 refs/heads/master

f3eaa7454e3a4714885905ae99f616fc7895b5fa refs/cobs/xyz.radicle.patch/fe31d5b6049583a42c21a543545d182b893aa4a0

0590b78ee42b39087983e4de04164065e5aa11bc refs/cobs/xyz.radicle.patch/ffbb812ad6e7fe1c5c610b1246ca5ca9d7d16027</pre>

  <figcaption>Example <code>refs</code> blob under a user's <code>refs/rad/sigrefs</code> branch.

  </figcaption>

</figure>

<aside> The signed references are in the same format as the <code>git

show-ref</code> command. </aside>

Signed refs are key to establishing a repository's canonical state and are

updated whenever there are changes to a repository.

Given an RID and a Radicle repository clone, anyone can retrieve the initial

identity document and authenticate all subsequent repository updates without a

trusted third party. This verification model draws inspiration from [The Update

Framework][tuf] (TUF), a framework designed to secure software update systems.

## Collaborative Objects

In the Radicle protocol, Collaborative Objects (COBs) play an important role in

supplementing Git with social artifacts such as issues, code reviews and

discussions, which are not inherently supported by Git. Typically, these

artifacts are only found on centralized platforms like GitHub or GitLab, or

their self-hosted counterparts.

In Radicle, COBs allow for social artifacts to be stored directly inside

repository, and replicated between peers. This means that social artifacts

inherit the same properties as source code: they are local-first, user-owned,

and cryptographically signed.

Radicle includes three predefined collaborative object types to support code

collaboration: *Issues*, *Patches*, and *Identities*, but users have full

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

* **Issues** (`xyz.radicle.issue`) are used for tracking bugs or feature

  requests, and support discussions, labeling and assigning.

* **Patches** (`xyz.radicle.patch`) are used to propose changes to a

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

* **Identities** (`xyz.radicle.id`) are used to represent identity documents.

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

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

COBs are identified by a unique type name in [reverse domain name

notation][reverse-dns] and a unique Object ID.

### Concurrency & Consistency

In a system with no central server, operation concurrency is the norm. If

two users comment on an issue at the same time, those comments will reach

peers in the network at different times and in different orders. To maintain

a good user experience, it's important that these factors don't determine

the issue's final state. All users must eventually converge to the same exact

state and see the same thing.

To achieve this, Radicle makes use of Git's native synchronization primitives,

and encodes COBs as a set of commits in a [directed acyclic graph][dag] (DAG).

Each issue, patch or identity document is represented by one such commit graph

that is disjoint from any other COB or source code branch.

This representation gives Radicle a few things for free:

1. Data integrity is guaranteed by Git.

2. Synchronization is handled by Git.

3. Causal dependencies can be modeled as commit parent-child relationships.

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

of two peers are synchronized, the commit graphs are simplied *unioned* with

each other in a non-destructive, idempotent way.

<figure class="diagram tall">

  <object type="image/svg+xml" data="/assets/images/cob-dag.svg"></object>

</figure>

<aside class="diagram">

  <p>

    Git DAG representing an Issue COB. Each box represents a

    commit object with a change to the COB.

  </p>

  <p>

    The different colors represent different

    commit authors and the arrows represent commit parents, or causal

    dependencies.

  </p>

</aside>

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

*reduced* in [topological order][topo], starting from the root of the graph and

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

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

are traversed in causal order. Since topological ordering may yield *partial*

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

configured to treat this as a *conflict* which can be bubbled up to the user.

<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

is stored as a separate Git *commit* object to ensure that the CRDT change

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.

### Extending COBs

Radicle's predefined COB types are stored under the `refs/cobs` hierarchy.

These are associated with unique namespaces, such as `xyz.radicle.issue` and

`xyz.radicle.patch`, to prevent naming collisions.

For example, if a user or organization were to define a new COB type under

their domain, it might look something like `com.acme.task`, for some

hypothetical "task" COB under the `acme.com` domain.

COBs are stored under the `refs/cobs` hierarchy, where Radicle's built-in COBs

co-exist with user-defined COBs. This extensibility allows for an unlimited set

of new collaboration primitives to be defined by users, without requiring

coordination with the broader network or user-base.

## Conclusion

The Radicle Heartwood protocol introduces a new approach to code collaboration

and hosting rooted in sovereignty. Built upon Git's well-established protocol,

Radicle can easily interoperate with existing systems and workflows that are

already familiar. Users have full control and ownership over their identity and

data. Repositories are self-certifying data structures, meaning updates are

cryptographically signed and can be verified by anyone, without needing a

trusted third party. Every user in Radicle is self-hosting while remaining

connected to a wider network. Radicle is highly extensible with its

Collaborative Objects that enable full control and customization over workflows

and datatypes, while also opening the possibility for Radicle to support a

wider range of functionalities, potentially extending far beyond code

collaboration.

<!-- References -->

[Gitea]: https://about.gitea.com/

[Forgejo]: https://forgejo.org/

[Radicle]: https://radicle.xyz/

[Git]: https://git-scm.com/

[gns]: https://git-scm.com/docs/gitnamespaces

[grh]: https://git-scm.com/docs/gitremote-helpers

[git-pack]: https://git-scm.com/docs/pack-protocol/en

[git-odb]: https://git-scm.com/book/en/v2/Git-Internals-Git-Objects

[git-v2]: https://git-scm.com/docs/protocol-v2

[Tor]: https://torproject.org/

[Ed25519]: https://ed25519.cr.yp.to/

[seed.radicle.garden]: https://app.radicle.xyz/nodes/seed.radicle.garden

[seed.radicle.xyz]: https://app.radicle.xyz/nodes/seed.radicle.xyz

[reverse-dns]: https://en.wikipedia.org/wiki/Reverse_domain_name_notation

[tuf]: https://theupdateframework.github.io/specification/latest/

[noise]: http://www.noiseprotocol.org/noise.html

[noise-xk]: https://noiseexplorer.com/patterns/XK/

[ssb]: https://en.wikipedia.org/wiki/Secure_Scuttlebutt

[ln]: https://en.wikipedia.org/wiki/Lightning_Network

[gossip]: https://en.wikipedia.org/wiki/Gossip_protocol

[causality]: https://en.wikipedia.org/wiki/Causal_consistency

[dag]: https://en.wikipedia.org/wiki/Directed_acyclic_graph

[topo]: https://en.wikipedia.org/wiki/Topological_sorting

[rip-1]: https://app.radicle.xyz/nodes/seed.radicle.xyz/rad:z3trNYnLWS11cJWC6BbxDs5niGo82/tree/0001-heartwood.md

[rip-2]: https://app.radicle.xyz/nodes/seed.radicle.xyz/rad:z3trNYnLWS11cJWC6BbxDs5niGo82/tree/0002-identity.md

[rip-3]: https://app.radicle.xyz/nodes/seed.radicle.xyz/rad:z3trNYnLWS11cJWC6BbxDs5niGo82/tree/0003-storage-layout.md

[nat]: https://en.wikipedia.org/wiki/Network_address_translation

[framing]: https://en.wikipedia.org/wiki/Frame_(networking)

[fs]: https://en.wikipedia.org/wiki/Forward_secrecy

[ecdh]: https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange

[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/

[seed]: https://docs.radicle.xyz/guides/seeder/

[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/

[signing]: https://en.wikipedia.org/wiki/Digital_signature

[pkc]: https://en.wikipedia.org/wiki/Public-key_cryptography

[crdt]: https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type

{% capture tocWorkspace %}

  {% comment %}

    Copyright (c) 2017 Vladimir "allejo" Jimenez

    Permission is hereby granted, free of charge, to any person

    obtaining a copy of this software and associated documentation

    files (the "Software"), to deal in the Software without

    restriction, including without limitation the rights to use,

    copy, modify, merge, publish, distribute, sublicense, and/or sell

    copies of the Software, and to permit persons to whom the

    Software is furnished to do so, subject to the following

    conditions:

    The above copyright notice and this permission notice shall be

    included in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES

    OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND

    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT

    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,

    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING

    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR

    OTHER DEALINGS IN THE SOFTWARE.

  {% endcomment %}

  {% comment %}

    Version 1.2.1

      https://github.com/allejo/jekyll-toc

    "...like all things liquid - where there's a will, and ~36 hours to spare, there's usually a/some way" ~jaybe

    Usage:

        {% include toc.html html=content sanitize=true class="inline_toc" id="my_toc" h_min=2 h_max=3 %}

    Parameters:

        * html         (string) - the HTML of compiled markdown generated by kramdown in Jekyll

    Optional Parameters:

        * sanitize      (bool)   : false  - when set to true, the headers will be stripped of any HTML in the TOC

        * class         (string) :   ''   - a CSS class assigned to the TOC

        * id            (string) :   ''   - an ID to assigned to the TOC

        * h_min         (int)    :   1    - the minimum TOC header level to use; any header lower than this value will be ignored

        * h_max         (int)    :   6    - the maximum TOC header level to use; any header greater than this value will be ignored

        * ordered       (bool)   : false  - when set to true, an ordered list will be outputted instead of an unordered list

        * item_class    (string) :   ''   - add custom class(es) for each list item; has support for '%level%' placeholder, which is the current heading level

        * submenu_class (string) :   ''   - add custom class(es) for each child group of headings; has support for '%level%' placeholder which is the current "submenu" heading level

        * base_url      (string) :   ''   - add a base url to the TOC links for when your TOC is on another page than the actual content

        * anchor_class  (string) :   ''   - add custom class(es) for each anchor element

    Output:

        An ordered or unordered list representing the table of contents of a markdown block. This snippet will only

        generate the table of contents and will NOT output the markdown given to it

  {% endcomment %}

  {% capture newline %}

  {% endcapture %}

  {% assign newline = newline | rstrip %} <!-- Remove the extra spacing but preserve the newline -->

  {% capture jekyll_toc %}{% endcapture %}

  {% assign orderedList = include.ordered | default: false %}

  {% assign baseURL = include.base_url | default: include.baseurl | default: '' %}

  {% assign minHeader = include.h_min | default: 1 %}

  {% assign maxHeader = include.h_max | default: 6 %}

  {% assign nodes = include.html | strip | split: '<h' %}

  {% assign firstHeader = true %}

  {% assign currLevel = 0 %}

  {% assign lastLevel = 0 %}

  {% capture listModifier %}{% if orderedList %}ol{% else %}ul{% endif %}{% endcapture %}

  {% for node in nodes %}

    {% if node == "" %}

      {% continue %}

    {% endif %}

    {% assign currLevel = node | replace: '"', '' | slice: 0, 1 | times: 1 %}

    {% if currLevel < minHeader or currLevel > maxHeader %}

      {% continue %}

    {% endif %}

    {% assign _workspace = node | split: '</h' %}

    {% assign _idWorkspace = _workspace[0] | split: 'id="' %}

    {% assign _idWorkspace = _idWorkspace[1] | split: '"' %}

    {% assign htmlID = _idWorkspace[0] %}

    {% assign _classWorkspace = _workspace[0] | split: 'class="' %}

    {% assign _classWorkspace = _classWorkspace[1] | split: '"' %}

    {% assign htmlClass = _classWorkspace[0] %}

    {% if htmlClass contains "no_toc" %}

      {% continue %}

    {% endif %}

    {% if firstHeader %}

      {% assign minHeader = currLevel %}

    {% endif %}

    {% capture _hAttrToStrip %}{{ _workspace[0] | split: '>' | first }}>{% endcapture %}

    {% assign header = _workspace[0] | replace: _hAttrToStrip, '' %}

    {% if include.item_class and include.item_class != blank %}

      {% capture listItemClass %} class="{{ include.item_class | replace: '%level%', currLevel | split: '.' | join: ' ' }}"{% endcapture %}

    {% endif %}

    {% if include.submenu_class and include.submenu_class != blank %}

      {% assign subMenuLevel = currLevel | minus: 1 %}

      {% capture subMenuClass %} class="{{ include.submenu_class | replace: '%level%', subMenuLevel | split: '.' | join: ' ' }}"{% endcapture %}

    {% endif %}

    {% capture anchorBody %}{% if include.sanitize %}{{ header | strip_html }}{% else %}{{ header }}{% endif %}{% endcapture %}

    {% if htmlID %}

      {% capture anchorAttributes %} href="{% if baseURL %}{{ baseURL }}{% endif %}#{{ htmlID }}"{% endcapture %}

      {% if include.anchor_class %}

        {% capture anchorAttributes %}{{ anchorAttributes }} class="{{ include.anchor_class | split: '.' | join: ' ' }}"{% endcapture %}

      {% endif %}

      {% capture listItem %}<a{{ anchorAttributes }}>{{ anchorBody }}</a>{% endcapture %}

    {% else %}

      {% capture listItem %}{{ anchorBody }}{% endcapture %}

    {% endif %}

    {% if currLevel > lastLevel %}

      {% capture jekyll_toc %}{{ jekyll_toc }}<{{ listModifier }}{{ subMenuClass }}>{% endcapture %}

    {% elsif currLevel < lastLevel %}

      {% assign repeatCount = lastLevel | minus: currLevel %}

      {% for i in (1..repeatCount) %}

        {% capture jekyll_toc %}{{ jekyll_toc }}</li></{{ listModifier }}>{% endcapture %}

      {% endfor %}

      {% capture jekyll_toc %}{{ jekyll_toc }}</li>{% endcapture %}

    {% else %}

      {% capture jekyll_toc %}{{ jekyll_toc }}</li>{% endcapture %}

    {% endif %}

    {% capture jekyll_toc %}{{ jekyll_toc }}<li{{ listItemClass }}>{{ listItem }}{% endcapture %}

    {% assign lastLevel = currLevel %}

    {% assign firstHeader = false %}

  {% endfor %}

  {% assign repeatCount = minHeader | minus: 1 %}

  {% assign repeatCount = lastLevel | minus: repeatCount %}

  {% for i in (1..repeatCount) %}

    {% capture jekyll_toc %}{{ jekyll_toc }}</li></{{ listModifier }}>{% endcapture %}

  {% endfor %}

  {% if jekyll_toc != '' %}

    {% assign rootAttributes = '' %}

    {% if include.class and include.class != blank %}

      {% capture rootAttributes %} class="{{ include.class | split: '.' | join: ' ' }}"{% endcapture %}

    {% endif %}

    {% if include.id and include.id != blank %}

      {% capture rootAttributes %}{{ rootAttributes }} id="{{ include.id }}"{% endcapture %}

    {% endif %}

    {% if rootAttributes %}

      {% assign nodes = jekyll_toc | split: '>' %}

      {% capture jekyll_toc %}<{{ listModifier }}{{ rootAttributes }}>{{ nodes | shift | join: '>' }}>{% endcapture %}

    {% endif %}

  {% endif %}

{% endcapture %}{% assign tocWorkspace = '' %}{{ jekyll_toc -}}

<!DOCTYPE html>

<html lang="{{ site.lang | default: "en-US" }}">

  <head>

    <title>

      {% if page.title %}

        {{ page.title }}

      {% else %}

        {{ site.title }}

      {% endif %}

    </title>

    <meta name="viewport" content="width=device-width, initial-scale=1">

    <meta charset="utf-8">

    <meta name="twitter:site" content="@radicle" />

    <meta name="twitter:creator" content="@radicle" />

    <link rel="shortcut icon" href="/assets/images/radicle.svg"/>

    <link rel="stylesheet" href="{{ "/assets/css/fonts.css" | relative_url }}">

    <link rel="stylesheet" href="{{ "/assets/css/main.css" | relative_url }}">

    <link rel="stylesheet" href="{{ "/assets/css/monokai.css" | relative_url }}">

  </head>

  <body>

    <header>

      <div class="title">

        <a href="{{ "/" | relative_url }}">

          <img src="{{ "/assets/images/radicle.svg" | relative_url }}" alt="" />

        </a>

      </div>

      <nav>

      </nav>

    </header>

    <main>

      <h1>{{ page.title }}</h1>

      <p class="subtitle">{{ page.subtitle }}</p>

      <hr />

      {% include toc.html html=content class="toc" item_class="toc-h%level%" %}

      <hr />

      {{ content }}

    </main>

    <footer>

      © The Radicle Team

    </footer>

  </body>

</html>

@font-face {

  font-family: "Inter";

  font-style: normal;

  font-weight: 400;

  font-display: swap;

  src: url("/assets/fonts/Inter-Regular.woff2");

}

@font-face {

  font-family: "Inter";

  font-weight: 500;

  font-display: swap;

  src: url("/assets/fonts/Inter-Medium.woff2");

}

@font-face {

  font-family: "Inter";

  font-weight: 600;

  font-display: swap;

  src: url("/assets/fonts/Inter-SemiBold.woff2");

}

@font-face {

  font-family: "Inter";

  font-weight: 700;

  font-display: swap;

  src: url("/assets/fonts/Inter-Bold.woff2");

}

@font-face {

  font-family: "JetBrains Mono";

  font-style: normal;

  font-weight: 400;

  font-display: swap;

  src: url("/assets/fonts/JetBrainsMono-Regular.woff2");

}

@font-face {

  font-family: "JetBrains Mono";

  font-style: normal;

  font-weight: 500;

  font-display: swap;

  src: url("/assets/fonts/JetBrainsMono-Medium.woff2");

}

@font-face {

  font-family: "JetBrains Mono";

  font-weight: 600;

  font-display: swap;

  src: url("/assets/fonts/JetBrainsMono-SemiBold.woff2");

}

@font-face {

  font-family: "JetBrains Mono";

  font-weight: 700;

  font-display: swap;

  src: url("/assets/fonts/JetBrainsMono-Bold.woff2");

}

:root {

  --font-family-default: "Inter", sans-serif;

  --font-family-code: "JetBrains Mono", monospace;

  --font-weight-regular: 400;

  --font-weight-medium: 500;

  --font-weight-semibold: 600;

  --font-weight-bold: 700;

  --font-size-tiny: 0.75rem; /* 12px */

  --font-size-small: 0.875rem; /* 14px */

  --font-size-regular: 1rem; /* 16px */

  --font-size-medium: 1.125rem; /* 18px */

  --font-size-large: 1.5rem; /* 24px */

  --font-size-x-large: 2rem; /* 32px */

  --font-size-xx-large: 3rem; /* 48px */

}

html {

  -ms-text-size-adjust: 100%;

  -webkit-font-smoothing: antialiased;

  -webkit-text-size-adjust: 100%;

  font-family: var(--font-family-default);

  font-feature-settings: "zero";

  font-size: 16px;

  font-weight: var(--font-weight-regular);

  line-height: 1.6;

}

@charset "utf-8";

:root {

  --color-bg-dark: #0a0d10;

  --color-bg-light: #f4f4f4;

  --color-fg-dim-0: #444;

  --color-fg-dim-1: #666;

  --color-fg-dim-2: #999;

  --color-fg-dim-3: #ccc;

  --color-fg-dim-4: #eee;

  --color-fg: #1a1a1a;

  --color-yellow: #ffff88;

  --color-fg-highlight: #5555bb;

  --color-fg-highlight-secondary: #229944;

  --color-border-highlight: #aaaaee;

  --color-bg-highlight: #eeeeff;

}

::selection {

  background-color: var(--color-yellow);

}

* {

  box-sizing: border-box;

}

html {

  font-family: var(--font-family-default);

  color: var(--color-fg);

  min-width: 1280px;

}

body {

  margin: 0;

}

header, main, footer {

  display: grid;

  align-items: start;

  grid-column-gap: 2rem;

  grid-template-columns:

    [screen-start] 1fr

    [page-start kicker-start left-start] 6rem 6rem

    [text-start kicker-end] 3rem 5rem 3rem 3rem

    [left-end right-start] 3rem 5rem 3rem 3rem

    [text-end gutter-start] 6rem 6rem

    [page-end gutter-end right-end] 1fr [screen-end];

}

main {

  align-items: first baseline;

  padding-bottom: 8rem;

}

header, footer {

  color: rgba(255, 255, 255, 0.8);

  font-weight: 300;

}

header {

  background-color: var(--color-bg-dark);

  height: 4rem;

  align-items: stretch;

}

footer {

  padding: 4rem 0;

}

nav {

  display: grid;

  grid-column: right;

  grid-auto-flow: column;

  grid-gap: 1.5rem;

  align-items: stretch;

  justify-self: end;

  text-transform: uppercase;

}

header a {

  display: flex;

  align-items: center;

}

main > *, footer > * {

  grid-column: text;

}

footer > *:last-child {

  margin-bottom: 0;

}

strong {

  font-weight: 600;

}

h1 {

  font-size: var(--font-size-xx-large);

  font-weight: var(--font-weight-semibold);

  margin: 4rem 0 0.5rem;

  line-height: 1.1;

}

h2 {

  font-size: var(--font-size-x-large);

  font-weight: var(--font-weight-semibold);

  margin: 3.75rem 0 1.5rem;

  padding-bottom: 1rem;

  border-bottom: 1px solid rgba(0, 0, 0, 0.1);

}

h3 {

  font-size: var(--font-size-large);

  font-weight: var(--font-weight-semibold);

  margin: 2rem 0 1.5rem;

}

h4 {

  font-size: var(--font-size-medium);

  font-weight: var(--font-weight-semibold);

  margin: 1.5rem 0 1rem;

}

h5 {

  font-size: var(--font-size-small);

  font-weight: var(--font-weight-semibold);

  margin: 1rem 0 0.25rem;

}

pre, code {

  font-family: var(--font-family-code);

}

pre {

  background-color: var(--color-bg-light);

  overflow-x: scroll;

  font-size: 0.875rem;

  padding: 1rem;

  margin: 0;

}

pre code {

  background: none;

  padding: 0;

}

pre.center {

  text-align: center;

}

p code, ul code, ol code, table code {

  font-size: 1rem;

  font-weight: 600;

}

p:last-child {

  margin-bottom: 0;

}

p + blockquote {

  margin-top: 0;

}

blockquote {

  color: var(--color-fg-dim-0);

  background: var(--color-bg-highlight);

  padding: 1rem;

  margin: 1rem 0;

  border-left: 2px solid var(--color-border-highlight);

}

.title {

  grid-column: left;

  display: grid;

  grid-auto-flow: column;

  align-items: stretch;

  justify-self: start;

}

.title img {

  width: 1.75rem;

  height: 1.75rem;

}

.toc + hr {

  margin-bottom: 4rem;

}

.first {

  margin-top: 60px;

}

.subtitle {

  font-size: 1.125rem;

  color: var(--color-fg-dim-1);

  margin: 0 0 4rem;

}

main figure, main img {

  margin: 1rem 0 2rem 0;

}

main img, main object {

  margin: 0;

  padding: 0;

  border: 0;

  outline: none;

}

main img.placeholder {

  width: 100%;

  height: 8rem;

  border: none !important;

  outline: none !important;

  background: var(--color-fg-dim-4) !important;

}

figure {

  width: 100%;

}

figure pre {

  margin: 0;

}

figure img, figure object {

  display: block;

  margin: 0 auto;

}

figure object + figcaption {

  margin-top: 1rem;

}

figure.diagram {

  grid-column-start: kicker-start;

  grid-column-end: gutter-end;

}

figure.diagram.tall {

  grid-column-start: text-start;

  grid-column-end: text-end;

}

figcaption {

  margin-top: 0.5rem;

  width: 100%;

  white-space: nowrap;

  overflow-x: hidden;

  text-align: center;

  text-overflow: ellipsis;

}

aside {

  grid-column: gutter;

}

aside.kicker {

  grid-column: kicker;

}

aside.diagram {

  margin-top: 1.5rem;

}

figcaption, aside {

  font-size: 0.75rem;

  line-height: 1.5;

  color: var(--color-fg-dim-1);

}

a {

  color: unset;

  text-decoration: unset;

  border-bottom: 1px solid var(--color-fg-dim-2);

}

a:hover {

  border-bottom-color: var(--color-fg-dim-1);

}

p, ol, ul, table, pre {

  margin: 0 0 1rem;

}

ol, ul {

  padding-left: 2rem;

}

li {

  padding-left: 0.5rem;

}

hr {

  grid-column: screen;

  width: 100%;

  border: none;

  border-top: 1px solid var(--color-fg-dim-4);

  margin: 0;

}

span.highlight {

  color: var(--color-fg-highlight);

}

span.highlight-secondary {

  color: var(--color-fg-highlight-secondary);

}

.toc {

  display: flex;

  flex-direction: column;

  flex-wrap: wrap;

  gap: 1rem;

  font-size: 0.75rem;

  margin: 2rem 0;

  padding: 0;

  height: 16rem;

}

.toc a {

  border-bottom-style: none;

}

.toc a:hover {

  border-bottom-style: solid;

}

.toc li, .toc ul {

  padding: 0;

  margin: 0;

  list-style-type: none;

}

.toc-h2 > a {

  font-weight: bold !important;

}

.toc-h2 > ul {

  margin-left: 0.5rem;

}

.toc-h3 > ul {

  margin-left: 1rem;

}

.toc-h3 > a, .toc-h4 > a, .tok-h5 > a {

  color: var(--color-fg-dim-1);

}

.highlight .nl { color: #555 }

.highlight .s2 { color: #555 }