Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 76 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 tcp-endpoint is defined within the KERI/GLEIF glossary as a service endpoint of the web transmission control protocol. This represents a fundamental network addressing mechanism used in KERI infrastructure for establishing communication channels between distributed components.
The defining technical characteristic of TCP endpoints, as documented in the KERI glossary sources, relates to session identification:
TCP packets do not include a session identifier. Instead, both communicating endpoints identify the session using:
When a TCP packet is received at a KERI component, the TCP implementation must perform a lookup operation on an internal routing table to determine the destination process for that packet. This stateful connection management is handled by the TCP protocol layer beneath KERI's cryptographic event exchange mechanisms.
This design differs from protocols that embed session identifiers within packet payloads, requiring both endpoints to maintain connection state through the network address tuple rather than explicit session tokens.
KERI implementations must handle TCP's stateful connection model by maintaining routing tables that map client address/port pairs to internal processing handlers. Unlike protocols with explicit session identifiers, TCP requires lookup operations on each packet arrival.
TCP's guaranteed delivery and in-order packet sequencing align well with KERI's requirement for reliable event transmission. However, KERI's cryptographic verification provides end-to-end integrity independent of transport reliability.
TCP endpoints are typically discovered through OOBI mechanisms, witness configuration files, or direct configuration in agent settings. The endpoint URL scheme (http://, tcp://) determines the transport protocol selection.
Direct TCP endpoint connectivity requires network accessibility between peers. In restricted network environments, HTTP-based transports (which layer over TCP) or WebSocket connections may provide better firewall traversal while maintaining the underlying TCP reliability characteristics.
The most concrete examples of TCP endpoints in KERI documentation appear in witness demonstration configurations. The GLEIF vLEI training materials document a three-witness demo network that uses TCP endpoints:
http://witness-demo:5642http://witness-demo:5643http://witness-demo:5644These endpoints demonstrate how KERI witnesses expose network services for receiving establishment events and returning signed receipts. The sequential port numbering (5642, 5643, 5644) on the same host represents a common pattern for deploying multiple witness instances for educational purposes.
KERI's direct mode operational model, as documented in the demo tutorials, involves peer-to-peer communication over TCP connections. The demo scripts keri_bob and keri_eve illustrate this pattern:
Bob's configuration:
Eve's configuration:
These configurations create bidirectional TCP connections where each participant acts as both client and server, exchanging key events and receipts directly without intermediary witnesses. The demo logs show communication patterns like:
Rx 127.0.0.1:5621
Tx 127.0.0.1:5620
Indicating received (Rx) and transmitted (Tx) messages over the established TCP connections between localhost endpoints.
The KERIA (KERI Agent in the cloud) service architecture references TCP endpoints in its deployment model. The documentation describes KERIA exposing three separate HTTP endpoints on three separate network interfaces:
While the specific implementation details use HTTP layered over TCP, the underlying network addressing relies on TCP endpoint mechanisms for establishing connections to these services.
The Out-Of-Band Introduction (OOBI) mechanism, which provides discovery and validation of IP resources for KERI autonomic identifiers, frequently references TCP endpoints. An OOBI associates a URL with an AID, and these URLs commonly point to TCP-accessible services:
The OOBI documentation notes that "discovery via URI, trust via KERI" - meaning while the initial network location discovery may use TCP endpoint URLs, the cryptographic trust establishment occurs through KERI's signature verification mechanisms independent of the transport layer.
KERI's architecture maintains strict separation between its cryptographic event verification mechanisms and the underlying transport layer. The KERI whitepaper and specifications emphasize that authenticity and integrity are established through digital signatures and CESR encoding rather than transport-layer security.
This design philosophy means:
The Composable Event Streaming Representation (CESR) protocol, which provides the encoding layer for KERI primitives, is designed to work across multiple transport mechanisms. CESR's dual text-binary encoding enables:
The CESR specification notes that primitives can be "streamed over TCP, UDP, or HTTP" while maintaining their cryptographic properties. TCP endpoints provide the reliable, ordered delivery that simplifies CESR stream processing compared to UDP's connectionless model.
The KERI demo documentation includes several network protocol traces that demonstrate TCP endpoint usage in practice. These traces show:
Inception events establishing new AIDs are transmitted between TCP endpoints with CESR-encoded payloads:
{"v":"KERI10JSON...","t":"icp","d":"...","i":"...","s":"0",...}
Followed by cryptographic signature attachments in CESR format.
Rotation events demonstrating key management operations flow over the same TCP connections:
{"v":"KERI10JSON...","t":"rot","d":"...","i":"...","s":"1","p":"...",...}
Receipt exchanges where validators return signed acknowledgments of observed events:
{"v":"KERI10JSON...","t":"vrc","d":"...","i":"...",...}
The demo logs show TCP endpoints from the perspective of a single node:
Rx 127.0.0.1:51612 # Received from remote endpoint
Tx 127.0.0.1:51612 # Transmitted to remote endpoint
This logging pattern demonstrates the bidirectional nature of KERI communication over TCP, where both participants send and receive events, receipts, and queries over established connections.
The glossary entry for "tcp-endpoint" specifically references "bare metal TCP" as one variant, distinguishing it from secured channel alternatives. This terminology acknowledges that:
Bare TCP provides:
Secured alternatives layered over TCP include:
KERI's security model explicitly does not depend on transport-layer security. The protocol provides:
This "end-to-end verifiable" security model means TCP endpoints can be used in untrusted network environments, with cryptographic verification providing security guarantees independent of the transport channel.
The KAWA (KERI's Algorithm for Witness Agreement) consensus mechanism, which coordinates witness receipts for identifiers operating in indirect mode, relies on witnesses communicating over network connections. While the specific transport is implementation-dependent, TCP endpoints provide the reliable delivery characteristics that simplify witness coordination:
The demo configurations show typical port selection patterns:
The KERI Command Line Interface (kli) includes options for configuring TCP endpoint parameters:
-r REMOTE, --remote REMOTE Remote port number for client connections
-l LOCAL, --local LOCAL Local port number for server listening
This flexibility allows deployments to adapt to different network environments, firewall rules, and organizational policies.
The TCP session identification mechanism described in the glossary entry has implications for KERI implementations:
Connection pooling: Implementations may maintain persistent TCP connections to frequently-contacted witnesses or agents, reusing the same client address/port tuple for multiple KERI operations.
Load distribution: When multiple witnesses share the same network address but use different ports (as in the demo configuration), clients can distribute load by opening connections to different TCP endpoints.
Failover handling: If a TCP connection to a witness endpoint fails, clients must re-establish the connection and potentially resend events, relying on KERI's idempotent event semantics rather than TCP's stream guarantees.
The did:webs resolver documentation demonstrates Docker-based deployment using TCP endpoints:
docker run -p 7676:7676 gleif/did-webs-resolver:latest
This command maps the container's internal TCP port 7676 to the host's port 7676, creating a TCP endpoint accessible to external clients. The resolver service listens on this endpoint for HTTP requests that resolve did:webs identifiers to their corresponding KERI event streams.
The KERIA architecture, when deployed in containers, exposes its three network interfaces through TCP endpoint mappings. This containerized approach enables:
The RACK security gateway implementation demonstrates production-grade TCP endpoint usage:
docker pull --platform linux/arm64 healthkeri/rack:latest
docker run -p [host_port]:[container_port] healthkeri/rack:latest
RACK implements "zero-trust network access" using KERI protocol over TCP endpoints, supporting both linux/amd64 and linux/arm64 architectures. The documentation shows TCP endpoint configuration for:
While the glossary defines tcp-endpoint as a specific type of service endpoint, KERI infrastructure uses various endpoint types:
Many KERI services expose HTTP(S) endpoints, which are layered over TCP but provide additional protocol semantics:
These maintain TCP's connection-oriented, reliable delivery while adding HTTP's request/response patterns and HTTPS's transport encryption.
The KERIA notification system uses server-sent events for streaming updates to clients, which may be implemented over WebSocket connections that are themselves built on TCP. This provides:
While not extensively documented in the provided sources, the CESR specification notes that primitives can be streamed over UDP as an alternative to TCP. UDP endpoints would sacrifice:
In exchange for:
The GLEIF vLEI training materials include a controller connection tutorial that demonstrates establishing authenticated connections between two KERI controllers. While the tutorial uses the KERIA agent architecture, the underlying communication occurs over TCP endpoints:
Setup pattern:
The tutorial notes that "real-world deployments would typically involve separate KERIA instances," each with its own TCP endpoints, communicating across network boundaries.
The witness training module demonstrates witness pool setup with explicit TCP endpoint configuration:
# Query witness KEL
curl http://witness-demo:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha
This command queries a witness's TCP endpoint to retrieve its OOBI information, demonstrating how TCP endpoints serve as the network access points for KERI infrastructure services.
The did:webs getting started guide describes a local command-line workflow for development that includes:
This workflow is described as "best for development and debugging" because TCP's reliable delivery and connection-oriented nature simplifies troubleshooting compared to production deployments with complex network topologies.
In direct mode, two KERI controllers establish peer-to-peer TCP connections for synchronous event exchange:
The training materials note this is "best for intermittent connections" where both parties are online simultaneously.
In indirect mode, witnesses provide persistent TCP endpoints that:
The witness network's TCP endpoints enable the asynchronous communication pattern that characterizes indirect mode operation.
TCP's connection-oriented nature imposes overhead compared to stateless protocols:
For high-throughput KERI applications with many ephemeral connections, this overhead may motivate alternative transport choices.
TCP's ordered delivery guarantee creates potential head-of-line blocking:
Modern alternatives like QUIC provide multiple streams over a single connection to mitigate this issue.
TCP endpoints face standard challenges in complex network environments:
KERI deployments must account for these infrastructure realities when configuring TCP endpoints for production use.
A tcp-endpoint in KERI represents a service endpoint using the Transmission Control Protocol, identified by the characteristic that TCP packets do not include session identifiers—instead, both endpoints identify sessions using the client's address and port number, requiring a lookup operation on an internal routing table for packet processing.
While TCP endpoints appear throughout KERI documentation—particularly in demo witness configurations, direct mode tutorials, and KERIA agent architectures—they represent implementation choices rather than fundamental protocol requirements. KERI's transport-agnostic design establishes security through cryptographic signatures and CESR encoding, allowing TCP endpoints to provide reliable, connection-oriented delivery without bearing responsibility for authenticity or integrity guarantees.
The practical examples show TCP endpoints primarily in educational contexts (demo witnesses at ports 5642-5644, direct mode peers at ports 5620-5621) and containerized deployments (KERIA agents, did:webs resolvers, RACK gateways). Production deployments select TCP endpoint configurations based on network topology, organizational policies, and infrastructure requirements while relying on KERI's cryptographic security model for trust establishment independent of the transport layer.