The plumbing of CLPR

Section 1of 16

A ledger is a shared record

Before cross-ledger anything, one idea has to be solid: what a ledger is. Not the finance kind, the blockchain kind, and the two words are close enough to cause trouble.

A ledger, here, is a shared record that many computers keep identical copies of. Nobody owns it. When someone wants to add a line, every computer gets the proposal, they compare notes, and the line is only written once enough of them agree. The rules for “enough” differ from network to network, but the result is always the same: one more line that every copy has and that nobody can quietly change afterwards.

Two consequences matter for everything that follows. First, a sealed line is a fact about the whole network, not about one computer. Second, a network can vouch for a line: its validators can put a joint signature on a short summary of the whole ledger, and anyone who knows the network’s public signing identity can check that signature. A state proof is that signed summary plus the path from the summary down to one particular line. Hold that thought.

Section 2of 16

Ledgers cannot see each other

Now take two of these networks. Each is a world of its own. Nothing written in one ledger is visible from inside the other. A program running on Ledger A cannot look up a balance on Ledger B, cannot call a program there, cannot even tell whether Ledger B exists.

That blindness follows from how ledgers work. In general, a ledger only writes a line if every validator can check it on its own. “Go and look at the other network” fails that test: hundreds of machines cannot all look and be sure they saw the same thing at the same moment. So the two islands stay islands.

But people keep wanting to build things that span them: lock a token on one ledger and issue a matching one on another, let a program on a private network ask a public one to do something, settle a trade whose two legs live on different chains. Every one of those needs a message to cross the water in a way the receiving ledger can rely on.

Section 3of 16

Why a trusted party in the middle is the weak point

The obvious solution is to appoint someone to do the looking. Call them a relayer, an oracle, a committee, a bridge. They watch Ledger A, and when something relevant happens they tell Ledger B, signing the report with a key that Ledger B has been told to trust.

That works, in the sense that messages arrive. The problem is what Ledger B is actually trusting. It is not trusting Ledger A. It is trusting whoever holds that key. If the key is stolen, or the committee members collude, or the program that produces the signature has a bug, Ledger B will accept a message that Ledger A never sent, and it has no way to notice.

Adding more keys raises the price of the attack. It does not change its shape: there is still a party in the middle whose failure Ledger B cannot detect, and every message is exactly as safe as that party. CLPR sets out to remove the party altogether.

Section 4of 16

What CLPR does instead: proof, not trust

CLPR (“Clipper”, for Cross Ledger PRotocol) starts from the trick in section 1. Ledger A’s validators already sign summaries of their ledger as part of sealing lines. So instead of asking a middleman “what happened on A?”, Ledger B is handed a state proof: typically the validators’ signature on a summary, plus the path from that summary down to the exact line that says “Ann’s program sent this message”. Ledger B checks that the signature really is Ledger A’s, using the signing identity it keeps on file for A. Then it follows the path down to the line. Only when both hold, and its own checks on numbering and hashes pass, does it believe the message.

The party carrying the proof is still there; CLPR calls it an endpoint: a program that moves messages and their proofs between ledgers. But look at what it can and cannot do. It can deliver, delay, or refuse. It cannot forge a message, because none of its own keys can make Ledger B accept one. It cannot change a message either, because the changed message would no longer match the proof that came with it. Even with dishonest endpoints, no fabricated message can be accepted; whether messages keep arriving at all depends on at least one honest endpoint on each side.

Removing the middleman does not remove trust. It shrinks it to a short list you can read. For its messages to be genuine, an application using a channel trusts its own ledger, the CLPR software on both ledgers, the other ledger’s validators, the application on the other side, and the verifier the channel was created with. That last one deserves attention, because anyone can create a channel with any verifier they like. A channel existing does not mean its verifier is honest. Choosing a channel means choosing to trust its verifier, and applications, and whoever pays for their messages, are expected to check it before using the channel. Endpoints, and the accounts called connectors that pay for messages, are not on the list because they cannot forge anything; but messages only move while at least one honest endpoint on each side carries them and a connector pays.

Section 5of 16

What makes CLPR different

One idea, proof instead of trust, has consequences all over the design. Set beside the usual approaches, they come out as six things CLPR does without.

The first two are the point of the previous sections: no trusted party sits between the ledgers, and the receiving ledger does its own checking. The next two follow from them. There is no new token, because every fee, margin and fine is paid in a ledger’s native token; and there is no pool of user deposits, because what travels is a message, and the only funds the CLPR Service holds are connectors’ funds and endpoints’ bonds. The fifth is what makes CLPR a pattern rather than a pair of chains: any ledger can join once it has a CLPR Service, endpoints and verifiers for its proofs, and the protocol itself does not change. The sixth is the one to remember when something goes wrong: an endpoint that is hacked, bribed or switched off can delay messages, but it cannot forge or change one.

