Skip to main content

Midnight.js

Midnight.js is a client library designed to facilitate the development of decentralized applications on the Midnight blockchain.

Link to related documentation

2 April 2025

Midnight.js 1.0.0 Release Notes​

Learn about the latest updates and improvements to the Midnight.js, including new features, bug fixes, and breaking changes designed to enhance functionality and stability.

Key Changes & Highlights​

  • Milestone Release – This release ensures we follow semantic versioning going forward.
  • Wallet 4.0.0 Support – Bech32m is now the default address format. midnight-js@1.0.0 supports both Wallet 4.0.0 and older versions.
  • midnight-js-testing – The test framework is now public. See known issues for details.
  • midnight-js-logger-provider – Developers can define custom logging strategies. See known issues for details.
  • Validated with Node.js 22 LTS – Fully compatible with the latest long-term support release.
  • Security – Package dependencies have been updated to mitigate known vulnerabilities.

Changelog​

Fixed​

  • createCircuitCallTxInterface – No private state found at private state key 'undefined'.
  • Top-level await in @midnight-ntwrk/zswap throws an error.
  • Update midnight-js to use Node.js 22.
  • [midnight-js] LevelDB – lock midnight-level-db/LOCK: Resource temporarily unavailable.
  • [midnight-js] watchForContractState is non-blocking.
  • [midnight-js] socket hang up on consecutive calls to proof-server.
  • Fix vulnerabilities reported by Checkmarx/Renovate.
  • Indexer client uses WebSocket over TLS.
  • [midnight-js-contracts] Calling submit() twice on unsubmittedCallTx throws 'null pointer passed to rust'.

Changed​

  • Update Midnight.js to support the new wallet key structure and address format.
  • deployContract does not accept a contract with a null state.
  • Provide global access to currently set network ID.
  • Refactor: Extract common hexadecimal utilities to a new midnight-js-utils package.

Added​

  • http-client-proof-provider implements a retry/backoff strategy.
  • deployContract and findDeployContract type inference.
  • Value cannot be null or undefined error when null is used as the witness state type.
  • contracts and private-state-provider support contracts without a private state.
  • Retry limits added to watchFor queries.
  • Enhanced error handling in http-proof-provider client connections.
  • Developer-defined logging support in Midnight.js.
  • Implement the PrivateStateProvider interface supporting composable contracts.
  • Interface design for PrivateStateProvider supporting composable contracts.

Breaking Changes​

  1. PrivateStateProvider Supports Multiple Private States

    The PrivateStateProvider interface now supports multiple contract private states.

    interface PrivateStateProvider<PSI extends PrivateStateId = string, PS = any>

    A typed key-value store interface for handling multiple contract private states.

    PSI: The private state ID (can be a union of string literals).

    PS: The private state type (can be a union of private state types).

  2. privateStateKey renamed to privateStateId

    privateStateKey parameter has been renamed privateStateId to be consistent with the new PrivateStateProvider interface. This impacts numerous functions, interfaces, and in the contracts library.

    type PrivateStateId = string

    A type representing an ID used to store a contract's private state.

    For example:

    const getStates: <PS>(publicDataProvider: PublicDataProvider, privateStateProvider: PrivateStateProvider<PrivateStateId, PS>, contractAddress: ContractAddress, privateStateId: PrivateStateId) => Promise<ContractStates<PS>>

    Retrieves the Zswap, ledger, and private states of the contract corresponding to the given identifier using the given providers.

    @param publicDataProvider

    The provider to use to fetch the public states (Zswap and ledger) from the blockchain.

    @param privateStateProvider — The provider to use to fetch the private state.

    @param contractAddress — The ledger address of the contract.

    @param privateStateId — The identifier for the private state of the contract.

Known Issues​

  • midnight-js-logger-provider – The new logger provider is not yet integrated into the contracts library.

  • midnight-js-testing – The test framework is complex and further guidance will be provided.
    Documentation is available here (Note: this link is currently not publicly accessible and requires a connected GitHub account).

Upgrade/Installation/Migration Instructions​

Package version changes are as follows:

"resolutions": {
    "@midnight-ntwrk/compact-runtime/@midnight-ntwrk/onchain-runtime": "^0.2.6",
    "@midnight-ntwrk/zswap": "^3.0.6"
  },
  "dependencies": {
    "@midnight-ntwrk/compact-runtime": "^0.7.0",
    "@midnight-ntwrk/dapp-connector-api": "2.0.0",
    "@midnight-ntwrk/ledger": "^3.0.6",
    "@midnight-ntwrk/midnight-js-contracts": "1.0.0",
    "@midnight-ntwrk/midnight-js-fetch-zk-config-provider": "1.0.0",
    "@midnight-ntwrk/midnight-js-http-client-proof-provider": "1.0.0",
    "@midnight-ntwrk/midnight-js-indexer-public-data-provider": "1.0.0",
    "@midnight-ntwrk/midnight-js-level-private-state-provider": "1.0.0",
    "@midnight-ntwrk/midnight-js-network-id": "1.0.0",
    "@midnight-ntwrk/midnight-js-node-zk-config-provider": "1.0.0",
    "@midnight-ntwrk/midnight-js-types": "1.0.0",
    "@midnight-ntwrk/midnight-js-utils": "1.0.0",
    "@midnight-ntwrk/wallet": "4.0.0",
    "@midnight-ntwrk/wallet-api": "4.0.0",
    "@midnight-ntwrk/wallet-sdk-address-format": "1.0.0",
    "fp-ts": "^2.16.1",
    "io-ts": "^2.2.20",
    "pino": "^8.16.0",
    "pino-pretty": "^10.2.3",
    "rxjs": "^7.8.1"
  },

Typical code change:

Midnight JS Code Change

Compatibility​

  • Operating Systems: No OS-specific compatibility issues identified.

  • Third-Party Tools: Requires Node.js v18 or higher.

  • Midnight Ecosystem Compatibility:
    Midnight.js and associated tests must be updated to support the new APIs.
    Wallet consumers will need to accommodate the breaking changes introduced in this release.

  • Updated @midnight-ntwrk/compact-runtime/@midnight-ntwrk/onchain-runtime from ^0.2.2 to ^0.2.4 in resolutions.

  • Updated @midnight-ntwrk/zswap from ^3.0.2 to ^3.0.6 in resolutions.

  • Updated @midnight-ntwrk/dapp-connector-api from ^1.2.2 to ^1.2.3 in dependencies.

  • Updated @midnight-ntwrk/ledger from ^3.0.2 to ^3.0.6 in dependencies.

  • Updated @midnight-ntwrk/wallet from ^3.7.3 to ^3.7.5 in dependencies.