Docs

Type a word to search all pages.

    Protocol Specification v0.6

    OIP Overview

    The Oracle Interoperability Protocol (OIP) (opens in a new tab) defines how state synchronization (opens in a new tab) participants encode a request, authenticate it and preserve its result across retries and recovery. OIP v0.6.0 adds a canonical Protocol Buffers schema, positional operation layouts and executable Rust and Go wire consumers to the design presented in v0.5.

    This edition is a complete reference for its own scope. The protocol core (opens in a new tab) and the reference profile are distinct: the core fixes interoperable bytes and product rules, while the profile records the choices made by the supplied reference implementation. OSS (opens in a new tab) is a separate product in development. It uses OIP; it is not the reference implementation in this repository.

    Core and profile

    One schema fixes the bytes for Rust and Go; only the Rust reference turns an admitted request into an effect.

    One schema fixes the bytes for Rust and Go; only the Rust reference turns an admitted request into an effect. The protocol core holds the schema proto/oip.proto with the Packet and the signed Core, the operation table spec/operations.json with the operands of every opcode, and the shared vectors under tests/vectors. One line leaves the core and splits to both packages: the bindings of each language are generated from the schema, and both test suites read shared vectors from the same folder. The Rust crate and the Go module both decode and admit packets in their wire packages. Only the Rust reference authority continues to the final consumer, which checks the current cut, role, lock and evidence, and then to the durable effect; the Go package is not a durable authority. Both packages together carry the reference profile, whose accepted operations, configured limits, storage, session tokens and host credentials are choices of this implementation. Protocol core 1 proto/oip.proto Packet and signed Core spec/operations.json operands of every opcode tests/vectors/ expected outcomes generated bindings and shared vectors Rust crate Go module Decode and admit src/wire/ Decode and admit go/wire/ 2 Final consumer current cut, role, lock and evidence Durable effect src/authority/ 3 not a durable authority Reference profile 4
    1. 1

      One schema, two bindings

      Both language bindings are generated from proto/oip.proto, and the operation table fixes the operands of every opcode. Both test suites read vectors from the same folder.

    2. 2

      A parse grants nothing

      A successful parse does not authorize an effect. The final consumer checks the current cut, role, lock and evidence for the exact decoded request.

    3. 3

      Wire and admission only

      The Go package implements the wire and admission surfaces. It is not the durable authority or a signed-response verifier.

    4. 4

      Profile choices

      Accepted operations, configured limits, storage, session tokens and host credentials are choices of the supplied reference implementation. Configured limits do not become network-wide constants.

    • Path of an admitted request
    • Rust reference authority
    • Not in the Go package

    Schematic: folders stand for the files that implement each step.

    Figure 1: The protocol core both languages follow, and the Rust-only path from an admitted request to an effect

    Who should read this edition#

    Protocol implementers, off-chain Driver builders and implementation reviewers should start with Wire Format and Field Tables. A DeFi application reads RWA Registry (opens in a new tab) contracts rather than exchanging OIP frames. Its reader can begin with System Architecture and State Synchronization.

    Specification boundary#

    NormativeBytes, test vectors and proofs

    SurfaceThis edition
    EnvelopeCanonical Packet and signed Core with fixed field numbers
    OperationsFamily and opcode select the exact word, blob and deadline layout
    AuthenticationCurrent registered identity, channel binding and per-operation authority
    EffectsOne authoritative request binding, recorded result and durable effect boundary
    RecoveryFresh authoritative state, exact retained outcomes and held unresolved obligations
    ImplementationRust reference authority and Go wire/admission package

    A successful parse does not authorize an effect. The final product consumer checks the current cut (opens in a new tab), role, lock and evidence for the exact decoded request. A transport timeout does not prove that a debit was reversed.

    The envelope is defined in one schema file, proto/oip.proto, from which both language bindings are generated. Its first message is the packet:

    Protocol BuffersPacketproto/oip.protoL1-L13Highlighted lines are discussed in the textSource (opens the lines on GitHub in a new tab)
    syntax = "proto2";package oip.v06;option go_package = "github.com/Oraclizer/oip-spec/go/wirepb";// The canonical OIP v0.6 wire schema. Receivers accept only the canonical// encoding of these messages and reject unknown fields; the encoding rules are// in spec/wire-conformance.md. New fields enter only through a new negotiated// version.message Packet {  optional Core core = 1;  optional bytes signature = 2;}

    Reference implementation#

    NormativeBytes, test vectors and proofs

    The public specification repository (opens in a new tab) contains the oip-spec Rust crate and the Go module github.com/Oraclizer/oip-spec/go. The specification, schema, field table, vectors, Rust reference implementation and Go bindings use Apache-2.0.

    The two package manifests name the crate and the module and pin their dependencies:

    Cargo.tomlCargo.tomlL1-L16Highlighted lines are discussed in the textSource (opens the lines on GitHub in a new tab)
    [package]name = "oip-spec"version = "0.6.0"edition = "2024"license = "Apache-2.0"publish = false[lib]path = "src/lib.rs"[dependencies]serde = { version = "=1.0.228", features = ["derive", "rc"] }serde_json = "=1.0.149"sha2 = "=0.10.9"prost = "=0.13.5"ed25519-dalek = { version = "=2.2.0", default-features = false, features = ["std"] }

    Both languages implement the wire and admission (opens in a new tab) surfaces identified by Conformance. The Go package is not the durable Rust authority or a signed-response verifier.

    Both test suites run from a fresh clone with the pinned toolchain, and the Rust suite runs the reference against the shared vectors:

    TextRun the Rust and Go testsREADME.mdL57-L61Source (opens the lines on GitHub in a new tab)
    git clone https://github.com/Oraclizer/oip-spec.gitcd oip-specrustup toolchain install 1.96.1 --profile minimalcargo +1.96.1 test --locked(cd go && go test -mod=readonly ./...)

    The reference profile accepts the operations marked as supported in Field Tables. Its storage, session tokens and host-supplied execution credentials are profile choices. Configuration limits do not become network-wide constants.

    Reading the status labels#

    Normative sections state the v0.6 contract and link it to the schema, vectors or verification artifacts. Design sections explain concepts carried from v0.5 that have no executable wire realization in this profile. A section label does not claim that every compiled instruction or external service is formally verified. Conformance states the assurance boundary.

    Design context#

    DesignCarried from v0.5, without bytes or test vectors in this version

    OIP belongs to the architecture described in the Core Concepts pages. Peer discovery, network-wide sequencing, arbitrary multi-hop relaying and the complete deployed OSS service are outside this edition's executable reference. The v0.5 migration guide identifies replaced and unimplemented design surfaces instead of implying wire compatibility.

    Related Pages#

    Edition history#

    • 0.6.0: Added this edition. The v0.5 specification remains available at its original addresses.