@keetanetwork/keetanet-client 0.10.4 → 0.12.0

package/lib/ledger/types.d.ts

@@ -1,7 +1,8 @@
 import type { GenericAccount, TokenAddress } from '../account';
 import type { AdjustMethod } from '../block';
 import type { Permissions } from '../permissions';
-import type { TimeStats } from '../stats';
+import type { DbStats, TimeStats } from '../stats';
+import type { Certificate, CertificateBundle } from '../utils/certificate';
 /**
  * Account info entry
  */
@@ -97,5 +98,10 @@ export interface LedgerStatistics {
     blockCount: number;
     transactionCount: number;
     representativeCount: number;
+    db: DbStats;
     settlementTimes: TimeStats;
 }
+export interface CertificateWithIntermediates {
+    certificate: Certificate;
+    intermediates: CertificateBundle | null;
+}

package/lib/node/local.d.ts

@@ -1,11 +1,18 @@
+import type { Response as ExpressResponse } from 'express';
 import type { NodeConfig } from './';
 import { Node } from './';
 import type { BootstrapConfig } from '../bootstrap';
 import { BootstrapClient } from '../bootstrap';
 import type { ErrorCode } from '../error';
-export type LocalNodeConfig = NodeConfig & {
+export type LocalNodeConfig = Omit<NodeConfig, 'nodeOptions'> & {
     bootstrap?: BootstrapConfig;
     invokeSecret?: string;
+    nodeOptions?: {
+        listenIP?: string;
+        listenPort?: number;
+        timingSampleRate?: number;
+        noSyncAfterEachRoute?: boolean;
+    };
 };
 export type ApiErrorResponse = {
     error: boolean;
@@ -19,7 +26,9 @@ type LocalNodeRunOptions = {
 export declare class LocalNode extends Node {
     #private;
     static isInstance: (obj: any, strict?: boolean) => obj is LocalNode;
+    config: LocalNodeConfig;
     constructor(config: LocalNodeConfig);
+    setCorsHeaders(response: ExpressResponse): void;
     addRoutes(prefix?: string): void;
     get _app(): import("express-serve-static-core").Express;
     run(options?: LocalNodeRunOptions): Promise<void>;

package/lib/node/timing.d.ts

@@ -1,11 +1,50 @@
+interface DisposableTimingHandle extends Disposable {
+    /**
+     * Unique identifier for the timing section
+     */
+    id: symbol;
+    /**
+     * End the timing section
+     */
+    end: () => void;
+    /**
+     * Dispose of the timing section, ending it
+     */
+    [Symbol.dispose]: () => void;
+}
 export declare class RequestTiming {
     #private;
-    startTime(section: string): void;
-    endTime(section: string, deduplicate?: boolean): void;
-    runTimer<T>(section: string, code: () => Promise<T>, deduplicate?: boolean): Promise<T>;
-    getTiming(section: string): number;
+    static defaultLogger: Console;
+    log: Console;
+    /**
+     * Start timing a section of code
+     * @param section Name of the section to time -- should be unique within the code base so that it can be identified later
+     * @returns A handle which can be used to end the timing section
+     */
+    startTime(section: string): DisposableTimingHandle;
+    endTime(section: symbol | undefined | ReturnType<RequestTiming['startTime']>): void;
+    /** @deprecated Use `endTime(section: symbol)` instead */
+    endTime(section: string | undefined, deduplicate?: boolean): void;
+    /**
+     * Run a piece of code and time it, returning the result of the code
+     *
+     * This takes an optional "timing" parameter which is a timing object
+     * if one exists, to update -- if this parameter is undefined no timing
+     * will be done.
+     *
+     * @param section Name of the section to time -- should be unique within the code base so that it can be identified later
+     * @param timing Timing object to update, if available
+     * @param code The code to run
+     * @returns The result of the code
+     */
+    static runTimer<T>(section: string, timing: RequestTiming | undefined, code: () => Promise<T>): Promise<T>;
+    runTimer<T>(section: string, code: () => Promise<T>): Promise<T>;
+    private getTiming;
     getAllTiming(): {
-        [section: string]: number;
+        [section: string]: {
+            name: string;
+            duration: number;
+        };
     };
     counter(): number;
 }

package/lib/p2p.d.ts

@@ -72,9 +72,12 @@ interface P2PPeerBase {
 interface P2PPeerRepBase extends P2PPeerBase {
     kind: NodeKind.REPRESENTATIVE;
     /**
-     * Endpoint to reach the representative
+     * Endpoints to reach the representative
      */
-    endpoint: string;
+    endpoints: {
+        p2p: string;
+        api: string;
+    };
     /**
      * Public key of the representative (used as the ID)
      */
@@ -224,7 +227,7 @@ export declare class P2PWebSocket implements P2PConnection {
 /**
  * The interfaces from the Node that the P2P switch uses
  */
-type NodeLike = Pick<Node, 'recvMessageFromPeer' | 'config' | 'stats' | 'log'>;
+type NodeLike = Pick<Node, 'recvMessageFromPeer' | 'sendMessage' | 'config' | 'stats' | 'log'>;
 /**
  * Deserializer DB
  */

package/lib/permissions.d.ts

@@ -17,7 +17,8 @@ declare enum BaseFlag {
     TOKEN_ADMIN_SUPPLY = 6,/* 0x0040 */
     TOKEN_ADMIN_MODIFY_BALANCE = 7,/* 0x0080 */
     PERMISSION_DELEGATE_ADD = 11,/* 0x0800 */
-    PERMISSION_DELEGATE_REMOVE = 12
+    PERMISSION_DELEGATE_REMOVE = 12,/* 0x1000 */
+    MANAGE_CERTIFICATE = 13
 }
 type ExternalFlagName = `${typeof externalFlagPrefix}${string}`;
 export type BaseFlagName = keyof typeof BaseFlag;
@@ -116,6 +117,5 @@ export declare class Permissions {
     get canUseDelegation(): boolean;
     get base(): BaseSet;
     get external(): ExternalSet;
-    static toJSONSerializablePrefix: string;
-    static toJSONSerializable(value: Permissions): bigint[];
+    toJSON(): [bigint, bigint];
 }

package/lib/pubsub/index.d.ts

@@ -1,7 +1,7 @@
 import type { JSONSerializable } from '../utils/conversion';
 export type SubscriptionCallback = (message: JSONSerializable) => void;
 export interface PubSubProviderAPI {
-    subscribe: (channel: string, callback: SubscriptionCallback) => Promise<void>;
     publish: (channel: string, message: JSONSerializable) => Promise<void>;
+    subscribe: (channel: string, callback: SubscriptionCallback) => Promise<void>;
     destroy: () => Promise<void>;
 }

package/lib/pubsub/providers.d.ts

@@ -1,7 +1,9 @@
 import PubSubProviderMemory from './ps_memory';
 import PubSubProviderRedis from './ps_redis';
+import PubSubProviderGCP from './ps_gcp';
 export declare const PS: {
     Memory: typeof PubSubProviderMemory;
     Redis: typeof PubSubProviderRedis;
+    GCP: typeof PubSubProviderGCP;
 };
 export default PS;

package/lib/pubsub/ps_gcp.d.ts

@@ -0,0 +1,14 @@
+import type { JSONSerializable } from '../utils/conversion';
+import type { PubSubProviderAPI, SubscriptionCallback } from '.';
+import { PubSub } from '@google-cloud/pubsub';
+import type { Topic } from '@google-cloud/pubsub';
+export declare class PubSubProviderGCP implements PubSubProviderAPI {
+    #private;
+    constructor(projectId: string, apiEndpoint?: string);
+    get _testing_pubsub(): PubSub;
+    publish(channel: string, message: JSONSerializable): Promise<void>;
+    subscribe(channel: string, callback: SubscriptionCallback): Promise<void>;
+    destroy(): Promise<void>;
+    assertTopicExists(topic: Topic, channel: string): Promise<true | undefined>;
+}
+export default PubSubProviderGCP;

package/lib/stats.d.ts

@@ -1,6 +1,7 @@
 import type { KVStorageProvider } from './kv';
 import { BufferStorage } from './utils/buffer';
 import type { BlockHash } from './block';
+import type { RequestTiming } from './node/timing';
 export interface StatsConfig {
     kv: KVStorageProvider | null;
 }
@@ -33,6 +34,9 @@ type TimeStat = {
 export type TimeStats = {
     [duration in DurationBreakdowns]: TimeStat;
 };
+export type DbStats = {
+    retries: number;
+};
 export declare class Stats {
     #private;
     constructor(config: StatsConfig);
@@ -44,6 +48,7 @@ export declare class Stats {
     xor(key: string, change: BlockHash | BufferStorage): void;
     getXor(key: string): Promise<BufferStorage>;
     addTimingPoint(arena: string, category: string, duration: number, returnOnly?: boolean): Parameters<Stats['incr']>;
+    addRequestTiming(arena: string, timing: RequestTiming, returnOnly?: boolean): Parameters<Stats['incr']>[];
     get(arena: string, key: string): Promise<number>;
     getTimingData(arena: string, category: string): Promise<TimeStats>;
     sync(): Promise<void>;

package/lib/utils/asn1.d.ts

@@ -63,7 +63,7 @@ export declare namespace ValidateASN1 {
         sequenceOf: Schema;
     } | {
         optional: Schema;
-    } | {
+    } | bigint | {
         type: 'context';
         kind: 'implicit' | 'explicit';
         contains: Schema;
@@ -110,7 +110,7 @@ export declare namespace ValidateASN1 {
         sequenceOf: Schema;
     } ? SchemaMap<T['sequenceOf']>[] : T extends {
         optional: Schema;
-    } ? SchemaMap<T['optional']> | undefined : T extends {
+    } ? SchemaMap<T['optional']> | undefined : T extends bigint ? T : T extends {
         type: 'context';
         kind: infer U extends 'implicit' | 'explicit';
         value: number;
@@ -182,7 +182,7 @@ type Mutable<T> = T extends Buffer | ArrayBuffer | Date ? T : T extends object ?
 export declare class BufferStorageASN1<T extends ASN1AnyJS | Readonly<ASN1AnyJS> = Readonly<ASN1AnyJS>, S extends ValidateASN1.Schema | undefined = undefined> {
     #private;
     static readonly Validate: typeof ValidateASN1;
-    static readonly isInstance: (obj: any, strict?: boolean) => obj is BufferStorageASN1<string | number | bigint | boolean | Buffer | ASN1AnyJS[] | Date | ASN1OID | ASN1Set | ASN1ExplicitContextTag | ASN1ImplicitContextTag | ASN1BitString | ASN1Date | ASN1String | readonly ASN1AnyJS[] | Readonly<Buffer> | Readonly<Date> | Readonly<ASN1OID> | Readonly<ASN1Set> | Readonly<ASN1ExplicitContextTag> | Readonly<ASN1ImplicitContextTag> | Readonly<ASN1BitString> | Readonly<ASN1Date> | Readonly<ASN1String> | null | undefined, ValidateASN1.Schema | undefined>;
+    static readonly isInstance: (obj: any, strict?: boolean) => obj is BufferStorageASN1<string | number | bigint | boolean | Date | Buffer | ASN1AnyJS[] | ASN1OID | ASN1Set | ASN1ExplicitContextTag | ASN1ImplicitContextTag | ASN1BitString | ASN1Date | ASN1String | readonly ASN1AnyJS[] | Readonly<Date> | Readonly<Buffer> | Readonly<ASN1OID> | Readonly<ASN1Set> | Readonly<ASN1ExplicitContextTag> | Readonly<ASN1ImplicitContextTag> | Readonly<ASN1BitString> | Readonly<ASN1Date> | Readonly<ASN1String> | null | undefined, ValidateASN1.Schema | undefined>;
     constructor(input: T | ArrayBuffer, schema?: S);
     getDER(): ArrayBuffer;
     getDERBuffer(): Buffer;

package/lib/utils/certificate.d.ts

@@ -1,6 +1,8 @@
 import * as ASN1 from './asn1';
-import Account from '../account';
+import Account, { AccountKeyAlgorithm } from '../account';
 import * as HashLib from './hash';
+import { BufferStorage } from './buffer';
+import type { ToJSONSerializableOptions, ToJSONSerializable } from './conversion';
 /**
  * De-normalized mapped Certificate Schema, for use in type annotations since
  * we do not want to expose such a complex type
@@ -132,7 +134,7 @@ export declare class CertificateBuilder {
      * Create a certificate
      */
     buildDER(params?: Partial<CertificateBuilderParams>): Promise<ArrayBuffer>;
-    build(params?: Partial<CertificateBuilderParams>): Promise<Certificate>;
+    build(params?: Partial<CertificateBuilderParams>, options?: ConstructorParameters<typeof Certificate>[1]): Promise<Certificate>;
 }
 type CertificateOptions = {
     /**
@@ -163,6 +165,22 @@ type CertificateOptions = {
      */
     isTrustedRoot?: boolean;
 };
+type CertificateHashString = string & {
+    readonly __certificateHash: never;
+};
+/**
+ * Certificate hash
+ */
+export declare class CertificateHash extends BufferStorage {
+    static isInstance: (obj: any, strict?: boolean) => obj is CertificateHash;
+    static Set: import("./helper").InstanceSetConstructor<CertificateHash, CertificateHashString>;
+    get hashFunctionName(): string;
+    constructor(certificateHash: ConstructorParameters<typeof BufferStorage>[0]);
+    static fromData(data: Buffer): CertificateHash;
+    toJSON(): CertificateHashString;
+    toString(): CertificateHashString;
+}
+export type CertificateJSONOutput = ToJSONSerializable<ReturnType<Certificate['toJSON']>>;
 export declare class Certificate {
     #private;
     /**
@@ -269,6 +287,11 @@ export declare class Certificate {
      * Verifies that the certificate is was signed by the given account or certificate
      */
     verify(account: Account | Certificate): boolean;
+    /**
+     * Asserts provided certificates can construct a valid graph with no loops or orphans, and that all provided certificates can reach the root, or current certificate
+     * @param certificates Additional intermediate certificates to verify
+     */
+    assertCanConstructValidGraph(certificates: Set<Certificate>): true | undefined;
     /**
      * Verify against a given certificate store
      */
@@ -331,10 +354,58 @@ export declare class Certificate {
     /**
      * Compute a hash of the certificate
      */
-    hash(): string;
+    hash(): CertificateHash;
     /**
      * Get a JSON representation of the certificate
      */
-    toJSON(includeChain?: boolean): any;
+    toJSON(options?: ToJSONSerializableOptions, includeChain?: boolean): {
+        $binary?: string;
+        $chain?: unknown;
+        serial: bigint;
+        notBefore: Date;
+        notAfter: Date;
+        subject: string;
+        issuer: string;
+        subjectPublicKey: Account<AccountKeyAlgorithm.ECDSA_SECP256K1 | AccountKeyAlgorithm.ED25519 | AccountKeyAlgorithm.ECDSA_SECP256R1>;
+        baseExtensions: {
+            /**
+             * Basic Constraints
+             */
+            basicConstraints?: [ca: boolean, pathLenConstraint?: bigint];
+            /**
+             * Subject Key Identifier
+             */
+            subjectKeyIdentifier?: Buffer;
+            /**
+             * Authority Key Identifier
+             */
+            authorityKeyIdentifier?: {
+                type: "context";
+                value: 0;
+                contains: Buffer;
+            };
+        } | undefined;
+        subjectDN: {
+            name: string;
+            value: string;
+        }[];
+        issuerDN: {
+            name: string;
+            value: string;
+        }[];
+        $hash: CertificateHash;
+    };
+}
+export declare class CertificateBundle {
+    #private;
+    static isInstance: (obj: any, strict?: boolean) => obj is CertificateBundle;
+    constructor(input: CertificateBundle | Certificate[] | ArrayBuffer | Buffer | string | (ConstructorParameters<typeof Certificate>[0])[] | Set<Certificate>);
+    get bundleSize(): number;
+    getDER(): ArrayBuffer;
+    getDERBuffer(): Buffer;
+    getCertificates(): Certificate[];
+    toJSON(): {
+        certificates: string[];
+    };
 }
 export {};

package/lib/utils/conversion.d.ts

@@ -1,46 +1,24 @@
-import type { Vote, VoteStaple } from '../vote';
-import type Account from '../account';
-import type { Block, BlockHash } from '../block';
-import type { Permissions } from '../permissions';
 export type JSONSerializable = string | number | boolean | null | JSONSerializable[] | {
     [key: string]: JSONSerializable;
 };
 export type JSONSerializableObject = {
     [key: string]: JSONSerializable;
 };
-type JSONUnsupportedTypes = Date | BlockHash | Account | bigint | Permissions | Vote | Block | VoteStaple;
-type JSONSupportedObject<T> = {
-    [Property in keyof T]: Exclude<T[Property], JSONUnsupportedTypes>;
-};
-type JSONSupportedValue<T> = JSONSupportedObject<T>[any];
-export type JSONSupported<T> = JSONSupportedObject<T> | JSONSupportedValue<T>;
-export type ToJSONSerializableOptions = {
+export interface ToJSONSerializableOptions<AddBinary extends boolean = boolean> {
     debugUnsafe?: boolean;
-    addBinary?: boolean;
-};
-export type ToJSONSerializable<T> = T extends bigint ? string : T extends Date ? string : T extends Buffer ? string : T extends {
-    toJSONSerializable(): infer U;
-} ? U : T extends {
+    addBinary?: AddBinary;
+}
+type AddBinaryIfIncluded<I> = I extends {
+    '$binary'?: infer BinaryType;
+} ? Omit<I, '$binary'> & {
+    '$binary': NonNullable<BinaryType>;
+} : I;
+export type ToJSONSerializable<T, Options extends ToJSONSerializableOptions = ToJSONSerializableOptions> = T extends JSONSerializable ? T : T extends undefined ? undefined : T extends bigint ? string : T extends Date ? string : T extends Buffer | ArrayBuffer ? string : T extends {
     toJSON(): infer U;
-} ? ToJSONSerializable<U> : T extends Account<infer K extends typeof Account.AccountKeyAlgorithm[keyof typeof Account.AccountKeyAlgorithm]> ? ReturnType<Account<K>['publicKeyString']['get']> : T extends BlockHash ? string : T extends Permissions ? [string, string] : T extends Vote ? ReturnType<Vote['toJSON']> & {
-    '$binary': string;
-} : T extends VoteStaple ? ReturnType<VoteStaple['toJSON']> & {
-    '$binary': string;
-} : T extends Block ? ReturnType<Block['toJSON']> & {
-    '$binary': string;
-} : T extends JSONSerializable ? T : T extends object ? {
-    [K in keyof T]: ToJSONSerializable<T[K]>;
+} ? Options['addBinary'] extends true ? ToJSONSerializable<AddBinaryIfIncluded<U>, Options> : ToJSONSerializable<U, Options> : T extends object ? {
+    [K in keyof T]: ToJSONSerializable<T[K], Options>;
 } : never;
-export declare function toJSONSerializable(data: JSONSupported<any>, opts?: ToJSONSerializableOptions): JSONSupported<any> & JSONSerializable;
-/** @deprecated -- move to toJSON methods */
-interface WithConversionClass<T, Y> {
-    toJSONSerializablePrefix: string;
-    toJSONSerializable(value: T, options: ToJSONSerializableOptions): Y;
-    isInstance(value: any): value is T;
-    new (...args: any[]): T;
-}
-/** @deprecated -- move to toJSON methods */
-export declare function RegisterSerializable(name: string): <X, Y>(target: WithConversionClass<X, Y>) => void;
-export declare function objectToBuffer(data: JSONSupported<any>, opts?: ToJSONSerializableOptions): Buffer;
+export declare function toJSONSerializable<Value, Options extends ToJSONSerializableOptions>(data: Value, opts?: Options): ToJSONSerializable<Value, Options>;
+export declare function objectToBuffer(data: any, opts?: ToJSONSerializableOptions): Buffer;
 export declare function parseHexBigIntString(input: string): bigint;
 export {};

package/lib/utils/helper.d.ts

@@ -23,6 +23,7 @@ export declare function waitTicks(ticks: number): Promise<void>;
  * Throws if neither are defined
  */
 export declare function env(name: string, defaultValue?: string): string;
+export declare function booleanEnv(name: string, defaultValue?: boolean): boolean;
 /**
  * Generate a random string from length provided (default 32)
  */
@@ -44,6 +45,7 @@ interface IsInstance<T> {
     check(obj: any, strict?: boolean): obj is T;
 }
 export declare function checkableGenerator<P extends Constructor<T>, T = InstanceType<P>>(parent: P, defaultStrict?: boolean): IsInstance<T>['check'];
+export declare function nonNullable<T>(value: T): NonNullable<T>;
 export type DeepMutable<T> = {
     -readonly [P in keyof T]: DeepMutable<T[P]>;
 };
@@ -53,15 +55,24 @@ interface WithIsInstance<Inst> extends Constructor<Inst> {
 type EncodeFunc<Inst, Enc> = (a: Inst) => Enc;
 type DecodeFunc<Inst, Enc> = (a: Enc) => Inst;
 type CanBeArray<T> = T | T[];
-export interface InstanceSet<Instance, Encoded = string> extends Set<Encoded> {
-    add(data: CanBeArray<Instance | Encoded>): this;
-    delete(data: Instance | Encoded): boolean;
-    has(data: Instance | Encoded): boolean;
-    decodedArray: Instance[];
-    encodedArray: Encoded[];
+interface InstanceSet<Instance, Encoded = string> extends Set<Instance> {
+    add(data: CanBeArray<Instance>): this;
+    forEach(callbackfn: (value: Instance, value2: Instance, set: InstanceSet<Instance, Encoded>) => void, thisArg?: any): void;
+    hasInternal(data: Encoded): boolean;
+    addInternal(data: Encoded): this;
+    deleteInternal(data: Encoded): boolean;
+    valuesInternal(): IterableIterator<Encoded>;
+    toArray(): Instance[];
+    toArrayInternal(): Encoded[];
+    isSubsetOf(data: InstanceSet<Instance, Encoded>): boolean;
+    isEqualTo(data: InstanceSet<Instance, Encoded>): boolean;
 }
-export interface InstanceSetConstructor<Instance, Encoded> {
-    new (data?: (Instance | Encoded)[]): InstanceSet<Instance, Encoded>;
+/**
+ * AsyncDisposableStack https://github.com/tc39/proposal-explicit-resource-management
+ */
+export declare const AsyncDisposableStack: AsyncDisposableStackConstructor;
+export interface InstanceSetConstructor<Instance, Encoded = string> {
+    new (data?: (Instance)[]): InstanceSet<Instance, Encoded>;
 }
 export declare function setGenerator<P extends WithIsInstance<Instance>, E extends EncodeFunc<Instance, Encoded>, D extends DecodeFunc<Instance, Encoded>, Instance = InstanceType<P>, Encoded = ReturnType<E>>(parent: P, rawEncode: E, rawDecode: D): InstanceSetConstructor<Instance, Encoded>;
 export {};

package/lib/utils/helper_testing.d.ts

@@ -2,7 +2,7 @@ import Account from '../account';
 import LocalNode from '../node/local';
 import { VoteStaple } from '../vote';
 import type { Block } from '../block';
-export declare const testingNetworkId: bigint;
+export declare const testingNetworkId = 0n;
 type NodeConfig = ConstructorParameters<typeof LocalNode>[0];
 export declare function canListenOn(ip: string): Promise<boolean>;
 export declare function findListenableIP(checkIPs: string[]): Promise<string | null>;