Skip to main content
For the complete documentation index, see llms.txt

Compatibility matrix


This compatibility matrix, also called the support matrix, lists the Midnight component versions tested against Preview, Preprod, and Mainnet. For releases that don't work with these versions, see Known incompatible combinations.

Mainnet, Preview, and Preprod all run ledger 9 with the same versions. For what changed and what to update, see Ledger 9 upgrade.

The client versions include the 1.1 patch of 17 November 2026: Compact toolchain 0.36.1, Compact JS 3.0.2, Wallet SDK 2.0.1, Midnight.js 5.0.1, and proof server 9.0.2. The patch fixes contract calls that the networks rejected with the earlier versions, so move to it. The networks didn't change, and you don't need to recompile or redeploy your contracts.

note

This matrix only reflects the latest tested versions. Earlier versions may still work, but we do not guarantee compatibility or provide support for them.

Preview support matrix​

Preview runs ledger 9, with the same versions as Mainnet. Preview relaunched as a new chain on 7 November 2026 and was upgraded to ledger 9, so contracts deployed to Preview before the relaunch are gone and you must redeploy them.

Functional areaComponentVersionNotes
NetworkNode (Midnight)2.1.101Preview network node (ledger 9)
Runtime and contractsCompact devtools (compact)0.5.1Installs compilers, compiles contracts
Compact toolchain (compact compile)0.36.1Contract compiler for ledger 9. Language version 0.28.0
Compact runtime0.21.0Runtime library for contracts. npm: @midnight-ntwrk/compact-runtime
Compact JS3.0.2TypeScript execution environment for compiled contracts. npm: @midnight-ntwrk/compact-js
Platform JS3.0.0Core abstractions and types. npm: @midnight-ntwrk/platform-js
On-chain runtime4.0.2On-chain runtime support (v4). npm: @midnightntwrk/onchain-runtime-v4
SDKs and APIsWallet SDK2.0.1SDK for building wallet integrations. npm: @midnightntwrk/wallet-sdk
Midnight.js5.0.1DApp framework: contracts, types, providers. npm: @midnight-ntwrk/midnight-js
testkit-js5.0.1E2E testing framework. npm: @midnight-ntwrk/testkit-js
DApp Connector API4.1.0Interface between DApps and wallets. npm: @midnightntwrk/dapp-connector-api
Indexing and dataMidnight Indexer4.4.101Preview indexer (ledger 9)
ZK and proving servicesProof server9.0.2Handles ZKP proof generation for ledger 9

Preprod support matrix​

Preprod runs ledger 9, with the same versions as Mainnet. Preprod was upgraded in place to ledger 9 on 9 November 2026, so its chain history, deployed contracts, and balances carried over. The Mainnet upgrade guidance, such as keeping ledger 8 contracts with verify: 'require-if-present', applies to Preprod too.

Functional areaComponentVersionNotes
NetworkNode (Midnight)2.1.101Preprod network node (ledger 9)
Runtime and contractsCompact devtools (compact)0.5.1Installs compilers, compiles contracts
Compact toolchain (compact compile)0.36.1Contract compiler for ledger 9. Language version 0.28.0
Compact runtime0.21.0Runtime library for contracts. npm: @midnight-ntwrk/compact-runtime
Compact JS3.0.2TypeScript execution environment for compiled contracts. npm: @midnight-ntwrk/compact-js
Platform JS3.0.0Core abstractions and types. npm: @midnight-ntwrk/platform-js
On-chain runtime4.0.2On-chain runtime support (v4). npm: @midnightntwrk/onchain-runtime-v4
SDKs and APIsWallet SDK2.0.1SDK for building wallet integrations. npm: @midnightntwrk/wallet-sdk. Wallet SDK 1.x can't transact on Preprod after the upgrade
Midnight.js5.0.1DApp framework: contracts, types, providers. npm: @midnight-ntwrk/midnight-js
testkit-js5.0.1E2E testing framework. npm: @midnight-ntwrk/testkit-js
DApp Connector API4.1.0Interface between DApps and wallets. npm: @midnightntwrk/dapp-connector-api
Indexing and dataMidnight Indexer4.4.101Preprod indexer (ledger 9). Blockfrost serves the Preprod indexer
ZK and proving servicesProof server9.0.2Handles ZKP proof generation for ledger 9

