Protocol Specification v0.5

OIP Overview

The Oracle Interoperability Protocol (OIP) (opens in a new tab) is the state synchronization protocol specification for the Oraclizer Oracle State Machine (opens in a new tab). OIP defines the message formats, state transition rules, routing decisions, validation procedures, and error handling semantics that two independent implementations must agree on to interoperate. OIP v0.5 is the first publicly released version of the specification on docs.oraclizer.io.

This page introduces what OIP is, what it deliberately does not specify, where v0.5 sits in the versioning trajectory, and how to read the rest of the Protocol Specification section. Subsequent pages in this section assume the boundaries and terminology established here.

Intended audience. The Protocol Specification section is written for OSS (opens in a new tab) implementers, builders of off-chain Drivers such as the Canton Driver (opens in a new tab), protocol designers, and reviewers who assess implementations against this contract. DeFi applications read asset state from the RWA Registry (opens in a new tab) contracts and do not exchange OIP messages; for their developers, this section is background on how those states change. Familiarity with cross-chain protocol design, zero-knowledge proof systems, and asset state modeling is assumed. Readers who are new to Oraclizer should start with What is Oraclizer and State Synchronization in the Core Concepts section before approaching this specification.

Specification Status
StatusDesign-stage specification (Draft)
Wire formatNot yet frozen. Finalized in v0.6 .proto definitions.
Production readinessExternal implementations targeting wire-level interoperability should track the v0.6 release.
Conformance basisSemantic conformance only. Wire-level interoperability test vectors are deferred to v0.6.

v0.5 fixes the message semantics, state transitions, validation pipeline, and error handling. The byte-level encoding is intentionally left to v0.6 so that interoperability tests are published against a stable wire format.


What OIP Defines and What It Does Not#

OIP is a contract between independent implementations. The specification limits itself to the surface that two implementations must share to exchange synchronization messages and reach the same conclusions. Anything internal to a single implementation is deliberately left outside the specification.

OIP Defines#

  • The wire-level structure and semantics of OIPMessage, including all seven message types (covered in Message Protocol)
  • The asset state model (HierarchicalLockStatus) and the matrix of valid state transitions (State Management)
  • Per-message-type validation pipelines and the eight validation criteria (Validation)
  • Protocol-level specifications for the six regulatory actions (Regulatory Actions)
  • Staged coordination for cross-chain message delivery: PREPARE → COMMIT → FINALIZE (Cross-chain Protocol)
  • The error code namespace and the processing-action matrix (Error Reference)

OIP Does Not Define#

  • Internal data structures, caching strategies, or algorithms within a single implementation. These belong to OSS, D-quencer (opens in a new tab), and CDK as their respective implementation concerns.
  • Sequencing algorithms. The choice of priority queue, batching strategy, and execution order is the sequencer’s concern, not the protocol’s.
  • Network propagation mechanisms. Peer discovery, gossip protocols, and transport-layer concerns are out of scope.
  • Proof-engine and wrapper structure. The internal GKR engine and external succinct ZK wrapper of StateSync-GKR (opens in a new tab) are governed by separate specifications. The inner GKR proof does not itself provide zero knowledge.
  • Wire format byte layout. The v0.5 specification fixes the semantics; the byte-level encoding is finalized in the .proto definitions delivered with v0.6.

Reference Architecture#

OIP sits between the Oracle State Synchronizer (OSS), the decentralized sequencer (D-quencer), and the L3 zk-Rollup (opens in a new tab) running on customized Polygon CDK. The diagram below illustrates the boundary OIP draws across these components and the contracts it establishes with adjacent systems.

Scope boundary

Two implementations interoperate when they agree on the OIP surface; below that line each one is free.

