Wildland documentation

# Forest discovery and addressing

A good mechanism, when it comes to users being able to reach or address other users' forests and get access to select containers, is of paramount importance for container sharing, which is to be understood as both giving read-only access, as well as read-write access to the user's data.

Wildland addressing has been designed with the following goals in mind:

  • Avoiding a Central Points of Control and Failure
  • Allowing for scalability to many forests
  • Introducing flexibility (e.g. allowing the addresses to reflect organizational or other semantic structures)
  • Providing human-readability of the addresses
  • Non-spoofability

# Wildland URLs

Wildland URLs provide a way to refer to remote forests or their subsets, such as directories or single files within the forest. Note that a single directory, that is visible in a mounted filesystem, might in fact by an union of more than one container.

A general form of a Wildland URL can be written as (tokens in square brackets are optional):

wildland:[/Bridge/Root@][/Bridge/1@][...][/Bridge/N@]/Path/To/Container@[/Resource]

It comprises 2 general sections:

  1. A bridge, or a chain of bridges, pointing to the target forest,
  2. A path to a final container or a file/directory within the target container.

The first Root Bridge is always assumed to be located within the so-called Root Directory Forest (RDF), which is a Wildland Forest, the forest manifest of which is assumed to be well-known by all clients (i.e. pre-configured with RDF's forest manifest).

# Alternative DNS Root Bridges

Alternatively, it is possible to specify a DNS name instead of a Root Bridge path:

wildland:[Forest DNS name:][/Bridge/1@][...][/Bridge/N@]/Path/To/Container@

In that case, the resolver should contact the DNS system and obtain a forest manifest from the DNS record (e.g. by reading the TXT record). We discuss the details of how a DNS record should be provisioned for Wildland resolver in a separate document.

This allows to bypass the use of RDF in Wildland URLs resolution.

Note that this form allows to skip any Forest Directory completely:

wildland:/Path/To/Container@

This would, however, expect the user to have their own DNS record (and also be able to host their forest manifest file on some URL-reachable server).

# Integration with other name systems

The resolver distinguishes between RDF bridge paths and DNS names by looking at the first character after the schema prefix (i.e. the wildland: string). If it is a slash /, then the string is assumed to mean a path to bridge within the RDF, otherwise it will be seen as a DNS name, the TXT record of which should be read in order to obtain the desired forest manifest.

We might consider integration with other DNS-like systems, the most prominent example being the Ethereum Name Service (ENS).

TODO: how to express DNS vs ENS distinction with the URL?

# Bridges to other forests

A bridge is a special kind of a container, which represents a gateway (or link) to another forest (referred to below to as a target forest), possibly owned by another user.

Bridge manifest contains the following information:

  1. The forestid of the target forest, which doubles as the hash of the target forest's master signing key,
  2. The address (object link or a traditional URL) of the target forest catalog (its integrity can be verified using the forest ID given above),
  3. The place in the source forest where it should be mounted.

Bridges are used for Wildland URLs' resolution (as discussed below). They can also be exposed in the mounted forest filesystem, allowing the user to manually navigate to remote forests.

# The @ separator

The ‘@’ operator can be thought of as an Inter-Forest Jumping Operator. When the client encounters this operator while parsing a WL address, it knows that it should interpret the resulting container on the left side of the operator as a new user-defining manifest (i.e. a bridge manifest), and then switch to this newly introduced user identity for the resolution of whatever follows the @-operator.

The use of a @-character to separate the directory part from the container part might seem superficial, yet the rationale for its use, we believe, comes from privacy. If we didn’t use the explicit marker of which part should be passed to which directory, it’s tempting to think we could just offload to the remote entity to give us a hint, by answering either: “yes, I can still resolve the path further, please send in subsequent path tokens for resolve”, or: “I have no more knowledge further down this path, please now contact the resultant directory”. This should work, yet, a malicious directory (a higher-level one) might be cheating it terms of supposedly having all the knowledge about all of our path fragments, only to trick us into giving in the full path of the resource that we want to access. This would be a privacy attack on addressing metadata. We believe that the use of explicit ‘@’ in Wildland addresses mitigates this problem.

Another use of the @ operator is to terminate the container path in a Wildland path. This suffix is required so that the path resolver knows when to stop resolving path as a container path and start looking for a resource within the storage of that particular container. Without this suffix it wouldn't be possible to differentiate whether wildland:/holidays/photos/uncle-bob.jpg means uncle-bob.jpg in a /holidays/photos container or uncle-bob.jpg inside photos directory in /holidays container.

# Why multi-chain addresses?

Isn't DNS bridge addressing good enough? Wildland Chained addresses still offer two advantages:

  1. They might be used with relaying on the DNS system altoughter, e.g. in case of censorship,
  2. They allow users to expose their forests without requiring them to register a DNS name (which costs money and takes mental effort). Instead, it's merely required to submit one's forest manifest to some forest directory.

# Forest Directories

A Forest Directory is a forest which contains bridges to other forests. The Forest owner is free to decide on the policy of publishing bridges to other user forests. The policy might limit the ability to submit forest manifests to the directory (e.g. only paying or otherwise verified users can do that) as well as the paths under which these bridges will be exposed to the visitors of the Directory Forest.

# The Root Forest Directory (RDF)

By convention, one Forest Directory is special and called the Root Forest Directory, and it is used as a starting point for URL resolution, as discussed above.

The manifest of the Root Directory Forest is expected to be part of each client's pre-configuration.

We expect such an RDF to be implemented using Ethereum Smart Contract data. This might indeed be feasible, since we expect that there would be not many 2nd level directories registered in the Root Directory (similarly to there not being many TLDs in the DNS system). More subjects should register their bridges in the 2nd- and further-level directories.

# Submitting manifests to the RDF forest

TODO

← Client software architecture →