Versioning & deprecation

info

Status. stable policy. Specific version transitions are in the change log.

TL;DR

• Protocol version is a semver-shaped triplet (MAJOR.MINOR.PATCH).
• Breaking wire changes go in MAJOR; non-breaking additions in MINOR; fixes in PATCH.
• Mainnet breaking changes require a 90-day deprecation window with both old and new wire shapes accepted.
• Testnet runs ahead of mainnet to surface migration issues before production.

Version components

The protocol version is not served on the wire. No read returns it, so do not gate client behaviour on a version string fetched at run time. Take the version from the change log, and detect capability from the shapes the node actually accepts.

Component	Meaning	Examples
MAJOR	Breaking wire change	Renamed Order fields; removed action variant; changed signing domain; changed RPC URL shape
MINOR	Additive non-breaking	New action variant; new info type; new WS channel; new error string
PATCH	Behaviour-only fix	Bug fixes that preserve wire shape; performance

What's "wire shape"

Wire shape is everything a client commits to in its serialisation / signing logic. Specifically:

Wire-shape	Examples
Yes	Action type strings, field names, field types, enum values, response shape, status codes, error strings, EIP-712 domain
Yes	Numerical scaling conventions (fixed-point integers, USDC base units)
Yes	WS channel names, payload shapes, frame format
No	Server-internal storage; consensus implementation; mark/oracle source weights (governance-controlled, not protocol-versioned); fee tier thresholds (governance)

Governance-mutable parameters (fee tiers, mark composition weights, scenario shocks, liquidation thresholds) are not part of the wire-shape commitment. Their shape is committed; their values can move at any time.

Mainnet promise

Change class	Notification	Grace period
MAJOR (breaking)	90 days before activation	Both old + new shape accepted for ≥ 90 days
MINOR (additive)	0 days; announced in change log	n/a
PATCH (fix)	0 days	n/a

A MAJOR change is rolled out as:

The 90-day window matches institutional change-management cycles. Bot operators have plenty of time to migrate; clients can run dual-wire code during the overlap.

Deprecation warnings

During the overlap window, responses to the old shape include a non-fatal warning:

{
  "accepted": true,
  "mempool_depth": 3,
  "_deprecation": {
    "field":      "params.price",
    "deprecated_at_version": "2.0.0",
    "removal_at_version":    "3.0.0",
    "migration": "use px (string, fixed-point 10^8)"
  }
}

The _deprecation field is always optional in your parser — clients on the new shape never see it.

Change log

The protocol change log is published at https://mtf.exchange/changelog (TBD URL pre-launch) and mirrored in this repo at CHANGELOG.md. Each entry has:

• Version triple
• Date of activation
• Class (MAJOR / MINOR / PATCH)
• Per-change description with migration notes for MAJOR / MINOR

Subscribe via:

• RSS at https://mtf.exchange/changelog.rss
• GitHub Releases on this repo
• WS push on a planned _meta channel (TBD)

Testnet ahead of mainnet

Testnet typically runs 1–2 minor versions ahead of mainnet. Migration discoveries from testnet shake out before the mainnet rollout date. Bot operators with testnet integration get early warning of breaking changes.

What governance can change without versioning

The protocol layer is wire-versioned. Governance can mutate:

• Per-market parameters (tick size, leverage cap, maintenance ratio, mark composition, funding cap)
• Fee tier thresholds and rates
• PM scenario shock magnitudes and correlation matrix
• Liquidation tier thresholds and cooldowns (within bounds — substantial changes require MAJOR)
• Rate-limit budgets
• Insurance pool replenishment ratios

These changes do NOT bump the protocol version. They DO emit events on the planned _governance WS channel and are queryable via /info for their current values.

Clients that compute against current parameter values (e.g. computing PM margin client-side) must read parameters live; never hard-code.

Client SDK versioning

SDKs (@metaflux-dex/client for TypeScript, metaflux-client for Rust — the only two supported client SDKs) follow semver independently of the protocol:

• 0.x.y — pre-mainnet; breaking changes allowed each minor bump
• 1.x.y — post-mainnet; semver-strict on the API surface

An SDK's 1.x API surface targets a specific protocol MAJOR. When the protocol bumps MAJOR, the SDK bumps MAJOR; SDK 1.x supports protocol 2.x, SDK 2.x supports protocol 3.x, with overlap support during the 90-day window.

Pre-mainnet caveats

Until mainnet launch:

• Testnet runs the latest protocol MINOR/MAJOR ahead of mainnet's planned release; breakage on testnet is expected.
• Status banners in each doc reflect what's stable vs preview vs planned.

See also

• Networks — per-network endpoints + chainIds
• Security — security model and disclosure policy