Usage: await client.core.getBestBlockHeight(options)
+Description: Allow to fetch the best (highest/latest block height) from the network
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| options | +DAPIClientOptions | +no | ++ |
Returns : {Promise
This document describes some tips and optimizations needed to speed up build of Docker images. +As Docker images are intensively used as part of the Dashmate workflow, these tips will be mainly +useful to:
+When building Dash Platform's Docker images, you can encounter the following issues:
+We implement the following levels of caching:
+RUN --mount=type=cache,...)sccacheCache mounts include some cachable elements of RUST_HOME (including downloaded dependencies), as well as +Cargo target dir. As the target dir grows to multiple +gigabytes, Docker cache garbage collector must be tuned accordingly.
+For example, you can create the following Buildkit config file in $HOME/.config/buildkit/buildkitd.toml:
[worker.oci]
+gc = true
+gckeepstorage = 40000 # 40 GB
+
+[[worker.oci.gcpolicy]]
+all = true
+keepBytes = 30000000000 # 30 GB
+keepDuration = 432000 # 5 days
+and create buildx builder instance:
+docker buildx create --config "$HOME/.config/buildkit/buildkitd.toml" --name local --use --bootstrap
+Double-check that configured garbage collection policy was correctly applied:
+docker exec -ti buildx_buildkit_local0 buildctl debug workers -v
+GC Policy rule#0:
+ All: true
+ Keep Duration: 120h0m0s
+ Keep Bytes: 30GB
+Sccache is an additional layer of caching that can be used to improve build speed. Sccache can cache build artifacts using multiple storage systems, like local filesystem, Github Actions, S3 buckets, memcache, and others.
+For local development in Docker, sccache uses Docker cache mounts. Alternative solution can be to use memcached daemon for caching.
+Sccache is disabled by default.
+To enable sccache, set RUSTC_WRAPPER=sccache build argument when building the Docker image. For example:
docker buildx build --build-arg RUSTC_WRAPPER=sccache --target drive-abci .
+To use sccache with memcache, setup local memcached daemon with reasonable amount of RAM (4GB here):
+docker run --name memcache -d -p 172.17.0.1:11211:11211 memcached memcached -m 4096 -l 0.0.0.0
+docker update --restart unless-stopped memcache
+Replace 172.17.0.1 with IP address of the host running memcached accessible from your Docker containers (and not accessible from external networks).
Before starting dashmate build, set SCCACHE_MEMCACHED to address of your memcache server:
export RUSTC_WRAPPER=sccache
+export SCCACHE_MEMCACHED=tcp://172.17.0.1:11211
+Pass SCCACHE_MEMCACHED build argument to Docker Buildx
+docker buildx build -f Dockerfile --build-arg SCCACHE_MEMCACHED=tcp://[your.ip.address.here]:11211 --progress=plain --target drive-abci .
+Replace 172.17.0.1 with IP address of the host running memcached accessible from your Docker containers.
You can also use the same cache for your local builds (eg. in your IDE). To do this, install sccache, and set RUSTC_WRAPPER environment variable before starting your IDE (on Linux, you can put them into $HOME/.profile):
export RUSTC_WRAPPER=/usr/local/bin/sccache
+If you want your local system to use same cache as docker builds, set SCCACHE_MEMCACHED:
export SCCACHE_MEMCACHED=tcp://172.17.0.1:11211
+If you use Microsoft Visual Studio Code and rust-analyzer, you can add forementioned environment variables to "rust-analyzer.cargo.extraEnv in your workspace config:
"settings": {
+ "rust-analyzer.rustfmt.extraArgs": [
+ "+nightly"
+ ],
+ "rust-analyzer.cargo.buildScripts.useRustcWrapper": true,
+ "rust-analyzer.cargo.extraEnv": {
+ "SCCACHE_MEMCACHED": "tcp://192.168.1.91:11211",
+ "CARGO_TARGET_DIR": "/home/lklimek/tmp/rust/target"
+ }
+}
+This document describes basic usage of drive-abci server.
+Configuration is implemented using environment variables. Environment variables will be read from operating system and .env file. If a variable is both defined in the operating system and the .env file, the former one takes precedence.
The logging configuration allows you to configure multiple logging destinations. Each destination is defined using a series of environment variables prefixed with ABCI_LOG_key_option, where key is an arbitrary name for the destination.
+The log destination configuration consists of the following parameters:
+Specifies the destination of the logs. It can have one of the following values:
+/var/log/dash/Specifies the logs verbosity level preset:
+Specifies whether to use colorful output for the logs. It is an optional boolean parameter. If not provided, the output colorization will be autodetected.
+Specifies the output format to use for the logs. It can have one of the following values:
+For more detailed description of different formats, refer to the tracing-subscriber documentation.
+Specifies the maximum number of daily log files to store. Defaults to 0.
+This parameter is only used when logs are stored in a file. If this is set to 0, log rotation is disabled.
+To configure multiple logging destinations, each destination should have its own environment variables. The environment variable names should be prefixed with ABCI_LOG_key, where key is an arbitrary name that uniquely identifies the destination.
+For example, to configure a logging destination with the key "example", you would set the following environment variables:
+Make sure to replace key with your desired destination name in the environment variable names.
+Here's an example configuration for a logging destination named "EXAMPLE":
+export ABCI_LOG_EXAMPLE_DESTINATION="/var/log/example"
+export ABCI_LOG_EXAMPLE_LEVEL=debug
+export ABCI_LOG_EXAMPLE_COLOR=false
+export ABCI_LOG_EXAMPLE_FORMAT="pretty"
+export ABCI_LOG_EXAMPLE_MAX_FILES=10
+This configuration specifies that logs for the "EXAMPLE" destination should be stored in the /var/log/example directory, with a verbosity level of 3. Colorful output should not be used, and the logs should be formatted in a human-readable and visually appealing manner. The maximum number of daily log files to store is set to 10.
+Ensure that you adjust the values according to your specific logging requirements.
+drive-abci verifyThe drive-abci verify command is used to verify the integrity of the database used by drive-abci.
+This command will execute GroveDB hash integrity checks to ensure that the database is consistent
+and free of corruption.
To use the drive-abci verify command, simply run the following command:
drive-abci verify
+This will execute the GroveDB hash integrity checks and report any errors or inconsistencies found in the database.
+You can also enforce GroveDB integrity checks during drive-abci start by creating a .fsck file in the database
+directory (DB_PATH). This file should be created before starting drive-abci, and can be empty.
When drive-abci starts up, it checks for the presence of the .fsck file in the database directory.
+If the file is present, it executes the specified integrity checks. After the checks are completed,
+the .fsck file is deleted from the database directory.
drive-abci running in DockerTo verify integrity of database when drive-abci runs in a Docker container, you can create a .fsck file in the
+database directory and and restart the container.
For example, for a drive-abci container dashmate_ccc1e5c2_local_1-drive_abci-1, you can execute the following commands:
docker exec -ti dashmate_ccc1e5c2_local_1-drive_abci-1 touch db/.fsck
+docker restart dashmate_ccc1e5c2_local_1-drive_abci-1
+You can check the result of verification in logs by running the following command:
+docker logs dashmate_ccc1e5c2_local_1-drive_abci-1 --tail 1000 2>&1 | grep 'grovedb verification'
+Usage
+new Account().broadcastTransaction().connect().createTransaction().decode().decrypt().disconnect().encode().encrypt().fetchAddressInfo().fetchStatus().fetchTransactionInfo().forceRefreshAccount().generateAddress().getAddress().getConfirmedBalance().getPrivateKeys().getTotalBalance().getTransaction().getTransactionHistory().getTransactions().getUnconfirmedBalance().getUTXOS().sign()new KeyChain().addNewTxToAddress().addUTXOToAddress().announce().calculateDuffBalance().clearAll().configure().createChain().createWallet().getStore().getTransaction().getTransactionMetadata().importTransaction().importTransactions().rehydrateState().saveState().searchAddress().searchAddressesWithTx().searchBlockHeader().searchTransaction().searchTransactionMetadata().searchWallet().startWorker().stopWorker().stopWorker().updateTransaction()Plugins
+ +Usage: new Account(wallet, accountOpts)
+Description: This method creates a new Account associated to the given wallet.
+Notes: As it is directly linked to a wallet, you might want to rely on Wallet.getAccount({index}) instead.
+When wallet.offlineMode:true, you can manage utxos / addresses via a cache options (or after init via the Storage controller).
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| wallet | +Wallet | +yes | +A valid wallet instance | +
| accountOpts.index | +number | +no | +The BIP44 account index; by default use the next one (n+1) of the biggest account index already created in wallet | +
| accountOpts.strategy | +string/function | +no | +A valid strategy string identifier (amongst "simpleAscendingAccumulator", "simpleDescendingAccumulator", simpleTransactionOptimizedAccumulator") or your own strategy function | +
| accountOpts.label | +string | +no (def: null) | +If you want to be able to reference to an account per label | +
| accountOpts.injectDefaultPlugins | +boolean | +no (def: true) | +Use to inject default plugins on loadup (BIP44Worker, ChainWorker and SyncWorker) | +
| accountOpts.allowSensitiveOperations | +boolean | +no (def: false) | +If you want a special plugin to access the keychain or other sensitive operation, set this to true. | +
| accountOpts.cacheTx | +boolean | +no (def: true) | +If you want to cache the transaction internally (for faster sync-up) | +
| accountOpts.cache.addresses | +object | +no | +If you have your addresses state somewhere else (fs) you can fetch and pass it along for faster sync-up | +
| accountOpts.cache.transactions | +object | +no | +If you have your tx state somewhere else (fs) you can fetch and pass it along for faster sync-up | +
Returns : Account instance.
+Examples (assuming a Wallet instance created) :
+const { Account, Wallet } = require('@dashevo/wallet-lib');
+const wallet = new Wallet();
+const account = new Account(wallet, {index: 42});
+await account.init();
+Reminder: Because many parameters are inherited from the wallet object (network, plugins, transporter, storage, keychain...), initializing an Account without a Wallet will require mocking all those properties.
+Identities: Identities are accessible from an account via the identities interface : account.identities. See Identities
Usage: account.broadcastTransaction(transaction)
+Description: Allow to broadcast a valid signed transaction to the network.
+Notes: Requires a signed transaction, use account.sign(transaction) for that.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| transaction | +Transaction/String | +yes | +A valid created transaction or it's hexadecimal raw representation | +
| options | +Object | +no | ++ |
| options.skipFeeValidation | +Boolean | +no | +When set to true, and min relay fee is not met, will still try to broadcast a transaction | +
| options.mempoolPropagationTimeout | +Number | +no | +The amount of milliseconds to wait for transaction mempool propagation | +
| Returns : transactionId (string). | ++ | + | + |
N.B : The TransactionID provided is subject to transaction malleability, and is not a source of truth (the transaction might be included in a block with a different txid).
+ + + + + + + + + + + + + +Usage: account.connect()
+Description: This method can be used to reconnect after having used .disconnect(). It will connect to all streams, bloomfilters and will start workers.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| + | + | + | + |
Returns : Boolean (true).
+ + + + + + + + + + + + + +Usage: account.createTransaction(txOpts)
+Description: Allow to create a transaction to one or multiple recipients.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| txOpts.recipient | +string | +yes (if no recipients) |
+The external address recipient of this transaction | +
| txOpts.satoshis | +string | +yes (if no recipients set) |
+The value amount to transfer to the recipient address | +
| txOpts.recipients | +Array[{recipient, satoshis}] | +no | +Alternatively, you can use this to send to multiple address/amount. Array arra of {recipient, satoshis} | +
| txOpts.utxos | +Array[utxos] | +no | +Can be specified to use specific utxo to use, or other utxos own by other private keys (you will need to pass the privateKeys along | +
| txOpts.privateKeys | +Array[PrivateKey/HDPrivateKey] | +no | +Overwrite the default behaviour (searching locally for keys) and uses these to sign instead. | +
| txOpts.strategy | +string/Function | +no | +Overwrite the default strategy used (using account default or specified strategy) | +
| txOpts.deductFee | +boolean | +no | +Defaults: true. When set at false, will not deduct fee on the Transaction object | +
| txOpts.change | +string | +no | +Defaults: account.getUnusedAddress(internal). When set, will use that address as a change address on remaining fund |
+
Returns : Transaction
+Notes: This transaction will be need to be signed account.sign(transaction) and then, if wanted, broadcasted to the network for execution account.broadcastTransaction().
Example :
+const recipients = [{recipient:"yereyozxENB9jbhqpbg1coE5c39ExqLSaG", satoshis:10e8},{recipient: "yMN2w8NiwcmY3zvJLeeBxpaExFV1aN23pg", satoshis: 1e8}];
+const change = "yaVrJ5dgELFkYwv6AydDyGPAJQ5kTJXyAN";
+const tx = account.createTransaction({recipients, change});
+Strategy:
+By default, wallet-lib is shipped with two different strategies :
+You can also pass your own strategy (as a function) to allow you to create your own strategy for how you will want to spend the UTXO.
+const recipient = "yereyozxENB9jbhqpbg1coE5c39ExqLSaG";
+const satoshis = 10e8;
+const specialStrategy = (utxosList, outputsList, deductFee = false, feeCategory = 'normal')=> {
+//...
+};
+const txOpts1 = {
+ recipient, satoshis,
+ strategy: 'simpleAscendingStrategy',
+};
+const txOpts2 = {
+ recipient, satoshis,
+ strategy: specialStrategy,
+};
+const tx1 = account.createTransaction(txOpts1);
+const tx2 = account.createTransaction(txOpts2);
+See more information about coinSelection.
+In order to broadcast a transaction, a minimal relay fee is required for a node to accept to broadcast the transaction.
+Such fee are used as a spam mechanism protection as a standard transaction would require slightly more than 0.0000012 Dash (varies per transaction and per node) as relay fee.
+The deduct fee property, when set at true allows to automatically estimate the size and deduct from outputs the corresponding amount.
+In case one user would want to not see that, he will be required to select an input to pay a fee by himself.
+Expected minimal relay fee for your transaction can be estimated this way :
+const { storage, network } = account;
+const { chains } = storage.getStore();
+const txOpts = {
+deductFee: false,
+}
+const transaction = account.createTransaction(txOpts);
+
+const { minRelay: minRelayFeeRate } = chains[network.toString()].fees;
+
+const estimateKbSize = transaction._estimateSize() / 1000;
+const minFeeToPay = estimateKbSize * minRelayFeeRate;
+Usage: account.decode(method, encodedValue)
+Description: Allow to decode an encoded value.
+Notes: Method allowed right now limited to cbor (used by platform protocol).
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| method | +String | +yes | +Enter a valid decoding method (one of: ['cbor']) | +
| encodedValue | +Buffer | +yes | +An encoded buffer value | +
Returns : decoded value (string).
+ + + + + + + + + + + + + +Usage: account.decrypt(method, encryptedData, secret, encoding)
+Description: Allow to decrypt an encrypted message
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| method | +String | +yes | +Enter a valid decrypt method (one of: ['aes']) | +
| encryptedData | +String | +yes | +An encrypted value | +
| secret | +String | +yes | +The secret used for encrypting the data in first place | +
| encoding | +['hex','utf8'] | +no (def: utf8) | +The secret used for encrypting the data in first place | +
Returns : decoded value (string).
+const decrypted = account.decrypt('aes','U2FsdGVkX18+7ixRbZ7DzC8P8X/4ewNHSp2R6pZDmsI=', 'secret')
+console.log(decrypted);// coucou
+Usage: account.disconnect()
+Description: This method will disconnect all plugins and other workers (Storage, SyncWorker). Useful to release all worker when doing integration testing with Wallet/Account
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| + | + | + | + |
Returns : void.
+ + + + + + + + + + + + + +Usage: account.encode(method, data)
+Description: Allow to encode any raw data
+Notes: Methods allowed right now limited to cbor (used by platform protocol).
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| method | +String | +yes | +Enter a valid encoding method (one of: ['cbor']) | +
| data | +Object/String | +yes | +A value to encode | +
Returns : encoded value (Buffer)
+Example :
+const jsonObject = {
+ string: 'string',
+ list: ['a', 'b', 'c', 'd'],
+ obj: {
+ int: 1,
+ boolean: true,
+ theNull: null,
+ },
+ };
+
+const encodedJSON = account.encode('cbor', jsonObject)
+console.log(Buffer.from(encodedJSON).toString('hex'));
+Usage: account.encrypt(method, data, secret)
+Description: Allow to encrypt a value using a specific secret
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| method | +String | +yes | +Enter a valid encryption method (one of: ['aes']) | +
| data | +String | +yes | +The value to encrypt | +
| secret | +String | +yes | +The secret used in order to encrypt the data | +
Returns : encrypted value (string).
+```js +const encrypted = account.encrypt('aes','coucou', 'secret'); +console.log(encrypted);// U2FsdGVkX18+7ixRbZ7DzC8P8X/4ewNHSp2R6pZDmsI=
+ + + + + + + + + + + + + +Usage: account.fetchAddressInfo(addressObj, fetchUtxo)
+Description: Fetch a specific address from the transport layer
+Notes: This method will have breaking changes with SPV implementation. We encourage you with using Storage or DAPI-Client.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| addressObj | +String | +yes | +Enter a valid encryption method (one of: ['aes']) | +
| fetchUtxo | +String | +yes | +The value to encrypt (default: true) | +
Returns : addrInfo (object representation of an address metadata)
+N.B: An AddressObject is an intern representation consisting of a {path, address, index}
Usage: account.fetchStatus()
+Description: Allow to retrieve status of the current chain (blockheight).
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| + | + | + | + |
Returns : status object
+ + + + + + + + + + + + + +Usage: account.fetchTransactionInfo()
+Description: Fetch a specific transaction from the transport layer
+Notes: This method will have breaking changes with SPV implementation. We encourage you with using Storage or DAPI-Client.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| transactionId | +String | +yes | +identifier of the Transaction to retrieve | +
Returns : transaction object (metadata : txid, blockhash, blockheight, blocktime, fees, size, vout, vin, txlock).
Usage: account.forceRefreshAccount()
+Description: Force a refresh of all the addresses informations (utxo, balance, txs...) by invalidating previous.
+Important: This is used for experience developer. If you have an issue or need using it, please do not hesitate to post an issue on GitHub.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| + | + | + | + |
Returns : boolean.
+ + + + + + + + + + + + + +Usage: account.generateAddress(path)
+Description: Generate an address from a path and import it to the store
+Notes: Usage of generate is discouraged, used account.getAddress() instead.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| path | +String | +yes | +BIP44 path of the address to generate | +
Returns : address object (metadata : path, index, address, transactions, balanceSat, unconfirmedBalanceSat, utxos, fetchedLast, used).
Usage: account.getAddress(index, type)
+Description: Get a specific address based on the index and type of address.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| index | +number | +no | +Index of the address (starting at 0) - default:0 | +
| type | +String | +no | +Type of the address, one of ['external','internal','misc']. - default: external | +
Returns : address object (metadata : path, index, address, transactions, balanceSat, unconfirmedBalanceSat, utxos, fetchedLast, used).
Usage: account.getConfirmedBalance(displayDuffs)
+Description: This method will return the confirmed balance (included in a block) of an account
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| displayDuffs | +boolean | +no (default: true) | +When set at true return in Duffs (satoshis), if false, returns in Dash | +
Return : number
+ + + + + + + + + + + + + +Usage: account.getPrivateKeys(addressList)
+Description: This method return the private keys list matching the passed address list of public keys
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| addressList | +Array[String ] | +yes | +The list of public address to match private key | +
Returns : Array[PrivateKey]
+ + + + + + + + + + + + + +Usage: account.getTotalBalance(displayDuffs)
+Description: This method will return the total (unconfirmed + confirmed) balance of an account
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| displayDuffs | +boolean | +no (default: true) | +When set at true return in Duffs (satoshis), if false, returns in Dash | +
Return : number
+ + + + + + + + + + + + + +Usage: account.getTransaction(txid)
+Description: This method will return the transaction of a specific id
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| txid | +string | +yes | +TxId of the transaction to fetch. | +
Return : transaction with metadata
+account.getTransaction('1a74dc225b3336c4edb1f94c9ec2ed88fd0ef136866fda26f8a734924407b4d6');
+/*
+ returns :
+ {
+ transaction: Transaction,
+ metadata: {
+ blockHash: '0000007a84abfe1d2b4201f4844bb1e59f24daf965c928281589269f281abc01',
+ height: 551438,
+ instantLocked: true,
+ chainLocked: true
+ }
+ }
+ */
+Usage: account.getTransactionHistory()
+Description: Allow to get the transaction history of an account
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| + | + | + | + |
Returns : sorted and classified transaction history
+const transactionHistory = await account.getTransactionHistory();
+Results in
+[{
+ from: [ { address: 'yNCqctyQaq51WU1hN5aNwsgMsZ5fRiB7GY', addressType: 'external' } ],
+ to: [
+ {
+ address: 'yiXh4Yo5djG6QH8WzXkKm5EFzqLRJWakXz',
+ satoshis: 1150000000,
+ addressType: 'otherAccount'
+ },
+ {
+ address: 'yh6Hcyipdvp6WJpQxjNbaXP4kzPQUJpY3n',
+ satoshis: 49999753,
+ addressType: 'internal'
+ }
+ ],
+ type: 'account_transfer',
+ time: Date('2021-08-17T21:35:58.000Z'),
+ txId: '6f76ca8038c6cb1b373bbbf80698afdc0d638e4a223be12a4feb5fd8e1801135',
+ blockHash: '000000444b3f2f02085f8befe72da5442c865c290658766cf935e1a71a4f4ba7',
+ isChainLocked: true,
+ isInstantLocked: true,
+ satoshisBalanceImpact: -1150000000,
+ feeImpact: 247
+}]
+Where addressType=external|internal|otherAccount|unknown
Usage: account.getTransactions()
+Description: This method will return the transactions for this account
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| + | + | + | + |
Returns : Array[transaction].
+ + + + + + + + + + + + + +Usage: account.getUTXOS(options)
+Description: This method will return the list of all available UTXOS for this account.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| options.coinbaseMaturity | +Number | +no (def: 100) | +Allow to override coinbase maturity | +
Returns : Array[utxos].
+ + + + + + + + + + + + + +Usage: account.getUnconfirmedBalance(displayDuffs)
+Description: This method will return the unconfirmed balance (missing inclusion in a block) of an account
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| displayDuffs | +boolean | +no (default: true) | +When set at true return in Duffs (satoshis), if false, returns in Dash | +
Return : number
+ + + + + + + + + + + + + +Usage: account.sign(transaction, privateKeys, sigType)
+Description: Allow to sign a transaction with private keys
+Notes: A Signable Object is of type : Transaction or Message (exported by DashJS).
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| object | +Signable | +yes | +Enter a valid encryption method (one of: ['aes']) | +
| privateKeys | +PrivateKey | +yes | +The private keys used to sign | +
| sigtype | +String | +no | +Default: crypto.Signature.SIGHASH_ALL | +
Returns : Signed Signable Object.
+const tx = account.createTransaction();
+const signedTx = account.sign(tx); // Will find the privateKey from keychain for you.
+const {Message} = require('dash');
+const message = new Message('hello, world');
+
+const idPrivateKey = account.getIdentityHDKeyByIndex(0, 0).privateKey;
+
+const signed = account.sign(message, idPrivateKey);
+const verify = message.verify(idPrivateKey.toAddress().toString(), signed.toString()); // true
+Wallet-lib will log multiple events happening which might help you to debug, or get a better understanding at what is happening internally.
+These are the different levels used internally sorted from the least verbose to the most.
+error - Warn about issues that are near critical (but are not straight thrown errors).warn - Warn about issues that aren't so critical.info - Log level used by default. Inform about some internal high value steps.debug - Inform about basic steps (plugin initialisations, ...)silly - Inform about everything going on (each transporter call, storage and worker execution,...)In order to control the granularity of the logger, simply put the environment variable LOG_LEVEL at the desired level.
set LOG_LEVEL=silly node index.jsLOG_LEVEL=silly node index.jsexport LOG_LEVEL=silly node index.js Wallet-lib allows the use of a persistence adapter in order to store information fetched via the transporter in order to provide faster loading on later uses.
+This adapter can be useful for multiple cases, for instance:
+When no persistence is set, Wallet-lib will use by default, an In Memory adapter, which won't persist information except in local RAM.
+A message will warn you about this on starting up, and won't be displayed with a properly set adapter.
By just providing a class or instance of a class containing a certain minimal set of methods, one can provide an adapter for various databases, remote services or file storage.
+config(props) - async / optional - When provided, before any execution, this method would be called passing with the following property name: 'dashevo-wallet-lib'.This method intends to allow the preparation of your persistence layer to be ready for further uses (for instance, in a case where your adapter is a database, this would allow to set indexes, and prepare the connection pool).
+setItem(key, item) - async / mandatory - This is the method that will be used to set any item to the persistence layer.
getItem(key) - async / mandatory - This will be called in order to retrieve any item from the persistence layer.
Usage: account.events.on('blockheight_changed', fn)
+Description: An event is thrown each time Wallet-lib is being made aware of a new block validated by the protocol.
Example:
+const {EVENTS} = require('@dashevo/wallet-lib');
+
+account.events.on(EVENTS.BLOCKHEIGHT_CHANGED, ({payload: blockHeight})=>{
+ console.log(`Blockheight changed to ${blockHeight}`);
+});
+Usage: account.events.on('confirmed_balance_changed', fn)
+Description: Wallet-lib, when finished to perform it's internal tasks (blockheight, SPV, utxos sync...), will throw this event.
+Important: Standardization on event might happen soon, to avoid breaking change, use the EVENTS constant as described below.
Example:
+const {EVENTS} = require('@dashevo/wallet-lib');
+const onConfirmedBalanceChange = ()=>{
+ console.log('Balance changed');
+}
+account.events.on(EVENTS.CONFIRMED_BALANCE_CHANGED, onConfirmedBalanceChange);
+Usage: account.events.on('FETCHED/CONFIRMED_TRANSACTION', fn)
+Description: Every time a new confirmed transaction is fetched from the network, an event in thrown.
Returns : {Transaction}
+Example:
+const {EVENTS} = require('@dashevo/wallet-lib');
+const onNewConfirmedTx = (tx)=>{
+ console.log('Confirmed tx', tx);
+}
+account.events.on(EVENTS.FETCHED_CONFIRMED_TRANSACTION, onNewConfirmedTx);
+Usage: account.events.on('FETCHED/UNCONFIRMED_TRANSACTION', fn)
+Description: Every time a new unconfirmed transaction is fetched from the network, an event in thrown.
Returns : {Transaction}
+Example:
+const {EVENTS} = require('@dashevo/wallet-lib');
+const onNewUnconfirmedTx = (tx)=>{
+ console.log('Unconfirmed tx', tx);
+}
+account.events.on(EVENTS.FETCHED_UNCONFIRMED_TRANSACTION, onNewUnconfirmedTx);
+Usage: account.events.on('ready', fn)
+Description: Wallet-lib, when finished to perform it's internal tasks (blockheight, SPV, utxos sync...), will throw this event.
Example:
+const {EVENTS} = require('@dashevo/wallet-lib');
+const onReady = ()=>{
+ console.log('Wallet-lib is ready to perform action');
+}
+account.events.on(EVENTS.READY, onReady);
+Usage: account.events.on('unconfirmed_balance_changed', fn)
+Description: When not offline, the wallet will keep track of new transaction incoming or outgoing, these cause balance modification that this method warn about
+Important: Standardization on event might happen soon, to avoid breaking change, use the EVENTS constant as described below.
Example:
+const {EVENTS} = require('@dashevo/wallet-lib');
+const onUnconfirmedBalanceChange = ()=>{
+ console.log('Unconfirmed Balance changed');
+}
+account.events.on(EVENTS.UNCONFIRMED_BALANCE_CHANGED, onUnconfirmedBalanceChange);
+The Dash Core Developer Guide will answer most of the questions about the fundamentals of Dash.
+However, some elements provided by the SDK need to be grasped, so we will quickly cover some of those.
+At the core of Dash is the Payment Chain, in order to be able to transact on it, one needs to have a set of UTXO that is controlled by a Wallet instance.
+In order to access your UTXO, you will have to provide a valid mnemonic that will unlock the Wallet and automatically fetch the associated UTXOs.
+Since the introduction of deterministic wallet, a Wallet is actually composed of multiple account.
+For manipulating multiple accounts, Wallet.getAccount() takes optional options where index allows either accessing or creating a specific account index.
A Wallet instance can be created from multiples types, which impact how much the Wallet can do.
+In general, we expect you to initialize from a mnemonic or an seed (HD seed) or an HDPrivateKey, which allows wallet-lib to deal with HD Wallet (deterministic wallet).
In some other cases, you might want to instantiate Wallet from another input such as :
+- privateKey: This allows managing a single privateKey/publicKey set. Therefore, you will only have a single unique address to receive money.
+- HDPublicKey: This allows a "watch-only" mode. You won't be able to spend anything, but this will allow you to track and monitor in real-time the address set of this public key. This allows you to derive unique unused addresses from a single key (shared by another user, third-party merchant).
In order to use this library in Node, you will need to add it to your project as a dependency.
+Having NodeJS installed, just type in your terminal :
+npm install @dashevo/wallet-lib
+For browser usage, you can also directly rely on unpkg for wallet-lib, and localForage as adapter for persistence.
+<script src="https://unpkg.com/@dashevo/wallet-lib"></script>
+<script src="https://unpkg.com/localforage"></script>
+
+<script>
+const { Wallet } = require('@dashevo/wallet-lib');
+const wallet = new Wallet({adapter: localforage});
+</script>
+Let's load our Wallet by creating a new Wallet instance specifying our mnemonic.
+const { Wallet } = require('@dashevo/wallet-lib');
+
+const opts = {
+ network: 'testnet',
+ mnemonic: "arena light cheap control apple buffalo indicate rare motor valid accident isolate",
+};
+const wallet = new Wallet(opts);
+wallet.getAccount().then((account) => {
+ // At this point, account has fetched all UTXOs if they exist
+ const balance = account.getTotalBalance();
+ console.log(`Balance: ${balance}`);
+
+ // We easily can get a new address to fund
+ const { address } = account.getUnusedAddress();
+});
+In above code, we did not specify any transport instance, as by default, wallet-lib is using DAPI as a transporter; The adapter not being set, we will use by default an in-memory (without persistence) adapter.
+One can set any adapter that contains a valid adapter syntax (getItem, setItem), such as localForage, you can learn more about creating your own persistence adapter.
Quick note :
+null, a mnemonic will be created for you automatically. evonet.wallet.getAccount() is by default equivalent to wallet.getAccount({ index:0 }), where 0 correspond of the account index as per BIP44.const options = {
+ recipient:'yLptqWxjgTxtwKJuLHoGY222NnoeqYuN8h',
+ satoshis:100000
+};
+const transaction = account.createTransaction(options)
+const txid = await account.broadcastTransaction(transaction);
+account.disconnect() which will care to
+call clearWorker(), closeSocket() of the different elements. You can still decide to remove them by hand if you want.Usage: new Identities(wallet)
+Description: This method creates a new Identities instance associated to the given wallet.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| wallet | +Wallet | +yes | +A valid wallet instance | +
Returns : Identities instance.
+Examples (assuming a Wallet instance created) :
+const { Identities, Wallet } = require('@dashevo/wallet-lib');
+const wallet = new Wallet();
+const identities = new Identities(wallet);
+identities.getIdentityHDKeyByIndex(0, 0);
+Usage: identities.getIdentityHDKeyByIndex(identityIndex, keyIndex)
+Description: This method returns the identity HDKey of identityIndex for the specified keyIndex
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| identityIndex | +number | +yes | +To derive the key for a specific identityIndex (default: 0) | +
| keyIndex | +number | +yes | +To derive the key for a specific keyIndex (default: 0) | +
Returns : HDKeys (private, public).
+ + + + + + + + + + + + + +Usage: new KeyChain(opts)
+Description: This method create a new KeyChain. Which handle handle the derivation and handling of the HDRootKey (when init from an HDPrivKey).
While both the seed and the mnemonic would allow to generate other coins private keys, a HDRootKey is specific to a coin, which is why it's the value used in store..
+Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| opts.network | +Network | +String | +no (testnet) | +
| opts.type | +string | +yes | +The type of the KeyChain (HDPrivateKey, HDPublicKey or privateKey) | +
| opts.HDPrivateKey | +object | +yes (if type) | +If type is HDPrivateKey, the root HDPrivateKey to allow KeyChain to generate new address | +
| opts.HDPublicKey | +object | +yes (if type) | +If type is HDPublicKey, the root HDPublicKey to allow KeyChain to generate new public address | +
| opts.privateKey | +object | +yes (if type) | +If type is a PrivateKey, the PrivKey to allow KeyChain to manage public address | +
| opts.keys | +object | +no | +If required, allow to create KeyChain by passing it a set of keys | +
Returns : Keychain instance.
+ + + + + + + + + + + + + +Usage: keychain.generateKeyForChild(index,type)
+Description: Generate key for a specific index without storing the result in keychain.
+Important: For cache/perf reason, this method is discouraged in favor of getKeyForPath.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| index | +number | +yes | +Enter a valid index to derivate to | +
| type | +string | +no (default:HDPrivateKey) | +Enter a valid type (one of: ['HDPrivateKey','HDPublicKey']) | +
Returns : {HDPrivateKey|HDPublicKey}
+Example:
+const { privateKey } = keychain.generateKeyForChild(0);
+VERIFY THAT IT ACTUALLY WORKS AS EXPECTED LOL.
+ + + + + + + + + + + + + +Usage: keychain.generateKeyForPath(path, type)
+Description: Generate key for a specific path without storing the result in keychain.
+Important: For cache/perf reason, this method is discouraged in favor of getKeyForPath.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| path | +string | +yes | +Enter a valid path | +
| type | +string | +no (default:HDPrivateKey) | +Enter a valid type (one of: ['HDPrivateKey','HDPublicKey']) | +
Returns : {HDPrivateKey|HDPublicKey}
+Example:
+const { privateKey } = keychain.generateKeyForPath(0);
+ADD TESTS! PLUS PATH
+ + + + + + + + + + + + + +Usage: keychain.getDIP15ExtendedKey(userUniqueId, contactUniqueId, index, accountIndex = 0, type = 'HDPrivateKey')
Description: Return a DIP15 Extended Key of a 2-contacts relationship
+Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| userUniqueId | +string | +yes | +Current DashPay unique UserID | +
| contactUniqueId | +string | +yes | +Contact DashPay unique UserID | +
| index | +number | +no(=0) | +the key index to derivate to | +
| accountIndex | +number | +no(=0) | +the wallet account index from which to derivate | +
| type | +string | +no (default:HDPrivateKey) | +type of returned keys. one of: ['HDPrivateKey','HDPublicKey']. | +
Returns : {HDPrivateKey|HDPublicKey} (of path: m/9'/5'/15'/accountIndex'/userId'/contactID'/index on mainnet or m/9'/1'/15'/... on testnet)
Example:
+// m/9'/5'/15'/0'/0x555d3854c910b7dee436869c4724bed2fe0784e198b8a39f02bbb49d8ebcfc3a'/0xa137439f36d04a15474ff7423e4b904a14373fafb37a41db74c84f1dbb5c89b5'/0
+
+const userUniqueId = '0x555d3854c910b7dee436869c4724bed2fe0784e198b8a39f02bbb49d8ebcfc3a';
+const contactUniqueId = '0xa137439f36d04a15474ff7423e4b904a14373fafb37a41db74c84f1dbb5c89b5';
+
+const DIP15ExtPrivKey_0 = keychain2.getDIP15ExtendedKey(userUniqueId, contactUniqueId, 0, 0, 'HDPrivateKey');
+const { privateKey } = DIP15ExtPrivKey_0; //fac40790776d171ee1db90899b5eb2df2f7d2aaf35ad56f07ffb8ed2c57f8e60
+Usage: keychain.getHardenedBIP44HDKey(type)
+Description: Return a safier root key to derivate from
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| type | +string | +no (default:HDPrivateKey) | +Enter a valid type (one of: ['HDPrivateKey','HDPublicKey']) | +
Returns : HDPrivateKey
+Example:
+const hdPrivateKey = keychain.getHardenedBIP44HDKey();
+const { privateKey } = hdPrivateKey
+Usage: keychain.getHardenedDIP15AccountKey(accountIndex = 0, type = 'HDPrivateKey')
+Description: Return a safier root path to derivate from
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| accountIndex | +number | +no (default:0) | +set the account index | +
| type | +string | +no (default:HDPrivateKey) | +Enter a valid type (one of: ['HDPrivateKey','HDPublicKey']) | +
Returns : HDPrivateKey (of path: m/9'/1'/15'/accountIndex' on testnet or m/9'/5'/15'/accountIndex' on livenet)
Example:
+
+const hdPrivateKey = keychain.getHardenedDIP15AccountKey();
+const { privateKey } = hdPrivateKey;
+
+Usage: keychain.getHardenedDIP9FeatureHDKey(type)
+Description: Return a safier root key to derivate from
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| type | +string | +no (default:HDPrivateKey) | +Enter a valid type (one of: ['HDPrivateKey','HDPublicKey']) | +
Returns : HDPrivateKey (of path: m/9'/1' on testnet or m/9'/5' on livenet)
Example:
+
+const hdPrivateKey = keychain.getHardenedDIP9FeatureHDKey();
+const { privateKey } = hdPrivateKey;
+
+Usage: keychain.getKeyForChild(index,type)
+Description: Use to derivate the root key to a specific child. (useful when Wallet is initialized from a HDPublicKey)
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| index | +number | +yes | +Enter a valid index | +
| type | +string | +no (default:HDPublicKey) | +Enter a valid type (one of: ['HDPrivateKey','HDPublicKey']) | +
Returns : HDPrivateKey
+Example:
+const { privateKey } = keychain.getKeyForChild(0);
+Usage: keychain.getKeyForPath(path,type)
+Description: Get a key from the keychain cache or generate if not yet existing
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| path | +string | +yes | +Enter a valid derivation path | +
| type | +string | +no (default:HDPrivateKey) | +Enter a valid type (one of: ['HDPrivateKey','HDPublicKey']) | +
Returns : HDPrivateKey
+Example:
+const { privateKey } = keychain.getKeyForPath(`m/44'/1'/0'/0'/0`);
+Usage: keychain.getPrivateKey()
+Description: Return the privateKey of the HDPrivateKey of a KeyChain initialized from a mnemonic (alternatively, if Keychain is init from a pk, it just returns it.)
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| + | + | + | + |
Returns : PrivateKey
+ + + + + + + + + + + + + +Usage: keychain.sign(transaction, privateKeys, sigType)
+Description: Allow to sign a transaction with private keys
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| object | +Transaction | +yes | +Enter a valid encryption method (one of: ['aes']) | +
| privateKeys | +PrivateKey | +yes | +The private keys used to sign | +
| sigtype | +String | +no | +Default: crypto.Signature.SIGHASH_ALL | +
Returns : Signed Transaction.
+ + + + + + + + + + + + + +You may propose your own plugin by submitting a P.R to this file with the GitHub or NPM repository for your plugin with a small description.
+ + + + + + + + + + + + + +In order to add features and logic to the Wallet-library and be able to share independant module and request them together. +Wallet-lib can be passed some plugins at his instantiation. +Plugins are particular shaped class that can perform action on your wallet.
+By default, three plugins are injected : BIP44Worker, SyncWorker and ChainWorker.
+They handle respectively with maintaining your address pool, getting you in sync with the blockchain and maintaining some knowledge about the chain (blockheight).
+You can disable them by adding injectDefaultPlugins:false at the initialization parameter of your wallet object.
For more granularity, you could do it as a parameter of getAccount(accOpts).
There are three different types of plugins that can be used in the wallet-library:
+workerIntervalTime.In order for a plugin to have the ability to access wallet data, you have to add a dependency in the constructor.
+class MyPlugin extends StandardPlugin {
+ constructor(){
+ this.dependencies = ['walletId']
+ }
+ doStruff(){
+ return this.walletId.substr(0);
+ }
+}
+This will allow to access the walletId property; the same thing is doable with the account function.
+wallet.getAccount({index:0}).then((account)=>{
+ const plugin = account.getPlugin('pluginName');
+ });
+In order to perform it's duty of being in-sync with the network and to always keep a pre-generated set of unused addresses, wallet-lib uses internally two workers : +- Sync Worker : Used to keep in sync with the network (utxo, received transactions,...) +- Chain Worker : Used to keep track of the current chain (best block height,...) +- BIP44 Worker : Used to always have a set of 20 unused addresses as per BIP44.
+Theses default workers can be deactivated by adding the options injectDefaultPlugins to false while initializing your Wallet instance.
worker.startWorker();
+worker.stopWorker();
+const {events, storage, getAddress} = account;
+const opts = {
+ events,
+ storage,
+ getAddress
+}
+const worker = new BIP44Worker(opts);
+There is no control nor monitoring over third-party plugin. So anyone can write it's own plugin.
+In order for a plugin to have the ability to access wallet data, you have to add a dependency in the constructor.
+Below, we create a Standard Plugin, see Using a plugin for more information about the different plugin types.
+const { StandardPlugin } = require('@dashevo/wallet-lib').plugins;
+
+class MyWalletConsolidatorPlugin extends StandardPlugin {
+ constructor() {
+ super({
+ // When true, the wallet instance will only fire "ready" when a first execution of the plugin has happen.
+ firstExecutionRequired: false,
+ // Describe if we want to automatically execute it on starting up an account.
+ executeOnStart: false,
+ // Methods and function that we would want to use
+ dependencies: [
+ 'getUTXOS',
+ 'getUnusedAddress',
+ 'getConfirmedBalance',
+ 'createTransactionFromUTXOS',
+ 'broadcastTransaction',
+ ],
+ });
+ }
+
+ consolidateWallet(address = this.getUnusedAddress().address, utxos = this.getUTXOS()) {
+ return {
+ prepareTransaction: () => {
+ if (!utxos || utxos.length === 0) {
+ throw new Error('There is nothing to consolidate');
+ }
+ const opts = {
+ utxos,
+ recipient: address,
+ };
+
+ const rawtx = this.createTransactionFromUTXOS(opts);
+ return {
+ toString: () => rawtx,
+ broadcast: async () => {
+ console.log(`BROADCASTING ${rawtx}`);
+ return self.broadcastTransaction(rawtx);
+ },
+ };
+ },
+ };
+ }
+}
+When you plugin is created, including it in your Wallet is as easy as referencing up the class in the plugins array.
const wallet = new Wallet({
+ plugins:[MyWalletConsolidatorPlugin]
+})
+When some parameters are required first for your plugin to work, you might also decide to initialize first your plugin like this :
+const wallet = new Wallet({
+ plugins:[new MyWalletConsolidatorPlugin({someOptions:true})]
+});
+Due to the risk from running a plugin that have access to your keychain, these are, by default, not accessible.
+One would need to initialize a Wallet with the option allowSensitiveOperations set to true.
You can see the list of thoses sensitive functions and properties, anything under UNSAFE_* will require this option to be set to true in order to be use from within a plugin.
While system plugins will by default be first injected in the system, in the case of a need for specific injection order.
+Plugin can be sorted in such a way that in got injected before or after another set of plugins.
+For this, use injectionOrder properties before and/or after.
In below example, this worker will be dependent on the methods getUTXOS to be internally available, and will be expected to be injected before TransactionSyncStreamWorker and after ChainPlugin.
+ class WithInjectBeforeDependenciesWorker extends Worker {
+ constructor() {
+ super({
+ name: 'withInjectBeforeDependenciesWorker',
+ dependencies: [
+ 'getUTXOS',
+ ],
+ injectionOrder: {
+ after: [
+ 'ChainPlugin'
+ ],
+ before: [
+ 'TransactionSyncStreamWorker'
+ ]
+ }
+ });
+ }
+ }
+ ```
+
+## Accessing events
+
+From a plugin, you have the ability to listen to account's emitted events.
+
+```js
+const { EVENT, plugins: { Worker } } = require('@dashevo/wallet-lib');
+class NewBlockWorker extends Worker {
+ constructor(options) {
+ super({
+ name: 'NewBlockWorker',
+ executeOnStart: true,
+ firstExecutionRequired: true,
+ workerIntervalTime: 60 * 1000,
+ gapLimit: 10,
+ dependencies: [
+ 'storage',
+ 'transport',
+ 'walletId',
+ 'identities',
+ ],
+ ...options,
+ });
+ }
+
+ async onStart() {
+ this.parentEvents.on(EVENT.BLOCKHEIGHT_CHANGED, ({payload: blockHeight}) => {
+ // on new blockheight do something.
+ });
+ }
+}
+Usage: new Storage(opts)
+Description: This method create a new Storage instance which provide various helper with interacting with atomic elements (tx, address). It connects with the adapter to perform load/save operations.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| opts.network | +Network|String | +no (testnet) | +The network to use for the Storage instance | +
| opts.rehydrate | +Boolean | +no (true) | +If data should be autoloaded from the adapter | +
| opts.autosave | +Boolean | +no (true) | +If set at true, will autosave the storage to adapter at an autosaveIntervalTime | +
| opts.autosaveIntervalTime | +Number | +no (10sec) | +If millisecond, the interval time at which the adapter should persist the data | +
Returns : Storage instance.
+ + + + + + + + + + + + + +Usage: storage.addNewTxToAddress(tx, address)
+Description: Add a specific transaction to the related address.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| tx | +Transaction Object | +yes | +The Transaction to link to the B58 address | +
| address | +String (b58 address) | +yes | +A valid B58 address | +
Returns: Boolean
+ + + + + + + + + + + + + +Usage: storage.addUTXOToAddress(utxo, address)
+Description: Link the specified utxo to the related address.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| utxo | +UTXO Object | +yes | +A valid UTXO | +
| address | +String (b58 address) | +yes | +A valid B58 address | +
Returns: Boolean
+ + + + + + + + + + + + + +Usage: storage.announce(type, el)
+Description: Internal method helper to announce event to the Wallet and Account class.
+Notes: Listening to accounts.events will transmit those event.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| type | +String (event) | +yes | ++ |
| el | +Object | +yes | ++ |
Returns: Boolean
+ + + + + + + + + + + + + +Usage: storage.calculateDuffBalance(walletId, accountIndex, type)
+Description: Perform a full calculation of the balance of a wallet and account set.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| walletId | +String | +yes | +The wallet identifier in which we the account is | +
| accountIndex | +Number | +yes | +The account index from which we want to perform the calculation | +
| type | +Enum['total', 'confirmed', 'unconfirmed'] | +no (def: total) | +Depending of UTXO status, will calculate accordingly | +
Returns: Number (duff - aka satoshis - value of the balance).
+ + + + + + + + + + + + + +Usage: storage.clearAll()
+Description: Clear all data from the store and ask the adapter to store the empty state.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| + | + | + | + |
Returns: Boolean (saveState).
+ + + + + + + + + + + + + +Usage: storage.configure(opts)
+Description: After Storage creation, this method is called to ensure Adapter contains expected method.
+Notes: This is an internal advanced function called on the startup of a Storage.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| opts.rehydrate | +Boolean | +no | +Set if the Storage will autoload from the adapter | +
| opts.autosave | +Boolean | +no | +Set if the Storage will autosave to the adapter | +
| opts.adapter | +Adapter | +no | +The adapter to test and use. | +
Returns: void.
+Emits: CONFIGURED
Usage: storage.createChain(network)
+Description: Create, if not already existing, a chain in the store.
+Notes: This is an internal advanced function called on the creation of a Wallet. Also, at current state, both testnet and evonet uses the same "Testnet" object. Which might cause support issue when using both chain.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| network | +Network/String | +yes | +The network of the chain to create | +
Returns: Boolean
+ + + + + + + + + + + + + +Usage: storage.createWallet(walletId, network, mnemonic, type)
+Description: Create a wallet in store based on the specified params.
+Notes: This is an internal advanced function called on the creation of a Wallet.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| walletId | +String | +yes | +The wallet id to create | +
| network | +Network/String | +no (Def: testnet) | +The network for the wallet | +
| mnemonic | +Mnemonic/String | +no (Def: null) | +When applicable, the mnemonic used to generate the wallet | +
| type | +String | +no (Def: null) | +The wallet type to create | +
Returns: Boolean
+ + + + + + + + + + + + + +Usage: storage.getStore()
+Description: Used to get the whole store.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| + | + | + | + |
Returns: Full store data
+ + + + + + + + + + + + + +Usage: storage.getTransaction(transactionId)
+Description: Return the transaction from the store matching the txId.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| transactionId | +String | +yes | +The transaction id to fetch from the state | +
Returns: TransactionObject
+Example:
+storage.getTransaction('4f71db0c4bf3e2769a3ebd2162753b54b33028e3287e45f93c5c7df8bac5ec7e')
+Usage: storage.getTransactionMetadata(transactionId)
+Description: Return the transaction metadata from the store matching the txId.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| transactionId | +String | +yes | +The transaction id to fetch from the state | +
Returns: TransactionMetadata
+Example:
+storage.getTransactionMetadata('4f71db0c4bf3e2769a3ebd2162753b54b33028e3287e45f93c5c7df8bac5ec7e')
+Usage: storage.importAccounts(accounts, walletId)
+Description: Allow to import one or multiple accounts (Account store representation) to the wallet store based on it's walletId.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| accounts | +Array[AccountObj] | +yes | +The array of account object to import to the store | +
| walletId | +String | +yes | +The wallet id to attach the account to | +
Returns: Boolean
+ + + + + + + + + + + + + +Usage: storage.importAddress(addressObj, walletId)
+Description: Allow to import one address to the wallet store
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| addressObj | +AddressObj | +yes | +The address object to import to the store | +
| walletId | +String | +yes | +The wallet id to attach the address to | +
Returns: Boolean
+ + + + + + + + + + + + + +Usage: storage.importAddresses(addresses, walletId)
+Description: Allow to import one or multiple addresses to the wallet
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| addresses | +Array(addressObj) | +yes | +The address object set to import to the store | +
| walletId | +String | +yes | +The wallet id to attach the address to | +
Returns: Boolean
+ + + + + + + + + + + + + +Usage: storage.importSingleAddress(singleAddress, walletId)
+Description: Allow to import a single address to the wallet
+Notes: Not useful when managing a HDWallet.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| singleAddress | +Object | +yes | +The single address object representation to import to the store | +
| walletId | +String | +yes | +The wallet id to attach the address to | +
Returns: Boolean
+ + + + + + + + + + + + + +Usage: storage.importTransaction(transaction, metadata?)
+Description: Allow to import a transaction to the store.
+Notes: TransactionObject needs to contains basic vin/vout information.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| transaction | +Object/Transaction | +yes | +The transaction to import to the store | +
| metadata | +TransactionMetaData | +no | +The transaction metadata | +
Returns: Boolean
+Emits: FETCHED_CONFIRMED_TRANSACTION/FETCHED_UNCONFIRMED_TRANSACTION
Usage: storage.importTransactions(transactions)
+Description: Allow to import a set (array) of transactions to the store.
+Notes: Uses storage.importTransaction
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| transactions | +Array[TransactionWithMetadata]/Array[Transaction/Object]/Object | +yes | +The set of transactions to import to the store (can be a single element) | +
Returns: Boolean
+ + + + + + + + + + + + + +Usage: async storage.rehydrateState()
+Description: Used to fetch the state from the persistence adapter
+Notes: Three items are fetch (adapter.getItem) : transactions, wallets and chains data.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| + | + | + | + |
Returns: Void
+Emit: REHYDRATE_STATE_SUCCESS/REHYDRATE_STATE_FAILED event
Usage: async storage.saveState()
+Description: Used to force persistence of the state to the adapter
+Notes: Three items are set (adapter.setItem) : transactions, wallets and chains data.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| + | + | + | + |
Returns : Boolean
+ + + + + + + + + + + + + +Usage: storage.searchAddress(address, forceLoop)
+Description: Returns a specific address information from the store
+Notes: We maintain mapped (cache) address for easy look-up, forceLoop value allow to outpass that cache and force a slow lookup in the store.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| address | +String | +yes | +The Address identifier (Base 58 hash representation) to search for | +
| forceLoop | +Boolean | +no (def: false) | +Used to bypass the cache and force looping over the addresses | +
Returns : Object ({found, result, type, address, walletId}).
+ + + + + + + + + + + + + +Usage: storage.searchAddressesWithTx(transactionId)
+Description: Returns the list of addresses objects that has a relation with the provided TxId.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| transactionId | +String | +yes | +The Transaction identifier to search for | +
Returns : Object ({found, results, txid}).
+ + + + + + + + + + + + + +Usage: storage.searchBlockHeader(identifier)
+Description: Returns the blockHeader matching the provided identifier if it is stored.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| identifier | +String/Number | +yes | +The BlockHeader identifier (hash or height) to search for | +
Returns : BlockHeader.
+ + + + + + + + + + + + + +Usage: storage.searchTransaction(transactionId)
+Description: Returns the transaction information from the provided TxId if exists.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| transactionId | +String | +yes | +The Transaction identifier to search for | +
Returns : Object ({found, result, hash}).
+ + + + + + + + + + + + + +Usage: storage.searchTransactionMetadata(transactionId)
+Description: Returns the transaction metadata from the provided TxId if exists.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| transactionId | +String | +yes | +The Transaction identifier to search for | +
Returns : Object ({found, result, hash}).
+ + + + + + + + + + + + + +Usage: storage.searchWallet(walletId)
+Description: Returns the wallet information from the provided walletId if exists.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| walletId | +String | +yes | +The Wallet identifier of the wallet containing the address to update | +
Returns : Object ({found, result, walletId}).
+ + + + + + + + + + + + + +Usage: storage.startWorker()
+Description: Allow to start the storage worker (uses interval), will save the state when needed.
+Notes: Use storage.stopWorker() to stop.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| + | + | + | + |
Returns : void.
+ + + + + + + + + + + + + +Usage: storage.stopWorker()
+Description: When the storage worker is running (interval), will clear it stopping further interval to be executed.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| + | + | + | + |
Returns : Boolean.
+ + + + + + + + + + + + + +Usage: async storage.updateAddress(addressObj, walletId)
+Description: Used to update a specific address of a wallet identified by it's walletId.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| addressObj | +AddressObject | +yes | +The AddressObject to update (uses address.path as primary key) | +
| walletId | +String | +yes | +The Wallet identifier of the wallet containing the address to update | +
Returns : Boolean.
+Example:
+storage.updateAddress({
+ path: "m/44'/1'/0'/0/0",
+ index: '0',
+ address: 'yLhsYLXW5sFHLDPLj2EHgrmQRhP712ANda',
+ transactions: [],
+ balanceSat: 0,
+ unconfirmedBalanceSat: 0,
+ utxos: {},
+ fetchedLast: 0,
+ used: true,
+ }, "a3771aaf93");
+Usage: storage.updateTransaction(transaction)
+Description: Internally, this is mostly called to update the information of a transaction in the store. Works mostly more as an replace than an update.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| transaction | +Transaction | +yes | +The Transaction to update (uses tx.hash as key) | +
Returns : Boolean.
+Example:
+const { Transaction } = require('@dashevo/dashcore-lib');
+const transaction = new Transaction({
+ hash: '9b4a34096f2270f70d8e0ba91094eb37535349f80874f8440e74c0567ef82680',
+ version: 3,
+ inputs: [
+ {
+ prevTxId: '9f398515b6fc898ebf4e7b49bbfc4359b8c89f508c6cd677e53946bd86064b28',
+ outputIndex: 0,
+ sequenceNumber: 4294967295,
+ script: '47304402205bb4f7880fb0fc13218940ba341c30e817363e5590343d28639af921b2a5f1d40220010920ae4b00bbb657f8653cb44172b8cb13447bb5105ddaf32a2845ea0666b90121025ae98eff89505fa5ff60f919ae690de638d31f4f2fcab9a9deeaf4d48eda794b',
+ scriptString: '71 0x304402205bb4f7880fb0fc13218940ba341c30e817363e5590343d28639af921b2a5f1d40220010920ae4b00bbb657f8653cb44172b8cb13447bb5105ddaf32a2845ea0666b901 33 0x025ae98eff89505fa5ff60f919ae690de638d31f4f2fcab9a9deeaf4d48eda794b'
+ }
+ ],
+ outputs: [
+ {
+ satoshis: 4294967000,
+ script: '76a9143ec33076ba72b36b66b7ec571dd7417abdeb76f888ac'
+ }
+ ],
+ nLockTime: 0
+})
+
+storage.updateTransaction(transaction);
+In order to decide which set of input to use for making payments, wallet-lib use the coin selection helper which will decide which unspent transaction output (UTXO) to select.
+There are multiples strategy algorithms provided with Wallet-lib, that you can chose from.
+| Strategy | +Description | +
|---|---|
| simpleDescendingAccumulator | +Will maximize the uses of big inputs to meet the amount required. Allows the fee to be optimized for the smallest size at the cost of breaking big inputs. | +
| simpleAscendingAccumulator | +Will try to use as many small inputs as possible to meet the amount required. Allows using many small inputs at the cost of a potentially bigger fee. | +
By default, the algorithm that is being used is simpleDescendingAccumulator.
See Account.createTransaction() for more information about how to select one during transaction creation.
+Additionally, you can also require the utility function const coinSelection = require('@dashevo/wallet-lib/src/utils/coinSelection.js') for your own usage.
const utxosList = account.getUTXOS();
+const outputsList = [{
+ address:'XmjeE...',
+ satoshis:1200000
+}]
+const coinSelection = coinSelection(utxosList, outputsList);
+const selectedUTXO = coinSelection(utxosList, outputsList);
+By creating a simple function algorithm that you pass to the createTransaction parameter, you can provide your own algorithm that will be used to the coinSelection.
+To implements your own algorithm, you might want to take example on the already existing one.
+You will need your algorithm to handle multiples parameter :
utxosList - An array consisting of multiple unspent output.outputsList - An array consisting of multiple Output.deductFee - A simple boolean that indicates if we want to deduct fee from our outputs. (Can be useful for a control on how much we wish to spend at maximum).feeCategory - A simple enum of the fee category (normal, slow, fast,...).Your algorithm will be required to return the following object structure :
+utxos: An array consisting of the final selection of UTXOs.outputs: An array consisting of the final outputs (which might have been modified in case of deductFee being true).estimatedFee: A duff value of the fee estimated for such transaction.utxosValue: The total accumulated duffs value of the used UTXOs.feeCategoryDAPI (Decentralized API) is a distributed and decentralized endpoints provided by the Masternode Network.
+You can learn more about DAPI on the DAPI-Client documentation.
When the Wallet-lib is initialized without any transporter, Wallet-lib will by default use DAPI-Client as a transporter. +You can fetch the current instance of DAPI directly from the wallet :
+ const wallet = new Wallet();
+ const client = wallet.transport;
+By using your own DAPI-Client instance and passing it to the Wallet constructor (using transport argument). You can specify your own seeds to connect to.
const DAPIClient = require('@dashevo/dapi-client');
+const { Wallet } = require('./src');
+const DAPIClientTransport = require('./src/transport/DAPIClientTransport/DAPIClientTransport.js');
+
+const client = new DAPIClient({
+ seeds: [{ service: '18.236.131.253:3000' }],
+ timeout: 20000,
+ retries: 5,
+});
+const transport = new DAPIClientTransport(client);
+const wallet = new Wallet({ transport });
+const {EVENTS} = require('@dashevo/wallet-lib');
+const {FETCHED_CONFIRMED_TRANSACTION} = EVENTS;
+const doSomethingConfirmedTransactionFetched = (tx) => {...}
+account.on(FETCHED_CONFIRMED_TRANSACTION, doSomethingConfirmedTransactionFetched);
+Events types :
+| Event Name | +Description | +
|---|---|
| CONFIGURED | +throwed when Storage has configured the adapter. | +
| REHYDRATE_STATE_FAILED | +onFailedRehydrateState | +
| REHYDRATE_STATE_SUCCESS | +throwed when Storage has succesfully rehydrated the data | +
| Event Name | +Description | +
|---|---|
| READY | +throwed when ready to be used | +
| Event Name | +Description | +
|---|---|
| BLOCKHEIGHT_CHANGED | +When the chain has moved from one block forward | +
| FETCHED_UNCONFIRMED_TRANSACTION | +When we got to fetch an unconfirmed transaction, we throw this event | +
| FETCHED_CONFIRMED_TRANSACTION | +This one is if the transaction is confirmed | +
| FETCHED_TRANSACTIONS | +In both case, we throw that event | +
| Event Name | +Description | +
|---|---|
| UNCONFIRMED_BALANCE_CHANGED | +When unconfirmed balance change, we gives the delta + totalValue | +
| BALANCE_CHANGED | +When the balance change, we gives the delta + totalValue | +
The wallet can handle a lack of connectivity. This could allow the use of the wallet library in an offline way.
+Such uses case would be to generate a bunch of addresses that you could manually import into a database (for rolling incoming addresses)
You also have ways to import a known address, transaction, account or any type of data that you could wish to have via the network, +thus allowing you to use the wallet-library without connectivity.
+See here sample code
+See here sample code
+Usage: calculateTransactionFees(transaction)
+Description: Return for a transaction, the fee value that were used
+Notes: To calculate the fee, provided transaction's input require output knowledge to be supplied
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| transaction | +Transaction | +yes | +A transaction instance | +
Returns : {number} - fee value used for this transaction
+ + + + + + + + + + + + + +Usage: categorizeTransactions()
+Description: Return for a transaction, the fee value that were used
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| transactionsWithMetadata | +[TransactionMetadata] | +yes | +Transaction with their metadata | +
| accountStore | +Object | +yes | +Account store with addresses | +
| accountIndex | +Number | +yes | +The account index | +
| walletType | +WALLET_TYPES | +yes | +The wallet type | +
| network | +Network/String | +no (def: testnet) | +Wallet network | +
Returns : {[CategorizedTransaction]} - Array of categorized transactions
+const categorizedTransactions = categorizeTransaction(transactionsWithMetadata, accountstore, 0, WALLET_TYPES.HDWALLET);
+[{
+ transaction: Transaction(),
+ type: 'received',
+ from: [{}],
+ to: [{}],
+ blockHash: '00001'
+ height: 42,
+ isInstantLocked: true,
+ isChainLocked: true
+}]
+Usage: classifyAddresses(addressStore, accountIndex, walletType)
+Description: Return for an addressStore, accountIndex and wallet type, the array classified set of addresses
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| addressStore | +Object | +yes | +Account store with addresses | +
| accountIndex | +Number | +yes | +The account index | +
| walletType | +WALLET_TYPES | +yes | +The wallet type | +
Returns : {[ClassifiedAddresses]} - Array of classified addresses
+const classifiedAddresses = classifyAddresses(addressStore, 0, WALLET_TYPES.HDWALLET);
+
+{
+ externalAddressList: [
+ 'yd1ohc12LgCYp56CDuckTEHwoa6LbPghMd',
+ '...'
+ ],
+ internalAddressList: [
+ 'yaLhoAZ4iex2zKmfvS9rvEmxXmRiPrjHdD',
+ '...'
+ ],
+ otherAccountAddressList: []
+};
+Usage: coinSelection(utxosList, outputsList, deductFee, feeCategory, strategy)
+Description: For a provided outputsList will select the best utxos from utxosList matching the fees and strategy requirements
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| utxosList | +[UTXO] | +yes | +Account store with addresses | +
| outputsList | +[Output] | +yes | +The account index | +
| deductFee | +Boolean | +no (def: false) | +The wallet type | +
| feeCategory | +FeeCategory | +no (def: normal) | +The wallet type | +
| strategy | +Strategy | +no (def: simpleDescendingAccumulator) | +The wallet type | +
Returns : {[ClassifiedAddresses]} - Array of classified addresses
+coinSelection(utxosList, outputsList, true);
+
+{
+ utxos,
+ outputs,
+ feeCategory,
+ estimatedFee,
+ utxosValue,
+ }
+Usage: dashToDuffs(dash)
+Description: For a dash value, returns value in duffs
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| dash | +Number | +yes | +Value input in dash | +
Returns : {Number} - Value in duffs (satoshis)
+dashToDuffs(1); //returns 100000000
+Usage: duffsToDash(duffs)
+Description: For a duff value, returns value in Dash
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| duffs | +Number | +yes | +Value input in duff | +
Returns : {Number} - Value in dash
+duffsToDash(100000000); //returns 1
+Usage: extendTransactionsWithMetadata(addressStore, accountIndex, walletType)
+Description: Return for an addressStore, accountIndex and wallet type, the array classified set of addresses
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| addressStore | +Object | +yes | +Account store with addresses | +
| accountIndex | +Number | +yes | +The account index | +
| walletType | +WALLET_TYPES | +yes | +The wallet type | +
Returns : {[TransactionsWithMetadata]} - Array of transactions with metadata addresses
+extendTransactionsWithMetadata(transactions, transactionsMetadata);
+[
+ [
+ Transaction,
+ {
+ blockHash: '0000012cf6377c6cf2b317a4deed46573c09f04f6880dca731cc9ccea6691e19',
+ height: 555508,
+ instantLocked: true,
+ chainLocked: true
+ }
+ ]
+];
+Usage: filterTransactions(accountStore, walletType, accountIndex, transactions)
+Description:
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| addressStore | +Object | +yes | +Account store with addresses | +
| accountIndex | +Number | +yes | +The account index | +
| walletType | +WALLET_TYPES | +yes | +The wallet type | +
Returns : {[Transaction]} - Array of transaction filtered
+filterTransactions(accountStore, walletType, accountIndex, transactions);
+[Transaction,...];
+Usage: getBytesOf(value, type)
+Description: For a provided type and value, returns the bytes value of it
+Notes: Used for transaction size calculation for fee estimation
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| value | +Output/UTXO | +yes | +Value input in dash | +
| type | +Output/UTXO | +yes | +Value input in dash | +
Returns : {Number} - Bytes value
+ + + + + + + + + + + + + +Usage: generateNewMnemonic()
+Description: Generate a new random mnemonic
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| + | + | + | + |
Returns : {Mnemonic}
+ + + + + + + + + + + + + +Usage: mnemonicToHDPrivateKey(mnemonic)
+Description:
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| mnemonic | +Mnemonic | +yes | +A mnemonic | +
Returns : {HDPrivateKey}
+ + + + + + + + + + + + + +Usage: mnemonicToSeed(mnemonic, password)
+Description: Generate the seed from mnemonic
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| mnemonic | +Mnemonic | +yes | +A mnemonic | +
| password | +string | +no | ++ |
Returns : {String} hex seed
+ + + + + + + + + + + + + +Usage: mnemonicToWalletId(mnemonic)
+Description: Generate the deterministic wallet id based on mnemonic
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| mnemonic | +Mnemonic | +yes | +A mnemonic | +
Returns : {String} hex wallet id
+ + + + + + + + + + + + + +Usage: seedToHDPrivateKey(seed)
+Description:
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| seed | +Mnemonic | +yes | +A mnemonic | +
Returns : {HDPrivateKey}
+ + + + + + + + + + + + + +Usage: new Wallet(walletOpts)
+Description: This method creates a new Wallet.
+In Wallet-Lib, a Wallet is a manager that is tied to a passphrase/seed or privateKey and manage one or multiples Account from that.
+It's purpose is mainly to create or get an account, allowing multiple account to be tracked and tied from a single manager.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| walletOpts.network | +string/Network | +no (def:'testnet') | +Use either a string reference to Networks ('livenet', 'testnet') or it's Networks representation | +
| walletOpts.mnemonic | +string/Mnemonic | +no | +If sets at null, generate a new mnemonic. If sets to a valid value, create wallet from mnemonic | +
| walletOpts.passphrase | +string | +no | +If sets at null, generate a new privateKey. It sets to a valid privateKey, uses it (with the passphrase if provided) to unlock the seed | +
| walletOpts.offlineMode | +boolean | +no (def: false) | +Set to true to not perform any request to the network | +
| walletOpts.injectDefaultPlugins | +boolean | +no (def: true) | +Use to inject default plugins on loadup (BIP44Worker, ChainWorker and SyncWorker) | +
| walletOpts.allowSensitiveOperations | +boolean | +no (def: false) | +If you want a special plugin to access the keychain or other sensitive operation, set this to true. | +
| walletOpts.cache.addresses | +object | +no | +If you have your cache state somewhere else (fs) you can fetch and pass it along for faster sync-up | +
| walletOpts.cache.transactions | +object | +no | +If you have your cache state somewhere else (fs) you can fetch and pass it along for faster sync-up | +
| walletOpts.plugins | +Array | +no | +It you have some plugins, worker you want to pass to wallet-lib. You can pass them as constructor or initialized object | +
| walletOpts.seed | +string | +no | +If you only have a seed representation, you can pass it instead of mnemonic to init the wallet from it | +
| walletOpts.HDPrivateKey | +string/HDPrivateKey | +no | +If you only have a HDPrivateKey representation, you can pass it instead of mnemonic to init the wallet from it | +
| walletOpts.HDPublicKey | +string/HDPublicKey | +no | +If you only have a HDPublicKey representation, you can pass it instead of mnemonic to init the wallet from it | +
| walletOpts.privateKey | +string/PrivateKey | +no | +If you only have a PrivateKey representation, you can pass it instead of mnemonic to init the wallet from it | +
| walletOpts.publicKey | +string/PublicKey | +no | +If you only have a PublicKey representation, you can pass it instead of mnemonic to init the wallet from it | +
N.B 1 : If both mnemonic, seed and privateKey are filled, only mnemonic will be used. If none is entered, the wallet will create a mnemonic.
+N.B 2 : When initialized from a privateKey, publicKey or an HDPublicKey, comportment of Wallet-lib differs slightly.
Returns : Wallet instance.
+Examples :
+const wallet = new Wallet();
+or
+const wallet = new Wallet({
+ mnemonic: null
+});
+console.log(wallet.exportWallet());
+In the case where you will want to have stronger entropy (have 24 words generated instead of 12), this snippet will allow to do that :
+const { Mnemonic } = require('@dashevo/dashcore-lib');
+const mnemonic = new Mnemonic(256).toString();
+const wallet = new Wallet({
+ mnemonic: 'hole lesson insane entire dolphin scissors game dwarf polar ethics drip math'
+})
+const wallet = new Wallet({
+ HDPrivateKey: 'tprv8ZgxMBicQKsPeWisxgPVWiXho8ozsAUqc3uvpAhBuoGvSTxqkxPZbTeG43mvgXn3iNfL3cBL1NmR4DaVoDBPMUXe1xeiLoc39jU9gRTVBd2'
+})
+const wallet = new Wallet({
+ HDPublicKey: 'tpubDEB6BgW9JvZRWVbFmwwGuJ2vifakABuxQWdY9yXbFC2rc3zagie1RkhwUEnahb1dzaapchEVeKqKcx99TzkjNvjXcmoQkLJwsYnA1J5bGNj'
+})
+const wallet = new Wallet({
+ seed: '436905e6756c24551bffaebe97d0ebd51b2fa027e838c18d45767bd833b02a80a1dd55728635b54f2b1dbed5963f4155e160ee1e96e2d67f7e8ac28557d87d96'
+})
+const wallet = new Wallet({
+ privateKey: 'cR4t6evwVZoCp1JsLk4wURK4UmBCZzZotNzn9T1mhBT19SH9JtNt'
+})
+const wallet = new Wallet({
+ HDPublicKey: 'tpubDEB6BgW9JvZRWVbFmwwGuJ2vifakABuxQWdY9yXbFC2rc3zagie1RkhwUEnahb1dzaapchEVeKqKcx99TzkjNvjXcmoQkLJwsYnA1J5bGNj'
+})
+Usage: await wallet.createAccount(accountOpts)
+Description: This method, equivalent of a new Account(wallet, accountOpts) will create a new account having the specified options.
Parameters:
+See the Account constructor parameters.
N.B : You also probably mean to use .getAccount() instead. This is designed mostly to be Private as get an account deal with it.
Returns : void.
+ + + + + + + + + + + + + +Usage: wallet.disconnect()
+Description: This method will disconnect all accounts, plugins and other workers (Storage). Useful to release all worker when doing integration testing with Wallet/Account
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| + | + | + | + |
Returns : void.
+ + + + + + + + + + + + + +Usage: wallet.dumpStorage([opts])
+Description: Method dumps the state of the storage in JSON format
Warning: Storage dump may contain sensitive data.
+Please, do not share the output of this function for mainnet wallets.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| opts.log | +Boolean | +no | +Indicates whether storage should be logged in the console | +
Returns : {String}
+ + + + + + + + + + + + + +Usage: wallet.exportWallet([outputType])
+Description: This method will export the wallet to the default outputType (depending on initializated params : mnemonic. HDPubKey,...).
This method varies depending from which type of wallet is this. +- When init from a mnemonic, by default return mnemonic but support 'HDPrivateKey' +- When init from a seed, by default returns and only support HDPrivateKey +- When init from a private key, by default returns and only support PrivateKey.
+Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| outputType | +String | +no | +The required output type of the exported wallet | +
Returns : {Mnemonic|HDPrivateKey|HDPublicKey|PrivateKey}
+ + + + + + + + + + + + + +Usage: wallet.fromHDPrivateKey(HDPrivateKey)
+Description: Initialize a Wallet from a HDPrivateKey representation.
+Notes: This is an internal method, in the future, when TC39 proposal pass, we will use the private markup.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| HDPrivateKey | +HDPrivateKey | +String | +yes | +
Returns : void (set a HD Wallet).
+Examples :
+wallet.fromHDPrivateKey('xprv9s21ZrQH143K37d2j9YW7snYGbAJJX9vzEZRwU7QEc4yP39t1Yc7t2Aw79aBBQWfLNqnpo9bFRnWoDv7xCPyBpLFHZvvrtVYfRv2zEBtnT5')
+Usage: wallet.fromHDPublicKey(HDPublicKey)
+Description: Initialize a Wallet from a HDPublicKey representation.
+Notes: This is an internal method, in the future, when TC39 proposal pass, we will use the private markup.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| HDPublicKey | +HDPublicKey | +String | +yes | +
Returns : void (set a HD Wallet in watch mode).
+Examples :
+wallet.fromHDPrivateKey('tpubDEB6BgW9JvZRWVbFmwwGuJ2vifakABuxQWdY9yXbFC2rc3zagie1RkhwUEnahb1dzaapchEVeKqKcx99TzkjNvjXcmoQkLJwsYnA1J5bGNj')
+Usage: wallet.fromMnemonic(mnemonic)
+Description: Initialize a Wallet from a Mnemonic representation.
+Notes: This is an internal method, in the future, when TC39 proposal pass, we will use the private markup. Mnemonic initialized wallet works a little differently as they store the mnemonic in the wallet object.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| mnemonic | +Mnemonic | +String | +yes | +
Returns : void (set a HD Wallet).
+Examples :
+wallet.fromMnemonic('knife easily prosper input concert merge prepare autumn pen blood glance toilet')
+Usage: wallet.fromPrivateKey(privateKey)
+Description: Initialize a Wallet from a PrivateKey representation.
+Notes: This is an internal method, in the future, when TC39 proposal pass, we will use the private markup.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| PrivateKey | +PrivateKey | +String | +yes | +
Returns : void (set a single address wallet).
+Examples :
+wallet.fromPrivateKey('cR4t6evwVZoCp1JsLk4wURK4UmBCZzZotNzn9T1mhBT19SH9JtNt')
+Usage: wallet.fromSeed(seed)
+Description: Initialize a Wallet from a seed.
+Notes: This is an internal method, in the future, when TC39 proposal pass, we will use the private markup.
+Notes 2: This actually transform seed in HDPrivateKey and uses wallet.fromHDPrivateKey().
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| seed | +String | +yes | +The seed from which you want to initialize the wallet. | +
Returns : void (set a HD wallet).
+Examples :
+wallet.fromSeed('9e55e5cb0e2fe273600cf5af7d7760fe569121c320395f0233202b97445e54f577d5a706c49aa1f3f0993d2ff97e2e6d63e4ccd0b7e9d4c4f115ae58957a9114')
+Usage: wallet.generateNewWalletId()
+Description: Internally, each wallet has a WalletId attached. This tries to be deterministic by actually just be a substring of a double sha256 hash from the input.
+Notes: This is an internal method, in the future, when TC39 proposal pass, we will use the private markup. Also, mutates Wallet.walletId.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| + | + | + | + |
Returns : String (wallet.walletId).
+ + + + + + + + + + + + + +Usage: await wallet.getAccount([opts])
+Description: This method will get you the account specified by it's index.
Parameters:
+| parameters | +type | +required | +Description | +
|---|---|---|---|
| opts.index | +number | +no (default: 0) | +The BIP44 index | +
Returns : Account.
+N.B: When getAccount is called on a never initialized account, you can pass-it any of Account options, and the wallet will initiate it (.createAccount) for you with those passed params and returns you the account.