DApp connector API
@midnight-ntwrk/dapp-connector-api v1.1.0 • Readme | API
Midnight DApp connector API
This API provides a comprehensive interface for the DApp connector operations, defining the structure of the wallet state it exposes, the methods for interacting with it, and the types and variables used within.
It's implemented by the Midnight Lace extension for Google Chrome and is injected in the global scope (window.midnight.mnLace
) of DApps running in browser.
Installation
The Midnight DApp connector API is available as an NPM package with the namespace @midnight-ntwrk/dapp-connector-api
. It can be installed using any node package manager, such as Yarn. To install the package using Yarn, execute the following command:
yarn add @midnight-ntwrk/dapp-connector-api
Package usage
The package provides the type declarations that are documented in the documentation of this package.
The DApp connector API should be exposed through the global variable as follows:
window.midnight.{walletName}
Available methods
Name | Description |
---|---|
apiVersion | Provides a semver string version of the DApp connector API |
enable | Returns a promise with the DAppConnectorWalletAPI or error |
isEnabled | Returns a promise with a boolean showing whether the DApp is authorized to access the API or not |
name | The name of the wallet that implements the API |
serviceUriConfig | Returns a promise with ServiceUriConfig or error if the DApp is not authorized. |
API usage
Below, we will use the Midnight Lace implementation of the DApp connector API. It is accessible within this namespace: window.midnight.mnLace
.
Authorizing a DApp
To authorize a DApp, call the enable()
method and wait for the user to respond to the request.
try {
const api = await window.midnight.mnLace.enable();
// api is available here
} catch (error) {
console.log('an error occurred', error);
}
Checking if the DApp is authorized
To check if the DApp is authorized, use the isEnabled()
method as follows:
try {
const isEnabled = await window.midnight.mnLace.isEnabled();
} catch (error) {
console.log('an error occurred', error);
}
Getting information about the DApp connector API
Name
To get the name of the wallet, use the name
property in the implemented DApp connector API:
const name = window.midnight.mnLace.name;
console.log('Wallet name', name);
API version
To get the API version, use the apiVersion
property as follows:
const apiVersion = window.midnight.mnLace.apiVersion;
console.log('API version', apiVersion);
Getting the service URI config
Midnight wallet users can configure the node, indexer, and proving server URIs in the wallet settings. To enable DApps to access and utilize these URLs, the following property is exposed:
Name | Description |
---|---|
Node URL | The node the wallet is pointing to |
Indexer URL | The indexer URL the wallet is pointing to |
Proving Server URL | The proving server URL the wallet is pointing to |
To get the service URI config, use the API as follows:
try {
const serviceUriConfig = await window.midnight.mnLace.serviceUriConfig();
console.log('serviceUriConfig', serviceUriConfig);
} catch (error) {
console.log('an error occurred', error);
}
Note: The DApp must be authorized before calling this method, otherwise it will throw an error.
Interacting with the API
After calling the enable()
method and the user approves the authorization request, you will receive an instance of the DAppConnectorWalletAPI, which includes the following properties:
Name | Description | Note |
---|---|---|
balanceAndProveTransaction | Balances and proves a transaction | - |
submitTransaction | Submits a balanced and proven transaction | - |
state | Returns DAppConnectorWalletState object | - |
balanceTransaction | Balances a transaction | This method is deprecated and will be removed in version 2.0.0 |
proveTransaction | Proves a transaction | This method is deprecated and will be removed in version 2.0.0 |
Getting the wallet state
To get the wallet state, call the state()
API method, which will return a promise with the DAppConnectorWalletState object as follows:
try {
const state = await api.state();
console.log('Wallet state', state);
} catch (error) {
console.log('an error occurred', error);
}
Balancing and proving a transaction
To balance and prove a transaction, begin by creating a transaction in your DApp. You can follow the guide on how to create a transaction here.
This method accepts the following properties:
Name | Data type | Required? |
---|---|---|
transaction | Transaction | Yes |
newCoins | CoinInfo[] | No |
Below, you'll find an example of how to balance and prove a transaction:
try {
// assuming we have a transaction at hand here
const transaction;
const balancedAndProvenTransaction = await api.balanceAndProveTransaction(transaction);
} catch (error) {
console.log('an error occurred', error);
}
Submitting a transaction
With the balanced and proven transaction from above, you can now submit it.
The submitTransaction()
method accepts the following parameters:
Name | Data type | Required? |
---|---|---|
transaction | Transaction | Yes |
Below, you'll find an example of how to submit a transaction:
try {
const submittedTransaction = await api.submitTransaction(balancedAndProvenTransaction);
} catch (error) {
console.log('an error occurred', error);
}
Examples
In this section, you'll find examples demonstrating how to fully utilize the DApp connector API.
Submitting a transaction
This example demonstrates how to authorize and submit a transaction from a DApp's perspective using the DApp connector API.
try {
const api = await window.midnight.mnLace.enable();
// assuming this is a transaction we've already created
// [link to create transaction docs is in the "Balancing and proving a transaction" section]
const transaction;
const balancedAndProvenTransaction = await api.balanceAndProveTransaction(transaction);
const submittedTx = await api.submitTransaction(balancedAndProvenTransaction);
console.log(submittedTx);
} catch (error) {
console.log('an error occurred', error);
}