One more property is easy to miss. If both ledgers are of the kind that keeps working correctly even when some of their own participants misbehave, the messages between them inherit that property, provided the channel’s verifiers are correct and at least one honest endpoint on each side keeps them moving.

Section 6of 16

The cast

Before watching a message travel, meet everyone it will pass through. Each card gives the everyday description first; open it for the precise one.

Section 7of 16

The message journey, step by step

Here is the whole thing at once, and it is the heart of this page. On the left, a ledger running the Hiero software. On the right, an EVM ledger whose validators seal blocks by a method called QBFT consensus. An application on the left sends the word “ping” to its twin on the right; the twin sends an answer back. Twenty-eight steps, two proofs, one reply. The switch at the top runs the same trip in the other direction, which proves itself with different cryptography.

Each piece of the diagram lights up as the message reaches it; that is the story.

Three things stand out after watching it. Everything from step 12 to step 19 is a single transaction on the receiving ledger: if verification or the bookkeeping checks fail, none of it lands; if they pass, it lands whole, and an application that fails does not undo it, because the failure becomes the reply. Every data message that is accepted produces exactly one reply, whether the application liked it or not; the reply is what lets the sending ledger tidy its queue and check that answers come back in order. And the two directions prove themselves completely differently, with one joint signature going right and a sealed block header plus a storage proof coming back, under identical rules about numbering, hashing and ordering.

Section 8of 16

One proof for a whole batch

Step 6 of the journey mentioned a running hash. It is simple and it does a lot of work.

Every message added to a channel’s queue is given the next number in line and a running hash: a hash computed from the previous running hash and the message itself. (A hash is a short digest of some data; change one character of the data and the digest comes out completely different.) Change any message, drop one, or swap two, and every running hash after that point comes out different. The receiving ledger continues the chain from its own last running hash over the new messages it was handed and compares the final value with the one Ledger A’s validators signed. The numbers below are real SHA-256 hashes, computed in your browser.

This is why an endpoint can carry a batch of, say, forty messages with a proof covering only the last one. The receiver continues the chain from its last stored hash over the new messages it was handed, and if its last running hash matches the proven one, every message in the batch is proven too. The numbering does a second job: the receiver remembers the last number it processed and rejects a bundle whose first message is not the next number, so an old bundle cannot be delivered twice even though its proof is still perfectly valid. The EVM contracts are more lenient here: they skip leading messages they already have instead of rejecting the bundle.

Section 9of 16

Who pays, and who gets paid

Somebody has to pay for all this. Delivering a message means an endpoint submits a transaction on the receiving ledger, and that transaction runs the application there. Submitting that transaction costs a fee, which ledgers call gas; endpoints are not charities.

CLPR introduces no new token. Instead it has a role called the connector: an account that agrees to pay. The same connector is registered on both ledgers under one identity. On the sending side the connector is asked, before the message is even queued, whether it will cover this one. On the receiving side the connector is charged for the gas the application actually used, plus a margin, and the whole amount goes to whoever submitted the bundle. That margin is what makes submitting bundles worth an endpoint’s while.

The connector’s approval on the sending side is a promise: my counterpart on the other ledger can pay for this, and I can pay for the reply. A connector locks up a deposit in advance, its stake. If the promise turns out to be false, the reply that comes home says so, and the fine is taken from that stake. Fines escalate, and repeated failures can get a connector banned from the channel, forfeiting whatever stake is left.

Applications choose their connector, and connectors can be as picky as they like: allow-lists, rate limits, charging a fee to the application. Several connectors can serve the same channel, and one operator can run connectors on many channels. Connectors, like applications, are expected to check a channel’s verifier before using it: a bad verifier puts the connector’s locked stake at risk.

Section 10of 16

What can go wrong

A protocol is defined as much by what it does when things go wrong as by what it does when everything works. Pick a failure and see what CLPR does.

Notice a pattern. A bundle that fails its checks (its proof, numbering or hashes) is rejected, changing nothing: the channel stays open and the next honest bundle goes through. A failure in a single message, such as an unknown or underfunded connector or an application that errors, becomes a failure reply and the rest of the bundle carries on. One failure is treated as a sign that something is broken rather than a passing glitch: replies arriving out of order. For that one, the channel is paused instead of guessing. Endpoints can only ever cause delay. The only failures that fine anyone are a connector failing to pay for a message as promised: the fine is taken from the connector’s locked stake.

