Welcome to the Hypermedia Protocol: a decentralized publishing and discussion network

    Documentation Test

    15 July 2025
    Gabo H Beaumont

    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

    14 July 2025
    Hypermedia
    Eric Vicenti

    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.

    14 July 2025
    Hypermedia
    Eric Vicenti

    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

    11 July 2025
    Eric Vicenti

    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

    10 July 2025
    Hypermedia
    Eric Vicenti

    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.

    10 July 2025
    Eric Vicenti

    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

    10 July 2025
    Hypermedia
    Eric Vicenti

    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

    10 July 2025
    Eric Vicenti

    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.

    10 July 2025
    Eric Vicenti

    Ref

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

    10 July 2025
    Eric Vicenti

    Change

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

    10 July 2025
    Eric Vicenti

    Signed Data Blob

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

    10 July 2025
    Eric Vicenti

    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.

    10 July 2025
    Hypermedia

    Contact

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

    10 July 2025
    Hypermedia

    Comment

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

    10 July 2025
    Hypermedia

    Resource

    The base mutable entity in the system

    10 July 2025
    Hypermedia

    Peer-to-Peer

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

    10 July 2025
    Eric Vicenti

    Content Addressability

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

    10 July 2025
    Eric Vicenti

    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

    3 June 2025
    Eric Vicenti

    Entity Introductions

    Accounts and Sites Comments Capabilities Contacts

    3 June 2025
    Eric Vicenti

    Concepts

    3 June 2025
    Eric Vicenti

    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)

    3 June 2025
    Eric Vicenti

    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

    14 March 2025
    Eric Vicenti

    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

    14 March 2025
    Eric Vicenti

    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

    14 March 2025
    Eric Vicenti

    Links

    How links work in the Hypermedia network New doc version

    20 January 2025
    Hypermedia
    Eric Vicenti

    Hypermedia URLS

    Hypermedia URLs Web URLs

    12 December 2024
    Hypermedia