OIP Overview

The Oracle Interoperability Protocol (OIP) is the state synchronization protocol specification for the Oraclizer Oracle State Machine. 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 implementers, protocol designers, and DeFi developers integrating Oraclizer state synchronization into their own systems. 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.

---

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, 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.
• Zero-knowledge circuit structure. The internal design of the StateSync-GKR proving stack is governed by separate specifications.
• 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 running on customized Polygon CDK. The diagram below illustrates the boundary OIP draws across these components and the contracts it establishes with adjacent systems.

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 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 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, bypassing OIP entirely. The RWA Registry self-defense principle (defined in Validation) ensures that an RWA Registry 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.

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.

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 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]. Additional formal verification work is currently in progress, addressing the composition of off-chain Driver Attestations with on-chain validation. Subsequent properties are scheduled for later specification stages and address the correctness of preemptive locking, the soundness of the rollback hierarchy, the structure of pre-trading versus settlement finality, and the integrity of cross-chain messaging.

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.

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 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: 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: 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: 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: 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: 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: The external settlement finality reached through fflonk → zkVerify → Base L2.
• Pending Sync Queue: 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: 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): 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: 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 [RFC 2119] [RFC 8174] 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.

Sequential Reading (Recommended for New Implementers)

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 + CAIP-2), the hierarchical lock status, identity types (OCID/RAI), 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, atomicity-driven coordination, priority-based atomicity escalation, the routing slip pattern.
4. State Management: The state transition matrix, preconditions and postconditions, the escalation chain, preemptive lock 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 with idempotency, retry policies, the Dead Letter Queue, 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.

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.

• GitHub: github.com/Oraclizer. The dedicated specification repository oraclizer/oip-spec opens with the v0.6 release; until then, specification issues can be raised through the existing public repositories.
• Formal verification questions: oraclizer/formal-verification. Questions about the alignment between the Isabelle/HOL models and OIP semantics belong here.
• Discussion and quick questions: @Oraclizer on X.

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.

• [RFC 2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997. https://www.rfc-editor.org/rfc/rfc2119
• [RFC 8174] Leiba, B., “Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words”, BCP 14, RFC 8174, May 2017. https://www.rfc-editor.org/rfc/rfc8174
• [ERC-3770] “Chain-specific addresses”, Ethereum Improvement Proposal. https://eips.ethereum.org/EIPS/eip-3770
• [CAIP-2] “Blockchain ID Specification”, Chain Agnostic Improvement Proposal 2. https://chainagnostic.org/CAIPs/caip-2
• [CAIP-10] “Account ID Specification”, Chain Agnostic Improvement Proposal 10. https://chainagnostic.org/CAIPs/caip-10

Informative References

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

• [CDSP] Oraclizer Formal Verification, “Safety and Liveness of Cross-Domain State Preservation under Byzantine Faults: A Mechanized Proof in Isabelle/HOL”. https://arxiv.org/abs/2604.03844