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.
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 area | Component | Version | Notes |
|---|---|---|---|
| Network | Node (Midnight) | 2.1.101 | Preview network node (ledger 9) |
| Runtime and contracts | Compact devtools (compact) | 0.5.1 | Installs compilers, compiles contracts |
Compact toolchain (compact compile) | 0.36.1 | Contract compiler for ledger 9. Language version 0.28.0 | |
| Compact runtime | 0.21.0 | Runtime library for contracts. npm: @midnight-ntwrk/compact-runtime | |
| Compact JS | 3.0.2 | TypeScript execution environment for compiled contracts. npm: @midnight-ntwrk/compact-js | |
| Platform JS | 3.0.0 | Core abstractions and types. npm: @midnight-ntwrk/platform-js | |
| On-chain runtime | 4.0.2 | On-chain runtime support (v4). npm: @midnightntwrk/onchain-runtime-v4 | |
| SDKs and APIs | Wallet SDK | 2.0.1 | SDK for building wallet integrations. npm: @midnightntwrk/wallet-sdk |
| Midnight.js | 5.0.1 | DApp framework: contracts, types, providers. npm: @midnight-ntwrk/midnight-js | |
| testkit-js | 5.0.1 | E2E testing framework. npm: @midnight-ntwrk/testkit-js | |
| DApp Connector API | 4.1.0 | Interface between DApps and wallets. npm: @midnightntwrk/dapp-connector-api | |
| Indexing and data | Midnight Indexer | 4.4.101 | Preview indexer (ledger 9) |
| ZK and proving services | Proof server | 9.0.2 | Handles 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 area | Component | Version | Notes |
|---|---|---|---|
| Network | Node (Midnight) | 2.1.101 | Preprod network node (ledger 9) |
| Runtime and contracts | Compact devtools (compact) | 0.5.1 | Installs compilers, compiles contracts |
Compact toolchain (compact compile) | 0.36.1 | Contract compiler for ledger 9. Language version 0.28.0 | |
| Compact runtime | 0.21.0 | Runtime library for contracts. npm: @midnight-ntwrk/compact-runtime | |
| Compact JS | 3.0.2 | TypeScript execution environment for compiled contracts. npm: @midnight-ntwrk/compact-js | |
| Platform JS | 3.0.0 | Core abstractions and types. npm: @midnight-ntwrk/platform-js | |
| On-chain runtime | 4.0.2 | On-chain runtime support (v4). npm: @midnightntwrk/onchain-runtime-v4 | |
| SDKs and APIs | Wallet SDK | 2.0.1 | SDK for building wallet integrations. npm: @midnightntwrk/wallet-sdk. Wallet SDK 1.x can't transact on Preprod after the upgrade |
| Midnight.js | 5.0.1 | DApp framework: contracts, types, providers. npm: @midnight-ntwrk/midnight-js | |
| testkit-js | 5.0.1 | E2E testing framework. npm: @midnight-ntwrk/testkit-js | |
| DApp Connector API | 4.1.0 | Interface between DApps and wallets. npm: @midnightntwrk/dapp-connector-api | |
| Indexing and data | Midnight Indexer | 4.4.101 | Preprod indexer (ledger 9). Blockfrost serves the Preprod indexer |
| ZK and proving services | Proof server | 9.0.2 | Handles 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 area | Component | Version | Notes |
|---|---|---|---|
| Network | Node (Midnight) | 2.1.101 | Mainnet 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 contracts | Compact devtools (compact) | 0.5.1 | Installs compilers, compiles contracts |
Compact toolchain (compact compile) | 0.36.1 | Contract compiler for ledger 9. Language version 0.28.0 | |
| Compact runtime | 0.21.0 | Runtime library for contracts. npm: @midnight-ntwrk/compact-runtime | |
| Compact JS | 3.0.2 | TypeScript execution environment for compiled contracts. npm: @midnight-ntwrk/compact-js | |
| Platform JS | 3.0.0 | Core abstractions and types. npm: @midnight-ntwrk/platform-js | |
| On-chain runtime | 4.0.2 | On-chain runtime support (v4). npm: @midnightntwrk/onchain-runtime-v4 | |
| SDKs and APIs | Wallet SDK | 2.0.1 | SDK for building wallet integrations. npm: @midnightntwrk/wallet-sdk. Wallet SDK 1.x can't transact on Mainnet after the upgrade |
| Midnight.js | 5.0.1 | DApp framework: contracts, types, providers. npm: @midnight-ntwrk/midnight-js | |
| testkit-js | 5.0.1 | E2E testing framework. npm: @midnight-ntwrk/testkit-js | |
| DApp Connector API | 4.1.0 | Interface between DApps and wallets. npm: @midnightntwrk/dapp-connector-api | |
| Indexing and data | Midnight Indexer | 4.4.101 | Mainnet indexer. Operators must re-index from genesis |
| ZK and proving services | Proof server | 9.0.2 | Handles 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.
| Combination | Result |
|---|---|
| Transactions built for ledger 8, submitted to Mainnet, Preview, or Preprod | The 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 Preprod | A 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 directory | The 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 Preprod | Wallets 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 Preprod | Midnight.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.1 | Midnight.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.0 | Importing 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.0 | Importing 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 8 | Midnight.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 ledger | Wallet SDK 2 refuses the transaction with ProtocolVersionMismatchError. |
| Indexer versions earlier than 4.4.101 with Mainnet or Preprod | The 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.101 | The 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 Preprod | Use 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 Preprod | Two 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.0 | A 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 types | Key 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.0 | Midnight.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 Preview | Midnight.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.