JavaScript SDK

Documentation of the nocust-client JavaScript library

NPM link: https://www.npmjs.com/package/nocust-client

NOCUSTTransfer

Interface For the parameters object required to make nocust transfers.

Parameters:

Name

Type

Description

to

string

Recipient of the transfer.

from

string

Sender of the transfer.

Optional tokenAddress

string

Token to send. Use Ether if not specified.

Amount

BigNumber | BN | string

Amount in wei (for Ether) of the transfer

Optional nonce

BigNumber

Specify a nonce, can be used to attribute an identifier to the transaction. Set randomly if not specified.

TransferDataInterface

Full transfer details including signatures and status.

Name

Type

Description

id

number

Transaction ID, uniquely identify the transfer

amount

string

Transfer amount

wallet

TransferWalletDataInterface

Sender details.

recipient

TransferWalletDataInterface

Recipient details.

eon_number

number

NOCUST operator eon or round of the transfer.

processed

boolean

If the payment operator processed the the transfer. The operator wait for the recipient confirmation before processing the transfer.

completed

boolean

If the transfer is fully confirmed.

canceled

boolean

If the transfer is canceled.

NOCUSTManager

approveAndDeposit

approveAndDeposit(address: string, amount: BigNumber | BN | string, gasPrice: BigNumber | BN | string, gas: number, tokenAddress?: string): Promise<string>

Similarly to the deposit function but prior check to send the deposit transaction it checks for token transfer allowance of the NOCUST smart contract. If the allowance is not sufficient it sends an ERC-20 aprove transaction. Approving token transfers is a required operation by the ERC-20 standard. If the depositor does not have sufficient allowance the deposit will fail. Note that this function will make 2 on-chain transaction (contract calls) with the specified gas price and gas limit. Approvals are not required for Ether.

Parameters:

Name

Type

Description

address

string

Targeted Ethereum address

amount

BigNumber | BN | string

Amount to deposit, this amount needs to be available on-chain for the specified address.

gasPrice

BigNumber | BN | string

Gas price for the on-chain transaction.

gas

number

Gas limit for the on-Chain transaction. Around 100'000 gas is advised.

Optional tokenAddress

string

Targeted ERC-20 token.

Returns: Promise<string> Hash of the on-chain transaction of the deposit.

buySLA

buySLA(address: string): Promise<void>

Buys a SLA. The address needs to have the token amount available as a nocust balance on the address as specified by the getSLADetail function. This function will make a nocust transfer to pay for the SLA.

Parameters:

Name

Type

Description

address

string

-

Returns: Promise<void>

deposit

deposit(address: string, amount: BigNumber | BN | string, gasPrice: BigNumber | BN | string, gas: number, tokenAddress?: string): Promise<string>

Make an on-chain transaction to deposit funds into the NOCUST commit-chain. This funds can be later used for making off-chain NOCUST transfers. The operator will credit the deposit after 20 blocks of confirmation.

Parameters:

Name

Type

Description

address

string

Targeted Ethereum address

amount

BigNumber | BN | string

Amount to deposit, this amount needs to be available on-chain for the specified address.

gasPrice

BigNumber | BN | string

Gas price for the on-chain transaction.

gas

number

Gas limit for the on-Chain transaction. Around 100'000 gas is advised.

Optional tokenAddress

string

Targeted ERC-20 token. Use Ether if not specified.

Returns: Promise<string> Hash of the on-chain transaction of the deposit.

getBlockPerEon

getBlockPerEon(): Promise<number>

Get the number of Eras (blocks) per Eon.

Returns: Promise<number>

getBlocksToWithdrawalConfirmation

getBlocksToWithdrawalConfirmation(address: string, txHash?: string, tokenAddress?: string): Promise<number>

Get the number of blocks until it is possible to send the withdrawal confirmation on-chain transaction. It will return -1 if no withdrawals are pending or 0 if the withdrawal is ready to be confirmed.

Parameters:

Name

Type

Description

address

string

