Class UserClient

The UserClient class provides a high-level interface, user-oriented interface to the Keeta network. It is designed to be easy to use and handle the most common cases for applications building on top of the Keeta network.

Example

  import { UserClient } from '@keetanetwork/keetanet-client';
  import { lib as KeetaNetLib } from '@keetanetwork/keetanet-client`;
  const seed = '...'; // 64 character hex seed
  const account = KeetaNetLib.Account.fromSeed(seed, 0);
  const client = UserClient.fromNetwork('test');
  const blocks = await client.chain();

Constructors

constructor

new UserClient(config: UserClientConfig): UserClient
Construct a new instance of the UserClient class from the given configuration. 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.

The recommended way to create a new instance of the UserClient class is to use the fromNetwork method.
Parameters
- config: UserClientConfig
Returns UserClient

Properties

`Readonly`baseToken

baseToken: TokenAddress

The base token for the network this client is connected to.

`Readonly`networkAddress

networkAddress: NetworkAddress

The network address for the network this client is connected to.

`Static` `Readonly`Config

Config: src/config = Config

Reference to the Config class for the client. This is used to access the Configuration operations which may be needed for the UserClient.

`Static`isInstance

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

Determine if a given object is an instance of the UserClient class. This is preferred over using instanceof because it works across different contexts.

Accessors

account

get account(): GenericAccount
Get the account for this instance. This is the account that will be affected by the blocks and transactions that are published.

Returns GenericAccount

client

get client(): Client
Get the low-level client for this instance.

Returns Client

config

get config(): UserClientConfig
Get the configuration for this UserClient instance.

Returns UserClientConfig

network

get network(): bigint
Get the network ID for this instance. This is the network that this instance is connected to.

Returns bigint

readonly

get readonly(): boolean
Whether or not this client is "readonly". This is true if the signer is null.

Returns boolean

signer

get signer(): null | Account<ECDSA_SECP256K1 | ED25519 | ECDSA_SECP256R1>
Get the signer for this instance, if it was set. This is the account that will be used to sign blocks and transactions. If this is null, then the client is readonly and will not be able to publish blocks or transactions.

Returns null | Account<ECDSA_SECP256K1 | ED25519 | ECDSA_SECP256R1>

Methods

allBalances

allBalances(options?: UserClientOptions): Promise<GetAllBalancesResponse>
Get all the balances for the given account. See Client.getAllBalances for more information.
Parameters
- options: UserClientOptions = {}
  The options to use for the request
Returns Promise<GetAllBalancesResponse>
The balances for the account

balance

balance(
token: string | TokenAddress,
options?: UserClientOptions,
): Promise<bigint>
Get the balance for a given token for the given account. See Client.getBalance for more information.
Parameters
- token: string | TokenAddress
  The token to get the balance for
- options: UserClientOptions = {}
  The options to use for the request
Returns Promise<bigint>
The balance for the account of the given token

block

block(blockhash: string | BlockHash): Promise<null | Block>
Get a specific block by its hash. This will return the block if it is known to the network or null if it is not.
Parameters
- blockhash: string | BlockHash
  The hash of the block to get
Returns Promise<null | Block>
The block if it is known to the network or null if it is not

chain

chain(
query?: { depth?: number; startBlock?: string | BlockHash },
options?: UserClientOptionsReadOnly,
): Promise<Block[]>
Get the chain for the given account. This will return the chain as Client.getChain does.
Parameters
- Optionalquery: { depth?: number; startBlock?: string | BlockHash }
  The query to use for the chain
- options: UserClientOptionsReadOnly = {}
  The options to use for the request
Returns Promise<Block[]>
The chain for the account, paginated

computeBuilderBlocks

computeBuilderBlocks(builder: UserClientBuilder): Promise<ComputeBlocksResponse>
Compute the blocks needed to publish a given builder. This will update the state of the builder and any new operations added after this will generate new blocks.
Parameters
- builder: UserClientBuilder
  The builder to compute the blocks for
Returns Promise<ComputeBlocksResponse>
The blocks that were computed

Deprecated
Use UserClientBuilder.computeBlocks instead

destroy

destroy(): Promise<void>
Destroy this instance -- this is required to clean up all resources.

Returns Promise<void>

filterStapleOperations

filterStapleOperations(
    voteStaples: VoteStaple[],
    options?: UserClientOptionsReadOnly,
): {
    [stapleHash: string]: {
        block: Block;
        filteredOperations: BlockOperations[];
    }[];
}
Filter the given vote staples for the user client account. See UserClient.filterStapleOperations for more information.
Parameters
- voteStaples: VoteStaple[]
  The vote staples to filter
