Data Model

This page is the type definition reference for OIP v0.5. It defines the enumerations, the address system, the hierarchical lock status, the identity types, the asset and contract types, the regulatory context types, and the field naming and type conventions used throughout the rest of the Protocol Specification section.

How to read this page. This is a reference page rather than a tutorial. Most readers will not read it from beginning to end on first contact. The recommended approach is to skim the Field Naming and Type Conventions section first, then jump to the type group needed for the page being read elsewhere in the specification. Subsequent pages in this section assume the conventions and definitions established here.

Type definitions are presented in TypeScript interface syntax for human readability. They are normative type signatures, not executable code. The wire-level encoding is fixed in the v0.6 .proto definitions.

Figure 1: OIP v0.5 Data Model Map

---

Field Naming and Type Conventions

The following conventions apply to every type definition in OIP v0.5. Subsequent sections of this page and subsequent pages in this section follow these rules without restating them. Readers who skim type definitions before reading this section may misinterpret field meanings; familiarity with the conventions is recommended before approaching the type groups below.

Naming

Data Types

Unit Suffixes

Time and duration fields encode their unit in the field name suffix. This rule prevents the same semantic dimension from carrying mixed units across the specification. All time and duration fields MUST follow this convention.

Null Handling

• When the semantics is “no value”, use null. Example: validUntil: null means “valid indefinitely”.
• When the semantics is “field absent”, use the optional marker ?. Example: omitting validUntil means “no validity information”.
• The two are not interchangeable. validUntil: null and an absent validUntil field carry different meanings and MUST be distinguished by implementations.

Version Notation

• Specification version: SemVer major.minor.patch (for example, "0.5.0").
• Message version field: version: "0.5.0" (full SemVer).
• The "v0.5" prefix appears only in prose. Data fields use SemVer without the v prefix.

Encoding

• Hex strings are lowercase by default. Addresses are the exception and follow EIP-55 mixed-case checksum.
• JSON serialization uses UTF-8 encoding.
• The wire format encoding is fixed in the v0.6 .proto definitions.

Core Enumerations

OIP v0.5 defines eight core enumerations and one additional signature-related enumeration introduced in v0.5 for cross-chain message integrity. Each is normative: implementations MUST recognize the values defined here. Treatment of unknown values follows the rules in this section and in Error Reference. Conformance requirements that aggregate the MUST-level rules from this section are summarized in Conformance.

OIPMessageType

The seven message types of OIP. Each type has its own validation pipeline (see Validation) and its own retry policy (see Fault Tolerance).

enum OIPMessageType {
  STATE_SYNC = 0x01,
  REGULATORY_ACTION = 0x02,
  LOCK_MANAGEMENT = 0x03,
  QUERY = 0x04,
  ACK = 0x05,
  HEARTBEAT = 0x06,
  GOVERNANCE = 0x07
}

PrimaryLockState

The authoritative asset state. PrimaryLockState is the canonical state on which all processing decisions depend; supplementary layers (such as SecondaryLockState) may be ignored by a receiver, but primary is never discarded. Every implementation MUST recognize all five values; an unknown value is rejected with INVALID_HEADER_FORMAT. The valid transitions between these states are defined in State Management. Versioning rules for changes to this enumeration are defined in Versioning and Compatibility Rules below.

enum PrimaryLockState {
  AVAILABLE = "AVAILABLE",
  RESERVED = "RESERVED",
  RESTRICTED = "RESTRICTED",
  SEIZED = "SEIZED",
  TERMINATED = "TERMINATED"
}

SecondaryLockState

An optional supplementary label that conveys finer-grained progress information. The enumeration is defined at the protocol level so that implementations agree on the meaning of these values, but the field that carries it (secondary in HierarchicalLockStatus) is OPTIONAL. Implementations are free to omit it or to add internal labels beyond the enumeration for their own purposes.

enum SecondaryLockState {
  PENDING_VERIFICATION = "PENDING_VERIFICATION",
  UNDER_REVIEW = "UNDER_REVIEW",
  AWAITING_CLEARANCE = "AWAITING_CLEARANCE",
  PROCESSING_TRANSFER = "PROCESSING_TRANSFER",
  COOLING_DOWN = "COOLING_DOWN"
}

Why enum at the protocol level, but field OPTIONAL. The decision reflects the fact that the five values do not all serve the same purpose. Some values, such as UNDER_REVIEW and AWAITING_CLEARANCE, combine with a RegulatoryContext or with a Driver Attestation’s verifiedClaims to influence how a receiving node handles the message; their meaning needs to be agreed upon by every implementation, which is why the enum is fixed at the protocol level. Other values, such as PENDING_VERIFICATION, PROCESSING_TRANSFER, and COOLING_DOWN, describe the sender’s internal progress and do not require the receiver to understand them. Making the enum protocol-level satisfies the first group; making the field OPTIONAL satisfies the second group. An implementation that does not need supplementary labels can omit the field entirely; an implementation that uses them must use one of the five enum values.

Unknown value handling. A receiving node that encounters an unknown SecondaryLockState value MUST ignore the field and decide based on primary alone. This is the deliberate asymmetry between the two: primary is authoritative and never ignored, while secondary is supplementary and may be discarded.

Forward compatibility exception. Although the v0.x compatibility policy permits breaking changes at minor version bumps, SecondaryLockState is an explicit exception: future versions MAY add new values, and existing nodes MUST handle them as described above. New SecondaryLockState values MUST NOT carry semantic meaning that affects processing decisions; meaningful state distinctions belong in PrimaryLockState or in dedicated authoritative fields. The full classification of allowed and prohibited changes is defined in Versioning and Compatibility Rules below.

RegulatoryActionType

The six regulatory actions specified by OIP. Each action’s parameters and processing rules are defined in Regulatory Actions. The Escalation Chain (FREEZE → SEIZE → CONFISCATE) is defined in State Management.

enum RegulatoryActionType {
  FREEZE = "FREEZE",
  SEIZE = "SEIZE",
  CONFISCATE = "CONFISCATE",
  LIQUIDATE = "LIQUIDATE",
  RESTRICT = "RESTRICT",
  RECOVER = "RECOVER"
}

AtomicityStrategy

The atomicity guarantee requested for cross-chain message delivery. The mapping from atomicity strategy to coordination pattern is defined in Routing.

enum AtomicityStrategy {
  BEST_EFFORT = "BEST_EFFORT",
  GUARANTEED = "GUARANTEED",
  ALL_OR_NOTHING = "ALL_OR_NOTHING"
}

Priority

Five priority levels used in routing and conflict resolution. CRITICAL messages receive additional authority verification (see Validation) and force the atomicity strategy to ALL_OR_NOTHING regardless of the requested value (see Routing).

enum Priority {
  CRITICAL = "CRITICAL",       // P0
  REGULATORY = "REGULATORY",   // P1
  HIGH = "HIGH",               // P2
  NORMAL = "NORMAL",           // P3
  LOW = "LOW"                  // P4
}

CoherenceState

The cross-chain coherence status of an asset. ROLLBACK_INCOMPLETE is a v0.5 addition that represents the transient state during multi-chain rollback before all participating chains have confirmed the rollback.

enum CoherenceState {
  SYNCED = "SYNCED",
  SYNCING = "SYNCING",
  DIVERGED = "DIVERGED",
  ROLLBACK_INCOMPLETE = "ROLLBACK_INCOMPLETE"   // v0.5 addition
}

ContractStatus

The legal status of a contract. ContractStatus and PrimaryLockState are orthogonal dimensions: a contract can be ACTIVE while its asset is RESTRICTED, or DISPUTED while the asset remains AVAILABLE. The interaction between these two dimensions is detailed in the OIPContract section below.

enum ContractStatus {
  PENDING = "PENDING",
  ACTIVE = "ACTIVE",
  COMPLETED = "COMPLETED",
  CANCELLED = "CANCELLED",
  DISPUTED = "DISPUTED"
}

SignatureType (v0.5 addition)

Identifies the signature scheme used in the message header. SignatureType is introduced in v0.5 alongside the eight core enumerations to support BLS threshold signatures used by the relayer set for cross-chain message integrity guarantees. THRESHOLD corresponds to this scheme; SINGLE preserves backward compatibility with single-sender signatures from earlier OIP drafts.

enum SignatureType {
  SINGLE = "SINGLE",        // single-sender signature (v0.1 compatible)
  THRESHOLD = "THRESHOLD"   // BLS threshold signature
}

Versioning and Compatibility Rules

The general v0.x compatibility policy permits breaking changes at minor version bumps. Two enumerations defined above carry stricter rules that override or refine that default. Implementations and downstream specifications MUST follow these rules. The Conformance page summarizes these rules at the requirement-strength level; this section is the normative source for the rule content.

PrimaryLockState change classification

PrimaryLockState is the authoritative state and directly affects every receiver’s processing decisions. The following changes are therefore always classified as major (incompatible) changes, regardless of the version number at which they are proposed.

• Adding a new value (MUST be major). Adding a sixth or further value to PrimaryLockState is always a major change. Existing nodes reject unknown values with INVALID_HEADER_FORMAT, so messages that use the new value cannot interoperate with prior versions.
• Changing the meaning of an existing value (MUST be major). Any change to the semantics of an existing value is always a major change.
• Removing a value (MUST be major). Removing any of the five values is always a major change.
• v0.5 stability intent. This specification is designed with the intent that the five values AVAILABLE, RESERVED, RESTRICTED, SEIZED, and TERMINATED remain unchanged through v1.0. Should a change become unavoidable, it is classified according to the rules above.

SecondaryLockState forward compatibility

SecondaryLockState is supplementary and OPTIONAL, and is the explicit forward-compatibility exception to the v0.x policy. The following rules apply.

• New values MAY be added at minor version bumps. Existing nodes MUST handle unknown values by ignoring the secondary field and deciding based on primary alone (as specified in the SecondaryLockState section above).
• New values MUST NOT carry semantic meaning that affects processing decisions. Any state distinction that drives a processing branch belongs in PrimaryLockState or in a dedicated authoritative field, not in SecondaryLockState.
• Violation reclassifies the change. If a future version introduces a SecondaryLockState value that does affect processing, that change is reclassified as a major change and requires the version negotiation procedure for major changes, not a minor bump.

This asymmetry between the two enumerations (PrimaryLockState always major, SecondaryLockState forward-compatible) reflects their semantic hierarchy: authoritative state versus supplementary label. Preserving the asymmetry is what makes the OPTIONAL design of the secondary field safe across versions.

Removed Enumerations

Three enumerations from earlier OIP drafts have been removed in v0.5. Their replacements or rationale are listed for implementers migrating from earlier drafts.

• PropagationMethod (GOSSIP, DIRECT): removed. Network propagation is out of OIP scope and is specified separately in a future propagation specification (see Open Issues).
• CoordinationStrategy (PARALLEL, SEQUENTIAL, STAGED): removed. The coordination pattern is now derived from AtomicityStrategy via the mapping defined in Routing.
• ContractExecution (ATOMIC, STAGED, CONDITIONAL): subsumed by AtomicityStrategy.

Address System

OIP uses a two-layer address scheme. The user-facing layer follows ERC-3770 with the shortName:0xAddress format for display and ingress. The internal processing layer uses a structured representation based on CAIP-2 chain identifiers (full specification at chainagnostic.org).

interface OIPAddress {
  chainId: string;   // CAIP-2 format (e.g., "eip155:42161")
  addr: string;      // EIP-55 checksummed hex address (e.g., "0x742d35...")
}

Why two layers. The internal structured form enables O(1) chain filtering, separates internal processing from external display, and preserves extensibility to non-EVM chain classes that may not fit the ERC-3770 short-name model. The user-facing form is reconstructed at display boundaries by formatting ${shortName}:${addr}.

Figure 2: Address System Layers

Short Name Registry

Short names are resolved against the ethereum-lists/chains registry. Conflicts and registry update lag are handled in the address resolution stage of the validation pipeline (see Validation).

EIP-55 Checksum Policy

All addresses MUST be processed under EIP-55 checksum semantics. The normalization policy balances input compatibility against checksum security as follows.

• Ingress normalization (input compatibility). An all-lowercase address is treated as “EIP-55 unspecified” rather than rejected. The receiver normalizes it to mixed-case and proceeds. This preserves compatibility with legacy lowercase systems.
• Mixed-case verification (security). A mixed-case address triggers EIP-55 checksum verification. A failed checksum is rejected with INVALID_ADDRESS_CHECKSUM.
• Egress mixed-case (MUST). The addr field of OIPAddress MUST be serialized in mixed-case EIP-55 form. A node that emits a lowercase address violates the specification.
• Routing slip recording. When ingress normalization occurs, the receiver MAY record the normalization in the routing slip’s mutations field (see Routing).

Rationale. Strict mixed-case enforcement breaks compatibility with existing lowercase systems, while unconditional lowercase acceptance loses the typo detection that EIP-55 was designed to provide. The “ingress normalize, egress enforce” compromise preserves both compatibility and security.

Hierarchical Lock Status

Asset state is represented as a hierarchical lock status. The hierarchical decomposition replaces the flat tier model used in earlier OIP drafts and persists in v0.5.

interface HierarchicalLockStatus {
  primary: PrimaryLockState;              // REQUIRED
  secondary?: SecondaryLockState;         // OPTIONAL
  regulatoryContext?: RegulatoryContext;
  temporalConstraints?: TemporalConstraint[];
  crossChainCoherence: CrossChainCoherence;
}

The hierarchical structure separates the authoritative state (primary) from supplementary progress information (secondary), regulatory context (regulatoryContext), time-bound constraints (temporalConstraints), and cross-chain synchronization status (crossChainCoherence). Each layer carries a different kind of information, and a receiving node can use whichever layers it understands while ignoring the rest.

Figure 3: Hierarchical Lock Status Decomposition

Composition Interfaces

The supplementary layers of HierarchicalLockStatus are defined by the following interfaces.

interface RegulatoryContext {
  authority: string;                       // identifier of the issuing authority
  authorityType: "GLOBAL" | "NATIONAL" | "INDUSTRY" | "SELF_REGULATORY";
  jurisdiction: string;                    // ISO 3166-1 alpha-2 or "EU", "GLOBAL"
  legalBasis: LegalReference;
  priorityLevel: number;                   // 0~10, higher is more urgent
  appealable: boolean;
}

interface LegalReference {
  documentType: "COURT_ORDER" | "REGULATORY_DIRECTIVE" | "EMERGENCY_ORDER" | "TREATY";
  documentHash: string;                    // 0x-prefixed hex (32 bytes)
  issuedAt: string;                        // ISO 8601
  validUntil: string | null;               // ISO 8601 or null (indefinite)
}

interface TemporalConstraint {
  type: "AUTO_EXPIRY" | "CONDITIONAL_RELEASE" | "PERIODIC_REVIEW";
  scheduledTime: string;                   // ISO 8601
  preconditions: string[];                 // condition expressions (Restricted DSL)
  automaticAction: "UNLOCK" | "ESCALATE" | "NOTIFY";
}

interface CrossChainCoherence {
  status: CoherenceState;
  lastSyncTime: string;                    // ISO 8601
  participatingChains: string[];           // CAIP-2 chain IDs
  primaryFinalityRecord?: PrimaryFinalityProof;
}

interface PrimaryFinalityProof {
  ossStateRoot: string;                    // 0x-prefixed hex (32 bytes)
  gkrProofHash: string;                    // GKR proof hash reference
  issuedAt: string;                        // ISO 8601
  ossEpoch: number;                        // OSS issuance epoch
}

The authorityType values correspond to the RCP authority hierarchy (Global > National > Industry > Self-Regulatory). "GLOBAL" is preferred over "INTERNATIONAL" to distinguish genuinely global authorities (FSB, BIS) from bilateral or multilateral arrangements that the term “international” would otherwise imply.

On TemporalConstraint.preconditions: the Restricted DSL grammar is restricted to a defined set of primitives without arbitrary code execution. The full grammar is specified in Regulatory Actions.

On PrimaryFinalityProof.ossEpoch: this is an OSS-internal monotonically increasing counter assigned at primary finality issuance. It is independent of the D-quencer consensus epoch; the relationship between the two (if any) is specified in v0.6.

Identity (OCID and RAI)

Oraclizer uses two identity layers. RAI (Regulated Asset Identity) is the EIP-standard generic interface for regulated asset identity. OCID (Oracle Contract ID) is the Oraclizer-specific implementation of RAI. v0.5 specifies the OCID structure; the RAI interface itself is defined as part of the ERC-TRUST work.

interface OCID {
  damlPartyId: string;                     // Canton Party ID (e.g., "Alice::1220abc...")
  zkId: string;                            // zk-basis ID (Privado.ID-based)
}

interface KYCStatus {
  isVerified: boolean;
  lastVerificationTimestamp: string;       // ISO 8601
  kycLevel: "NONE" | "BASIC" | "ENHANCED" | "FULL";
}

KYCStatus is defined here as a forward-reference type. Its consumption in messages and the validation flow that fills it is specified as part of the ERC-TRUST work; v0.5 fixes only the type shape so that earlier specification work can reference it without creating a circular dependency.

Party ID and OCID Mapping

The mapping between Canton Party IDs and OCIDs is governed by the following rules.

• Canton to OIP: when the Canton Driver receives a Party ID, it looks up the corresponding OCID in the mapping table and attaches it to the OIP message.
• OIP to Canton: when an OIP message carrying an OCID is delivered to Canton, the Driver extracts damlPartyId from the OCID for use within Canton.
• Mapping authority: the zk-basis ID system (KYC) verifies the connection between a Canton Party and a zkId. OCID registration records this connection in the RAI Registry.
• Mapping changes: changes to an existing mapping are made only through GOVERNANCE messages.

Multi-Party to multi-OCID mappings and the handling of mapping invalidation are explicitly listed as v0.5 deferred items; see Open Issues for the resolution timeline.

Asset and Contract Types

OIPAsset

interface OIPAsset {
  assetId: string;                         // unique asset identifier
  assetType: AssetType;
  balance: string;                         // big number as string
  metadata: object;                        // asset-specific metadata
  lockStatus: HierarchicalLockStatus;
}

type AssetType =
  | "ERC20" | "ERC721" | "ERC1155"
  | "ERC_TRUST"                            // ERC-TRUST tokens (Phase 5+)
  | "BOND" | "STOCK" | "DERIVATIVE"
  | "REAL_ESTATE" | "COMMODITY" | "IP";

assetId Ordering

The format of assetId is implementation-defined, but the ordering of assetId values MUST be deterministic across implementations. OIP relies on assetId-based sorting for deadlock prevention in multi-asset locking; if two implementations sort the same input differently, lock acquisition order diverges and the deadlock-prevention guarantee fails. The required ordering is:

• Sort algorithm: byte-sequence lexicographic comparison over the UTF-8 encoding of the assetId.
• Comparison: convert assetId to its UTF-8 byte sequence, compare byte by byte. If one sequence is a strict prefix of the other, the shorter sequence orders first.
• Locale-independent: locale-aware collation (e.g., ICU collation) MUST NOT be used. The same input MUST produce the same ordering on every node.

Standard byte-string comparison in most language runtimes satisfies this requirement (Rust’s Ord on &[u8], Go’s bytes.Compare, Python’s bytes comparison, and equivalent operations in other languages). Implementations satisfy the rule automatically as long as they do not impose a separate collation or locale-aware sort.

OIPContract

interface OIPContract {
  contractId: string;
  contractStatus: ContractStatus;
  contractLockStatus: PrimaryLockState;    // contract-level lock (separate from asset lock)
  participants: OCID[];
  regulatoryAction?: RegulatoryActionRef;  // active regulatory action reference
  oracleSession?: OracleSessionRef;        // active Oracle Session reference
}

interface RegulatoryActionRef {
  actionType: RegulatoryActionType;
  actionId: string;                        // messageId of the action message
  initiatedAt: string;                     // ISO 8601
  appealDeadline?: string;                 // ISO 8601 or undefined
}

interface OracleSessionRef {
  sessionId: string;                       // hash of (assetId + ownerOCID + sessionStart)
  sessionStart: string;                    // ISO 8601
}

ContractStatus and PrimaryLockState Orthogonality

ContractStatus tracks the legal status of a contract while PrimaryLockState tracks the operational state of the underlying asset. These are orthogonal dimensions and evolve independently. The following combinations occur in practice.

DISPUTED Transition Rules

• Entry into DISPUTED requires a separate dispute trigger (a GOVERNANCE message or an external dispute event). Regulatory actions do not automatically trigger DISPUTED.
• The exception is CONFISCATE with appealable: true, which automatically transitions to DISPUTED while the appeal is in progress.
• Recovery from DISPUTED back to ACTIVE is permitted only through a GOVERNANCE message (governance decision) or an external dispute-resolution trigger.
• TERMINATED is the final PrimaryLockState regardless of ContractStatus. Once the asset reaches TERMINATED, the contract status settles to COMPLETED or CANCELLED.

The orthogonal model preserves expressive power: a contract may be in dispute while the asset operates normally, or the asset may be locked without the contract being legally disputed. Collapsing these into a single dimension would erase the cases where the two diverge.

Regulatory Context Types

The full payload structure for regulatory action messages is specified in Regulatory Actions. This section defines the data-model-level skeleton.

interface RegulatoryPayload {
  actionType: RegulatoryActionType;
  targetAsset: {
    assetId: string;
    assetType: AssetType;
    currentStateHash: string;              // for idempotency
  };
  authority: AuthorityClaim;
  actionParameters: ActionParameters;       // action-specific
  evidence: Evidence;
}

interface AuthorityClaim {
  authorityId: string;
  authorityType: "GLOBAL" | "NATIONAL" | "INDUSTRY" | "SELF_REGULATORY";
  jurisdiction: string[];                   // multi-jurisdictional support
  legalBasis: LegalReference;
  priorityLevel: Priority;                  // CRITICAL triggers extra verification
}

interface Evidence {
  documentHashes: string[];                 // 0x-prefixed hex
  witnessSignatures: string[];              // optional witness signatures
  externalReferences: string[];             // external URLs or DOIs
}

The currentStateHash field on targetAsset binds the regulatory action to a specific observed state of the asset, which is used for idempotency: a duplicate delivery of the same action carrying the same currentStateHash is recognized as a duplicate and suppressed (see Fault Tolerance).

---

References to Other Specification Pages

The types defined here are used throughout the Protocol Specification section. The most common cross-references are:

• Message Protocol uses OIPMessageType, OIPAddress, SignatureType, and Priority in the unified header and routing metadata.
• State Management defines the transition matrix over PrimaryLockState and the cross-chain coherence semantics over CoherenceState.
• Regulatory Actions specifies the per-action parameters that fill ActionParameters in RegulatoryPayload.
• Routing uses AtomicityStrategy and Priority to determine coordination patterns.
• Conformance aggregates the MUST/SHOULD/MAY rules from this page (PrimaryLockState recognition, EIP-55 egress form, assetId ordering, and the versioning rules) into a single conformance checklist.
• Open Issues records v0.5 deferred items referenced from this page (multi-Party to multi-OCID mapping, mapping invalidation handling, KYCStatus consumption rules, RWA Registry Solidity signatures).
• Error Reference lists the error codes raised when type validation fails (INVALID_HEADER_FORMAT, INVALID_ADDRESS_CHECKSUM, and others).