Class Client

The Client class provides a low-level interface to the KeetaNet network. It handles sending messages to the KeetaNet representatives and parsing the responses.

It does not handle any of the higher-level logic of the KeetaNet network, for that there is the UserClient class.

Example

  import { Client } from '@keetanetwork/keetanet-client';
  const client = Client.fromNetwork('test');
  const blocks = await client.getChain('keeta_...');

Constructors

constructor

new Client(reps: ClientRepresentative[]): Client
Create a new instance of the Client class from the given set of representatives. This is used to create a new instance of the Client class with a custom set of representatives.

New instances should be cleaned up with the destroy() method when they are no longer needed.

In general this is not needed and the Client.fromNetwork() method should be used instead.
Parameters
- reps: ClientRepresentative[]
  The representatives to use for this instance of the Client class
  - Optionalweight?: bigint
    The weight of the representative, in terms of voting power
Returns Client
A new instance of the Client class

Properties

logger

logger: Pick<Console, "error" | "log" | "warn"> = Client.DefaultLogger

The logger to use for this instance of the Client class. This is defined by the Client.DefaultLogger property, but can be overridden by the application.

`Readonly`stats

stats: { api: { called: number; failures: number } } = ...

Stats for this instance of the client

Type declaration

api: { called: number; failures: number }
Breakdown of the API calls made
- called: number
  The total number of times the API was called
- failures: number
  The number of times the API failed

`Static` `Readonly`Builder

Builder: typeof UserClientBuilder = UserClientBuilder

A reference to the UserClientBuilder class, which is the high-level interface to building blocks.

`Static` `Readonly`Config

Config: src/config = Config

A reference to the Config class, which provides access to the KeetaNet configuration utilities.

`Static`DefaultLogger

DefaultLogger: Pick<Console, "error" | "log" | "warn"> = console

The default logger to use for new instances of the Client class. This is set to the console object by default, but can be changed by the application.

`Static`isInstance

isInstance: (obj: any, strict?: boolean) => obj is Client = ...

Check if the given object is an instance of the Client class. This is preferred to using the instanceof operator because it will work across different contexts.

Accessors

representatives

get representatives(): ClientRepresentative[]
Get the list of representatives that the CLIENT is aware of

Returns ClientRepresentative[]
The list of representatives that the client is aware of

Methods

computeBuilderBlocks

computeBuilderBlocks(
network: bigint,
builder: UserClientBuilder,
): Promise<ComputeBlocksResponse>
Compute the blocks for a given builder. This will take the pending operations and compute the blocks for them.

This will additionally mutate the state of the builder to "seal" the blocks meaning new operations will be added to new blocks.
Parameters
- network: bigint
  The network to use for the builder
- builder: UserClientBuilder
  The builder to use for the computation
Returns Promise<ComputeBlocksResponse>
The blocks that were computed

destroy

destroy(): Promise<void>
Destroy this instance of the Client class. This will clean up any resources used by the instance and stop any background tasks.

Returns Promise<void>

getAccountInfo

getAccountInfo(
account: string | GenericAccount,
): Promise<GetAccountStateAPIResponseFormatted>
Fetch the account information for a given account. This will return the account information including the current head block, representative, balances, and metadata.
Parameters
- account: string | GenericAccount
  The account to fetch the information for
Returns Promise<GetAccountStateAPIResponseFormatted>
The account information

getAccountsInfo

getAccountsInfo(
accounts: (string | GenericAccount)[],
): Promise<{ [account: string]: GetAccountStateAPIResponseFormatted }>
Fetch the account information for multiple accounts. This will return the account information including the current head block, representative, balances, and metadata for each account.
Parameters
- accounts: (string | GenericAccount)[]
  The accounts to fetch the information for
Returns Promise<{ [account: string]: GetAccountStateAPIResponseFormatted }>
The account information for each account, as an object with the account as the key and the account information as the value

getAllBalances

getAllBalances(
account: string | GenericAccount,
): Promise<GetAllBalancesResponse>
Get the balance of a given account for all tokens.
Parameters
- account: string | GenericAccount
  The account to get the balance for
Returns Promise<GetAllBalancesResponse>
An array of objects which specify the token and the balance for each token the user holds a balance for

getAllRepresentativeInfo

getAllRepresentativeInfo(): Promise<RepresentativeInfo[]>
Get a list of all representatives that the node is aware of and their weights. This will fetch the information from all representatives

