An Ardor client library written in TypeScript.
npm install @blobaa/ardor-ts
You need to have Node.js installed.
To initialize the project just clone this repository and run
npm install
For linting run
npm run lint
You can try to autofix lint errors with
npm run fix-lint
For unit testing run the following associated commands
browser:
npm run test-browser
node:
npm run test-node
both:
npm test
Because broadcasting a transaction costs fees, the transaction post request tests are disabled by default. You can enable them in the test/config.ts file.
The library consist of the following modules:
This module creates requests to communicate with an ardor node. It handles get requests and transaction post requests. Every request which involves a transaction creation is signed locally so that your passphrase is never transmitted to an ardor node.
Each function has the following singature:
functionName(url: string, params: FunctionNameParams): Promise<FunctionNameResponse>
The functionName corresponds to the ardor API request type, the functionNameParams interface to the request parameters and the functionNameResponse interface to the JSON response properties (see API console).
An example request to get the current account balance might look like this:
import { request, GetBalanceParams, ChainId, ErrorResponse } from '@blobaa/ardor-ts'
const exampleRequest = async () => {
/* set request parameters */
const params: GetBalanceParams = {
chain: ChainId.IGNIS,
account: "ARDOR-XCTG-FVBM-9KNX-3DA6B"
}
try {
/* create and emit a request */
const response = await request.getBalance("https://testardor.jelurida.com", params);
/* the response implements the GetBalanceResponse interface */
console.log(response.balanceNQT);
console.log(response.unconfirmedBalanceNQT);
console.log(response.requestProcessingTime);
} catch(e) {
/* check the error type */
const error = e as ErrorResponse;
if(error.errorCode) {
/* error is an api error */
console.log(error.errorDescription);
console.log(error.errorCode);
} else {
/* error is an axios error */
console.log(e);
}
}
}
exampleRequest();The following requests are implemented:
- decodeToken(url: string, params: DecodeTokenParams): Promise<DecodeTokenResponse>
- getAccountProperties(url: string, params: GetAccountPropertiesParams): Promise<GetAccountPropertiesResponse>
- getBalance(url: string, params: GetBalanceParams): Promise<GetBalanceResponse>
- getBlockchainTransactions(url: string, params: GetBlockchainTransactionsParams): Promise<GetBlockchainTransactionsResponse>
- getBundlerRates(url: string, params: GetBundlerRatesParams): Promise<GetBundlerRatesResponse>
- getTransaction(url: string, params: GetTransactionParams): Promise<GetTransactionResponse>
- downloadTaggedData(url: string, params: DownloadTaggedDataParams): Promise<DownloadTaggedDataResponse>- broadcastTransaction(url: string, params: BroadcastTransactionParams): Promise<BroadcastTransactionResponse>
- deleteAccountProperty(url: string, params: DeleteAccountPropertyParams): Promise<DeleteAccountPropertyResponse>
- sendMessage(url: string, params: SendMessageParams): Promise<SendMessageResponse>
- sendMoney(url: string, params: SendMoneyParams): Promise<SendMoneyResponse>
- setAccountProperty(url: string, params: SetAccountPropertyParams): Promise<SetAccountPropertyResponse>
- uploadTaggedData(url: string, params: UploadTaggedDataParams): Promise<UploadTaggedDataResponse> // only data upload (no file upload) supportedThe Account module is a wrapper of a forked version of the ardorjs package. It handles transaction signing, account conversions and token generation.
It provides the following APIs:
- convertPassphraseToPublicKey(passphrase: string, toByteArray?: boolean): string | Array<number> // toByteArray defaults to false
- convertPublicKeyToAccountId(publicKey: string): string
- convertPublicKeyToAccountRs(publicKey: string): string
- convertPassphraseToAccountId(passphrase: string): string
- convertPassphraseToAccountRs(passphrase: string): string
- checkAccountRs(accountRs: string): boolean // ok => true, error => false
- generateToken(message: string, passphrase: string, forTestnet?: boolean): string // forTestnet defaults to false
- signTransactionBytes(unsignedTransactionBytesHex: string, passphrase: string): string
- verifyTransactionBytes(unsignedTransactionBytesHex: string, transactionType: string, transactionJSON: object, publicKey: string): booleanThis module provides passphrase generation. It uses the bip39 package with the default english wordlist.
API:
- generate(): stringThe Time module handles conversions between Ardor epoch timestamps and unix timestamps.
It provides the following APIs:
- convertUnixToArdorTimestamp(timestampInMsec: number, isTestnetTimestamp?: boolean): number // isTestnetTimestamp defaults to false
- convertArdorToUnixTimestamp(timestamp: number, isTestnetTimestamp?: boolean): number // isTestnetTimestamp defaults to falseThe ChainCurrency module handles conversions between a chain currency representation and its base value.
For example: ARDR has 8 decimals so that 1 ARDR can be converted to 100000000 ARDR NQTs which is called the base unit here.
It provides the following APIs:
- convertToBaseUnit(amount: number, currencyType: ChainCurrencyType): number;
- convertFromBaseUnit(amount: number, currencyType: ChainCurrencyType): number;Each module is pre instantiated and importable via the lower case module name. If you need the class definition of a module, import it via the upper case name. For example:
import { passphrase, Passphrase } from '@blobaa/ardor-ts'
/* use the default instance */
const passphrase1 = passphrase.generate();
console.log(passphrase1);
/* use your own instance */
const myPassphrase = new Passphrase();
const passphrase2 = myPassphrase.generate();
console.log(passphrase2);Enjoy :)