CLPR for developers

Section 1of 23

What CLPR is for, and what you can build

Source: design §1 · design §3.4 · design §2.2 (clpr-spec@945082d)

CLPR is a transport primitive: reliable, asynchronous, in-order delivery of arbitrary byte payloads from an application on one ledger to an application on another, with exactly one response per data message. It is defined by what it refuses to introduce. No new token. No intermediary consensus layer. No federated signer set. No pooled liquidity. The destination ledger accepts a message only after verifying, in its own execution environment, a state proof produced by the source ledger’s own consensus. When both ledgers provide asynchronous Byzantine fault tolerant finality, cross-ledger communication inherits those guarantees and “requires only a single honest endpoint node per ledger for correct operation”, provided the channel’s verifier and both CLPR Services are correct; that honest endpoint is needed for liveness, not for safety.

In one paragraph: an application calls sendMessage. The message is appended to an ordered, per-channel outbound queue and folded into a SHA-256 running hash. An off-chain endpoint fetches (or constructs) a proof that the queue state is committed on the source ledger, hands it to a peer endpoint over gRPC, and the peer submits it as a native transaction. The destination CLPR Service passes the opaque proof to the channel’s verifier contract, then independently checks progress, size, sequence and the running hash, dispatches to the application, charges the connector for the gas used, and enqueues a response. The response travels back the same way. The simulation below is the same twenty-eight-step round trip as the general page’s, with the protocol wording under each step and a source line per step.

Four application patterns are outlined so far, each just messages with replies:

When several channels exist between the same two ledgers, for example one per Ethereum commitment level, the application picks one at send time by its own needs: a price feed may accept the risk of a reorganisation for speed, a high-value transfer waits for finality. CLPR imposes no default.

Source: design §3.4.1 · design §3.4.2 · design §3.4.3 · design §3.4.4 · design §3.4 (clpr-spec@945082d)

Choosing a channel is part of the application’s design, not the protocol’s: several channels may join the same two ledgers with different verifiers, and the application names one on every send.

Section 2of 23

The mental model: the trust chain, safety and liveness

Source: design §1 · design §2.3 · spec §8.2 (clpr-spec@945082d)

Removing the intermediary does not remove trust; it shortens the list. An application on Ledger A sending to Ledger B trusts, in order:

1. Its own ledger’s consensus: Ledger A orders and finalizes correctly.
2. The local CLPR Service: the implementation on A executes the protocol faithfully.
3. The channel’s verifier: the contract that validates B’s proofs. “A buggy or compromised verifier could accept fabricated proofs.”
4. The remote ledger’s consensus and CLPR Service.
5. The remote application.

Two infrastructure roles sit outside the chain: the CLPR Service Admin, with purely protective powers (configure, close) and no economic incentive; and the Endpoint Operator, who moves bundles for every channel on a ledger without choosing among them.

Endpoints are untrusted for safety, required for liveness. “Even with dishonest endpoints, no fabricated messages can be accepted — but availability depends on at least one honest endpoint per side relaying bundles.” A malicious connector, likewise, “cannot forge or tamper with messages” but can refuse to pay.

Section 3of 23

The four layers

Source: design §3 · organization profile (clpr-spec@945082d, org-profile@528e9c0)

Network communication uses gRPC; every protocol type on the wire is protobuf. All state-proof verification is delegated to verifier contracts registered per channel; the CLPR Service itself is proof-system-agnostic and never interprets proof bytes. That single decision is what makes the protocol extensible to ledgers with different consensus and data formats without changing the service on ledgers already connected.

Section 4of 23

Send, and two callbacks

Source: design §3.4 · spec §6.4 · spec §6.5 Application Delivery · IClprApplication.sol (clpr-spec@945082d, clpr-smart-contracts@276c8d5)

The application surface is deliberately tiny: one call to send, two callbacks to receive.

sendMessage([auth] caller, channel_id: bytes(32), connector_id: bytes(32),
            target_application: bytes, message_data: bytes) → { message_id: uint64 }

interface IClprApplication {
    /// Called when a cross-ledger Data Message arrives. Return bytes become the reply.
    function onClprMessage(bytes32 channelId, bytes calldata sender, bytes calldata messageData)
        external returns (bytes memory responseData);

    /// Called, best-effort, when the response to a message this contract sent arrives.
    function onClprResponse(bytes32 channelId, uint64 messageId, uint8 status, bytes calldata responseData)
        external;
}

Platform specifications define the gas budget, whether callbacks are synchronous, how success is signalled and what happens to externally owned senders: an EOA cannot receive a callback, so responses to it “SHOULD be recorded in the transaction receipt/record but no callback is made”. In the EVM implementation the callback is synchronous within the bundle transaction, capped at max_gas_per_message, and a revert becomes APPLICATION_ERROR with the revert data as the reply.

A minimal echo application, with the caller check that any real deployment needs:

contract PingPong is IClprApplication {
    address public immutable clprService;
    event MessageReceived(bytes32 indexed channelId, bytes sender, bytes messageData);
    event ResponseReceived(bytes32 indexed channelId, uint64 messageId, uint8 status, bytes responseData);

    constructor(address _clprService) { clprService = _clprService; }

    function serve(bytes32 channelId, bytes32 connectorId, bytes calldata target, bytes calldata data)
        external returns (uint64 messageId)
    { return IClprService(clprService).sendMessage(channelId, connectorId, target, data); }

    function onClprMessage(bytes32 channelId, bytes calldata sender, bytes calldata messageData)
        external returns (bytes memory)
    {
        require(msg.sender == clprService, "only CLPR service");   // both callbacks are public
        emit MessageReceived(channelId, sender, messageData);
        return messageData;                                          // the returned bytes go in the reply
    }

    function onClprResponse(bytes32 channelId, uint64 messageId, uint8 status, bytes calldata responseData)
        external
    {
        require(msg.sender == clprService, "only CLPR service");
        emit ResponseReceived(channelId, messageId, status, responseData);
    }
}

