# 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 and Google's ProtoBuf, 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) grammar of an OBI schema.
# Pseudocode Implementation
Below is an example pseudocode 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 to see all currently available implementations.