Midnight wallet - developer guide

Installing

The Midnight wallet is provided as an NPM package under the namespace @midnight-ntwrk/wallet. You can install it using any node package manager, including Yarn. To install the package using Yarn, run the following command:

yarn add @midnight-ntwrk/wallet

Important information

The wallet uses the @midnight-ntwrk/zswap library to manage its local state and construct transactions. The serialization formatting, which ensures transactions are processed correctly depending on the network (eg, testnet or mainnet) they belong to, relies on the network ID set in the library's context.

When setting up the wallet in any context, it's essential to configure the appropriate network ID. To do this, import the setNetworkId function from @midnight-ntwrk/zswap and call it before initializing the wallet instance.

For more information on available network IDs, please refer to the relevant section.

Below is an example of how to set the network ID for the devnet network:

import { setNetworkId, NetworkId } from '@midnight-ntwrk/zswap';

setNetworkId(NetworkId.DevNet);

Instantiating

The @midnight-ntwrk/wallet package offers a builder that enables you to create multiple wallets. Once created and started, each wallet will automatically connect to the specified node, indexer, and proving server.

To create a wallet instance, begin by importing the builder from the @midnight-ntwrk/wallet package:

import { WalletBuilder } from '@midnight-ntwrk/wallet';

Next, use the wallet builder to create a new wallet instance. This requires the following parameters (in the precise order):

Name	Data type	Required?	Default
Indexer URL	String	Yes	N/A
Indexer WebSocket URL	String	Yes	N/A
Proving server URL	String	Yes	N/A
Node URL	String	Yes	N/A
Log level	LogLevel	No	warn

import { WalletBuilder } from '@midnight-ntwrk/wallet';

const wallet = await WalletBuilder.build(
  'https://indexer.devnet.midnight.network/api/v1/graphql', // Indexer URL
  'wss://indexer.devnet.midnight.network/ws/api/v1/graphql', // Indexer WebSocket URL
  'http://localhost:6300', // Proving Server URL
  'https://rpc.devnet.midnight.network',// Node URL
  'error' // LogLevel
);

To begin synchronizing the wallet with the indexer, start the wallet variable, which holds an instance of the wallet and resource types from the wallet API, using the following method:

 wallet.start();

Getting the wallet state

The wallet state is provided through an rx.js observable. You can retrieve the state value using various methods supported by rx.js. Here's an example:

wallet.state().subscribe((state) => {
  console.log(state);
});

Balancing a transaction

To balance a transaction, you need to use the balanceTransaction method, which requires the following parameters:

Name	Data type	Required?
transaction	Transaction	Yes
newCoins	LogLevel	No

note

The newCoins parameter is intended for cases where a new coin is created, such as when a DApp mints one and intends to send it to the wallet. Due to the nature of the Midnight devnet, these newly created coins must be explicitly provided to the wallet using this method. This allows the wallet to monitor and incorporate them into its state effectively.

const balancedTransaction = await wallet.balanceTransaction(transaction);

Proving a transaction

To prove a transaction, you need to use the proveTransaction method, which requires the following parameters:

Name	Data type	Required?
provingRecipe	ProvingRecipe	Yes

This example uses the unprovenTransaction from the section above:

import { TRANSACTION_TO_PROVE } from '@midnight-ntwrk/wallet-api';

const recipe = {
  type: TRANSACTION_TO_PROVE, // available from the Wallet API
  transaction: balancedTransaction // this is a balanced, unproven transaction
};

const provenTransaction = await wallet.proveTransaction(recipe);

Submitting a transaction

To submit a transaction, you need to use the submitTransaction method, which requires the following parameters:

Name	Data type	Required?
transaction	Transaction	Yes

The transaction must be balanced and proven (in this order) for it to be accepted by the node.

The example below uses the provenTransaction from the section above:

const submittedTransaction = await wallet.submitTransaction(provenTransaction);

Transferring transaction API

The wallet API includes a transferTransaction() method that enables you to construct transactions specifying the token type, amount, and recipient address. You can then validate and submit these transactions to the node.

This method requires an array of objects containing the following properties:

Name	Data type	Required?
amount	BigInt	Yes
tokenType	TokenType	Yes
receiverAddress	Address	Yes