Address that started the withdrawal.

Optional txHash

string

Transaction hash of the on-chain transaction of the of the withdrawal request. Will use the oldest pending withdrawal if not specified.

Optional tokenAddress

string

Targeted ERC-20 token. Use Ether if not specified.

Returns: Promise<number>

getEonNumber

getEonNumber(): Promise<number>

Get the current Eon or round number.

Returns: Promise<number>

getEraNumber

getEraNumber(): Promise<number>

Get the current Era or sub-block number. The number of block since the current Eon started.

Returns: Promise<number> Era

getNOCUSTBalance

getNOCUSTBalance(address: string, tokenAddress?: string): Promise<BigNumber>

Fetch the current NOCUST balance.

Parameters:

Name

Type

Description

address

string

Targeted Ethereum address.

Optional tokenAddress

string

Targeted ERC-20 token. Use Ether if not specified.

Returns: Promise<BigNumber> Nocust balance

getOnChainBalance

getOnChainBalance(address: string, tokenAddress?: string): Promise<BigNumber>

Get current on-chain balance.

Parameters:

Name

Type

Description

address

string

Targeted Ethereum address.

Optional tokenAddress

string

Targeted ERC-20 token. Use Ether if not specified.

Returns: Promise<BigNumber> On-chain balance.

getOrderBook

getOrderBook(buyTokenAddress: string, sellTokenAddress: string): Promise<OrderBookDataInterface>

Parameters:

Name

Type

Description

buyTokenAddress

string

-

sellTokenAddress

string

-

Returns: Promise<OrderBookDataInterface>

getSLADetail

getSLADetail(): Promise<SLADetailsInterface>

Get informations about the SLA pricing model.

Returns: Promise<SLADetailsInterface> Object with the token address with which to pay the SLA, the cost/amount of the SLA in this token, the recipient of the SLA payment, the transaction limit per month without SLA.

getSLAStatus

getSLAStatus(address: string): Promise<number>

Get the SLA status for a given address.

Parameters:

Name

Type

Description

address

string

Targeted Ethereum address.

Returns: Promise<number> 0 if not under SLA, expiry date unix timestamp in millisecond if currently enroll with a SLA.

getSupportedTokens

getSupportedTokens(): Promise<object[]>

Fetch the smart contract addresses of the supported token by the commit-chain.

Returns: Promise<object[]> Promise that resolves with an array of objects { tokenAddress: string, name: string, shortName: string } for each token supported by the commit-chain. Address is the address of the ERC-20 contract of the token.

getTransaction

getTransaction(transactionId: number): Promise<TransferDataInterface>

Fetch the transaction details given a transaction ID

Parameters:

Name

Type

Description

transactionId

number

Transaction ID of the transaction to fetch

