Skip to content

Glossary of terms

This page contains a glossary of terms for Ceramic. Consider this list a work-in-progress; we will continue to update it until it's complete.

Core concepts

Streams

Streams are DAG-based data structures for storing continuous, mutable streams of content on IPFS and tracking state in a completely decentralized, peer-to-peer way. When syncing or loading a stream from the network, you will always get back the current state.

StreamID

A StreamID is an immutable identifier for a stream. StreamIDs enable continuous streams of data to be referenced by a persistent identifier instead of by constantly-changing IPFS CIDs.

StreamTypes

StreamTypes are functions used for processing updates to streams. StreamTypes handle everything from defining the data structure of the stream, to what can be stored in its commits, its state transitition function, authentication requirements, and conflict resolution strategy. Every stream must specify a StreamType; and StreamTypes run on Ceramic nodes. Ceramic comes pre-installed with various StreamTypes, or you can code your own.

Commits

Commits are individual IPFS records that make up a stream. Streams may contain one or more commits.

Genesis commit

A genesis commit is the first commit in a stream. Genesis commits may be signed by a public key, or unsigned.

Signed commit

Signed commits are commits that update the state of a stream. All signed commits need to be cryptographically signed by a public key.

Anchor commit

Anchor commits are commits that contain a blockchain timestamp, providing an immutable record of time and ordering to other commits in the stream, sometimes known as a proof-of-publication.

CommitID

A commitID is an immutable identifier for a specific commit in a stream.

State

State represents the state of a stream at various points in time. When a stream is loaded or queried from the network, the current state is returned.

Tip

A tip is the CID for the most recent commit(s) of a stream.

Conflict resolution strategy

A conflict resolution strategy is logic defined by a StreamType that describes how the protocol should handle conflicting updates to a stream that uses this StreamType.

Controllers

Controllers are entities allowed to perform updates to a stream, by creating new signed commits. A given stream may have one or more controllers.

Stream authentication

Authentication

Authentication allows a user to perform protected operations on a stream, such as creating genesis commits, signed commits, or decrypting data. Each StreamType implementation is able to specify its own authentication mechanism as long as the signatures can be resolved/validated by Ceramic, but most StreamTypes use DIDs.

DIDs

DIDs is the W3C standard for decentralized identifiers. The DID specification outlines a standard URI scheme for creating a persistent decentralized identifier (DID) for a given subject as well as resolving metadata about that identifier via a DID document. DIDs are used as an authentication mechanism by most StreamTypes.

DID methods

DID methods are implementations of the DID specification. DID methods must specify a name for the method in the form of a string (see below), a description of where the DID document is stored (or how it is statically generated), and a DID resolver which can return a DID document given a URI that conforms to that particular DID method. There are over 40 DID methods on the W3C's official DID registry. Ceramic can support any DID method if needed, and currently supports the 3ID DID method and the Key DID method. DID URIs look like this:

did:<method-name>:<method-specific-identifier>

DID document

DID documents are documents which contain metadata about a given DID. At a minimum they should contain cryptographic key material used for signature verification and encryption/decryption. They may be mutable where their keys and content can be changed/rotated (i.e. 3ID DID method) or statically generated where their contents cannot be manually changed (i.e. Key DID method).

DID resolver

DID resolvers are software libraries responsible for returning a DID document given a DID string. Each DID method has at least one resolver implementation. For all DID methods supported by Ceramic, the corresponding DID resolver must be included in a Ceramic node.

DID providers

DID providers are software libraries that allow developers or other programs to create, manage, and use DIDs that conform to a particular DID method. When using Ceramic with streams that require DIDs for authentication, applications either need to integrate a DID provider library, which leaves the responsibility of key management up to the application, or a DID wallet, which is a more user-friendly experience.

DID wallets

DID wallets are software libraries or end-user applications that wrap DID providers with additional capabilities. 3ID Connect is the most popular DID wallet SDK that allows users create, manage, and use a 3ID DID method with their existing blockchain wallets, and without needing to install any additional software.

Network

Clients

Clients are software libraries that provide developer interfaces to a Ceramic node. Clients are responsible for authenticating users, providing StreamType-specific interfaces for generating genesis commits and signed commits, and providing generic, streamtype-agnostic interfaces for loading or querying streams. A list of Ceramic clients can be found here.

Nodes

Nodes are software libraries that provide core protocol functionality for the Ceramic network. Nodes are responsible for processing stream updates (in the form of signed commits from clients), storing state for the streams that it cares about, responding to queries, networking with other nodes, replicating streams across the network, and sending valid signed commits to an external anchor service for generating anchor commits.

Anchor service

Anchor services are hosted "layer-2" services for Ceramic that generate anchor commits for many different streams in a scalable, low cost manner by batching many different stream transactions into a merkle tree, and including the merkle root into a transaction on a blockchain platform (currently Ethereum). This eliminates the need for each stream transaction to have its own corresponding blockchain transaction, which would be slower and more expensive.

Networks

Networks are collections of Ceramic nodes that share specific configurations and communicate over a dedicated libp2p topic. Networks are discrete from one another. Streams that exist on one network are not discoverable on or portable to another. Currently, Ceramic has three primary networks: mainnet, Clay Testnet, and dev unstable.

Mainnet

Mainnet is the Ceramic network used for production deployments. For more information on mainnet, see the Networks page.

Clay Testnet

Clay Testnet is a Ceramic network used by the community for application prototyping, development, and testing purposes. Ceramic core devs also use Clay for testing official protocol release candidates. For more information on Clay Testnet, see the Networks page.

Dev Unstable

Dev Unstable is a Ceramic network used by Ceramic core protocol developers for testing new protocol features and the most recent commits on the develop branch of js-ceramic. It should be considered unstable and highly experimental.

Underlying technologies

IPFS

IPFS is the Interplanetary File System. Simply put, IPFS is a way to address static content using CIDs and to discover this content over a peer-to-peer network of nodes. Ceramic relies on IPFS for storing the commits that make up streams and discovering this data over the network.

CID

A CID (content identifier) is an immutable identifier for a discrete piece of static content stored on IPFS. CIDs are essentially a hash of the content along with metadata that describes how the content is encoded. Ceramic streams consist of multiple CIDs, encoded using dag-jose (and other formats such as dag-cbor), and linked together using IPLD.

IPLD

IPLD (Interplanetary Linked Data) is the data structures layer of IPFS. It is used to link multiple CIDs together into higher-level linked-data structures. Ceramic uses IPLD to create the data structures for streams.

DagJOSE

DagJOSE is a codec for IPLD which stores content in IPFS using IETF's JOSE (JSON object signing and encryption) format. With DagJOSE, each data object actually consists of two separate but linked CIDs. It supports both signed and encrypted objects. JWS is used for signed objects and it encodes the payload as a CID, which means that the actual payload is a separate IPLD object. JWE is used for encrypted objects, and it requires the ciphertext to be a CID in order to not leak the full cleartext. A separate inline CID is used to encode the entire cleartext. For more information refer to the DagJOSE spec.

Libp2p

Libp2p is the peer-to-peer networking protocol that is used by Ceramic. It is included as part of the IPFS stack. Ceramic relies on libp2p for discovering data over the network and communicating between nodes. Libp2p is also used by other major decentralized platforms such as Ethereum (Eth2) and Polkadot.

Ethereum

Ethereum is the world's leading public, permissionless smart contract blockchain platform. Ceramic uses Ethereum for generating the timestamps contained within anchor commits.