- options: UserClientOptionsReadOnly = {}
  The options to use for the request
Returns {
    [stapleHash: string]: {
        block: Block;
        filteredOperations: BlockOperations[];
    }[];
}
The filtered operations for the given account, ordered by vote staple hash, then by block, and then containing each operation

generateIdentifier

generateIdentifier(
type: NETWORK | TOKEN | STORAGE,
options?: UserClientOptions,
): Promise<PendingAccount<NETWORK | TOKEN | STORAGE>>
Generate a new identifier for the given type and publish the blocks
Parameters
- type: NETWORK | TOKEN | STORAGE
  The type of identifier to generate
- options: UserClientOptions = {}
  The options to use for the request
Returns Promise<PendingAccount<NETWORK | TOKEN | STORAGE>>
The identifier that was generated

head

head(options?: UserClientOptions): Promise<null | BlockHash>
Get the current head block for the given account. This will return the hash of the current head block for the account or null if the account has no blocks.
Parameters
- options: UserClientOptions = {}
  The options to use for the request
Returns Promise<null | BlockHash>
The hash of the current head block for the account or null if the account has no blocks

history

history(
query?: { depth?: number; startBlocksHash?: string | VoteBlockHash },
options?: UserClientOptionsReadOnly,
): Promise<{ effects: ComputedEffectOfBlocks; voteStaple: VoteStaple }[]>
Get the history for the given account. This will return the history as Client.getHistory does.
Parameters
- Optionalquery: { depth?: number; startBlocksHash?: string | VoteBlockHash }
  The query to use for the history
- options: UserClientOptionsReadOnly = {}
  The options to use for the request
Returns Promise<{ effects: ComputedEffectOfBlocks; voteStaple: VoteStaple }[]>
The history for the account, paginated

initBuilder

initBuilder(options?: UserClientOptions): UserClientBuilder
Create a new UserClientBuilder instance for this client. This is used to create a new builder for adding operations to which are then converted into the appropriate set of blocks.
Parameters
- options: UserClientOptions = {}
  The options to use for the builder
Returns UserClientBuilder
A new UserClientBuilder instance

initializeNetwork

initializeNetwork(
    initOpts: {
        addSupplyAmount: bigint;
        delegateTo?: Account<ECDSA_SECP256K1 | ED25519 | ECDSA_SECP256R1>;
        voteSerial?: bigint;
    },
    options?: UserClientOptions,
): Promise<{ from: "direct"; publish: boolean; voteStaple: VoteStaple }>
Generate and publish the blocks needed to initialize a new network with the given parameters.

This is generally only needed once per network and is used to initialize the network with a base token and a representative in order to start-up the network.
Parameters
- initOpts: {
      addSupplyAmount: bigint;
      delegateTo?: Account<ECDSA_SECP256K1 | ED25519 | ECDSA_SECP256R1>;
      voteSerial?: bigint;
  }
  The options to use for the initialization
  - addSupplyAmount: bigint
    The amount of supply to add to the network of the base token
  - OptionaldelegateTo?: Account<ECDSA_SECP256K1 | ED25519 | ECDSA_SECP256R1>
    The representative account to delegate the supply to
  - OptionalvoteSerial?: bigint
    The serial number to use for the vote -- must never be reused by the representative
- options: UserClientOptions = {}
  The options to use for the request
Returns Promise<{ from: "direct"; publish: boolean; voteStaple: VoteStaple }>
The vote staple that was generated and whether it was able to be published

listACLsByEntity

listACLsByEntity(options?: UserClientOptionsReadOnly): Promise<ACLRow[]>
List ACLs for the given account. This will return the ACLs the account has set. See Client.listACLsByEntity for more information.
Parameters
- options: UserClientOptionsReadOnly = {}
  The options to use for the request
Returns Promise<ACLRow[]>
The ACLs for the account

listACLsByPrincipal

listACLsByPrincipal(
entities?: (string | GenericAccount)[],
options?: UserClientOptionsReadOnly,
): Promise<ACLRow[]>
List ACLs for the given account. This will return the ACLs that relate to specified entities. See Client.listACLsByPrincipal for more information.
Parameters
- entities: (string | GenericAccount)[] = []
  The list of entities to get the ACLs for
- options: UserClientOptionsReadOnly = {}
  The options to use for the request
Returns Promise<ACLRow[]>
The ACLs for the account

