Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 148 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.
KERIpy is the reference Python implementation of the KERI protocol, serving as the canonical implementation against which all other KERI implementations are validated. Developed primarily by Samuel M. Smith and maintained by the WebOfTrust organization, KERIpy implements the complete KERI specification including autonomic identifiers, key event logs, witnesses, watchers, and the full CESR encoding system.
As the reference implementation, KERIpy defines the practical interpretation of KERI specifications and serves as the foundation for production systems including GLEIF's vLEI ecosystem. The implementation is licensed under Apache 2.0 and is actively developed with regular releases tracking IETF specification evolution.
Current Status: Version 1.2.x series (as of documentation), with active development in the main branch and stable releases for production use.
Relationship to Specifications: KERIpy implements:
/usr/local/var/keri/ but can be configuredn - f where f is fault tolerance--insecure flag in production (writes secrets to filesystem)--kc (keychain) or --op (1Password) for secret managementKERIpy provides complete implementation of KERI's foundational features:
Autonomic Identifier Management:
Key Event Log Architecture:
Multi-Signature Support:
KERIpy includes complete witness implementation:
Witness Operations:
Watcher Services:
KERIpy implements the complete ACDC specification:
Credential Issuance:
Registry Management:
IPEX Protocol:
KERIpy provides the reference CESR implementation:
Primitive Types:
Stream Processing:
KERIpy uses LMDB (Lightning Memory-Mapped Database) for persistent storage:
Storage Architecture:
Key Management:
The KLI provides comprehensive command-line access:
Identifier Operations:
kli incept - Create new identifierskli rotate - Rotate keyskli interact - Create interaction eventskli status - Query identifier stateWitness Management:
kli witness demo - Run demonstration witness poolkli witness add - Add witnesses to identifierkli witness rotate - Rotate witness configurationCredential Operations:
kli vc create - Issue credentialskli vc present - Present credentialskli vc revoke - Revoke credentialskli vc verify - Verify credential validityOOBI Resolution:
kli oobi resolve - Resolve Out-Of-Band Introductionskli oobi generate - Generate OOBIs for identifiersPython Version: 3.12.1 or higher (3.12.x recommended)
System Dependencies:
macOS libsodium Setup:
# Install via Homebrew
brew install libsodium
# Create symlink for Python ctypes discovery
sudo ln -s /opt/homebrew/lib /usr/local/lib
From PyPI (stable releases):
pip install keri
From Source (development):
git clone https://github.com/WebOfTrust/keripy.git
cd keripy
python3 -m pip install -e ./
Docker Installation:
# Build image
make build-keri
# Run container
docker run --pull=never -it --entrypoint /bin/bash weboftrust/keri:1.1.10
KERIpy requires several specialized packages:
Core Dependencies:
lmdb>=0.98 - Database backendpysodium>=0.7.5 - Cryptographic operationsblake3>=0.1.5 - BLAKE3 hashingmsgpack>=1.0.0 - MessagePack serializationsimplejson>=3.17.0 - JSON encodingcbor2>=5.1.0 - CBOR encodingInstallation:
pip install -U lmdb pysodium blake3 msgpack simplejson cbor2
Virtual Environment:
# Create environment
python3 -m venv keripy-env
# Activate
source keripy-env/bin/activate # Unix/macOS
keripy-env\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
Testing:
# Install pytest
pip install pytest
# Run core tests
pytest tests/ --ignore tests/demo/
# Run demo tests
pytest tests/demo/
KERIpy uses configuration files for witness and agent setup:
Witness Configuration (witness-config.json):
{
"dt": "2024-01-01T00:00:00.000000+00:00",
"curls": [
"http://127.0.0.1:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha",
"http://127.0.0.1:5643/oobi/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM",
"http://127.0.0.1:5644/oobi/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX"
]
}
Agent Configuration (keria-config.json):
{
"dt": "2024-01-01T00:00:00.000000+00:00",
"iurls": [
"http://127.0.0.1:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha"
]
}
Non-Transferable Identifier:
import keri.core.eventing as eventing
import keri.core.coring as coring
import keri.app.keeping as keeping
import keri.db.dbing as dbing
# Open database and keystore
with dbing.openLMDB(name="test") as db, keeping.openKS(name="test") as kpr:
# Generate salt for key derivation
salt = coring.Salter().qb64
# Create key manager
mgr = keeping.Manager(ks=kpr, salt=salt)
# Generate keys (1 current, 0 next = non-transferable)
verfers, _, _, _ = mgr.incept(icount=1, ncount=0)
# Create inception event
srdr = eventing.incept(
keys=[verfers[0].qb64],
code=coring.MtrDex.Ed25519
)
print(f"Identifier: {srdr.pre}")
Transferable Identifier with Pre-Rotation:
# Generate keys with pre-rotation
verfers, digers, _, _ = mgr.incept(icount=1, ncount=1)
# Create transferable inception
srdr = eventing.incept(
keys=[verfers[0].qb64],
nxt=coring.Nexter(digs=[digers[0].qb64]).qb64,
code=coring.MtrDex.Ed25519
)
print(f"Transferable AID: {srdr.pre}")
print(f"Next key digest: {coring.Nexter(digs=[digers[0].qb64]).qb64}")
Rotating Keys:
# Generate new keys
verfers, digers, _, _ = mgr.rotate(pre=srdr.pre, count=1)
# Create rotation event
rot_srdr = eventing.rotate(
pre=srdr.pre,
keys=[verfers[0].qb64],
dig=srdr.said, # Previous event digest
nxt=coring.Nexter(digs=[digers[0].qb64]).qb64,
sn=1 # Sequence number
)
print(f"Rotated to key: {verfers[0].qb64}")
Creating Multi-Sig Group:
# Generate keys for multiple participants
verfers1, digers1, _, _ = mgr.incept(icount=1, ncount=1)
verfers2, digers2, _, _ = mgr.incept(icount=1, ncount=1)
# Create multi-sig inception with 2-of-2 threshold
srdr = eventing.incept(
keys=[verfers1[0].qb64, verfers2[0].qb64],
nxt=coring.Nexter(digs=[digers1[0].qb64, digers2[0].qb64]).qb64,
code=coring.MtrDex.Ed25519,
sith="2", # Signing threshold
nsith="2" # Next threshold
)
print(f"Multi-sig AID: {srdr.pre}")
Adding Witnesses:
# Witness AIDs
wits = [
"BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha",
"BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM",
"BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX"
]
# Create inception with witnesses
srdr = eventing.incept(
keys=[verfers[0].qb64],
nxt=coring.Nexter(digs=[digers[0].qb64]).qb64,
wits=wits,
toad=2 # Threshold of Accountable Duplicity
)
Creating Primitives:
from keri.core import coring
# Create digest
diger = coring.Diger(raw=b"some data", code=coring.MtrDex.Blake3_256)
print(f"Digest: {diger.qb64}")
# Create signature
signer = coring.Signer(raw=b"private_key_bytes")
sig = signer.sign(b"message")
print(f"Signature: {sig.qb64}")
# Create verifier
verfer = coring.Verfer(raw=b"public_key_bytes")
verified = verfer.verify(sig.raw, b"message")
print(f"Verified: {verified}")
Creating Credential:
import keri.core.scheming as scheming
# Define schema
schema = {
"$id": "EBfdlu8R27Fbx-ehrqwImnK-8Cm79sqbAQ4MmvEAYqao",
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"name": {"type": "string"},
"role": {"type": "string"}
}
}
# Create credential
cred = {
"v": "ACDC10JSON000197_",
"d": "", # SAID computed
"i": issuer_aid,
"s": schema_said,
"a": {
"d": "",
"i": issuee_aid,
"name": "John Doe",
"role": "Manager"
}
}
Querying KEL:
from keri.core import eventing
from keri.db import dbing
with dbing.openLMDB(name="test") as db:
# Get KEL for identifier
kever = eventing.Kever(db=db, pre=aid)
# Access key state
print(f"Sequence: {kever.sn}")
print(f"Keys: {kever.verfers}")
print(f"Witnesses: {kever.wits}")
print(f"Threshold: {kever.tholder.thold}")
KERI-ox (Rust):
KERIgo (Go):
KERIml (Swift):
KERIA (KERI Agent):
Signify (Client Libraries):
Keep (Wallet UI):
Witness Networks:
OOBI Resolution:
Credential Verification:
Asynchronous Design: KERIpy uses HIO (Hierarchical Asynchronous Coroutines and I/O) for all I/O operations. This enables:
Doer Pattern:
The doing.DoDoer class provides hierarchical coroutine management:
class CustomDoer(doing.DoDoer):
def recur(self, tyme):
# Custom logic
yield from super().recur(tyme)
Escrow System: Out-of-order events are escrowed until dependencies arrive:
Key Storage:
Witness Selection:
n - f where f is fault toleranceDuplicity Detection:
Database Tuning:
Stream Processing:
Caching:
Witness Configuration:
Key Rotation:
Multi-Sig Coordination:
Breaking Changes:
Migration Paths:
Unit Tests:
Integration Tests:
Demo Scripts:
kli witness demo for local testingOfficial Documentation:
Community Resources:
Training Materials:
kli witness demo provides six-witness network for local testingscripts/demo/ directory demonstrate complete workflows