Returns: Promise<TransferDataInterface> Transaction details }`

getTransactionsForAddress

getTransactionsForAddress(address: string, tokenAddress?: string, roundNumber?: number): Promise<TransferDataInterface[]>

Get the list of transactions for a given address and token (Incoming and outgoing).

Parameters:

Name

Type

Description

address

string

Targeted Ethereum address.

Optional tokenAddress

string

Targeted ERC-20 token. Use Ether if not specified.

Optional roundNumber

number

Get the transactions only starting from a specific round number. Return all transactions if unspecified.

Returns: Promise<TransferDataInterface[]> Array of transactions

getWalletState

getWalletState(address: string, tokenAddress?: string): Promise<WalletState>

Get the WalletState object for lower level API use.

Parameters:

Name

Type

Description

address

string

Targeted Ethereum address.

Optional tokenAddress

string

Targeted ERC-20 token. Use Ether if not specified.

Returns: Promise<WalletState>

getWithdrawalFee

getWithdrawalFee(withdrawalRequestGasPrice: BigNumber | BN | string): Promise<BigNumber>

Doing a withdrawal request involve a fee to the operator. This function gets the current fee.

Parameters:

Name

Type

Description

withdrawalRequestGasPrice

BigNumber | BN | string

Gas price that will be used for the withdrawal request. The Fee is dependant on the gas price to be used.

Returns: Promise<BigNumber> Fee amount

getWithdrawalLimit

getWithdrawalLimit(address: string, tokenAddress?: string): Promise<BigNumber>

Withdrawals are limited to a certain amount (Because funds need to committed into a check point) and the limit increase over time. This method gets you the current available off-chain funds for withdrawal.

Parameters:

Name

Type

Description

address

string

Targeted Ethereum address.

Optional tokenAddress

string

Targeted ERC-20 token. Use Ether if not specified.

Returns: Promise<BigNumber> Withdrawal limit.

subscribeToIncomingTransfer

subscribeToIncomingTransfer(address: string, callBack: function, tokenAddress?: any): function

Return an observable to notify of incoming transfers.

Parameters:

Name

Type

Description

address

string

Address to watch for.

callBack

function

Callback function that will be called on incoming transfers. The function provides the incoming transfer as argument.

Optional tokenAddress

any

Targeted ERC-20 token. Use Ether if not specified. The string 'all' can be used to be notified for all tokens available on the commit-chain.

Returns: Promise< unsubscribe () => Void> A promise that resolves when the callback is registered. The promise resolves with the unsubscribe function of the callback.

Example:

const unsubscribe = await nocustManager.subscribeToIncomingTransfer(
bob,
tx => console.log(`Incoming transaction from: ${tx.wallet.address} of: ${tx.amount.toString()} wei of token ${tx.wallet.token}.`),
'all'
)
// Unsubscribe when it is not needed anymore
unsubscribe()

isAddressRegistered

isAddressRegistered(address: string, tokenAddress?: string): Promise<boolean>

Check if an address is registered with the nocust commit-chain.

Parameters:

Name

Type

Description

address

string

Address to check.

Optional tokenAddress

string

Targeted ERC-20 token. Use Ether if not specified.

Returns: Promise<boolean> Return true if the registration is successful

isAddressRegisteredWithOperator

isAddressRegisteredWithOperator(address: string, tokenAddress?: string): Promise<boolean>

Check whether an address is registered with the commit-chain and can therefore receive payments.

Parameters:

Name

Type

Description

address

string

Targeted Ethereum address.

Optional tokenAddress

string

Targeted ERC-20 token. Use Ether if not specified.

Returns: Promise<boolean>

isRecovery

isRecovery(): Promise<boolean>

Check whether the commit-chain is in recovery mode. If it is the case, the commit-chain can't be used anymore and funds need to be recovered.

Returns: Promise<boolean> Recovery status.

issueDeliveryChallenge

issueDeliveryChallenge(address: string, txId: number, gasPrice: any, gas: any, tokenAddress?: string): Promise<string>

Make an on-chain transaction to initiate a delivery challenge.

Parameters:

Name

Type

Description

address

string

Targeted Ethereum address.

txId

number

Transaction id to challenge for delivery.

gasPrice

any

Gas price for the on-chain transaction.

gas

any

Gas limit for the off-Chain transaction. Around 350'000 gas is advised.

Optional tokenAddress

string

Targeted ERC-20 token. Use Ether if not specified.

Returns: Promise<string>

issueStateUpdateChallenge

issueStateUpdateChallenge(address: string, gasPrice: any, gas: any, tokenAddress?: string): Promise<string>

Make an on-chain transaction to initiate a state update challenge.

Parameters:

Name

Type

Description

address

string

Targeted Ethereum address.

gasPrice

any

Gas price for the on-chain transaction.

gas

any

Gas limit for the off-Chain transaction. Around 350'000 gas is advised.

Optional tokenAddress

string

Targeted ERC-20 token. Use Ether if not specified.

Returns: Promise<string>

recoverFunds

recoverFunds(address: string, gasPrice: any, gas: any, tokenAddress?: string): Promise<string>

Make an on-chain transaction to recover funds whenever the commit-chain falls into recovery mode.

Parameters:

Name

Type

Description

address

string

Targeted Ethereum address.

gasPrice

any

Gas price for the on-chain transaction.

gas

any

Gas limit for the off-Chain transaction. Around 350'000 gas is advised.

Optional tokenAddress

string

Targeted ERC-20 token. Use Ether if not specified.

Returns: Promise<string>

registerAddress

registerAddress(address: string, tokenAddress?: string): Promise<void>

Register an address for a given token with the commit-chain. An address needs to be registered with the commit-chain for each token separately in order to send or receive transfers. This operation is done implicitly when sending a transfer if the address is not yet registered. Note that for a transfer to succeed the recipient need to have registered.

Parameters:

Name

Type

Description

address

string

Address to register with the commit-chain.

Optional tokenAddress

string

Targeted ERC-20 token. Use Ether if not specified.

Returns: Promise<void>

sendSwap

sendSwap(address: string, buyTokenAddress: string, sellTokenAddress: string, buyAmount: BigNumber | BN | string, sellAmount: BigNumber | BN | string): Promise<number>

Parameters:

Name

Type

Description

address

string

Main wallet address.

buyTokenAddress

string

Token address to buy.

sellTokenAddress

string

Token address to sell.

buyAmount

BigNumber | BN | string

Amount of buy token to buy.

sellAmount

BigNumber | BN | string

Amount of sell token to swap for buying amount.

Optional subWalletSeedPhrase

string

(optional) A string signed by wallet's private key to generate a seed used to create auxilary swap accounts. Default value is "I want to use Liquidity Network Swaps"

Returns: Promise<number>

sendTransaction

sendTransaction(transfer: NocustTransfer): Promise<number>

Send a NOCUST transfer.

Parameters:

Name

Type

Description

transfer

NocustTransfer

Parameter object of an off-chain transfer.

Returns: Promise<number> Transaction Id of the NOCUST transfer

synchronizeSwapOrders

synchronizeSwapOrders(address: string, subWalletSeedPhrase?: string): Promise<TransferDataInterface[]>

Claims all auxilary wallet's fulfilled swap orders and returns a list of unfulfilled swaps.

Parameters:

Name

Type

Description

address

string

Main wallet address.

Optional subWalletSeedPhrase

string

(optional) A string signed by wallet's private key to generate a seed used to create auxiliary swap accounts. Default value is "I want to use Liquidity Network Swaps"

syncWallet

syncWallet(address: string, tokenAddress?: string): Promise<void>

Force synchronize the wallet of the given public key for the given token. The result will be cached making later calls of this wallet faster. This function can be useful to pre-cache required internal data (for example on starup of your app) to make later function calls faster.

Parameters:

Name

Type

Description

address

string

Targeted Ethereum address

Optional tokenAddress

string

Targeted ERC-20 token. Use Ether if not specified

Returns: Promise<void>

withdrawalConfirmation

withdrawalConfirmation(address: string, gasPrice: BigNumber | BN | string, gas: number, tokenAddress?: string): Promise<string>

Make an on-chain transaction to confirm a withdrawal previously initialized and effectively transfer the funds.

Parameters:

Name

Type

Description

address

string

Targeted Ethereum address.

gasPrice

BigNumber | BN | string

Gas price for the on-chain transaction.

gas

number

Gas limit for the on-Chain transaction. Around 100'000 gas is advised.

Optional tokenAddress

string

Targeted ERC-20 token. Use Ether if not specified.

Returns: Promise<string> Hash of the on-chain transaction of the withdrawal confirmation.

withdrawalRequest

withdrawalRequest(address: string, amount: BigNumber | BN | string, gasPrice: BigNumber | BN | string, gas: number, tokenAddress?: string): Promise<string>

Make an on-chain transaction to initiate a withdrawal to remove the funds from the NOCUST smart contract and to get them at the specified address. The amount specified needs to be available for withdrawal . The withdrawal will have to be confirmed after a certain period of time (Currently between 36 and 72h). On the top the gas fee, this function will take an Ether fee from the on-chain balance for the commit-chain operator.

Parameters:

Name

Type

Description

address

string

Targeted Ethereum address

amount

BigNumber | BN | string

Amount to deposit, this amount needs to be available on-chain for the specified address

gasPrice

BigNumber | BN | string

Gas price for the on-chain transaction.

gas

number

Gas limit for the on-chain transaction. Around 100'000 gas is advised.

Optional tokenAddress

string

Targeted ERC-20 token. Use Ether if not specified.

Returns: Promise<string> Hash of the on-chain transaction of the withdrawal request.

Errors handling

The NOCUSTManager instance throws errors that can be catch and easily handled.

import { NOCUSTManager, NOCUSTError } from 'nocust-client'
try {
balance = await nocustManager.getNOCUSTBalance(address)
} catch(err) {
if(err.code === NOCUSTError.UNREGISTERED_WITH_COMMIT_CHAIN) {
// Register...
} else {
console.error(err.message)
}
}

Error codes

The library supports the following error code that can be checked as in the example above. The error codes are available in the NOCUSTError enum.

UNKNOWN_ERROR

Unknown error.

UNREGISTERED_WITH_COMMIT_CHAIN

Wallet not registered with the commit-chain ledger. The address was not register with the commit-chain, the registerAddress function need to be called for the specific address and token.

PREPARE_TRANSFER_FAILURE

Could not prepare transfer/swap hashes.

SINGING_FAILURE

Was not able to produce a signature. The function called require to sign a message with the corresponding private key. Ensure that the private key was added to the web3 object passed to the NOCUSTManager instance. To add a private key to a web3 instance do: web3.eth.accounts.wallet.add(privateKey)

POST_FAILURE

Post request to operator server failed. The server most likely replied with a more specific error.

REGISTRATION_THROTTLING

This means that the DoS protection of the server was triggered. Human verification is required. The complete the human verification the user is required to solve a captcha. The captcha page is available at <server URL>/whitelist/

FETCH_OPERATOR_DATA_ERROR

Error when fetching data from the operator HTTP or Websocket API. Please ensure that the operatorUrl parameter passed to the NOCUSTManager instance is correct and that the URL is reachable.

FETCH_PARENT_CHAIN_DATA_ERROR

Error when fetching data from contract/blockchain. Ensure that your RPC endpoint (infura ?) is working correctly. The RPC endpoint URL is passe to the NOCUSTManager instance by the parameter rpcApi.

CONFIRMATION_TIMEOUT

Confirmation timeout of transfer/registration/swap. The server could not process the action.

NON_UNIQUE_TRANSFER

The exact same transfer/swap/registration was already posted. To solve this issue adjust nonce in the transfer NOCUSTTransfer object. The nonce can also be set it to undefined to automatically assign a random nonce.

PARENT_CHAIN_TRANSACTION_FAILURE

Could not execute a blockchain transaction. Please verify that the gas limit is sufficiently high. Verify contract address and gas price. Ensure that you have enough Ether to pay for gas fees and amount,

INSUFFICIENT_WITHDRAWAL_LIMIT

You do not have enough withdrawal allowances (Yet). It is required to wait one full Eon (round) to pass for freshly received or deposited funds to be withdrawable. Use the getWithdrawalLimit function to get your current withdrawal limit.

NO_ETHER_TO_PAY_FOR_GAS

Some Ether are needed to pay for gas fees. Send a small amount of Ether to the address trying to execute the operation.

WALLET_STATE_ERROR

Wallet state service failed, meaning that there is some inconsistent data from the operator API. The error message will likely give you more information. Note this can mean that the account is potentially unsafe/out of service and you might need to initiate a challenge/recover.

INSUFFICIENT_COMMIT_CHAIN_BALANCE

Not enough commit-chain/off-chain funds

SWAP_PENDING

A swap is pending so the account can't be use until the swap is finalized, canceled or the eon ends.