listACLsByPrincipalWithInfo

listACLsByPrincipalWithInfo(
options?: UserClientOptionsReadOnly,
): Promise<PrincipalACLWithInfoParsed[]>
List ACLs that others have set for the given account. See Client.listACLsByEntity for more information.
Parameters
- options: UserClientOptionsReadOnly = {}
  The options to use for the request
Returns Promise<PrincipalACLWithInfoParsed[]>
The ACLs applied for the account

modTokenSupplyAndBalance

modTokenSupplyAndBalance(
    amount: bigint,
    token: TokenAddress,
    options?: UserClientOptionsReadOnly,
): Promise<
    | { from: "direct"; publish: boolean; voteStaple: VoteStaple }
    | { blocks: Block[]; from: "publish-aid"; publish: boolean },
>
Modify both the token supply (mint/burn) and account balance for a given account of a given token.

This will mint if a positive amount is given and burn if a negative amount is given, and the add or subtract the same amount from the account balance.
Parameters
- amount: bigint
  The amount to add or subtract from the token supply and account balance
- token: TokenAddress
  The token to modify the supply and balance for
- options: UserClientOptionsReadOnly = {}
  The options to use for the request
Returns Promise<
| { from: "direct"; publish: boolean; voteStaple: VoteStaple }
| { blocks: Block[]; from: "publish-aid"; publish: boolean },
>
The vote staple that was generated and whether it was able to be published

off

off(id: symbol): void
Cancel a previously registered callback from on
Parameters
- id: symbol
Returns void

on

on<EventName extends "change">(
event: EventName,
handler: UserClientListenerTypes[EventName],
): symbol
Register a callback for change messages and set up a websocket filtered to our account only. Also set up long timeout polling for changes in case the websocket misses a change update Check that parameters of function complies with respective event function
Type Parameters
- EventName extends "change"
Parameters
- event: EventName
- handler: UserClientListenerTypes[EventName]
Returns symbol

pendingBlock

pendingBlock(options?: UserClientOptionsReadOnly): Promise<null | Block>
Get the pending block for the given account. This will return any side-ledger block for that account, or null if there is no pending block.
Parameters
- options: UserClientOptionsReadOnly = {}
  The options to use for the request
Returns Promise<null | Block>
The pending block for the account or null if there is no pending block

publishBuilder

publishBuilder(
    builder: UserClientBuilder,
): Promise<
    | { from: "direct"; publish: boolean; voteStaple: VoteStaple }
    | { blocks: Block[]; from: "publish-aid"; publish: boolean },
>
Compute the blocks needed to publish a given builder and then publish those blocks to the network. The builder should generally not be used after this method is called as the blocks will be published and the builder will be in an invalid state.

In general, the UserClientBuilder.publish method should be used instead of this one.
Parameters
- builder: UserClientBuilder
  The builder to publish
Returns Promise<
| { from: "direct"; publish: boolean; voteStaple: VoteStaple }
| { blocks: Block[]; from: "publish-aid"; publish: boolean },
>
The vote staple that was generated and whether it was able to be published

recover

recover(
publish?: boolean,
options?: UserClientOptions,
): Promise<null | VoteStaple>
Recover any unpublished or half-publish account artifacts
Parameters
- Optionalpublish: boolean
  Publish the recovered staple to the network (default: true)
- options: UserClientOptions = {}
  User client options (common options)
Returns Promise<null | VoteStaple>

send

send(
    to: string | GenericAccount,
    amount: number | bigint,
    token: string | TokenAddress,
    external?: string,
    options?: UserClientOptions,
    retries?: number,
): Promise<void>
Send some tokens from this account to another account.

If an external identifier is provided, it will be included in the Send operation and can be used by the recipient to identify the transaction.
Parameters
- to: string | GenericAccount
  The account to send the tokens to
- amount: number | bigint
  The amount of tokens to send (in base units)
- token: string | TokenAddress
  The token to send
- Optionalexternal: string
  The external identifier to use for the transaction
- options: UserClientOptions = {}
  The options to use for the request
- retries: number = 0
  The number of times to retry the request if it fails
Returns Promise<void>
The vote staple that was generated and whether it was able to be published

setInfo

setInfo(
    info: AccountInfo,
    options?: UserClientOptions,
): Promise<
    | { from: "direct"; publish: boolean; voteStaple: VoteStaple }
    | { blocks: Block[]; from: "publish-aid"; publish: boolean },