Two implementations interoperate when they agree on the OIP surface; below that line each one is free. Implementations A and B exchange OIP messages across the OIP surface, which fixes message formats, state transitions, routing, validation and errors. Below the surface each implementation chooses its own language, runtime, storage engine, queue strategy and cache layout. Three adjacent systems meet OIP through one-way contracts: D-quencer orders OIP messages, StateSync-GKR issues the proof for each State Root and CDK commits the State Root. When the OIP path is unavailable, users submit through Base L2 directly, and the RWA Registry applies the same checks on either path. Adjacent systems 1 D-quencer orders OIP messages StateSync-GKR proof for each State Root CDK commits the State Root OSS implementation A OSS implementation B OIP surface 2 message formats, state transitions, routing, validation, errors OIP messages same meaning on both sides language runtime storage engine queue strategy cache layout language runtime storage engine queue strategy cache layout 3 chosen independently below the line OIP path Base L2 users submit directly Force Inclusion, bypasses OIP RWA Registry same checks on either path 4
  1. 1

    One-way contracts

    D-quencer orders OIP messages, StateSync-GKR issues the primary finality proof for each State Root and CDK commits it on-chain through its block proof. OIP does not constrain how any of them works.

  2. 2

    The OIP surface

    What two implementations must share: message formats, state transition rules, routing decisions, validation procedures and error handling.

  3. 3

    Free below the line

    Language, runtime, storage engine, queue strategy and cache layout may differ between implementations. Sharing a stack does not help if OIP semantics differ.

  4. 4

    Same checks on both paths

    If the OIP path is unavailable, users reach the L3 through Base L2. The RWA Registry performs its own authority, state and proof checks whichever path delivered the transaction.

  • The OIP surface, fixed by the specification
  • Implementation-defined choice
  • Outside OIP, with its own specification
  • One-way contract with an adjacent system
  • Fallback path that bypasses OIP
Figure 1: OIP Scope Boundary

The diagram makes one point. Two implementations may differ in every internal choice (language, runtime, storage engine, queue strategy, cache layout) and still interoperate, provided they agree on the OIP surface. Conversely, two implementations that share the same internal stack but disagree on OIP semantics will not interoperate. The protocol is the agreement; the implementations are free below the line.

Adjacent systems are governed by their own specifications and meet OIP at well-defined contracts. D-quencer’s consensus output orders OIP messages for downstream processing. CDK commits the OSS State Root on-chain through its block proof. StateSync-GKR issues the primary finality (opens in a new tab) proof attached to each State Root. Each contract is one-way: OIP does not constrain how D-quencer reaches consensus, how CDK builds blocks, or how StateSync-GKR generates proofs.

The Force Inclusion (opens in a new tab) path shown at the bottom of the diagram is a deliberate fallback. If the OIP path is unavailable, users may submit transactions to the L3 directly through Base L2 (opens in a new tab), bypassing OIP entirely. The RWA Registry self-defense (opens in a new tab) principle (defined in Validation) ensures that an RWA Registry (opens in a new tab) contract performs its own authority, state, and proof checks regardless of which path delivered the transaction, so the safety guarantees of the OIP path and the Force Inclusion path are equivalent.

v0.5 in the Versioning Trajectory#

OIP versions evolve along a trajectory from research-stage drafts to a production-stable specification. Each version has a distinct artifact form and a distinct audience.

VersionStageArtifactPublic Location
v0.1 – v0.3+Research draftsMarkdown, JSON Schema, TypeScript interfaces in research articlesresearch.oraclizer.io only
v0.5Design-stage specificationNormative markdown specification with TypeScript-style type definitions and pseudocodedocs.oraclizer.io (this section)
v0.6 – v0.8Implementation refinementSpecification + .proto definitions, JSON Schema, code generationdocs.oraclizer.io + oraclizer/oip-spec repository
v0.9 – v1.0Production specificationWire-stable, conformance-tested specificationdocs.oraclizer.io (final)

v0.5 is the first OIP version published on docs.oraclizer.io. The earlier drafts (v0.1 through v0.3+) exist in research articles where the protocol’s design space was being explored. v0.5 consolidates those drafts into a single coherent specification with explicit normative requirements and explicit boundaries.

The consolidation was not a mechanical merge. v0.5 resolved open design questions across five interconnected areas: state transition validation, off-chain integration boundaries (Canton), the L3-OIP boundary, error handling and recovery semantics, and version negotiation. The decisions in each area are presented in their respective specification pages alongside the requirements they produced, rather than collected into a separate rationale section. This keeps each requirement next to the reasoning that justifies it, which is the convention adopted by mature protocol specifications such as TLS 1.3 and the Cosmos IBC specification.

Cumulative Design Decisions#

OIP’s pre-publication versions accumulated semantic decisions in research articles before consolidation. The table below records the principal contributions of each version. None of the pre-v0.5 versions were published as independent specifications; each was an interim research artifact that fed into the next.

