DEV Community

Cover image for Handling Midnight SDK Breaking Changes: A Developer's Upgrade Playbook
Harrie
Harrie

Posted on

Handling Midnight SDK Breaking Changes: A Developer's Upgrade Playbook

#blockchain #midnightfordevs #tutorial

You run npm update on a Friday afternoon. Tests were passing that morning. Now your terminal looks like this:

CompactError: Version mismatch
  Expected circuit artifact version: 4.1.0
  Found: 3.8.2
  Contract: ./managed/counter/contract/index.cjs
Enter fullscreen mode Exit fullscreen mode

Nothing is actually wrong with your .compact source files. You just have stale compiled artifacts sitting in managed/ from before the upgrade, and the runtime now refuses to load them.

Breaking changes on Midnight split into two categories: TypeScript API renames and Compact compiler artifact incompatibility. Once you know which you're dealing with, the fix is usually fast.

What changed in the v3.x to v4.x migration

Package consolidation

The biggest structural change was flattening six individual packages into one barrel export. If you haven't done this migration yet, your package.json probably looks like this:

{
  "dependencies": {
    "@midnight-ntwrk/wallet": "^3.2.0",
    "@midnight-ntwrk/wallet-api": "^3.2.0",
    "@midnight-ntwrk/zswap": "^3.2.0",
    "@midnight-ntwrk/midnight-js-network-id": "^3.2.0",
    "@midnight-ntwrk/midnight-js-types": "^3.2.0",
    "@midnight-ntwrk/midnight-js-contracts": "^3.2.0"
  }
}
Enter fullscreen mode Exit fullscreen mode

After v4.0.3, one package replaces all of them:

{
  "dependencies": {
    "@midnight-ntwrk/midnight-js": "^4.0.3"
  }
}
Enter fullscreen mode Exit fullscreen mode

Your imports change accordingly:

// Before
import { WalletProvider } from '@midnight-ntwrk/wallet';
import { NetworkId } from '@midnight-ntwrk/midnight-js-network-id';
import { ContractAddress } from '@midnight-ntwrk/midnight-js-types';

// After
import { WalletProvider, NetworkId, ContractAddress } from '@midnight-ntwrk/midnight-js';
Enter fullscreen mode Exit fullscreen mode

API renames

Three function-level changes trip people up most.

Wallet initialization renamed one provider option:

// Before
const wallet = await Wallet.initialize({
  walletProvider: storageProvider,
  networkId: NetworkId.TestNet
});

// After
const wallet = await Wallet.initialize({
  privateStoragePasswordProvider: storageProvider,
  networkId: NetworkId.TestNet
});
Enter fullscreen mode Exit fullscreen mode

TypeScript catches walletProvider immediately with "Object literal may only specify known properties." One of the easier breaks to find.

Transaction signing merged two calls into one:

// Before
const balanced = await balanceTx(tx, walletProvider);
const signed = await signTx(balanced, walletProvider);
await submitTx(signed);

// After
const signed = await balanceAndSign(tx, walletProvider);
await submitTx(signed);
Enter fullscreen mode Exit fullscreen mode

Grep for balanceTx to find every instance. It tends to show up in more places than expected.

The CLI command changed from compact compile to compactc. CI pipelines and build scripts using the old command will either fail silently or error out, depending on how your shell handles missing executables.

Pragma version

Compact contracts now require an explicit version pragma at the top of every .compact file:

pragma language_version >= 0.20;
Enter fullscreen mode Exit fullscreen mode

Contracts without this line fail at compile time with CompactError: Language version not specified. Add it as the first non-comment line.

Diagnosing CompactError: Version mismatch

When you compile a .compact file, the Compact compiler generates circuit artifacts: .cjs JavaScript wrappers and .wasm zero-knowledge circuit binaries. These files contain an embedded version tag. When the SDK runtime (now v4.x) finds artifacts tagged for v3.x, it refuses to load them.

Upgrading the SDK packages doesn't touch your compiled artifacts. They stay in managed/ exactly as they were. The runtime just stops accepting them.

To confirm which contracts are affected:

# List all contract artifact directories
ls managed/

# Check the version inside one
cat managed/counter/contract/package.json | grep version
Enter fullscreen mode Exit fullscreen mode

In practice, if you upgraded the SDK, assume all contracts are affected and recompile everything. Checking individually isn't worth the time.

Fixing the version mismatch

Three steps, in order.

Delete the stale artifacts first:

rm -rf managed/*/contract/
Enter fullscreen mode Exit fullscreen mode

Then recompile:

# Single contract
compactc src/contracts/counter.compact managed/counter/contract

# All contracts at once
for contract in src/contracts/*.compact; do
  name=$(basename "$contract" .compact)
  mkdir -p "managed/$name/contract"
  compactc "$contract" "managed/$name/contract"
done
Enter fullscreen mode Exit fullscreen mode

Verify the artifacts exist:

ls managed/counter/contract/
# index.cjs  index.d.cts  zkir.wasm  ...
Enter fullscreen mode Exit fullscreen mode

If you see those files, the compile worked.

The dependency audit workflow

The order matters more than most people expect.

  1. Audit before touching anything: 
# What's currently installed
npm list | grep midnight

# What updates are available
npm outdated | grep midnight
Enter fullscreen mode Exit fullscreen mode

Read the changelog before proceeding. Sometimes what looks like a routine upgrade removes a feature you're using.

  1. Update package.json. Replace old package names with the new barrel package. Remove old packages completely from both dependencies and devDependencies. Don't run install yet.

  2. Delete node_modules:

rm -rf node_modules
Enter fullscreen mode Exit fullscreen mode

npm sometimes partially updates packages and leaves old peer dependency resolutions cached. A clean install avoids half-upgraded states where you're running v4 types against v3 implementations.

  1. Delete compiled artifacts: 
rm -rf managed/*/contract/
Enter fullscreen mode Exit fullscreen mode