Reply statuses. There are four: SUCCESS, APPLICATION_ERROR, CONNECTOR_NOT_FOUND and CONNECTOR_UNDERFUNDED. The last two are connector-attributable and slash, and so does a connector charge that fails after the call. The EVM ClprTypes.ReplyStatus adds REDACTED (the reply to a redacted message), CHANNEL_CLOSED and NOT_HANDLED; the pinned code defines the last two but never sets them. Treat any value beyond the four as implementation-specific.

Section 5of 23

The 28 steps, in protocol terms

Source: design §2.2 (clpr-spec@945082d)

One message, end to end, in protocol terms: twenty-eight steps, two state proofs, one reply, between a Hiero ledger on the left and a QBFT ledger on the right. Each step names the algorithm or structure it runs through; the plain narration sits above the protocol narration. The switch runs the trip the other way, where the proofs change and the rules do not.

Keep two things from it for the sections that follow. Steps 12 to 19 are one transaction on the receiving ledger: submitBundle, the verification algorithm, acknowledgement, the connector charge, dispatch and the queued response. A rejected bundle applies none of it; in an accepted one, a failed application call or connector charge becomes that message’s reply status and the rest of the bundle still commits. And steps 7 to 11 and 20 to 21 are the endpoints’ own work, re-checked the moment it comes back on chain.

Section 6of 23

The message queue and the running hash

Source: spec §1.4 · spec §4.1 · spec §4.3 · design §3.2.2 (clpr-spec@945082d)

One ordered queue per channel per direction carries three message classes in a single intermixed stream, sharing one running hash chain, one proof mechanism and one transport:

message ClprMessagePayload {
  oneof payload {
    ClprMessage        message       = 1;  // DATA: application content
    ClprMessageReply   message_reply = 2;  // RESPONSE: outcome of a Data Message
    ClprControlMessage control       = 3;  // CONTROL: protocol housekeeping (ConfigUpdate)
  }
}
message ClprMessage {
  bytes connector_id       = 1;  // keccak256(channel_id ‖ public_key ‖ salt); same on both ledgers
  bytes target_application = 2;  // destination application address
  bytes sender             = 3;  // stamped by the service from the caller; not caller-supplied
  bytes message_data       = 4;  // opaque
}
message ClprMessageReply {
  uint64                 message_id         = 1;  // the Data Message this answers
  ClprMessageReplyStatus status             = 2;  // SUCCESS | APPLICATION_ERROR | CONNECTOR_NOT_FOUND | CONNECTOR_UNDERFUNDED
  bytes                  message_reply_data = 3;
}
message ClprMessageValue {
  ClprMessagePayload payload                       = 1;
  bytes              running_hash_after_processing = 2;
}

Queue entries are stored separately from the channel, keyed by (channel_id, message_id), because they are read by id range during bundle construction and deleted after acknowledgement. On Hiero they live in a Merkle state map (directly provable); on EVM ledgers in contract storage, where gas cost makes aggressive deletion important.

The running hash

running_hash = SHA-256( previous_running_hash ‖ serialized_payload )     H0 = 0x00 × 32

serialized_payload is the canonical protobuf encoding of the ClprMessagePayload. SHA-256 was chosen for universal availability (EVM precompile, Hiero native, Solana syscall) and retains 128-bit preimage resistance under Grover’s algorithm; the fields are opaque bytes, so an upgrade needs a protocol version bump and channel renegotiation but no wire format change.

Enqueue (sendMessage)

1. Look up the channel; reject unless ACTIVE. 1a. If last_config_timestamp is behind the current configuration’s consensus timestamp, enqueue a ConfigUpdate control message first and update the timestamp.
2. Look up the connector by (channel_id, connector_id); reject if absent.
3. Call the connector’s authorization contract; reject if not authorized.
4. Check len(message_data) ≤ peer_config.throttles.max_message_payload_bytes. A stricter local limit is allowed; exceeding the peer’s is not.
5. Check next_message_id − acked_message_id < max_queue_depth.
6. Build the ClprMessage, stamping sender from the transaction caller.
7. Compute the running hash. 8. Store under (channel_id, next_message_id). 9. Set sent_running_hash; increment next_message_id.

The sender pays only the native transaction fee; there is no protocol fee on the sending side. If anything fails, “the whole thing reverts and the user pays only for the failed attempt”.

Section 7of 23

Bundles and progress

Source: design §3.2.3 · spec §2.1.2 · design §3.2.6 · ADR 2026-07-17 · ClprEvmBundleVerifier.sol (clpr-spec@945082d, clpr-smart-contracts@276c8d5)

Messages never travel individually. A bundle is an ordered batch of payloads plus one state proof over the last of them, the anchor. The proof covers the running hash at the anchor, so the receiver can verify that the whole batch exists in the sender’s state, in order, with nothing omitted, by recomputing the chain. The endpoint reads unacknowledged messages starting after the peer’s current_received_message_id; if received + 1 ≥ next_message_id the bundle carries no messages. A bundle may be a proper prefix of the backlog, so a queue larger than max_messages_per_bundle or max_sync_bytes can still drain in slices.

Progress criteria

The service rejects any bundle that satisfies none of these (NoProgress), and endpoints MUST NOT submit one:

Endpoints evaluate these against their cached view before building a bundle (the pre-check); the service re-evaluates against on-chain values after the verifier returns (step 1a). A rotation-only or manifest-only bundle with no messages is valid.

