Namespaces, writer policies and session keys
Every message on an app chain names a topic, such as
freight/acme/shipments. On any chain the topic is a label. On a chain sealed
with a topics: block, a topic registry in the chain’s state also decides
who may write each topic, and every member enforces it before any state machine
sees the message. Yano owns the registry, its checks and its proofs; Yano X
supplies the appchain topics commands, the clients and the composite rules.
The examples on this page follow one chain: a freight consortium whose members
share delivery records. The consortium owns the freight/ namespace, each
member company runs its own namespace below it, and Acme’s drivers record
delivery scans on freight/acme/shipments from a web app.
One topic name, used everywhere
Section titled “One topic name, used everywhere”- On every chain: Route & filter, Read & stream, Submit access, Encrypted bodies.
- With a topic registry: Who may write, Session keys, Payload rules, Composite rules.
- freight/acme/shipments → On every chain (always).
- freight/acme/shipments → With a topic registry (when sealed with topics:).
Select a box to see what the topic does there.
- freight/acme/shipments
- Every message names a topic when it is submitted:
POST /messageswith{"topic": …, "body": …}. Here, a freight consortium's chain carries Acme's delivery scans onfreight/acme/shipments. Topics starting with~are reserved for the system. - Route & filter
- The topic is a label for routing and filtering. It does not create a separate log: one chain can carry many topics, and a composite chain gives each component its topic.
- Read & stream
GET /messages/by-topic/{topic}lists finalized messages on a topic,GET /stream?topic=streams them live, and the Java client's@AppChainListener(topic = …)receives them.- Submit access
- An API key written as
key=topicA|topicBmay submit only to those topics. This controls who may use a node's REST API; the node still signs the envelope with its own member key. - Encrypted bodies
- Bodies can be encrypted with AES-256-GCM and the topic as associated data, so a key for one topic cannot open another topic's messages.
- Who may write
- The topic's policy names its writers:
open, or a threshold of writer keys. A write on a protected topic carries their signatures, and every member checks them before the message can enter a block. - Session keys
- A writer listed under
delegatecan sign a short-lived credential for a user's session key, so a browser writes without holding the writer key. - Payload rules
maxPayloadBytesand an optional CBOR schema are checked on every member, even on open topics.- Composite rules
- Admission rules of a composite chain can read
writer.kind,writer.signersandpayload.*: the verified writer and payload, after the topic policy passed.
topics:, the topic registry also decides who may write it, and every member enforces that before any state machine sees the message.- on every chain
- enforced by the topic registry
A chain gets a registry from its draft: add topics: to the chain
(./yano.sh appchain new --topics <chain>=members, or answer the wizard), with
governed membership. It is sealed into the chain’s genesis; see
configure an application. Without it, topics work
as before and anyone who can submit to a node may write any topic.
Who registers, manages and writes
Section titled “Who registers, manages and writes”- Create a namespace: Members vote, Registrars sign, Anyone claims.
- Topic registry: freight/, freight/acme/, freight/acme/shipments.
- Create a namespace → freight/ (create).
- Namespace owners → freight/acme/ (manage).
- freight/ → freight/acme/.
- freight/acme/ → freight/acme/shipments.
- Login service → Session key (credential).
- Session key → freight/acme/shipments.
- Writers → freight/acme/shipments.
Select a box to see who it is and what it may do.
- Members vote
- Each operator runs
topics approve <plan>on their own node. The namespace is created once the chain's block threshold of members has voted and the activation lag has passed. The members can always create or recover a namespace by vote, whatever else the draft allows. - Registrars sign
- Keys named in the draft sign a creation with authority
~registrars, without a vote. A registrar named by operator signs with that operator's member key; name a separate public key to keep them apart. Registrars create top-level names only. - Anyone claims
- The first claim for an unused single-segment name wins. The claim is signed by the owners it names (authority
~claim). - Namespace owners
- The owners of a namespace create entries below it, change their policies, rotate the owner set, retire entries and revoke credentials, with
topics plan,signandsubmit. Here the consortium ownsfreight/and createsfreight/acme/with Acme's operations and security keys as its owners; from then on Acme runs its own topics. A change takes effect at a later height, never retroactively. - Uncovered topics
- A topic that no entry covers follows the draft's
unregistered:setting.open, whichappchain newwrites, accepts it as on a chain without topics;rejectrefuses it withTOPIC_UNREGISTERED. Topics starting with~are system topics with their own rules. - freight/
- A namespace ends in
/and covers every topic below it. Its entry holds the owners and a policy:writers,delegate,maxDelegationMs,maxPayloadBytesand a schema. The consortium sets defaults here, such as a 4 KB payload limit, that every member company inherits. - freight/acme/
- The longest matching entry wins. A child entry can override single policy fields; an omitted field inherits from
freight/.writers: open, an emptydelegatelist andschema: noneare explicit overrides. Retirement is inherited, and a child cannot undo it. - freight/acme/shipments
- Acme's delivery scans. Every message on this topic is checked against its effective policy, on every member, before it can enter a block.
- Login service
- An application service whose key is a writer and is listed under
delegate, such as Acme's driver login behind its corporate SSO. After it signs a driver in, it signs a short-lived credential for the driver's session key and one scope. Delegation works only with a 1-of-n writer set: a credential stands in for one writer. - Session key
- A non-extractable WebCrypto key that the driver's web app makes. It signs each scan, and the write carries the issuer's credential. The credential lasts at most
maxDelegationMsand the chain's limit (one hour by default), and the owners or the issuer can revoke it. - Writers
- A service holding writer keys signs each write itself, such as Acme's warehouse system. The write needs the policy's threshold of valid signatures from the listed keys. With
writers: openanyone may write; size and schema still apply.
- app ledger member
- key holders
- registry entry
- writers
- topic
| Who | What they may do | How |
|---|---|---|
| The members, by a vote | Create a top-level namespace (create: members). Always available, also to recover a namespace whose owners lost their keys | topics init, plan, then topics approve on each node |
| Registrars, keys named in the draft | Create a top-level namespace alone (create: registrars) | topics init, plan, sign, submit |
| Anyone, first come | Claim an unused single-segment name (create: anyone) | the same, signed by the new owners |
| The owners of a namespace (k-of-n keys) | Create entries below it, change policies, rotate owners, retire entries, revoke credentials | topics plan, sign, submit |
Writers (k-of-n keys, or anyone when writers: open) | Write messages on the topic | the Java or JavaScript client |
An issuer: a writer listed under delegate | Sign short-lived credentials so users write with session keys | an application service; topics delegate for tests |
Names form a tree:
- A namespace ends in
/and covers every topic below it. The longest matching entry wins:freight/acme/can override single fields offreight/, and an omitted field inherits.writers: open, an emptydelegatelist andschema: noneare explicit overrides. Retirement is inherited, and a child cannot undo it. - A topic no entry covers follows the draft’s
unregistered:setting.open, the default ofappchain new, accepts it as before.rejectrefuses it withTOPIC_UNREGISTERED, and the chain then makes blocks only from registered topics. Topics starting with~are system topics. - Changes take effect later: a committed change activates after the chain’s activation lag (10 blocks by default), never retroactively, so every earlier message stays verifiable under the policy it was written under.
A policy has these fields:
| Field | Meaning |
|---|---|
writers | open, or threshold of keys: the signatures a write needs |
delegate | Writer keys that may issue session credentials. Only with a 1-of-n writer set |
maxDelegationMs | The longest credential lifetime; the chain’s max-delegation-ms (one hour by default) also caps it |
maxPayloadBytes | The largest payload. It applies to open topics too |
schemaCddl | An optional CBOR schema for the payload (see below) |
Some common policies:
| Use case | Topic | Policy |
|---|---|---|
| Delivery scans from drivers’ phones | freight/acme/shipments | writers 1 of [login service, warehouse system]; the login service in delegate gives drivers one-hour session keys; a schema checks tempC |
| Payments that need two officers | finance/payments/approvals | writers 2 of [three officers’ keys]; no delegation |
| Readings from plant gateways | iot/plant-7/readings | writers 1 of [the gateways’ keys]; maxPayloadBytes 512; a schema |
| Feedback from any partner | partners/feedback | writers: open; size and schema still apply |
| Scratch or test traffic | not registered | accepted with unregistered: open, refused with reject |
A write on a protected topic
Section titled “A write on a protected topic”What you're seeing: a driver's app records a delivery scan on freight/acme/shipments with a session key. Step through it, then try a “What if” to see which check stops a bad write.
- Log in A driver signs in to Acme's delivery app through the company's SSO; any login the application likes works, including OAuth or a wallet. The app makes a session key pair. The private key is a non-extractable WebCrypto key that never leaves the device.
- Issue a credential Acme's login service checks the sign-in and signs a delegation: the session public key, the scope
freight/acme/,notBeforeandnotAfter, bound to this chain and its generation. Its key is a writer of the topic and is listed underdelegate. - Write At the customer's dock the app builds a frame for
freight/acme/shipments: the payload{shipment: "SHP-1042", tempC: 4}and a proof with a fresh nonce, anotAfter, the credential and the session key's signature over the write statement. The statement binds the chain, generation, topic, payload hash, nonce and expiry. It posts the frame to any member. - Check the policy The member resolves the topic's effective policy from committed state: the longest matching entry, with omitted fields inherited. It then runs the checks in order; the first failure refuses the message with
400and a code.- passes: An entry covers the topic (or unregistered topics are open)
- passes: The entry is not retired
- passes: The body is a canonical frame
- passes: The write proof's
notAfteris inside its window - passes: The credential: allowed issuer, scope, time, not revoked
- passes: The session key signed this write
- passes: This write statement was not used before
- passes: Payload size and schema
Effective policy of freight/acme/shipmentsField Value From entry writers1 of [login, warehouse] freight/acme/delegate[login] freight/acme/maxDelegationMs3,600,000 (1 h) freight/acme/maxPayloadBytes4,096 freight/(inherited)schema tempC: -30..30freight/acme/owners 2 of [ops, security] freight/acme/ - Run the machine Only now do the state machine's own admission and any composite rules run. The machine receives the verified payload as the body; composite rules see
writer.kind=delegated, the session key and its issuer. The message id still refers to the submitted frame. - Finalize The proposer and every follower repeat the same checks against the block's parent state. A follower rejects a block that breaks them, which makes the policy a consensus rule. The write statement is recorded as used, and the delivery scan is now evidence every company in the consortium can verify.
What if: A legacy integration posts JSON
An old script posts {"shipment": "SHP-1042"} as the body, with no frame and no signature.
- Write The script posts the payload to
freight/acme/shipmentsas an ordinary body, the way it would on an unprotected topic. - Check the policy The topic has writer keys, so the body must be a canonical frame carrying a write proof. It is not.
- passes: An entry covers the topic (or unregistered topics are open)
- passes: The entry is not retired
- fails: The body is a canonical frame
TOPIC_FRAME_INVALID - not reached: The write proof's
notAfteris inside its window - not reached: The credential: allowed issuer, scope, time, not revoked
- not reached: The session key signed this write
- not reached: This write statement was not used before
- not reached: Payload size and schema
Effective policy of freight/acme/shipmentsField Value From entry writers1 of [login, warehouse] freight/acme/delegate[login] freight/acme/maxDelegationMs3,600,000 (1 h) freight/acme/maxPayloadBytes4,096 freight/(inherited)schema tempC: -30..30freight/acme/owners 2 of [ops, security] freight/acme/
What if: The credential expired
The app was offline for two hours and queued a scan without refreshing its one-hour credential.
- Log in A driver signs in to Acme's delivery app through the company's SSO; any login the application likes works, including OAuth or a wallet. The app makes a session key pair. The private key is a non-extractable WebCrypto key that never leaves the device.
- Issue a credential Acme's login service checks the sign-in and signs a delegation: the session public key, the scope
freight/acme/,notBeforeandnotAfter, bound to this chain and its generation. Its key is a writer of the topic and is listed underdelegate. - Write Back online, the app signs the queued scan with the old credential. The SDK normally refreshes the credential before it expires; this client did not.
- Check the policy The block time is past the credential's
notAfter, so the credential no longer stands in for the login service. Get a fresh credential and sign the scan again.- passes: An entry covers the topic (or unregistered topics are open)
- passes: The entry is not retired
- passes: The body is a canonical frame
- passes: The write proof's
notAfteris inside its window - fails: The credential: allowed issuer, scope, time, not revoked
TOPIC_DELEGATION_INVALID - not reached: The session key signed this write
- not reached: This write statement was not used before
- not reached: Payload size and schema
Effective policy of freight/acme/shipmentsField Value From entry writers1 of [login, warehouse] freight/acme/delegate[login] freight/acme/maxDelegationMs3,600,000 (1 h) freight/acme/maxPayloadBytes4,096 freight/(inherited)schema tempC: -30..30freight/acme/owners 2 of [ops, security] freight/acme/
What if: A write for another company
The same session tries to write freight/globex/shipments, a competitor's topic.
- Log in A driver signs in to Acme's delivery app through the company's SSO; any login the application likes works, including OAuth or a wallet. The app makes a session key pair. The private key is a non-extractable WebCrypto key that never leaves the device.
- Issue a credential Acme's login service checks the sign-in and signs a delegation: the session public key, the scope
freight/acme/,notBeforeandnotAfter, bound to this chain and its generation. Its key is a writer of the topic and is listed underdelegate. - Write The app signs a write for
freight/globex/shipmentswith the credential forfreight/acme/. - Check the policy The credential's scope,
freight/acme/, does not cover the topic. A session key can write only inside the scope it was issued for, so one company cannot write another's records.- passes: An entry covers the topic (or unregistered topics are open)
- passes: The entry is not retired
- passes: The body is a canonical frame
- passes: The write proof's
notAfteris inside its window - fails: The credential: allowed issuer, scope, time, not revoked
TOPIC_DELEGATION_INVALID - not reached: The session key signed this write
- not reached: This write statement was not used before
- not reached: Payload size and schema
Effective policy of freight/acme/shipmentsField Value From entry writers1 of [login, warehouse] freight/acme/delegate[login] freight/acme/maxDelegationMs3,600,000 (1 h) freight/acme/maxPayloadBytes4,096 freight/(inherited)schema tempC: -30..30freight/acme/owners 2 of [ops, security] freight/acme/
What if: The scan is sent twice
A retry on a flaky network, or a proxy, posts the same final frame again.
- Log in A driver signs in to Acme's delivery app through the company's SSO; any login the application likes works, including OAuth or a wallet. The app makes a session key pair. The private key is a non-extractable WebCrypto key that never leaves the device.
- Issue a credential Acme's login service checks the sign-in and signs a delegation: the session public key, the scope
freight/acme/,notBeforeandnotAfter, bound to this chain and its generation. Its key is a writer of the topic and is listed underdelegate. - Write At the customer's dock the app builds a frame for
freight/acme/shipments: the payload{shipment: "SHP-1042", tempC: 4}and a proof with a fresh nonce, anotAfter, the credential and the session key's signature over the write statement. The statement binds the chain, generation, topic, payload hash, nonce and expiry. It posts the frame to any member. - Check the policy The member resolves the topic's effective policy from committed state: the longest matching entry, with omitted fields inherited. It then runs the checks in order; the first failure refuses the message with
400and a code.- passes: An entry covers the topic (or unregistered topics are open)
- passes: The entry is not retired
- passes: The body is a canonical frame
- passes: The write proof's
notAfteris inside its window - passes: The credential: allowed issuer, scope, time, not revoked
- passes: The session key signed this write
- passes: This write statement was not used before
- passes: Payload size and schema
Effective policy of freight/acme/shipmentsField Value From entry writers1 of [login, warehouse] freight/acme/delegate[login] freight/acme/maxDelegationMs3,600,000 (1 h) freight/acme/maxPayloadBytes4,096 freight/(inherited)schema tempC: -30..30freight/acme/owners 2 of [ops, security] freight/acme/ - Run the machine Only now do the state machine's own admission and any composite rules run. The machine receives the verified payload as the body; composite rules see
writer.kind=delegated, the session key and its issuer. The message id still refers to the submitted frame. - Finalize The proposer and every follower repeat the same checks against the block's parent state. A follower rejects a block that breaks them, which makes the policy a consensus rule. The write statement is recorded as used, and the delivery scan is now evidence every company in the consortium can verify.
- Resend Anyone who has the frame can post the same bytes again, to any member.
- Check the policy Every signature is still valid, but the write statement is already recorded as used. A copy never counts twice, so a retry cannot record a delivery twice.
- passes: An entry covers the topic (or unregistered topics are open)
- passes: The entry is not retired
- passes: The body is a canonical frame
- passes: The write proof's
notAfteris inside its window - passes: The credential: allowed issuer, scope, time, not revoked
- passes: The session key signed this write
- fails: This write statement was not used before
TOPIC_PROOF_REPLAYED - not reached: Payload size and schema
Effective policy of freight/acme/shipmentsField Value From entry writers1 of [login, warehouse] freight/acme/delegate[login] freight/acme/maxDelegationMs3,600,000 (1 h) freight/acme/maxPayloadBytes4,096 freight/(inherited)schema tempC: -30..30freight/acme/owners 2 of [ops, security] freight/acme/
What if: The payload breaks the schema
A faulty app build reports the temperature in Fahrenheit.
- Log in A driver signs in to Acme's delivery app through the company's SSO; any login the application likes works, including OAuth or a wallet. The app makes a session key pair. The private key is a non-extractable WebCrypto key that never leaves the device.
- Issue a credential Acme's login service checks the sign-in and signs a delegation: the session public key, the scope
freight/acme/,notBeforeandnotAfter, bound to this chain and its generation. Its key is a writer of the topic and is listed underdelegate. - Write The app signs a correct frame whose payload is
{shipment: "SHP-1042", tempC: 39}. - Check the policy The signatures and credential are fine, but the topic's schema allows
tempConly from -30 to 30. Signatures prove who wrote a message, not that its content makes sense; that is the schema's job.- passes: An entry covers the topic (or unregistered topics are open)
- passes: The entry is not retired
- passes: The body is a canonical frame
- passes: The write proof's
notAfteris inside its window - passes: The credential: allowed issuer, scope, time, not revoked
- passes: The session key signed this write
- passes: This write statement was not used before
- fails: Payload size and schema
TOPIC_SCHEMA_REJECTED
Effective policy of freight/acme/shipmentsField Value From entry writers1 of [login, warehouse] freight/acme/delegate[login] freight/acme/maxDelegationMs3,600,000 (1 h) freight/acme/maxPayloadBytes4,096 freight/(inherited)schema tempC: -30..30freight/acme/owners 2 of [ops, security] freight/acme/
What if: Nobody registered the topic
A client writes analytics/clicks, which no entry covers, on a chain sealed with unregistered: reject.
- Write The client posts a plain body to
analytics/clicks. - Check the policy No entry covers the topic and the chain refuses unregistered topics. With
unregistered: open, whichappchain newwrites by default, the message would be accepted as on a chain without topics.- fails: An entry covers the topic (or unregistered topics are open)
TOPIC_UNREGISTERED - not reached: The entry is not retired
- not reached: The body is a canonical frame
- not reached: The write proof's
notAfteris inside its window - not reached: The credential: allowed issuer, scope, time, not revoked
- not reached: The session key signed this write
- not reached: This write statement was not used before
- not reached: Payload size and schema
- fails: An entry covers the topic (or unregistered topics are open)
- driver's app
- application service
- member node
- state machine
- refused
- A direct write carries the policy’s threshold of writer signatures instead of a credential.
- A credential stands in for one writer. Its issuer must be listed under
delegateand belong to a 1-of-n writer set; it cannot satisfy a 2-of-n policy by itself. A change to the allowed issuers takes effect at its activation height. - Signatures bind the chain generation, so a credential copied to a fresh chain grants nothing. A write also binds the topic, payload hash, nonce and expiry, and the host rejects reused, revoked, expired or out-of-scope writes.
- The machine sees the payload, not the frame. Machine hooks receive the
verified payload through
getBody(), while the message id, receipt and message proof follow the submitted frame. Do not strip a frame from an archived message or make up a replacement id.
| Code | The write was refused because |
|---|---|
TOPIC_UNREGISTERED | no entry covers the topic, and the chain rejects unregistered topics |
TOPIC_RETIRED | the entry is retired |
TOPIC_FRAME_INVALID | the topic is protected and the body is not a canonical frame |
TOPIC_PROOF_EXPIRED | the write proof’s notAfter has passed or is too far ahead |
TOPIC_WRITER_DENIED | signatures are missing, invalid, below the threshold, or not from writer keys |
TOPIC_DELEGATION_INVALID | the credential’s issuer, scope or time window is wrong, or it was revoked |
TOPIC_PROOF_REPLAYED | this write was already used |
TOPIC_PAYLOAD_TOO_LARGE | the payload is above maxPayloadBytes |
TOPIC_SCHEMA_REJECTED | the payload is not canonical CBOR or does not match the schema |
Registry commands have their own codes: TOPIC_COMMAND_INVALID, _DENIED,
_EXPIRED, _STALE, _LIMIT and _SUPERSEDED.
Payload schemas
Section titled “Payload schemas”Topic schemas use the same yano-cbor-schema-ir-v1 evaluator as
authenticated-map. CDDL is compiled by CddlSchemaCompiler before
submission; members only evaluate the committed IR. Put a topic
schema on an opaque machine such as ordered-log. Typed kernels such as
balances already define their command format and reject a second topic
schema. Composite rules can read the verified payload; see
admission rules.
Read the registry
Section titled “Read the registry”| You want | CLI | REST, below /api/v1/app-chain/chains/{chainId} |
|---|---|---|
| The chain’s topic settings | topics init reads them | GET /topics/config |
| One entry and its revisions | GET /topics/entries/{name} | |
| A topic’s effective policy at the tip | GET /topics/resolve?topic= | |
| The same for a block, with proofs | topics resolve <topic> [--height <n>], verified | GET /topics/proof?topic=&height= |
| A schema’s IR | GET /topics/schemas/{hash} | |
| The outcome of a registry command | GET /topics/receipts/{messageId} |
All of these are reads. In an entry name, encode the trailing slash:
/topics/entries/freight%2F. Owners’ commands are submitted as ordinary messages on
~topics/registry; members’ votes go through the privileged
POST /admin/topics/governance, which topics approve calls on each
operator’s own node. See the REST API.
Proofs and trust
Section titled “Proofs and trust”An entry-state proof establishes one registry record at a root. It does not
establish a topic’s effective policy: ancestors, the absence of overrides and
the configuration also matter. appchain topics resolve returns a
topic-policy-v1 effective-policy bundle for a candidate height, anchored to
its parent state’s root. It includes the configuration revision and source
entry revisions, including disabled and unregistered outcomes.
Entry-state proofs come from the generic state proof API, not a separate
topic-entry-v1 typed endpoint. Studio labels them as entry-only proofs, and
its downloaded peer responses are not independent verification. For
authorship, appchain topics verify requires the message, frame, generation
and complete effective-policy, replay, revocation and schema evidence, plus
independently trusted block/root information; the
how-to lists the inputs. It refuses entry-only data. A
valid signature alone does not establish current authority or finality.
Preview upgrade boundary
Section titled “Preview upgrade boundary”This implementation pins the Yano host at 0.1.0-pre19, API level 13, with
its matching ordinary JVM ZIP. Qualify it on a fresh app-chain genesis.
Existing retained deployments remain on their exact host, profile and genesis;
this change supplies no in-place migration or reset procedure.
The old collection schema vectors keep their IR bytes and results. The merged core evaluator also hardens the work budget by charging bytes examined in literal comparisons. A pathological legacy value can therefore be rejected at that budget boundary; the regression suite records this case. This is an intentional prerelease boundary, not a claim that every historical state can be replayed under the new host. The host also adds a committed clock-skew field to its consensus profile. Keep old stores with the binary that created them.