protocol-versions

Protocol Versions and Migrations

The protocol version is the count of upgrades applied to a network, starting at 0 at genesis. Genesis is immutable — it is the network's identity — so every change to CVM semantics after launch arrives as a scheduled migration that increments the version by exactly 1.

Full design: convex-core/docs/UPGRADE.md. Read it before authoring a migration; this skill is orientation and conventions.

Write Against v1

v1 is the target. It is the first upgrade, it bundles every bug known at genesis, and it is what networks will be running. Unless you are specifically reasoning about live or historical behaviour, v1 semantics are the semantics.

This is the project's own test convention — three state roles, each answering a different question:

Migrations.LIVE_VERSION is bumped when, and only when, the live network applies an upgrade. Everything pinned to LIVE follows automatically.

What v1 Contains

The bootstrap — installing schedule-upgrade / unschedule-upgrade plus the new core functions gensym, cat, splice and char? (#92) — and fixes that could not ship any other way, because a naive fix would move the genesis hash:

Two of these change behaviour agents rely on — see the trust and token skills, which document the v1 behaviour and flag the pre-v1 trap.

Changing CVM Behaviour

Where the change lives determines the strategy.

Tier 1 — state-resident core. Functions defined in core.cvx are compiled into account #8 at genesis; they are state. Fix by migration: replace the binding with the recompiled definition. No Java version branch.

Caveat: the compiler statically links core symbols, so already-deployed actors keep the old embedded function unless the migration also sweeps environments. Whether to sweep is a per-upgrade decision.

Tier 2 — native semantics. Opcodes, native core functions, juice costs and cast rules are the transition function, in Java. These change by version-keyed dispatch:

long cost = (state.getProtocolVersion() >= 3) ? Juice.NEW_COST : Juice.OLD_COST;

Whether a gate is needed is decided by replay evidence, not judgement. Make the change unconditional locally and run SnapshotStateTest: if the replay hash moves, recorded history exercised the old semantics and the gate is mandatory; if not, it ships unconditionally with no permanent branch. Branches are permanent — replay from genesis needs every historical semantics.

Adding a core function means a new core definition code, registered with regNonGenesis and installed by a migration — never into genesis. Standing rule (amended 2026-08-13): no release adds a code beyond 506 unless it ships, in the same release, at minimum a 506-style in-definition version gate — fail-first below the introducing version, before arity checking or any other work (char?, code 506, is the model). Once v1 has activated on the live network, full versioned materialisation is required instead. Rationale: the decode-skew policy in UPGRADE.md.

Tier 3 — encodings. Decoding happens outside any state context, so it cannot branch on version. Decoders stay permissive of all historical forms forever; the version gates what the CVM writes and canonicalises. See the cad3-encoding skill — this is why a permissive decoder is correct rather than a bug.

Authoring a Migration

• Purity is a hard contract. A migration is State → State with no clock, randomness or I/O. An impure migration forks the network.
• The list is append-only forever. Position is identity — Migrations.get(k) produces version k+1 — so never insert or reorder.
• Test the exact delta. Every migration needs tests asserting precisely what changed and that nothing else did (compare untouched subtrees by hash).
• Failure at an activation boundary makes peers withdraw from consensus rather than produce a state — a stall is recoverable, divergence is not.

MigrationFixesTest owns the intended differences between genesis and upgraded semantics; add to it when a migration changes observable behaviour.

Fresh Networks

Launchers that create a new genesis (local start, peer genesis, peer start --genesis, GUI local networks) apply all migrations at creation, so a fresh network starts at MAX_VERSION — it has no history to preserve and should not launch with known-fixed bugs.

Pin a lower version with --protocol-version (CLI) or :protocol-version (peer config) to mirror a network that has not yet upgraded. This is how you reproduce live behaviour locally while v1 is pending.