Sizing. On a ledger with a 30M-gas block the worked example is ten messages per bundle at 2M gas each, leaving room for the service’s own logic. On Hiero, limits are expressed as operations-per-second so that oversized bundles are rejected at ingest: “once a bundle starts execution, it must be able to finish”. max_message_payload_bytes is enforced on both ends, the destination’s check being authoritative.

Section 8of 23

Verifying a bundle

Source: spec §4.2 · design §3.2.5 · contracts docs/bundle-flow.md · BundleLib.sol (clpr-spec@945082d, clpr-smart-contracts@276c8d5)

This is the heart of the protocol: what a CLPR Service does, post-consensus, when submitBundle(channel_id, bundle_payload) lands. Step through it on a concrete bundle, then inject faults and watch which step rejects.

The division of labour matters. The verifier answers one question: is this payload authentically the peer’s state under the current trust anchor, and if so, what sync data, messages, anchor id and anchor hash does it contain? Everything else, progress, size, contiguity, the running hash, acknowledgements, status transitions and dispatch, is the service’s own logic and runs identically regardless of proof system. What this buys is precise: the service’s checks “catch verifier bugs but not a compromised verifier, which would return fabricated data with matching hashes”.

Two ordering rules inside the algorithm are easy to miss. The manifest update (1b) and trust anchor update (1c) are applied before any message is processed, so every message in a bundle is attributed to the authority that produced it, with no window in which two anchors apply. And the lazy ConfigUpdate (5c) is enqueued after the acknowledgement update and before any response generated by this bundle’s dispatch, pinning it to a deterministic point in the stream.

A rejected bundle changes no state and costs the submitter its fee; the one exception is a bundle with out-of-order responses, which is rejected but sets the channel to PAUSED. “Critically, a failure on one message does not stop processing of the remaining messages in the bundle.”

Section 9of 23

Response ordering and correlation

Source: design §3.2.8 · spec §4.5 · spec §4.4 (clpr-spec@945082d)

CLPR distinguishes two confirmations. An acknowledgement is transport-level: the peer’s received_message_id, reported on every sync, becomes the sender’s acked_message_id. A response is application-level: the ClprMessageReply generated when the destination processed a Data Message. Because the destination processes each inbound message sequentially, responses are generated in exactly the order the Data Messages arrived, “regardless of whether each individual response indicates success or failure”.

That ordering guarantee is what lets the source verify correlation without a separate counter. It walks its retained Data Messages in order and matches each incoming response to the next expected one. Hence the lifecycle rules: Response and Control messages in the outbound queue are deleted as soon as they are acknowledged; Data Messages are retained past acknowledgement and deleted only when their response has arrived and matched.

A mismatch is a protocol violation by the peer ledger. The service sets the channel to PAUSED, rejects the bundle outright (nothing dispatched, no acks, no hash advance), and blocks new sendMessage calls; syncs continue, and the channel auto-resumes when a correctly ordered bundle arrives. It does not slash: “you cannot slash a peer ledger, only individual endpoints”, and the out-of-order responses are already committed in the peer’s queue. PAUSED is reserved exclusively for this case; bundles that fail hashing, replay or size checks are simply rejected with no state change.

Section 10of 23

Ledger identity and configuration

Source: design §3.1.1 · spec §1.1 · spec §7 (clpr-spec@945082d)

Each ledger publishes one ClprLedgerConfiguration: its identity and the limits it will enforce on peers.

message ClprLedgerConfiguration {
  uint32        protocol_version        = 1;  // both sides MUST agree; unknown → reject
  string        chain_id                = 2;  // CAIP-2, e.g. "hedera:mainnet", "eip155:1"
  bytes         service_address         = 3;  // this ledger's CLPR Service (contract addr / well-known constant)
  Timestamp     timestamp               = 4;  // consensus time of the last change; monotonic
  ClprThrottles throttles               = 5;
  bytes         initial_trust_anchor    = 6;  // e.g. Hiero ledger_id; empty if derived from a separate proof
  bytes         initial_trust_anchor_id = 7;  // non-empty iff initial_trust_anchor is non-empty
}

Identity is a compound key. chain_id is a CAIP-2 string, but it does not uniquely identify a CLPR Service: two competing service contracts on Ethereum can both claim eip155:1. A peer is therefore identified by (ChainID, ClprServiceAddress). Private networks may self-assign an unregistered namespace such as hashsphere:acme-prod.

Protocol version is bumped on any backward-incompatible change: new control message variants, running hash algorithm, signature schemes, wire format. Cross-version messaging is not supported; a peer that receives a ConfigUpdate with an unrecognized version rejects it, halting the channel until it upgrades.

Throttles are ledger-wide values advertised to all peers and enforced per channel:

Strictness. Every limit is published, so exceeding one is “a measurable, attributable violation”. Implementations MUST reject unrecognized fields, unknown message types and malformed metadata outright rather than skipping them. Defaults for the main throttle values are still to be fixed (the spec marks them TBD); clprEnabled defaults to false and is checked dynamically on every call, giving each deployment a runtime kill switch.

Section 11of 23

Channels

Source: spec §2.1 · spec §5.1 · design §3.1.3 · contracts docs/lifecycle.md (clpr-spec@945082d, clpr-smart-contracts@276c8d5)

A channel is the on-ledger record of one peer relationship. Its state is presented as a single structure, while allowing implementations to split it for efficient state proofs:

Channel {
  channel_id             : bytes(32)   // primary key; same value on both ledgers
  chain_id               : string      // CAIP-2 id of the peer
  peer_config_timestamp  : Timestamp   // last known peer configuration
  verifier_contract      : bytes       // immutable after registration
  verifier_fingerprint   : bytes       // code hash at registration (informational)
  trust_anchor           : bytes       // peer signing authority; only verifyBundle may change it
  trust_anchor_id        : bytes       // opaque id for trust_anchor
  channel_context        : ChannelContext { channel_id, service_address }   // immutable
  endpoint_manifest      : ClprEndpointManifest   // cached peer endpoints (+ version)
  last_config_timestamp  : Timestamp   // for lazy ConfigUpdate propagation
  acked_message_id       : uint64      // highest own message confirmed received by peer
  sent_running_hash      : bytes(32)
  received_running_hash  : bytes(32)
}

