A fully typed Nimiq RPC client for every javascript runtime.
deno:
deno add jsr:@blouflash/nimiq-rpc
npm:
npx jsr add @blouflash/nimiq-rpc
pnpm:
pnpm dlx jsr add @blouflash/nimiq-rpc
It is structured the same way as the Rust RPC Client
import { NimiqRPCClient } from '@blouflash/nimiq-rpc' const client = new NimiqRPCClient(); // async/await based example http call try { const result = await client.blockchain.getEpochNumber(); console.log("Result:", result); } catch (error) { if (error instanceof JSONRPCError) { console.error("JSON-RPC Error:", error); } else { console.error("An unknown error occurred:", error); } } // Promise based example http call client.blockchain.getBlockNumber().then((result) => { console.log("Result:", result); }).catch((error) => { if (error instanceof JSONRPCError) { console.error("JSON-RPC Error:", error); } else { console.error("An unknown error occurred:", error); } }); // async/await based example ws stream call const subscribtion = await client.blockchainStreams.subscribeForBlockHashes( { onMessage: (result) => { console.log("onMessage", result); }, onError: (error) => { console.error("onError", error); }, onConnectionError: (error) => { console.error("onConnectionError", error); }, }, { maxReconnects: 5, reconnectTimeout: 1000, callTimeout: 10000 }, // optional { filter: (_data) => true }, // optional ); console.log(subscribtion.getSubscriptionId()); subscribtion.close();
Auth is not supported however you can use a proxy like nginx and pass the auth token via query url. I recommend to use tls.
const client = new NimiqRPCClient("http://localhost/?token=mysecrettoken", "ws://localhost/ws?token=mysecrettoken");
NGINX Config:
http { server { listen 80; location / { # Check the token from the query parameter (?token=...) if ($arg_token != "mysecrettoken") { return 403; # Deny if the token is missing or invalid } # Forward valid requests to the node proxy_pass http://127.0.0.1:8648; } location /ws { # Check the token from the query parameter (?token=...) if ($arg_token != "mysecrettoken") { return 403; # Deny if the token is missing or invalid } proxy_pass http://127.0.0.1:8648; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; proxy_read_timeout 3600; } } }
The BlockchainClient
class provides methods to interact with the blockchain.
getBlockNumber(options)
: Returns the block number for the current head.getBatchNumber(options)
: Returns the batch number for the current head.getEpochNumber(options)
: Returns the epoch number for the current head.getBlockByHash(hash, params, options)
: Tries to fetch a block given its hash.getBlockByNumber(blockNumber, params, options)
: Tries to fetch a block given its number.getLatestBlock(params, options)
: Returns the block at the head of the main chain.getSlotAt(blockNumber, params, options)
: Returns the information for the slot owner at the given block height and offset.getTransactionByHash(hash, options)
: Fetches the transaction(s) given the hash.getTransactionsByBlockNumber(blockNumber, options)
: Fetches the transaction(s) given the block number.getTransactionsByBatchNumber(batchIndex, options)
: Fetches the transaction(s) given the batch number.getTransactionsByAddress(address, params, options)
: Fetches the transaction(s) given the address.getInherentsByBlockNumber(blockNumber, options)
: Returns all the inherents (including reward inherents) given the block number.getInherentsByBatchNumber(batchIndex, options)
: Returns all the inherents (including reward inherents) given the batch number.getAccountByAddress(address, options)
: Tries to fetch the account at the given address.getAccounts(options)
: Fetches all accounts in the accounts tree.getActiveValidators(options)
: Returns a collection of the currently active validator's addresses and balances.getCurrentPenalizedSlots(options)
: Returns the currently penalized slots.getPreviousPenalizedSlots(options)
: Returns the previously penalized slots.getValidatorByAddress(address, options)
: Tries to fetch a validator information given its address.getValidators(options)
: Fetches all validators in the staking contract.getStakersByValidatorAddress(address, options)
: Fetches all stakers for a given validator.getStakerByAddress(address, options)
: Tries to fetch a staker information given its address.import { NimiqRPCClient } from '@blouflash/nimiq-rpc' const client = new NimiqRPCClient(); // Example usage for getBlockNumber client.blockchain.getBlockNumber().then((result) => { console.log("Block Number:", result); }).catch((error) => { console.error("Error:", error); }); // Example usage for getBlockByHash client.blockchain.getBlockByHash("some-block-hash").then((result) => { console.log("Block by Hash:", result); }).catch((error) => { console.error("Error:", error); });
The BlockchainStream
class provides methods to interact with the Nimiq Albatross Node's blockchain streams.
subscribeForBlockHashes(wsCallbacks, options, streamOptions)
: Subscribes to block hash events.subscribeForElectionBlocks(params, wsCallbacks, options)
: Subscribes to election blocks.subscribeForMicroBlocks(params, wsCallbacks, options)
: Subscribes to micro blocks.subscribeForMacroBlocks(params, wsCallbacks, options)
: Subscribes to macro blocks.subscribeForBlocks(params, wsCallbacks, options, streamOptions)
: Subscribes to all blocks.subscribeForValidatorElectionByAddress(params, wsCallbacks, options, streamOptions)
: Subscribes to pre epoch validators events.subscribeForLogsByAddressesAndTypes(params, wsCallbacks, options, streamOptions)
: Subscribes to log events related to a given list of addresses and log types.import { NimiqRPCClient } from '@blouflash/nimiq-rpc' const client = new NimiqRPCClient(); // Example usage for subscribeForBlockHashes const subscription = await client.blockchainStreams.subscribeForBlockHashes( { onMessage: (result) => { console.log("Block Hash:", result); }, onError: (error) => { console.error("Error:", error); }, onConnectionError: (error) => { console.error("Connection Error:", error); }, } ); console.log("Subscription ID:", subscription.getSubscriptionId()); subscription.close();
The ConsensusClient
class provides methods to interact with the consensus layer of the blockchain.
isConsensusEstablished(options)
: Returns a boolean specifying if we have established consensus with the network.getRawTransactionInfo(params, options)
: Given a serialized transaction, it will return the corresponding transaction struct.sendRawTransaction(params, options)
: Sends a raw transaction to the network.createTransaction(params, options)
: Creates a serialized transaction.sendTransaction(params, options)
: Sends a transaction.sendSyncTransaction(params, options)
: Sends a transaction and waits for confirmation.createNewVestingTransaction(params, options)
: Returns a serialized transaction creating a new vesting contract.sendNewVestingTransaction(params, options)
: Sends a transaction creating a new vesting contract to the network.sendSyncNewVestingTransaction(params, options)
: Sends a transaction creating a new vesting contract to the network and waits for confirmation.createRedeemVestingTransaction(params, options)
: Returns a serialized transaction redeeming a vesting contract.sendRedeemVestingTransaction(params, options)
: Sends a transaction redeeming a vesting contract.sendSyncRedeemVestingTransaction(params, options)
: Sends a transaction redeeming a vesting contract and waits for confirmation.createNewHtlcTransaction(params, options)
: Returns a serialized transaction creating a new HTLC contract.sendNewHtlcTransaction(params, options)
: Sends a transaction creating a new HTLC contract.sendSyncNewHtlcTransaction(params, options)
: Sends a transaction creating a new HTLC contract and waits for confirmation.createRedeemRegularHtlcTransaction(params, options)
: Returns a serialized transaction redeeming an HTLC contract.sendRedeemRegularHtlcTransaction(params, options)
: Sends a transaction redeeming an HTLC contract.sendSyncRedeemRegularHtlcTransaction(params, options)
: Sends a transaction redeeming a new HTLC contract and waits for confirmation.createRedeemTimeoutHtlcTransaction(params, options)
: Returns a serialized transaction redeeming a HTLC contract using the TimeoutResolve
method.sendRedeemTimeoutHtlcTransaction(params, options)
: Sends a transaction redeeming a HTLC contract using the TimeoutResolve
method to network.sendSyncRedeemTimeoutHtlcTransaction(params, options)
: Sends a transaction redeeming a HTLC contract using the TimeoutResolve
method to network and waits for confirmation.createRedeemEarlyHtlcTransaction(params, options)
: Returns a serialized transaction redeeming a HTLC contract using the EarlyResolve
method.sendRedeemEarlyHtlcTransaction(params, options)
: Sends a transaction redeeming a HTLC contract using the EarlyResolve
method.sendSyncRedeemEarlyHtlcTransaction(params, options)
: Sends a transaction redeeming a HTLC contract using the EarlyResolve
method and waits for confirmation.signRedeemEarlyHtlcTransaction(params, options)
: Returns a serialized signature that can be used to redeem funds from a HTLC contract using the EarlyResolve
method.createNewStakerTransaction(params, options)
: Returns a serialized new_staker
transaction.sendNewStakerTransaction(params, options)
: Sends a new_staker
transaction.sendSyncNewStakerTransaction(params, options)
: Sends a new_staker
transaction and waits for confirmation.createStakeTransaction(params, options)
: Returns a serialized stake
transaction.sendStakeTransaction(params, options)
: Sends a stake
transaction.sendSyncStakeTransaction(params, options)
: Sends a stake
transaction and waits for confirmation.createUpdateStakerTransaction(params, options)
: Returns a serialized update_staker
transaction.sendUpdateStakerTransaction(params, options)
: Sends a update_staker
transaction.sendSyncUpdateStakerTransaction(params, options)
: Sends a update_staker
transaction and waits for confirmation.createSetActiveStakeTransaction(params, options)
: Returns a serialized set_active_stake
transaction.sendSetActiveStakeTransaction(params, options)
: Sends a set_active_stake
transaction.sendSyncSetActiveStakeTransaction(params, options)
: Sends a set_active_stake
transaction and waits for confirmation.createRetireStakeTransaction(params, options)
: Returns a serialized retire_stake
transaction.sendRetireStakeTransaction(params, options)
: Sends a retire_stake
transaction.sendSyncRetireStakeTransaction(params, options)
: Sends a retire_stake
transaction and waits for confirmation.createRemoveStakeTransaction(params, options)
: Returns a serialized remove_stake
transaction.sendRemoveStakeTransaction(params, options)
: Sends a remove_stake
transaction.sendSyncRemoveStakeTransaction(params, options)
: Sends a remove_stake
transaction and waits for confirmation.createNewValidatorTransaction(params, options)
: Returns a serialized new_validator
transaction.sendNewValidatorTransaction(params, options)
: Sends a new_validator
transaction.sendSyncNewValidatorTransaction(params, options)
: Sends a new_validator
transaction and waits for confirmation.createUpdateValidatorTransaction(params, options)
: Returns a serialized update_validator
transaction.sendUpdateValidatorTransaction(params, options)
: Sends a update_validator
transaction.sendSyncUpdateValidatorTransaction(params, options)
: Sends a update_validator
transaction and waits for confirmation.createDeactivateValidatorTransaction(params, options)
: Returns a serialized inactivate_validator
transaction.sendDeactivateValidatorTransaction(params, options)
: Sends a inactivate_validator
transaction.sendSyncDeactivateValidatorTransaction(params, options)
: Sends a inactivate_validator
transaction and waits for confirmation.createReactivateValidatorTransaction(params, options)
: Returns a serialized reactivate_validator
transaction.sendReactivateValidatorTransaction(params, options)
: Sends a reactivate_validator
transaction.sendSyncReactivateValidatorTransaction(params, options)
: Sends a reactivate_validator
transaction and waits for confirmation.createRetireValidatorTransaction(params, options)
: Returns a serialized retire_validator
transaction.sendRetireValidatorTransaction(params, options)
: Sends a retire_validator
transaction.sendSyncRetireValidatorTransaction(params, options)
: Sends a retire_validator
transaction and waits for confirmation.createDeleteValidatorTransaction(params, options)
: Returns a serialized delete_validator
transaction.sendDeleteValidatorTransaction(params, options)
: Sends a delete_validator
transaction.sendSyncDeleteValidatorTransaction(params, options)
: Sends a delete_validator
transaction and waits for confirmation.import { NimiqRPCClient } from '@blouflash/nimiq-rpc' const client = new NimiqRPCClient(); // Example usage for isConsensusEstablished client.consensus.isConsensusEstablished().then((result) => { console.log("Consensus Established:", result); }).catch((error) => { console.error("Error:", error); }); // Example usage for sendTransaction const transactionParams = { wallet: "wallet-address", recipient: "recipient-address", value: 1000, fee: 1, absoluteValidityStartHeight: 100 }; client.consensus.sendTransaction(transactionParams).then((result) => { console.log("Transaction Sent:", result); }).catch((error) => { console.error("Error:", error); });
The MempoolClient
class provides methods to interact with the Nimiq Albatross Node's mempool.
pushTransaction(params, options)
: Pushes the given serialized transaction to the local mempool.mempoolContent(params, options)
: Content of the mempool.mempool(options)
: Obtains the mempool content in fee per byte buckets.getMinFeePerByte(options)
: Obtains the minimum fee per byte as per mempool configuration.getTransactionFromMempool(hash, options)
: Fetches a transaction from the mempool given its hash.import { NimiqRPCClient } from '@blouflash/nimiq-rpc' const client = new NimiqRPCClient(); // Example usage for pushTransaction const transactionParams = { transaction: "serialized-transaction", withHighPriority: true }; client.mempool.pushTransaction(transactionParams).then((result) => { console.log("Transaction Pushed:", result); }).catch((error) => { console.error("Error:", error); }); // Example usage for mempoolContent client.mempool.mempoolContent({ includeTransactions: true }).then((result) => { console.log("Mempool Content:", result); }).catch((error) => { console.error("Error:", error); });
The NetworkClient
class provides methods to interact with the Nimiq Albatross Node's network.
getPeerId(options)
: The peer ID for our local peer.getPeerCount(options)
: Returns the number of peers.getPeerList(options)
: Returns a list with the IDs of all our peers.import { NimiqRPCClient } from '@blouflash/nimiq-rpc' const client = new NimiqRPCClient(); // Example usage for getPeerId client.network.getPeerId().then((result) => { console.log("Peer ID:", result); }).catch((error) => { console.error("Error:", error); }); // Example usage for getPeerCount client.network.getPeerCount().then((result) => { console.log("Peer Count:", result); }).catch((error) => { console.error("Error:", error); });
The PolicyClient
class provides methods to interact with the Nimiq Albatross Node's policy.
getPolicyConstants(options)
: Gets a bundle of policy constants.getEpochAt(blockNumber, options)
: Returns the epoch number at a given block number (height).getEpochIndexAt(blockNumber, options)
: Returns the epoch index at a given block number.getBatchAt(blockNumber, options)
: Returns the batch number at a given block number (height).getBatchIndexAt(blockNumber, options)
: Returns the batch index at a given block number.getElectionBlockAfter(blockNumber, options)
: Gets the number (height) of the next election macro block after a given block number (height).getElectionBlockBefore(blockNumber, options)
: Gets the block number (height) of the preceding election macro block before a given block number (height).getLastElectionBlock(blockNumber, options)
: Gets the block number (height) of the last election macro block at a given block number (height).isElectionBlockAt(blockNumber, options)
: Gets a boolean expressing if the block at a given block number (height) is an election macro block.getMacroBlockAfter(blockNumber, options)
: Gets the block number (height) of the next macro block after a given block number (height).getMacroBlockBefore(blockNumber, options)
: Gets the block number (height) of the preceding macro block before a given block number (height).getLastMacroBlock(blockNumber, options)
: Gets the block number (height) of the last macro block at a given block number (height).isMacroBlockAt(blockNumber, options)
: Gets a boolean expressing if the block at a given block number (height) is a macro block.isMicroBlockAt(blockNumber, options)
: Gets the block number (height) of the next micro block after a given block number (height).getFirstBlockOfEpoch(epochIndex, options)
: Gets the block number (height) of the first block of the given epoch (which is always a micro block).getBlockAfterReportingWindow(blockNumber, options)
: Gets the block number of the first block of the given reporting window (which is always a micro block).getBlockAfterJail(blockNumber, options)
: Gets the block number of the first block of the given jail (which is always a micro block).getFirstBlockOfBatch(batchIndex, options)
: Gets the block number of the first block of the given batch (which is always a micro block).getElectionBlockOfEpoch(epochIndex, options)
: Gets the block number of the election macro block of the given epoch (which is always the last block).getMacroBlockOfBatch(batchIndex, options)
: Gets the block number of the macro block (checkpoint or election) of the given batch (which is always the last block).getFirstBatchOfEpoch(blockNumber, options)
: Gets a boolean expressing if the batch at a given block number (height) is the first batch of the epoch.getSupplyAt(params, options)
: Gets the supply at a given time (as Unix time) in Lunas (1 NIM = 100,000 Lunas).import { NimiqRPCClient } from '@blouflash/nimiq-rpc' const client = new NimiqRPCClient(); // Example usage for getPolicyConstants client.policy.getPolicyConstants().then((result) => { console.log("Policy Constants:", result); }).catch((error) => { console.error("Error:", error); }); // Example usage for getEpochAt client.policy.getEpochAt(1000).then((result) => { console.log("Epoch at Block 1000:", result); }).catch((error) => { console.error("Error:", error); });
The SerdeHelper
class provides methods to serialize and deserialize data.
serializeToHex(params, options)
: Serializes a byte array to a hexadecimal string.deserializeFromHex(params, options)
: Deserializes a hexadecimal string to a byte array.import { NimiqRPCClient } from '@blouflash/nimiq-rpc' const client = new NimiqRPCClient(); // Example usage for serializeToHex const data = new Uint8Array([1, 2, 3, 4]); client.serdeHelper.serializeToHex({ data }).then((result) => { console.log("Serialized Hex:", result); }).catch((error) => { console.error("Error:", error); }); // Example usage for deserializeFromHex const hexString = "01020304"; client.serdeHelper.deserializeFromHex({ hexString }).then((result) => { console.log("Deserialized Data:", result); }).catch((error) => { console.error("Error:", error); });
The ValidatorClient
class provides methods to interact with the Nimiq Albatross Node's validator.
getAddress(options)
: Returns our validator address.getSigningKey(options)
: Returns our validator signing key.getVotingKey(options)
: Returns our validator voting key.setAutomaticReactivation(params, options)
: Updates the configuration setting to automatically reactivate our validator.isElected(options)
: Returns whether our validator is elected.isSynced(options)
: Returns whether our validator is synced.import { NimiqRPCClient } from '@blouflash/nimiq-rpc' const client = new NimiqRPCClient(); // Example usage for getAddress client.validator.getAddress().then((result) => { console.log("Validator Address:", result); }).catch((error) => { console.error("Error:", error); }); // Example usage for isElected client.validator.isElected().then((result) => { console.log("Is Elected:", result); }).catch((error) => { console.error("Error:", error); });
The WalletClient
class provides methods to interact with the Nimiq Albatross Node's wallet.
importRawKey(params, options)
: Imports a raw key into the wallet.isAccountImported(address, options)
: Checks if an account is imported.listAccounts(options)
: Lists all imported accounts.lockAccount(address, options)
: Locks an account.createAccount(params, options)
: Creates a new account.unlockAccount(address, params, options)
: Unlocks an account.isAccountUnlocked(address, options)
: Checks if an account is unlocked.sign(params, options)
: Signs a message with an account's key.verifySignature(params, options)
: Verifies a signature.removeAccount(address, options)
: Removes an account.import { NimiqRPCClient } from '@blouflash/nimiq-rpc' const client = new NimiqRPCClient(); // Example usage for importRawKey const keyParams = { keyData: "raw-key-data", passphrase: "passphrase" }; client.wallet.importRawKey(keyParams).then((result) => { console.log("Imported Key Address:", result); }).catch((error) => { console.error("Error:", error); }); // Example usage for createAccount const accountParams = { passphrase: "passphrase" }; client.wallet.createAccount(accountParams).then((result) => { console.log("Created Account:", result); }).catch((error) => { console.error("Error:", error); });
The ZkpComponentClient
class provides methods to interact with the Nimiq Albatross Node's ZKP component.
getZkpState(options)
: Returns the latest header number, block number and proof.import { NimiqRPCClient } from '@blouflash/nimiq-rpc' const client = new NimiqRPCClient(); // Example usage for getZkpState client.zkpComponent.getZkpState().then((result) => { console.log("ZKP State:", result); }).catch((error) => { console.error("Error:", error); });
Released under MIT by @blouflashdb.
Add Package
deno add jsr:@blouflash/nimiq-rpc
Import symbol
import * as nimiq_rpc from "@blouflash/nimiq-rpc";
---- OR ----
Import directly with a jsr specifier
import * as nimiq_rpc from "jsr:@blouflash/nimiq-rpc";
Add Package
npx jsr add @blouflash/nimiq-rpc
Import symbol
import * as nimiq_rpc from "@blouflash/nimiq-rpc";
Add Package
yarn dlx jsr add @blouflash/nimiq-rpc
Import symbol
import * as nimiq_rpc from "@blouflash/nimiq-rpc";
Add Package
pnpm dlx jsr add @blouflash/nimiq-rpc
Import symbol
import * as nimiq_rpc from "@blouflash/nimiq-rpc";
Add Package
bunx jsr add @blouflash/nimiq-rpc
Import symbol
import * as nimiq_rpc from "@blouflash/nimiq-rpc";