TL;DR
The essence of the Oracle Interoperability Protocol (OIP) lies in defining fundamental data structures for complex oracle state synchronization. While existing oracles remained limited to simple key-value data transmission, OIP provides a structured state representation system centered around four core elements: Asset, Identity, Contract, and Regulatory Action. These data structures transcend mere message formats, functioning as a semantic framework that enables complete state synchronization between on-chain and off-chain systems.
Introduction: Data Structure is Protocol
The most fundamental question we faced while designing the Oracle Interoperability Protocol was: “How do we represent the complex states of real-world assets as data?” While traditional oracles were satisfied with simple key-value pairs like “temperature 25°C” or “ETH price $3,000,” state synchronization oracles face much more complex challenges.
Consider a single tokenized treasury bond. This asset isn’t defined merely by its “price.” Countless pieces of state information must be managed simultaneously: who owns it, whether it’s currently used as collateral, what regulatory constraints exist, when it matures, and more. Furthermore, this information must be perfectly synchronized across different chains and off-chain systems.
“Data structures are not merely technical choices. They represent philosophical perspectives on how we understand and represent the world.” – Oraclizer Whitepaper
OIP’s data structure design started from this philosophical perspective. We sought to create a representation system that could completely recreate the essence of real-world assets in the digital world.
1. Asset: Complete Representation of Asset State
The Asset structure defined in OIP was designed to overcome the limitations of existing token standards. Beyond ERC-20’s simple balance representation or ERC-721’s ownership records, it’s a structure that can comprehensively contain all relevant states of an asset.
1.1 Core Elements of Asset Data Structure
interface Asset {
assetId: string; // Unique asset identifier
assetType: AssetType; // Asset classification system
balance: string; // String for precise decimal handling
lockStatus: LockStatus; // Asset lock state
lockExpiration?: number; // Expiration time for temporary locks
regulatoryAuthority?: RegulatoryAuthority; // Regulatory authority info
metadata: AssetMetadata; // Extensible metadata
}
The notable point here is the definition of assetType. While existing token standards treated all assets identically, OIP supports differentiated processing by asset type:
enum AssetType {
ERC20 = "ERC20",
ERC721 = "ERC721",
ERC1400 = "ERC1400", // Security tokens
BOND = "BOND", // Bonds
STOCK = "STOCK", // Stocks
REAL_ESTATE = "REAL_ESTATE", // Real estate
CARBON_CREDIT = "CARBON_CREDIT", // Carbon credits
GAME_ITEM = "GAME_ITEM" // Game items
}
1.2 Lock Status: Innovation in Concurrency Control
Particularly innovative is the introduction of LockStatus. This was designed to fundamentally prevent double-spending problems in cross-chain environments:
enum LockStatus {
UNLOCKED = "UNLOCKED", // Freely tradeable
TEMP_LOCKED = "TEMP_LOCKED", // Temporary lock (transaction in progress)
PERM_LOCKED = "PERM_LOCKED", // Permanent lock (collateral, etc.)
REGULATORY_LOCKED = "REGULATORY_LOCKED" // Regulatory lock
}
This locking mechanism is managed by the Oracle State Synchronizer (OSS) and prevents simultaneous transactions on the same asset through preemptive locking.
Important Note: The Asset structure’s balance field is stored as a string to avoid JavaScript’s floating-point precision issues. This ensures precise calculations essential for financial applications.
2. Identity: A New Paradigm for Unified Identity Management
The most innovative data structure in OIP is the Oracle Contract ID (OCID) system. This represents the first attempt to unify on-chain addresses, off-chain DAML Party IDs, and zero-knowledge proof-based identities.
2.1 Structural Design of OCID
interface OCID {
damlPartyId: string; // DAML contract participant identifier
zkId: string; // Zero-knowledge proof-based identity hash
chainId: string; // EIP-155 chain identifier
}
The true innovation of OCID lies in implementing System-wide AML (Anti-Money Laundering). While existing systems managed identities independently on each chain or platform, OCID enables unified identity tracking across the entire ecosystem.
2.2 Identity Resolution System
The most complex part of OCID’s actual implementation is the Identity Resolution system:
class OCIDResolver {
private identityGraph: Map<string, IdentityNode>;
private crossChainMappings: Map<string, string[]>;
async resolveIdentity(ocid: OCID): Promise<ResolvedIdentity> {
const unifiedId = this.computeUnifiedId(ocid);
return {
ocid,
unifiedId,
crossChainAddresses: await this.resolveCrossChainAddresses(ocid),
complianceStatus: await this.checkComplianceStatus(ocid),
riskScore: await this.calculateRiskScore(ocid)
};
}
}
This system connects various addresses used by the same real entity across multiple chains into one unified identity. For example, when the same institution uses 0x123… on Ethereum, 0x456… on Polygon, and alice_bank as a Party ID in CANTON, the OCID system recognizes and tracks them all as the same entity.
3. Contract: Lifecycle Management of Contract State
OIP’s Contract structure goes beyond simple smart contract addresses to become a data structure that tracks and manages the entire lifecycle of contracts.
3.1 Contract State Definition
interface Contract {
contractId: string; // Unique contract identifier
contractStatus: ContractStatus; // Contract progress state
contractLockStatus: LockStatus; // Contract-level lock state
participants: OCID[]; // List of participants
regulatoryAction?: RegulatoryAction; // Related regulatory measures
stateRoot: string; // Merkle root of contract state
}
enum ContractStatus {
PENDING = "PENDING", // Pending
ACTIVE = "ACTIVE", // Active
COMPLETED = "COMPLETED", // Completed
CANCELLED = "CANCELLED", // Cancelled
DISPUTED = "DISPUTED" // Disputed
}
3.2 Ensuring Contract Completeness
A particularly important concept in OIP is contract completeness. This is a core element for supporting simultaneous settlement models like DvP (Delivery versus Payment):
interface ContractExecution {
executionType: "ATOMIC" | "STAGED" | "CONDITIONAL";
preconditions: Condition[];
postconditions: Condition[];
rollbackPolicy: RollbackPolicy;
}
Through this structure, atomicity can be guaranteed even in complex financial transactions. For example, it fundamentally prevents situations where only one side is executed in an exchange of tokenized treasury bonds and USDC.
4. Regulatory Action: Technical Implementation of Regulatory Enforceability
The most challenging data structure design in OIP was Regulatory Action. This represents an innovative approach to finding balance between blockchain’s immutability principle and regulatory authorities’ need for intervention.
4.1 Six Granular Regulatory Actions
enum RegulatoryActionType {
FREEZE = "FREEZE", // Temporary transaction suspension
SEIZE = "SEIZE", // Court-ordered seizure
CONFISCATE = "CONFISCATE", // Permanent ownership deprivation
LIQUIDATE = "LIQUIDATE", // Forced liquidation
RESTRICT = "RESTRICT", // Conditional transaction restrictions
RECOVER = "RECOVER" // Recovery of stolen/fraudulent assets
}
4.2 Regulatory Authority Hierarchy
One of the most complex implementations is resolving priorities among regulatory authorities:
interface RegulatoryAuthority {
authorityId: string;
jurisdiction: string; // ISO 3166-1 alpha-2 country code
authorityType: AuthorityType;
priorityLevel: number; // Priority level
publicKey: string; // Public key for signature verification
}
enum AuthorityType {
COURT_ORDER = "COURT_ORDER", // Court orders (highest priority)
NATIONAL_REGULATOR = "NATIONAL_REGULATOR", // National regulators
INTERNATIONAL_BODY = "INTERNATIONAL_BODY", // International bodies
INDUSTRY_REGULATOR = "INDUSTRY_REGULATOR" // Industry-specific regulators
}
For example, when a US SEC FREEZE action conflicts with an international FATF SEIZE action, the system automatically resolves this according to predefined priority rules.
5. Interaction Among Data Structures: Integrated State Management
The true innovation of OIP is that these four core data structures organically interact to realize complete state synchronization.
5.1 State Transition Model
interface StateTransition {
transitionId: string;
fromState: SystemState;
toState: SystemState;
trigger: TransitionTrigger;
proof: ZKProof; // Validity proof of state transition
timestamp: number;
}
interface SystemState {
assets: Map<string, Asset>;
contracts: Map<string, Contract>;
identities: Map<string, OCID>;
activeActions: RegulatoryAction[];
stateRoot: string; // Merkle root of entire state
}
5.2 Meta Event Sourcing Pattern
OIP adopts a Meta Event Sourcing pattern. This is an innovative approach that utilizes each blockchain’s native event logs as-is while recording only the metadata necessary for cross-chain state synchronization:
// Utilize existing blockchain events without modification
// EthereumEvent: Transfer(alice, bob, 1000) <- Automatically recorded on Ethereum
// Meta events that Oraclizer additionally records only on L3
interface CrossDomainMetaEvent {
sourceChain: string; // "ethereum", "base", "polygon"
sourceEventHash: string; // Reference to original chain event hash
affectedDomains: string[]; // Affected domains
stateCoherence: SyncStatus; // Synchronization state
rollbackEligible: boolean; // Rollback eligibility
causality: EventCausalityRef; // Causality tracking
}
This enables maximum utilization of blockchain’s natural event sourcing while efficiently implementing Oraclizer’s unique requirements of cross-chain synchronization and regulatory rollback.
6. Challenges and Solutions in Real Implementation
6.1 Implementation of Meta Event Sourcing
The biggest challenge in cross-chain environments was utilizing each chain’s native event logs while ensuring cross-chain consistency. We developed a meta event sourcing approach:
class MetaEventSourcing {
// Don't touch each chain's native events
async captureNativeEvent(chainEvent: ChainEvent): Promise<void> {
// Only add cross-chain metadata to existing blockchain events
const metaEvent: CrossDomainMetaEvent = {
sourceChain: chainEvent.chainId,
sourceEventHash: chainEvent.hash,
affectedDomains: this.analyzeCrossDomainImpact(chainEvent),
stateCoherence: "pending",
rollbackEligible: this.isRollbackEligible(chainEvent),
causality: this.buildCausalityGraph(chainEvent)
};
// Store only in L3 meta store (don't record on each chain)
await this.l3MetaStore.record(metaEvent);
}
// Two-phase commit for cross-chain state synchronization
async executeAtomicUpdate(updates: CrossChainUpdate[]): Promise<UpdateResult> {
// Phase 1: Prepare native transactions on each chain
// Phase 2: Simultaneous commit on all chains + L3 metadata update
}
}
The essence of this approach is utilizing blockchain’s natural event sourcing as-is while solving Oraclizer’s unique cross-chain synchronization requirements with minimal additional recording.
6.2 Performance Optimization
For processing large-scale state data, we introduced incremental state update techniques:
interface StateDiff {
added: Partial<SystemState>;
modified: Map<string, Partial<any>>;
removed: string[];
proof: IncrementalProof;
}
This allows efficient synchronization of only changed parts without retransmitting entire states.
Tip: In actual implementation, we use a hybrid approach that monitors StateDiff size and switches to Full State Sync when it exceeds a certain threshold.
Conclusion: New Possibilities Created by Data Structures
OIP’s fundamental data structure design transcends mere technical choices to become the core foundation that realizes the new paradigm of state synchronization oracles. Through the organic combination of four core elements—Asset, Identity, Contract, and Regulatory Action—we have made possible, for the first time, complete state synchronization between on-chain and off-chain worlds.
“Good data structures make complex problems simple. OIP’s data structures transform the complex problem of state synchronization into an elegant solution.” – OIP Technical Documentation
We hope that these data structures we’ve designed will become the new standard for RWA tokenization, serving as a true bridge between traditional finance and DeFi.
Learn more: Actual implementation examples and test cases for OIP data structures can be found at docs.oraclizer.io.
References
- Martin Fowler. (2013). Patterns of Enterprise Application Architecture. Addison-Wesley Professional.
- IEEE Standards Association. (2008). IEEE Standard for Precision Time Protocol for Networked Measurement and Control Systems. https://standards.ieee.org/ieee/1588/4355/
- Chris Richardson. (2018). Microservices Patterns: With examples in Java. Manning Publications.
- Ethereum Foundation. (2023). EIP-155: Simple replay attack protection. https://eips.ethereum.org/EIPS/eip-155
