Serialization Formats

KERI messages support multiple serialization formats, all of which must maintain the fundamental body-plus-attachments structure:

JSON Serialization: The most common format for human-readable messages, using KERI10JSON version strings. JSON messages consist of a JSON object (the body) followed by CESR-encoded attachments.

CBOR Serialization: Concise Binary Object Representation provides compact binary encoding while maintaining the same logical structure.

MessagePack (MGPK): Another binary serialization option offering efficient encoding for streaming applications.

Message Body Structure

The message body is a serialized data structure that varies by message type but typically includes:

Version String (v): A regexable format string indicating protocol version, serialization type, and message size (e.g., KERI10JSON0000e6_)

Message Type (t): Identifies the category of message:

• icp - Inception event
• rot - Rotation event
• ixn - Interaction event
• rct - Receipt
• qry - Query
• rpy - Reply
• exn - Exchange message
• vrc - Validator receipt

Identifier (i): The AID that is the subject of the message

Sequence Number (s): For key events, indicates position in the KEL

Event-Specific Fields: Additional fields determined by message type (keys, thresholds, digests, anchors, etc.)

Attachment Structure

Attachments are encoded using CESR primitives and groups, providing self-framing cryptographic material:

Signature Attachments: The most common attachment type, containing:

• Count codes: Indicate the number and type of signatures
• Indexed signatures: For multi-sig scenarios, include key index information
• Non-indexed signatures: For single-sig scenarios

Receipt Attachments: For witness receipts, containing:

• Witness identifier
• Witness signature on the event
• Coupling information linking receipt to event

Seal Attachments: Cryptographic commitments to external data

OOBI Attachments: Out-of-Band Introduction information for discovery

Attachments are separated from the body by CESR framing codes (e.g., -AAB for a signature attachment), enabling parsers to distinguish between body content and cryptographic material.

Size and Constraints

Message size is constrained by:

• Version string encoding: Includes size information for efficient parsing
• CESR alignment: All primitives must align on 24-bit boundaries for composability
• Transport limitations: HTTP, TCP, or UDP constraints depending on delivery mechanism

Typical message sizes range from hundreds of bytes (simple events) to several kilobytes (complex multi-sig events with multiple attachments).

Operations

Message Creation

Creating a KERI message involves several steps:

1. Body Construction: Assemble the message body with required fields for the message type
2. Serialization: Convert the body to the chosen format (JSON, CBOR, MGPK)
3. Signing: Generate cryptographic signatures over the serialized body
4. Attachment Encoding: Encode signatures and other attachments in CESR format
5. Concatenation: Append CESR-encoded attachments to the serialized body

For key event messages, the body must include the event digest (d field), which is a SAID computed over the entire event content. This creates a self-referential structure where the identifier is derived from the content it identifies.

Message Transmission

Messages are transmitted through various transport mechanisms:

Direct Mode: Point-to-point transmission between controllers over HTTP or TCP

Indirect Mode: Transmission via witnesses and watchers, using mailbox services for asynchronous delivery

Streaming: Messages can be concatenated into CESR streams for efficient batch processing

The CESR encoding ensures messages are self-framing, allowing parsers to extract individual messages from streams without external framing protocols.

Message Verification

Verifying a KERI message requires:

1. Parsing: Separate the body from attachments using CESR framing codes
2. Deserialization: Convert the body from its serialized format to a data structure
3. Signature Verification: For each signature attachment:
   • Extract the signature and signing key information
   • Determine the authoritative keys at the time of signing (from the KEL)
   • Verify the signature against the message body using the public key
4. Threshold Validation: Ensure sufficient signatures meet the signing threshold
5. Semantic Validation: Verify message-specific constraints (sequence numbers, digests, etc.)

For key event receipts, verification additionally requires:

• Confirming the receipt references a valid key event
• Verifying the witness signature
• Checking witness authorization in the event's witness list

Message Processing

Processing messages involves:

Escrow Management: Messages that cannot be immediately processed (due to missing dependencies) are placed in escrow:

• Out-of-order escrow: Events arriving before their predecessors
• Partially signed escrow: Multi-sig events awaiting additional signatures
• Delegation escrow: Delegated events awaiting delegator approval

State Updates: Successfully verified messages update the local state:

• Key events append to the KEL
• Receipts update the KERL
• Queries trigger state lookups and reply generation

Duplicity Detection: Messages are checked against existing state to detect duplicity—the existence of conflicting versions of the same event.

Usage Context

In KERI Protocol

Messages are the fundamental communication primitive in KERI, used for:

Key Event Logs: The KEL is constructed from a sequence of key event messages, each cryptographically chained to its predecessor through digest references.

Witness Infrastructure: Witnesses receive key event messages, verify them, and return receipt messages attesting to their observation of the events.

Watcher Networks: Watchers collect messages from multiple sources to detect duplicity and provide ambient verifiability.

Controller Interactions: Controllers exchange messages to:

• Discover each other's key state via OOBI resolution
• Request and provide key event logs
• Coordinate multi-sig operations
• Delegate identifier authority

In ACDC Protocol

Messages carry ACDC credentials and related operations:

Credential Issuance: IPEX grant messages contain ACDC credentials being issued from issuer to holder.

Credential Presentation: IPEX apply and offer messages enable credential presentation from holder to verifier.

Registry Operations: TEL events are anchored in KEL messages through seals, linking credential state to key state.

In TSP Protocol

The Trust Spanning Protocol uses KERI messages for:

VID Resolution: Messages carry DID documents and key state information for verifiable identifiers.

Encrypted Communication: TSP messages wrap KERI messages with additional encryption layers while preserving the underlying message structure.

Lifecycle Management

Messages have a defined lifecycle:

1. Creation: Message is constructed by a controller or agent
2. Signing: Cryptographic signatures are attached
3. Transmission: Message is sent to recipients (witnesses, watchers, other controllers)
4. Reception: Recipients receive and parse the message
5. Verification: Recipients verify signatures and semantic validity
6. Processing: Message updates local state or triggers responses
7. Archival: Messages are stored in logs for future reference and verification

Related Structures

Messages interact with several related data structures:

Key Event Log (KEL): An ordered sequence of key event messages forming the authoritative history of an AID.

Key Event Receipt Log (KERL): A KEL augmented with receipt messages from witnesses.

Transaction Event Log (TEL): A log of transaction events (like credential issuance/revocation) anchored to a KEL through seals in key event messages.

CESR Streams: Concatenated sequences of messages encoded in CESR format for efficient streaming and processing.

OOBI: Out-of-Band Introductions that bootstrap message exchange by providing initial discovery information.

The message structure's flexibility and composability make it the universal carrier for all KERI protocol operations, enabling the protocol's security properties while maintaining efficiency and interoperability across diverse deployment scenarios.