Deploying and calling Midnight contracts

A Midnight contract call is a zero-knowledge proof, not a signed transaction. So an embedded wallet cannot simply “sign the contract call” — the work splits in two:

Half	Who does it	What it covers
Contract	Your app, via `midnight-js`	Circuit execution, witness handling, ZK proof, private state
Settlement	The Dynamic wallet	Adding coin inputs so the transaction balances, paying DUST, signing, submitting

primaryWallet.getWalletProvider() returns the settlement half as a midnight-js–compatible provider. Balancing and MPC signing happen inside the wallet iframe, so shielded, DUST and MPC key material never leaves it — only public keys and serialized transactions cross the boundary.

This is for embedded Midnight wallets. Injected wallets (1am) expose their own provider surface — see Using Midnight wallets.

What the wallet gives you

React

// Parameterise with the transaction types from your own installed midnight-js
// and ledger versions, and the result is assignable to `MidnightProviders`
// with no cast. The connector deliberately declares these structurally, so it
// pins no midnight-js version on your app.
const walletProvider = await primaryWallet.getWalletProvider<
  UnboundTransaction,
  FinalizedTransaction
>();

walletProvider.getCoinPublicKey();       // shielded coin public key
walletProvider.getEncryptionPublicKey(); // shielded encryption public key
walletProvider.balanceTx(tx, ttl);       // balance + pay DUST + sign, in the iframe
walletProvider.submitTx(tx);             // broadcast

That satisfies both walletProvider and midnightProvider in MidnightProviders. The remaining four are yours.

Provider	Supplied by	Notes
`walletProvider`	Dynamic	`getWalletProvider()`
`midnightProvider`	Dynamic	the same object
`privateStateProvider`	you	your contract’s witnesses
`publicDataProvider`	you	indexer; required to read contract state
`zkConfigProvider`	you	your compiled ZK artefacts
`proofProvider`	you	a Midnight proof server

Prerequisites

Fund the wallet and register DUST

Contract calls cost DUST. Fund the wallet with unshielded NIGHT, call registerDust(), then wait for a non-zero DUST balance — see Registering for DUST.

Compile your contract

compact compile produces the ZK artefacts your zkConfigProvider serves: zkir/<circuit>.bzkir, keys/<circuit>.prover, keys/<circuit>.verifier. These are deterministic, public build outputs — not secrets.

Prover keys are large: expect single-digit to tens of megabytes per circuit. They are uploaded to the proof server on every proof, so keep them served from somewhere fast.

Point at a proof server

Your proofProvider needs a Midnight proof server for your circuits. The wallet proves its own shielded and DUST work separately, inside the iframe.

Deploying and calling

React

import { CompiledContract } from '@midnight-ntwrk/compact-js';
import { FetchZkConfigProvider } from '@midnight-ntwrk/midnight-js-fetch-zk-config-provider';
import { httpClientProofProvider } from '@midnight-ntwrk/midnight-js-http-client-proof-provider';
import { indexerPublicDataProvider } from '@midnight-ntwrk/midnight-js-indexer-public-data-provider';
import { levelPrivateStateProvider } from '@midnight-ntwrk/midnight-js-level-private-state-provider';
import {
  deployContract,
  findDeployedContract,
} from '@midnight-ntwrk/midnight-js/contracts';
import { setNetworkId } from '@midnight-ntwrk/midnight-js/network-id';

import { Contract } from './my-contract/index.js'; // compact compile output

const PRIVATE_STATE_ID = 'my-contract-state';

setNetworkId('preview');

// Absolute URL: FetchZkConfigProvider runs `new URL(...)` on this and rejects
// anything without an http/https scheme.
const zkArtifactBaseUrl = `${window.location.origin}/my-contract`;

const compiledContract = CompiledContract.make('my-contract', Contract)
  .withWitnesses({
    // your witness implementations
  })
  .withCompiledFileAssets(zkArtifactBaseUrl);

const walletProvider = await primaryWallet.getWalletProvider();
const accountId = walletProvider.getCoinPublicKey();

const zkConfigProvider = new FetchZkConfigProvider(
  zkArtifactBaseUrl,
  // Pass the browser's fetch explicitly — the default is `cross-fetch`, which
  // a bundler may resolve to its Node build and fail with an opaque
  // ZKConfigurationReadError. See the notes below for the content-type guard.
  window.fetch.bind(window),
);

