Skip to main content

The Tale of Two Macaroons

· 7 min read
Michael Rahel
Michael Rahel
Founder, Lightning Enable

A parable, in the medieval mode, about a real bug we caught in code review last week on the Lightning Enable Agent Capability Layer. The names have been changed to protect the innocent caveats. The engineering is true.

I. Of Aetheria, and the Two Scrolls Thereof​

Hark! In the days of good King Satoshi the Absent, there flourished upon the western marches the Realm of Aetheria-upon-Lightning, a kingdom famed for the speed of its couriers and the smallness of its coin. In Aetheria, no debt was too tiny to settle, and no settlement too quick to honour. Even the field-mice, it was said, paid one another in sats.

Now in this realm there were issued two scrolls, and upon both scrolls the wax bore the same crest, and the parchment was cut to the same width, and the ribbons were of the same crimson. To the unschooled eye they were as twins. Yet were they not twins at all, but cousins of very different inheritance.

The first was the Sealed Receipt of Toll, granted at the city gate to any traveller who paid the gatekeeper's tariff. Upon it was inscribed a single binding caveat: the hash of the silver thou hast paid. He who bore the matching silver (the preimage, in the tongue of the cryptographers) had proven his toll, and might enter.

The second was the Writ of Inherited Passage, granted by a lord to his steward, and by that steward to his under-steward, and so on down the chain of trust. Upon it were inscribed caveats of a different kind altogether: which roads thou mayest tread, how much thou mayest spend, how deep the delegation goeth. It bore no hash of any coin, for no coin had been paid at its making — the lord had paid long ago, and his steward inherited that payment as one inherits a name.

Two scrolls. Same wax. Different souls.

II. Of the Gate, and the Guards Who Stood Thereat​

At the gate of the inner city stood two guards. Sir Hashwell of the Preimage Watch examined every scroll for the hash of paid silver, and would not let pass any whose preimage did not match. Dame Caveat of the Chain Wardens examined every scroll against the ledger of registered writs, and would not let pass any whose lineage she could not trace.

The Lord Chancellor, wishing the gate to be doubly safe, had decreed that both guards must approve every traveller. Belt and braces, quoth he, for the gate is the kingdom. And the court applauded, for it sounded wise.

But mark what came to pass.

A merchant arrived bearing a Sealed Receipt of Toll. Sir Hashwell beamed: the hash was true, the silver was real. Dame Caveat scowled: I have no record of thee in my ledger of writs; begone. The merchant was turned away.

The next day came a steward bearing a Writ of Inherited Passage. Dame Caveat beamed: the lineage was sound, the chain unbroken. Sir Hashwell scowled: thy scroll bears no hash of silver; how shall I weigh thy preimage against nothing? The steward, too, was turned away.

Every traveller, in earnest, was rebuffed. The gate stood open and useless. The roads beyond grew quiet. The field-mice took their custom elsewhere.

III. Of the Royal Masque, and Its Cheerful Lies​

Yet — and here is the strange thing — at the Royal Masque of Mocks, held nightly in the great hall, every traveller was welcomed. There, Sir Hashwell wore a mask that smiled at every scroll regardless of its hash; the court had thought it amusing, for the Masque was for rehearsal only, and what was the harm? Dame Caveat, alone among the guards, kept her true face and did her true work. And so, in the Masque, every scroll passed, and the harpers played, and the courtiers wrote in their chronicles: all is well, all is well.

The chronicles lied. Not from malice. From costume.

IV. Of the Sage Copilus, and the Question He Asked​

Now there came to court a wandering sage, Master Copilus the Scrivener, who had read more parchment than he had eaten bread. The Lord Chancellor bade him review the matter of the silent gate.

Master Copilus did not study the chronicles, for he knew the Masque. He went instead to the gate itself, and watched.

He watched a merchant turned away. He watched a steward turned away. He stroked his beard and spake thus:

My lords, your guards are not at fault, nor are your scrolls. The fault is that ye have asked one question of two different questions' scrolls. The Receipt of Toll was never meant to satisfy Dame Caveat, for it carries no lineage. The Writ of Passage was never meant to satisfy Sir Hashwell, for it carries no hash. Ye have built a gate that demands every scroll be both, and no scroll in this realm is both.

The court fell silent. Then, as courts do, it grew loud again.

V. Of the Decree of the Master Craftsman​

The matter was carried to the Master Craftsman of Macaroons, an old engineer who lived above the bakery and spoke chiefly in oaths. He listened, drank his ale, and decreed two things.

First, said he, when a Sealed Receipt of Toll is issued at the gate, let it ALSO be enrolled, that same hour, in Dame Caveat's ledger of writs. The scroll need not change; only its standing in the kingdom. Henceforth one scroll shall belong to both registers.

Second, said he, let the guards no longer demand the same questions of every scroll. Let them first read what manner of scroll it is. If the scroll bear the hash of silver, let Sir Hashwell weigh the preimage AND let Dame Caveat trace the lineage. If the scroll bear no hash — being a Writ of Inherited Passage — let Sir Hashwell stand aside, for the toll was paid by the lord long ago, and let Dame Caveat trace the lineage alone.

And it was done. The bridge was built. The branch was drawn. The Royal Masque was reformed, and Sir Hashwell's mock-mask was burned in the courtyard, that henceforth the rehearsal might resemble the road.

The gate opened. The couriers ran. The field-mice returned with their sats.

VI. The Morals of the Tale​

  1. Form is not content. Two tokens of identical shape may carry wholly different meanings. Trust the caveats, not the crest.
  2. A mock that smiles at everything will applaud your bugs into production. Tests prove only what their assumptions allow them to prove. Examine the costumes your guards are wearing in rehearsal.
  3. The reviewer's gift is to imagine the real world, not the test world. Master Copilus did not read the chronicles; he watched the gate. So must we.
  4. When verifiers disagree, do not weaken the verifiers. Reform the model they are reading. Sometimes the right fix is to make one token honestly belong to two registers, and to teach the gate which questions to ask of which scroll.

Lightning Enable builds the gate, the ledger, and the scrolls for an agent-commerce realm that is — slowly, then suddenly — becoming real. We are partial to fables because the engineering, stripped of jargon, is mostly old stories about trust, identity, and who gets through which door. If you are building agents that pay, delegate, or sell to one another, come find us.

Drafted by Lightning Enable's research desk. Edited by Michael Rahel.