Three fields are deliberately not on the Channel: status, received_message_id and next_message_id. Each side keeps them in its own ChannelSyncData, which is state-proven and exchanged on every bundle. Wherever a rule says Channel.status, read it as this side’s own ChannelSyncData.status. An ADR moved these fields out so that proofs carry the minimum, not the whole record.

Initial values. acked_message_id = 0; both running hashes are 32 zero bytes; received_message_id = 0; next_message_id = 1. The first Data Message ever enqueued has ID 1 and the first Response Message received must reference it.

Registration: commit, then reveal

Because the same channel_id must be claimed on both ledgers, an attacker who watches a registration on A could race to claim the id on B. The commit-reveal scheme hides both the id and the key until both claims exist. The ownership commitment is keccak256(channel_id ‖ public_key); keccak-256 is fixed cross-platform, while the signature scheme and key encoding are platform-specific (ECDSA secp256k1 or Ed25519 today; “extensible for post-quantum”). Different keypairs may be used on each ledger; the channel id, not the key, ties the two sides together.

At the reveal (completeChannel) the service verifies the commitment preimage and a signature over keccak256(channel_id), then calls the verifier’s verifyConfig(config_proof_bytes, channel_id, endpoint_manifest_proof_bytes). The verifier returns the peer’s verified chain_id, config timestamp and throttles, the immutable ChannelContext, the initial_trust_anchor and its id, and the peer’s initial endpoint manifest (version ≥ 1; an empty endpoint list is valid). All of it is stored and the channel becomes ACTIVE. The registrant has no privileges afterwards; “the keypair used for registration exists solely to coordinate cross-ledger registration”.

The simulation’s “reference implementation” note lists where the EVM contracts bind these rules to the platform (a derived channel id, 64-byte keys, an EIP-191 signature domain).

Lifecycle

The subtleties are in the closing states. From ACTIVE or PAUSED, closeChannel (admin only) moves to CLOSING: sendMessage is rejected, but inbound Data Messages are still dispatched and answered, and inbound responses are still delivered. CLOSING becomes DRAINED when no Data Message with an id above acked_message_id remains in the outbound queue; responses generated during CLOSING may still be in flight and drain through DRAINED. DRAINED becomes CLOSED when an inbound bundle carries the peer’s status DRAINED or CLOSED and acked_message_id ≥ next_message_id − 1. The peer’s status travels in ChannelSyncData.status on every sync, which is how one side’s close propagates to the other. PAUSED is different in kind: it is entered automatically on a response-ordering violation and exits automatically when a correctly ordered bundle arrives; the admin cannot resume it, only close it.

Verifier immutability. Fixed for the channel’s lifetime so that “applications can evaluate a Channel’s verifier once and know it will not change underneath them”. If a source ledger upgrades its proof format, a new channel is registered with a new verifier and applications migrate. One caveat: the verifier address being fixed does not stop the verifier being an upgradeable proxy: check who holds the upgrade key.

Multiple channels per pair. Channels are keyed by id, not by peer, so several can target the same service: for instance one per Ethereum commitment level (latest, safe, finalized), each with its own verifier and its own independent queue. Applications choose at send time.

Section 12of 23

Endpoints and manifests

Source: design §3.1.2 · spec §1.2 · spec §2.4 · spec §6.5 · ADR 2026-07-03 (clpr-spec@945082d)

An endpoint is an off-chain node that runs the sync protocol, obtains proofs, pre-verifies and submits bundles. Two manifests describe them.

The local manifest (ClprEndpointManifest) is service-level state: an ordered list of ClprEndpoint entries, a version counter starting at 1 and incremented on every change to the set, and the service_address it belongs to. An entry holds an optional ServiceEndpoint (numeric IP and port; omitted by private networks that only dial out) and a tls_certificate: a DER-encoded, self-signed ECDSA P-384 CA certificate, minimized (single-RDN DN, minimal serial, only basicConstraints and keyUsage) and at most 512 bytes, rejected at admission otherwise. That CA is never presented on the wire; each endpoint mints an in-memory Ed25519 leaf signed by it at process start, presents the leaf at every mTLS handshake, and regenerates it on restart or after leaf_certificate_validity_seconds (default 86 400).

How endpoints get into the local manifest depends on the platform:

• Hiero: every consensus node is automatically an endpoint. The manifest mirrors the roster; a node joining, leaving or rotating its identity bumps the version, stake-weight-only changes do not. No manual administration is required or permitted.
• Permissionless ledgers (EVM): the admin decides. Anyone may call registerEndpoint(endpoint_data, bond) and enter pending, with a bond whose minimum the platform specification defines; the admin calls addEndpoint to admit it to the live manifest, or to add an endpoint directly with no bond (updateEndpointManifest does either for a batch, one version bump for the whole batch). removeEndpoint by the endpoint or the admin returns the bond in full. Endpoint bonds are never slashed; misbehavior means eviction with a refund. Slashing applies only to connectors.

The peer manifest is stored per channel as Channel.endpoint_manifest: the authoritative directory of remote endpoints to dial. It is populated at completeChannel from the manifest proof passed to verifyConfig, truncated to max_peer_endpoints, and refreshed whenever verifyBundle returns a new_endpoint_manifest with a higher version, replacing the whole manifest atomically (verification step 1b).