VersionPrincipal Contributions
v0.1Initial five message types; JSON Schema Draft; four-tier LockStatus; initial Asset / OCID / Contract data structures.
v0.2State reconciliation; incremental proof; enhanced five-tier lock; batch processing.
v0.3Hierarchical lock status (primary / secondary separation); regulatory context; temporal constraints; cross-chain coherence; atomic lock manager.
v0.3Six regulatory actions formalized; Escalation Chain; scheduled action; priority system; three-phase cross-chain broadcast; three atomicity levels.
v0.3ERC-3770 address system adopted; address resolution pipeline; short-name registry; EIP-55 checksum.
v0.3+Seven message types under MECE classification; unified message header; routing metadata; content-based routing; routing slip; atomicity-driven coordination; priority-based atomicity escalation; fault handling.
v0.5State transition validation rules; eight validation criteria; three-group DAG; signatureType with single and threshold schemes; Driver Attestation; RWA Registry self-defense; ROLLBACK_INCOMPLETE coherence state; integration of all prior contributions through 24 design decisions across five areas.

The significance of v0.5’s documentation publication is that, for the first time, every semantic decision two independent implementations must agree on is fixed in a single coherent specification. The wire format remains intentionally open until v0.6, but the design space has stopped moving.

Formal Verification Track#

The OIP specification has been developed alongside a formal verification track. The Oraclizer team has built Isabelle/HOL (opens in a new tab) models of the protocol’s core properties and mechanically verified them. Cross-Domain State Preservation, covering both safety and liveness under Byzantine faults, is complete and published as [CDSP] (opens in a new tab). The formal verification artifacts for OIP v0.6 are published with that edition, and its Conformance page states what they establish.

OIP v0.5 has been designed so that its message semantics and state transition matrix align with the verified properties. The proofs target the protocol’s semantic model rather than any particular source code, which is one reason OIP is published as a written specification: a single canonical codebase would make the verified meaning depend on whichever code happened to be authoritative, while a written specification fixes the meaning independently of any implementation.

v0.x Compatibility#

While the protocol is in the v0.x range, even minor version bumps may introduce breaking changes. Refinements to the data model and message format are expected between v0.5 and v0.6 as the wire format is fixed. After v1.0, the specification adopts standard semantic versioning: major bumps for breaking changes, minor bumps for backward-compatible additions, patch bumps for clarifications and corrections.

Implementers planning early integration should expect to track changes through the v0.6 release. The Changelog records every published change at the group-release level.

Path to Wire-Stable Implementation#

External implementers should treat v0.5 as a design-stage contract. The semantics are stable enough to reason about, model, and prototype against, but the byte-level wire format is not yet frozen. Implementations targeting production interoperability should track the v0.6 .proto release as the start of wire-stable development.

The v0.6 release will accompany the public oraclizer/oip-spec repository, which will host the .proto definitions and the generated language bindings (Rust, TypeScript, Go), following the convention used by Protocol Buffers-based protocols across the Cosmos, gRPC, and Tendermint ecosystems. From v0.6 onward, the markdown specification fixes the semantics, the .proto files fix the wire encoding, and language bindings are generated from the .proto files rather than written by hand.

Versioning trajectory

v0.5 fixes what messages mean; from v0.6, .proto files fix their bytes and the bindings are generated from them.

v0.5 fixes what messages mean; from v0.6, .proto files fix their bytes and the bindings are generated from them. Four stages in order: research drafts v0.1 to v0.3+, the v0.5 design-stage specification, v0.6 to v0.8 implementation refinement and the v0.9 to v1.0 production specification. Below them a staircase shows what each stage fixes: v0.5 fixes every semantic decision two implementations must agree on, from v0.6 the .proto files also fix the bytes and the language bindings are generated from them, and from v0.9 to v1.0 the bytes are held stable and conformance-tested. At the bottom, a brace over the v0.x range notes that even a minor version bump may break compatibility there, and an arrow from v1.0 notes that versions after v1.0 follow semantic versioning. v0.1 – v0.3+ Research drafts v0.5 Design-stagespecification 1 v0.6 – v0.8 Implementationrefinement v0.9 – v1.0 Productionspecification What each stage fixes Semantics every semantic decision two implementations must agree on 2 Wire encoding .proto files fix the bytes; bindings are generated Wire stability bytes held stable,conformance-tested Compatibility 3 within v0.x, even a minor version bump may break compatibility after v1.0,semantic versioning
  1. 1

    This edition

    v0.5 fixes message semantics, state transitions, the validation pipeline and error handling. Conformance is semantic only.

  2. 2

    Bytes from v0.6

    The .proto files fix the wire encoding, and the Rust, TypeScript and Go bindings are generated from them rather than written by hand.

  3. 3

    Compatibility

    Within v0.x even a minor version bump may break compatibility. After v1.0, versions follow semantic versioning.

  • v0.5, this edition, and what it fixes
  • Later version
  • Interim research drafts, never published as specifications