Returns Promise<RepresentativeInfo[]>
The list of all representatives and their weights

getBalance

getBalance(
account: string | GenericAccount,
token: string | TokenAddress,
): Promise<bigint>
Get the balance of a given account for a given token.
Parameters
- account: string | GenericAccount
  The account to get the balance for
- token: string | TokenAddress
  The token to get the balance of for the given account
Returns Promise<bigint>
The balance of the account for the given token

getBlock

getBlock(blockhash: string | BlockHash): Promise<null | Block>
Get a block from the specified representative by its block hash.

The default mode of operation will request the block from the main ledger of the "best" representative.

The "side" ledger is a special ledger that is used to hold unpublished blocks that the given representative has learned about but which have not been published to the network. This is used as part of the voting process.
Parameters
- blockhash: string | BlockHash
  The block hash to get the block for
Returns Promise<null | Block>
The block for the given block hash or null if the block does not exist on the given ledger
getBlock(
    blockhash: string | BlockHash,
    side?: LedgerSelector,
    rep?: ClientRepresentative | "ANY",
): Promise<null | Block>
Parameters
- blockhash: string | BlockHash
  The block hash to get the block for
- Optionalside: LedgerSelector
  The side of the ledger to get the block from -- this is generally "main", but it is possible to request "side" ledger blocks
- Optionalrep: ClientRepresentative | "ANY"
  The representative to get the block from -- this is generally "ANY" in which case the best representative will be used, but it is possible to request a specific representative
Returns Promise<null | Block>
The block for the given block hash or null if the block does not exist on the given ledger

getChain

getChain(
account: string | GenericAccount,
options?: { depth?: number; startBlock?: string | BlockHash },
): Promise<Block[]>
Get the chain for a given account. This is the set of blocks that the account has created. This will return the blocks in reverse order, with the most recent block first.

This is a paginated request and may return only a partial set of blocks for a given request if there are more blocks to be fetched from the representative. The startBlock parameter can be used to fetch the next set of blocks. Once all blocks have been fetched an empty array will be returned.

The depth parameter can be used to limit the number of blocks returned. The default is to leave it up to the representative to determine the number of blocks to return. The representative may return fewer than the requested number of blocks even if there are more blocks available, except that it will always return at least 1 block if there are any blocks available.
Parameters
- account: string | GenericAccount
  The account to get the chain for
- options: { depth?: number; startBlock?: string | BlockHash } = {}
  The options to use for the request
  - Optionaldepth?: number
    The maximum number of blocks to return -- this is used to limit the number of blocks returned
  - OptionalstartBlock?: string | BlockHash
    The block hash to start from -- this is used to paginate the request
Returns Promise<Block[]>
The chain of blocks for the given account, in reverse order starting with the most recent block

getHeadBlock

getHeadBlock(account: string | GenericAccount): Promise<null | Block>
Get the current head block for a given account. This will return the entire block, or null if the account has not created any blocks.

An account with no blocks may still have a balance because other users may have sent tokens to it.
Parameters
- account: string | GenericAccount
  The account to get the head block for
Returns Promise<null | Block>
The head block for the account or null if the account has not created any blocks

getHistory

getHistory(
account: string | GenericAccount,
options?: { depth?: number; startBlocksHash?: string | VoteBlockHash },
): Promise<{ voteStaple: VoteStaple }[]>
Get the history for a given account. This is the set of vote staples that have interacted with the account. This is different from the chain in that it includes vote staples that have affected this account but are not directly created by this account.

This is a paginated request and may return only a partial set of vote staples for a given request if there are more vote staples to be fetched from the representative. The startBlocksHash parameter can be used to fetch the next set of vote staples. It can be computed from the last entry in the previous response's blocksHash field. Once all vote staples have been fetched an empty array will be returned.

The depth parameter can be used to limit the number of vote staples returned. The default is to leave it up to the representative to determine the number of vote staples to return. The representative may return fewer than the requested number of vote staples even if there are more vote staples available, except that it will always return at least 1 vote staple if there are any vote staples available.
Parameters
- account: string | GenericAccount
  The account to get the history for
- options: { depth?: number; startBlocksHash?: string | VoteBlockHash } = {}
  The options to use for the request
  - Optionaldepth?: number
    The maximum number of vote staples to return -- this is used to limit the number of vote staples returned
  - OptionalstartBlocksHash?: string | VoteBlockHash
    The block hash to start from -- this is used to paginate the request