Bundle submission is permissionless and orthogonal to manifest membership: anyone may submit a bundle that makes progress, whether or not they registered, and the bond plays no role in reimbursement. Sybil resistance on permissionless ledgers is “provided primarily by admin curation”; the bond is “commitment friction”, not a threshold calibrated against attack cost. Peer selection should incorporate randomization, and endpoints SHOULD prefer peers that reciprocate with messages of their own, which “cannot be faked — providing a valid bundle with messages requires having actual messages to send”.

Seen from the endpoint’s side, the whole job is a loop: watch the home queue and the peer manifest, open a stream per channel, ask for what is missing, dry-run what arrives, submit only what would pass.

Section 13of 23

The sync protocol

Source: spec §1.5 · design §3.1.4 · ADR 2026-07-14 (clpr-spec@945082d)

In the specification, every endpoint exposes one gRPC service with one method:

service ClprEndpointService {
  rpc sync(stream ClprSyncPayload) returns (stream ClprSyncPayload);
}

message ClprSyncPayload {
  bytes          channel_id      = 1;  // exactly 32 bytes
  BundleRequest  bundle_request  = 2;  // absent when nothing more to request
  BundleResponse bundle_response = 3;  // absent when carrying no bundle
}
message BundleRequest {                // UNPROVEN: shapes the peer's bundle, never changes state
  uint64            current_received_message_id       = 1;
  ClprChannelStatus current_status                    = 2;
  bytes             current_trust_anchor_id           = 3;
  uint64            current_endpoint_manifest_version = 4;
}
message BundleResponse { bytes bundle_payload = 1; }   // opaque; for the verifier

A sync cycle is one bidirectional stream scoped to a single channel. Each side sends a BundleRequest describing its own state; the responder builds a minimal bundle starting at current_received_message_id + 1, or at its own acked_message_id + 1 if the claim names a message it has not sent yet; a payload with both fields absent closes the stream. The connection and its TLS session may persist across cycles.

Three properties to internalize. The request is unproven and “MUST NOT cause a state change”: a stale or under-claiming request at worst produces duplicates that the replay defence rejects, costing bandwidth and a fee, never correctness, and an over-claim only delays messages the requester still needs. Each bundle is shaped by the receiver’s request: the responder starts from the state the receiver reports in the same stream, not from a cached view of it. And endpoints MUST pre-verify by executing the verifier locally before submitting, “otherwise the endpoint will have to pay for invalid payloads that fail verification post-consensus”.

The reason: the earlier single-call sync computed bundles from a cached view of the peer’s acknowledgements one cycle stale, so in steady state delivered messages were sent again, roughly halving effective bundle throughput. Sync cadence is intentionally unspecified: “an empirical tuning question, not a protocol-level constant”.

Private networks simply omit service_endpoint from their manifest entries; their endpoints are then the only ones that can initiate. Close-notification: when a channel reaches CLOSED locally, the endpoint’s terminal obligation is to keep submitting one final bundle carrying status = CLOSED to the remote until it is accepted or rejected as already closed.

Section 14of 23

Verifiers and trust anchors

Source: spec §3.1 · spec §3.2 · design §3.1.5 · verifiers/ · HieroVerifier.sol · QBFTVerifier.sol · ADR 2026-07-02 (clpr-spec@945082d, clpr-smart-contracts@276c8d5)

A verifier implements two read-only methods. It holds no per-channel state: mutable trust material comes in and goes out through the trust_anchor parameters, and constant identity through ChannelContext.

struct ChannelContext { bytes channel_id; bytes service_address }   // immutable per channel

interface IClprVerifier {
  function verifyConfig(bytes config_proof_bytes, bytes channel_id, bytes endpoint_manifest_proof_bytes)
    returns (ChannelContext ctx, string chain_id, uint96 peer_config_nanos, ClprThrottles throttles,
             bytes initial_trust_anchor, bytes initial_trust_anchor_id, ClprEndpointManifest endpoint_manifest)

  function verifyBundle(bytes bundle_payload, bytes trust_anchor, ChannelContext ctx)
    returns (ChannelSyncData sync_data, ClprMessagePayload[] messages,
             uint64 anchor_message_id, bytes anchor_running_hash,
             bytes new_trust_anchor, bytes new_trust_anchor_id, ClprEndpointManifest new_endpoint_manifest)
}

verifyConfig runs once, at completeChannel; it MUST revert if any proof fails, if the manifest’s service_address does not match, or if the manifest version is 0, and MUST NOT revert merely because the endpoint list is empty. verifyBundle runs on every submission and “is responsible for validating that the bundle data belongs to the (trust_anchor, ctx.service_address, ctx.channel_id) triple”; hash chain, ordering and replay are the service’s job. EVM verifiers SHOULD fail fast on malformed input before expensive cryptography. ChannelContext exists for two reasons: EVM and QBFT verifiers need the channel id and peer service address to derive the storage slots they prove, and without them a valid Hiero proof for one channel could be passed off as another’s when both trust the same ledger_id; the running hash catches that except in a narrow window at the start of a channel’s life, which ADR 2026-07-02 addresses. It is kept apart from the trust anchor because identity must not live in a field designed to rotate.

Trust anchors and rotation

The trust anchor is opaque to the service: “it stores, passes, and replaces the anchor, but never inspects its contents.” It is initialized from verifyConfig and changes through exactly one path, a non-empty new_trust_anchor returned by verifyBundle, applied atomically before any message in that bundle. No admin key, governance call or ConfigUpdate can set it; only the channel’s verifier, by accepting a proof, can move it, and a verifier behind an upgradeable proxy can change what it accepts. A verifier that returns a new anchor without a state-proven commitment in the same proof MUST revert; that requirement is what prevents anchor injection by a compromised endpoint.

The endpoint carries the obligation to keep the remote anchor current. Every sync payload reports the peer’s trust_anchor_id; the endpoint keeps a local ordered record of authorities it has seen and, when it cannot produce proofs the remote would accept, submits transition bundles until it can. Whether timing is tight depends on the anchor’s encoding: a single-authority anchor must be advanced exactly at the boundary, while a window anchor (current, next) decouples submission from the rotation and is recommended for proof systems with frequent, predictable rotations such as Ethereum’s roughly 27-hour sync committee. A proof system that cannot produce a proof verifiable by the old authority and committing to the new one “cannot support the CLPR trust anchor model”.

The two production verifiers

Both are documented under verifiers/ in the specification repository, which also prescribes the three files (state_proof.md, verifier_contract.md, trust_anchor.md) any new chain must add. The contracts repository additionally carries verifier code for other proof families (Ethereum beacon BLS, Sei/CometBFT, an Avalanche mock) which have READMEs in the contracts repository but no specification in clpr-spec and no stated maturity.

Section 15of 23

Connectors, payment and slashing

Source: design §3.3 · spec §2.2 · spec §3.3 · spec §4.6 · spec §6.3 · BundleLib.sol (clpr-spec@945082d, clpr-smart-contracts@276c8d5)

The messaging layer moves bytes; the payment layer decides who pays. A connector is a contract registered on a specific channel with a counterpart on the peer ledger under the same derived identity:

connector_id = keccak256( channel_id ‖ public_key ‖ salt )      // salt defaults to 32 zero bytes

Connector {
  connector_id       : bytes(32)   // primary key with channel_id
  channel_id         : bytes(32)
  connector_contract : bytes       // authorization contract on this ledger
  admin              : bytes       // can top up, adjust, shut down
  balance            : uint        // pays for inbound execution
  locked_stake       : uint        // slashable
}

Registration mirrors channels: commit keccak256(connector_id ‖ public_key), then reveal (public_key, salt, signature over keccak256(connector_id ‖ service_address), connector_contract, initial_balance, stake); the service re-derives the id and checks the commitment. On Hiero, service_address is the system contract 0x…016e. Storage is keyed by (channel_id, connector_id), so a squatter on some third ledger affects only channels there. The relationship is many-to-many, and the requirement is bilateral: a connector registered only on the source side authorizes messages that then fail on the destination with CONNECTOR_NOT_FOUND.

Authorizing

interface IClprConnectorAuth {
  function authorizeMessage(bytes sender, bytes target_application,
                            uint64 message_size, bytes message_data) returns (bool authorized)
}

Returning true is a commitment: “it asserts that its counterpart on the destination ledger has sufficient funds to pay for execution, and that it itself can cover the cost of handling the response. This commitment is the contractual basis for slashing.” A pass-through connector accepts everything; a sophisticated one enforces allow-lists, rate limits or payment from the application. The call MUST NOT modify service state.

Paying

On the destination, each Data Message’s connector_id is resolved to the local connector. If it exists and can pay, it is charged actual_gas_used × (1 + margin_percent / 100), and the entire amount goes to the account that submitted the bundle: no treasury, no owner cut, nothing to the sending side. Response Messages are charged the same way on their way home. Then the application is called.

Slashing

Penalties may escalate from a fine to a ban with forfeited stake; the schedule is left to platform specifications. Two acknowledged gaps: the destination submitter is uncompensated when no connector exists at all, and endpoints are paid only on the receiving side, so pure senders face a free-rider problem mitigated by peer preference rather than payment.

Section 16of 23

Recovery scenarios

Source: design §5 · spec §9 (clpr-spec@945082d)

R1, R3 and R9 share one mechanism, the proven manifest submitted directly as a bundle, which the figure in section 12 draws as the third refresh path. R5 and R6 may leave in-flight messages UNRESOLVED, requiring application-level, out-of-band reconciliation; tooling for that is one of the items in the options to consider.

Section 17of 23

Security considerations

Source: spec §8 (clpr-spec@945082d)

• Strictness (8.1). Published limits make violations attributable; unrecognized fields, unknown message types and malformed metadata are rejected outright, never skipped.
• Trust model (8.2). Verifier, peer consensus, both services. No verifier allow-list exists.
• Reorg risk (8.3). Commitment level is the verifier’s property; use finalized for anything irreversible.
• Sybil resistance (8.4). Admin curation of the endpoint manifest; the bond is friction, not a threshold; no reputation system for endpoints; the admin is fully trusted not to empty the manifest.
• Reentrancy (8.5). Dispatching hands control to arbitrary code. Implementations MUST use reentrancy guards and checks-effects-interactions: all channel state updated before the application is called.

• Untrusted payloads (8.6) and no confidentiality (8.7).
• Upgradeable verifiers (8.8) are valid but shift trust to whoever holds the upgrade key.
• Upgradeable services (8.9). Endpoint proof construction depends on storage layout; uncoordinated upgrades halt all syncs. The EVM contracts are not upgradeable; their CI still diffs a committed storage-layout snapshot, because every logic module writes into the router’s layout by DELEGATECALL.
• Endpoint pre-funding (8.10). Out-of-funds endpoints are effectively offline.
• Queue monopolization (8.11). Open; platform specs SHOULD define quotas, escrow or pricing.

Misbehavior detection is strictly local: “there is no cross-ledger misbehavior reporting protocol”.

Section 18of 23

Roles, operations and four scenarios

Source: design §2.4 · design §4 · design §4.7 (clpr-spec@945082d)

Source: design §4.1 · design §4.2 · design §4.3 · design §4.4 · design §4.5 · design §4.6 (clpr-spec@945082d)

Operational rules worth pinning above your desk: removeConnector MUST NOT succeed while in-flight messages exist; endpoint signing accounts must be pre-funded because reimbursement is post-consensus; a compromised verifier is handled by advisory, admin close, patched verifier, new channel, migration, and “the window of vulnerability is between discovery and close”; a proof format upgrade follows the same new-channel path while the source keeps the old format alive long enough to migrate.