>
Set the metadata for an account and publish the blocks to the network.
Parameters
- info: AccountInfo
  The account info to set
- options: UserClientOptions = {}
  The options to use for the request
Returns Promise<
| { from: "direct"; publish: boolean; voteStaple: VoteStaple }
| { blocks: Block[]; from: "publish-aid"; publish: boolean },
>
The vote staple that was generated and whether it was able to be published

state

state(
options?: UserClientOptionsReadOnly,
): Promise<GetAccountStateAPIResponseFormatted>
Get the current live state of the account. This will return the current state of the account as Client.getAccountInfo does.
Parameters
- options: UserClientOptionsReadOnly = {}
  The options to use for the request
Returns Promise<GetAccountStateAPIResponseFormatted>
The current state of the account

updatePermissions

updatePermissions(
    principal: string | GenericAccount,
    permissions: AcceptedPermissionTypes,
    target?: string | GenericAccount,
    method?: AdjustMethod,
    options?: UserClientOptions,
): Promise<
    | { from: "direct"; publish: boolean; voteStaple: VoteStaple }
    | { blocks: Block[]; from: "publish-aid"; publish: boolean },
>
Update the permissions for a given account. This will publish the changes to the network.
Parameters
- principal: string | GenericAccount
  The account to update the permissions regarding for this account
- permissions: AcceptedPermissionTypes
  The permissions to set for the account
- Optionaltarget: string | GenericAccount
  The account to set the permissions for, if applicable for this permission
- Optionalmethod: AdjustMethod
  The method to use for the permission, defaults to SET
- options: UserClientOptions = {}
  The options to use for the request
Returns Promise<
| { from: "direct"; publish: boolean; voteStaple: VoteStaple }
| { blocks: Block[]; from: "publish-aid"; publish: boolean },
>
The vote staple that was generated and whether it was able to be published

`Static`filterStapleOperations

filterStapleOperations(
    voteStaples: VoteStaple[],
    account: GenericAccount,
): {
    [stapleHash: string]: {
        block: Block;
        filteredOperations: BlockOperations[];
    }[];
}
Helper method to filter a list of vote staples into a list of blocks and operations that are related to a given account.
Parameters
- voteStaples: VoteStaple[]
  The list of vote staples to filter
- account: GenericAccount
  The account to search for operations related to
Returns {
    [stapleHash: string]: {
        block: Block;
        filteredOperations: BlockOperations[];
    }[];
}
An array of filtered operations for the given account, ordered by vote staple hash, then by block, and then containing each operation

`Static`fromNetwork

fromNetwork(
    network: "production" | "staging" | "beta" | "test" | "dev",
    signer: null | Account<ECDSA_SECP256K1 | ED25519 | ECDSA_SECP256R1>,
    options?: UserClientOptions,
): UserClient
Construct a new instance of the UserClient 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 UserClient class.
Parameters
- network: "production" | "staging" | "beta" | "test" | "dev"
  The network to use for this instance of the UserClient class
- signer: null | Account<ECDSA_SECP256K1 | ED25519 | ECDSA_SECP256R1>
  The account to use for this instance of the UserClient class, or null if this is a read-only client
- Optionaloptions: UserClientOptions
  The options to use for this instance of the UserClient class
  - Optionalaccount?: GenericAccount
    The account to use for the user client, if this is not supplied then the signer will be used (if available) otherwise this there will be no account and some operations may not be available.
  - OptionalpublishAidURL?: string
    If using the publish aid (see ['usePublishAid']) the URL to use.
    
    The default depends on the network configuration.
  - OptionalusePublishAid?: boolean
    Use the "publish aid" service to publish blocks.
    
    This service handles requesting short votes and permanent votes and publishing to the network. This can reduce latency for clients far away from representatives because they only need to wait for a single response instead of multiple round-trips.
    
    The default is false.
Returns UserClient
A new instance of the UserClient class

`Static`fromSimpleSingleRep

fromSimpleSingleRep(
    hostname: string,
    ssl: boolean,
    repKey: string | Account<ECDSA_SECP256K1 | ED25519 | ECDSA_SECP256R1>,
    networkID: bigint,
    networkAlias: "production" | "staging" | "beta" | "test" | "dev",
    signer: null | Account<ECDSA_SECP256K1 | ED25519 | ECDSA_SECP256R1>,
    options?: UserClientOptions,
): UserClient
Create an instance of the UserClient class from a specific representative. This will use the given representative to initialize the connection to the network, however it will find other representatives to use for the network as well.

