Class: Client
The Client to interact with nodes.
Table of contents
Constructors
Methods
- destroy
- getInfo
- getNetworkInfo
- basicOutputIds
- getOutput
- getOutputs
- buildAndPostBlock
- getTips
- postBlock
- getBlock
- getBlockMetadata
- findInputs
- prepareTransaction
- signTransaction
- signatureUnlock
- postBlockPayload
- getNode
- getNetworkId
- getBech32Hrp
- getMinPowScore
- getTipsInterval
- getTokenSupply
- getProtocolParameters
- getLocalPow
- getFallbackToLocalPow
- getHealth
- getNodeInfo
- getPeers
- postBlockRaw
- getBlockRaw
- getMilestoneById
- getUtxoChangesById
- getMilestoneByIndex
- getUtxoChangesByIndex
- getReceipts
- getReceiptsMigratedAt
- getTreasury
- getIncludedBlock
- getIncludedBlockMetadata
- hexToBech32
- aliasIdToBech32
- nftIdToBech32
- hexPublicKeyToBech32Address
- aliasOutputIds
- aliasOutputId
- nftOutputIds
- nftOutputId
- foundryOutputIds
- foundryOutputId
- getOutputsIgnoreErrors
- findBlocks
- retry
- retryUntilIncluded
- consolidateFunds
- reattach
- reattachUnchecked
- promote
- promoteUnchecked
- unhealthyNodes
- buildBasicOutput
- buildAliasOutput
- buildFoundryOutput
- buildNftOutput
- listenMqtt
- clearMqttListeners
- minimumRequiredStorageDeposit
- requestFundsFromFaucet
- callPluginRoute
Constructors
constructor
• new Client(options)
Parameters
| Name | Type | Description |
|---|---|---|
options | ClientMethodHandler | IClientOptions | client options or a client method handler. |
Methods
destroy
▸ destroy(): Promise<any>
Returns
Promise<any>
getInfo
▸ getInfo(): Promise<INodeInfoWrapper>
Get the node information together with the url of the used node.
Returns
Promise<INodeInfoWrapper>
getNetworkInfo
▸ getNetworkInfo(): Promise<INetworkInfo>
Get network related information such as protocol parameters and minimum pow score.
Returns
Promise<INetworkInfo>
basicOutputIds
▸ basicOutputIds(queryParameters): Promise<IOutputsResponse>
Fetch basic output IDs based on the given query parameters.
Parameters
| Name | Type |
|---|---|
queryParameters | QueryParameter[] |
Returns
Promise<IOutputsResponse>
getOutput
▸ getOutput(outputId): Promise<OutputResponse>
Get output from a given output ID.
Parameters
| Name | Type |
|---|---|
outputId | string |
Returns
Promise<OutputResponse>
getOutputs
▸ getOutputs(outputIds): Promise<OutputResponse[]>
Fetch OutputResponse from given output IDs. Requests are sent in parallel.
Parameters
| Name | Type |
|---|---|
outputIds | string[] |
Returns
Promise<OutputResponse[]>
buildAndPostBlock
▸ buildAndPostBlock(secretManager?, options?): Promise<[string, Block]>
Build and post a block.
Parameters
| Name | Type | Description |
|---|---|---|
secretManager? | SecretManagerType | One of the supported secret managers. |
options? | IBuildBlockOptions | Options on how to build a block. |
Returns
Promise<[string, Block]>
The block ID and the posted block itself.
getTips
▸ getTips(): Promise<string[]>
Request tips from the node. The tips can be considered as non-lazy and are therefore ideal for attaching a block to the Tangle.
Returns
Promise<string[]>
An array of tips represented by their block IDs.
postBlock
▸ postBlock(block): Promise<string>
Post a block in JSON format.
Parameters
| Name | Type | Description |
|---|---|---|
block | Block | The block to post. |
Returns
Promise<string>
The block ID once the block has been posted.
getBlock
▸ getBlock(blockId): Promise<Block>
Get a block in JSON format.
Parameters
| Name | Type | Description |
|---|---|---|
blockId | string | The corresponding block ID of the requested block. |
Returns
Promise<Block>
The requested block.
getBlockMetadata
▸ getBlockMetadata(blockId): Promise<IBlockMetadata>
Get the metadata of a block.
Parameters
| Name | Type | Description |
|---|---|---|
blockId | string | The corresponding block ID of the requested block metadata. |
Returns
Promise<IBlockMetadata>
The requested block metadata.
findInputs
▸ findInputs(addresses, amount): Promise<UTXOInput[]>
Find inputs from addresses for a given amount (useful for offline signing).
Parameters
| Name | Type | Description |
|---|---|---|
addresses | string[] | A list of included addresses. |
amount | bigint | The amount to find inputs for. |
Returns
Promise<UTXOInput[]>
An array of UTXO inputs.
prepareTransaction
▸ prepareTransaction(secretManager?, options?): Promise<PreparedTransactionData>
Prepare a transaction for signing.
Parameters
| Name | Type | Description |
|---|---|---|
secretManager? | SecretManagerType | One of the supported secret managers. |
options? | IBuildBlockOptions | Options to build a block. |
Returns
Promise<PreparedTransactionData>
An instance of PreparedTransactionData.
signTransaction
▸ signTransaction(secretManager, preparedTransactionData): Promise<TransactionPayload>
Sign a transaction.
Parameters
| Name | Type | Description |
|---|---|---|
secretManager | SecretManagerType | One of the supported secret managers. |
preparedTransactionData | PreparedTransactionData | An instance of PreparedTransactionData. |
Returns
Promise<TransactionPayload>
The corresponding transaction payload.
signatureUnlock
▸ signatureUnlock(secretManager, transactionEssenceHash, chain): Promise<UnlockCondition>
Create a signature unlock using the given secret manager.
Parameters
| Name | Type | Description |
|---|---|---|
secretManager | SecretManagerType | One of the supported secret managers. |
transactionEssenceHash | string | The hash of the transaction essence. |
chain | Bip44 | A BIP44 chain |
Returns
Promise<UnlockCondition>
The corresponding unlock condition.
postBlockPayload
▸ postBlockPayload(payload): Promise<[string, Block]>
Submit a payload in a block.
Parameters
| Name | Type | Description |
|---|---|---|
payload | Payload | The payload to post. |
Returns
Promise<[string, Block]>
The block ID followed by the block containing the payload.
getNode
▸ getNode(): Promise<INode>
Get a node candidate from the healthy node pool.
Returns
Promise<INode>
getNetworkId
▸ getNetworkId(): Promise<string>
Get the ID of the network the node is connected to.
Returns
Promise<string>
getBech32Hrp
▸ getBech32Hrp(): Promise<string>
Get the Bech32 HRP (human readable part) of the network the node is connected to.
Returns
Promise<string>
getMinPowScore
▸ getMinPowScore(): Promise<number>
Get the minimum PoW score.
Returns
Promise<number>
getTipsInterval
▸ getTipsInterval(): Promise<number>
Get the tips interval.
Returns
Promise<number>
getTokenSupply
▸ getTokenSupply(): Promise<string>
Get the token supply.
Returns
Promise<string>
getProtocolParameters
▸ getProtocolParameters(): Promise<INodeInfoProtocol>
Get the protocol parameters.
Returns
Promise<INodeInfoProtocol>
getLocalPow
▸ getLocalPow(): Promise<boolean>
Check whether local pow should be used or not.
Returns
Promise<boolean>
getFallbackToLocalPow
▸ getFallbackToLocalPow(): Promise<boolean>
Check whether to fallback to local proof of work in case the node doesn't support remote PoW.
Returns
Promise<boolean>
getHealth
▸ getHealth(url): Promise<boolean>
Get the health of a node.
Parameters
| Name | Type | Description |
|---|---|---|
url | string | The URL of the node. |
Returns
Promise<boolean>
getNodeInfo
▸ getNodeInfo(url, auth?): Promise<INodeInfo>
Get the info about the node.
Parameters
| Name | Type | Description |
|---|---|---|
url | string | The URL of the node. |
auth? | IAuth | An authentication object (e.g. JWT). |
Returns
Promise<INodeInfo>
getPeers
▸ getPeers(): Promise<IPeer[]>
Get the peers of the node.
Returns
Promise<IPeer[]>
postBlockRaw
▸ postBlockRaw(block): Promise<string>
Post block as raw bytes, returns the block ID.
Parameters
| Name | Type | Description |
|---|---|---|
block | Block | The block. |
Returns
Promise<string>
The ID of the posted block.
getBlockRaw
▸ getBlockRaw(blockId): Promise<Uint8Array>
Get block as raw bytes.
Parameters
| Name | Type | Description |
|---|---|---|
blockId | string | The block ID of the requested block. |
Returns
Promise<Uint8Array>
The raw bytes of the requested block.
getMilestoneById
▸ getMilestoneById(milestoneId): Promise<MilestonePayload>
Get a milestone payload by its ID.
Parameters
| Name | Type | Description |
|---|---|---|
milestoneId | string | The ID of the requested milestone. |
Returns
Promise<MilestonePayload>
The corresponding milestone payload.
getUtxoChangesById
▸ getUtxoChangesById(milestoneId): Promise<IMilestoneUtxoChangesResponse>
Get all UTXO changes of a milestone by its ID.
Parameters
| Name | Type | Description |
|---|---|---|
milestoneId | string | The ID of the milestone that applied the UTXO changes. |
Returns
Promise<IMilestoneUtxoChangesResponse>
A milestone UTXO changes response.
getMilestoneByIndex
▸ getMilestoneByIndex(index): Promise<MilestonePayload>
Get a milestone payload by its index.
Parameters
| Name | Type | Description |
|---|---|---|
index | number | The index of the requested milestone. |
Returns
Promise<MilestonePayload>
The corresponding milestone payload.
getUtxoChangesByIndex
▸ getUtxoChangesByIndex(index): Promise<IMilestoneUtxoChangesResponse>
Get all UTXO changes of a milestone by its index.
Parameters
| Name | Type | Description |
|---|---|---|
index | number | The index of the milestone that applied the UTXO changes. |
Returns
Promise<IMilestoneUtxoChangesResponse>
A milestone UTXO changes response.
getReceipts
▸ getReceipts(): Promise<ReceiptsResponse>
Get all receipts.
Returns
Promise<ReceiptsResponse>
getReceiptsMigratedAt
▸ getReceiptsMigratedAt(milestoneIndex): Promise<ReceiptsResponse[]>
Get the receipts at a given milestone index.
Parameters
| Name | Type | Description |
|---|---|---|
milestoneIndex | number | The index of the milestone that migrated funds to the new network. |
Returns
Promise<ReceiptsResponse[]>
getTreasury
▸ getTreasury(): Promise<TreasuryOutput>
Get the treasury output.
Returns
Promise<TreasuryOutput>
getIncludedBlock
▸ getIncludedBlock(transactionId): Promise<Block>
Get the included block of a given transaction.
Parameters
| Name | Type | Description |
|---|---|---|
transactionId | string | The ID of the transaction. |
Returns
Promise<Block>
The included block that contained the transaction.
getIncludedBlockMetadata
▸ getIncludedBlockMetadata(transactionId): Promise<Block>
Get the metadata of the included block of a given transaction.
Parameters
| Name | Type | Description |
|---|---|---|
transactionId | string | The ID of the transaction. |
Returns
Promise<Block>
The included block that contained the transaction.
hexToBech32
▸ hexToBech32(hex, bech32Hrp?): Promise<string>
Convert a hex encoded address to a Bech32 encoded address.
Parameters
| Name | Type | Description |
|---|---|---|
hex | string | The hexadecimal string representation of an address. |
bech32Hrp? | string | The Bech32 HRP (human readable part) to be used. |
Returns
Promise<string>
The corresponding Bech32 address.
aliasIdToBech32
▸ aliasIdToBech32(aliasId, bech32Hrp?): Promise<string>
Convert an Alias ID to a Bech32 encoded address.
Parameters
| Name | Type | Description |
|---|---|---|
aliasId | string | An Alias ID. |
bech32Hrp? | string | The Bech32 HRP (human readable part) to be used. |
Returns
Promise<string>
The corresponding Bech32 address.
nftIdToBech32
▸ nftIdToBech32(nftId, bech32Hrp?): Promise<string>
Convert an NFT ID to a Bech32 encoded address.
Parameters
| Name | Type | Description |
|---|---|---|
nftId | string | An NFT ID. |
bech32Hrp? | string | The Bech32 HRP (human readable part) to be used. |
Returns
Promise<string>
The corresponding Bech32 address.
hexPublicKeyToBech32Address
▸ hexPublicKeyToBech32Address(hex, bech32Hrp?): Promise<string>
Convert a hex encoded public key to a Bech32 encoded address.
Parameters
| Name | Type | Description |
|---|---|---|
hex | string | The hexadecimal string representation of a public key. |
bech32Hrp? | string | The Bech32 HRP (human readable part) to be used. |
Returns
Promise<string>
The corresponding Bech32 address.
aliasOutputIds
▸ aliasOutputIds(queryParameters): Promise<IOutputsResponse>
Get the corresponding output IDs given a list of Alias query parameters.
Parameters
| Name | Type | Description |
|---|---|---|
queryParameters | AliasQueryParameter[] | An array of AliasQueryParameters. |
Returns
Promise<IOutputsResponse>
A paginated query response of corresponding output IDs.
aliasOutputId
▸ aliasOutputId(aliasId): Promise<string>
Get the corresponding output ID from an Alias ID.
Parameters
| Name | Type | Description |
|---|---|---|
aliasId | string | An Alias ID. |
Returns
Promise<string>
The corresponding output ID.
nftOutputIds
▸ nftOutputIds(queryParameters): Promise<IOutputsResponse>
Get the corresponding output IDs given a list of NFT query parameters.
Parameters
| Name | Type | Description |
|---|---|---|
queryParameters | NftQueryParameter[] | An array of NftQueryParameters. |
Returns
Promise<IOutputsResponse>
A paginated query response of corresponding output IDs.
nftOutputId
▸ nftOutputId(nftId): Promise<string>
Get the corresponding output ID from an NFT ID.
Parameters
| Name | Type | Description |
|---|---|---|
nftId | string | An NFT ID. |
Returns
Promise<string>
The corresponding output ID.
foundryOutputIds
▸ foundryOutputIds(queryParameters): Promise<IOutputsResponse>
Get the corresponding output IDs given a list of Foundry query parameters.
Parameters
| Name | Type | Description |
|---|---|---|
queryParameters | FoundryQueryParameter[] | An array of FoundryQueryParameters. |
Returns
Promise<IOutputsResponse>
A paginated query response of corresponding output IDs.
foundryOutputId
▸ foundryOutputId(foundryId): Promise<string>
Get the corresponding output ID from a Foundry ID.
Parameters
| Name | Type | Description |
|---|---|---|
foundryId | string | A Foundry ID. |
Returns
Promise<string>
The corresponding output ID.
getOutputsIgnoreErrors
▸ getOutputsIgnoreErrors(outputIds): Promise<OutputResponse[]>
Get outputs from provided output IDs (requests are sent in parallel and errors are ignored, can be useful for spent outputs)
Parameters
| Name | Type | Description |
|---|---|---|
outputIds | string[] | An array of output IDs. |
Returns
Promise<OutputResponse[]>
An array of corresponding output responses.
findBlocks
▸ findBlocks(blockIds): Promise<Block[]>
Find blocks by their IDs.
Parameters
| Name | Type | Description |
|---|---|---|
blockIds | string[] | An array of BlockIds. |
Returns
Promise<Block[]>
An array of corresponding blocks.
retry
▸ retry(blockId): Promise<[string, Block]>
Retry (promote or reattach) a block given its block ID.
Note: Blocks should be retried only if they are valid and haven't been confirmed for some time.
Parameters
| Name | Type | Description |
|---|---|---|
blockId | string | The ID of the block to retry. |
Returns
Promise<[string, Block]>
The included block.
retryUntilIncluded
▸ retryUntilIncluded(blockId, interval?, maxAttempts?): Promise<[string, Block][]>
Retry (promote or reattach) a block given its block ID until it's included (i.e. referenced by a milestone).
Parameters
| Name | Type | Description |
|---|---|---|
blockId | string | The ID of the block to retry. |
interval? | number | A retry interval in seconds. Defaults to 5. |
maxAttempts? | number | A maximum number of retries. Defaults to 40. |
Returns
Promise<[string, Block][]>
The included block at first position and additional reattached blocks.
consolidateFunds
▸ consolidateFunds(secretManager, generateAddressesOptions): Promise<string>
Consolidate all funds from a range of addresses to the address with the lowest index in that range.
Parameters
| Name | Type | Description |
|---|---|---|
secretManager | SecretManagerType | One of supported secret managers. |
generateAddressesOptions | IGenerateAddressesOptions | Options for generating addresses. |
Returns
Promise<string>
The address to which the funds got consolidated, if any were available.
reattach
▸ reattach(blockId): Promise<[string, Block]>
Reattach a block.
Note: Blocks can be reattached only if they are valid and haven't been confirmed for some time.
Parameters
| Name | Type | Description |
|---|---|---|
blockId | string | The ID of the block to reattach. |
Returns
Promise<[string, Block]>
The included block.
reattachUnchecked
▸ reattachUnchecked(blockId): Promise<[string, Block]>
Reattach a block without checking whether it should be reattached.
Parameters
| Name | Type | Description |
|---|---|---|
blockId | string | The ID of the block to reattach. |
Returns
Promise<[string, Block]>
The included block.
promote
▸ promote(blockId): Promise<[string, Block]>
Promote a block.
NOTE: The method validates whether a promotion is necessary through get_block. If not, the
method will error out and will not do unnecessary promotions.
Parameters
| Name | Type | Description |
|---|---|---|
blockId | string | The ID of the block to promote. |
Returns
Promise<[string, Block]>
The included block.
promoteUnchecked
▸ promoteUnchecked(blockId): Promise<[string, Block]>
Promote a block without checking if it should be promoted.
Parameters
| Name | Type | Description |
|---|---|---|
blockId | string | The ID of the block to promote. |
Returns
Promise<[string, Block]>
The included block.
unhealthyNodes
▸ unhealthyNodes(): Promise<Set<INode>>
Return the unhealthy nodes.
Returns
Promise<Set<INode>>
buildBasicOutput
▸ buildBasicOutput(params): Promise<BasicOutput>
Build a basic output.
Parameters
| Name | Type | Description |
|---|---|---|
params | BasicOutputBuilderParams | An instance of BasicOutputBuilderParams. |
Returns
Promise<BasicOutput>
buildAliasOutput
▸ buildAliasOutput(params): Promise<AliasOutput>
Build an alias output.
Parameters
| Name | Type | Description |
|---|---|---|
params | AliasOutputBuilderParams | An instance of AliasOutputBuilderParams. |
Returns
Promise<AliasOutput>
buildFoundryOutput
▸ buildFoundryOutput(params): Promise<FoundryOutput>
Build a foundry output.
Parameters
| Name | Type | Description |
|---|---|---|
params | FoundryOutputBuilderParams | An instance of FoundryOutputBuilderParams. |
Returns
Promise<FoundryOutput>
buildNftOutput
▸ buildNftOutput(params): Promise<NftOutput>
Build an NFT output.
Parameters
| Name | Type | Description |
|---|---|---|
params | NftOutputBuilderParams | An instance of NftOutputBuilderParams. |
Returns
Promise<NftOutput>
listenMqtt
▸ listenMqtt(topics, callback): Promise<void>
Listen to MQTT events.
Parameters
| Name | Type | Description |
|---|---|---|
topics | string[] | An array of MQTT topics to listen to. |
callback | (error: Error, result: string) => void | - |
Returns
Promise<void>
clearMqttListeners
▸ clearMqttListeners(topics): Promise<void>
Stop listening to certain MQTT events.
Parameters
| Name | Type | Description |
|---|---|---|
topics | string[] | An array of MQTT topics to stop listening to. |
Returns
Promise<void>
minimumRequiredStorageDeposit
▸ minimumRequiredStorageDeposit(output): Promise<number>
Calculate the minimum required storage deposit for an output.
Parameters
| Name | Type | Description |
|---|---|---|
output | Output | The output to calculate the minimum deposit amount for. |
Returns
Promise<number>
The minimum required amount.
requestFundsFromFaucet
▸ requestFundsFromFaucet(url, address): Promise<string>
Request funds from a faucet.
Example URLs: https://faucet.testnet.shimmer.network/api/enqueue or http://localhost:8091/api/enqueue.
Parameters
| Name | Type | Description |
|---|---|---|
url | string | The URL of the faucet. |
address | string | The address to send the funds to. |
Returns
Promise<string>
The faucet response.
callPluginRoute
▸ callPluginRoute(basePluginPath, method, endpoint, queryParams?, request?): Promise<string>
Extension method which provides request methods for plugins.
Parameters
| Name | Type | Description |
|---|---|---|
basePluginPath | string | The base path for the plugin eg indexer/v1/ . |
method | "GET" | "POST" | The http method. |
endpoint | string | The path for the plugin request. |
queryParams? | string[] | Additional query params for the request. |
request? | string | The request object. |
Returns
Promise<string>
The response json.