Returns Promise<{ voteStaple: VoteStaple }[]>
The history of vote staples for the given account, in reverse order starting with the most recent vote staple

getLedgerChecksum

getLedgerChecksum(
rep?: ClientRepresentative | "ANY",
): Promise<{ checksum: string; moment: string; momentRange: number }>
Work in progress
Parameters
- rep: ClientRepresentative | "ANY" = 'ANY'
Returns Promise<{ checksum: string; moment: string; momentRange: number }>

getNetworkStatus

getNetworkStatus(
    timeout?: number,
): Promise<
    (
        | { online: false; rep: ClientRepresentative }
        | {
            ledger: {
                blockCount: number;
                moment: string;
                momentRange: number;
                representativeCount: number;
                settlementTimes: TimeStats;
                transactionCount: number;
            };
            online: true;
            rep: ClientRepresentative;
            switch: {
                incomingMessages: number;
                outgoingMessagesPeerFailure: number;
                outgoingMessagesPeerFailureUngreeted: number;
                outgoingMessagesPeerFiltered: number;
                outgoingMessagesPeerSuccess: number;
            };
        }
    )[],
>
Get the network status of all representatives
Parameters
- timeout: number = 5000
  Maximum time to wait for a response from a representative in milliseconds
Returns Promise<
    (
        | { online: false; rep: ClientRepresentative }
        | {
            ledger: {
                blockCount: number;
                moment: string;
                momentRange: number;
                representativeCount: number;
                settlementTimes: TimeStats;
                transactionCount: number;
            };
            online: true;
            rep: ClientRepresentative;
            switch: {
                incomingMessages: number;
                outgoingMessagesPeerFailure: number;
                outgoingMessagesPeerFailureUngreeted: number;
                outgoingMessagesPeerFiltered: number;
                outgoingMessagesPeerSuccess: number;
            };
        }
    )[],
>

getNodeStats

getNodeStats(): Promise<
{ ledger: LedgerStatistics; switch: P2PSwitchStatistics },
>
Get statistics about the preferred representative

Returns Promise<{ ledger: LedgerStatistics; switch: P2PSwitchStatistics }>

getPeers

getPeers(): Promise<GetPeersAPIResponse>
Get a list of peers that the node is connected to.

Returns Promise<GetPeersAPIResponse>
The list of peers that the node is connected to

getPendingBlock

getPendingBlock(account: GenericAccount): Promise<null | Block>
Get the pending block for a given account. This will return the block on the representative's side ledger that is pending vote completion. This is used to recover the pending block for an account that has not been published yet.
Parameters
- account: GenericAccount
  The account to get the pending block for
Returns Promise<null | Block>
The pending block for the account or null if there is no pending block

getSingleRepresentativeInfo

getSingleRepresentativeInfo(
rep?: string | Account<ECDSA_SECP256K1 | ED25519 | ECDSA_SECP256R1>,
): Promise<RepresentativeInfo>
Get the representative information for a given representative account
Parameters
- Optionalrep: string | Account<ECDSA_SECP256K1 | ED25519 | ECDSA_SECP256R1>
  The representative account to get the information for
Returns Promise<RepresentativeInfo>
The representative information

getTokenSupply

getTokenSupply(token: string | TokenAddress): Promise<bigint>
Get the supply of a token. This will return the total supply of the specified token.
Parameters
- token: string | TokenAddress
  The token to get the supply for
Returns Promise<bigint>
The total supply of the token

getVersion

getVersion(rep?: ClientRepresentative | "ANY"): Promise<{ node: string }>
Get the version of the node for a given representative, if no representative is specified then the version of the "best" representative will be returned.
Parameters
- rep: ClientRepresentative | "ANY" = 'ANY'
Returns Promise<{ node: string }>

getVoteStaple

getVoteStaple(blockhash: string | BlockHash): Promise<null | VoteStaple>
Get the vote staple for a given block hash. This will return the entire vote staple including the blocks whose hash has not been requested.

The default mode of operation will request the block from the main ledger of the "best" representative.

The "side" ledger is a special ledger that is used to hold unpublished votes and blocks that the given representative has learned about but which have not been published to the network. This is used as part of the voting process.
Parameters
- blockhash: string | BlockHash
  The block hash to get the vote staple for
