@keetanetwork/keetanet-client 0.10.4 → 0.12.0

package/api/index.d.ts

@@ -7,17 +7,13 @@ declare const rootTree: {
                 blocks: string[];
                 votes?: string[];
             }) => Promise<{
-                vote: import("../lib/vote").VoteJSONOutput & {
-                    $binary: string;
-                };
+                vote: import("../lib/vote").Vote;
             }>;
         };
         ':blockhash': {
             GET: (request: APIRequest, blockhash: string) => Promise<{
-                blockhash: string;
-                votes: (import("../lib/vote").VoteJSONOutput & {
-                    $binary: string;
-                })[] | null;
+                blockhash: import("../lib/block").BlockHash;
+                votes: import("../lib/vote").Vote[] | null;
             }>;
         };
     };
@@ -125,6 +121,26 @@ declare const rootTree: {
                             }>;
                         };
                     };
+                    certificates: {
+                        GET: (request: APIRequest, account: string) => Promise<{
+                            account: string;
+                            certificates: {
+                                certificate: string;
+                                intermediates: string[] | null;
+                            }[];
+                        }>;
+                        ':certificateHash': {
+                            GET: (request: APIRequest, account: string, certificateHash: string) => Promise<{
+                                certificate: string;
+                                intermediates: string[] | null;
+                                account: string;
+                            } | {
+                                certificate: null;
+                                intermediates: null;
+                                account: string;
+                            }>;
+                        };
+                    };
                     pending: {
                         GET: (request: APIRequest, account: string) => Promise<{
                             account: string;

package/api/node.d.ts

@@ -10,7 +10,10 @@ import type { VoteStaple } from '../lib/vote';
 interface GetPeersAPIResponse {
     kind: NodeKind;
     key?: string;
-    endpoint?: string;
+    endpoints?: {
+        p2p: string;
+        api: string;
+    };
     signature?: string;
 }
 interface GetAccountChainAPIResponse {
@@ -56,7 +59,7 @@ interface PrincipalACLWithInfoResponse {
 }
 interface GetAccountHistoryResponse {
     history: {
-        voteStaple: ReturnType<typeof VoteStaple['toJSONSerializable']>;
+        voteStaple: VoteStaple;
         '$id': string;
         '$timestamp': string;
     }[];
@@ -97,6 +100,22 @@ declare function getAllBalances(request: APIRequest, account: string | GenericAc
     account: GenericAccount;
     balances: GetAllBalancesResponse;
 }>;
+declare function getAccountCertificates(request: APIRequest, account: string): Promise<{
+    account: string;
+    certificates: {
+        certificate: string;
+        intermediates: string[] | null;
+    }[];
+}>;
+declare function getCertificateByHash(request: APIRequest, account: string, certificateHash: string): Promise<{
+    certificate: string;
+    intermediates: string[] | null;
+    account: string;
+} | {
+    certificate: null;
+    intermediates: null;
+    account: string;
+}>;
 declare function getAccountState(request: APIRequest, pubKey: string): Promise<AccountState | AccountStateError>;
 declare function getBlockByHash(request: APIRequest, blockhash: string): Promise<{
     blockhash: string;
@@ -192,6 +211,12 @@ declare const _default: {
                         GET: typeof listACLsByPrincipal;
                     };
                 };
+                certificates: {
+                    GET: typeof getAccountCertificates;
+                    ':certificateHash': {
+                        GET: typeof getCertificateByHash;
+                    };
+                };
                 pending: {
                     GET: typeof getAccountPendingBlock;
                 };

package/api/vote.d.ts

@@ -1,18 +1,16 @@
 import type { APIRequest } from '.';
 import KeetaNet from '../lib';
 type Vote = InstanceType<typeof KeetaNet['Vote']>;
-type VoteJSONOutput = ReturnType<Vote['toJSON']> & {
-    '$binary': string;
-};
+type BlockHash = InstanceType<typeof KeetaNet['Block']['Hash']>;
 declare function createNewVote(request: APIRequest, payload: {
     blocks: string[];
     votes?: string[];
 }): Promise<{
-    vote: VoteJSONOutput;
+    vote: Vote;
 }>;
 declare function getVotes(request: APIRequest, blockhash: string): Promise<{
-    blockhash: string;
-    votes: VoteJSONOutput[] | null;
+    blockhash: BlockHash;
+    votes: Vote[] | null;
 }>;
 declare const _default: {
     _root: {

package/client/builder.d.ts

@@ -2,10 +2,12 @@ import type { GenericAccount, IdentifierKeyAlgorithm } from '../lib/account';
 import { Account, AccountKeyAlgorithm } from '../lib/account';
 import type { AdjustMethod, BlockHash } from '../lib/block';
 import { Block } from '../lib/block';
+import type { BlockJSONOperations } from '../lib/block/operations';
 import type { AccountInfo } from '../lib/ledger/types';
 import type { AcceptedPermissionTypes } from '../lib/permissions';
 import type { UserClient } from '.';
 import { Permissions } from '../lib/permissions';
+import { Certificate, CertificateBundle } from '../lib/utils/certificate';
 type GetPrevFunction = (acct: GenericAccount | string) => Promise<BlockHash | string | null | undefined>;
 interface AccountSignerOptions {
     account: GenericAccount;
@@ -48,6 +50,9 @@ interface IdentifierCreateRequest {
 }
 type AccountOrPending<Type extends AccountKeyAlgorithm = AccountKeyAlgorithm> = Account<Type> | PendingAccount<Type>;
 type TokenOrPending = AccountOrPending<AccountKeyAlgorithm.TOKEN>;
+export type ManageCertificateMethod = Extract<BlockJSONOperations, {
+    type: typeof Block['OperationType']['MANAGE_CERTIFICATE'];
+}>['method'];
 export interface PendingOperations {
     receive?: {
         otherParty: AccountOrPending;
@@ -69,6 +74,11 @@ export interface PendingOperations {
         amount: bigint;
         token: TokenOrPending;
     }[];
+    modifyCertificates?: {
+        method: ManageCertificateMethod;
+        certificate: Certificate;
+        intermediateCertificates: CertificateBundle | null;
+    }[];
     permissionsChanges?: PerAccount<PerAccount<{
         method: AdjustMethod;
         permissions: Permissions;
@@ -99,6 +109,11 @@ export interface PendingOperationsJSON {
         amount: string;
         token: string;
     }[];
+    modifyCertificates?: {
+        method: ManageCertificateMethod;
+        certificate: string;
+        intermediateCertificates: string | null;
+    }[];
     permissionsChanges?: PerAccount<PerAccount<{
         method: AdjustMethod;
         permissions: [string, string];
@@ -138,6 +153,7 @@ export declare class PendingAccount<AccountType extends AccountKeyAlgorithm = Ac
     static GetValue<T extends AccountKeyAlgorithm>(data: AccountOrPending<T>): Account<T>;
     set account(account: Account<AccountType>);
     get account(): Account<AccountType>;
+    toJSON(): Account<AccountType>;
 }
 type AllPending = [AccountSignerOptions, PendingOperations][];
 export declare class UserClientBuilder {
@@ -158,6 +174,7 @@ export declare class UserClientBuilder {
     send(recipient: AccountOrPending, amount: bigint, token: TokenOrPending, external?: string, options?: BuilderBlockOptions): void;
     receive(from: AccountOrPending, amount: bigint, token: TokenOrPending, exact?: boolean, forward?: GenericAccount, options?: BuilderBlockOptions): void;
     updatePermissions(principal: GenericAccount, permissions: AcceptedPermissionTypes, target?: GenericAccount, method?: AdjustMethod, options?: BuilderBlockOptions): void;
+    modifyCertificate(method: ManageCertificateMethod, certificate: Certificate, intermediateCertificates?: CertificateBundle | null, options?: BuilderBlockOptions): void;
     modifyTokenSupply(amount: bigint, options?: BuilderBlockOptions): void;
     modifyTokenBalance(token: TokenOrPending, amount: bigint, isSet?: boolean, options?: BuilderBlockOptions): void;
     setInfo(info: AccountInfo, options?: BuilderBlockOptions): void;

package/client/client_common_tests.d.ts

@@ -4,6 +4,7 @@ import type { Networks } from '../config';
 import { AccountKeyAlgorithm } from '../lib/account';
 import type Account from '../lib/account';
 import { UserClient } from '.';
+import { type CreateTestNodeOptions } from '../lib/utils/helper_testing';
 import { toJSONSerializable } from '../lib/utils/conversion';
 import { KeetaNetError as KeetaError } from '../lib/error';
 export type ClientParams = {
@@ -21,6 +22,7 @@ export type ClientParams = {
 export type NodeCreationOptions = {
     p2pTested?: boolean;
     count?: number;
+    customNodeOptions?: Omit<CreateTestNodeOptions, 'peerNodes' | 'enableP2P' | 'initialTrustedAccount'>[];
 };
 export declare function setup(options?: NodeCreationOptions): Promise<{
     trustedKey: Account<AccountKeyAlgorithm.ECDSA_SECP256K1>;
@@ -37,7 +39,8 @@ export declare function setup(options?: NodeCreationOptions): Promise<{
 declare function runBasicTests(nodes: LocalNode[], userClient: UserClient, trustedClient: UserClient, params: ClientParams, expect: any, _ignoreExpectErrorCode: any): Promise<void>;
 declare function runBuilderStorageTests(_ignoreNodes: LocalNode[], userClient: UserClient, trustedClient: UserClient, params: ClientParams, expect: any, ExpectErrorCode: any): Promise<void>;
 declare function runRecoverAccountTest(nodes: LocalNode[], userClient: UserClient, trustedClient: UserClient, params: ClientParams, expect: any, ExpectErrorCode: any): Promise<void>;
-declare function runNonNodeTests(_ignore_nodes: LocalNode[], _ignore_userClient: UserClient, _ignore_trustedClient: UserClient, _ignore_params: ClientParams, expect: any, _ignore_ExpectErrorCode: any): Promise<void>;
+declare function runNonNodeTests(_ignore_nodes: LocalNode[], _ignore_userClient: UserClient, _ignore_trustedClient: UserClient, _ignore_params: ClientParams, expect: any, ExpectErrorCode: any): Promise<void>;
+declare function runErrorTests(nodes: LocalNode[], userClientAccount1: UserClient, trustedClient: UserClient, params: ClientParams, expect: any, ExpectErrorCode: any): Promise<void>;
 export declare const clientTests: {
     'Basic Client Tests': {
         test: typeof runBasicTests;
@@ -68,6 +71,30 @@ export declare const clientTests: {
             count: number;
         };
     };
+    'Client Error Tests': {
+        test: typeof runErrorTests;
+        options: {
+            p2pTested: boolean;
+            count: number;
+            customNodeOptions: ({
+                readonly ledger: {
+                    readonly ledgerWriteMode: "no-voting";
+                };
+            } | {
+                readonly ledger: {
+                    readonly ledgerWriteMode: "read-write";
+                };
+            } | {
+                readonly ledger: {
+                    readonly ledgerWriteMode: "bootstrap-only";
+                };
+            } | {
+                readonly ledger: {
+                    readonly ledgerWriteMode: "read-only";
+                };
+            })[];
+        };
+    };
 };
 export declare const KeetaNetError: typeof KeetaError;
 export { toJSONSerializable };

package/client/index-browser.d.ts

@@ -15,13 +15,15 @@ import type { AdjustMethod } from '../lib/block';
 import Block, { BlockHash } from '../lib/block';
 import type { P2PSwitchStatistics } from '../lib/p2p';
 import * as Config from '../config';
-import type { BuilderOptions } from './builder';
+import type { BuilderOptions, ManageCertificateMethod } from './builder';
 import { UserClientBuilder } from './builder';
 import { KeetaNetError } from '../lib/error';
 import type { AccountInfo, GetAllBalancesResponse, ACLRow, LedgerStatistics } from '../lib/ledger/types';
 import type { LedgerSelector, LedgerStorage } from '../lib/ledger';
 import type { AcceptedPermissionTypes } from '../lib/permissions';
 import { type BlockOperations } from '../lib/block/operations';
+import { Certificate } from '../lib/utils/certificate';
+import { CertificateBundle, type CertificateHash } from '../lib/utils/certificate';
 type Vote = InstanceType<typeof KeetaNet['Vote']>;
 type VoteStaple = InstanceType<typeof KeetaNet['Vote']['Staple']>;
 type VoteBlocksHash = Vote['blocksHash'];
@@ -113,6 +115,10 @@ interface PrincipalACLWithInfoParsed {
      */
     balances: GetAllBalancesResponse;
 }
+interface CertificateWithIntermediatesResponse {
+    certificate: Certificate;
+    intermediates: CertificateBundle | null;
+}
 /**
  */
 interface UserClientOptions {
@@ -217,6 +223,11 @@ export declare class Client {
      * by the application.
      */
     logger: Pick<Console, "error" | "log" | "warn">;
+    /**
+     * Indication of whether or not this client has been destroyed.
+     */
+    destroyed: boolean;
+    private static updateRepsInterval;
     /**
      * Stats for this instance of the client
      */
@@ -277,6 +288,14 @@ export declare class Client {
      * any resources used by the instance and stop any background tasks.
      */
     destroy(): Promise<void>;
+    /**
+     * This enables the use of `using` to automatically clean up the
+     * instance of the {@link Client} class when it is no longer needed.
+     *
+     * It calls the {@link destroy}() method to clean up the instance when
+     * it goes out of scope.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
     /**
      * Create a new instance of the {@link UserClientBuilder} class.  This
      * is a convenience method to create a new instance of the builder
@@ -424,6 +443,23 @@ export declare class Client {
      *         for each token the user holds a balance for
      */
     getAllBalances(account: GenericAccount | string): Promise<GetAllBalancesResponse>;
+    /**
+     * List all certificates for a given account.  This will return
+     * all certificates that have been added by and issued to the account, including
+     * any intermediate certificates that have been issued.
+     * @param account Account to lookup certificates for
+     * @returns An array of objects containing the certificate and any intermediates associated with the specified account
+     */
+    getAllCertificates(account: GenericAccount | string): Promise<CertificateWithIntermediatesResponse[]>;
+    /**
+     * Get a certificate by its hash for a given account.  This will return
+     * the certificate and any intermediate certificates that have been issued.
+     *
+     * @param account The account to get the certificate for
+     * @param certificateHash The hash of the certificate to get
+     * @return The certificate and any intermediates or null if the certificate was not found
+     */
+    getCertificateByHash(account: GenericAccount | string, certificateHash: string | CertificateHash): Promise<CertificateWithIntermediatesResponse | null>;
     /**
      * 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.
@@ -432,10 +468,11 @@ export declare class Client {
      * may have sent tokens to it.
      *
      * @param account The account to get the head block for
+     * @param rep The representative to get the head block from -- this is generally "ANY" in which case the best representative will be used, but it is possible to request a specific representative
      * @return The head block for the account or null if the account has
      *         not created any blocks
      */
-    getHeadBlock(account: GenericAccount | string): Promise<Block | null>;
+    getHeadBlock(account: GenericAccount | string, rep?: Config.Representative | 'ANY'): Promise<Block | null>;
     /**
      * Get a block from the specified representative by its block hash.
      *
@@ -477,9 +514,10 @@ export declare class Client {
     /**
      * @param blockhash The block hash to get the vote staple for
      * @param side The side of the ledger to get the vote staple from -- this is generally "main", but it is possible to request "side" ledger blocks
+     * @param rep The representative to get the staple from -- this is generally "ANY" in which case the best representative will be used, but it is possible to request a specific representative
      * @return The vote staple for the given block hash or null if the vote staple does not exist on the given ledger
      */
-    getVoteStaple(blockhash: BlockHash | string, side?: LedgerStorage): Promise<VoteStaple | null>;
+    getVoteStaple(blockhash: BlockHash | string, side?: LedgerStorage, rep?: Config.Representative): Promise<VoteStaple | null>;
     /**
      * 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
@@ -501,11 +539,13 @@ export declare class Client {
      * @param account The account to get the chain for
      * @param options The options to use for the request
      * @param options.startBlock The block hash to start from -- this is used to paginate the request
+     * @param options.endBlock The block hash to stop on -- this is used to limit the chain to a specific range of blocks
      * @param options.depth The maximum number of blocks to return -- this is used to limit the number of blocks returned
      * @return The chain of blocks for the given account, in reverse order starting with the most recent block
      */
     getChain(account: GenericAccount | string, options?: {
         startBlock?: BlockHash | string;
+        endBlock?: BlockHash | string;
         depth?: number;
     }): Promise<Block[]>;
     /**
@@ -586,6 +626,7 @@ export declare class Client {
             blockCount: number;
             transactionCount: number;
             representativeCount: number;
+            db: import("../lib/stats").DbStats;
             settlementTimes: import("../lib/stats").TimeStats;
         };
         switch: {
@@ -643,6 +684,16 @@ export declare class Client {
      *         pending block
      */
     getPendingBlock(account: GenericAccount): Promise<Block | null>;
+    /**
+     * Get the successor block for a given block.  This will return the
+     * block on the representative's ledger that comes after the given block
+     *
+     * @param blockOrHash The block or hash to get the successor for
+     * @param rep The representative account to get the successor block from
+     * @return The successor block for the block or null if there is no
+     *         successor block
+     */
+    getSuccessorBlock(blockOrHash: Block | BlockHash | string, rep?: Config.Representative | 'ANY'): Promise<Block | null>;
     /**
      * Recover any unpublished or half-publish account artifacts
      *
@@ -669,6 +720,11 @@ interface UserClientListenerTypes {
     change: ((data: GetAccountStateAPIResponseFormatted) => void);
 }
 type UserClientEventName = keyof UserClientListenerTypes;
+interface UserClientListenerOptions {
+    change: {
+        fallbackFrequency?: number;
+    };
+}
 /**
  *   The UserClient class provides a high-level interface, user-oriented
  *   interface to the Keeta network.  It is designed to be easy to use and
@@ -704,6 +760,10 @@ export declare class UserClient {
      * The network address for the network this client is connected to.
      */
     readonly networkAddress: NetworkAddress;
+    /**
+     * Indication of whether or not this client has been destroyed.
+     */
+    destroyed: boolean;
     /**
      * Create an instance of the UserClient class from a specific
      * representative.  This will use the given representative to
@@ -879,6 +939,59 @@ export declare class UserClient {
         publish: boolean;
         from: "publish-aid";
     }>;
+    /**
+     * Add a certificate for a account
+     *
+     * @param method The method to use for modifying the certificate: `ADD` for this signature
+     * @param certificate The certificate to modify, this should be a {@link Certificate} instance.
+     * @param intermediates The certificate bundle containing the intermediate certificates, or null if there are no intermediates.
+     * @param options The options to use for the request
+     * @returns The vote staple that was generated and whether it was able to be published
+     */
+    modifyCertificate(method: AdjustMethod.ADD, certificate: Certificate, intermediates: CertificateBundle | null, options?: UserClientOptions): Promise<Awaited<ReturnType<typeof this.publishBuilder>>>;
+    /**
+     * Remove a certificate from a account
+     *
+     * @param method The method to use for modifying the certificate, either `ADD` or `REMOVE`
+     * @param certificate The certificate to remove, this should be a {@link Certificate} or a {@link CertificateHash} instance.
+     * @param intermediates Because the `SUBTRACT` method is used to remove a certificate, intermediates are not needed and should not be defined.
+     * @param options The options to use for the request
+     * @returns The vote staple that was generated and whether it was able to be published
+     */
+    modifyCertificate(method: AdjustMethod.SUBTRACT, certificate: Certificate | CertificateHash, intermediates?: undefined, options?: UserClientOptions): Promise<Awaited<ReturnType<typeof this.publishBuilder>>>;
+    /**
+     * Add or remove a certificate for a account
+     *
+     * @param method The method to use for modifying the certificate, either `ADD` or `REMOVE`
+     * @param certificate The certificate to modify, this should be a {@link Certificate} instance.
+     * @param intermediates The certificate bundle containing the intermediate certificates, or null if there are no intermediates.
+     * @param options The options to use for the request
+     * @returns The vote staple that was generated and whether it was able to be published
+     */
+    modifyCertificate(method: ManageCertificateMethod, certificate: Certificate | CertificateHash, intermediates?: CertificateBundle | null, options?: UserClientOptions): Promise<Awaited<ReturnType<typeof this.publishBuilder>>>;
+    /**
+     * Get a single certificate for the account, by the certificate hash.
+     * @param certificateHash The hash of the certificate to get, or a {@link CertificateHash} instance.
+     * @param options The options to use for the request
+     * @return The found certificate, or null if no certificate was found.
+     */
+    getCertificates(certificateHash: string | CertificateHash, options?: UserClientOptions): Promise<CertificateWithIntermediatesResponse | null>;
+    /**
+     * List certificates for a account.
+     * @param options The options to use for the request
+     * @return The found certificates for the account
+     */
+    getCertificates(certificateHash?: undefined, options?: UserClientOptions): Promise<CertificateWithIntermediatesResponse[]>;
+    /**
+     * Get the certificates for the account.  If a certificate hash is provided,
+     * then only that certificate will be returned, otherwise all certificates
+     * for the account will be returned.
+     * @param certificateHash The hash of the certificate to get, or a {@link CertificateHash} instance.
+     * If not provided, all certificates for the account will be returned.
+     * @param options The options to use for the request
+     * @return The certificate or certificates for the account, depending on whether a hash was provided.
+     */
+    getCertificates(certificateHash?: string | CertificateHash | undefined, options?: UserClientOptions): Promise<CertificateWithIntermediatesResponse | (CertificateWithIntermediatesResponse[]) | null>;
     /**
      * Send some tokens from this account to another account.
      *
@@ -891,10 +1004,10 @@ export declare class UserClient {
      * @param token The token to send
      * @param external The external identifier to use for the transaction
      * @param options The options to use for the request
-     * @param retries The number of times to retry the request if it fails
+     * @param retries The number of times the request has been retried
      * @return The vote staple that was generated and whether it was able to be published
      */
-    send(to: GenericAccount | string, amount: bigint | number, token: TokenAddress | string, external?: string, options?: UserClientOptions, retries?: number): Promise<void>;
+    send(to: GenericAccount | string, amount: bigint | number, token: TokenAddress | string, external?: string, options?: UserClientOptions, retries?: number): Promise<Awaited<ReturnType<typeof this.publishBuilder>>>;
     /**
      * Generate a new identifier for the given type and publish the blocks
      *
@@ -902,7 +1015,7 @@ export declare class UserClient {
      * @param options The options to use for the request
      * @return The identifier that was generated
      */
-    generateIdentifier(type: IdentifierKeyAlgorithm, options?: UserClientOptions): Promise<import("./builder").PendingAccount<AccountKeyAlgorithm.NETWORK | AccountKeyAlgorithm.TOKEN | AccountKeyAlgorithm.STORAGE>>;
+    generateIdentifier(type: IdentifierKeyAlgorithm, options?: UserClientOptions): Promise<import("./builder").PendingAccount<AccountKeyAlgorithm.NETWORK | AccountKeyAlgorithm.TOKEN | AccountKeyAlgorithm.STORAGE | AccountKeyAlgorithm.MULTISIG>>;
     /**
      * Update the permissions for a given account.  This will publish the
      * changes to the network.
@@ -1051,7 +1164,7 @@ export declare class UserClient {
      * 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
      */
-    on<EventName extends UserClientEventName>(event: EventName, handler: UserClientListenerTypes[EventName]): symbol;
+    on<EventName extends UserClientEventName>(event: EventName, handler: UserClientListenerTypes[EventName], listenerOptions?: UserClientListenerOptions[EventName]): symbol;
     /**
      * Cancel a previously registered callback from {@link on}
      */
@@ -1060,6 +1173,15 @@ export declare class UserClient {
      * Destroy this instance -- this is required to clean up all resources.
      */
     destroy(): Promise<void>;
+    /**
+     * This enables the use of `using` to automatically clean up the
+     * instance of the {@link UserClient} class when it is no longer
+     * needed.
+     *
+     * It calls the {@link destroy}() method to clean up the instance when
+     * it goes out of scope.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
     /**
      * Get the configuration for this UserClient instance.
      */