Protocol vocabulary

Every glowcap session uses a small vocabulary from the OCapN specifications. Concepts explains how the parts work together, and the protocol diagrams draw the flows.

The operation and descriptor names below are checked against the Syrup codec. In the tables, 1.0 means CapTP 1.0, the version Goblins speaks, and Next means glowcap-next, the profile tracking newer draft operations.

Operations

An operation (op:...) opens or ends a session, makes a call, settles a promise, or releases references.

MessageWhat it does
op:start-sessionOpens a session. Each side announces its location and session public key, with a signature over the location.
op:deliverCalls a method on a reference. Next has separate resolver and listen-mode operands. The optional answer position enables pipelining. On 1.0, omitting both answer and resolver makes a one-way send.
op:deliver-onlyNext sends a message without requesting a result.
op:resolveSettles an answer to its value or a break. glowcap never sends it to a live peer: CapTP 1.0 settles through the resolver below, and glowcap-next through its inline subscription or op:listen. The codec reads and writes it for the reference fixtures.
op:listenRequests a notification when a promise resolves.
op:abortEnds the session with a typed reason. A refused handshake is answered the same way, before the session ever opens.
op:getOn 1.0, reads a named field of an answer without waiting for the whole result.
op:indexOn 1.0, reads one item of an answer by position.
op:untagUnwraps a tagged value read from an answer. glowcap accepts it on every 1.0 session and sends it only when the partner advertises the untag feature, so a silent Goblins peer never sees one.
op:gc-exportsTells the peer that some exported references have been released, so it can drop them.
op:gc-answersTells the peer that some answers can be discarded, so it can release them.

How a promise settles

On a CapTP 1.0 session, a caller that wants an answer passes a resolver with its op:deliver: a reference the callee calls back. The answer returns as another op:deliver to that resolver, carrying ['fulfill <value>] or ['break <error>]. Goblins and glowcap both settle promises this way.

glowcap-next tracks the draft’s operation contracts while keeping the shared Goblins-compatible hello and crypto formats. A call carries its resolver and a listen mode inline: mode 1 requests shortening (later messages to the promise go straight to what it resolves to), and mode 3 requests shortening or settlement. A separate op:listen can add a mode-2 settling subscription after mode 1. Notifications use op:deliver-only. Next refuses op:get, op:index, and op:untag, which exist only on 1.0.

What a CapTP 1.0 peer sees from glowcap

A Goblins peer, or any other CapTP 1.0 implementation, sees plain CapTP 1.0 over Syrup. glowcap’s preferences travel as three hints on the location its op:start-session signs: glowcap/captp-version, glowcap/codec, and glowcap/features. A peer that doesn’t know them ignores them, and the session uses the 1.0 baseline. The version and codec hints for glowcap’s own tracks also name the exact wire a build writes, so two glowcap builds that write it differently use the 1.0 baseline. Goblins refuses a hinted onion address, so over Tor glowcap sends hints only to a partner it already knows is glowcap. With anyone else, an onion session runs the baseline.

glowcap sends op:untag only to a partner that lists the untag feature. Application code uses the same call API under either version. session.listen accepts a live far object on 1.0 but only a far promise on glowcap-next.

Reference descriptors

A descriptor (desc:...) names a reference or a handoff inside a message: what a slot points at.

DescriptorWhat it names
desc:exportA reference back to an object the receiver exports: how the sender names something it received in a preceding message (position 0 is the bootstrap object).
desc:answerA reference to a pending answer from a preceding op:deliver, the target of promise pipelining.
desc:import-objectAn object the sender hosts and is introducing. The receiver records it as an import.
desc:import-promiseA promised reference the sender is introducing, settled later when the sender resolves it.
desc:handoff-giveThe gifter’s half of a three-party introduction: “go meet this peer, on my word.”
desc:handoff-receiveThe recipient’s half of that introduction, redeemed with the third party.
desc:sig-envelopeA signed wrapper that makes a handoff unforgeable as it crosses between the three parties.

Locators

A locator (ocapn-...) gives a peer’s address and, for a sturdyref, the object to fetch from it. The designator inside it is the peer’s name on its transport: an iroh node id, a public key for Noise and keyed transports, a Tor service id, or a host:port for testing-only tcp. A locator rides inside op:start-session as the location each side announces, and travels as an argument when one peer hands another a long-lived reference to bring back to life later. The ocapn:// URI you paste into a config is one of these records, in text.

LocatorWhat it addresses
ocapn-peerA peer’s location: its transport (iroh, noise-tcp, tcp, and the rest), the designator to reach it at, and any connection hints. An ocapn://<designator>.<transport> URI is this record.
ocapn-sturdyrefA peer location plus a swiss number: a restorable, long-lived reference to one object, the thing an ocapn://…/s/<swiss> URI names.

Reserved characters inside a designator are URI-encoded, so a tcp peer’s host:port shows %3A where the colon is. The first two examples are sealed (iroh and noise-tcp), and plain tcp is testing-only:

ocapn://<64 hex chars>.iroh
ocapn://<64 hex chars>.noise-tcp?direct-addresses=127.0.0.1%3A9099
ocapn://127.0.0.1%3A46659.tcp

The id locator bundles several such routes under one durable key. Multi-home peers covers it.

Transports lists what a locator can name, and Codecs compares the wire encodings.