Returns Promise<null | VoteStaple>
The vote staple for the given block hash or null if the vote staple does not exist on the given ledger
getVoteStaple(
blockhash: string | BlockHash,
side?: LedgerStorage,
): Promise<null | VoteStaple>
Parameters
- blockhash: string | BlockHash
  The block hash to get the vote staple for
- Optionalside: LedgerStorage
  The side of the ledger to get the vote staple from -- this is generally "main", but it is possible to request "side" ledger blocks
Returns Promise<null | VoteStaple>
The vote staple for the given block hash or null if the vote staple does not exist on the given ledger

getVoteStaplesAfter

getVoteStaplesAfter(
    moment: Date,
    limit?: number,
    bloomFilter?: string,
): Promise<VoteStaple[]>
Get a list of vote staples that have been added to the representative's ledger since a given moment in time.

This method is used to bootstrap a new node with the vote staples that have been added to the ledger since the last time the node was updated.

It is a paginated request and may return only a partial set of vote staples for a given request if there are more vote staples to be fetched from the representative. The moment parameter can be used to fetch the next set of vote staples, and the bloomFilter parameter can be used to tell the server not to include any duplicate vote staples that have already been sent as part of the last page in the case of a moment overlap. Once all vote staples have been fetched an empty array will be returned.

The bloom filter is constructed from the bytes of the vote staples to exclude.
Parameters
- moment: Date
  The moment in time to get the vote staples after
- Optionallimit: number
  The maximum number of vote staples to return
- OptionalbloomFilter: string
  The bloom filter to use to filter the vote staples which have already been sent
Returns Promise<VoteStaple[]>
The list of vote staples that have been added to the representative's ledger since the given moment in time

listACLsByEntity

listACLsByEntity(entity: string | GenericAccount): Promise<ACLRow[]>
List the ACLs that have been set on a given account by any other account. This will return the ACLs including the principal.
Parameters
- entity: string | GenericAccount
  The account to list the ACLs for
Returns Promise<ACLRow[]>
The ACLs for the account where the entity is the specified account

listACLsByPrincipal

listACLsByPrincipal(
account: string | GenericAccount,
entities?: (string | GenericAccount)[],
): Promise<ACLRow[]>
List the ACLs that have been set for a given account that are targeting a particular set of accounts. This will return the ACLs including the principal, entity, and permissions for each ACL entry.
Parameters
- account: string | GenericAccount
  The account to list the ACLs for
- entities: (string | GenericAccount)[] = []
  The accounts to filter the ACLs by
Returns Promise<ACLRow[]>
The ACLs for the account where the target is one of the specified accounts

listACLsByPrincipalWithInfo

listACLsByPrincipalWithInfo(
account: string | GenericAccount,
targets?: (string | GenericAccount)[],
): Promise<PrincipalACLWithInfoParsed[]>
List the ACLs that have been set for a given account that are targeting a particular set of accounts. This will return the ACLs including the principal, entity, and permissions for each ACL entry.
Parameters
- account: string | GenericAccount
  The account to list the ACLs for
- targets: (string | GenericAccount)[] = []
  The accounts to filter the ACLs by
Returns Promise<PrincipalACLWithInfoParsed[]>
The ACLs for the account where the target is one of the specified accounts with additional information

makeBuilder

makeBuilder(options: BuilderOptions): UserClientBuilder
Create a new instance of the UserClientBuilder class. This is a convenience method to create a new instance of the builder class.

The builder class is used to create blocks in a high-level way.
Parameters
- options: BuilderOptions
  The options to use for the builder
  - OptionaluserClient?: UserClientOrClientAndNetwork
    User Client or object with a client and network
Returns UserClientBuilder

recoverAccount

recoverAccount(
account: GenericAccount,
publish?: boolean,
): Promise<null | VoteStaple>
Recover any unpublished or half-publish account artifacts
Parameters
- account: GenericAccount
  Account to recover
- publish: boolean = true
  Publish the recovered staple to the network (default is true)
Returns Promise<null | VoteStaple>

transmit

transmit(
blocks: Block[],
): Promise<{ from: "direct"; publish: boolean; voteStaple: VoteStaple }>
Transmit a set of blocks to the network. This will request short votes and permanent votes for the blocks and then publish them to the network.
Parameters
- blocks: Block[]
  The blocks or UserClientBuilder to transmit
Returns Promise<{ from: "direct"; publish: boolean; voteStaple: VoteStaple }>
The result of the publish operation
transmit(
blocks: UserClientBuilder,
network: bigint,
): Promise<{ from: "direct"; publish: boolean; voteStaple: VoteStaple }>
Transmit a set of blocks to the network. This will request short votes and permanent votes for the blocks and then publish them to the network.

