1.2.5NKN client that sends data to and receives data from other NKN clients. Typically you might want to use MultiClient for better reliability and lower latency.
(Object
= {})
Client configuration
| Name | Description |
|---|---|
options.seed string
(default undefined)
|
Secret seed (64 hex characters). If empty, a random seed will be used. |
options.identifier string
(default undefined)
|
Identifier used to differentiate multiple clients sharing the same secret seed. |
options.reconnectIntervalMin number
(default 1000)
|
Minimal reconnect interval in ms. |
options.reconnectIntervalMax number
(default 64000)
|
Maximal reconnect interval in ms. |
options.responseTimeout number
(default 5000)
|
Message response timeout in ms. Zero disables timeout. |
options.msgHoldingSeconds number
(default 0)
|
Maximal message holding time in second. Message might be cached and held by node up to this duration if destination client is not online. Zero disables cache. |
options.encrypt boolean
(default true)
|
Whether to end to end encrypt message. |
options.rpcServerAddr string
(default 'https://mainnet-rpc-node-0001.nkn.org/mainnet/api/wallet')
|
RPC server address used to join the network. |
options.tls boolean
(default undefined)
|
Force to use wss instead of ws protocol. If not defined, wss will only be used in https location. |
options.worker (boolean | function)
(default false)
|
Whether to use web workers (if available) to compute signatures. Can also be a function that returns web worker. Typically you only need to set it to a function if you import nkn-sdk as a module and are NOT using browserify or webpack worker-loader to bundle js file. The worker file is located at
lib/worker/webpack.worker.js
.
|
Client address, which will be identifier.pubicKeyHex if identifier is not empty, otherwise just pubicKeyHex.
Type: string
Close the client.
Same as wallet.deleteName, but using this client's connected node as rpcServerAddr, followed by this client's rpcServerAddr if failed.
(string)
(TransactionOptions
= {})
Promise<TxnOrHash>
Same as Wallet.getBalance, but using this client's connected node as rpcServerAddr, followed by this client's rpcServerAddr if failed.
(string?)
Promise<common.Amount>
Same as Wallet.getSubscribers, but using this client's connected node as rpcServerAddr, followed by this client's rpcServerAddr if failed.
Promise<{subscribers: (Array<string> | {}), subscribersInTxPool: (Array<string> | {})?}>
Same as Wallet.getSubscription, but using this client's connected node as rpcServerAddr, followed by this client's rpcServerAddr if failed.
Promise<{meta: string, expiresAt: number}>
Add event listener function that will be called when client is connected to
node. Multiple listeners will be called sequentially in the order of added.
Note that listeners added after client is connected to node (i.e.
client.isReady === true) will not be called.
(ConnectHandler)
Add event listener function that will be called when client fails to
connect to node. Multiple listeners will be called sequentially in the
order of added. Note that listeners added after client fails to connect to
node (i.e. client.isFailed === true) will not be called.
(ConnectFailedHandler)
Add event listener function that will be called when client receives a
message. Multiple listeners will be called sequentially in the order of
added. Can be an async function, in which case each call will wait for
promise to resolve before calling next listener function. If the first
non-null and non-undefined returned value is Uint8Array or string,
the value will be sent back as reply; if the first non-null and
non-undefined returned value is false, no reply or ACK will be sent;
if all handler functions return null or undefined, an ACK indicating
msg received will be sent back. Receiving reply or ACK will not trigger
the event listener.
(MessageHandler)
Add event listener function that will be called when client websocket connection throws an error. Multiple listeners will be called sequentially in the order of added.
(WsErrorHandler)
Send byte or string data to all subscribers of a topic.
Promise<null>:
A promise that will be resolved with null when send success.
Same as wallet.registerName, but using this client's connected node as rpcServerAddr, followed by this client's rpcServerAddr if failed.
(string)
(TransactionOptions
= {})
Promise<TxnOrHash>
Send byte or string data to a single or an array of destination.
(Destination)
(MessageData)
(SendOptions
= {})
Send options that will override client options.
Promise<ReplyData>:
A promise that will be resolved when reply or ACK from destination is received, or reject if send fail or message timeout. If dest is an array with more than one element, or
options.noReply=true
, the promise will resolve with null as soon as send success.
Same as Wallet.sendTransaction, but using this client's connected node as rpcServerAddr, followed by this client's rpcServerAddr if failed.
(common.pb.transaction.Transaction)
Promise<string>
Same as wallet.subscribe, but using this client's connected node as rpcServerAddr, followed by this client's rpcServerAddr if failed.
(string)
(number)
(string?
= '')
(string?
= '')
(TransactionOptions
= {})
Promise<TxnOrHash>
Same as wallet.transferName, but using this client's connected node as rpcServerAddr, followed by this client's rpcServerAddr if failed.
Promise<TxnOrHash>
Same as wallet.transferTo, but using this client's connected node as rpcServerAddr, followed by this client's rpcServerAddr if failed.
Promise<TxnOrHash>
Same as wallet.unsubscribe, but using this client's connected node as rpcServerAddr, followed by this client's rpcServerAddr if failed.
Promise<TxnOrHash>
NKN client that sends data to and receives data from other NKN clients.
(Object
= {})
Client configuration
| Name | Description |
|---|---|
options.seed string
(default undefined)
|
Secret seed (64 hex characters). If empty, a random seed will be used. |
options.identifier string
(default undefined)
|
Identifier used to differentiate multiple clients sharing the same secret seed. |
options.reconnectIntervalMin number
(default 1000)
|
Minimal reconnect interval in ms. |
options.reconnectIntervalMax number
(default 64000)
|
Maximal reconnect interval in ms. |
options.responseTimeout number
(default 5000)
|
Message response timeout in ms. Zero disables timeout. |
options.msgHoldingSeconds number
(default 0)
|
Maximal message holding time in second. Message might be cached and held by node up to this duration if destination client is not online. Zero disables cache. |
options.encrypt boolean
(default true)
|
Whether to end to end encrypt message. |
options.rpcServerAddr string
(default 'https://mainnet-rpc-node-0001.nkn.org/mainnet/api/wallet')
|
RPC server address used to join the network. |
options.tls boolean
(default undefined)
|
Force to use wss instead of ws protocol. If not defined, wss will only be used in https location. |
options.worker (boolean | function)
(default false)
|
Whether to use web workers (if available) to compute signatures. Can also be a function that returns web worker. Typically you only need to set it to a function if you import nkn-sdk as a module and are NOT using browserify or webpack worker-loader to bundle js file. The worker file is located at
lib/worker/webpack.worker.js
.
|
options.numSubClients number
(default 3)
|
Number of sub clients to create. |
options.originalClient boolean
(default false)
|
Whether to create client with no additional identifier prefix added. This client is not counted towards sub clients controlled by
options.numSubClients
.
|
options.msgCacheExpiration number
(default 300000)
|
Message cache expiration time in ms. This cache is used to remove duplicate messages received by different clients. |
options.sessionConfig Object
(default {})
|
Session configuration |
Client address, which will be identifier.pubicKeyHex if identifier is not empty, otherwise just pubicKeyHex.
Type: string
Underlying NKN clients used to send/receive data.
Type: {}
Same as wallet.deleteName, but using this multiclient's connected node as rpcServerAddr, followed by this multiclient's rpcServerAddr if failed.
(string)
(TransactionOptions
= {})
Promise<TxnOrHash>
Dial a session to a remote NKN address.
(string)
(DialOptions
= {})
Promise<ncp.Session>
Same as Wallet.getBalance, but using this multiclient's connected node as rpcServerAddr, followed by this multiclient's rpcServerAddr if failed.
(string?)
Promise<common.Amount>
Same as Wallet.getNonce, but using this multiclient's connected node as rpcServerAddr, followed by this multiclient's rpcServerAddr if failed.
Promise<number>
Same as Wallet.getRegistrant, but using this multiclient's connected node as rpcServerAddr, followed by this multiclient's rpcServerAddr if failed.
(string)
Promise<{registrant: string, expiresAt: number}>
Same as Wallet.getSubscribers, but using this multiclient's connected node as rpcServerAddr, followed by this multiclient's rpcServerAddr if failed.
Promise<{subscribers: (Array<string> | {}), subscribersInTxPool: (Array<string> | {})?}>
Same as Wallet.getSubscription, but using this multiclient's connected node as rpcServerAddr, followed by this multiclient's rpcServerAddr if failed.
Promise<{meta: string, expiresAt: number}>
Whether multiclient fails to connect to node (all underlying clients failed).
Type: boolean
Whether multiclient is ready (at least one underylying client is ready).
Type: boolean
Start accepting sessions from addresses, which could be one or an array of RegExp. If addrs is a string or string array, each element will be converted to RegExp. Session from NKN address that matches any RegExp in addrs will be allowed. When addrs is null or undefined, any address will be accepted. Each function call will overwrite previous listening addresses.
Add event listener function that will be called when at least one sub
client is connected to node. Multiple listeners will be called sequentially
in the order of added. Note that listeners added after client is connected
to node (i.e. multiclient.isReady === true) will not be called.
(ConnectHandler)
Add event listener function that will be called when all sub clients fail
to connect to node. Multiple listeners will be called sequentially in the
order of added. Note that listeners added after client fails to connect to
node (i.e. multiclient.isFailed === true) will not be called.
(ConnectFailedHandler)
Add event listener function that will be called when client receives a
message. Multiple listeners will be called sequentially in the order of
added. Can be an async function, in which case each call will wait for
promise to resolve before calling next listener function. If the first
non-null and non-undefined returned value is Uint8Array or string,
the value will be sent back as reply; if the first non-null and
non-undefined returned value is false, no reply or ACK will be sent;
if all handler functions return null or undefined, an ACK indicating
msg received will be sent back. Receiving reply or ACK will not trigger
the event listener.
(MessageHandler)
Add event listener function that will be called when client accepts a new session.
(SessionHandler)
Add event listener function that will be called when any client websocket connection throws an error. Multiple listeners will be called sequentially in the order of added.
(WsErrorHandler)
Send byte or string data to all subscribers of a topic using all available clients.
Promise<null>:
A promise that will be resolved with null when send success.
Same as wallet.registerName, but using this multiclient's connected node as rpcServerAddr, followed by this multiclient's rpcServerAddr if failed.
(string)
(TransactionOptions
= {})
Promise<TxnOrHash>
Send byte or string data to a single or an array of destination using all available clients.
Promise<ReplyData>:
A promise that will be resolved when reply or ACK from destination is received, or reject if send fail or message timeout. If dest is an array with more than one element, or
options.noReply=true
, the promise will resolve with null as soon as send success.
Same as Wallet.sendTransaction, but using this multiclient's connected node as rpcServerAddr, followed by this multiclient's rpcServerAddr if failed.
(common.pb.transaction.Transaction)
Promise<string>
Send byte or string data to a single or an array of destination using the
client with given clientID. Typically send should be used instead for
better reliability and lower latency.
Promise<ReplyData>:
A promise that will be resolved when reply or ACK from destination is received, or reject if send fail or message timeout. If dest is an array with more than one element, or
options.noReply=true
, the promise will resolve with null as soon as send success.
Same as wallet.subscribe, but using this multiclient's connected node as rpcServerAddr, followed by this multiclient's rpcServerAddr if failed.
(string)
(number)
(string?
= '')
(string?
= '')
(TransactionOptions
= {})
Promise<TxnOrHash>
Same as wallet.transferName, but using this multiclient's connected node as rpcServerAddr, followed by this multiclient's rpcServerAddr if failed.
Promise<TxnOrHash>
Same as wallet.transferTo, but using this multiclient's connected node as rpcServerAddr, followed by this multiclient's rpcServerAddr if failed.
Promise<TxnOrHash>
Same as wallet.unsubscribe, but using this multiclient's connected node as rpcServerAddr, followed by this multiclient's rpcServerAddr if failed.
Promise<TxnOrHash>
NKN client that sends data to and receives data from other NKN clients.
(Object
= {})
Wallet options.
| Name | Description |
|---|---|
options.seed string
(default undefined)
|
Secret seed (64 hex characters). If empty, a random seed will be used. |
options.password string
|
Wallet password. |
options.rpcServerAddr string
(default 'https://mainnet-rpc-node-0001.nkn.org/mainnet/api/wallet')
|
RPC server address. |
options.iv string
(default undefined)
|
AES iv, typically you should use Wallet.fromJSON instead of this field. |
options.masterKey string
(default undefined)
|
AES master key, typically you should use Wallet.fromJSON instead of this field. |
options.worker (boolean | function)
(default false)
|
Whether to use web workers (if available) to compute signatures. Can also be a function that returns web worker. Typically you only need to set it to a function if you import nkn-sdk as a module and are NOT using browserify or webpack worker-loader to bundle js file. The worker file is located at
lib/worker/webpack.worker.js
.
|
Recover wallet from JSON string and password.
(Object
= {})
Wallet options.
| Name | Description |
|---|---|
options.password string
|
Wallet password. |
options.rpcServerAddr string
(default 'https://mainnet-rpc-node-0001.nkn.org/mainnet/api/wallet')
|
RPC server address. |
options.async bool
(default false)
|
If true, return value will be a promise that resolves with the wallet object, and more importantly, the underlying scrypt computation will not block eventloop. |
(Wallet | Promise<Wallet>)
Get the next nonce of a NKN wallet address.
(string)
(Object
= {})
Get nonce options.
| Name | Description |
|---|---|
options.rpcServerAddr string
(default 'https://mainnet-rpc-node-0001.nkn.org/mainnet/api/wallet')
|
RPC server address to query nonce. |
options.txPool boolean
(default true)
|
Whether to consider transactions in txPool. If true, will return the next nonce after last nonce in txPool, otherwise will return the next nonce after last nonce in ledger. |
Promise<number>
Get the registrant's public key and expiration block height of a name. If
name is not registered, registrant will be '' and expiresAt will be 0.
Promise<{registrant: string, expiresAt: number}>
Get subscribers of a topic.
(string)
({offset: number?, limit: number?, meta: boolean?, txPool: boolean?, rpcServerAddr: string?}
= {})
Get subscribers options.
| Name | Description |
|---|---|
options.offset number
(default 0)
|
Offset of subscribers to get. |
options.limit number
(default 1000)
|
Max number of subscribers to get. This does not affect subscribers in txpool. |
options.meta boolean
(default false)
|
Whether to include metadata of subscribers in the topic. |
options.txPool boolean
(default false)
|
Whether to include subscribers whose subscribe transaction is still in txpool. Enabling this will get subscribers sooner after they send subscribe transactions, but might affect the correctness of subscribers because transactions in txpool is not guaranteed to be packed into a block. |
options.rpcServerAddr string
(default 'https://mainnet-rpc-node-0001.nkn.org/mainnet/api/wallet')
|
RPC server address. |
Promise<{subscribers: (Array<string> | {}), subscribersInTxPool: (Array<string> | {})?}>:
A promise that will be resolved with subscribers info. Note that
options.meta=false/true
will cause results to be an array (of subscriber address) or map (subscriber address -> metadata), respectively.
Create or update a NanoPay channel. NanoPay transaction does not have
nonce and will not be sent until you call sendTransaction explicitly.
(string)
(number)
NanoPay expiration height.
(number)
NanoPay id, should be unique for (this.address, toAddress) pair.
(TransactionOptions
= {})
Promise<common.pb.transaction.Transaction>
Delete a name owned by this wallet.
(string)
(TransactionOptions
= {})
Promise<TxnOrHash>
Same as Wallet.getBalance, but using this wallet's rpcServerAddr as rpcServerAddr. If address is not given, this wallet's address will be used.
(string?)
Promise<common.Amount>
Same as Wallet.getSubscribers, but using this wallet's rpcServerAddr as rpcServerAddr.
Promise<{subscribers: (Array<string> | {}), subscribersInTxPool: (Array<string> | {})?}>
Register a name for this wallet's public key at the cost of 10 NKN. The name will be valid for 1,576,800 blocks (around 1 year). Register name currently owned by this wallet will extend the duration of the name to current block height + 1,576,800. Registration will fail if the name is currently owned by another account.
(string)
(TransactionOptions
= {})
Promise<TxnOrHash>
Same as Wallet.sendTransaction, but using this wallet's rpcServerAddr as rpcServerAddr.
(common.pb.transaction.Transaction)
Promise<string>
Subscribe to a topic with an identifier for a number of blocks. Client using the same key pair and identifier will be able to receive messages from this topic. If this (identifier, public key) pair is already subscribed to this topic, the subscription expiration will be extended to current block height + duration.
(string)
(number)
Duration in unit of blocks.
(string
= '')
Client identifier.
(string
= '')
Metadata of this subscription.
(TransactionOptions
= {})
Promise<TxnOrHash>
Return the wallet object to be serialized by JSON.
WalletJson
Verify whether the password is the correct password of this wallet.
(string)
(Object
= {})
Verify password options.
| Name | Description |
|---|---|
options.async bool
(default false)
|
If true, return value will be a promise, and more importantly, the underlying scrypt computation will not block eventloop. |
(boolean | Promise<boolean>)
Amount of NKN tokens. See documentation at decimal.js.
Extends Decimal
Connect Failed handler function type.
Type: function (): void
Connect handler function type.
Type: function ({addr: string}): void
Create transaction options type.
Type: {fee: (number | string | common.Amount | null | void), attrs: string?, buildOnly: boolean?}
One or multiple NKN address type. Each NKN address should either be the form of 'identifier.publicKey', or a name registered using wallet.
Dial session options type.
Type: {dialTimeout: number?, sessionConfig: {}?}
(number?)
: Dial timeout in ms. Zero disables timeout.
({}?)
Message type.
Type: {src: string, payload: MessageData, payloadType: common.pb.payloads.PayloadType, isEncrypted: boolean, messageId: Uint8Array, noReply: boolean}
(string)
: Message sender address.
(MessageData)
: Message payload.
(nkn.pb.payloads.PayloadType)
: Message payload type.
(boolean)
: Whether message is end to end encrypted.
(Uint8Array)
: Unique message ID.
(boolean)
: Indicating no reply should be sent back as sender will not process it.
Message data type.
Type: (Uint8Array | string)
Message handler function type.
Type:
function (Message): (ReplyData | false | void | Promise<(ReplyData | false | void)>)
Publish message options type.
Type: {encrypt: boolean?, msgHoldingSeconds: number?, messageId: Uint8Array?, replyToId: Uint8Array?, txPool: boolean?, offset: number?, limit: number?}
(boolean?)
: Whether to send message to subscribers whose subscribe transaction is still in txpool. Enabling this will cause subscribers to receive message sooner after sending subscribe transaction, but might affect the correctness of subscribers because transactions in txpool is not guaranteed to be packed into a block.
(boolean?)
: Whether to end to end encrypt message.
(number?)
: Maximal message holding time in second. Message might be cached and held by node up to this duration if destination client is not online. Zero disables cache.
(Uint8Array?)
(Uint8Array?)
(number?)
(number?)
Reply data type, null means ACK instead of reply is received.
Type: (MessageData | null)
Send message options type.
Type: {responseTimeout: number?, encrypt: boolean?, msgHoldingSeconds: number?, noReply: boolean?, messageId: Uint8Array?, replyToId: Uint8Array?}
(number?)
: Message response timeout in ms. Zero disables timeout.
(boolean?)
: Whether to end to end encrypt message.
(number?)
: Maximal message holding time in second. Message might be cached and held by node up to this duration if destination client is not online. Zero disables cache.
(boolean?)
: Do not allocate any resources to wait for reply. Returned promise will resolve with null immediately when send success.
(Uint8Array?)
(Uint8Array?)
Accept session handler function type.
Type: function (ncp.Session): void
Transaction options type.
Type: any
Transaction hash if options.buildOnly=false, otherwise the transaction object.
Type: (string | common.pb.transaction.Transaction)
Websocket error handler function type.
Type: function (Event): void