SnapshotResource

A lightweight Resource, where the value is modified by replacing it entirely in a subsequent edit blob. Examples of Hypermedia SnapshotResources:

Resource

A Resource is a mutable object that is made from immutable data. Resource Types Address

ChangeResource

Documentation Test

Document

A Document is the primary data structure for knowledge in the Hypermedia ecosystem. Every Document is a , so it is modeled with Refs and Change blobs. The main building block for knowledge in the Hypermedia network is the Document. Each Document is identified by the Site Id + Path Content Metadata

Capability

The Capability is a signed blob used to delegate new permissions to read, write, or author as another identity. It is used to grant signing permissions to other devices or people. Each capability is a . Shape Chaining A capability might be granting permissions to another account, which might require a chain of capabilities.

Signed Data

At the heart of the Hypermedia protocol is the immutable data that is signed by authors and then distributed over  Aside from files/attachments, every  utilizes IPLD DAG-CBOR format to produce structured IPFS blocks identified by CID. Here we introduce you to the  and all of the data it can produce. Then you can reference the  which builds on this knowledge to offer many different RPCs for exchanging the signed data and the interpreted results. Resources Data Blob Definitions All Definitions

ChangeResource

This Resource is created by forming a graph of Changes and then using Refs to point to the latest heads of the change graph. Currently, the protocol's only ChangeResource is the  The Change blobs describe the operations to add/remove data from the resource. They depend on other Changes, and you can walk through all changes, applying operations, until you reach the current state of the Resource. Changes are the raw data with version history, and a Ref specifies the actual location. Unlike basic Resources, the ChagneResource allows easy branching, redirecting, and re-publishing. Branching Deleting Redirecting Generations

RPC

The Hypermedia Protocol relies on several RPC interfaces that may be used interchangeably depending on your use case. Important: the Hypermedia RPC protocols are highly unstable right now. Eventually we will stabilize these under a unified schema system. For now we are using a messy mix of gRPC and JSON REST APIs. These RPCs are not yet documented, as they are very prone to change.

Protocol

To approach learning the Hypermedia protocol, we can break the learning down into different areas: Signed Data Schema How to Receive and Distribute the Data Validating the Data

Account

The account is the base unit of identity in the Hypermedia network. Each account has a private key and a corresponding public key, known as the Account ID Account URLs

gRPC

For many of our RPC interfaces we utilize gRPC/Protobuf to provide a schema-first definition that can be consumed by many clients. For an overview of our existing gRPC endpoints, see the protocol definition section of our repository.

Ref

A Ref is a  that points to the latest state of a  according to the signer. Version Location Generation Tombstone/Deletes Redirect

Change

A Change is a  that specifies some set of operations against a  Deps Ops

Signed Data Blob

A Signed Data Blob is a  which has the "sig" and "signer" fields

Data Blob

A generic data blob is any IPFS file which is encoded using DAG-CBOR and has a "type" field that references this documentation.

Contact

A Contact is metadata that an Account uses to describe itself or another Account. Each Contact is a  .

Comment

A small unit of content that comes from a single author. Each Comment is a .

Resource

The base mutable entity in the system

Peer-to-Peer

We use a gRPC API over libp2p in order to enable communication between peers on the Hypermedia network

Content Addressability

We build upon IPFS to bring permanent content to the ecosystem. Why Content Addressability CIDs

Entities

An Entity is a mutable value in the network, which can be created, modified, forked, and deleted by creating chunks of signed data. The primary Entity in our network is the Document. We have two types of data which work together to define the state of an Entity/Document. A Change describes a modification to the state of the Entity, and a Ref is an assertion of the Entity's current state. Change Blob Ref Blob Snapshot Entities

Entity Introductions

Accounts and Sites Comments Capabilities Contacts

Concepts

Accounts and Keys

We use public-key cryptography to identify people, organizations, and devices. In each case, there is a private-public key pair. The private key is kept a secret and is used to securely sign data. The public key is known as the Account ID. The signatures are included in the content and this arrangement allows anyone to verify that the creator of this content, identified with the Account ID, must have had access to the private key. This allows you to stay anonymous but maintain a consistent identity over time. (Technically this is pseudo-anonymity- your Account ID is your pseudonym)

Data Model

The Hypermedia data model can be described in two shapes. The format of the signed data events that are permanently saved for validation, and the state snapshot, which represents the current state of the content. Immutable Signed Data Snapshot Data

Document

The main building block for knowledge in the Hypermedia network is the Document. Each Document is identified by the Site Id + Path Content Metadata How Documents Change

Site

Every private-public key pair has a Site in the Hypermedia Data Model. The site is identified by its public key, and as a URL it looks like this: hm://z6MkqcG5f6xTfivFPxkiwqoddJwGAuBw9qUpz7cuy55An7i6 A Site is a hierarchal collection of Documents, where each Doc is represented by a unique path name. By default, a Site can only be edited by creating Immutable Signed Data signed with the corresponding private key, but that can be expanded by granting Capabilities. Site Organization Each Document in the site has a Path, which is used to describe a hierarchy of pages. For example: Home Documents Site URL

Links

How links work in the Hypermedia network New doc version

Hypermedia URLS

Hypermedia URLs Web URLs