Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 177 GitHub source documents. All source documents are searchable here.
Last updated: October 7, 2025
This content is meant to be consumed by AI agents via MCP. Click here to get the MCP configuration.
Note: In rare cases it may contain LLM hallucinations.
For authoritative documentation, please consult the official GLEIF vLEI trainings and the ToIP Glossary.
An exn (exchange) message is a KERI protocol message type used for peer-to-peer communication and data exchange between KERI entities, enabling credential issuance, presentation, and general information exchange through cryptographically signed, self-framing messages.
The exn (exchange) message type serves as the foundational communication mechanism for peer-to-peer interactions in the KERI ecosystem. As documented in the KERI Peer-to-Peer Communication specification, exn messages enable:
The exn message type is explicitly designed to be protocol-agnostic at the transport layer while maintaining cryptographic authenticity through KERI's signature mechanisms. This design enables exn messages to carry embedded protocols (like IPEX for credential exchange) while preserving the security guarantees of KERI's key event infrastructure.
All exn messages share a common top-level structure that provides consistent parsing and verification across different use cases:
{
"v": "KERI10JSON00011c_",
"t": "exn",
"dt": "2023-08-15T14:30:00.000000+00:00",
"r": "/credential/offer",
"q": { /* embedded protocol data */ }
}
The structure follows KERI's self-framing message design, where:
v) enables protocol evolution and serialization format identificationVersion String Calculation: The size indicator in the version string MUST accurately reflect the message body length. Incorrect size values will cause parsing failures in stream processors.
Datetime Precision: Use ISO 8601 format with microsecond precision and timezone offset. Implementations should use UTC (+00:00) to avoid timezone-related issues.
Route Namespacing: When defining custom protocols, use organization-specific namespaces to avoid collisions: /org.example/protocol/operation
Multi-Signature Coordination: For multi-sig scenarios, implement proper signature collection and aggregation. The MultisigIssuance documentation describes using exn messages to coordinate between signers.
Threshold Verification: Always verify that collected signatures meet the threshold requirements defined in the sender's current key state.
Key State Resolution: Cache KEL queries to avoid repeated lookups, but implement cache invalidation when key rotations occur.
Time Window Configuration: Configure acceptable time windows based on network latency and security requirements. Typical values range from 30 seconds to 5 minutes.
Clock Synchronization: Ensure system clocks are synchronized via NTP. Clock drift can cause legitimate messages to be rejected.
Nonce Tracking: For high-security scenarios, implement additional nonce-based replay protection beyond datetime validation.
Payload Schema Validation: Define JSON schemas for custom protocol payloads and validate incoming messages against these schemas.
Error Handling: Implement comprehensive error responses using exn messages with error-specific routes (e.g., /error/invalid-signature).
Versioning Strategy: Plan for protocol evolution by including version indicators in routes or payload structures.
tdt) provides temporal ordering and replay attack protectionr) specifies the embedded protocol and operationq) contains the protocol-specific data structurev)The version string follows KERI's regexable format: KERI10JSON00011c_
KERI10 indicates KERI version 1.0JSON specifies JSON encoding (alternatives: CBOR, MGPK)00011c (hexadecimal) specifies message body length_ marks the end of the version stringThis format enables cold-start stream parsing where processors can determine message boundaries without parsing the entire content.
t)The t field value "exn" distinguishes exchange messages from:
"icp" - Inception events"rot" - Rotation events"ixn" - Interaction events"rct" - Receipt messages"qry" - Query messages"rpy" - Reply messagesThis type system enables KERI processors to route messages to appropriate handlers.
dt)The datetime field uses ISO 8601 format with microsecond precision:
2023-08-15T14:30:00.000000+00:00
This timestamp serves multiple purposes:
The KRAM (KERI Request Authentication Mechanism) specification defines how datetime fields interact with replay protection windows.
r)The route field uses a hierarchical namespace structure:
/protocol/operation/suboperation
Common route patterns include:
/credential/offer - Credential issuance offer/credential/apply - Credential application request/credential/issue - Actual credential issuance/presentation/request - Presentation request/presentation/submit - Presentation submissionThe route enables protocol multiplexing where different embedded protocols can coexist within the exn message framework.
q)The q field contains the embedded protocol data structure, which varies based on the route. For credential issuance:
{
"issuer": "did:keri:EEBp64Aw2rsjdJpAR0e2qCq3jX7q7gLld3LjAwZgaLXU",
"schema": "EckOnHB11J4H9q16I3tN8DdpNXnCiP5QJQ7yvkWqTDdA",
"credential_manifest": { /* manifest structure */ }
}
The q field structure is protocol-specific and defined by the embedded protocol specification (IPEX, custom protocols, etc.).
All exn messages MUST include:
v (version): String, regexable KERI version identifiert (type): String, must be "exn"dt (datetime): String, ISO 8601 timestamp with timezoner (route): String, hierarchical resource pathq (query/payload): Object, embedded protocol dataExn messages MAY include:
a (attachments): Array of additional data structurese (edges): References to related messages or credentialsExn messages support multiple serialization formats:
The primary format for human-readable exchanges:
{
"v": "KERI10JSON00011c_",
"t": "exn",
"dt": "2023-08-15T14:30:00.000000+00:00",
"r": "/credential/offer",
"q": {
"issuer": "did:keri:EEBp64Aw2rsjdJpAR0e2qCq3jX7q7gLld3LjAwZgaLXU"
}
}
Binary format for compact transmission:
KERI10CBOR000118_MessagePack format for high-performance scenarios:
KERI10MGPK000115_Exn messages include CESR-encoded cryptographic attachments appended after the message body:
-AABAA1o61PgMhwhi89FES_vwYeSbbWnVuELV_jv7Yv6f5zNiOLnj1ZZa4MW2c6Z_vZDt55QUnLaiaikE-d_ApsFEgCA
The attachment structure:
-AAB indicates attachment type and countThis format enables self-framing where the attachment length is determinable from the count code.
The version string's size indicator supports:
Practical limits depend on:
"exn")Creating an exn message involves:
q structureAfter message construction:
For multi-signature scenarios:
Once signed, exn messages are cryptographically immutable:
This immutability is fundamental to KERI's security model.
New message versions are created through:
q structure with new fieldsBackward compatibility is maintained through:
Recipients perform multi-layer validation:
t field is "exn"q structure against protocol schemaSignature verification involves:
For replay attack protection:
dt fieldThe KRAM specification defines acceptable time windows based on:
The primary use case for exn messages is IPEX protocol:
Credential Issuance Flow:
/credential/offer): Issuer proposes credential/credential/apply): Holder requests credential/credential/issue): Issuer delivers credentialPresentation Flow:
/presentation/request): Verifier requests proof/presentation/submit): Holder provides proofEach step uses exn messages with protocol-specific payloads.
Organizations can define custom protocols using exn:
/org/protocol/operationThis extensibility enables domain-specific applications while maintaining KERI security guarantees.
Exn messages facilitate multi-signature workflows:
The MultisigIssuance documentation describes using exn messages for coordinating credential issuance among multiple issuers.
Exn messages are created when:
Transmission occurs through:
Exn messages may be stored:
Storage policies depend on:
Exn messages depend on KELs for:
Without access to sender's KEL, recipients cannot verify exn message signatures.
For credential-related exn messages:
Exn messages transport ACDCs:
q fieldOOBIs enable exn message exchange by:
Exn messages cannot be exchanged without prior OOBI resolution or pre-existing connections.
The dt field combined with KRAM provides replay protection:
CESR signature attachments provide end-to-end security:
Exn messages provide authenticity but not confidentiality:
Exn messages enable authorization verification:
For request-response patterns:
This pattern suits interactive protocols like credential presentation.
For store-and-forward patterns:
This pattern suits offline-capable scenarios like credential issuance.
For one-to-many patterns:
This pattern suits notification scenarios.
The exn message type represents KERI's universal communication primitive, enabling secure, verifiable peer-to-peer exchanges while maintaining protocol extensibility. Its design balances:
Understanding exn messages is essential for implementing KERI-based applications, particularly those involving credential issuance and presentation through IPEX protocol.
Serialization Format Selection: Use JSON for development and debugging, CBOR for production bandwidth efficiency, MGPK for high-performance scenarios.
Batch Processing: When processing multiple exn messages, batch signature verifications to amortize cryptographic operation costs.
Async I/O: Implement asynchronous message handling to avoid blocking on network operations or cryptographic computations.
Input Validation: Validate all fields before processing. Malformed messages should be rejected early to prevent resource exhaustion attacks.
Rate Limiting: Implement rate limiting on exn message acceptance to prevent denial-of-service attacks.
Confidentiality: For sensitive data, implement additional encryption layers (SPAC protocol) as exn messages provide authenticity but not confidentiality by default.
Test Vectors: Use the demo vectors in the keripy repository (src/keri/demo/vectors/) as reference implementations.
Interoperability Testing: Test against multiple KERI implementations (keripy, keriox, signify-ts) to ensure compatibility.
Failure Scenarios: Test handling of invalid signatures, expired timestamps, malformed payloads, and network failures.