The four cross-role scenarios, as step-throughs; each step lights the roles that act:

Section 19of 23

Adding a ledger: the verifier developer

Source: design §3.1.5 · verifier specifications · organization profile · design §4.4 (clpr-spec@945082d, org-profile@528e9c0)

Four steps: deploy a CLPR Service on the new ledger; build a verifier for its proofs, including defining the trust anchor and its rotation; publish it for peers to evaluate; and let anyone deploy it and register a channel. No protocol change is needed on existing ledgers. Expanded into the eight operational steps below.

Each kind of ledger needs three short documents (state_proof.md, verifier_contract.md, trust_anchor.md) saying how its proofs are built, checked and kept current, plus a verifier that implements IClprVerifier. The verifiers that exist today, documented or as code only:

Source: Hiero state proof · Hiero verifier · HieroVerifier.sol · QBFT state proof · QBFT verifier · QBFTVerifier.sol · EthMainnetVerifier.sol · verifier README · endpoint proof types · SeiCometBftVerifier.sol · verifier README · MockAvalancheVerifier.sol (clpr-spec@945082d, clpr-smart-contracts@276c8d5, clpr-endpoint@2ccd48d)

The verifier developer is an off-chain role with no protocol identity: ledger implementers, connector operators, application developers with high-value flows and auditors all have reasons to write one. A proof format change needs a new verifier and a new channel; an upgrade key on a proxy verifier is a single point of compromise; and the protocol pays nothing for maintenance.

Section 20of 23

The reference implementations

Source: contracts docs/architecture.md · contracts README · endpoint README · design §3.1.5 · PeerSelector.java · org profile (clpr-smart-contracts@276c8d5, clpr-endpoint@2ccd48d, clpr-spec@945082d, org-profile@528e9c0)

EVM: clpr-smart-contracts

A Foundry project. ClprService.sol is an immutable router holding all state and dispatching by DELEGATECALL to five logic modules (ChannelLogic, MessagingLogic, BundleLogic, ConnectorLogic, AdminLogic) that share one storage layout (ClprServiceStorage.sol); state-mutating helpers (BundleLib, ConnectorLib, ManifestLib) take storage references, ClprProtobuf is a pure protobuf codec, and ClprTypes holds the enums, structs, custom errors and shared events. Two consequences to know before you integrate: read functions are not annotated view (call them via eth_call), and storage-layout.json is a committed snapshot that CI regenerates and diffs, because every logic module writes into that one layout. Deployment goes through a viem CLI; clprEnabled is false after deploy until an explicit enable, and when the owner is a multisig the script stops and prints the admin calls. Verifiers live under src/verifiers/: hiero/HieroVerifier.sol, which decodes the StateProof, derives the SHA-384 block root, has TSSVerifier.sol check the hinTS aggregate signature with the EIP-2537 precompiles and walks the leaf paths, with wraps/ helpers (WRAPS verification key, Poseidon, BN254); evm/qbft/QBFTVerifier.sol; and beacon-chain BLS (EthMainnetVerifier), Sei/CometBFT and a mock Avalanche verifier. Interfaces the protocol calls outward are IClprApplication, IClprConnector and IClprVerifier; the public ABI is IClprService.

The repository records its non-obvious design choices and pipeline mapping (docs/bundle-flow.md, docs/quirks.md, docs/evm-platform-spec.md). Divergences that hold in the pinned code: the hash folded as sha256(prev ‖ sha256(payload)); a REDACTED message type still present although ADR 2026-08-01 removed redaction from the spec; bundles that must run to the sender’s newest message rather than a prefix; and the platform bindings described under connectors above. Some of the docs are themselves behind the code: several items on their divergence list are fixed in it (payload size is checked against the peer’s throttles, Channel.peerThrottles is populated, cross-bundle response ordering is validated, a malformed data message gets an error reply instead of unwinding the bundle), and bundle-flow.md still describes submitBundle as gated to registered endpoints, while the pinned code is permissionless. When in doubt, the Solidity is the reference.

Hiero: the native service

On Hiero the CLPR Service is a native service inside the consensus node, reachable from the EVM at the system address 0x…016e. Its state is part of the node’s Merkle tree, which is why its queue can be proven directly. A native verification path for Hiero proofs (VerifyConfigCall/VerifyBundleCall) is documented alongside the verifiers, and verifiers for other ledgers are contracts deployed to Hiero. The native implementation lives in the hiero-ledger/hiero-consensus-node repository.

The endpoint: clpr-endpoint

A standalone Java 25 relay for EVM ledgers, built with Gradle from seven modules: protobuf/PBJ types, core domain types, a Helidon gRPC server, an outbound gRPC client, EVM interaction over JSON-RPC, sync orchestration and peer management, and the application entry point. It serves two listeners: an always-plaintext info port (default 9546) for chain-verifiable public data, and the sync data plane (default 9545), plaintext by default and mandatory mTLS when enabled, minting the Ed25519 leaf from the operator’s P-384 CA key exactly as specified. The reference endpoint still serves and calls the earlier unary sync (one ClprSyncPayload each way, no BundleRequest); the streaming cycle described in the sync section is the specified behaviour. Local networks are declared with a proof type (QBFT, or CometBFT for Sei); Hiero appears only as a channel’s peer proof type. The maxMessageSize default is 1 MiB, and the config comments warn that the PBJ default of 10 KiB “is too small for production payloads”. Its QbftBundleConstructor builds the RLP 5-tuple (7 items with a manifest proof), AccountTransactionSubmitter previews each submitBundle with eth_call before paying, and HieroProofCodec parses proofs the Hiero node produced. The repository’s docs/ folder is the map: architecture.md (the seven modules, the app → sync/grpc/evm → core → proto dependency direction, the core abstractions TransactionSubmitter, ContractStateReader, BundlePayloadCodec, BundleConstructor, PeerSyncClient, PeerEndpointCache, CommitmentLevel), sync-protocol.md, evm-integration.md (the contract surface it calls, EIP-1559 submission, nonce handling, and why it polls getChannel instead of subscribing to events), multi-chain-design-changes.md (the three-tier local-network → service → channel hierarchy and the checklist for adding a chain type) and configuration.md. Some of those documents describe work in flight, for instance a stub bundle constructor, so read them against the pinned code. Outbound: a per-channel state-change poller notices nextMessageId advancing, the channel’s sync task reads the new messages and builds a payload, a peer is picked at random, weighted by past successes, with failing peers backed off, and the peer’s sync RPC is invoked. Inbound: the peer’s bundle is decoded; for EVM-format bundles, messages the local ledger already accepted are trimmed so a duplicate cannot sink the bundle as a replay (a Hiero proof is submitted whole); and the submitter signs and sends submitBundle client-side, polling for the receipt.

