Skip to main content

Migration & versioning

How OMY versions the SDK + contracts, what stays stable across releases, and how to migrate your consumer when something does change. Read this once before launching production code; reference it when you see release notes.

What's versioned​

Three things, each with its own version pace:

import {DocFeatures, DocFeature} from '@site/src/components/docs/DocFeatures';

TypeScript helpers. Semver. Breaking changes only in major bumps, documented in changelog. The cross-contract message format (TL-B layouts, opcodes). Pinned — any change is a new contract deployment at a new address. Phase 1 committee vs Phase 2 DVM. Interface to consumers stays identical; the underlying mechanism upgrades behind the resolver address.

Wire stability promise​

The cross-contract opcodes and TL-B layouts OMY uses are pinned. Specifically:

  • Every opcode in oracle-messages.tolk, factory-messages.tolk, market-messages.tolk — stable
  • Every struct exported from assertion-storage.tolk, market-storage.tolk — field order and types stable
  • All cross-contract bodies (CreateAssertion, OracleResult, OracleDisputed, Resolve, etc.) — stable

The SDK is a thin convenience layer over these primitives. If you ever need to talk to OMY contracts without the SDK at all, the Reference page lists every opcode and layout.

What "stable" means: we will not change these in a deployed contract. If we need to evolve the wire format, we ship v2 contracts at new addresses. Your existing consumer continues to work against the existing addresses forever (or until the contract self-destructs, which OMY contracts never do).

SDK versioning​

The SDK is pre-1.0 (current: 0.x) until mainnet. Semver applies once we hit 1.0:

Version bumpAllowed changes
Patch (0.1.0 → 0.1.1)Bug fixes, doc tweaks, typed return-shape clarification
Minor (0.1.0 → 0.2.0)New exports, new optional fields, new helper functions
Major (1.0.0 → 2.0.0)Breaking: removed exports, renamed exports, signature changes, type tightening

Today's SDK is 0.x — we may polish opcodes and signatures, but nothing in the SDK shape will change without a clear note in this changelog.

When contracts shift to v2​

If OMY needs to ship new contract behavior (which is rare; we minimize surface area on purpose), the playbook is:

  1. New addresses, not in-place upgrade. OMY contracts have no SetCode action. v2 = fresh deployment.
  2. Announcement window. Minimum 30 days before v2 contracts are recommended. New consumers start with v2; existing consumers can stay on v1.
  3. Coexistence. v1 keeps running. Both factories are addressable. The SDK ships address constants for both, and you choose at config-time.
  4. Documentation diff. A migration guide page ships alongside the v2 contracts explaining what changed and why your existing consumer probably doesn't need to migrate.
  5. No forced migration. v1 contracts on TON have no expiration. Your consumer can stay on v1 indefinitely. If you DO migrate, you do it on your schedule.

How to migrate your consumer (if needed)​

Three steps, in order:

  1. Read the migration guide for the specific change. Each contract-level shift gets its own page in /docs/migration/. Includes: what changed, what stayed the same, the diff for typical consumer code.
  2. Update your config. Point at the new factory address. Re-deploy your consumer (or, if it accepts factory via runtime message, just send a bind-update).
  3. Re-test against the new factory. Run your full integration suite. Verify gas measurements haven't regressed.

In OMY's lifetime so far (pre-mainnet), the wire format has been pinned since the build. No v2 contracts have been required.

Phase A → Phase B transition​

This is a scheduled, non-breaking event, not a contract migration:

  • The OracleFactory.UpdateMonetization opcode flips the treasury address from a multisig to a RewardsDistributor contract
  • Already-deployed assertions snapshot their treasury at spawn time and are unaffected
  • New assertions inherit the new treasury target
  • Consumer contracts don't change at all — the same OracleResult callback fires from the same Assertion contract type

The only thing that changes from your consumer's perspective: a fraction of the fees you've paid through OMY now flow to $OMY stakers instead of a multisig. The fee math is identical.

Indicators a change is breaking​

If a release announcement says any of these, treat it as breaking:

  • "New factory address" — re-deploy or re-config your consumer
  • "Opcode pinning change" — re-check your message-body builders
  • "Storage layout change" — re-derive any pre-computed addresses
  • "Removed export from SDK" — replace with the recommended alternative
  • "TL-B field type change" — re-check your parsers

None of these have happened in OMY's lifetime so far. Our goal is to keep that streak.

How to track changes​

import {DocCards, DocCard} from '@site/src/components/docs/DocCards';

Reporting compatibility issues​

If your consumer breaks against a OMY update, open a GitHub issue. Include:

  • Your SDK version (from package.json once we ship npm)
  • The factory address you're using
  • The tx hash + exit code of the failing call
  • A minimal reproducer if possible

Backwards compatibility is a hard promise. If we broke it accidentally, we'll fix it.