const providers = {
  privateStateProvider: levelPrivateStateProvider({
    accountId,
    privateStateStoreName: PRIVATE_STATE_ID,
  }),
  publicDataProvider: indexerPublicDataProvider(indexerHttpUrl, indexerWsUrl),
  zkConfigProvider,
  proofProvider: httpClientProofProvider(proofServerUrl, zkConfigProvider),
  walletProvider,
  midnightProvider: walletProvider,
};

// Deploy
const deployed = await deployContract(providers, {
  compiledContract,
  privateStateId: PRIVATE_STATE_ID,
  initialPrivateState: { /* your witnesses' backing state */ },
});
const { contractAddress } = deployed.deployTxData.public;

// Call a circuit on an already-deployed instance
const found = await findDeployedContract(providers, {
  compiledContract,
  contractAddress,
  privateStateId: PRIVATE_STATE_ID,
});
await found.callTx.myCircuit(...args);

Both calls go through balanceTx and submitTx on the wallet provider, so the user’s shielded coins and DUST pay for the transaction and the unshielded segment is MPC-signed — without your app ever holding key material.

Things that will catch you out

These are not obvious from the midnight-js types, and each one fails in a way that points somewhere unhelpful.

Your zkConfigProvider must fail for built-in circuits

A circuit that creates a shielded coin needs prover keys for Midnight’s own midnight/zswap/output, input and spend circuits. Those are not in your compiled artefacts — the proof server has them.The preimage marks proving data as optional, so your provider should throw for circuit ids it does not own. midnight-js then omits proving data and the server uses its own keys. If your provider returns something for those ids instead, it ends up in the preimage and the proof server rejects the request with a bare 400.

Validate the content type of artefact responses

createProverKey does not inspect what you hand it. A dev server’s single-page-app fallback answers unknown paths with 200 and index.html, so a wrong artefact path becomes HTML embedded in your proof preimage — and the only symptom is a bare 400 from the proof server.Reject HTML in the custom fetch and a bad path becomes an obvious error:

const guardedFetch = async (input, init) => {
  const response = await window.fetch(input, init);
  const contentType = response.headers.get('content-type') ?? '';
  if (response.ok && contentType.includes('text/html')) {
    throw new Error(`ZK artefact request returned HTML: ${String(input)}`);
  }
  return response;
};

Throwing here is also what makes the built-in zswap circuits work, since those requests 404 into the same fallback.

Deploy needs no proof; circuit calls do

Deploying publishes state and verifier keys — there is no circuit execution to prove, so a deploy can succeed with no proof server reachable. The first callTx is where proofProvider is actually used, which is why a misconfigured proof server often looks like “deploy worked, calls broke”.

The first call is slow

getWalletProvider() initialises the wallet inside the iframe, which includes a full sync on a cold cache. Expect well over a minute on first use, with no intermediate progress. Later calls reuse the synced wallet.

Private state is yours to keep

Witnesses live in your app’s private state, never in the wallet. If they are lost, gated circuits on that contract can no longer be called by anyone — the wallet cannot help recover them, because it never held them. Persist anything you cannot regenerate.

Newly minted shielded coins take time to appear

A shielded coin exists on chain as soon as the transaction is included, but the wallet has to sync the Zswap tree before it shows in balances. A zero balance straight after a successful mint usually means sync, not failure.

Confirming a transaction landed

submitTx returns the submission identifier, which is what inclusion is polled by. It is a different value from the canonical transaction hash that block explorers index — querying an indexer by the wrong one returns an empty result rather than an error, which reads like a failed transaction.

query ($id: HexEncoded!) {
  transactions(offset: { identifier: $id }) {
    hash
    block { height }
    ... on RegularTransaction {
      transactionResult { status }
      contractActions { __typename address }
    }
  }
}

contractActions returns ContractDeploy or ContractCall with the contract address — the simplest way to confirm a deploy and recover its address.

Implementation Guides

SDK Reference

Deploying and calling Midnight contracts

What the wallet gives you

Prerequisites

Deploying and calling

Things that will catch you out

Confirming a transaction landed

Resources

​What the wallet gives you

​Prerequisites

​Deploying and calling

​Things that will catch you out

​Confirming a transaction landed

​Resources

What the wallet gives you

Prerequisites

Deploying and calling

Things that will catch you out

Confirming a transaction landed

Resources