JavaScript SDK
Documentation of the nocust-client JavaScript library
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. |
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. |
▸ 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(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(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():
Promise<number>Get the number of Eras (blocks) per Eon.
Returns:
Promise<number>▸ 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():
Promise<number>Get the current Eon or round number.
Returns:
Promise<number>▸ 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(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(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(buyTokenAddress:
string, sellTokenAddress: string): Promise<OrderBookDataInterface>Parameters:
Name | Type | Description |
buyTokenAddress | string | - |
sellTokenAddress | string | - |
Returns:
Promise<OrderBookDataInterface>▸ 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(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():
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(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(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(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(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(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(address:
string, callBack: function, tokenAddress?: any): functionReturn 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(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(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():
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(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(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(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(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(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(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(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(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(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(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.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)
}
}
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.
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. Could not prepare transfer/swap hashes.
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 request to operator server failed. The server most likely replied with a more specific error.
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/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.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 of transfer/registration/swap. The server could not process the action.
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.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,
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.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 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.
Last modified 3yr ago