Mainnet support matrix​

Mainnet runs ledger 9. Use these versions for anything that runs against Mainnet. For upgrade steps, see Ledger 9 upgrade.

Functional areaComponentVersionNotes
NetworkNode (Midnight)2.1.101Mainnet network node. Every Mainnet validator and RPC node must run this release before the ledger 9 network upgrade. Upgrade directly from 1.0.400 or 2.1.100, upgrade block producers together, and snapshot the data directory first
Runtime and contractsCompact devtools (compact)0.5.1Installs compilers, compiles contracts
Compact toolchain (compact compile)0.36.1Contract compiler for ledger 9. Language version 0.28.0
Compact runtime0.21.0Runtime library for contracts. npm: @midnight-ntwrk/compact-runtime
Compact JS3.0.2TypeScript execution environment for compiled contracts. npm: @midnight-ntwrk/compact-js
Platform JS3.0.0Core abstractions and types. npm: @midnight-ntwrk/platform-js
On-chain runtime4.0.2On-chain runtime support (v4). npm: @midnightntwrk/onchain-runtime-v4
SDKs and APIsWallet SDK2.0.1SDK for building wallet integrations. npm: @midnightntwrk/wallet-sdk. Wallet SDK 1.x can't transact on Mainnet after the upgrade
Midnight.js5.0.1DApp framework: contracts, types, providers. npm: @midnight-ntwrk/midnight-js
testkit-js5.0.1E2E testing framework. npm: @midnight-ntwrk/testkit-js
DApp Connector API4.1.0Interface between DApps and wallets. npm: @midnightntwrk/dapp-connector-api
Indexing and dataMidnight Indexer4.4.101Mainnet indexer. Operators must re-index from genesis
ZK and proving servicesProof server9.0.2Handles ZKP proof generation for ledger 9

Known incompatible combinations​

All three networks run ledger 9 and accept only the ledger 9 versions in the matrices above. Most ledger 8 versions, such as Compact toolchain 0.31.1, Midnight.js 4.1.1, and Wallet SDK 1.2.0, don't work on any of them. The table and the paragraph after it list the cases. Mainnet and Preprod were upgraded in place, so rows about the upgrade itself, such as node upgrades, pending ledger 8 transactions, and contracts deployed before the upgrade, apply to both. Preview relaunched as a new chain, so nothing carried over there. For the full list of changes, see Ledger 9 upgrade.