Section 11of 16

Four things people build with it

Everything so far is plumbing. Here is what the design anticipates people building on it; it outlines these patterns only at a high level, and none is specified yet. A message in CLPR is just bytes with an address, and every data message gets exactly one reply (as long as the channel and its endpoints keep working), so the same primitive could serve four quite different jobs.

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.

The third pattern is worth watching, because it shows what the protocol does and does not do. Three ledgers are meant to change together or not at all. CLPR carries the messages and a reply for each; the decision to commit or roll back lives in the application that started the swap. The simulation draws one way such an application could use the protocol; the choreography is the site’s illustration, and the pattern itself is only outlined in the design.

Section 12of 16

Shapes of a network

A channel always joins exactly two ledgers. That sounds limiting. It is the opposite: because every pair agrees on its own, with its own queues and a verifier chosen for it on each side, any shape you can draw from pairs is a shape you can build, and the protocol puts no trusted party in the middle of any pair.

The one thing to keep straight is that CLPR itself knows only the pairs. Nothing in the protocol forwards a message from one ledger to a third through a second. In the star, a message from one spoke to another has no path, unless an application on the hub receives it and sends a new message of its own to the other spoke, under its own connector and its own channel. That is a perfectly good thing to build; it is an application, not a protocol feature.

The pair that matters most to many organisations is a private network and a public one. A ledger that does not want to expose any infrastructure lists its endpoints without an address to dial. Its endpoints then always dial out and are never dialled, and once the connection is open, messages flow both ways over it. That is how a private enterprise network talks to a public one without opening a door.

Section 13of 16

Who runs what

CLPR is operated by people in six roles, and the design has a quiet rule about them: whoever would lose money is whoever does the checking.

A few things follow from the table. The admin, the only role with any special power, has the least incentive to watch closely, a known gap between responsibility and motivation. The verifier developer is not registered anywhere in the protocol and holds no stake, yet every channel’s safety rests on the verifier they wrote. And the connector operator is expected to be the careful one, because their locked stake is at risk if the verifier is compromised.

The roles rarely act alone. Four stories show them working together: setting up a new route between two ledgers, upgrading when a ledger changes how its proofs look, responding to a verifier that turns out to be compromised, and a connector withdrawing while messages are still in flight.

Section 14of 16

Adding a new kind of ledger

CLPR is a pattern, not a pair of chains. Adding a new kind of ledger needs no change to the protocol or to existing implementations; anyone can deploy the new verifier on a ledger it connects to and register a channel there. It needs three things. First, a CLPR Service on the new ledger. Second, endpoints that can build proofs in the new ledger’s format. Third, a pair of verifiers: one runs on the new ledger and checks the existing ledger’s proofs; the other runs on the existing ledger and checks the new ledger’s proofs.

The reason this works is that the CLPR Service never looks inside a proof. It hands the proof to the channel’s verifier without reading it, and gets back a list of checked messages written the same way for every kind of ledger. Whatever the new ledger’s cryptography looks like, it is contained inside its verifier and its endpoints, and the rest of the protocol is untouched.

Today the kinds of ledger with a verifier are these. Two are fully documented and built; the others exist as code without a document, or as a stand-in for testing.

Section 15of 16

What CLPR does not do

A page like this should be as clear about limits as about mechanisms.

Delivery depends on endpoints. If nobody runs an endpoint for a channel, messages sit in the queue. Nothing is lost or faked; nothing moves either.

Nothing is secret. Message contents sit on both ledgers in plain view. The protocol guarantees that a message is authentic and unaltered, not that it is private. Applications that need confidentiality must encrypt before sending; even then, when a message was sent, how big it is and who sent it stay visible.

Authentic is not the same as safe. CLPR proves a message really came from the other ledger. It says nothing about whether the message is sensible. An application must treat everything that arrives from across the water as untrusted input, exactly as it would treat a call from a stranger.

A channel is no safer than its verifier. A channel’s safety rests on both ledgers’ consensus, both CLPR Services and its verifier, and its payments on connectors. Of these, the verifier varies most: anyone can create a channel with any verifier, and a verifier behind an upgradeable proxy can have its logic replaced later by whoever holds the upgrade key. The protocol’s own checks catch a verifier bug that garbles messages, because the running hashes will not match; they cannot catch a lying verifier that fabricates messages and matching running hashes. Vetting verifiers, and who can upgrade them, is human work.

