midnight-tooling:midnight-compatibility

Midnight Version Compatibility

Understanding version relationships between Midnight components.

Component Overview

Midnight development involves multiple versioned components:

Version Relationships

Language Version (in pragma)
         │
         ▼
┌─────────────────────────┐
│   Compact Compiler      │ ──── Produces ───▶ Contract Artifacts
│   (e.g., 0.26.0)        │
└─────────────────────────┘
         │
         │ Must match
         ▼
┌─────────────────────────┐
│   compact-runtime       │
│   (e.g., 0.9.0)         │
└─────────────────────────┘
         │
         │ Compatible with
         ▼
┌─────────────────────────┐
│   ledger, midnight.js   │
│   Proof Server          │
└─────────────────────────┘

Checking Current Compatibility Matrix

The authoritative source is the support matrix in Midnight release notes.

To check current recommended versions:

/​midnight:versions

Or parse directly:

python3 ${CLAUDE_PLUGIN_ROOT}/​scripts/​parse-support-matrix.py

Pragma Language Version

Every Compact contract must declare its language version:

pragma language_version 0.18;

ledger {
  // ...
}

Pragma Rules

1. Must match compiler capability: The compiler must support the declared version
2. Consistency: All contracts in a project should use the same pragma
3. Update on upgrade: When upgrading compiler, update pragma if language version changed

Finding Language Version for Compiler

The compiler version (e.g., 0.26.0) maps to a language version (e.g., 0.18.0):

# Check release notes for mapping
/​midnight:changelog compact

Recent mappings (verify with release notes):

• Compiler 0.26.0 → Language 0.18.0 (Minokawa)
• Compiler 0.25.0 → Language 0.17.0

Package Version Guidelines

Use Exact Versions

In package.json, always use exact versions:

{
  "dependencies": {
    "@midnight-ntwrk/​compact-runtime": "0.9.0",
    "@midnight-ntwrk/​ledger": "4.0.0",
    "@midnight-ntwrk/​midnight.js": "2.1.0"
  }
}

Never use:

• ^0.9.0 (allows minor updates)
• ~0.9.0 (allows patch updates)
• >=0.9.0 (allows any newer version)

Why Exact Versions Matter

Midnight components have strict compatibility requirements. A minor version bump in one component may require updates to others. Using ranges can lead to:

• Silent incompatibilities
• Works-on-my-machine issues
• CI failures with different lockfiles

Using npm ci

For reproducible builds, use npm ci instead of npm install:

# npm ci uses exact versions from package-lock.json
npm ci

# npm install may update within semver ranges
npm install  # Avoid for production

Compiler Version Management

List Available Versions

compact list

List Installed Versions

compact list --installed

Switch Default Version

# Update to latest
compact update

# Switch to specific version
compact update 0.25.0

Use Specific Version for One Compilation

# Prefix with +version
compact compile +0.25.0 src/​contract.compact contract/

This is useful for:

• Testing against multiple compiler versions
• Maintaining older contracts while developing new ones
• Gradual migration

Proof Server Versions

The proof server must be compatible with your contracts:

# Check available tags
docker search midnightnetwork/​proof-server

# Pull specific version
docker pull midnightnetwork/​proof-server:4.0.0

# Run specific version
docker run -p 6300:6300 midnightnetwork/​proof-server:4.0.0 -- midnight-proof-server --network testnet

Breaking Changes Between Versions

When upgrading, check release notes for breaking changes:

/​midnight:changelog compact

Common breaking changes include:

• New reserved keywords (e.g., slice in 0.18.0)
• Runtime function renames
• Type system changes
• New pragma requirements

Version Upgrade Workflow

1. Check current versions: /​midnight:versions
2. Check target versions: Review compatibility matrix
3. Read release notes: /​midnight:changelog <component>
4. Update package.json: Use exact versions
5. Update compiler: compact update <version>
6. Update pragma: If language version changed
7. Clean install: rm -rf node_modules && npm ci
8. Recompile: compact compile src/​*.compact contract/
9. Test: Run your test suite

Additional Resources

• references/​compatibility-matrix.md - Detailed version compatibility table
• references/​pragma-guide.md - Pragma declaration guide

For troubleshooting version issues, see the midnight-debugging skill.