Do this before reinstalling. If you install first and forget to delete artifacts, you'll think the upgrade worked until the first test run.

  1. Install: 
npm install
Enter fullscreen mode Exit fullscreen mode
  1. Recompile contracts: 
for contract in src/contracts/*.compact; do
  name=$(basename "$contract" .compact)
  compactc "$contract" "managed/$name/contract"
done
Enter fullscreen mode Exit fullscreen mode
  1. Run your test suite. TypeScript type errors from renamed imports surface here. Fix them as they come up.

The verified contract

The companion repository for this guide contains a minimal versioned feature-flag registry compiled against pragma language_version >= 0.20. CI passes on the latest Compact toolchain.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger owner: Bytes<32>;
export ledger contractVersion: Bytes<32>;
export ledger upgradeCount: Counter;
export ledger featureFlags: Map<Bytes<32>, Boolean>;

witness getOwnerSecret(): Bytes<32>;

circuit ownerKey(): Bytes<32> {
    return persistentHash<Vector<2, Bytes<32>>>([
        pad(32, "registry:owner:v1"),
        getOwnerSecret()
    ]);
}

circuit requireOwner(): [] {
    assert(disclose(ownerKey()) == owner, "Owner only");
}

export circuit initialize(ownerPubkey: Bytes<32>): [] {
    owner = disclose(ownerPubkey);
}

export circuit setVersion(newVersion: Bytes<32>): [] {
    requireOwner();
    contractVersion = disclose(newVersion);
    upgradeCount.increment(1);
}

export circuit enableFlag(flagKey: Bytes<32>): [] {
    requireOwner();
    featureFlags.insert(disclose(flagKey), disclose(true));
}

export circuit disableFlag(flagKey: Bytes<32>): [] {
    requireOwner();
    featureFlags.insert(disclose(flagKey), disclose(false));
}

export circuit isFlagEnabled(flagKey: Bytes<32>): Boolean {
    if (!featureFlags.member(disclose(flagKey))) {
        return false;
    }
    return featureFlags.lookup(disclose(flagKey));
}
Enter fullscreen mode Exit fullscreen mode

Five exported circuits, well under Lace's 13-circuit deployment limit. The non-exported helpers (ownerKey, requireOwner) don't count toward the limit. Only export circuit declarations do.

The feature-flag pattern is genuinely useful post-upgrade. You can gate new features behind flags and enable them on-chain once you've confirmed the upgraded contracts are stable in production.

Common pitfalls

Upgrading packages without deleting artifacts. The most common way to hit CompactError: Version mismatch. Packages update, old .wasm files stay. Delete and recompile after every SDK version change.

Partial barrel migration. Updating package.json to use @midnight-ntwrk/midnight-js but leaving old import paths in TypeScript files. This only works as long as the old packages are still in dependencies. Remove them completely and run npm list | grep @midnight-ntwrk after installing to confirm nothing old is lingering.

Missing pragma. Contracts compiled under older Compact versions don't have pragma language_version >= 0.20; at the top. The compiler error is clear, but unexpected if you haven't seen it before. Add the pragma to every .compact file as part of the upgrade.

compactc not in PATH. The toolchain manager (compact) downloads the actual compiler binary. After updating the manager, run compact update to pull the new compiler. If compactc is still missing afterward, check that ~/.compact/bin is in your PATH.

Reserved keywords as parameter names. from and to are reserved keywords in Compact and can't be used as circuit parameter names. If you're refactoring transfer circuits during an upgrade, rename from to sender and to to receiver. The error looks like this:

parse error: found keyword "from" looking for a typed pattern or ")"
Enter fullscreen mode Exit fullscreen mode

This one doesn't come from the SDK change itself, but tends to surface when people are reworking circuits during an upgrade.

Stale type definitions from mixed packages. If you add @midnight-ntwrk/midnight-js without removing the individual packages, TypeScript picks up conflicting type definitions. The build might succeed, but you'll have subtle mismatches at runtime. Remove old packages completely.

That's the playbook

Breaking SDK changes feel arbitrary until you've seen the pattern twice. The package consolidation is a one-time migration. CompactError: Version mismatch always means the same thing: delete artifacts and recompile. The API renames are search-and-replace.

The workflow: audit dependencies first, update package.json, delete node_modules and artifacts, clean install, recompile, fix imports. Same order every time. Skipping step 3 or 4 is how you spend four hours debugging a two-minute fix.

Top comments (0)