Section 21of 23

How the specification evolves

Source: ADR guide · options to consider (clpr-spec@945082d)

The text comes in two parts. The design document (clpr-service.md) explains the reasoning: the problem, the layers, the participants, the trust model, and what happens in each failure. The protocol specification (clpr-service-spec.md) is the normative part every implementation is measured against: the exact bytes on the wire, the on-ledger state, the step-by-step algorithms, and a language-independent description of every operation a service offers. Next to them sit one folder per proof system under verifiers/, the decision records under ADR/, and the list of options under consideration.

Three rules govern change. Any change to the bytes that travel between ledgers raises the protocol version, and two ledgers must agree on it or stop talking. Data an implementation does not recognize is rejected, never skipped. And the EVM contracts keep a written list of where they still differ from the text.

Decisions that change the specification are recorded as Architecture Decision Records, named YYYY-MM-DD-short-title.md, with a fixed final form: an abstract ending in an enumerated “Changes in this ADR”, a problem description per discrete problem, the options considered and non-goals, the complete solution and the tests that check it, plus optional appendices for line-by-line spec patches and implementation notes.

Only final-form ADRs are meant to be committed to main. Five are there; the newest, 2026-08-01, follows the final form, and the four earlier records use an older layout:

A separate document lists thirteen options to consider, not yet decided: application-level clawback, migrating messages between channels (three approaches compared), graceful connector wind-down, reconciliation tooling for UNRESOLVED messages, multiple proof formats per channel, the admin incentive gap, verifier developer sustainability, channel-creation anti-griefing, connector deregistration on PAUSED channels, indefinitely PAUSED channels, post-quantum endpoint signing keys, SHA-384 for the running hash, and cross-ledger propagation of endpoint signing keys. If you are looking for somewhere to contribute, that list is the map.

Section 22of 23

Governance and the lab

Source: governance/teams.yml · Labs charter · organization profile · governance/GOVERNANCE.md (governance@1447ae0, org-profile@528e9c0)

CLPR is incubated as a lab of LF Decentralized Trust, a Linux Foundation project. The signed Labs charter, kept in the lab’s governance repository, fixes the rules every lab operates under:

• Oversight by the foundation’s Technical Advisory Council (TAC), which approves project proposals, including incubation and deprecation, organizes and removes sub-projects, and approves the processes for contributing.
• Licensing. Inbound and outbound code under Apache License 2.0, every new inbound code contribution carrying a Developer Certificate of Origin sign-off; specifications under the Community Specification License 1.0; documentation under CC BY 4.0. Exceptions need a two-thirds vote of the entire TAC. Files should carry SPDX identifiers.
• Copyright in new contributions stays with its holders, and no contributor is required to assign it. Project trademarks are transferred to LF Projects, LLC, which holds them for the project; the Hedera Governing Council undertook to donate the CLPR brand and trademark to LFDT once the lab was accepted.
• Openness. Participation cannot be refused on any basis that is not reasonable and non-discriminatory, and “the output of all Project discussions, proposals, timelines, decisions, and status should be made open and easily visible to all”.

The mission of the Labs project is “to support development of very early open projects”.

Inside the lab, every team and its rights on each repository are defined in teams.yml, and a change to a role or team is a pull request against that file referencing a governance issue. Anyone who contributes is a Contributor and needs no team. Committers are per repository: the spec, smart-contracts and endpoint repositories each have a <repository-name>-committers team with write access. One clpr-maintainers team, with maintain rights on every repository, takes the decisions that affect the whole organization, including creating repositories and adding or removing Committers and Maintainers. General teams cover release engineering (clpr-release-engineers), security (security-maintainers) and foundation staff (lfdt-staff, admin on .github and governance). Decisions aim for consensus; otherwise the Maintainers vote, in the weekly call when more than half of them are present or asynchronously over 14 days, and a vote passes when more Maintainers vote for it than against it.

The lab’s scope: collaboration on the specification, the reference implementations of service, verifiers and endpoints, application development, and native integrations into other ledger types.

Section 23of 23

Glossary

Source: design §2.1 (clpr-spec@945082d)

Plus a few terms that only appear on this page: anchor message, the last message in a bundle, whose running hash the state proof covers; acknowledgement, the peer’s received_message_id as reported in ChannelSyncData, distinct from a response; close-notification, the final bundle an endpoint owes the remote once its side reaches CLOSED; transition bundle, a bundle whose proof advances the trust anchor, possibly carrying no messages; NoProgress, the rejection of a bundle satisfying none of the five progress criteria; HashSphere, a private or permissioned network running Hiero; CAIP-2, the namespace:reference chain identifier standard used for chain_id.