Prose Specification

Protocol Specification

Core protocol: crypto, events, RBAC, enclave state, predefined events, registry, and migration.

ENC Protocol Specification

1. Overview

Protocol Summary

ENC (encode, encrypt, enclave) is a protocol for building log-based, verifiable, sovereign data structures with Role-Based Access Control (RBAC).

Key properties:

• Append-only event log — immutable sequence of finalized events
• Verifiable state — Sparse Merkle Tree (SMT) for RBAC and event status
• Cryptographic proofs — Certificate Transparency (CT) for log integrity
• Single sequencer — one node orders and finalizes events per enclave

Trust Model

The ENC protocol defines two query paths with different trust properties:

Enclave (Source of Truth)

• Queries to the enclave node return verifiable proofs
• Clients can verify RBAC state, event existence, and event status (U/D) against the SMT root
• The enclave is the final arbiter when disputes arise

DataView (Convenience)

A DataView is a separate service that indexes, aggregates, and transforms enclave data for efficient querying.

• Clients trust DataView responses without cryptographic verification
• DataView is optimized for performance and flexibility, not provability
• If a client suspects incorrect data, they SHOULD verify against the enclave directly

Data Access Methods:

A DataView can receive enclave data through three methods, each requiring a role assignment:

• Dispute resolution
• High-value transactions
• Audit trails

2. Cryptographic Primitives

Signature Scheme

The ENC protocol uses Schnorr signatures over the secp256k1 curve, following the BIP-340 specification.

• All schnorr(message, private_key) operations MUST use the secp256k1 elliptic curve.
• Signatures MUST conform to BIP-340 (32-byte x-only public keys, 64-byte signatures).
• Identity keys (id_pub) are 32-byte x-only secp256k1 public keys as defined in BIP-340.

Deterministic Signing:

All Schnorr signatures MUST be deterministic. Implementations MUST use the default nonce derivation specified in BIP-340, which derives the nonce from:

• The private key
• The message being signed
• Optional auxiliary randomness (if used, MUST be set to 32 zero bytes for determinism)

This ensures that signing the same message with the same key always produces the same signature, making event IDs deterministic and verifiable.

Hash Function

• All sha256() operations use SHA-256 as defined in FIPS 180-4.

Hash Encoding

All hash pre-images MUST be serialized using CBOR (RFC 8949) with deterministic encoding before hashing.

Canonical Hash Function:

This specification defines:

H(fields...) = sha256(cbor_encode([fields...]))

All hash formulas in this document use H() implicitly. When you see:

sha256([0x10, enclave, from, type, content_hash, exp, tags])

it means:

sha256(cbor_encode([0x10, enclave, from, type, content_hash, exp, tags]))

CBOR Encoding Rules:

• Implementations MUST use deterministic CBOR encoding (RFC 8949 Section 4.2)
• Integer prefixes (0x00, 0x10, etc.) are encoded as CBOR unsigned integers
• Binary data (hashes, public keys) are encoded as CBOR byte strings
• Strings (content, type) are encoded as CBOR text strings (UTF-8)
• Empty string "" is encoded as CBOR text string with length 0 (0x60)
• Arrays are encoded as CBOR arrays with definite length

Hash Prefix Registry

To prevent hash collisions between different data types, all hash operations use a unique single-byte prefix:

Prefixes 0x02–0x0F, 0x13–0x1F, and 0x22–0x2F are reserved for future use.

String Prefixes for Signatures:

Signature contexts use string prefixes (not byte prefixes) for domain separation:

String prefixes are concatenated with data before hashing: sha256(prefix || data).

Wire Format

Transport Encoding:

The normative wire format for v1 is JSON. CBOR is used only for hash computation, not transport.

JSON Encoding:

When serializing for transport or storage as JSON:

CBOR Encoding:

When serializing for hashing or binary transport:

3. Core Concepts

Enclave

An Enclave is a log-based, verifiable, sovereign data structure with Role-Based Access Control (RBAC).

An enclave maintains:

• An append-only event log — immutable sequence of finalized events
• A verifiable state (SMT) — unified tree storing RBAC state and event status
• A structural proof — append-only Merkle tree proving log integrity (see Structural Proof)

Node

A Node is a host for one or more enclaves.

A node is responsible for:

• Storing data for enclave
• Serving queries
• Producing cryptographic proofs
• Sequencing commits into events (if acting as sequencer)

Sequencer Model

Each enclave has a single sequencer — the node responsible for ordering and finalizing commits.

Assignment:

• The node that accepts and finalizes the Manifest event becomes the sequencer for that enclave
• The sequencer's identity key is recorded in the Manifest event's sequencer field
• The sequencer is discoverable via Registry (Reg_Enclave)

Responsibilities:

• Accept valid commits and assign seq, timestamp
• Sign events with seq_sig
• Maintain the append-only Merkle tree
• Maintain the Enclave State SMT
• Deliver P (Push) and N (Notify) to registered recipients

Sequencer change:

• See Migration section for sequencer handoff protocol

Client

A Client is a software agent that controls an Identity Key by holding (or having authorized access to) the corresponding private key id_priv, and can produce signatures or decrypt/encrypt on behalf of the identity id_pub according to the ENC protocol.

Notes:

• A client may be an app, service, or device component.
• id_priv may be held directly or accessed via a secure signer (e.g., OS keystore, HSM, enclave, wallet).

Identity Key

An Identity Key is a 256-bit public key (id_pub) used to represent an identity in the ENC protocol.

4. Event Lifecycle

Commit

A Commit is a client-generated, signed message proposing an event.

A commit:

• Is authored by a client
• Is cryptographically bound to its content and metadata
• Has not yet been ordered or finalized by a node

Commit Structure

{
  hash: <hex64>,
  enclave: <enclave id>,
  from: <sender_id_pub>,
  type: <string>,
  content_hash: <hex64>,
  content: <string>,
  exp: <unix timestamp>,
  tags: [ <name | str1 | str2>, ... ],
  sig: <signature over hash>
}

Where:

• hash: commitment hash of the commit fields
• enclave: destination enclave
• from: identity key of the author
• type: commit type, defined within the enclave scope
• content: payload (UTF-8 string; MAY be empty "" for events with no payload like Pause/Resume; binary data SHOULD be base64 encoded; large binaries SHOULD use external resource URLs)
• exp: latest time at which the node may accept the commit (Unix epoch milliseconds; also acts as a nonce)
• tags: node-level metadata (see Tags)
• sig: signature by from, proving authorship

Commit Hash Construction

This formula applies to ALL event types (Manifest, Grant, Chat_Message, etc.):

_content_hash = sha256(utf8_bytes(content))
hash = H(0x10, enclave, from, type, _content_hash, exp, tags)
sig = schnorr(hash, from_priv)

Where utf8_bytes() returns the raw UTF-8 byte sequence. No Unicode normalization (NFC/NFD) is performed at the protocol level. The content structure varies by event type, but the hash formula is identical.

Note: _content_hash uses raw SHA-256 on bytes, not H(), because content is already a byte string.

Binary Data in Content:

If content contains binary data (e.g., images, files), the data MUST be base64-encoded before inclusion. The content_hash is computed over the base64-encoded string, not the decoded binary bytes.

Example:

• Binary data: 0x48656c6c6f (5 bytes, "Hello")
• Base64 encoded in content: "SGVsbG8="
• content_hash = sha256(utf8_bytes("SGVsbG8=")) — hash of 8 UTF-8 bytes

This ensures the hash matches what is transmitted and stored. Implementations MUST NOT decode base64 before hashing.

This establishes:

• Integrity of content
• Binding between author and intent

Content Integrity:

The node MUST store and serve event.content exactly as received in the commit — byte-for-byte, with no normalization or transformation. Any modification would invalidate the commit hash.

Application-Level Canonicalization:

If applications treat content as structured data (e.g., JSON), they MUST define their own canonical encoding rules to ensure cross-client byte-identical hashing. The protocol treats content as an opaque byte string.

Tags

Tags provide node-level metadata that instructs the node how to process an event.

• Content — opaque to the node; the node stores and serves it without interpretation
• Tags — understood by the node; predefined tags trigger specific node behaviors

Unlike protocols where tags serve as query indexes, ENC data is already scoped to enclaves. Tags exist primarily to convey processing instructions to the node.

Structure:

Tags are an array of arrays. Each tag has:

• Position 0: tag name (key)
• Position 1: primary value
• Position 2+: additional values (optional)

All tag values MUST be strings. Numeric or other typed values are encoded as their string representation.

[
  ["<name>", "<value>", "<additional>", ...],
  ...
]

Hash Encoding: When computing the commit hash, tags are encoded as a single CBOR text string using bracket notation: each tag becomes [name,val1,val2,...] and tags are comma-separated. For example, [["r","abc","reply"],["auto-delete","1706000000000"]] encodes as the text "[r,abc,reply],[auto-delete,1706000000000]". Empty tags [] encode as an empty text string "". The order of tags is significant for hash computation.

Empty Tags: An empty tags array [] is valid.

Example:

[
  ["auto-delete", "1706000000000"],
  ["r", "abc123...", "reply"]
]

Predefined Tags:

r Tag Context Values:

Custom context values are allowed for application-specific semantics. Nodes treat unrecognized contexts as general references.

Auto-delete vs Delete event:

Relationship with exp:

The auto-delete timestamp MUST be greater than exp. The commit must be accepted before auto-delete takes effect. Nodes SHOULD reject commits where auto-delete <= exp as semantically invalid.

Auto-delete and SMT:

Auto-delete does NOT update the SMT. The event remains "active" in SMT state (no entry in Event Status namespace). Auto-delete only affects storage — the node removes content but event metadata may remain. This is intentional: auto-delete is trust-based, not verifiable via SMT proofs.

Additional predefined tags may be defined by the protocol or application schemas.

Event Finalization

Upon receiving a valid commit, a node performs:

1. Expiration check — reject if exp < current time
2. Deduplication check — reject if commit hash was already processed (see Replay Protection)
3. RBAC authorization check — verify sender has C permission for this event type
4. Sequencing and timestamp assignment

If accepted, the node finalizes the commit into an event by adding node-generated fields.

Replay Protection

The node MUST reject commits with a hash that has already been processed for this enclave.

Implementation:

• Node maintains a set of accepted commit hashes per enclave
• Before accepting a commit, check if hash exists in the set
• If duplicate, reject the commit
• Only add hash to set AFTER successful acceptance
• Hashes MAY be garbage collected after exp + 60000 ms (60 seconds buffer for clock skew)

This prevents replay attacks where an attacker resubmits a valid commit multiple times within the expiration window.

Expiration Window Limit:

Nodes MUST reject commits where the expiration is too far in the future:

exp - current_time > MAX_EXP_WINDOW → reject

The protocol defines MAX_EXP_WINDOW = 3600000 (1 hour in milliseconds). Implementations MAY use a shorter window.

This prevents storage DoS attacks where clients submit commits with extremely large exp values, forcing indefinite hash retention.

Clock Skew Tolerance:

The protocol tolerates bounded clock skew (±60 seconds) between client and sequencer:

Implementations SHOULD sync clocks via NTP and log warnings if skew exceeds 60 seconds.

Event

An Event is the fundamental, immutable record within an enclave.

Conceptually, an event represents a user-authorized action that has been:

1. Authored and signed by a client, and
2. Accepted, ordered, and finalized by a node.

An event is derived from a Commit, after validation and sequencing by a node.

Event Structure

{
  id: <hex64>,
  hash: <hex64>,
  enclave: <enclave id>,
  from: <sender_id_pub>,
  type: <string>,
  content: <string>,
  exp: <unix timestamp>,
  tags: [ <name | str1 | str2>, ... ],
  timestamp: <unix time>,
  sequencer: <sequencer_id_pub>,
  seq: <number>,
  sig: <signature over hash>,
  seq_sig: <signature over hash>,
}

Where:

• timestamp: time at which the event was finalized (Unix epoch milliseconds; MUST be ≥ previous event's timestamp; equal timestamps allowed, ordering determined by seq)
• sequencer: identity key of the sequencing node
• seq: monotonically increasing sequence number within the enclave (starts at 0; Manifest is seq=0)
• seq_sig: signature by the sequencer over the finalized event
• id: canonical identifier of the event

Sequencer Continuity:

For all events except Migrate (forced takeover), the sequencer field MUST match the current sequencer recorded in the Manifest. If a different key signs seq_sig, the event is invalid and clients MUST reject it. Exception: Migrate in forced takeover mode — the new sequencer finalizes the Migrate event (see Migration section).

Field inheritance from Commit:

The following fields are copied directly from the original Commit:

• hash — the commit hash (Event.hash == Commit.hash)
• enclave, from, type, content, exp, tags, sig

The node adds: id, timestamp, sequencer, seq, seq_sig

Event Hash Chain

The event's cryptographic commitments are constructed as follows:

_event_hash = H(0x11, timestamp, seq, sequencer, sig)
seq_sig = schnorr(_event_hash, sequencer_priv)
id = sha256(seq_sig)

The resulting id:

• Commits to both client intent and node ordering
• Serves as the leaf identifier for Merkle trees and proofs
• Is immutable and globally referencable

Receipt

A Receipt is a node-signed acknowledgment proving that a commit has been accepted, sequenced, and finalized into an event.

It provides the client with the canonical event identifier and sequencing metadata, without including the event content.

Structure

{
  id: <hex64>,
  hash: <hex64>,
  timestamp: <unix time>,
  sequencer: <sequencer_id_pub>,
  seq: <number>,
  sig: <signature over hash>,
  seq_sig: <signature over _event_hash>
}

Where:

• sig: the client's signature from the original commit (proves client intent)
• seq_sig: the sequencer's signature over the finalized event (proves node acceptance)

The receipt cryptographically binds client intent and node ordering, and allows the client to verify successful finalization of its commit.

5. RBAC

RBAC (Role-Based Access Control) consists of two parts:

• Schema — defines which roles can perform which operations
• State — tracks current role assignments

Schema

The Schema defines which roles are permitted to perform which events.

It can be represented as an Event–Role–CRUD matrix, for example:

Where C (Member) means Create permission with target_roles: ["Member"].

Schema Entry Structure

Each schema entry defines permissions for a (role, event type) pair:

{ "event": "<type>", "role": "<role>", "ops": ["<op>", ...], "target_roles": ["<role>", ...] }

Fields:

Operations (ops):

target_roles field:

Required for: Grant, Grant_Push, Revoke, Revoke_Self, Move. Ignored for other event types.

Schema entries for Grant and Grant_Push:

Grant and Grant_Push are independent event types requiring separate schema entries. An Admin with C permission for Grant does NOT automatically have C permission for Grant_Push.

Example:

{ "event": "Grant", "role": "Admin", "ops": ["C"], "target_roles": ["Member"] }
{ "event": "Grant_Push", "role": "Admin", "ops": ["C"], "target_roles": ["Member"] }

If only Grant is defined for a role, that role cannot issue Grant_Push (and vice versa).

This field prevents privilege escalation:

{ "event": "Grant", "role": "Owner", "ops": ["C"], "target_roles": ["Admin", "Member"] }
{ "event": "Grant", "role": "Admin", "ops": ["C"], "target_roles": ["Member"] }

• Owner can grant Admin or Member roles
• Admin can only grant Member (cannot grant Admin — would be escalation)

Note: Force_Move bypasses target_roles restriction (see AC Event Authorization).

Wildcard Event Pattern:

The special event pattern * matches all event types. This is useful for:

• Backup roles that need P (Push) for all events
• DataView roles that need N (Notify) for all events

Example:

{ "event": "*", "role": "Backup", "ops": ["P"] }

Note: Wildcard patterns apply to both AC Events and Content Events.

Granting P (Push) with wildcard * gives the recipient full read access to all enclave data via push delivery. This is equivalent to granting R for all event types, but bypasses query authentication. Assign wildcard P only to trusted services (e.g., backup, authorized DataViews).

Reserved Roles

The ENC protocol defines the following reserved roles:

• Self (bit 0) — An implicit role that matches the event creator (the from field). This role is NOT stored in the RBAC state; it is evaluated dynamically at authorization time. For U/D operations, Self refers to the original Content Event's from field — this allows authors to update or delete their own events without explicit role assignment. When an event has been updated multiple times, Self always evaluates against the original author, not any intermediate Update event's author.

• Owner (bit 1) — The enclave owner. This role MUST be explicitly assigned in the Manifest's initial_state. The owner may be different from the Manifest's from (creator), allowing one identity to create an enclave on behalf of another.

• Node (bit 2) — The node hosting this enclave. Like Self, this role is NOT stored in RBAC state; it is evaluated dynamically by comparing the actor's identity with the enclave's current sequencer. In v1, a node's identity key (seq_pub) serves as both its registration identity and its sequencer identity. To rotate keys, use Migrate to the new identity. The Node role is reserved for future protocol extensions (e.g., node-initiated events). In v1, no predefined events require Node role for authorization.

• Any (bit 3) — Represents any identity, including unauthenticated requests. If the schema grants read permission to Any, no authentication is required for that operation. Restriction: The Any role cannot have P (Push) or N (Notify) permissions — P/N delivery requires an authenticated identity with a registered endpoint. Nodes MUST reject schemas that grant P or N to the Any role.

State

The State represents the current role assignments of identities.

Conceptually, it answers the question:

> "Which identity keys are assigned to which roles?"

Representation

• Each role is represented as a binary slot (bit position)
• A combination of roles is encoded as a role binary (integer)
• The full state is stored in a Sparse Merkle Tree (SMT)

Role Binary Encoding

Roles are mapped to bit positions as follows:

Reserved roles (bits 0–31):

Custom roles (bits 32+):

Custom roles defined in the schema are assigned bit positions starting at bit 32, in the order they appear in the schema.

Example:

Schema defines: ["Admin", "Member", "Moderator"]

Resulting mapping:

• Bit 0: Self (reserved)
• Bit 1: Owner (reserved)
• Bit 2: Node (reserved)
• Bit 3: Any (reserved)
• Bits 4–31: (reserved)
• Bit 32: Admin
• Bit 33: Member
• Bit 34: Moderator

An identity with Owner + Admin + Member has role binary: 2^1 + 2^32 + 2^33

Bitmask Encoding in JSON:

Role bitmasks in event content (e.g., Move, Force_Move) are encoded as hex strings with 0x prefix:

{ "from": "0x100000002", "to": "0x100000000" }

This ensures arbitrary precision (JSON numbers lose precision beyond 2^53) and makes bit positions visually clear.

Bitmask Contexts:

In SMT, bitmasks are always stored as 32-byte big-endian values for consistent leaf hashing.

P (Push) and N (Notify)

P (Push) and N (Notify) enable proactive delivery from nodes to external services or clients.

P (Push):

• Node delivers the full event to identities with P permission for that event type
• Use case: DataView services that index, aggregate, or transform enclave data
• DataView does not need R permission — it receives data via push, not query

N (Notify):

• Node delivers a lightweight notification (metadata only, not content)
• Use case: Clients that want to know when to refresh, or services tracking enclave activity

Registration:

• Identities receiving P or N MUST be assigned the appropriate role in RBAC state (e.g., Admin assigns a DataView identity to a role with P permission)
• The identity's delivery endpoint MAY be registered in the Registry for well-known services

Transport:

• Transport mechanism is implementation-defined
• Nodes SHOULD support HTTPS POST (webhook) delivery
• Nodes MAY support WebSocket for real-time streaming

Delivery Guarantees:

P (Push) Retry Policy:

• Initial retry: 1 second after failure
• Exponential backoff: 2x multiplier per retry
• Maximum interval: 5 minutes
• Maximum retries: 10 attempts
• After max retries: drop event, log failure, SHOULD alert enclave owner

Implementations MAY use different parameters but MUST implement retry with backoff. Nodes SHOULD NOT retry indefinitely to avoid resource exhaustion.

Grant_Push Endpoint Failure:

When P delivery to a Grant_Push endpoint fails persistently (max retries exhausted):

• The endpoint registration is kept (not removed)
• The node SHOULD alert the enclave Owner
• The Owner can manually revoke the role if the endpoint is permanently invalid
• The node retries with a fresh retry cycle on subsequent events (stateless — no failure tracking between events)

P/N Delivery Independence:

Each event's P/N delivery is independent. If delivery fails for one event, it does not affect delivery of other events. Events in the same bundle are delivered separately, each with its own retry cycle.

P (Push) Payload:

The P payload is the complete Event structure (see Event Structure). No wrapper is needed — the event already contains the enclave field.

N (Notify) Payload:

{
  "enclave": "<enclave_id>",
  "event_id": "<event_id>",
  "type": "<event_type>",
  "seq": 123,
  "type_seq": 45,
  "timestamp": 1706000000000
}

Where:

• enclave — the enclave identifier
• event_id — the canonical event identifier
• type — the event type
• seq — the global sequence number of the event within the enclave
• type_seq — the sequence number of this event within its type (1-indexed, continuous per type)
• timestamp — the event timestamp (milliseconds)

Per-Type Sequence Counter:

Nodes MUST maintain a per-type sequence counter for each enclave. When an event of type T is finalized, the node increments the counter for T and assigns it as type_seq. This allows N recipients to detect missed notifications by checking continuity of type_seq.

type_seq Rules:

• Starts at 1 for the first event of each type (not 0)
• Increments by 1 for each subsequent event of that type
• Never resets — even after migration, counters continue from their last value
• Each event type has an independent counter

When a recipient detects a type_seq gap (e.g., received 5, then 8):

• If R permission available: Use Query (/query) to fetch missed events by type and sequence range. This is the preferred recovery method.
• If N permission only: Gaps cannot be recovered through the protocol. N-only recipients SHOULD design their applications to tolerate gaps (e.g., treat notifications as hints rather than authoritative state). Consider upgrading to R permission if complete event history is required.

A role MAY have both P and N permissions for the same event type. P takes precedence — if P delivery succeeds, N is not sent separately. If P fails (max retries exhausted), N MAY be sent as fallback notification.

U (Update) and D (Delete)

U (Update) and D (Delete) are logical operations implemented as new events that reference prior events.

Semantics:

• The event log remains append-only; original events are never mutated
• A Delete event marks a target event as logically deleted
• An Update event marks a target event as superseded and provides new content
• An event MAY be updated multiple times, forming an update chain
• Only identities with U or D permission (per schema) for that event type can issue these operations

Event Status State:

The current status of each event (active, updated, deleted) is tracked in the Enclave State SMT alongside RBAC state (see Enclave State SMT).

When a U or D event is finalized:

1. The node updates the SMT entry for the target event
2. The SMT root reflects the new state
3. Clients can verify event status via SMT proof

Content Integrity Proofs:

Verification Flow:

1. Call POST /state with namespace: "event_status" and key: <event_id> → get SMT proof
2. If proof value = 0x00 → event is Deleted (conclusive)
3. If proof value = 32-byte ID → event is Updated to that ID (conclusive)
4. If proof value = null (non-membership): - Call POST /bundle with event_id → get bundle membership proof - If proof succeeds → event is Active - If proof fails (EVENT_NOT_FOUND) → event never existed

Clients MUST perform step 4 to distinguish Active from never-existed. The 1-byte vs 32-byte value length unambiguously distinguishes Deleted from Updated.

Content Handling:

When an event is updated or deleted:

• The node SHOULD delete the original content from storage
• However, there is no guarantee of content deletion — the node operates on a best-effort basis
• Clients MUST NOT assume original content is irrecoverable

Querying:

• Enclave queries: Return event + status + SMT proof (verifiable)
• DataView queries: Return event + status (trusted, no proof)

6. Enclave State

Enclave State SMT

The enclave maintains a single Sparse Merkle Tree (SMT) that stores both:

• RBAC state — identity → role binary
• Event status state — event ID → status (active/updated/deleted)

The SMT uses:

• Trimmed depth (shorter than 256 bits) for efficiency
• Flag bits to distinguish entry types (RBAC vs Event Status)

Implementation details (depth, flag encoding, proof format) are specified in smt.md.

RBAC Entries:

• Path: derived from id_pub (trimmed + flag)
• Leaf value: role binary

Event Status Entries:

• Path: derived from event_id (trimmed + flag)
• Leaf value: status + reference to U/D event

Root Hash:

The SMT root hash represents the complete enclave state (both RBAC and event status). This single root can be used to verify any state query.

Structural Proof (Certificate Transparency)

The enclave maintains an append-only Merkle tree over the event log, providing verifiable log integrity. This follows the Certificate Transparency (CT) specification defined in RFC 9162.

Properties:

• CT root: Single hash representing the entire event history AND state
• Inclusion proof: Proves a specific event exists at a given position in the log
• Consistency proof: Proves an earlier log state is a prefix of the current state

Bundle Structure:

Events are grouped into bundles (see Bundle Configuration). Each bundle produces one CT leaf.

bundle = {
  events: [event_id_0, event_id_1, ..., event_id_N],
  state_hash: <SMT root after last event in bundle>
}

Initial State:

Before any events (including Manifest), the SMT is empty:

empty_state_hash = sha256("")
                 = 0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

The Manifest event is always in bundle 0. The bundle's state_hash is the SMT root AFTER Manifest's initial_state has been applied.

Leaf hash:

events_root = merkle_root(events)  // binary Merkle tree of event IDs
leaf_hash = H(0x00, events_root, state_hash)

Where:

• events_root — Merkle root of event IDs in this bundle
• state_hash — SMT root AFTER the last event in this bundle is applied

events_root Construction:

For N events in a bundle:

1. If N = 1: events_root = event_ids[0] (no tree needed)
2. If N > 1: Build a binary Merkle tree over event IDs: - Leaf: event_id (raw 32-byte hash, no prefix) - Internal node: H(0x01, left, right) - If N is not a power of 2, right-pad with the last event_id until the next power of 2 - Example: 3 events → pad to 4 leaves: [e0, e1, e2, e2]

Bundle Event Ordering:

Events within a bundle are ordered by their sequence number (seq). The first event has the lowest seq, the last has the highest. This ordering is deterministic and verifiable.

Bundle Index Assignment:

Bundles are numbered sequentially starting from 0. An event's bundle membership is determined by bundle boundaries:

• bundle_0 contains events from seq=0 until size or timeout reached
• bundle_N contains events from boundary[N-1] + 1 until size or timeout reached
• boundary[N] = seq of last event in bundle N

Determining bundle from seq:

event.seq belongs to bundle_N where:
  boundary[N-1] < event.seq <= boundary[N]
  (boundary[-1] = -1 for the first bundle)

Deterministic reconstruction:

During log replay or migration, bundle boundaries are reconstructed by applying the same closing rules (size/timeout). If CT root matches after reconstruction, bundle assignment is correct.

Example:

Config: bundle.size = 3, timeout = 5000ms

seq=0,1,2 (ts: 1000ms) → bundle_0, boundary[0]=2
seq=3,4,5 (ts: 3000ms) → bundle_1, boundary[1]=5
seq=6     (ts: 9000ms) → bundle_2, boundary[2]=6 (timeout hit)

Query: which bundle is seq=4?
Answer: bundle_1 (because 2 < 4 <= 5)

Internal node:

node_hash = H(0x01, left_child, right_child)

The 0x00 and 0x01 prefixes prevent second-preimage attacks by distinguishing leaf nodes from internal nodes.

CT Tree Construction:

The CT tree follows RFC 9162 Section 2.1 (Merkle Tree algorithm):

• Bundles are CT leaves, numbered sequentially (bundle_0, bundle_1, ...)
• Tree grows as bundles are appended
• For N bundles where N is not a power of 2: right-pad with the last bundle's leaf_hash until the next power of 2
• Example: 5 bundles → pad to 8 leaves: [b0, b1, b2, b3, b4, b4, b4, b4]

CT root (8 leaves, 5 actual bundles):

              root
            /      \
         h01        h23
        /   \      /   \
      h0    h1   h2    h3
     / \   / \  / \   / \
    b0 b1 b2 b3 b4 b4 b4 b4
    ↑  ↑  ↑  ↑  ↑
    actual bundles (b4 repeated as padding)

This ensures deterministic CT roots across all implementations.

Proof Structure:

To prove an event exists and verify state:

1. Bundle membership proof — proves event_id is in the bundle's events_root
2. CT inclusion proof — proves bundle is in the CT tree

With bundle.size = 1, the events_root equals the single event_id, and bundle membership proof is trivial.

State Binding:

The CT leaf binds each bundle to the enclave state after that bundle:

state_hash[bundle_0] = SMT root after all events in bundle 0
state_hash[bundle_N] = SMT root after all events in bundle N

Within a bundle, state changes are applied sequentially:

For events [e_0, e_1, ..., e_k] in bundle:
  state = apply(state, e_0)
  state = apply(state, e_1)
  ...
  state = apply(state, e_k)
  bundle.state_hash = state

State-changing events: Manifest, Grant, Grant_Push, Revoke, Revoke_Self, Move, Force_Move, Transfer_Owner, AC_Bundle, Update, Delete

Non-state-changing events: Content Events, Pause, Resume, Terminate, Migrate

Since state_hash is deterministic from the log, anyone can recompute and verify it. If a node provides incorrect state_hash values, the CT root will not match.

State Query Semantics:

When clients query enclave state (RBAC or event status) mid-bundle, two modes are available:

• Verified queries: Use for audits, disputes, high-stakes operations
• Current queries: Use for real-time apps (chat, collaboration)

Nodes SHOULD support both modes. The default mode is implementation-defined (SHOULD be documented).

Staleness Guidance:

With default bundle.timeout = 5000 ms, verified queries may be up to 5 seconds stale. Nodes SHOULD document their bundle configuration and expected staleness.

Use cases:

• Client verifies an event is part of the canonical log
• Client verifies the enclave state at any point in history
• Client verifies the log they cached is still valid (consistency with current log)
• Detect if a node is presenting different log histories to different clients
• Checkpoint for migration (CT root proves both log and state)

Proof serialization formats are specified in proof.md.

Enclave Lifecycle

An enclave exists in one of four states, derived from the event log:

*After Terminate, the node SHOULD delete enclave data. Reads MAY be allowed until deletion completes.

**After Migrate, the old node is not obligated to serve reads. Clients should query the new node.

State Derivation:

migrated = exists(Migrate)
terminated = !migrated && exists(Terminate)
paused = !migrated && !terminated && last_of(Pause, Resume).type == "Pause"
active = !migrated && !terminated && !paused

Mutual Exclusion: Terminate and Migrate are mutually exclusive terminal states. The node MUST reject:

• Migrate commit if Terminate already exists → error ENCLAVE_TERMINATED
• Terminate commit if Migrate already exists → error ENCLAVE_MIGRATED

This prevents ambiguous state derivation. The first terminal event wins.

last_of() Semantics: last_of(Pause, Resume) returns the most recent event of either type. If neither exists, the result is null, and the paused condition evaluates to false.

The lifecycle state is not stored in the SMT. Nodes derive it from the event log (and MAY cache for performance). The lifecycle events themselves are recorded in the append-only log, providing an audit trail.

Lifecycle Events:

Behavior in Paused State:

• Node MUST reject all commits except Resume, Terminate, and Migrate
• In-flight commits at the moment of Pause are rejected
• Read queries continue to work normally
• In-flight P (Push) and N (Notify) deliveries SHOULD complete (events already finalized)

P/N Delivery in Paused State:

Events finalized before Pause may have in-flight P/N deliveries — these SHOULD complete. No new events are finalized during Pause (except Resume/Terminate/Migrate), so no new P/N deliveries are initiated. P/N is not "paused" — there are simply no new events to trigger deliveries.

7. Predefined Events

Predefined events are event types with special semantics understood and processed by the node.

Event Categories

• Only Content Events can be Updated or Deleted
• AC Events are irreversible — they represent state transitions
• Update/Delete events cannot themselves be Updated or Deleted

The node determines the category by event type — all AC event types and Update/Delete are predefined by the protocol.

Predefined Event Type Registry

Content Events: Any type NOT in this registry is a Content Event (e.g., Chat_Message, File_Upload). Content Events do not modify SMT state.

Manifest

A Manifest is a predefined event type used to initialize an enclave.

The acceptance and finalization of a Manifest event marks the creation of the enclave and establishes its initial configuration.

Type: Manifest

Manifest Commit Content

{
  "enc_v": 1,
  "RBAC": {
    "use_temp": "none",
    "schema": [
      { "event": "Grant", "role": "Owner", "ops": ["C"], "target_roles": ["Admin", "Member"] },
      { "event": "Grant", "role": "Admin", "ops": ["C"], "target_roles": ["Member"] },
      { "event": "Grant", "role": "Member", "ops": ["R"] },
      { "event": "Revoke", "role": "Owner", "ops": ["C"], "target_roles": ["Admin", "Member"] },
      { "event": "Revoke", "role": "Admin", "ops": ["C"], "target_roles": ["Member"] },
      { "event": "Revoke", "role": "Member", "ops": ["R"] },
      { "event": "Revoke_Self", "role": "Member", "ops": ["C"], "target_roles": ["Member"] },
      { "event": "Terminate", "role": "Owner", "ops": ["C"] },
      { "event": "Terminate", "role": "Member", "ops": ["R"] },
      { "event": "Chat_Message", "role": "Member", "ops": ["C", "R"] },
      { "event": "Chat_Message", "role": "Self", "ops": ["U", "D"] }
    ],
    "initial_state": {
      "Owner": [id_owner],
      "Admin": [id1, ...],
      "Member": [id1, id2, ...]
    }
  },
  "meta": { "description": "a simple group" },
  "bundle": {
    "size": 256,
    "timeout": 5000
  }
}

Note: This is a simplified example. Production schemas should include additional AC events (Move, Force_Move, Transfer_Owner, Pause, Resume, Migrate) as needed for the enclave's requirements.

Manifest Content Canonicalization:

Unlike Content Events, the node parses Manifest content as JSON for validation. For commit hash verification:

• Client sends content as UTF-8 JSON string
• Node hashes content byte-for-byte (does not re-serialize)
• Node parses JSON only for validation, not for hashing

Clients SHOULD use deterministic JSON serialization (sorted keys, no extra whitespace) for reproducibility, but this is not enforced by the protocol.

Fields

• enc_v — Version of the ENC protocol.
• RBAC.use_temp — Optional reference to a predefined RBAC template. If set, the schema field is ignored.
• RBAC.schema — JSON representation of the Event–Role–CRUD matrix.
• RBAC.initial_state — Initial RBAC state, assigning identity keys to roles. MAY be empty ({}), creating an enclave with no initial roles; roles must then be granted explicitly via Grant after Manifest.
• meta — Optional application-defined metadata (object). Can include a unique value to differentiate enclaves with otherwise identical content. The serialized meta field (as JSON) MUST NOT exceed 4 KB (4096 bytes). Nodes MUST reject Manifests with larger meta fields.

Unused Schema Roles:

A schema MAY define roles that are never assigned in initial_state. This is valid and common in modular systems. Unused roles do not affect protocol behavior — they simply define permissions that can be granted later.

• bundle — Optional bundle configuration (see below). If omitted, defaults apply.

Schema Immutability:

The RBAC schema is immutable after the Manifest is finalized. To change the schema, a new enclave must be created.

This ensures:

• Role bit positions remain stable for the enclave's lifetime
• RBAC proofs remain valid across the entire event history
• No ambiguity about which schema version applies to which events

No Schema Version Field:

The schema has no explicit version field. The enclave ID is derived from Manifest content (which includes the schema), so any schema change would produce a different enclave ID. This is intentional — changing the schema requires creating a new enclave.

Bundle Configuration:

The bundle field controls how events are grouped for CT and SMT efficiency.

Bundle closing rules:

• Close when size events accumulated, OR
• Close when timeout ms passed since bundle opened
• Whichever comes first

Timeout Clock:

Timeout is measured using event timestamps, not wall clock. The bundle opens when the first event's timestamp is recorded. The bundle closes when a new event arrives with timestamp >= first_event.timestamp + timeout.

Determinism: Bundle boundaries depend only on the finalized event sequence (seq order) and timestamps, which are immutable once sequenced. Out-of-order network delivery does NOT affect bundle boundaries — replaying the same log always produces identical bundles.

Idle Bundles:

If an enclave receives no new events, the current bundle remains open (no timeout trigger). This is intentional: bundles are only closed when needed for new events. An open bundle has no negative effect — CT/SMT are still current in-memory. The bundle closes immediately when the next event arrives (if timeout elapsed).

Concurrent Events:

The sequencer processes commits serially. "Simultaneous" arrival is resolved by the sequencer's internal ordering. Bundle boundaries are deterministic given the final event sequence.

Semantics:

• All events in a bundle share the same state_hash (SMT root after last event in bundle)
• CT leaf is created per bundle, not per event
• Set size: 1 for per-event state verification (no bundling)

state_hash Computation Timing:

The state_hash is computed when the bundle closes:

1. Process all events in bundle sequentially by seq order
2. Apply each state-changing event to SMT (RBAC updates, Event Status updates)
3. After last event is applied, capture current SMT root
4. This root becomes the bundle's state_hash

Immutability:

Bundle configuration is immutable after the Manifest is finalized, like the RBAC schema.

Enclave Identifier

The enclave identifier is derived from the Manifest commit:

enclave = H(0x12, from, type, content_hash, tags)

For a Manifest commit, the client MUST:

1. Compute enclave using the formula above
2. Set the enclave field in the commit to this value
3. Compute the commit hash (which includes enclave)

Derivation Order (critical for implementation):

1. content_hash = sha256(utf8_bytes(content))
2. enclave_id = H(0x12, from, "Manifest", content_hash, tags)
3. commit.enclave = enclave_id
4. commit_hash = H(0x10, enclave_id, from, "Manifest", content_hash, exp, tags)
5. sig = schnorr_sign(commit_hash, id_priv)

This two-step derivation ensures the enclave ID is self-referential and deterministic.

Enclave Identity and Collision:

The enclave ID is deterministic and independent of which node hosts it. If two nodes receive identical Manifest commits, they compute the same enclave ID. However, only one enclave with that ID should exist in the Registry at a time. Clients SHOULD verify the sequencer via Registry.

Collision Handling:

If a node receives a Manifest commit for an enclave ID that already exists on that node, the node MUST reject the commit. This is detected by checking if the enclave already has a seq=0 event.

If different nodes independently create enclaves with the same ID, both enclaves are technically valid on their respective nodes. The Registry determines which is canonical for discovery purposes — clients discovering via Registry will only see one sequencer.

Registry Conflict Resolution:

If two nodes attempt to register the same enclave ID in Registry:

• First valid Reg_Enclave wins (earliest seq in Registry)
• Subsequent registrations for the same enclave_id are rejected (not superseded)
• To transfer an enclave to a different node, use Migrate (not Registry re-registration)

This differs from normal Reg_Enclave superseding behavior — enclave ID conflicts are errors, not updates.

Manifest exp Field:

The exp field in a Manifest commit has the same semantics as other commits: it defines the deadline by which the node must accept the commit. After enclave creation, the Manifest's exp has no ongoing effect.

Manifest Validation

Validation Order:

1. Verify commit structure (fields present, types correct)
2. Verify commit hash and signature
3. Verify enclave ID derivation matches
4. Parse and validate content JSON
5. Apply content-specific rules below

The node MUST reject a Manifest commit if:

1. enc_v is not a supported protocol version
2. RBAC.use_temp is not "none" and not a recognized template name
3. RBAC.schema is invalid (when use_temp is "none"): - Not an array - Contains entries with missing required fields - Contains invalid ops values
4. RBAC.initial_state does not include exactly one identity with the Owner role (validation occurs at Manifest acceptance time; multiple Owners is invalid; zero Owners is invalid; Owner-only initial_state is valid)
5. Any identity in initial_state is not a valid 32-byte public key
6. Any role in initial_state is not defined in schema and not Owner (Owner is required; Self, Node, Any are dynamic and cannot be assigned)
7. Any custom role name conflicts with reserved names (Self, Owner, Node, Any)
8. initial_state includes Self, Node, or Any (these are dynamic roles, not assignable)

Initialization Semantics

If a node accepts the Manifest commit and returns a valid receipt, the client can conclude that:

• The enclave has been successfully initialized
• The RBAC schema and initial state are finalized
• The enclave identifier is canonical and immutable

Update

An Update event replaces the content of a previously finalized event.

Type: Update

Structure

Semantics

• The target event MUST be a Content Event (AC events cannot be updated)
• The target event (referenced by r tag) is marked as updated in the Enclave State SMT
• The original content SHOULD be deleted by the node (best-effort, no guarantee)
• Only identities with U permission for the target event's type can issue an Update
• An event MAY be updated multiple times; each Update references the original event (not the previous Update)
• The SMT leaf for the original event points to the latest Update

SMT Update Tracking:

When an Update event is finalized:

1. Node looks up the target event ID from the r tag
2. Node writes SMT[target_event_id] = update_event_id
3. If a subsequent Update targets the same original event, the SMT entry is overwritten

The SMT always stores the most recent Update event ID for each target. Clients can follow the chain by querying the Update event, which contains the new content.

Update Lookup:

All Update events target the original Content Event, not previous Updates. The SMT stores only one entry per original event, always pointing to the most recent Update. No chain following is needed — one SMT lookup returns the latest content.

Concurrent Updates in Bundle:

If multiple Updates target the same original event within one bundle, they are processed serially by seq order. Each Update overwrites the previous SMT entry. Only the last Update's event_id is stored in SMT after the bundle closes.

Empty Content:

An Update event with content: "" (empty string) is valid. This clears the content while preserving the update chain. Use case: author wants to retract content but preserve the event record.

Authorization

The node checks U permission against the target event's type, not Update. For example, if the schema grants Self the U permission for Chat_Message, only the original author can update their own messages.

Update Target Validation

The node MUST reject Update if:

• Target event does not exist
• Target event is a Delete or Update event (U/D events cannot be U/D'd)
• Target event is an AC Event
• Target event is already deleted (has Delete status in SMT)

Updating an Already-Updated Event:

Updating an event that was previously updated is allowed. The new Update supersedes the previous one — the SMT entry is overwritten with the new Update's event_id. The target MUST always be the original Content Event, not any intermediate Update event.

Delete

A Delete event marks a previously finalized event as logically deleted.

Type: Delete

Structure

Content fields:

Semantics

• The target event MUST be a Content Event (AC events cannot be deleted)
• The target event (referenced by r tag) is marked as deleted in the Enclave State SMT
• The original content SHOULD be deleted by the node (best-effort, no guarantee)
• Only identities with D permission for the target event's type can issue a Delete
• Delete events provide a verifiable audit trail of who deleted content and why

Authorization

The node checks D permission against the target event's type, not Delete. For example, if the schema grants Self the D permission for Chat_Message, only the original author can delete their own messages.

Self Evaluation Example:

If schema defines:

{ "event": "Chat_Message", "role": "Self", "ops": ["D"] }

Alice (id_alice) can delete a Chat_Message only if target_event.from == id_alice. The Self role matches the target event's author, not the Delete event's sender (which should be the same for this to succeed).

If the schema also grants Admin the D permission:

{ "event": "Chat_Message", "role": "Admin", "ops": ["D"] }

An Admin can delete any Chat_Message regardless of authorship. The Self entry only applies when the actor's identity matches the target event's from.

Delete Target Validation

The node MUST reject Delete if:

• Target event does not exist
• Target event is a Delete or Update event (U/D events cannot be U/D'd)
• Target event is an AC Event
• Target event is already deleted

Deleting an Already-Updated Event:

Deleting an event that was previously updated is allowed. Delete targets the original Content Event, and the SMT status changes from "updated" to "deleted". All associated Update events become orphaned — they remain in the log but reference a deleted event. Clients querying the original event will see "deleted" status.

AC Events

AC (Access Control) events modify the RBAC state or lifecycle of an enclave. All AC event types are predefined by the ENC protocol and understood by the node.

RBAC Events

Events that modify role assignments (stored in SMT):

Lifecycle Events

Events that control enclave state (see Enclave Lifecycle):

Lifecycle state is derived from the event log, not stored in SMT.

AC Event Authorization

For Grant, Grant_Push, Revoke, Revoke_Self:

1. Check actor has C permission for the event type
2. Check content.role is in target_roles for that schema entry

This prevents privilege escalation — an Admin with target_roles: ["Member"] cannot grant the Admin role.

Idempotent behavior:

• Grant a role the identity already has: succeeds (no-op, SMT unchanged)
• Revoke a role the identity doesn't have: succeeds (no-op, SMT unchanged)

Revoke vs Revoke_Self:

• Revoke — actor revokes a role from another identity; requires C permission for Revoke with matching target_roles
• Revoke_Self — actor revokes a role from themselves; requires C permission for Revoke_Self; identity is implicit (taken from from field)

Revoke_Self exists to allow members to leave voluntarily without needing permission to revoke others. An Admin with Revoke permission could also use Revoke targeting themselves, but Revoke_Self provides a more limited permission for self-removal only.

Owner Cannot Self-Revoke:

Revoke_Self MUST NOT target the Owner role. The node MUST reject Revoke_Self where content.role = "Owner". An enclave must always have an Owner for governance. Use Transfer_Owner to change ownership, or Terminate to end the enclave.

Error Response:

{ "type": "Error", "code": "OWNER_SELF_REVOKE_FORBIDDEN", "message": "Owner role cannot be self-revoked" }

Revoke_Self Last Role:

If Revoke_Self removes the identity's last role, the SMT leaf is removed (bitmask = 0). Any active P/N delivery registered via Grant_Push stops. The identity becomes "not in tree" (same as if never granted).

Grant_Push specifics:

• Grants the role (same as Grant) AND registers the endpoint for P/N delivery
• If the identity already has a Grant_Push for this role, the new endpoint supersedes the previous
• The endpoint is operational state (not stored in SMT); node maintains an internal lookup table
• Use standard Revoke to remove the role and stop push delivery

Grant_Push to Existing Role Holder:

If the identity already has the role (from Grant or previous Grant_Push):

• The role assignment is a no-op (identity already has role)
• The endpoint IS registered/updated (endpoint state is separate from RBAC state)
• Use case: Owner wants to add push delivery to an existing member

Endpoint Storage and Migration:

Node maintains two internal data structures:

1. Endpoint lookup table: (identity, role) → endpoint - Maps role assignments to webhook endpoints - Reconstructed during migration by replaying Grant_Push events - Only the most recent Grant_Push for each (identity, role) pair is active

1. Delivery queue: (identity, url) → event queue - Aggregates events from all enclaves where identity has P/N permission at this endpoint - Each queue has its own push_seq counter - See node-api.md for delivery semantics

The lookup table determines WHERE to deliver; the queue aggregates WHAT to deliver.

Endpoint Supersession Semantics:

When Grant_Push registers a new endpoint for an already-held role:

1. Node immediately updates lookup table: (identity, role) → new_endpoint
2. Events finalized AFTER the Grant_Push use the new endpoint
3. Events already queued for old endpoint — deliver to old endpoint (not redirected)
4. In-flight deliveries complete independently; failures are not retried to new endpoint

The switch is immediate upon finalization — no grace period. Recipients MUST be idempotent and use push_seq to detect gaps during endpoint transitions.

Endpoint URL Requirements:

• MUST be a valid absolute URL per RFC 3986
• Scheme MUST be https or wss (no plaintext HTTP/WS)
• Host MUST be a valid domain name or IP address
• Nodes MAY reject private/reserved IP ranges (10.x, 192.168.x, 127.x) for security
• Maximum URL length: 2048 characters
• Node validates URL syntax at grant time; reachability is NOT checked
• Invalid URL → reject with error INVALID_ENDPOINT_URL

Grant_Push Atomicity:

Grant_Push is atomic: if endpoint URL validation fails, the entire operation fails (no RBAC change). The role is only granted if the endpoint is successfully registered.

For Move:

1. Check actor has C permission for Move
2. Check target identity's current bitmask equals content.from (reject if mismatch)
3. Check all roles in content.to are within actor's target_roles

The from field in Move content records the previous state, enabling role history tracking and restoration.

Move to Zero Bitmask:

Move with content.to = 0x0 is allowed. This atomically removes all roles from the identity (equivalent to revoking all roles at once). The SMT leaf is removed. Use case: demote an identity to no roles in a single operation.

Bitmask Mismatch Error:

If Move or Force_Move fails due to bitmask mismatch, the error response includes both values:

{ "type": "Error", "code": "BITMASK_MISMATCH", "expected": "0x...", "actual": "0x..." }

For Force_Move:

1. Check actor has C permission for Force_Move (typically Owner only)
2. Check target identity's current bitmask equals content.from (reject if mismatch)
3. Check neither content.from nor content.to includes the Owner bit (cannot touch Owner role)
4. No target_roles restriction — can move to any non-Owner role

If step 3 fails, reject with: { "type": "Error", "code": "OWNER_BIT_PROTECTED", "message": "Owner role cannot be modified by Force_Move" }

Force_Move is intended for emergency situations where normal RBAC hierarchy is insufficient.

For Transfer_Owner:

1. Check actor is current Owner
2. Atomically: remove Owner role from actor, grant Owner role to new_owner

Transfer_Owner is irreversible — the new owner would need to transfer back.

Self-Transfer:

If Transfer_Owner specifies new_owner equal to the current Owner, the operation succeeds as a no-op (idempotent). No SMT changes occur.

New Owner with Existing Roles:

If new_owner already has roles (e.g., Admin + Member), Transfer_Owner adds the Owner bit to their existing roles. The operation is: new_owner.roles |= Owner. Existing roles are preserved.

Transfer_Owner vs Migrate:

Transfer_Owner changes WHO can issue Migrate, Pause, etc. It does NOT change the sequencer node. The sequencer public key remains the same; only the Owner role is reassigned. No Registry update is required.

Contrast with Migrate: changes the sequencer node, DOES require Reg_Enclave update.

AC_Bundle Content

{
  "operations": [
    { "type": "Grant", "role": "Member", "identity": "<id_pub_1>" },
    { "type": "Grant", "role": "Member", "identity": "<id_pub_2>" },
    { "type": "Revoke", "role": "Member", "identity": "<id_pub_3>" }
  ]
}

Allowed operation types:

• Grant
• Grant_Push
• Revoke
• Revoke_Self
• Move
• Force_Move

Operation Fields by Type:

Not allowed in AC_Bundle:

• Transfer_Owner (must be explicit, not bundled)
• Lifecycle events (Pause, Resume, Terminate, Migrate)

Size Limit:

The protocol does not define a maximum number of operations per AC_Bundle. Nodes MAY impose implementation-defined limits for resource protection (e.g., 1000 operations). Clients SHOULD handle rejection gracefully and split large bundles if needed.

Processing:

• Operations are processed in order
• If any operation fails authorization, the entire bundle is rejected
• Rejection response SHOULD indicate which operation (index) failed

Authorization Timing:

Each operation in an AC_Bundle is authorized against the state AFTER all preceding operations in the bundle have been applied. This enables dependent operations:

{
  "operations": [
    { "type": "Grant", "role": "Member", "identity": "<id>" },
    { "type": "Move", "identity": "<id>", "from": "0x200000000", "to": "0x300000000" }
  ]
}

Here, the Move operation sees the state after Grant, so it can move the identity that was just granted a role.

Atomicity (Simulated Sequential Validation):

AC_Bundle uses simulated sequential validation:

1. Node creates a copy of current SMT state
2. For each operation in order: authorize against simulated state, then apply to simulated state
3. If all operations pass, apply all changes to real SMT atomically

If any operation fails:

• The entire bundle is rejected
• No SMT changes occur
• Error response includes: { "type": "Error", "code": "AC_BUNDLE_FAILED", "failed_index": N, "reason": "..." }

Concurrency Note (TOCTOU):

Between client simulation and node application, other commits may change RBAC state. The protocol does NOT guarantee that a successfully-simulated AC_Bundle will succeed when submitted. Clients MUST:

• Treat simulation as advisory (preview, not guarantee)
• Implement retry logic if state changed between simulation and submission
• Use SMT proofs to verify final state after Receipt

Wildcard Validation:

Operations in AC_Bundle MUST specify explicit event types (Grant, Revoke, etc.). Wildcard patterns (*) are NOT allowed in operation type fields — wildcards apply only to schema entries for P/N delivery.

Content Events

Content Events are application-defined event types that carry data without affecting enclave state.

Characteristics:

• Defined in the RBAC schema (not predefined by the protocol)
• Do not modify RBAC state or enclave lifecycle
• Can be Updated or Deleted (if schema permits)
• Examples: Chat_Message, Post, Comment, Reaction

Identifying Content Events:

An event is a Content Event if and only if its type is NOT one of the predefined AC event types:

• Manifest, Grant, Grant_Push, Revoke, Revoke_Self, Move, Force_Move, Transfer_Owner, AC_Bundle
• Pause, Resume, Terminate, Migrate
• Update, Delete

Any other type value (e.g., Chat_Message, Post) is a Content Event. This is determined by string comparison against the predefined list — no schema lookup is needed.

Schema example:

{ "event": "Chat_Message", "role": "Member", "ops": ["C", "R"] },
{ "event": "Chat_Message", "role": "Self", "ops": ["U", "D"] }

8. Registry

The Registry is a special enclave that maps Enclave IDs to the Node endpoints that host them, and may optionally attach descriptive metadata.

Purpose

• Service discovery: resolve enclave_id → node(s)
• Identity resolution: resolve id_pub → enclave(s)
• Context lookup: understand what an enclave represents

Registry Record

A registry entry MAY include:

• enclave_id — canonical enclave identifier
• nodes — hosting node endpoints or identifiers
• app (optional) — application that created or uses the enclave
• creator (optional) — identity key that initialized the enclave
• desc (optional) — human-readable description
• meta (optional) — application-defined metadata

Trust Model

• Sequencer discovery: Registry is authoritative. Clients MUST use Registry to discover the current sequencer.
• Enclave metadata: Registry is advisory. Clients SHOULD verify enclave proofs independently.

Event Category

Reg_Node, Reg_Enclave, and Reg_Identity are Content Events within the Registry enclave. They can be Updated (to change metadata) or Deleted (to deregister) per the Registry's RBAC schema.

Update Mechanism

The Registry maintains one active entry per resource:

• Reg_Node: keyed by seq_pub
• Reg_Enclave: keyed by enclave_id
• Reg_Identity: keyed by id_pub

A new submission supersedes any existing entry for the same key. The old entry is automatically marked as updated in SMT (no explicit Update event needed).

Registry-Specific Behavior:

This implicit update is a Registry-only exception. The Registry node internally marks old entries as updated in SMT when a new entry for the same key is submitted. Normal enclaves require explicit Update events to modify event status.

SMT Update Entry:

When a new Reg_Node, Reg_Enclave, or Reg_Identity supersedes an existing entry:

• SMT entry for old event: SMT[old_event_id] = new_event_id
• This follows the same pattern as explicit Update events

Clients can query the old event ID and discover it was superseded, then follow the chain to the current entry.

Implementation Note:

The Registry node maintains a secondary index: key → current_event_id. On new submission:

1. Look up existing event for this key
2. If exists, write SMT[old_event_id] = new_event_id
3. Update index to point to new event

This is internal to Registry operation — the SMT update follows normal semantics.

Querying Registry:

Clients query Registry by key (seq_pub for nodes, enclave_id for enclaves, id_pub for identities). The Registry returns the latest active entry for that key. Historical entries are available in the event log but superseded entries are marked as updated in SMT.

Registry Schema

The Registry uses a minimal RBAC schema:

{
  "enc_v": 1,
  "RBAC": {
    "use_temp": "none",
    "schema": [
      { "event": "*", "role": "Any", "ops": ["R"] },
      { "event": "*", "role": "DataView", "ops": ["P"] },
      { "event": "Reg_Node", "role": "Any", "ops": ["C"] },
      { "event": "Reg_Node", "role": "Self", "ops": ["U", "D"] },
      { "event": "Reg_Enclave", "role": "Any", "ops": ["C"] },
      { "event": "Reg_Enclave", "role": "Self", "ops": ["U", "D"] },
      { "event": "Reg_Identity", "role": "Any", "ops": ["C"] },
      { "event": "Reg_Identity", "role": "Self", "ops": ["U", "D"] },
      { "event": "Grant_Push", "role": "Owner", "ops": ["C"], "target_roles": ["DataView"] },
      { "event": "Revoke", "role": "Owner", "ops": ["C"], "target_roles": ["DataView"] },
      { "event": "Transfer_Owner", "role": "Owner", "ops": ["C"] },
      { "event": "Pause", "role": "Owner", "ops": ["C"] },
      { "event": "Resume", "role": "Owner", "ops": ["C"] },
      { "event": "Terminate", "role": "Owner", "ops": ["C"] }
    ],
    "initial_state": {
      "Owner": ["<registry_owner_id>"],
      "DataView": [{ "identity": "<dataview_identity>", "endpoint": "<dataview_url>" }]
    }
  }
}

Authorization rules:

• Anyone can read all events (* wildcard R)
• DataView receives all events via Push (* wildcard P) to serve the REST API
• Anyone can submit Reg_Node (signed by seq_pub)
• Anyone can submit Reg_Enclave (signed by enclave creator)
• Anyone can submit Reg_Identity (signed by id_pub)
• Only the original submitter can Update or Delete their own entries
• Self for Reg_Node is evaluated against content.seq_pub
• Self for Reg_Enclave is evaluated against content.manifest_event.from
• Self for Reg_Identity is evaluated against content.id_pub
• Owner can Grant_Push / Revoke the DataView role (manage endpoints)
• Owner can create lifecycle events (Transfer_Owner, Pause, Resume, Terminate)

Strict Self-Authorization:

For Reg_Node: the commit's from field MUST equal content.seq_pub. One identity cannot register another node.

For Reg_Enclave: the commit's from field MUST equal content.manifest_event.from. One identity cannot register another's enclave.

For Reg_Identity: the commit's from field MUST equal content.id_pub. One identity cannot register enclaves for another.

Reg_Enclave and Ownership Transfer:

The Registry tracks the original creator (manifest_event.from) as the default authorized identity. However, after Transfer_Owner, the new Owner can update the Registry by providing an owner_proof.

Update Scenarios:

See the Authorization section in Reg_Enclave for verification details.

Registry Governance

Registry Owner:

The registry_owner_id is the identity operating the Registry service. In the current centralized design:

• The Registry Owner is a fixed, well-known identity (e.g., protocol operator)
• The Registry Owner has standard Owner powers: can Transfer_Owner, Pause, Resume, Terminate
• The Registry Owner does NOT have special powers over individual Reg_Node/Reg_Enclave/Reg_Identity entries — those are controlled by their respective Self identities

Notes:

• Current design is centralized; future versions may be decentralized.

The Process of Registry

1. Node Register: The node should register seq_pub and domain / IP on the registry with Reg_Node. If both domain and Ip is set, first resolve IP then the domain
2. Create Enclave: The client send manifest to the node, and get receipt with sequencer, then the client knows who is hosting the enclave
3. Enclave Register: Then the client can send the finalized event as content of the register commit (event type predefined as Reg_Enclave). And the registry will check the sig = event.sig in content. If it comes from the same signer, registry will accept this register
4. Identity Register: The client registers its enclaves via Reg_Identity, mapping id_pub → enclaves. The commit must be signed by id_pub. This is optional but enables discovery of an identity's enclaves

Reg_Node

Type: Reg_Node

Purpose: Register a node in the Registry for discovery.

Content Structure

{
  "seq_pub": "<node's sequencer public key>",
  "endpoints": [
    {
      "uri": "https://node.example.com: 443",
      "priority": 1
    },
    {
      "uri": "https://1.2.3.4: 443",
      "priority": 2
    }
  ],
  "protocols": ["https", "wss"],
  "enc_v": 1
}

Fields

Validation Limits

Nodes MUST reject Reg_Node commits exceeding these limits.

Authorization

• The commit MUST be signed by seq_pub (proves ownership)
• from field MUST equal seq_pub

Update/Deregister

• To update: submit new Reg_Node (replaces previous)
• To deregister: submit Delete event referencing the Reg_Node event

Reg_Enclave

Type: Reg_Enclave

Purpose: Register an enclave in the Registry for discovery.

Content Structure

{
  "manifest_event": {
    "id": "<event_id>",
    "hash": "<commit_hash>",
    "enclave": "<enclave_id>",
    "from": "<creator_id_pub>",
    "type": "Manifest",
    "content": "...",
    "exp": 1706000000000,
    "tags": [],
    "timestamp": 1706000000000,
    "sequencer": "<sequencer_id_pub>",
    "seq": 0,
    "sig": "<creator_signature>",
    "seq_sig": "<sequencer_signature>"
  },
  "owner_proof": {
    "sth": {
      "t": 1706000000000,
      "ts": 500,
      "r": "<ct_root_hex>",
      "sig": "<sth_signature_hex>"
    },
    "ct_proof": {
      "ts": 500,
      "li": 499,
      "p": ["<hex64>", ...]
    },
    "state_hash": "<hex64>",
    "events_root": "<hex64>",
    "smt_proof": {
      "k": "<hex42>",
      "v": "<hex64>",
      "b": "<hex42>",
      "s": ["<hex64>", ...]
    }
  },
  "app": "my-chat-app",
  "desc": "A group chat for project X",
  "meta": {}
}

Fields

Owner Proof Structure

The owner_proof field allows the current Owner to submit Reg_Enclave even if they are not the original creator. This is required after Transfer_Owner when the new Owner needs to update the Registry.

Authorization

The Reg_Enclave commit can be authorized in two ways:

Path 1: Original Creator (no owner_proof)

• from field MUST equal manifest_event.from
• Registry verifies manifest_event.sig is valid

Path 2: Current Owner (with owner_proof)

• from field MAY differ from manifest_event.from
• owner_proof field MUST be present and valid
• Registry verifies the submitter currently holds the Owner bit

Manifest Signature Verification (both paths):

The manifest_event.sig signs the Manifest commit hash:

_content_hash = sha256(utf8_bytes(manifest_event.content))
commit_hash = H(0x10, enclave_id, from, "Manifest", _content_hash, exp, tags)
verify: schnorr_verify(commit_hash, manifest_event.sig, manifest_event.from)

Owner Proof Verification (Path 2 only):

1. Verify STH signature:

   message = "enc:sth:" || be64(sth.t) || be64(sth.ts) || hex_decode(sth.r)
   verify: schnorr_verify(sha256(message), sth.sig, manifest_event.sequencer)

1. Verify CT inclusion: - Compute leaf hash: H(0x00, events_root, state_hash) - Verify CT inclusion proof against sth.r using RFC 9162 algorithm - This binds state_hash to the signed tree

1. Verify SMT proof: - Compute expected key: 0x00 || sha256(from)[0:160 bits] (RBAC namespace, 21 bytes total) - Verify smt_proof.k equals expected key - Verify SMT proof against state_hash - Verify smt_proof.v has Owner bit (bit 1) set

1. Verify enclave binding: - The manifest_event.enclave MUST match the enclave ID in Registry lookup - This prevents using an owner proof from a different enclave

Post-Migration Updates:

After migration, the sequencer changes. To update Registry after migration:

1. Include the migrate_event field in owner_proof:

   {
     "owner_proof": {
       "migrate_event": {
         "id": "<migrate_event_id>",
         "type": "Migrate",
         "content": { "new_sequencer": "<new_sequencer_pub>", ... },
         "sequencer": "<new_sequencer_pub>",
         "seq_sig": "<new_sequencer_signature>",
         ...
       },
       "sth": { ... },
       "ct_proof": { ... },
       ...
     }
   }

1. Registry verifies the Migrate event: - migrate_event.content.new_sequencer = new sequencer public key - migrate_event.seq_sig is valid signature by new sequencer - migrate_event.enclave matches manifest_event.enclave

1. STH signature is verified against migrate_event.sequencer (new sequencer)

Chained Migrations:

If multiple migrations occurred, only the most recent migrate_event is needed. The new sequencer's STH authenticates the current state, which includes the full history.

• The manifest_event provides enclave identity and original creator
• The migrate_event (if present) proves sequencer transition
• The SMT proof proves current Owner status
• All three are cryptographically bound via signatures

Derived Fields

Registry extracts:

• enclave_id = manifest_event.enclave
• sequencer = owner_proof.migrate_event.content.new_sequencer if migrate_event is present, otherwise manifest_event.sequencer
• creator = manifest_event.from

Update/Deregister

• To update metadata: submit new Reg_Enclave (replaces previous)
• To deregister: submit Delete event referencing the Reg_Enclave event

Reg_Identity

Type: Reg_Identity

Purpose: Register an identity's enclaves in the Registry for discovery.

Content Structure

{
  "id_pub": "a1b2c3...",
  "enclaves": {
    "personal": "<enclave_id>",
    "dm": "<enclave_id>"
  }
}

Fields

Enclaves Map

The enclaves field is a free-form map of string keys to enclave IDs. Applications use this to associate named enclaves with an identity.

Common keys:

• personal — the identity's personal enclave (see Appendix A)

The map is application-defined; the Registry stores but does not interpret the keys.

Validation Limits

Nodes MUST reject Reg_Identity commits exceeding these limits.

Authorization

• The commit MUST be signed by id_pub (proves key ownership)
• from field MUST equal id_pub

Update/Deregister

• To update: submit new Reg_Identity with same id_pub (replaces previous)
• To deregister: submit Delete event referencing the Reg_Identity event

9. Migration

Migration transfers an enclave from one node to another while preserving the full event history and enclave identity.

Migrate Event

Type: Migrate

Content Structure:

{
  "new_sequencer": "<new_seq_pub>",
  "prev_seq": 1234,
  "ct_root": "<ct_root_at_prev_seq>"
}

Fields:

Authorization:

• Only Owner can issue Migrate
• The commit MUST be signed by Owner

Migration Barrier:

Once a node accepts a Migrate commit:

• The node MUST reject all other pending commits
• The Migrate event MUST be the final event from this sequencer
• No concurrent commits are allowed during migration
• The node MUST immediately close the current bundle after finalizing Migrate

Bundle Handling:

The Migrate event does NOT need to be alone in its bundle. Events accepted before the Migrate commit may be in the same bundle. The bundle closes immediately after Migrate is finalized, regardless of bundle.size or bundle.timeout configuration.

Example with bundle.size = 10:

• Events seq=100-105 are in an open bundle
• Migrate commit arrives, finalized as seq=106
• Bundle closes immediately with events seq=100-106
• No events seq=107+ are possible from this sequencer

This ensures a clean handoff with no ambiguity about which events belong to which sequencer.

Migration Modes

Peaceful Handoff (old node online):

1. Owner submits Migrate commit to old node
2. Old node finalizes Migrate as the last event
3. Old node transfers full event log to new node
4. New node verifies log matches ct_root
5. New node continues sequencing; next event will be seq = prev_seq + 2 (Migrate event was prev_seq + 1)
6. Owner updates Registry (Reg_Enclave)

Forced Takeover (old node offline):

1. Owner or Backup has a copy of the event log
2. Owner signs Migrate commit (unfinalized)
3. Owner submits log + unfinalized commit to new node
4. New node verifies log integrity (see verification below)
5. New node finalizes the Migrate event (special case)
6. New node becomes the sequencer
7. Owner updates Registry (Reg_Enclave)

In forced mode, the sequencer field of the Migrate event will be the NEW node, not the old one. This is the only event type where sequencer discontinuity is allowed.

Forced Takeover Verification:

Before finalizing Migrate, the new node MUST rebuild state from scratch:

1. Replay all events from the log, computing SMT state after each state-changing event
2. Verify computed SMT root matches state_hash in final bundle
3. Verify the from field of the Migrate commit has Owner bit set in the computed SMT (RBAC namespace)
4. Recompute CT root — MUST match ct_root in Migrate commit
5. Verify commit signature (sig) is valid for the computed commit hash
6. Verify prev_seq equals the last event's sequence number in the log

If any check fails, the new node MUST reject the migration. This full replay ensures the new node has a correct, verified copy of enclave state.

Checkpoint Verification

The ct_root field serves as a checkpoint:

• CT root commits to both the event log AND state (via state_hash in leaves)
• New node recomputes CT root from received log
• If mismatch, migration is rejected

Split-Brain Prevention

After migration:

• Old node's sequencer key is no longer valid
• Any events finalized by old node after Migrate are invalid
• Registry is authoritative for sequencer discovery
• Clients SHOULD check Registry periodically

Client Recovery after Migrate:

If a client queries the old node after Migrate:

1. Old node MAY still serve read requests (CT proofs, state proofs) — data is valid
2. Old node MUST reject new commits (new sequencer handles writes)
3. Client discovers migration via Registry lookup or ENCLAVE_NOT_FOUND on commit
4. Client migrates to new node for subsequent operations

No explicit "migrated" error is required on reads; normal operation continues until the client syncs with Registry.

Backup Pattern

To enable forced takeover, ensure someone has the full event log:

Option 1: Owner maintains backup

• Owner's client stores all events locally

Option 2: Dedicated Backup role

• Define a custom role with P (Push) permission for all event types
• Assign to a backup service

Schema example:

{ "event": "*", "role": "Backup", "ops": ["P"] }

The wildcard * means Backup receives push for ALL event types. This enables disaster recovery if the node goes offline.

• Forced takeover is blocked (intentional security — only Owner can authorize sequencer changes)
• Mitigation: ensure Owner's client/key is highly available, or use Transfer_Owner before sequencer goes offline

10. Node API

TODO: Endpoints and request formats assigned to Tomo

Error Response Format

When a node rejects a commit or request, it MUST return an error response:

{
  "type": "Error",
  "code": "<ERROR_CODE>",
  "message": "<human-readable description>",
  ...additional fields specific to the error...
}

Defined Error Codes:

11. Templates

Predefined RBAC templates for common enclave patterns.

When use_temp is set in Manifest content, the node uses the referenced template instead of the explicit schema field.

v1 Scope:

In ENC v1, only none is supported. Additional templates (e.g., chat, forum, personal) are planned for future versions. Nodes MUST reject Manifests with unrecognized use_temp values. For the recommended personal enclave schema using explicit none template, see Appendix A.

Appendix A: Design Patterns

This section is non-normative. It describes common usage patterns, not protocol requirements.

Shared Enclave

A Shared Enclave is an enclave whose data and access-control are intended to be jointly used by multiple identities.

Typical characteristics

• Multi-writer / multi-reader by design
• RBAC is centered on group roles (e.g., Admin/Member/Moderator)
• Data is considered collective (not owned by a single identity)

Examples

• Group chat enclave
• A protocol-level registry/directory enclave
• DAO / project coordination enclave
• Shared public feed with moderators

Personal Enclave

A Personal Enclave is an enclave whose data is logically owned and controlled by a single identity, even if many others can read or contribute under permission.

Typical characteristics

• A single "owner" identity is the final authority for RBAC and lifecycle
• Designed for portable identity-scoped data with a unified API
• Others may write into it (e.g., comments, reactions) but the enclave remains owner-governed

Examples

• A user's posts / profile / settings enclave
• A user's inbox / notifications enclave
• Personal "data vault" enclave used across apps

Recommended RBAC Schema

The RBAC schema is fixed at Manifest creation. Rather than defining a specific event type per content type (which would require a new enclave to add content types), the schema groups event types by access pattern — who can write and who can read. New content types (e.g., adding bookmark or reaction) only require defining a new kind under the appropriate access pattern, not modifying the enclave's RBAC schema.

Three access patterns cover all personal enclave use cases:

Full schema:

{
  "enc_v": 1,
  "RBAC": {
    "use_temp": "none",
    "schema": [
      { "event": "public", "role": "Owner", "ops": ["C", "U", "D"] },
      { "event": "public", "role": "Any", "ops": ["R"] },
      { "event": "public", "role": "DataView", "ops": ["P"] },
      { "event": "private", "role": "Owner", "ops": ["C", "R", "U", "D"] },
      { "event": "inbox", "role": "Any", "ops": ["C"] },
      { "event": "inbox", "role": "Owner", "ops": ["R", "D"] },
      { "event": "inbox", "role": "DataView", "ops": ["P"] },
      { "event": "Grant", "role": "Owner", "ops": ["C"], "target_roles": ["DataView"] },
      { "event": "Grant_Push", "role": "Owner", "ops": ["C"], "target_roles": ["DataView"] },
      { "event": "Revoke", "role": "Owner", "ops": ["C"], "target_roles": ["DataView"] },
      { "event": "Transfer_Owner", "role": "Owner", "ops": ["C"] },
      { "event": "Terminate", "role": "Owner", "ops": ["C"] },
      { "event": "Pause", "role": "Owner", "ops": ["C"] },
      { "event": "Resume", "role": "Owner", "ops": ["C"] }
    ]
  }
}

Design notes:

• public events are readable by anyone — suitable for posts, profile, and follow lists
• private events are readable only by the Owner — suitable for configuration, block lists, and muted users
• inbox events are writable by anyone but readable only by the Owner — suitable for DM requests and incoming messages. The Owner can Delete inbox events to clean up
• The schema is fixed at Manifest creation. New content types are added via the kind convention (below), not by modifying the schema

Content kind Convention

Since the RBAC schema defines only 3 broad event types, applications distinguish content subtypes using a kind field inside content:

{
  "kind": "post",
  "text": "Hello world",
  "created_at": 1706000000000
}

Recommended kinds by event type:

The kind field is application-defined — the node does not validate it. Applications MAY define additional kinds as needed.

Registration

After creating a personal enclave, the owner SHOULD register their identity via Reg_Identity (see Section 8) with the enclaves.personal field pointing to the personal enclave. This enables other users to discover the enclave by public key:

id_pub → Reg_Identity → enclaves.personal → enclave_id → Reg_Enclave → node

How to Choose

Use Shared when:

• The enclave represents a group object (a room, project, DAO, registry)
• Governance and policy must be collective or moderator-driven
• Many identities are primary contributors

Use Personal when:

• The enclave represents identity-scoped state (my profile, my posts, my inbox)
• You want data to be portable across apps
• One identity should remain the owner-of-record

DM (Direct Message)

DM is a messaging pattern built on personal enclaves, not a shared conversation enclave.

Each identity maintains a personal mailbox enclave that receives incoming messages.

How it works

• Alice sends a message event to Bob's personal enclave
• Bob replies by sending a message event to Alice's personal enclave
• Bob's client MAY also store a local copy of his outgoing reply in Bob's own enclave

Properties

• Messages are asymmetric by default (each direction is a separate write)
• Each participant maintains a complete local history inside their own enclave
• Ownership and RBAC are enforced per enclave, independently
• No shared or mutually-owned log is required

Implication

DM is modeled as:

> "write into the recipient's enclave, optionally mirror into the sender's enclave"

—not:

> "append to a shared conversation log"

Important Note

There is no mandatory "type" field. You MAY include a hint in metadata (e.g., meta.enclave_kind = "shared" | "personal"), but clients must not rely on it for security decisions.

Appendix B: Event Type Registry

Machine-readable registry of predefined event types. Content Events are any type NOT in this list.

{
  "version": 1,
  "predefined_types": {
    "ac_events": [
      "Manifest",
      "Grant",
      "Grant_Push",
      "Revoke",
      "Revoke_Self",
      "Move",
      "Force_Move",
      "Transfer_Owner",
      "AC_Bundle"
    ],
    "lifecycle_events": [
      "Pause",
      "Resume",
      "Terminate",
      "Migrate"
    ],
    "mutation_events": [
      "Update",
      "Delete"
    ],
    "registry_events": [
      "Reg_Node",
      "Reg_Enclave",
      "Reg_Identity"
    ]
  }
}

Usage:

To determine if an event is a Content Event:

is_content_event = type NOT IN predefined_types.ac_events
                   AND type NOT IN predefined_types.lifecycle_events
                   AND type NOT IN predefined_types.mutation_events

This registry is authoritative for ENC v1. Future protocol versions may extend this list.

Node API

REST and WebSocket endpoints, proof retrieval, webhook delivery, sessions, filters, encryption.

Node API

REST and WebSocket API for ENC protocol nodes.

Table of Contents

API

1. Overview
2. Enclave API
3. WebSocket API
4. Proof Retrieval API
5. Webhook Delivery
6. Registry DataView API

Appendix

• A. Session
• B. Filter
• C. Encryption
• D. Error Codes
• E. Push/Notify

Overview

Base URL

https://<node_host>/

Content Type

All requests and responses use application/json.

Authentication

Endpoints Summary

Enclave API (all enclaves):

Request types: Commit, Query, Pull

Proof Retrieval API:

Registry DataView API (Registry enclave only):

Enclave API

POST / (Commit)

Submit a commit to the enclave.

Detection: Request contains exp field.

Request:

{
  "hash": "<hex64>",
  "enclave": "<hex64>",
  "from": "<hex64>",
  "type": "<string>",
  "content": "<any>",
  "exp": 1706000000000,
  "tags": [["key", "value"]],
  "sig": "<hex128>"
}

Response (200 OK): Receipt

{
  "type": "Receipt",
  "id": "<hex64>",
  "hash": "<hex64>",
  "timestamp": 1706000000000,
  "sequencer": "<hex64>",
  "seq": 42,
  "sig": "<hex128>",
  "seq_sig": "<hex128>"
}

Errors:

POST / (Query)

Query events from the enclave.

Detection: Request contains type: "Query" field.

Request:

{
  "type": "Query",
  "enclave": "<hex64>",
  "from": "<hex64>",
  "content": "<encrypted>"
}

Content (plaintext):

{
  "session": "<hex136>",
  "filter": { ... }
}

Response (200 OK):

{
  "type": "Response",
  "content": "<encrypted>"
}

Response Content (plaintext):

{
  "events": [
    { "event": Event, "status": "active" },
    { "event": Event, "status": "updated", "updated_by": "<hex64>" },
    ...
  ]
}

Errors:

WebSocket API

Real-time pub/sub for event subscriptions.

Endpoint: wss://<node_host>/

Subscription is automatic: First valid Query on a connection creates a subscription. Node assigns sub_id and begins streaming events.

Connection Model

Client → Node

Node → Client

Event (stored or live):

{
  "type": "Event",
  "sub_id": "<string>",
  "event": "<encrypted>"
}

End of Stored Events:

{
  "type": "EOSE",
  "sub_id": "<string>"
}

Write Success: Receipt (same as HTTP)

{
  "type": "Receipt",
  "id": "<hex64>",
  "hash": "<hex64>",
  "timestamp": 1706000000000,
  "sequencer": "<hex64>",
  "seq": 42,
  "sig": "<hex128>",
  "seq_sig": "<hex128>"
}

Write Error:

{
  "type": "Error",
  "code": "<CODE>",
  "message": "<reason>"
}

Subscription Closed:

{
  "type": "Closed",
  "sub_id": "<string>",
  "reason": "<reason_code>"
}

Closed Reasons:

Notice:

{
  "type": "Notice",
  "message": "<string>"
}

Node Processing

On Query:

1. Verify session (same as HTTP)
2. Check AC (read permission)
3. Generate sub_id, store subscription
4. Send matching events as Event messages (encrypted)
5. Send EOSE message
6. On new events matching filter → push Event to client

On Commit:

Same as HTTP, returns Receipt.

On Close:

Remove subscription. Terminate connection if none remain.

Connection Lifecycle

Termination conditions:

• All subscriptions closed by client
• All sessions expired
• All access revoked
• Client disconnects

Multi-key support:

• One connection, multiple identities (from)
• Each identity has own session
• Session expiry only affects that identity's subscriptions

HTTP vs WebSocket

Proof Retrieval API

Endpoints for retrieving cryptographic proofs. Used by clients to verify events and state.

Access Control:

STH (Signed Tree Head)

GET /:enclave/sth

Returns the current signed tree head. Public endpoint for auditing.

Response (200 OK):

{
  "t": 1706000000000,
  "ts": 1000,
  "r": "<hex64>",
  "sig": "<hex128>"
}

See proof.md for STH structure and verification.

Consistency Proof

GET /:enclave/consistency?from=<tree_size>&to=<tree_size>

Returns consistency proof between two tree sizes. Public endpoint for auditing.

Response (200 OK):

{
  "ts1": 500,
  "ts2": 1000,
  "p": ["<hex64>", ...]
}

See proof.md for verification algorithm.

Errors:

Inclusion Proof

POST /inclusion

Returns inclusion proof for a bundle. Requires R permission.

Request:

{
  "type": "Inclusion_Proof",
  "enclave": "<hex64>",
  "from": "<hex64>",
  "content": "<encrypted>"
}

Content (plaintext):

{
  "session": "<hex136>",
  "leaf_index": 42
}

Response (200 OK):

{
  "type": "Response",
  "content": "<encrypted>"
}

Response Content (plaintext):

{
  "ts": 1000,
  "li": 42,
  "p": ["<hex64>", ...],
  "events_root": "<hex64>",
  "state_hash": "<hex64>"
}

See proof.md for verification algorithm.

Errors:

Bundle Membership Proof

POST /bundle

Returns bundle membership proof for an event. Requires R permission.

Request:

{
  "type": "Bundle_Proof",
  "enclave": "<hex64>",
  "from": "<hex64>",
  "content": "<encrypted>"
}

Content (plaintext):

{
  "session": "<hex136>",
  "event_id": "<hex64>"
}

Response Content (plaintext):

{
  "leaf_index": 42,
  "ei": 2,
  "s": ["<hex64>", ...],
  "events_root": "<hex64>"
}

See proof.md for verification algorithm.

Errors:

State Proof

POST /state

Returns SMT proof for a key. Requires R permission.

Request:

{
  "type": "State_Proof",
  "enclave": "<hex64>",
  "from": "<hex64>",
  "content": "<encrypted>"
}

Content (plaintext):

{
  "session": "<hex136>",
  "namespace": "rbac" | "event_status",
  "key": "<hex64>",
  "tree_size": 1000
}

Response Content (plaintext):

{
  "k": "<hex42>",
  "v": "<hex | null>",
  "b": "<hex42>",
  "s": ["<hex64>", ...],
  "state_hash": "<hex64>",
  "leaf_index": 999
}

Verification Flow:

To fully verify a state proof is authentic and from the requested tree position:

1. Verify SMT proof against state_hash (see proof.md)
2. Request CT inclusion proof for leaf_index via POST /inclusion
3. Verify CT inclusion: Recompute leaf as H(0x00, events_root, state_hash) and verify against signed CT root
4. Verify STH signature to authenticate the CT root

This binds the SMT state to a specific, signed tree checkpoint. See proof.md for detailed algorithms.

Errors:

Webhook Delivery

Node delivers Push messages via HTTPS POST to registered endpoints. See Appendix: Push/Notify for design rationale.

Grant_Push Event

Grants a role and registers webhook endpoint. See spec.md for event structure and content fields.

Node maintains queue per (identity, url):

• Aggregates events from all enclaves on this node where identity has P/N permission
• Tracks single push_seq per queue
• All enclaves in a Push delivery share the node's seq_priv for encryption

Multiple Endpoints:

An identity MAY register multiple webhook endpoints via separate Grant_Push events. Each (identity, url) pair has its own push_seq and event queue. Events are delivered independently to each endpoint. To replace an endpoint, submit a new Grant_Push with the new URL; both endpoints remain active until explicitly revoked.

Ordering Guarantee:

Events within each enclave (push.enclaves[N].events) are ordered by sequence number ascending. Events from different enclaves have no guaranteed relative ordering. If global ordering is required, use per-enclave seq to reconstruct the timeline.

Endpoint Transition Atomicity:

When a Grant_Push changes the webhook URL (new Grant_Push with same role, different URL):

1. Old and new endpoints operate as separate queues (no events lost)
2. Old endpoint receives events finalized before the Grant_Push
3. New endpoint receives events finalized after the Grant_Push
4. To stop delivery to old endpoint, explicitly Revoke the role

Delivery Flow

1. Enclave submits Grant_Push event (grants role + registers url)
2. Node adds enclave to (identity, url) queue if not exists
3. On new event, node checks role's P/N permissions
4. Node aggregates events into (identity, url) queue
5. Node periodically POSTs Push to url
6. Node increments push_seq

Push

Webhook delivery containing full events (P permission) and/or event IDs (N permission).

HTTP Request:

POST <url>
Content-Type: application/json

Body:

{
  "type": "Push",
  "from": "<hex64>",
  "to": "<hex64>",
  "url": "<string>",
  "content": "<encrypted>"
}

Content (plaintext):

{
  "push_seq": 130,
  "push": {
    "enclaves": [
      { "enclave": "<hex64>", "events": [Event, ...] }
    ]
  },
  "notify": {
    "enclaves": [
      { "enclave": "<hex64>", "seq": 150 }
    ]
  }
}

Either push or notify may be omitted if empty.

Encryption: See Encryption.

Delivery semantics:

• At-least-once delivery
• Exponential backoff on failure
• Recipient MUST dedupe by event.id (for push) or track last synced seq (for notify)

Expected response: 200 OK

Pull Fallback

If webhook delivery fails, recipient can pull missed batches.

Request:

{
  "type": "Pull",
  "enclave": "<hex64>",
  "from": "<hex64>",
  "content": "<encrypted>"
}

Content (plaintext):

{
  "session": "<hex136>",
  "url": "<string>",
  "push_seq": { "start_after": 5, "end_at": 7 },
  "enclave": "<hex64>"
}

push_seq formats:

• Single: 6 — returns batch 6
• Array: [6, 7, 8] — returns batches 6, 7, 8
• Range: { "start_after": 5, "end_at": 7 } — returns batches 6, 7

Response:

{
  "type": "Response",
  "content": "<encrypted>"
}

Content (plaintext):

[
  {
    "push_seq": 6,
    "push": { "enclaves": [...] },
    "notify": { "enclaves": [...] }
  },
  {
    "push_seq": 7,
    "push": { "enclaves": [...] },
    "notify": { "enclaves": [...] }
  }
]

Array of batches. Each batch has same structure as Push delivery content.

Range Handling:

When push_seq is a Range:

• start_after / end_at are inclusive/exclusive as documented
• Results are ordered by push_seq ascending
• If enclave filter is provided, only events from that enclave are included in each batch
• If enclave is omitted, all enclaves in the original batch are included

Retry Policy:

Node retries webhook delivery with exponential backoff per spec.md. After max retries exhausted, batch is moved to dead-letter queue. Recipient can recover via Pull fallback.

Encryption: Same as Query. See Encryption.

Registry DataView API

The Registry is an enclave with a DataView server that provides discovery endpoints. These endpoints are served by the Registry's DataView, not by the generic Enclave API.

Base URL: Registry node endpoint (discovered via bootstrap)

GET /nodes/:seq_pub

Resolve node by sequencer public key.

Path Parameters:

Request:

GET /nodes/a1b2c3...

Response (200 OK):

{
  "seq_pub": "<hex64>",
  "endpoints": [
    { "uri": "https://node.example.com", "priority": 1 },
    { "uri": "https://backup.example.com", "priority": 2 }
  ],
  "protocols": ["https", "wss"],
  "enc_v": 1
}

Errors:

GET /enclaves/:enclave_id

Resolve enclave to hosting node.

Path Parameters:

Request:

GET /enclaves/d4e5f6...

Response (200 OK):

{
  "enclave_id": "<hex64>",
  "sequencer": "<hex64>",
  "creator": "<hex64>",
  "created_at": 1706000000000,
  "app": "chat",
  "desc": "Team chat",
  "meta": {}
}

Errors:

GET /resolve/:enclave_id

Combined lookup: enclave → node (convenience endpoint).

Path Parameters:

Request:

GET /resolve/d4e5f6...

Response (200 OK):

{
  "enclave": {
    "enclave_id": "<hex64>",
    "sequencer": "<hex64>",
    "creator": "<hex64>",
    "created_at": 1706000000000,
    "app": "chat",
    "desc": "Team chat",
    "meta": {}
  },
  "node": {
    "seq_pub": "<hex64>",
    "endpoints": [
      { "uri": "https://node.example.com", "priority": 1 }
    ],
    "protocols": ["https", "wss"],
    "enc_v": 1
  }
}

Errors:

GET /identity/:id_pub

Resolve identity by public key. Returns the identity's registered enclaves.

Path Parameters:

Request:

GET /identity/a1b2c3...

Response (200 OK):

{
  "id_pub": "<hex64>",
  "enclaves": {
    "personal": "<enclave_id>",
    "dm": "<enclave_id>"
  }
}

Errors:

Appendix

Session

Session tokens provide stateless authentication for queries.

Token Format

136 hex characters = 68 bytes

Bytes 0-31:   r          (Schnorr signature R value)
Bytes 32-63:  session_pub (x-only public key)
Bytes 64-67:  expires    (big-endian uint32, Unix seconds)

Client Derivation

1. expires = now + duration (max 7200 seconds)
2. message = "enc:session:" || be32(expires)
3. sig = schnorr_sign(sha256(message), id_priv)
4. r = sig[0:32]
5. s = sig[32:64]
6. session_priv = s
7. session_pub = point(s)
8. session = hex(r || session_pub || be32(expires))

Node Verification

O(1) EC math — no signature verification.

1. Parse: r, session_pub, expires from token
2. Check: expires > now - 60 (allow 60s clock skew)
3. Check: expires ≤ now + 7200 + 60 (allow 60s clock skew)
4. message = "enc:session:" || be32(expires)
5. expected = r + sha256(r || from || message) * from
6. Verify: session_pub == expected

Clock skew tolerance (±60 seconds) allows clients with slightly-off clocks to connect.

Curve Parameters:

All EC arithmetic uses secp256k1. The curve order is:

n = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141

All scalar operations (addition, multiplication) are performed modulo n.

Signer Derivation

Per-node signer for ECDH.

t = sha256(session_pub || seq_pub || enclave)
signer_priv = session_priv + t (mod n)
signer_pub = session_pub + t * G

Design Rationale:

The enclave ID is included in the signer derivation so that the same session_pub produces different signer keys for different enclaves. This provides per-enclave key isolation:

• Session token is reusable across enclaves (same session_pub)
• Derived encryption key (via signer_pub) is enclave-specific
• A compromised signer key in Enclave A cannot decrypt messages for Enclave B

This is intentional and provides defense-in-depth.

No additional replay protection is needed; the derivation inputs guarantee uniqueness.

Session Properties

Filter

Query filter for event retrieval.

Structure

{
  "id": "<hex64> | [<hex64>, ...]",
  "seq": "<uint> | [<uint>, ...] | Range",
  "type": "<string> | [<string>, ...]",
  "from": "<hex64> | [<hex64>, ...]",
  "tags": { "<tag_name>": "<value> | [<value>, ...] | true" },
  "timestamp": "Range (Unix ms)",
  "limit": 100,
  "reverse": false
}

All fields are optional. Omitted field = no filter (match all).

Tags Filter:

The tags field filters events by tag presence or value:

• { "r": "abc123..." } — events with r tag matching value
• { "r": ["abc123...", "def456..."] } — events with r tag matching any value
• { "auto-delete": true } — events with auto-delete tag (any value)

Default Sort Order:

Events are sorted by sequence number ascending unless reverse: true. This is the canonical enclave order.

Range

{
  "start_at": 100,      // >= 100
  "start_after": 100,   // > 100
  "end_at": 200,        // <= 200
  "end_before": 200     // < 200
}

Semantics

Limits

Examples

By type:

{ "type": "Chat_Message" }

By authors:

{ "type": "Chat_Message", "from": ["abc...", "def..."] }

Time range:

{ "timestamp": { "start_at": 1704067200000, "end_before": 1704153600000 } }

Resume from seq:

{ "seq": { "start_after": 150 }, "limit": 100 }

Newest first:

{ "type": "Chat_Message", "reverse": true, "limit": 20 }

Encryption

Client-node communication is encrypted using ECDH + XChaCha20Poly1305.

Overview

Query Encryption (Client → Node)

Client encrypts query content:

1. Derive signer from session:
   t = sha256(session_pub || seq_pub || enclave)
   signer_priv = session_priv + t (mod n)

2. Compute shared secret:
   shared = ECDH(signer_priv, seq_pub)

3. Derive key and encrypt:
   key = HKDF(shared, "enc:query")
   ciphertext = XChaCha20Poly1305_Encrypt(key, plaintext)

Node decrypts:

1. Derive signer_pub from session_pub:
   t = sha256(session_pub || seq_pub || enclave)
   signer_pub = session_pub + t * G

2. Compute shared secret:
   shared = ECDH(seq_priv, signer_pub)

3. Decrypt:
   key = HKDF(shared, "enc:query")
   plaintext = XChaCha20Poly1305_Decrypt(key, ciphertext)

Response Encryption (Node → Client)

Node encrypts response (HTTP and WebSocket):

shared = ECDH(seq_priv, signer_pub)
key = HKDF(shared, "enc:response")
ciphertext = XChaCha20Poly1305_Encrypt(key, plaintext)

Client decrypts:

shared = ECDH(signer_priv, seq_pub)
key = HKDF(shared, "enc:response")
plaintext = XChaCha20Poly1305_Decrypt(key, ciphertext)

Push Encryption (Node → Webhook)

Node encrypts webhook payload:

shared = ECDH(seq_priv, to)
key = HKDF(shared, "enc:push")
ciphertext = XChaCha20Poly1305_Encrypt(key, plaintext)

Recipient decrypts:

shared = ECDH(recipient_priv, seq_pub)
key = HKDF(shared, "enc:push")
plaintext = XChaCha20Poly1305_Decrypt(key, ciphertext)

Primitives

HKDF Parameters:

IKM   = ECDH shared secret (32 bytes)
salt  = empty (no salt)
info  = UTF-8 encoded label string, NO null terminator
        e.g., "enc:query" = 9 bytes: 0x65 0x6E 0x63 0x3A 0x71 0x75 0x65 0x72 0x79
L     = 32 bytes (256-bit key)

XChaCha20Poly1305 Nonce:

nonce = random 24 bytes, prepended to ciphertext
ciphertext_wire = nonce || ciphertext || tag

Recipient extracts first 24 bytes as nonce before decryption.

Minimum Length: ciphertext_wire MUST be at least 40 bytes (24-byte nonce + 16-byte Poly1305 tag). Shorter values indicate malformed or truncated ciphertext — implementations MUST reject with DECRYPT_FAILED.

Error Codes

HTTP Status Mapping

Error Response Format

{
  "type": "Error",
  "code": "<CODE>",
  "message": "<human readable>"
}

Error Codes

WebSocket Errors:

WebSocket errors use the same JSON format as HTTP errors. HTTP status codes do not apply to WebSocket; use the application-level code field instead.

Push/Notify

Problem

A DataView server may have P/N permissions across hundreds of enclaves on the same node. Naive approach — one HTTP request per event per enclave — creates massive overhead.

Solution

Node aggregates events into a single queue per (identity, url) pair.

Enclave A ──┐
Enclave B ──┼──► Queue (identity, url) ──► Single POST to url
Enclave C ──┘

Why This Is Efficient

Pull Fallback Efficiency

When webhook delivery fails, recipient uses Pull to recover. The single sequence number makes this extremely efficient:

Without unified sequence (naive):

Recipient must track:
  - Enclave A: last_seq = 42
  - Enclave B: last_seq = 17
  - Enclave C: last_seq = 103
  ...hundreds of enclaves...

Recovery requires:
  - One Query per enclave
  - Complex state management
  - N round trips for N enclaves

With unified push_seq:

Recipient tracks:
  - push_seq = 130

Recovery requires:
  - One Pull request with Range
  - Returns all missed batches
  - Single round trip

Gap detection is trivial:

• Received push_seq 5, then 8 → know you missed 6, 7
• Pull with push_seq: { "start_after": 5, "end_at": 7 } returns both batches in one request

This is why the queue is per (identity, url) not per enclave — it enables O(1) state tracking regardless of how many enclaves you're subscribed to.

Push vs Notify (within same message)

A single Push delivery contains both:

• push.enclaves[] — full events for enclaves with P permission
• notify.enclaves[] — latest seq for enclaves with N permission

Permissions

Example:

Identity has:
  - Enclave A: P permission → full events in push.enclaves[]
  - Enclave B: N permission → seq in notify.enclaves[]
  - Enclave C: N + R permissions → seq in notify.enclaves[], can Query full events

If you only have N (no R), you know new events exist but cannot read their content. This is useful for:

• Mobile push notifications (just alert user)
• Protocol-level sync signals (trigger sync via other means)
• Audit logging (record that activity occurred)

Typical Pattern

1. Receive Push with notify.enclaves[].seq
2. Query events with { "seq": { "start_after": last_synced_seq } } (requires R permission)
3. Full events arrive directly in push.enclaves[] if you have P permission

Node Internal Table

Key:   (identity, url)
Value: { push_seq, enclaves[] }

For each enclave, node tracks which events to include based on role permissions.

Cryptographic Proofs

CT inclusion, consistency, bundle membership, SMT state proofs — verification algorithms and wire formats.

Cryptographic Proofs

This document specifies proof formats for the ENC protocol.

Overview

The ENC protocol uses two types of Merkle proofs:

CT Proofs

Bundle Membership Proof

Proves that an event is part of a specific bundle.

Structure:

{
  event_id: <32 bytes>,
  bundle_index: <number>,
  siblings: [<hash>, ...]
}

Where:

• event_id — the event being proven
• bundle_index — position of event within the bundle (0-indexed)
• siblings — Merkle proof siblings from event_id to events_root

Verification:

1. Set hash = event_id, index = bundle_index
2. For each sibling s in siblings array (from leaf toward root): - If index is even (LSB = 0): hash = H(0x01, hash, s) — current is left child - If index is odd (LSB = 1): hash = H(0x01, s, hash) — current is right child - index = index >> 1 (shift right by 1)
3. Verify hash == events_root

Algorithm Notes:

• bundle_index is the event's 0-indexed position within the bundle
• The LSB (least significant bit) of index determines left (0) or right (1) at each level
• After each hash step, shift index right to get the parent's position
• Siblings are ordered from leaf level (closest to event) to root level

Example:

Bundle with 4 events, verifying event at bundle_index = 2:

        events_root
           /    \
         h01    h23
        /  \   /  \
       e0  e1 e2  e3   ← bundle_index: 0, 1, 2, 3

• Start: hash = e2, index = 2 (binary: 10)
• Step 1: LSB(2) = 0 → hash = H(0x01, hash, siblings[0]) where siblings[0] = e3
• Shift: index = 1
• Step 2: LSB(1) = 1 → hash = H(0x01, siblings[1], hash) where siblings[1] = h01
• Result: hash should equal events_root

With bundle.size = 1, the bundle contains one event, so siblings is empty and events_root = event_id.

CT Inclusion Proof

Proves that a bundle exists at a specific position in the log.

Structure:

{
  tree_size: <uint64>,
  leaf_index: <uint64>,
  path: [<hash>, ...]
}

Where:

• tree_size — number of bundles in the tree when proof was generated
• leaf_index — 0-based position of the bundle in the log
• path — sibling hashes from leaf to root

Leaf Hash:

leaf_hash = H(0x00, events_root, state_hash)

Where events_root is the Merkle root of event IDs in the bundle, and state_hash is the SMT root after the bundle.

Verification (RFC 9162 Section 2.1.3.2):

1. Set fn = leaf_index, sn = tree_size - 1, r = leaf_hash
2. For each p in path: - a. If sn == 0: FAIL (proof too long) - b. If LSB(fn) == 1 or fn == sn: - r = H(0x01, p, r) - While LSB(fn) == 0 and fn != 0: fn >>= 1; sn >>= 1 - c. Else: - r = H(0x01, r, p) - d. fn >>= 1; sn >>= 1
3. Verify sn == 0 and r == expected_root

Test Vector:

Tree size: 7, Leaf index: 5
Initial: fn=5, sn=6

Step 1 (p[0]): LSB(5)=1 → r=H(0x01,p[0],r), shift → fn=2, sn=3
Step 2 (p[1]): LSB(2)=0, fn≠sn → r=H(0x01,r,p[1]), shift → fn=1, sn=1
Step 3 (p[2]): fn==sn → r=H(0x01,p[2],r), shift → fn=0, sn=0

Final: sn=0 ✓, compare r to expected_root

Edge Cases:

1. Single-element tree (tree_size = 1, leaf_index = 0): - Initial: fn = 0, sn = 0 - path is empty (no siblings) - Skip the loop and verify r == expected_root directly

1. Leaf at last position (leaf_index = tree_size - 1): - Valid case; algorithm handles via fn == sn condition

CT Consistency Proof

Proves that an earlier log state is a prefix of the current state.

Structure:

{
  tree_size_1: <uint64>,
  tree_size_2: <uint64>,
  path: [<hash>, ...]
}

Where:

• tree_size_1 — size of the older (smaller) tree
• tree_size_2 — size of the newer (larger) tree
• path — sibling hashes proving consistency

Verification:

1. If tree_size_1 == tree_size_2: verify path has 1 element equal to both roots
2. If tree_size_1 is a power of 2: prepend first_hash to path
3. Set fn = tree_size_1 - 1, sn = tree_size_2 - 1
4. While LSB(fn) == 0: shift both fn and sn right by 1
5. Set fr = path[0], sr = path[0]
6. For each c in path[1:]: - If sn == 0: FAIL - If LSB(fn) == 1 or fn == sn: set fr = H(0x01, c, fr), sr = H(0x01, c, sr), then while LSB(fn) == 0 and fn != 0: shift both right by 1 - Else: set sr = H(0x01, sr, c) - Shift both fn and sn right by 1
7. Verify fr == first_hash, sr == second_hash, and sn == 0

Based on RFC 9162 Section 2.1.4.

Signed Tree Head (STH)

The sequencer signs the CT root periodically to create a checkpoint.

Structure:

{
  t:   <timestamp>,
  ts:  <tree_size>,
  r:   <root_hash>,
  sig: <signature>
}

Where:

• t — Unix milliseconds when STH was generated
• ts — number of bundles in the tree
• r — CT root hash (32 bytes)
• sig — Schnorr signature over the STH

Signature:

message = "enc:sth:" || be64(t) || be64(ts) || r
sig = schnorr_sign(sha256(message), seq_priv)

Where r is the raw 32-byte root hash (NOT hex-encoded). The message is binary concatenation:

• "enc:sth:" = 8 bytes UTF-8
• be64(t) = 8 bytes big-endian
• be64(ts) = 8 bytes big-endian
• r = 32 bytes raw

Total: 56 bytes before SHA256.

{
  "t": 1706000000000,
  "ts": 1000,
  "r": "<hex64>",
  "sig": "<hex128>"
}

Verification:

1. Reconstruct message: "enc:sth:" || be64(t) || be64(ts) || hex_decode(r)
2. Verify: schnorr_verify(sha256(message), sig, seq_pub)

Full Event Proof

To fully prove an event exists and verify its state:

1. Bundle membership proof — proves event_id is in bundle's events_root
2. CT inclusion proof — proves bundle is in CT tree
3. SMT proof — proves state claim against bundle's state_hash

This two-level structure allows efficient bundling while maintaining per-event verifiability.

SMT Proofs

SMT proofs verify state claims (RBAC assignments, event status) against the state_hash.

Proof Structure

{
  key: <21 bytes>,
  value: <bytes | null>,
  bitmap: <21 bytes>,
  siblings: [<hash>, ...]
}

Where:

• key — 21-byte SMT key (namespace + truncated path)
• value — leaf value (null for non-membership proof)
• bitmap — 168 bits indicating which siblings are present (1) vs empty (0)
• siblings — only non-empty sibling hashes, in order

Empty siblings are omitted; verifier uses empty_hash for missing slots.

Bitmap Bit Ordering (LSB-first):

Bit N corresponds to depth N in the tree, where depth 0 is closest to the root and depth 167 is the leaf level.

Bit numbering within bytes: LSB-first. Bit 0 is the least significant bit (rightmost). Bit 7 is the most significant bit (leftmost).

Bitmap Example:

For a proof with non-empty siblings at depths 0, 10, and 167:

• Bitmap bit 0 = 1 (sibling at root level)
• Bitmap bit 10 = 1 (sibling at depth 10)
• Bitmap bit 167 = 1 (sibling at leaf level)
• All other bits = 0

Serialized as 21 bytes (168 bits), with bit 0 = LSB of byte 0. The siblings array contains exactly 3 hashes, in depth order (0, 10, 167).

Bit-to-Byte Mapping:

Depth D maps to: byte[D / 8], bit (D % 8) where bit 0 is LSB.

Example: depth 10 → byte[1], bit 2 (since 10 / 8 = 1, 10 % 8 = 2)

Hex Serialization:

The 21-byte bitmap is serialized as a hex string in standard byte order:

• Byte 0 (containing bits 0-7) is the first two hex characters
• Byte 20 (containing bits 160-167) is the last two hex characters

Example: Depths 0, 10, 167 have siblings:

• Byte 0 = 0x01 (bit 0 set)
• Byte 1 = 0x04 (bit 10 = bit 2 of byte 1)
• Byte 20 = 0x80 (bit 167 = bit 7 of byte 20)
• Hex: "010400...80" (42 chars total)

Verification

1. Compute leaf hash: H(0x20, key, value) (or empty_hash if value is null)
2. For each depth from 167 to 0: - If bitmap bit is 1: use next sibling from array - If bitmap bit is 0: use empty_hash - Compute: H(0x21, left, right)
3. Compare with expected root (state_hash)

Non-Membership Verification

A non-membership proof proves that a key does not exist in the SMT.

Verification:

1. Verify that value is null
2. Compute the expected leaf hash as empty_hash (the key has no value)
3. Follow the same path computation as membership verification
4. Compare result with expected root (state_hash)

If the computed root matches and the path is valid with an empty leaf, the key does not exist in the tree.

Empty Node Hash

empty_hash = sha256("")
           = 0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Hardcoded constant — do not compute at runtime.

Wire Format (JSON)

The normative wire format for v1 is JSON.

SMT Proof

{
  "k": "<hex>",
  "v": "<hex | null>",
  "b": "<hex>",
  "s": ["<hex>", ...]
}

Value Encoding by Proof Type:

CT Inclusion Proof

{
  "ts": 1000,
  "li": 42,
  "p": ["<hex>", ...]
}

CT Consistency Proof

{
  "ts1": 500,
  "ts2": 1000,
  "p": ["<hex>", ...]
}

Bundle Membership Proof

{
  "ei": 2,
  "s": ["<hex>", ...]
}

Sparse Merkle Tree

Tree structure, namespaces, key construction, hash functions, collision analysis, state binding.

Sparse Merkle Tree (SMT)

This document specifies the implementation details for the Enclave State SMT referenced in the main protocol spec.

Tree Structure

The 160-bit entry path matches Ethereum address length, providing the same collision safety properties.

Namespaces

Key Construction

RBAC key:

path = 0x00 || sha256(id_pub)[0:160 bits]

Where id_pub is the raw 32-byte secp256k1 x-only public key. Always compute sha256(id_pub) even though id_pub is already 32 bytes; this ensures uniform distribution across the tree.

Event Status key:

path = 0x01 || sha256(event_id)[0:160 bits]

Notation: sha256(x)[0:160 bits] means the first 160 bits (20 bytes) of the SHA256 hash. The full key is 21 bytes: 1-byte namespace prefix + 20-byte truncated hash.

API Key Construction:

When calling the State Proof API, clients provide the 32-byte raw key (id_pub or event_id). The node internally constructs the 21-byte SMT key by:

1. Selecting namespace based on namespace parameter
2. Computing sha256(key)[0:160 bits]
3. Concatenating: namespace_byte || truncated_hash

The response k field contains the full 21-byte SMT key for verification.

Leaf Values

RBAC:

value = <role bitmask as 256-bit integer>

CBOR Encoding:

Role bitmasks are encoded as 32-byte big-endian byte strings for CBOR hashing:

• Pad with leading zeros to 32 bytes
• Example: bitmask 0x100000002 → 0x0000...00100000002 (32 bytes)

The 32-byte padding is applied during CBOR encoding for SMT leaf hash computation (leaf_hash = H(0x20, key, value)). In JSON proofs (see proof.md), the same 32-byte value is hex-encoded as 64 characters. The padding is persistent — it represents the actual leaf value stored in SMT.

Zero Bitmask:

When all roles are revoked (bitmask = 0), the leaf is removed from the SMT. An identity with no roles is semantically equivalent to "not in tree". This follows the same pattern as Event Status where "(not in tree) = Active".

Event Status:

Encoding: Deleted status is a single zero byte (0x00). Updated status is the 32-byte update_event_id. This unambiguously distinguishes the two cases.

• Deleted: CBOR encodes as 0x40 0x00 (1-byte bytestring) or 0x00 (integer zero)
• Updated: CBOR encodes as 0x58 0x20 <32 bytes> (32-byte bytestring)

This prevents any collision between deleted status and an update_event_id that happens to start with zeros.

Proof Interpretation:

To distinguish "Active" from "never existed" for events, combine with CT inclusion proof. To prove historical role membership, use CT inclusion proof for the Grant event.

Distinguishing Event Outcomes:

For Event Status proofs, if you receive a non-membership proof (null):

• The event is currently Active OR it never existed
• To distinguish: obtain a CT inclusion proof for the event
• If CT inclusion succeeds: event was created → currently Active
• If CT inclusion fails: event never existed

For RBAC proofs, a non-membership proof means:

• Identity currently has no roles
• To prove historical role assignment, obtain a CT inclusion proof for the Grant event

Hash Construction

Leaf Hash

leaf_hash = H(0x20, key, value)

Internal Node Hash

node_hash = H(0x21, left_child, right_child)

Empty Node

empty_hash = sha256("")
         = 0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Hardcoded constant — do not compute at runtime.

Proofs

SMT proof structure and verification are defined in proof.md.

Collision Analysis

Same security margin as Ethereum addresses.

Performance

Note: Computation is always O(168) regardless of tree sparsity. Empty siblings are still hashed.

State-Changing Events

Only certain events modify the SMT.

RBAC Namespace (0x00):

Event Status Namespace (0x01):

Update Chaining:

Multiple Updates to the same event are allowed. Each Update overwrites the previous value:

• First Update: SMT[event_A] = update_event_B
• Second Update: SMT[event_A] = update_event_C
• Final state: SMT[event_A] = update_event_C

The SMT always stores the latest update_event_id. To trace the full Update history, use CT inclusion proofs to find all Update events referencing the original target_event_id.

Events that do NOT modify SMT:

• Content events (e.g., Chat_Message)
• Lifecycle events: Pause, Resume, Terminate, Migrate

Lifecycle state is derived from the event log, not stored in SMT.

State Binding

The SMT root (state_hash) is bound to the event log via the Certificate Transparency (CT) structure, not via the event hash itself.

CT Leaf Hash:

leaf_hash = H(0x00, events_root, state_hash)

Where:

• events_root — Merkle root of event IDs in this bundle (see spec.md for bundle structure)
• state_hash — SMT root AFTER the last event in this bundle is applied

Proof Binding (CT + SMT)

The CT root proves both log integrity AND state integrity. To verify a state claim, the client needs:

1. CT inclusion proof — proves the event exists at position N in the log
2. SMT proof — proves the state against state_hash at position N

Verification Flow:

1. Obtain the event, bundle membership proof, and CT inclusion proof from the node
2. Verify bundle membership: confirm event_id is in the bundle's events_root
3. Verify CT inclusion proof: recompute path from leaf_hash = H(0x00, events_root, state_hash) to CT root
4. Verify SMT proof against the state_hash from step 3

Unified Checkpoint:

The CT root alone is sufficient to prove both:

• Event log integrity (which events exist, in what order)
• State integrity (what the SMT root was after each event)

This simplifies migration and audit: a single ct_root value commits to the entire enclave history and state.

Storage

• Store only non-empty nodes
• Empty subtrees computed on-demand
• Historical states MAY be pruned