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.
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.
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.
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. Anchor commits are needed since vanilla merkle DAGs have no notion of absolute time needed to build consensus.
Conflict resolution strategy¶
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 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 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 PKH DID method, 3ID DID method and the Key DID method. DID URIs look like this:
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 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. Ceramic uses DID resolvers to verify stream transactions by comparing the signature on the transaction to the controller of the stream. For the transaction to be successfully processed, a public key corresponding to the transaction signature must be present in the DID Document of the DID listed as a controller.
DID providers are software libraries that expose a json-rpc interface which allows for the creation and usage of a DID that conforms to a particular DID method. Usually a DID provider is constructed using a seed that the user controls. 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 are software libraries or end-user applications that wrap DID providers with additional capabilities. DID Session is the most popular DID wallet SDK that allows users create, manage, and use a DID method with their existing blockchain wallets, and without needing to install any additional software.
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 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.
A Ceramic Anchor Service (CAS) is a hosted "layer-2" solution for generating anchor commits for many different stream transactions in a scalable, low cost manner. Ceramic nodes are responsible for sending anchor requests containing a StreamID and a CommitID to a CAS, which then batches these transactions into a merkle tree, and includes the merkle root into a blockchain platform in a single transaction (currently Ethereum). After the transaction makes its way onto a blockchain, a Ceramic node creates an anchor commit which includes a reference to the blockchain transaction for every anchored stream. A CAS eliminates the need for each stream transaction to have its own corresponding blockchain transaction, which would be slower and more expensive.
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 is the Ceramic network used for production deployments. For more information on mainnet, see the Networks page.
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 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.
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.
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 (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 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 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.