Below, you can see an example of how you can utilize the API:

const transactionToProve = await wallet.transferTransaction([
  {
    amount: 1n,
    receiverAddress: '<midnight-wallet-address>',
    tokenType: '0100010000000000000000000000000000000000000000000000000000000000000000' // tDUST token type
  }
]);

Serializing state

The wallet state can be serialized, allowing it to be stored and later re-instantiated from that serialized checkpoint.

To serialize the state, use the serialize() method as follows:

const serializedState = await wallet.serializeState();

Instantiating from the serialized state

The wallet builder offers a method to create a wallet instance from the serialized state (learn more about the serialized state here). This method requires the following parameters (in the precise order):

Name	Data type	Required?
Indexer URL	String	Yes
Indexer WebSocket URL	String	Yes
Proving server URL	String	Yes
Node URL	String	Yes
Serialized state	String	Yes
Log level	LogLevel	No

The example below uses the serializedState variable from the example above:

import { WalletBuilder } from '@midnight-ntwrk/wallet';

const wallet = await WalletBuilder.restore(
  'https://indexer.devnet.midnight.network/api/v1/graphql', // Indexer URL
  'wss://indexer.devnet.midnight.network/ws/api/v1/graphql', // Indexer WebSocket URL
  'http://localhost:6300', // Proving Server URL
  'https://rpc.devnet.midnight.network',// Node URL
  serializedState,
  'error' // LogLevel
);

This will create a wallet with its state checkpoint set to the time when you called the serializeState() method. Once the wallet is started with wallet.start(), it will begin syncing and updating the state from that point onward.

This functionality is especially valuable in scenarios like browser extensions, where it's crucial to swiftly restore the wallet state for the user.

Instantiating from a seed

The wallet builder offers a method that enables you to instantiate a wallet with a specific seed, resulting in obtaining the same address and keys but with a fresh state that is then synchronized with the indexer. The method requires the following parameters (in the exact order):

Name	Data type	Required?
Indexer URL	String	Yes
Indexer WebSocket URL	String	Yes
Proving server URL	String	Yes
Node URL	String	Yes
Seed	String	Yes
Log level	LogLevel	No

import { WalletBuilder } from '@midnight-ntwrk/wallet';

const wallet = await WalletBuilder.buildFromSeed(
  'https://indexer.devnet.midnight.network/api/v1/graphql', // Indexer URL
  'wss://indexer.devnet.midnight.network/ws/api/v1/graphql', // Indexer WebSocket URL
  'http://localhost:6300', // Proving Server URL
  'https://rpc.devnet.midnight.network',// Node URL
  '0000000000000000000000000000000000000000000000000000000000000000', // Seed
  'error' // LogLevel
);

Closing an instance

To gracefully close a wallet instance, use the close() method:

await wallet.close();

Connecting to a DApp

See the DApp connector overview for more details.

Examples

In this section, you'll find examples of how you can fully utilize the wallet APIs.

Transferring tDUST

This example instantiates a new wallet and uses it to transfer one tDUST to another wallet:

import { WalletBuilder } from '@midnight-ntwrk/wallet';

try {
  const wallet = await WalletBuilder.build(
    'https://indexer.devnet.midnight.network/api/v1/graphql', // Indexer URL
    'wss://indexer.devnet.midnight.network/ws/api/v1/graphql', // Indexer WebSocket URL
    'http://localhost:6300', // Proving Server URL
    'https://rpc.devnet.midnight.network',// Node URL
  );

  const transactionToProve = await wallet.transferTransaction([
    {
      amount: 1n,
      tokenType: '0100010000000000000000000000000000000000000000000000000000000000000000', // tDUST token type
      receiverAddress: '2f646b14cbcbfc43ccdae6379891c2b01e9731d1e4c1e0c1b71c04b7948a3e0e|010001f38d17a48161d6248ee10a799dca0799eecbd8f1f20bbeb4eb2645656c104cde'
    }
  ]);

  const provenTransaction = await wallet.proveTransaction(transactionToProve);

  const submittedTransaction = await wallet.submitTransaction(provenTransaction);

  console.log('Transaction submitted', submittedTransaction);
} catch (error) {
  console.log('An error occurred', error);
}