of the protocol, in particular around the issues of privacy, censorship

resistance, peer misbehavior and DoS are left for future RIPs to expand on,

and won't be tackled here. Additionally, details and specifics on the wire

Overview

--------

peer-to-peer code hosting network:

*Alice publishes a repository on the network under a unique identifier, and

The above must hold true independent of the network topology and number of

manner.

This functionality can be broken down into three components:

Table of Contents

-----------------

* [Repository Identity](#repository-identity)

* [Repository Discovery](#repository-discovery)

    * [Topology](#topology)

    * [Routing](#routing)

is their mandate to decide what gets merged into a codebase.

We can then define a repository's identity as the set of all branches and tags

cryptographic signature over the repository's heads, tags, and other relevant

into a Radicle *project*. A project is simply a repository with an associated

*identity document*. In this document, the public keys of the repository's

current maintainers are stored. When a project is initialized from an existing

git repository for the first time, the user initializing becomes the de-facto

initial maintainer of the project, and his key is included in the new identity

maintainers, this is not a requirement. The only requirement is that they be

From this initial identity document we can then derive a unique, stable

It is by including the identity document in the *signed refs* that we establish

a relationship between the source code and the identity, and thus associate

the project identifier with the project source code. Note that this permits

identical source codes to have more than one identity. This is useful when

a user wishes to a *fork* a repository. In that case, a new project would

The storage, update and verification mechanism for the identity document

will be discussed in more detail in a future RIP. For the purposes of this

Routing information is usually stored in a *routing table* that is keyed

by the "target", in our case this is the project identifier:

For each project, we keep track of the nodes that are known to host this

identifiers, the table might look something like:

    …

To build the table, nodes gossip information about other nodes, namely *what*

operating the node. To be able to securely verify data authorship, we use

public key cryptography, with the public key being used as the node identifier.

In the case of nodes run by end-users; which is likely most nodes; the

The use of the same identity for both network communications and code signing

For nodes that are run as always-on "servers", the node identity may not be

used for signing code. These *seed* nodes only use their secret keys to

### Inventory Announcements

To build their routing table, nodes connecting to the network announce to their

on until they reach the majority of nodes on the network. Messages that have

already been seen are dropped, to prevent messages from propagating forever.

Gossip messages may be retained by nodes for a certain amount of time, so that

announcement* message has the following shape:

    InventoryAnnouncement = (

        NodeId,

        Timestamp,

        Signature,

    )

    RefsAnnouncement = (

        NodeId,

        Map<RefName, CommitId>,

        Signature,

    )

It contains the identifier of the node announcing the updated references, the

with their new commit hashes (`CommitId`) and a signature from the publishing

node (`NodeId`), over the refs and project identifier.

as they will usually be followed by a `git-fetch`.

We should also note that the `NodeId` in this case is not only the announcer

announcement, via her own node.

### Node Announcements

### Layout

Since nodes replicate Git data from other nodes, a partitioning scheme is

needed to separate references belonging to each node within each project.

#### Special References

that are written to a known location that doesn't vary between projects, and in

some cases is meant to be hidden from the user, and accessed only through

purpose-built tooling.

In a project with multiple delegates, for example, Alice, Bob and Eve, each

would have their *own* `master` branch which only they could write to, eg.:

So how does a contributor know which of those branches is the canonical one?

The protocol itself does not have a notion of canonicity. It is left up to