# Oracle Binary Encoding (OBI)
Oracle Binary Encoding (OBI) is a standard method for serializing and deserializing binary data in the BandChain ecosystem. Under the concept of Ethereum's Contract ABI Specification (opens new window) and Google's ProtoBuf (opens new window), an OBI schema explains how a data object in any supported programming language can be encoded to and decoded from plain bytes.
OBI is designed with the following properties in mind:
- Compactness: OBI schema will be stored on-chain and passed around between blockchains. Thus, it is essential to keep the size of the schema specification tiniest.
- Simplicity & Portability: As a blockchain-agnostic protocol, OBI serialization and deserialization must be easy to implement in any environment. Consequently, complex platform-specific features are not supported.
- Readability: Lastly, OBI is intended to be used as a communication tool between oracle script creators and smart contract developers. It must be intuitive for readers to understand the OBI underlying objects from reading the schema.
# Specification
An OBI schema is a non-self-describing binary serialization format of multiple objects. Some particular notes:
- An OBI schema consists of one or more individual schemas. In most cases, an OBI schema will consist of two individual schemas: the input type and the output type.
- bool is supported.
- 6 sizes (8-bit, 16-bit, 32-bit, 64-bit, 128-bit, and 256-bit) of signed and unsigned integers are supported. There are all serialized into big-endian bytes.
- Strings, bytes, vectors are serialized with their length as u32 first, followed by their contents.
- Structs are serialized field by field in the declaration order.
# Backus–Naur Form (BNF) Grammar Specification
Below is the Backus–Naur form (BNF) (opens new window) grammar of an OBI schema.
# Pseudocode Implementation
Below is an example pseudocode (opens new window) implementation of OBI schema declaration and the corresponding serializing function in a somewhat broken function language 😛. The deserialization function is essentially the inverse of the serialization function.
# OBI Schema Examples
Below is an example OBI schema of an oracle script to fetch a cryptocurrency price, which is then multiplied by a specific multiplier. The OBI itself schema consists of two internal schemas, one for the inputs to the oracle script and the other for the output.
- The input consists with two fields: a string symbol and a u64 multiplier.
- The output consists with two fields: a u64 final price and a vector of struct each has string name and u64 timestamp.
# Example Object Serialization
# Reference Implementations
OBI serialization libraries are being actively developed in multiple programming languages. Head over to BandChain's OBI module (opens new window) to see all currently available implementations.