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
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);
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/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();
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);
});
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 |
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);
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);
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);
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
}
]);
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();
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/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.
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/api/v1/graphql', // Indexer WebSocket URL
'http://localhost:6300', // Proving Server URL
'https://rpc.devnet.midnight.network', // Node URL
'0000000000000000000000000000000000000000000000000000000000000000', // Seed
'error' // LogLevel
);
To gracefully close a wallet instance, use the close()
method:
await wallet.close();
In this section, you'll find examples of how you can fully utilize the wallet APIs.
This example instantiates a new wallet and uses it to transfer one tDUST to another wallet:
import { WalletBuilder } from '@midnight-ntwrk/wallet';
import { setNetworkId, NetworkId } from '@midnight-ntwrk/zswap';
try {
// set network id to devnet
setNetworkId(NetworkId.DevNet);
const wallet = await WalletBuilder.build(
'https://indexer.devnet.midnight.network/api/v1/graphql',
'wss://indexer.devnet.midnight.network/api/v1/graphql',
'http://localhost:6300',
'https://rpc.devnet.midnight.network',
);
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);
}