The blocks builder will be computed using computeBuilderBlocks and then transmitted.
Parameters
- blocks: UserClientBuilder
  The UserClientBuilder to compute and transmit transmit
- network: bigint
  The network to use for the builder (if using a builder)
Returns Promise<{ from: "direct"; publish: boolean; voteStaple: VoteStaple }>
The result of the publish operation

transmitStaple

transmitStaple(
votesAndBlocks: VoteStaple,
reps?: ClientRepresentative[],
): Promise<{ from: "direct"; publish: boolean; voteStaple: VoteStaple }>
Publish a Vote Staple to the network. This will publish the votes and blocks to the network.

If reps is not defined then the highest weight representative will be used. If reps is defined then the votes and blocks will be published to all representatives in the list.
Parameters
- votesAndBlocks: VoteStaple
  The votes and blocks to publish
- Optionalreps: ClientRepresentative[]
  The representatives to publish to
  - Optionalweight?: bigint
    The weight of the representative, in terms of voting power
Returns Promise<{ from: "direct"; publish: boolean; voteStaple: VoteStaple }>
The result of the publish operation as well as the vote staple

updateReps

updateReps(addNewReps?: boolean): Promise<void>
Update this client's view of the network representatives. This will fetch the list of representatives from the network and update the list of representatives that this client will use.
Parameters
- addNewReps: boolean = false
  If true, add any new representatives to the list of representatives
Returns Promise<void>

`Static`fromNetwork

fromNetwork(network: "production" | "staging" | "beta" | "test" | "dev"): Client
Construct a new instance of the Client class from the given network name. This will use the default representatives for the network based on the configuration.

New instances should be cleaned up with the destroy() method when they are no longer needed.

This is the recommended way to create a new instance of the Client class.
Parameters
- network: "production" | "staging" | "beta" | "test" | "dev"
  The network to use for this instance of the Client class
Returns Client
A new instance of the Client class

Class Client

Example

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Optionalweight?: bigint

Returns Client

Properties

logger

Readonlystats

Type declaration

api: { called: number; failures: number }

called: number

failures: number

Static ReadonlyBuilder

Static ReadonlyConfig

StaticDefaultLogger

StaticisInstance

Accessors

representatives

Returns ClientRepresentative[]

Methods

computeBuilderBlocks

Parameters

Returns Promise<ComputeBlocksResponse>

destroy

Returns Promise<void>

getAccountInfo

Parameters

Returns Promise<GetAccountStateAPIResponseFormatted>

getAccountsInfo

Parameters

Returns Promise<{ [account: string]: GetAccountStateAPIResponseFormatted }>

getAllBalances

Parameters

Returns Promise<GetAllBalancesResponse>

getAllRepresentativeInfo

Returns Promise<RepresentativeInfo[]>

getBalance

Parameters

Returns Promise<bigint>

getBlock

Parameters

Returns Promise<null | Block>

Parameters

Returns Promise<null | Block>

getChain

Parameters

Optionaldepth?: number

OptionalstartBlock?: string | BlockHash

Returns Promise<Block[]>

getHeadBlock

Parameters

Returns Promise<null | Block>

getHistory

Parameters

Optionaldepth?: number

OptionalstartBlocksHash?: string | VoteBlockHash

Returns Promise<{ voteStaple: VoteStaple }[]>

getLedgerChecksum

Parameters

Returns Promise<{ checksum: string; moment: string; momentRange: number }>

getNetworkStatus

Parameters

getNodeStats

Returns Promise<{ ledger: LedgerStatistics; switch: P2PSwitchStatistics }>

getPeers

Returns Promise<GetPeersAPIResponse>

getPendingBlock

Parameters

Returns Promise<null | Block>

getSingleRepresentativeInfo

Parameters

Returns Promise<RepresentativeInfo>

getTokenSupply

`Optional`weight?: bigint

`Readonly`stats

`Static` `Readonly`Builder

`Static` `Readonly`Config

`Static`DefaultLogger

`Static`isInstance

`Optional`depth?: number

`Optional`startBlock?: string | BlockHash

`Optional`depth?: number

`Optional`startBlocksHash?: string | VoteBlockHash

`Optional`userClient?: UserClientOrClientAndNetwork

`Optional`weight?: bigint

`Static`fromNetwork