Schematic: column widths do not represent time.

Figure 2: OIP Versioning Trajectory

Conformance and Open Issues#

The Protocol Specification section closes with two pages dedicated to the boundaries of the specification itself: what it requires of conformant implementations, and what it explicitly leaves open for later resolution.

Conformance formalizes what it means for an implementation to claim OIP v0.5 compatibility. It classifies every requirement scattered across this specification under the RFC 2119 (opens in a new tab) keywords (MUST, SHOULD, MAY), states the minimum conformant implementation criteria across six functional groups, and provides a 20-item self-check list that an implementer can run against their codebase before claiming v0.5 compatibility. Wire-level interoperability test vectors are deferred to v0.6, when the byte format is fixed; what v0.5 offers is a semantic conformance contract.

Open Issues records the items that v0.5 deliberately does not resolve. They are classified into three groups: Deferred items that v0.5 intentionally does not address with a scheduled later resolution, Pending Definition items where v0.5 fixes the skeleton but defers the concrete formalization, and Future Research items dependent on external standards or empirical evidence not yet available. The items span Canton Driver integration, RWA Registry interface details, asset model extensions, operational mechanisms, operational tooling, security, and v0.5 interoperability testing. Recording these openly is a deliberate choice: institutional partners, EIP reviewers, and academic readers treat the explicit listing of open issues as a stronger signal of specification maturity than the appearance of completeness.

Terminology#

The terms below are normative within the Protocol Specification section. The Glossary page provides broader definitions for the wider documentation audience; the definitions here are scoped to specification semantics.

  • Oracle State Machine (opens in a new tab): A specialized state machine that realizes bidirectional state synchronization. Distinguished from a data-feed oracle, which delivers values in one direction without state-bound semantics.
  • Atomic State Binding (opens in a new tab): The property that on-chain and off-chain state changes succeed together or fail together. Distinguished from two-unidirectional channels, where each direction is processed as an independent event with no causal consistency guarantee.
  • OIP Domain (opens in a new tab): A unit system that an OIP message can reach. Each EVM chain, each Canton instance, and the L3 itself are distinct domains.
  • Cross-domain Effect (opens in a new tab): A state change in one domain that affects asset state in another domain. This is the criterion for message promotion across domain boundaries.
  • Primary Finality (opens in a new tab): The point at which the OSS State Root is fixed by GKR proof issuance. The OSS treats this as its source of truth and preserves it permanently.
  • Secondary Finality (opens in a new tab): The external settlement finality reached through a selected succinct ZK wrapper, an authenticated zkVerify (opens in a new tab) receipt, a receipt-gated CDK L3 transition and Base L2 confirmation of that L3 state commitment.
  • Pending Sync Queue (opens in a new tab): An OSS-internal queue tracking messages whose primary finality has been issued but whose external propagation (secondary finality) has not yet completed. OIP requires invariants on this queue’s behavior; the concrete data structure is implementation-defined.
  • Driver Attestation (opens in a new tab): A signed assertion issued by a domain driver (such as the Canton Driver) conveying domain-internal facts (authorization, contract activation, observer membership) to OIP.
  • Self-defense (RWA Registry) (opens in a new tab): The principle that an RWA Registry contract performs its own authority, state, and proof checks rather than trusting OIP unconditionally. This ensures that the OIP path and the Force Inclusion path arrive at the same safety guarantees.
  • Force Inclusion (opens in a new tab): A path through Base L2 that allows transactions to reach the L3 directly, bypassing the OIP path. Equivalence of safety guarantees on both paths is established by RWA Registry self-defense.