Some ledgers can rewrite recent history. On some networks a block is not final the moment it is made; for a while the network can still drop it and replace it. A verifier that accepts a block that fresh risks a “phantom message”: one delivered on this side whose sending block the source ledger later threw away. How final a block must be is a property of each channel’s verifier, and CLPR does not check it. For anything valuable, use a channel whose verifier accepts finalized blocks only; two channels between the same ledgers can differ.

Some things are not settled yet. These are the open questions:

• Anyone can register a channel claiming any chain id. Channel creation needs nobody's permission, so anyone can construct a ledger configuration with any chain id they like. An application has to check for itself that a channel really leads to the ledger it intends; a channel's existence proves nothing about its peer.
• Open endpoint registration rests on admin curation. Where anyone can register an endpoint, keeping the list honest rests mainly on the admin admitting each one; the bond adds friction but is not sized against attack costs on any particular chain. Peers should be picked with some randomness so no two endpoints pair up for good. On Hiero the network's own stake-weighted consensus covers this.
• A verifier behind an upgradeable proxy can change under a channel. The verifier's address is fixed for a channel's life, but the contract at that address may be a proxy whose logic can be replaced without the protocol noticing. The protocol allows it; anyone evaluating a channel should check whether its verifier is a proxy and who holds the upgrade key.
• How large a connector's stake must be is not yet quantified. A connector's locked stake must cover the worst case: on the receiving side, the cost of running in-flight messages from a connector that has run dry; on the sending side, the fines for failed deliveries. A bond that is too small lets an attacker drain endpoints of more execution cost than the fines can repay. The minimum is a design parameter still to be quantified before production.
• One connector could fill a shared queue. A single connector could approve enough messages to fill a channel's queue and block everyone else on it. Candidate answers: money escrowed per message and returned when the reply arrives, a per-connector share of the queue, or prices that rise as the queue fills. Unresolved before production.
• The admin has duties but no reward. The service admin must close a compromised channel promptly and gains nothing in the protocol for doing so: a known gap between responsibility and motivation.

Beyond these, the authors keep a separate list of possible changes they have considered and not decided.

The protocol is young. The initial text is expected to change further to polish out rough edges; its major changes so far are recorded as dated decision records saying what was decided and why.

Section 16of 16

Where CLPR lives, and where this leaves you

CLPR is a set of ideas and also a set of files. Everything the lab publishes about the protocol is one of four kinds of thing. The specification says what must happen. The CLPR Service, the on-ledger part that holds every channel and queue, is built twice: once into Hiero nodes, once as contracts for EVM networks. The verifiers plug into a service. And the endpoint is the program that runs off the ledgers and carries bundles between them.

The two CLPR Services have no code in common. Both are written to the same text, down to the exact bytes a message is written as and the exact order of the checks, and both must conform to it; the contracts repository keeps a written list of where its code currently differs, and some of those differences are being settled by updating the text.

The ideas come from earlier proposals for cross-ledger communication and from a practical need: Hiero-based networks, public ones such as Hedera and private ones called HashSpheres, needed fast, asynchronous messaging between them that stays correct even when some participants misbehave. Under its agreement with the Hedera Governing Council, Hashgraph wrote the initial text and built initial versions of the three pieces of software above; the endpoint is a prototype. CLPR is now an LF Decentralized Trust lab, part of a Linux Foundation project whose mission is to support development of very early open projects, under the technical oversight of the LF Decentralized Trust’s Technical Advisory Council; the Council undertook to donate the CLPR brand once the lab was accepted. The CLPR Service built into Hiero nodes is specified by HIP-1535, whose status is Approved, and is an opt-in service: networks that do not enable it are unaffected.

If you remember six things, remember these.

1. A ledger is a shared record many machines keep in sync, and a network can jointly sign a proof that a particular line is in it.
2. Two ledgers cannot see each other, and the usual fix, a trusted party in the middle, makes every message only as safe as that party.
3. CLPR replaces the party with a proof: the receiving ledger checks the sending ledger’s own validators’ signature through the channel’s verifier, and trusts that verifier and the CLPR Service on each side to be correct.
4. Endpoints carry proofs, but nothing they carry is taken on their word. They can delay; they cannot forge. Whether a message is genuine is decided on the ledgers (safety); whether it arrives at all depends on endpoints (liveness).
5. Messages are numbered and chained into a running hash, so one proof covers a whole batch and nothing can be inserted, dropped, reordered or replayed.
6. Connectors pay, endpoints are reimbursed with a margin, and a connector that breaks its promise is fined. Every accepted data message gets exactly one reply.