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):
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 |
Network ID | NetworkId | Yes | N/A |
Log level | LogLevel | No | warn |
Discard Transaction History | Boolean | No | false |
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:
Name | Data type | Required? |
---|---|---|
transaction | Transaction | Yes |
newCoins | CoinInfo[] | 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 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:
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:
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):
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 |
Discard Transaction History | Boolean | 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.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):
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 |
Network ID | NetworkId | Yes |
Log level | LogLevel | No |
Discard Transaction History | Boolean | No |
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);
}