Skip to content

Instantly share code, notes, and snippets.

@kumavis
Created May 20, 2026 01:27
Show Gist options
  • Select an option

  • Save kumavis/0e932476dd9564235ad9648929f75f2a to your computer and use it in GitHub Desktop.

Select an option

Save kumavis/0e932476dd9564235ad9648929f75f2a to your computer and use it in GitHub Desktop.

The Three Implementation Properties

There are three properties an implementation might attempt to hold, detailed below. With Opaque Handoffs, they form a trilema (pick two of three) and trivially allow for E-Order. With Transparent Handoffs, you can get all three, but lose E-order. E-order can be re-established with the WormholeOp.

Handoff Transparency

Handoffs have a register side (OCapN: bootstrap method "deposit-gift") and a two-message redeem side (OCapN: record "desc:handoff-give" and bootstrap method "withdraw-gift").

For Opaque Handoffs, the Receiver and the Exporter cannot see what Reference is being handed off from the redeem side alone. Therefore, Handoff cannot resolve until after the register and redeem messages have been seen by the exporter.

Transparent Handoffs allow the Receiver to identify References they already have. This can be implemented by using an unique ID across vats that must be provided whener a Reference is introduced. In contrast to Swissnums, knowing this ID must not alone be authority to access the Reference.

Property Definitions

Pass-Invariance

This is the property that call arguments arrive as they were sent (eg Targets arrive as Targets).

In CapTP-of-E, Third Party References were replaced with Promises for their handoff resolution. This resulted in the "Lost Resolution Bug" where sending Maps with Third Party References as keys resulted in the keys being replaced by Promises, producing a different, incompatible Map.

Canonicalization

This is the property that there should be one local Presence per remote Reference.

This allows you to check equality between References as in the brand check pattern and use them as keys in a Map.

Timely Invocation

This is the property that received messages are invoked on receipt without waiting for any interaction with a third party.

Waiting for Handoffs in call arguments to resolve would be a violation of this property.

Property Pairings, under Opaque Handoffs

Pass-Invariance + Canonicalization

By waiting for Handoffs to resolve before invoking a message, we can ensure the call arguments are in the same form as they were sent and canonicalized, at the expense of waiting for the Third Parties to resolve the Handoffs.

Waiting for a Byzantine Third-Party can lead to a denial of service.

Pass-Invariance + Timely Invocation

We can avoid waiting for Handoff resolution by immediately creating a new Presence for the Handoff, at the cost of canonicalization. In this scenario Handoffs are opaque, so we cannot tell if we already have a canonical Presence for a Handoff Reference in the call args before Handoff resolution.

Canonicalization + Timely Invocation

We can avoid waiting for Handoff resolution and guarantee canonicalization by replacing incomming Handoffs with Promises for their resolution, at the cost of pass-invariance.

All Three Properties via Transparent Handoffs

Transparent Handoffs allow the message recipient to recognize if they already have a Presence for a Reference, allowing for existing Presences to immediately used. For new unknown References, we can create a new Presence and pipeline its messages to its Handoff Resolution. This allows for three properties: Pass-Invariance, Canonicalization, and Timely Invocation.

However, when shortcutting to known Handoffs, we lose E-Order because messages to the received handoffs are no longer queued behind the resolution of the Handoff which previously gated message delivery behind the Gifter's previous message sends. Here we can accept the weaker End-to-end Reference FIFO message ordering guarantee or pursue WormholeOp to recover E-Order.

@kumavis

kumavis commented May 26, 2026

Copy link
Copy Markdown
Author

note that when establishing a unique id under the host for a reference, a special case may be needed for specifying the reference id for answer promises

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment