Conformance

This page formalizes what it means for an implementation to claim OIP v0.5 compatibility. It classifies every requirement scattered across the Protocol Specification under the RFC 2119 keywords (MUST, SHOULD, MAY), states the minimum criteria a conformant implementation must satisfy, and provides a self-check list that an implementer can run against their codebase before claiming v0.5 compatibility.

Conformance is the contract that allows two independent implementations to interoperate without prior coordination. The other specification pages define the protocol’s mechanisms; this page fixes the obligations. When ambiguity arises between a mechanism page and this page on the strength of a requirement, this page is authoritative for the requirement strength, and the mechanism page is authoritative for the requirement’s content.

Audience. Implementers preparing a v0.5-compatible OSS, integrators verifying that a third-party implementation meets the v0.5 contract, and external reviewers (EIP editors, institutional partners, formal verification reviewers) using v0.5 conformance as an objective benchmark. Newcomers to OIP should approach OIP Overview first.

What is intentionally not on this page. Wire-level interoperability test vectors are deferred to v0.6 once the .proto definitions fix the byte format. The reasoning is recorded in the Interoperability Testing section below and in Open Issues. Conformance against the design-stage specification is what v0.5 offers; conformance against a wire-stable specification is a v0.6 deliverable.

---

RFC 2119 Keyword Application

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL are interpreted as described in BCP 14 [RFC 2119] [RFC 8174] when, and only when, they appear in all capitals as shown.

The three sections below aggregate the requirements from across the Protocol Specification into a single classified list. Each item links back to the page where its mechanism is defined.

MUST Requirements

Implementations claiming v0.5 compatibility MUST satisfy every requirement in this section. A failure on any single MUST requirement disqualifies the conformance claim.

Message Header and Identity

• Every OIP message MUST carry a complete OIPMessageHeader with all required fields populated. (Message Protocol)
• Message signature MUST verify under one of the two schemes carried in signatureType: SINGLE or THRESHOLD. SINGLE verification is mandatory; THRESHOLD support is governed by the SHOULD requirement below. (Message Protocol)
• Source authentication MUST be performed independently of signature verification: the cryptographic identity behind the signature MUST match the identity declared in the routing metadata. A valid signature on its own does not satisfy this check. (Validation)
• All EVM addresses MUST be processed under EIP-55 checksum semantics. The addr field of OIPAddress MUST be serialized in mixed-case EIP-55 form on egress; lowercase egress violates the specification. Mixed-case ingress that fails the checksum MUST be rejected with INVALID_ADDRESS_CHECKSUM. Lowercase ingress is normalized rather than rejected. (Data Model)
• Idempotency MUST be enforced keyed on messageId. Re-delivery of the same message MUST NOT cause duplicate state mutation. (Fault Tolerance)
• Messages whose TTL has expired MUST be rejected with MESSAGE_TTL_EXPIRED. The TTL check MUST occur at the routing boundary, before any validation pipeline executes. (Message Protocol, Routing)

Enumeration Recognition

• All five PrimaryLockState values MUST be recognized: AVAILABLE, RESERVED, RESTRICTED, SEIZED, TERMINATED. Unknown values MUST be rejected with INVALID_HEADER_FORMAT. (Data Model)
• All four CoherenceState values MUST be recognized: SYNCED, SYNCING, DIVERGED, ROLLBACK_INCOMPLETE. (Data Model, State Management)
• All five ContractStatus values MUST be recognized: PENDING, ACTIVE, COMPLETED, CANCELLED, DISPUTED. (Data Model)
• All seven OIPMessageType values MUST be recognized. An implementation MAY restrict which types it emits but MUST be able to receive and process all seven, including HEARTBEAT and ACK. (Message Protocol)
• All six RegulatoryActionType values MUST be recognized: FREEZE, SEIZE, CONFISCATE, LIQUIDATE, RESTRICT, RECOVER. (Regulatory Actions)
• All three AtomicityStrategy values MUST be recognized: BEST_EFFORT, GUARANTEED, ALL_OR_NOTHING. (Data Model, Routing)

State Transitions and Escalation

• The PrimaryLockState transition matrix MUST be enforced. Transitions not listed in the matrix MUST be rejected with INVALID_STATE_TRANSITION or the corresponding sequence-related error code. (State Management)
• The Escalation Chain (FREEZE → SEIZE → CONFISCATE) MUST be enforced. SEIZE on an asset whose state is not RESTRICTED MUST be rejected with FREEZE_REQUIRED_BEFORE_SEIZE. CONFISCATE on an asset whose state is not SEIZED MUST be rejected with SEIZE_REQUIRED_BEFORE_CONFISCATE. (State Management)
• CONFISCATE MUST execute only when FinalityProof.appealDeadlinePassed = true. Execution before the appeal deadline has elapsed MUST be rejected with APPEAL_PERIOD_NOT_EXPIRED. The literal true on this field is a hard requirement; missing or false values MUST be rejected. (Regulatory Actions)
• SEIZE action parameters MUST carry ownershipRetained: true as a literal-typed flag. CONFISCATE action parameters MUST carry ownershipRetained: false. Missing or contradictory values MUST be rejected as malformed input. (Regulatory Actions)
• LIQUIDATE action parameters MUST satisfy the constraint that the sum of sharePercent across all ProceedsDistribution.recipients equals totalShare, and totalShare equals 100. (Regulatory Actions)

Routing and Coordination

• Priority-based atomicity escalation MUST be applied before invoking the coordination decision. A CRITICAL message MUST be coordinated with ALL_OR_NOTHING atomicity and ALL_CHAINS scope regardless of the declared values. A REGULATORY message MUST have its atomicity raised to at least GUARANTEED if it was declared BEST_EFFORT. (Routing)
• The coordination decision function MUST be deterministic. Given identical inputs, every conformant node MUST produce identical outputs; non-determinism breaks cross-node interoperation and is a conformance violation. (Routing)
• The routing slip MUST be append-only. Existing entries MUST NOT be rewritten or removed; mutations MUST be recorded as deltas in new entries. (Routing)
• assetId ordering MUST be deterministic across nodes. Implementations MUST use byte-sequence lexicographic comparison over the UTF-8 encoding; locale-aware collation MUST NOT be used. (Data Model)

CRITICAL Authority Verification

• When a REGULATORY_ACTION message carries Priority.CRITICAL, receivers MUST run the five-step CRITICAL Authority Verification procedure during validation Group 1-C: confirm the priority value, resolve the authorityId against the Authority Registry, read the registered hierarchy level, verify that the requested targetScope is a subset of the authority’s permitted scope, and verify jurisdiction match for Levels 2 and 3. Any failure step MUST reject the message with the appropriate error code (AUTHORITY_NOT_REGISTERED, CRITICAL_PRIORITY_NOT_AUTHORIZED, or JURISDICTION_MISMATCH). (Regulatory Actions, Validation)
• Level 4 (SELF_REGULATORY) authorities MUST NOT be permitted to issue CRITICAL-priority actions. The maximum priority for Level 4 is REGULATORY. (Regulatory Actions)

Restricted DSL Determinism

Restricted DSL is used in FreezeParameters.autoUnfreezeCondition, SeizeParameters.releasePreconditions, RestrictParameters.conditionExpression, and ScheduledExecution.conditions. Conformant evaluators MUST satisfy the determinism rules below; any deviation breaks cross-node consensus on whether a condition is met.

• currentTime MUST be sourced from the OSS State Root timestamp agreed by D-quencer consensus. Local clocks MUST NOT be used.
• Numeric values MUST be signed 64-bit integers. Floating-point types MUST NOT be used.
• Integer overflow MUST cause explicit evaluation failure (treated as the condition being unmet). Silent wraparound MUST NOT occur.
• String comparison MUST use UTF-8 byte-sequence lexicographic order. Locale-dependent comparison MUST NOT be used.
• ISO 8601 timestamp comparison MUST normalize all values to UTC before comparing.
• Logical operator evaluation MUST proceed left-to-right with short-circuit semantics: AND stops at the first false; OR stops at the first true.
• References to absent fields MUST cause evaluation failure. Comparison against null or undefined MUST NOT be used as a defined operation. (Regulatory Actions)

Cross-chain Protocol

• The three-phase broadcast protocol (PREPARE → COMMIT → FINALIZE) MUST be implemented for messages with atomicity GUARANTEED or ALL_OR_NOTHING. (Cross-chain Protocol)
• All three atomicity levels MUST be supported as receivers. An implementation that emits only a subset is acceptable; an implementation that cannot process incoming messages of any level is not. (Cross-chain Protocol)
• Phase messages MUST carry a CrossChainPhasePayload with phase, originalMessageId, and phaseSequence fields populated. Routing metadata alone is insufficient for phase identification. (Cross-chain Protocol)
• Phase coordination ACKs MUST use one of the phase-aware ackType values (PHASE_PREPARE_OK, PHASE_COMMIT_OK, PHASE_FINALIZE_OK, PHASE_REJECT) paired with a populated PhaseAckContext. Using terminal ACK values (PROCESSED, FAILED) for a phase response is non-conformant. (Cross-chain Protocol)
• Receivers MUST process phase ACKs idempotently. Receiving the same phase message twice MUST produce the same ACK; duplicate processing on the receiver side is forbidden. (Cross-chain Protocol)
• ALL_OR_NOTHING rollback messages MUST be dispatched with BEST_EFFORT atomicity. Promoting a rollback to GUARANTEED or ALL_OR_NOTHING is a conformance violation because it produces unbounded recursion on rollback failure. (Cross-chain Protocol)
• The PrimaryFinalityRecord MUST be persisted in a verifiable form for the long term, beyond lock expiration and reconciliation events. The exact storage strategy is implementation-defined; the verifiability is normative. (Cross-chain Protocol, State Management)

Validation Pipeline

• All eight validation criteria defined in Validation MUST be applied. The order of execution within the three-group DAG is implementation-defined and MAY be parallelized; the criteria themselves MUST NOT be skipped.
• The Group 1 → Group 2 → Group 3 ordering MUST be preserved at the group level. Within each group, parallelism is permitted; across groups, the dependency order is normative.
• Address resolution (ERC-3770 short-name lookup, EIP-55 verification, CAIP-2 chainId expansion) MUST be performed during validation. (Validation)
• The deduplication cache MUST be written only after signature verification succeeds. Reading from the cache MAY proceed in parallel with other Stage 1-A checks, but writing an unverified messageId opens a cache-poisoning attack vector and is non-conformant. (Validation, Fault Tolerance)
• The deduplication cache window MUST satisfy windowSize ≥ max(perTypeTtl) + 2 × maxClockSkew. Implementations MAY run a separate window per message type, in which case each per-type window must individually satisfy the invariant. (Fault Tolerance)
• The deduplication cache MUST be persisted (durable across node restarts), with restoration on startup. An in-memory-only cache leaves a replay window every time the node restarts. (Fault Tolerance)
• For messages originating from Canton, attestation replay defense MUST check cantonContext.transactionId independently of messageId. A duplicate transaction wrapped in two distinct messageId values MUST be rejected with ATTESTATION_REPLAY_DETECTED. (Validation, Fault Tolerance)
• RWA Registry self-defense verification MUST be performed by RWA Registry contracts regardless of the path through which a transaction arrived. The four self-defense checks (caller identity, authority, primary finality record, escalation chain) MUST hold equally on the OIP path and the Force Inclusion path. (Validation)

Error Code Vocabulary

• The 36 error codes defined in Error Reference MUST be emitted under the conditions specified, and MUST be processed under the recommended action (REJECT, RETRY, ROLLBACK, ESCALATE, DIVERGE) when received.
• The five processing actions (REJECT, RETRY, ROLLBACK, ESCALATE, DIVERGE) MUST all be implemented. Conformant implementations cannot omit any action class. (Error Reference)
• The distinction between REJECTED and FAILED ACK types MUST be preserved. REJECTED indicates a structurally or contextually invalid message (sender-side problem); FAILED indicates a receiver-side state issue (refresh-and-retry path). Conflating the two breaks sender retry logic. (Error Reference)
• Implementations encountering an unknown error code MUST fall back to category-level handling based on the error code prefix. Forward compatibility for new codes within existing categories is normative; treating an unknown code as a fatal parse error is non-conformant. (Error Reference)

Retry, Lock, and Pending Sync Queue

• Per-type retry policies MUST be applied as defined in the Fault Tolerance retry policy table. Retries MUST reuse the original messageId; changing the messageId on retry breaks idempotency.
• Backoff MUST use exponential backoff with ±10% jitter, never exceeding the per-type max backoff value.
• CRITICAL REGULATORY_ACTION messages MUST be retried indefinitely. They MUST NOT enter the Dead Letter Queue. Other DLQ-enabled message types MUST be moved to the DLQ after maxRetries is reached.
• Lock TTL MUST exceed the worst-case retry window of the message holding the lock: lockTtl ≥ messageTtl + (maxRetries × maxBackoff). Violation creates state-machine corruption windows. (State Management, Fault Tolerance)
• The lock manager MUST satisfy four invariants: deadlock freedom (achieved through deterministic lock ordering), lock timeout safety (every lock released in finite time), no lost updates (concurrent updates blocked, not silently overwritten), and lock granularity correctness (asset-level locking prevents partial-update conflicts). (State Management)
• The pending sync queue MUST satisfy four invariants: deterministic tracking of which message has been applied to which chain, idempotency preservation on re-propagation, long-term primary finality preservation, and source-of-truth usage when resolving DIVERGED or ROLLBACK_INCOMPLETE states. (State Management, Fault Tolerance)
• DLQ entries MUST execute the four-step recovery protocol (notify, analyze, decide, record). DLQDecisionRecord entries MUST be signed by the decision-maker and retained indefinitely as audit-grade records. (Fault Tolerance)

Versioning

• Adding a new value to PrimaryLockState, changing the meaning of an existing value, or removing a value MUST be classified as a major change regardless of the version number proposed. (Data Model)
• New SecondaryLockState values MAY be added at minor version bumps; existing nodes MUST handle them by ignoring the secondary field and deciding based on primary alone. New SecondaryLockState values MUST NOT carry semantic meaning that affects processing decisions. (Data Model)
• New error codes MUST belong to one of the seven existing prefix categories. Introducing a new category requires a major version increase. Changing the meaning of an existing code is a major change. (Error Reference)

SHOULD Requirements

Implementations are strongly encouraged to satisfy the requirements below. Non-compliance does not invalidate a v0.5 conformance claim, but reduces operational quality, audit traceability, or compatibility with companion implementations.

• THRESHOLD signature support SHOULD be implemented. Implementations that omit THRESHOLD support MUST reject incoming THRESHOLD messages with INVALID_THRESHOLD_SIGNATURE; silent downgrade to single-signature semantics is forbidden. The recommendation is grounded in interoperability with the formally verified Cross-Chain Message Integrity property. (Message Protocol)
• SecondaryLockState value recognition SHOULD be implemented for all five values. Unknown values MUST be ignored. (Data Model)
• Driver Attestation verification SHOULD be performed by implementations that integrate with Canton or other off-chain Driver-based domains. The four-check protocol (driver signature, timestamp freshness, party mapping proof, transaction replay) is the SHOULD baseline. Without attestation verification, the off-chain origin’s authority claims cannot be cryptographically verified by the OIP receiver. (Validation)
• Authority Registry caching SHOULD be invalidated by registration epoch. A simple approach is to key the cache by registration epoch and treat any epoch change as a full invalidation. Caching without epoch-based invalidation produces stale CRITICAL authority decisions after governance changes. (Validation)
• Routing slip accumulation SHOULD be performed by every routing node. The slip is the primary audit substrate for cross-node behavior reconstruction; omitting it sacrifices traceability. (Routing)
• DIVERGED reconciliation SHOULD be triggered automatically upon detection. Manual reconciliation introduces operational delay during which assets are unavailable for trading. (State Management)
• Dead Letter Queue (DLQ) operation SHOULD be implemented for message types where DLQ is enabled (per the retry policy table in Fault Tolerance). DLQ alerting and analysis SHOULD be operationally supported, with alerts routed to configured channels at alertThreshold and immediately at criticalThreshold.
• Pending sync queue gap recovery SHOULD be triggered when HEARTBEAT.syncProgress.lagSeconds exceeds the configured threshold (default 300 seconds). (Fault Tolerance)
• Time-variant error context SHOULD attach the relevant timestamp (issuedAt, appealDeadline) to errorDetails.contextData when emitting LEGAL_BASIS_EXPIRED_OR_NOT_YET_VALID or APPEAL_PERIOD_NOT_EXPIRED. The operational benefit for automated retry schedulers is substantial. (Error Reference)
• Recommended TTL values per message type SHOULD be used. Implementations MAY override with longer values; senders MUST NOT undercut the asset-class minimum TTL floor. (Message Protocol)
• Slashing-eligible error patterns SHOULD be surfaced to the consensus layer. Repeated INVALID_SIGNATURE or INVALID_THRESHOLD_SIGNATURE failures from a single source within a short window indicate possible misbehavior; surfacing the pattern enables consensus-layer slashing review. The slashing decision itself is governed at the consensus layer, not in OIP. (Error Reference)

MAY Requirements

The following are optional features. An implementation that omits them is fully conformant; an implementation that includes them MUST do so per the specification’s semantics.

• The secondary field of HierarchicalLockStatus MAY be populated. Implementations choosing to populate it MUST use one of the five recognized SecondaryLockState values or omit the field entirely. (Data Model)
• Scheduled Regulatory Actions (scheduledExecution on a REGULATORY_ACTION message) MAY be supported. Implementations omitting support MUST reject scheduled action messages with the appropriate error code. (Regulatory Actions)
• Per-type deduplication windows MAY be operated rather than a single global window. Each per-type window must individually satisfy the windowSize ≥ max(perTypeTtl) + 2 × maxClockSkew invariant for its type. (Fault Tolerance)
• Asset-class-specific minimum TTL policies MAY be applied beyond the four classes recommended in the specification. The applied minimum MUST be the floor of final_ttl = max(sender_ttl, asset_min_ttl). (Message Protocol)
• Quantum-resistant signature schemes MAY be supported in addition to the v0.5 baseline schemes (Ed25519, ECDSA, BLS). Coexistence with baseline schemes MUST preserve the SignatureType discriminator semantics. The migration roadmap is recorded in Open Issues.
• Implementations MAY define additional message types beyond the seven specified, provided that (a) the new types do not collide with the v0.5 enumeration values and (b) other implementations encountering them respond with UNKNOWN_MESSAGE_TYPE. Forward compatibility for new types is at the discretion of the issuer. (Message Protocol)

---

Minimum Conformant Implementation

An implementation that satisfies all of the criteria below MAY claim “OIP v0.5 compatibility”. The criteria aggregate the MUST requirements from the previous section into seven functional groups.

Message Processing

• All seven message types are received and processed correctly, including HEARTBEAT and ACK.
• An implementation MAY restrict which message types it emits. A node-only implementation, for example, may legitimately omit GOVERNANCE emission while still receiving and dispatching incoming GOVERNANCE messages to its consensus layer.

Signature and Identity

• SINGLE signature verification is implemented (MUST).
• Source authentication is performed independently of signature verification (MUST).
• THRESHOLD signature verification is implemented (SHOULD). Omitted THRESHOLD support is acceptable provided that incoming THRESHOLD messages are rejected with INVALID_THRESHOLD_SIGNATURE.

State Model

• All five PrimaryLockState values are recognized and the transition matrix is enforced (MUST).
• The Escalation Chain is enforced and the literal-typed flags ownershipRetained and appealDeadlinePassed are validated (MUST).
• All five SecondaryLockState values are recognized; unknown values are ignored (SHOULD; ignore behavior is MUST).
• All four CoherenceState values are recognized and processed correctly (MUST).
• All five ContractStatus values are recognized and the orthogonal interaction with PrimaryLockState is preserved (MUST).

Validation Pipeline

• All eight validation criteria defined in Validation are applied (MUST). The execution order within the three-group DAG is free; the criteria are not.
• The Group 1 → Group 2 → Group 3 ordering is preserved at the group level (MUST).
• Address resolution is performed for both ERC-3770 inputs and EIP-55 checksum verification (MUST).
• The deduplication cache is durable and signature-verification-gated; the dedup window meets the invariant (MUST).
• RWA Registry self-defense (four checks) holds equally on the OIP path and the Force Inclusion path (MUST).

Regulatory Actions

• All six regulatory actions are recognized and their preconditions, postconditions, and parameter constraints are enforced (MUST).
• The five-step CRITICAL Authority Verification procedure runs on every CRITICAL message (MUST).
• Restricted DSL evaluation satisfies the seven determinism rules (MUST).

Error Handling

• All 36 error codes are emitted under their specified conditions (MUST).
• The five processing actions (REJECT, RETRY, ROLLBACK, ESCALATE, DIVERGE) are implemented (MUST).
• The REJECTED vs FAILED ACK distinction is preserved (MUST).
• Unknown error codes fall back to category-prefix handling (MUST).
• DLQ is operated for message types where DLQ is enabled in the retry policy table (SHOULD).

Cross-chain

• The three-phase broadcast (PREPARE → COMMIT → FINALIZE) is implemented (MUST).
• All three atomicity levels are supported as receivers (MUST).
• Phase messages carry CrossChainPhasePayload; phase ACKs use phase-aware ackType values with populated PhaseAckContext (MUST).
• Lock TTL alignment with retry windows is enforced (MUST).
• Rollback messages are dispatched with BEST_EFFORT atomicity (MUST).
• Primary finality records are preserved with verifiable retrieval (MUST).

---

Self-Check List

An implementation that can answer yes to every item below satisfies the OIP v0.5 minimum conformant implementation criteria. Each item references the specification page where its mechanism is defined.

The list is sufficient but not exhaustive. Implementations are encouraged to extend it with internal checks specific to their integration target (Canton, particular EVM chains, custom Drivers). The 34 items above are the floor.

---

Interoperability Testing

Wire-level interoperability test vectors are deferred to v0.6. This deferral is deliberate, not an oversight.

Interoperability tests at the wire level require a fixed byte-format encoding. v0.5 fixes the message semantics through the type definitions and processing rules, but the byte-level encoding is fixed only with the .proto definitions delivered in v0.6. Publishing test vectors against a wire format that has not yet been frozen would produce vectors that v0.6 would have to invalidate, which is worse than no vectors at all.

What v0.5 provides instead is a semantic conformance contract. An implementation can verify that its message handling, state transitions, validation pipeline, and error emission match the specification by exercising the self-check list above against its own test corpus. The matching is checked at the type-and-behavior level rather than at the byte level, which is the appropriate granularity for the design-stage specification.

The v0.6 release will accompany the public oraclizer/oip-spec repository, which will host the .proto definitions, a wire-format conformance test suite, and language-specific bindings (Rust, TypeScript, Go) generated from the .proto files. The interoperability test work is recorded as an explicit deferred item in Open Issues.

---

Related Pages

• OIP Overview establishes the boundary OIP draws and the v0.5 versioning context.
• Data Model defines the enumerations, address system, and type definitions referenced throughout this conformance specification.
• Message Protocol defines the unified header, routing metadata, and the seven message type payloads.
• Routing defines content-based routing, atomicity-driven coordination, and the priority escalation that conformance enforces.
• State Management defines the transition matrix, escalation chain, lock manager invariants, and pending sync queue invariants.
• Validation defines the eight validation criteria, the three-group DAG, RWA Registry self-defense, and CRITICAL authority verification.
• Regulatory Actions defines the six regulatory actions, the appeal-deadline gate on CONFISCATE, and the Restricted DSL determinism rules.
• Cross-chain Protocol defines the three-phase broadcast, the atomicity levels, and the BEST_EFFORT rollback rule.
• Fault Tolerance defines retry policy, idempotency, deduplication invariants, and DLQ recovery.
• Error Reference lists the 36 error codes, the five processing actions, and the extension policy.
• Open Issues records what v0.5 deliberately does not resolve, including the v0.6 interoperability test work.

References

• RFC 2119: Key words for use in RFCs to Indicate Requirement Levels
• RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
• ERC-3770: Chain-specific addresses
• EIP-55: Mixed-case checksum address encoding
• CAIP-2: Blockchain ID Specification