Conventions#

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in BCP 14 (opens in a new tab) [RFC 2119 (opens in a new tab)] [RFC 8174 (opens in a new tab)] when, and only when, they appear in all capitals as shown. Lowercase or mixed-case occurrences of these words carry no normative meaning. The aggregated MUST/SHOULD/MAY classification of every requirement in this specification is published on the Conformance page.

Type definitions in this specification are presented in TypeScript interface syntax for readability. They are not executable code. They are normative type signatures intended for human reading, used to fix field names, types, and structural relationships. The wire-level encoding (byte layout, field tags, serialization rules) is fixed in the .proto definitions delivered with v0.6, from which language-specific bindings (Rust, TypeScript, Go) are generated.

Field names follow camelCase. Enumeration values follow UPPER_SNAKE_CASE. Error codes follow UPPER_SNAKE_CASE with a category prefix.

Reading the Protocol Specification#

The Protocol Specification section consists of twelve pages. The first nine pages establish the vocabulary, types, and behaviors of the protocol. The final two pages, Conformance and Open Issues, describe the boundaries of the specification itself. Three reading paths are common.

For implementers building from scratch, read the section in order. Each page assumes the definitions established in earlier pages.

  1. Data Model: Core enumerations, the address system (ERC-3770 (opens in a new tab) + CAIP-2 (opens in a new tab)), the hierarchical lock status, identity types (OCID (opens in a new tab)/RAI (opens in a new tab)), asset and contract types, regulatory context.
  2. Message Protocol: The unified message header, routing metadata, and the seven message types: STATE_SYNC, REGULATORY_ACTION, LOCK_MANAGEMENT, QUERY, ACK, HEARTBEAT, GOVERNANCE.
  3. Routing: Content-based routing (opens in a new tab), atomicity-driven coordination (opens in a new tab), priority-based atomicity escalation (opens in a new tab), the routing slip (opens in a new tab) pattern.
  4. State Management: The state transition matrix, preconditions and postconditions, the escalation chain (opens in a new tab), preemptive lock (opens in a new tab) protocol, cross-chain coherence, pending sync queue invariants.
  5. Validation: The eight validation criteria, the three-group DAG pipeline, per-message-type pipelines, Driver Attestation verification, RWA Registry self-defense, the CRITICAL priority authority system.
  6. Regulatory Actions: The six regulatory actions in detail, action parameters, the escalation chain, scheduled regulatory actions.
  7. Cross-chain Protocol: Three-phase broadcast (PREPARE → COMMIT → FINALIZE), atomicity-level handling, primary and secondary finality structure.
  8. Fault Tolerance: At-least-once delivery (opens in a new tab) with idempotency (opens in a new tab), retry policies, the Dead Letter Queue (opens in a new tab), DLQ recovery protocol.
  9. Error Reference: The full error code namespace organized by category, with processing-action recommendations (REJECT, RETRY, ROLLBACK, ESCALATE).
  10. Conformance: MUST / SHOULD / MAY classification, minimum conformant implementation criteria, self-check list.
  11. Open Issues: Items deferred to subsequent versions, items reserved for future research, integration questions dependent on external standards.

Topic-First Reading (For Specific Concerns)#

Readers approaching with a specific question can enter the section at the relevant page.

ConcernEntry Point
What does an OIP message look like on the wire?Message Protocol
How are addresses represented across chains?Data Model § Address System
How does a regulatory action propagate across chains?Regulatory Actions + Cross-chain Protocol
What state transitions are valid for a frozen asset?State Management § Transition Matrix
What error code corresponds to insufficient authority?Error Reference § Authority Errors
How are duplicate messages handled?Fault Tolerance § Idempotency
What does it take to claim OIP v0.5 compatibility?Conformance
What does v0.5 deliberately leave unresolved?Open Issues

Reference Reading (For Maintenance and Lookups)#

Readers maintaining an existing integration or looking up a specific definition typically use Data Model, State Management, and Error Reference as standalone reference pages. Each is structured to be read in isolation once the terminology on this page is familiar.


Feedback and Specification Issues#

The OIP specification benefits from external review. Implementers, integrators, and reviewers who encounter ambiguity, inconsistency, or missing requirements are encouraged to report them through the channels below.

Confirmed issues that affect the specification will be acknowledged in the Changelog with the corresponding correction or version note.


References#

Normative References#

The following references are required to understand and implement this specification.

Informative References#

The following references provide background and context for the specification’s design but are not required for implementation.