This is useful for testing and development purposes, but in general it is recommended to use the fromNetwork method to create a new instance of the UserClient class.
Parameters
- hostname: string
- ssl: boolean
- repKey: string | Account<ECDSA_SECP256K1 | ED25519 | ECDSA_SECP256R1>
- networkID: bigint
- networkAlias: "production" | "staging" | "beta" | "test" | "dev"
- signer: null | Account<ECDSA_SECP256K1 | ED25519 | ECDSA_SECP256R1>
- Optionaloptions: UserClientOptions
Returns UserClient

`Static`getConfigFromNetwork

getConfigFromNetwork(
network: "production" | "staging" | "beta" | "test" | "dev",
options?: UserClientOptions,
): Omit<UserClientConfig, "signer">
A helper method to get the configuration from the network alias and options. This will use the default representatives for the network based on the configuration.
Parameters
- network: "production" | "staging" | "beta" | "test" | "dev"
  The network to use to generate the configuration
- Optionaloptions: UserClientOptions
  The options to use to generate the configuration
Returns Omit<UserClientConfig, "signer">
The configuration object for the UserClient class

Class UserClient

Example

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns UserClient

Properties

ReadonlybaseToken

ReadonlynetworkAddress

Static ReadonlyConfig

StaticisInstance

Accessors

account

Returns GenericAccount

client

Returns Client

config

Returns UserClientConfig

network

Returns bigint

readonly

Returns boolean

signer

Returns null | Account<ECDSA_SECP256K1 | ED25519 | ECDSA_SECP256R1>

Methods

allBalances

Parameters

Returns Promise<GetAllBalancesResponse>

balance

Parameters

Returns Promise<bigint>

block

Parameters

Returns Promise<null | Block>

chain

Parameters

Returns Promise<Block[]>

computeBuilderBlocks

Parameters

Returns Promise<ComputeBlocksResponse>

Deprecated

destroy

Returns Promise<void>

filterStapleOperations

Parameters

Returns { [stapleHash: string]: { block: Block; filteredOperations: BlockOperations[]; }[];}

generateIdentifier

Parameters

Returns Promise<PendingAccount<NETWORK | TOKEN | STORAGE>>

head

Parameters

Returns Promise<null | BlockHash>

history

Parameters

Returns Promise<{ effects: ComputedEffectOfBlocks; voteStaple: VoteStaple }[]>

initBuilder

Parameters

Returns UserClientBuilder

initializeNetwork

Parameters

addSupplyAmount: bigint

OptionaldelegateTo?: Account<ECDSA_SECP256K1 | ED25519 | ECDSA_SECP256R1>

OptionalvoteSerial?: bigint

Returns Promise<{ from: "direct"; publish: boolean; voteStaple: VoteStaple }>

listACLsByEntity

Parameters

Returns Promise<ACLRow[]>

listACLsByPrincipal

Parameters

Returns Promise<ACLRow[]>

listACLsByPrincipalWithInfo

Parameters

Returns Promise<PrincipalACLWithInfoParsed[]>

modTokenSupplyAndBalance

Parameters

`Readonly`baseToken

`Readonly`networkAddress

`Static` `Readonly`Config

`Static`isInstance

Returns {
[stapleHash: string]: {
block: Block;
filteredOperations: BlockOperations[];
}[];
}

`Optional`delegateTo?: Account<ECDSA_SECP256K1 | ED25519 | ECDSA_SECP256R1>

`Optional`voteSerial?: bigint

Returns Promise<
| { from: "direct"; publish: boolean; voteStaple: VoteStaple }
| { blocks: Block[]; from: "publish-aid"; publish: boolean },
>

Returns Promise<
| { from: "direct"; publish: boolean; voteStaple: VoteStaple }
| { blocks: Block[]; from: "publish-aid"; publish: boolean },
>

Returns Promise<
| { from: "direct"; publish: boolean; voteStaple: VoteStaple }
| { blocks: Block[]; from: "publish-aid"; publish: boolean },
>

Returns Promise<
| { from: "direct"; publish: boolean; voteStaple: VoteStaple }
| { blocks: Block[]; from: "publish-aid"; publish: boolean },
>

`Static`filterStapleOperations

Returns {
[stapleHash: string]: {
block: Block;
filteredOperations: BlockOperations[];
}[];
}

`Static`fromNetwork

`Optional`account?: GenericAccount

`Optional`publishAidURL?: string

`Optional`usePublishAid?: boolean

`Static`fromSimpleSingleRep

`Static`getConfigFromNetwork