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 AliasQueryParameter s. |
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 NftQueryParameter s. |
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 FoundryQueryParameter s. |
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 BlockId s. |
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.