This section will guide you through several examples using the node.js binding of the
wallet.rs library. You can also find the code for the examples in the
/bindings/nodejs/examples folder in the official GitHub repository.
All the examples in this section expect you to set your custom password in the .env file:
You can initialize (open) a secure storage for individual accounts. The storage is backed up by
Stronghold by default, using an AccountManager instance.
The following example creates a new database and account:
- Storage is initialized under the given path (
- The password is set based on your password in .env file (
- When you initialize the new database, a Stronghold mnemonic (seed) is automatically generated and stored by default (
- The seed should be set only for the first time. In order to open already initialized database, you can simply use your password.
The storage is encrypted at rest, so you need a strong password and location where to place your storage.
We highly recommended that you to store your
Stronghold password encrypted on rest and separated from
Deal with the password with utmost care.
The storage comprises two things:
- A single file called wallet.stronghold , which contains seed.
Strongholdwill secure the seed and encrypt it at rest. The generated seed (mnemonic) serves as a cryptographic key, which is used to generate all accounts and related addresses.
- Other data used by library that is stored under db sub-directory. The includes account information, generated addresses, fetched messages, etc. This data is used to speed up some operations, such as account creation, address generation, etc.
One of the key principles behind
Stronghold based storage is that no one can extract a seed from the storage. You deal with all accounts purely via an AccountManager instance and all complexities are hidden under the hood and are dealt with securely.
If you also want to store a seed somewhere else, you can use the
AccountManager.generateMnemonic() method. You can use this method to generate a random seed. You can also use it before the actual account initialization.
You can find detailed information about seed generation at Developer Guide to Chrysalis.
wallet.rs library uses a model of individual accounts to separate individual users/clients from each other. It is possible to generate multiple addresses for each account deterministically. You can find more information about account management in the Developer Guide to Chrysalis.
Once the backend storage has been created, individual accounts for individual users can be created by running the
Each account is related to a specific IOTA network (mainnet / testnet), which is referenced by a node properties such as node url. In this example, the
Chrysalis testnet balancer.
For more information about clientOptions , please refer to Wallet NodeJs API Reference.
Alias should be unique, and it can be any string that you see fit. The alias is usually used to identify the account later on. Each account is also represented by an index which is incremented by 1 every time new account is created. Any account can be then referred to by its index , alias or one of its generated addresses .
Several API calls can be performed via an account instance.
It is a good practice to sync accounts with the Tangle every time you work with an account instance. This way you can ensure that you rely on the latest available information.
You can do this using
account.sync() is performed automatically on
promote API calls.
Once an account has been created, you can retrieve an instance using the following methods:
The most common methods of account instance are:
account.alias() : returns an alias of the given account.
account.listAddresses() : returns list of addresses related to the account.
account.getUnusedAddress() : returns a first unused address.
account.generateAddress() : generate a new address for the address index incremented by 1.
account.balance() : returns the balance for the given account.
account.sync() : sync the account information with the tangle.
Each account can have multiple addresses. Addresses are generated deterministically based on the account and address index. This means that the combination of account and index uniquely identifies the given address.
There are two types of addresses, internal and public (external), and each set of addresses is independent of each other and has independent index id.
- Public addresses are created by
account.generateAddress()and are indicated as internal=false (public)
- Internal addresses are also called
changeaddresses. Internal addresses are used to store the excess funds and are indicated as internal=false.
This approach is also known as a BIP32 Hierarchical Deterministic wallet (HD Wallet).
The IOTA 1.5 (Chrysalis) network supports reusing addresses multiple times.
You can use the following example to generate a new address:
Before we continue further, please visit the IOTA testnet faucet service and send to your testnet addresses some tokens.
You can use the following example to generate a new database and account:
IOTA is based on Unspent Transaction Output model. You can find a detailed explanation in the Developer Guide to Chrysalis.
You can use the following example to send tokens using an Account instance to any desired address:
The full function signature is
Account.send(address, amount, [options]).
You can use the default options. However, you can provide additional options, such as
remainderValueStrategy which has the following strategies:
changeAddress() : Send the remainder value to an internal address
reuseAddress() : Send the remainder value back to its original address
Account.send() function returns a wallet message that fully describes the given transaction. You can use the messageId to check confirmation status. You can retrieve individual messages related to any given account using the
The network uses a dust protection protocol to prevent malicious actors from spamming the network while also keeping track of the unspent amount ( UTXO ).
Micro-transaction below 1Mi of IOTA tokens can be sent to another address if there is already at least 1Mi on that address. That's why we sent 1Mi in the last example, to comply with the dust protection.
Dust protection also means you can't leave less than 1Mi on a spent address (leave a dust behind).
Due to security practices that are incorporated in the Stronghold's DNA, there is no way to retrieve a seed, as it is encrypted at rest. Therefore, if you're using the default options, you should make sure that you back up your seed regularly.
The following example will guide you in backing up your data in secure files. You can move this file to another app or device, and restore it.
To restore a database via
wallet.rs, you will need to create new empty database with a password (without mnemonic seed). After you've created the empty database, you will need to import all accounts from the file that has been backed up earlier
The following example restores a secured backup file:
Since the backup file is just a copy of the original database it can be also be renamed to wallet.stronghold and opened in a standard way.
wallet.rs library is able to listen to several supported event. As soon as the event occurs, a provided callback will be triggered.
You can use the following example to fetch an existing Account and listen to transaction events related to that Account :
You can then use the accountId to identify the account via
Read more about Events in the API reference.
You can use the following example to create a new database and account, and migrate funds from the legacy network to the