CombinationResult
Transactions built for ledger 8, submitted to Mainnet, Preview, or PreprodThe ledger 8 transaction format doesn't decode on ledger 9, so every network rejects these transactions. On Mainnet and Preprod, this includes transactions built and proved before the upgrade but not yet submitted.
Node 1.0.400 with Mainnet or PreprodA 1.0.400 node stops at the ledger 9 upgrade block. Upgrade directly to node 2.1.101, from 1.0.400 or 2.1.100. Node 2.1.0 release candidates aren't a supported upgrade step. The binary upgrade is one-way: once 2.1.101 opens a data directory, 1.0.400 can't start on it, so snapshot the data directory first.
Node 2.1.101 set to storage_separation=unified on an existing 1.0.400 data directoryThe node stops importing blocks. The process keeps running with no crash and no peers, so liveness checks don't flag it. Keep the default separate storage layout for this upgrade. To move to unified, stop the node, delete the whole data directory (chains/ and ledger_storage/), and resync.
Wallet SDK 1.x, including 1.2.0, with Mainnet, Preview, or PreprodWallets on Wallet SDK 1.x can't transact on ledger 9. Move to the wallet SDK version in the Mainnet matrix.
Midnight.js 4.1.1 with Mainnet, Preview, or PreprodMidnight.js 4.1.1 builds ledger 8 transactions, which ledger 9 networks reject. Move to Midnight.js 5.
Compact runtime 0.19.0, 0.20.0, or 0.21.0 with Midnight.js 4.1.1Midnight.js 4.1.1 pins @midnight-ntwrk/compact-runtime to 0.16.0 and @midnight-ntwrk/onchain-runtime-v3 to 3.0.0. Compact runtime 0.19.0, 0.20.0, and 0.21.0 depend on @midnightntwrk/onchain-runtime-v4 instead. Even when the toolchain matches the runtime, deployContract throws Failed to configure constructor context with coin public key. The coin public key isn't the cause: Midnight.js 4.1.1 doesn't support contracts compiled for ledger 9.
Compact toolchain 0.34.0, 0.35.0, 0.36.0, or 0.36.1 with Compact runtime 0.16.0Importing the compiled contract throws Version mismatch: compiled code expects 0.19.0, runtime is 0.16.0. For toolchain 0.35.0, the expected version is 0.20.0. For toolchain 0.36.0 and 0.36.1, it's 0.21.0.
Compact toolchain 0.31.1 with Compact runtime 0.19.0, 0.20.0, or 0.21.0Importing the compiled contract throws Version mismatch: compiled code expects 0.16.0, runtime is 0.20.0. The message ends with the runtime version you installed, so for Compact runtime 0.21.0 it ends with runtime is 0.21.0.
Midnight.js 5 with a transaction built for ledger 8Midnight.js 5 throws EraMismatchError with the reason ledger8-transaction-on-ledger9-network and doesn't submit the transaction.
Wallet SDK 2 with a transaction built for the other ledgerWallet SDK 2 refuses the transaction with ProtocolVersionMismatchError.
Indexer versions earlier than 4.4.101 with Mainnet or PreprodThe 4.3 line doesn't index ledger 9, and versions earlier than 4.4.101 don't report DUST capacity correctly after the upgrade. Run the indexer version in the Mainnet matrix, and re-index its database from genesis.
Contract action subscription without an offset, against indexer 4.4.101The subscription delivers only new actions. It no longer replays the contract's history. Pass an explicit offset, such as height 0, to replay history. Midnight.js 5.0.0 does this. Midnight.js 4.x doesn't, so it receives no history.
Proof server 8.x with Mainnet, Preview, or PreprodUse the proof server version in the Mainnet matrix.
Midnight.js 5.0.0, or @midnightntwrk/ledger-v9 earlier than 1.0.2, with Mainnet, Preview, or PreprodTwo kinds of contract call are rejected. A call that spends a shielded coin the contract already holds and writes the change back fails with Custom error: 104 (ran out of gas budget). A call whose fee is paid with exactly one DUST spend can fail with OutsideTimeToDismiss. A contract's state can also fail to load after a map write. Midnight.js 5.0.1, with ledger-v9 1.0.2, fixes all three.
Wallet SDK 2.0.0A transfer that needs more proofs than the proof server queues by default is refused, and the in-process prover can't prove circuits compiled with Compact toolchain 0.36. Wallet SDK 2.0.1 fixes both.
Compact toolchain 0.36.0, or proof server 9.0.0 or 9.0.1, with some circuits that use Jubjub typesKey generation or proving crashes. Compact toolchain 0.36.1 and proof server 9.0.2 fix it. Toolchain 0.36.1 also fixes an internal compiler error on some circuits that use deserialized Boolean values.
Contracts deployed before the upgrade, compiled with Compact toolchain 0.30.0Midnight.js 5 refuses these artifacts with EraMismatchError. It accepts artifacts for Compact runtime 0.16 (toolchain 0.31.x) and 0.21 (toolchain 0.36.x) only. Move the contract to toolchain 0.36.1 through its maintenance authority, or redeploy it. See the ledger 9 upgrade page.
New contracts compiled with Compact toolchain 0.31.1, deployed to Mainnet or Preprod after the upgrade, or to PreviewMidnight.js 5 refuses a new deployment, or a maintenance update, that uses a ledger 8 artifact. Compile new contracts with the toolchain in the Mainnet matrix.

Contracts deployed before the upgrade and compiled with Compact toolchain 0.31.1 keep working without a recompile. Configure the ZK config provider with verify: 'require-if-present', because toolchain 0.31.1 doesn't emit a contract-manifest.json file. Moving the contract to the current toolchain changes its verifier keys. Before the 1.1 patch, a call that spent a shielded coin the contract already held and wrote the change back failed with Custom error: 104 (midnight-ledger#839). Midnight.js 5.0.1 fixes it on the client side, without a recompile. Calling a contract deployed before the upgrade, and deploying a contract compiled with Compact toolchain 0.36.0, are part of the tested upgrade rehearsal.