Skip to main content

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 NetworkId provided when building the wallet.


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):

NameData typeRequired?Default
Indexer URLStringYesN/A
Indexer WebSocket URLStringYesN/A
Proving server URLStringYesN/A
Node URLStringYesN/A
Network IDNetworkIdYesN/A
Log levelLogLevelNowarn
Discard Transaction HistoryBooleanNofalse
import { WalletBuilder } from '@midnight-ntwrk/wallet';
import { NetworkId } from '@midnight-ntwrk/zswap';

const wallet = await WalletBuilder.build(
'https://indexer.testnet.midnight.network/api/v1/graphql', // Indexer URL
'wss://indexer.testnet.midnight.network/api/v1/graphql', // Indexer WebSocket URL
'http://localhost:6300', // Proving Server URL
'https://rpc.testnet.midnight.network', // Node URL
NetworkId.TestNet, // Network ID
'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:

NameData typeRequired?
transactionTransactionYes
newCoinsCoinInfo[]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 TestNet, 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:

NameData typeRequired?
provingRecipeProvingRecipeYes

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:

NameData typeRequired?
transactionTransactionYes

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:

NameData typeRequired?
amountBigIntYes
tokenTypeTokenTypeYes
receiverAddressAddressYes

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

import { nativeToken } from '@midnight-ntwrk/zswap';

const transactionToProve = await wallet.transferTransaction([
{
amount: 1n,
receiverAddress: '<midnight-wallet-address>',
tokenType: nativeToken() // 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):

NameData typeRequired?
Indexer URLStringYes
Indexer WebSocket URLStringYes
Proving server URLStringYes
Node URLStringYes
Serialized stateStringYes
Log levelLogLevelNo
Discard Transaction HistoryBooleanNo

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

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

const wallet = await WalletBuilder.restore(
'https://indexer.testnet.midnight.network/api/v1/graphql', // Indexer URL
'wss://indexer.testnet.midnight.network/api/v1/graphql', // Indexer WebSocket URL
'http://localhost:6300', // Proving Server URL
'https://rpc.testnet.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.

Note that this builder method doesn't provide a network ID parameter, because it is stored in the serialized snapshot.

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):

NameData typeRequired?
Indexer URLStringYes
Indexer WebSocket URLStringYes
Proving server URLStringYes
Node URLStringYes
SeedStringYes
Network IDNetworkIdYes
Log levelLogLevelNo
Discard Transaction HistoryBooleanNo
import { WalletBuilder } from '@midnight-ntwrk/wallet';
import { NetworkId } from '@midnight-ntwrk/zswap';

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

Closing an instance

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

await wallet.close();

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';
import { NetworkId, nativeToken } from '@midnight-ntwrk/zswap';

try {
const wallet = await WalletBuilder.build(
'https://indexer.testnet.midnight.network/api/v1/graphql',
'wss://indexer.testnet.midnight.network/api/v1/graphql',
'http://localhost:6300',
'https://rpc.testnet.midnight.network',
NetworkId.TestNet
);

const transactionToProve = await wallet.transferTransaction([
{
amount: 1n,
tokenType: nativeToken(), // 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);
}