Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 144 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.
A prefix is a qualified cryptographic primitive in CESR format that combines a derivation code with an encoded public or , serving as the self-certifying for an in . The prefix cryptographically binds the identifier to its controlling key material through one-way functions, enabling self-certification without external trust.
A prefix in KERI is a composite data structure that serves as the fundamental identifier for an Autonomic Identifier (AID). The prefix combines two essential components into a single self-describing string:
The canonical example from the source documents illustrates this structure:
BDKrJxkcR9m5u1xs33F5pxRJP6T7hJEbhpHrUtlDdhh0
In this 44-character prefix:
B): Single-character derivation code indicating Ed25519 non-transferable prefixThe prefix structure implements KERI's principle of self-certification - the identifier itself contains sufficient information to cryptographically verify control authority without requiring external lookups or trusted third parties. This design eliminates the need for certificate authorities or centralized registries that plague traditional PKI systems.
The derivation code serves multiple critical functions:
The binding between derivation code and key material is immutable - any modification to either component produces a completely different prefix, making tampering immediately evident.
KERI supports multiple prefix derivation patterns, each serving different use cases:
Basic Self-Certifying Prefix: Directly encodes the public key with a derivation code. The identifier is literally the encoded public key, making verification straightforward - extract the key from the prefix and verify signatures.
Self-Addressing Prefix: Uses a cryptographic digest of the inception event data rather than the raw public key. This approach:
Multi-Sig Self-Addressing Prefix: Derives from a digest that includes multiple public keys and threshold specifications, enabling group control.
Delegated Self-Addressing Prefix: Includes cryptographic commitment to a delegating identifier, creating hierarchical trust structures.
Prefixes use Base64 URL-safe encoding (RFC 4648) exclusively, which provides:
[A-Z, a-z, 0-9, -, _] (64 characters)Critical constraint: CESR requires 24-bit alignment for composability. All prefixes must be integer multiples of 4 Base64 characters (24 bits = 4 × 6 bits). This alignment enables lossless round-trip conversion between text and binary domains.
The derivation code determines the prefix structure. From the CESR specification, common codes include:
Single-character codes (1 byte derivation code + variable key material):
B: Ed25519 non-transferable prefix (44 chars total)C: X25519 public encryption keyD: Ed25519 public verification keyE: Blake3-256 digest (self-addressing)F: Blake2b-256 digestMulti-character codes (for larger key sizes or specialized types):
1AAA: ECDSA secp256k1 non-transferable prefix1AAC: Ed448 non-transferable prefixEach code specifies:
Prefixes must satisfy multiple constraints:
Prefix generation follows a deterministic process:
Step 1: Entropy Generation
Step 2: Key Pair Derivation
Step 3: Prefix Construction
Step 4: Validation
The source documents emphasize that the bran (seed) combined with the keystore's aeid (authentication encryption identifier) deterministically generates all key-pairs. This means identical inputs always produce identical prefixes, enabling key recovery from seed backup.
Prefix verification involves multiple layers:
Structural Validation:
Cryptographic Validation:
Key State Validation:
The source documents note that for self-addressing identifiers, both the d (SAID) and i (identifier) fields in the inception event must contain identical values after derivation, creating a self-referential integrity check.
Critical principle: Prefixes are immutable identifiers. They never change once created. However, the control authority over a prefix can change through key rotation.
Key Rotation Process:
This separation between identifier (prefix) and key state is fundamental to KERI's architecture. The prefix provides stable identity while keys can be rotated for security.
Delegation Operations:
Prefixes appear throughout KERI protocol messages:
In Key Events:
i field: Identifier prefix of the AIDdi field: Delegator prefix (for delegated identifiers)b arrayn field (also prefixes)In Receipts:
In ACDCs:
i field)Inception Phase:
Operational Phase:
Delegation Phase (if applicable):
Recovery Phase:
Prefixes interact with multiple KERI data structures:
KEL (Key Event Log):
i fieldKERL (Key Event Receipt Log):
TEL (Transaction Event Log):
SAID (Self-Addressing Identifier):
Discovery:
http://witness:port/oobi/{prefix}/witness/{witness_prefix}Verification:
Delegation:
di field with delegator prefixPrefix operations have specific performance characteristics:
Generation: Computationally expensive (key generation)
Verification: Moderate cost (signature verification)
Parsing: Very fast (string operations)
Storage: Compact representation
Source documents reveal several implementation patterns:
Keystore Organization:
Witness Configuration:
Multi-Signature Groups:
Delegation Hierarchies:
di fieldThe source documents emphasize that prefixes are the atomic unit of identity in KERI - all other structures (KELs, credentials, registries) reference and depend on prefixes as their foundation.
Choosing the appropriate derivation code is critical:
Non-transferable vs. Transferable: Use basic codes (e.g., 'B') for ephemeral identifiers that don't need key rotation. Use self-addressing codes (e.g., 'E') for persistent identifiers requiring rotation capability.
Algorithm Selection: Ed25519 ('B', 'D') provides excellent performance and security for most use cases. ECDSA secp256k1 ('1AAA', '1AAB') may be required for blockchain interoperability. Ed448 ('1AAC', '1AAD') offers higher security margins.
Multi-sig Requirements: Self-addressing prefixes ('E', 'F', etc.) are required for multi-signature configurations, as the prefix must be derived from a digest that includes all participant keys and thresholds.
The source documents emphasize that the bran (seed) is the root secret:
Implementations should follow the KERIpy pattern:
When creating prefixes with witnesses:
Implement comprehensive validation:
def validate_prefix(prefix: str) -> bool:
# Check length is multiple of 4 (24-bit alignment)
if len(prefix) % 4 != 0:
return False
# Validate Base64 URL-safe character set
valid_chars = set('ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_')
if not all(c in valid_chars for c in prefix):
return False
# Parse derivation code and verify length
code = prefix[0] # Simplified - may be multi-char
expected_length = DERIVATION_CODE_LENGTHS.get(code)
if expected_length and len(prefix) != expected_length:
return False
return True