@keetanetwork/keetanet-client 0.10.2

package/lib/p2p.d.ts

@@ -0,0 +1,300 @@
+import type net from 'net';
+import { WebSocket } from 'ws';
+import Node, { NodeKind } from './node';
+import Account from './account';
+import type { JSONSerializable, JSONSerializableObject } from './utils/conversion';
+import type { DistributiveOmit } from './utils/helper';
+import type { KVStorageProvider } from './kv';
+import type { Representative } from '../config';
+/**
+ * Peer to Peer connection configuration
+ */
+export interface P2PConfig {
+    /**
+     * How long should a P2P connection allowed to be idle (after
+     * greeting, excluding listeners) (ms)
+     */
+    timeoutIdle?: number;
+    /**
+     * How long should a P2P connection be allowed to be idle for a
+     * greeting to complete (ms)
+     */
+    timeoutIdleGreeting?: number;
+    /**
+     * How long should a P2P connection from a listener allowed to be
+     * idle (ms)
+     */
+    timeoutIdleListener?: number;
+    /**
+     * How frequently should the idle connection checker run and terminate
+     * connections (ms)
+     */
+    timeoutIdleCheck?: number;
+    /**
+     * How frequently should manual peers be connected to in order to get
+     * additional peering information (ms)
+     */
+    manualPeersCheckInFreq?: number;
+    /**
+     * How many peers should messages that are being broadcast be
+     * forwarded to
+     */
+    forwardingPeerCount?: number;
+    /**
+     * Key-Value Storage Instance (null means a new in-memory instance will be created)
+     */
+    kv?: KVStorageProvider | null;
+    /**
+     * Forget about seen message ids after this many milliseconds
+     */
+    seenMessageTTL?: number;
+}
+/**
+ * Shape of statistics
+ */
+export interface P2PSwitchStatistics {
+    incomingMessages: number;
+    outgoingMessagesPeerSuccess: number;
+    outgoingMessagesPeerFailure: number;
+    outgoingMessagesPeerFiltered: number;
+    outgoingMessagesPeerFailureUngreeted: number;
+}
+/**
+ * How we should represent peers internally.  Peers are known endpoints we can
+ * connect to or placeholders for inbound connections
+ */
+interface P2PPeerBase {
+    kind: NodeKind;
+}
+/**
+ * Peering information for a Representative (Basic, unsigned information)
+ */
+interface P2PPeerRepBase extends P2PPeerBase {
+    kind: NodeKind.REPRESENTATIVE;
+    /**
+     * Endpoint to reach the representative
+     */
+    endpoint: string;
+    /**
+     * Public key of the representative (used as the ID)
+     */
+    key: Account;
+}
+/**
+ * Peering information for a Representative
+ */
+type P2PPeerRep = P2PPeerRepBase & ({
+    /**
+     * Certificate from this peer which confirms its endpoints
+     */
+    certificate: null;
+} | {
+    /**
+     * Direct signature of the peer information
+     */
+    signature: ArrayBuffer;
+});
+/**
+ * Peering information for an inbound socket which has no callback information
+ */
+interface P2PPeerListener extends P2PPeerBase {
+    kind: NodeKind.PARTICIPANT;
+    /**
+     * Temporary ID to use for identifying this peer while we are connected to it
+     */
+    id: string;
+}
+export type P2PPeer = P2PPeerRep | P2PPeerListener;
+type P2PPeerUnsigned = DistributiveOmit<P2PPeer, 'certificate' | 'signature'>;
+export declare function generateP2PPeerSigned(peer: P2PPeerUnsigned): Promise<P2PPeer>;
+/**
+ * Options for the "peers" method
+ */
+interface GetPeersOptions {
+    /**
+     * Whether or not to consider ourselves (if we are attached to a
+     * representative node) as a peer.  Default is false.
+     */
+    includeSelf?: boolean;
+    /**
+     * Whether or not to include peers which are potentially stale
+     * because we have not heard from them in a while.  Default is false.
+     */
+    includeStale?: boolean;
+    /**
+     * Whether or not to include peers which have not been validated
+     * yet.  Default is false.
+     */
+    includeUnverified?: boolean;
+}
+export declare function P2PPeerFromJSO(object: any): P2PPeer | null;
+export declare function P2PPeerToJSO(peer: P2PPeer): JSONSerializableObject;
+type SerializedConnection = {
+    [key: string]: JSONSerializable;
+    type: string;
+    data: string;
+};
+/**
+ * Represents an active connection on the P2P network
+ */
+export interface P2PConnection {
+    /**
+     * Signal to abort the connection
+     */
+    abort: boolean;
+    /**
+     * Peer information, if null the peer has not yet greeted us so we do
+     * not know who they are
+     */
+    peer: P2PPeer | null;
+    /**
+     * Printable form of the peer
+     */
+    peerString: string | null;
+    /**
+     * Printable form of the connection
+     */
+    connString: string;
+    /**
+     * The peering information is normally untrusted since it just what
+     * the peer gave us once it has been validated we can populate this.
+     *
+     * Validation can be via a callback to the peer or a certificate
+     *
+     * A callback isn't as reliable since it could be a MITM proxy
+     */
+    validatedPeer: P2PPeer | null;
+    /**
+     * Timeout of when to close this connection (Date.valueOf)
+     */
+    timeout: number;
+    /**
+     * If this connection can be serialized to our KV store,
+     * return the type.
+     *
+     * @see P2PSwitch.RegisterP2PConnectionDeserializer
+     * for registering a handler to convert it back
+     */
+    serialize?: () => SerializedConnection;
+    /**
+     * Method to send a message to this peer
+     */
+    send: (data: Buffer) => Promise<boolean>;
+    /**
+     * Method to close this connection
+     */
+    close: () => Promise<void>;
+}
+/**
+ * Transportable form a of a message
+ */
+type JSONMessage = {
+    valid: true;
+    id: string;
+    type: string;
+    data: any;
+    ttl: number | undefined;
+};
+export declare function randomizeReps(reps: Representative[]): Representative[];
+export declare function formatRepEndpoints(peers: P2PPeer[]): Representative[];
+/**
+ * A P2PConnection using the "ws" package
+ */
+export declare class P2PWebSocket implements P2PConnection {
+    #private;
+    abort: boolean;
+    peer: P2PPeer | null;
+    validatedPeer: P2PPeer | null;
+    timeout: number;
+    /**
+     * Initiate an outbound websocket connection and attach it to the specified switch
+     */
+    static initiate(peer: P2PPeer, p2pSwitch: P2PSwitch): Promise<P2PWebSocket | null>;
+    /**
+     * Attach a new "ws" connection to the switch
+     */
+    static connectToSwitch(socket: WebSocket, p2pSwitch: P2PSwitch, underlyingSocket?: net.Socket): Promise<P2PWebSocket>;
+    static isInstance: (obj: any, strict?: boolean) => obj is P2PWebSocket;
+    constructor(socket: WebSocket, p2pSwitch: P2PSwitch, underlyingSocket?: net.Socket);
+    get connString(): string;
+    get peerString(): string | null;
+    send(messageBuffer: Buffer): Promise<boolean>;
+    close(): Promise<void>;
+}
+/**
+ * The interfaces from the Node that the P2P switch uses
+ */
+type NodeLike = Pick<Node, 'recvMessageFromPeer' | 'config' | 'stats' | 'log'>;
+/**
+ * Deserializer DB
+ */
+type DeserializerCallback = (node: NodeLike, data: string) => P2PConnection;
+/**
+ * A P2PSwitch is a method of coordinating messages from peers (either
+ * connected or known) with a Node.
+ */
+export declare class P2PSwitch {
+    #private;
+    readonly config: Omit<Required<P2PConfig>, 'kv'> & {
+        kv: NonNullable<P2PConfig['kv']>;
+    };
+    static RegisterP2PConnectionDeserializer(type: string, deserializer: DeserializerCallback): void;
+    static isInstance: (obj: any, strict?: boolean) => obj is P2PSwitch;
+    DeserializeP2PConnection(connString: string): Promise<P2PConnection | undefined>;
+    constructor(node: NodeLike);
+    /**
+     * Get a list of known peers
+     */
+    peers(options?: GetPeersOptions): Promise<P2PPeer[]>;
+    /**
+     * Add a manual peer to initiate peering process
+     *
+     * The switch will periodically reach out to this peer to build its
+     * peer database
+     */
+    addManualPeer(peer: P2PPeer, schedule?: boolean): void;
+    /**
+     * Stop this switch
+     */
+    stop(): Promise<void>;
+    /**
+     * Handle any waiting that needs to be done
+     */
+    wait(): Promise<void>;
+    stats(): Promise<P2PSwitchStatistics>;
+    registerConnection(conn: P2PConnection): Promise<void>;
+    unregisterConnection(conn: P2PConnection): Promise<void>;
+    static parseJSONMessage(messageBuffer: Buffer | ArrayBuffer): {
+        valid: false;
+        reason: string;
+    } | JSONMessage;
+    /**
+     * Our own peer information
+     */
+    selfPeer(): Promise<P2PPeer | null>;
+    /**
+     * Receive a message from a connection
+     *
+     * This message will get sent to our local node, which may then rebroadcast it
+     */
+    recvMessageFromPeer(from: P2PConnection, messageBuffer: Buffer | ArrayBuffer): Promise<boolean>;
+    /**
+     * Send a message to one or more peers
+     *
+     * If they are already connected that connection will be re-used,
+     * otherwise a new connection will be established.
+     *
+     * If "to" is null then it will be sent to a sampling of peers
+     *
+     * @param to - Where to send the message
+     * @param id - Unique message identifier
+     * @param type - Message type
+     * @param data - Message data, must be serializable to JSON
+     * @param ttl - Maximum number of hops to pass through
+     * @param exclude - List of connections to exclude (e.g., because we got the message from that connection) if "to" is null
+     * @param skipConnectToPeers - Skip creating new connections to send to, only connected clients will be sent the message
+     * @returns If the message could be delivered to at least one peer
+     */
+    sendMessage(to: P2PConnection | Account | P2PPeer | null, id: string, type: string, data: any, ttl?: number, exclude?: (string | P2PConnection)[], skipConnectToPeers?: boolean): Promise<boolean>;
+}
+export default P2PSwitch;

package/lib/permissions.d.ts

@@ -0,0 +1,121 @@
+import type { GenericAccount } from './account';
+import BitField from './utils/bitfield';
+declare const externalFlagPrefix: "EXTERNAL_";
+/**
+ * Flags we have for non-external permissions
+ */
+declare enum BaseFlag {
+    ACCESS = 0,/* 0x0001 */
+    OWNER = 1,/* 0x0002 */
+    ADMIN = 2,/* 0x0004 */
+    UPDATE_INFO = 3,/* 0x0008 */
+    SEND_ON_BEHALF = 4,/* 0x0010 */
+    STORAGE_CAN_HOLD = 9,/* 0x0200 */
+    STORAGE_DEPOSIT = 10,/* 0x0400 */
+    STORAGE_CREATE = 8,/* 0x0100 */
+    TOKEN_ADMIN_CREATE = 5,/* 0x0020 */
+    TOKEN_ADMIN_SUPPLY = 6,/* 0x0040 */
+    TOKEN_ADMIN_MODIFY_BALANCE = 7,/* 0x0080 */
+    PERMISSION_DELEGATE_ADD = 11,/* 0x0800 */
+    PERMISSION_DELEGATE_REMOVE = 12
+}
+type ExternalFlagName = `${typeof externalFlagPrefix}${string}`;
+export type BaseFlagName = keyof typeof BaseFlag;
+export type BaseFlagNames = BaseFlagName[];
+type FlagOrExternalName = BaseFlagName | ExternalFlagName;
+type FlagOrExternalNames = FlagOrExternalName[];
+type ExternalPermissionOffsetSet = {
+    [key: ExternalFlagName]: number;
+};
+type BasePermissionOffsetSet = {
+    [K in BaseFlagName]: number;
+};
+type PermissionOffsetSet = ExternalPermissionOffsetSet | BasePermissionOffsetSet;
+/**
+ * Handles what flags are in what groups, groups cannot be mixed (except BASE)
+ * network/token permissions must be granted on network/token identifiers
+ */
+declare enum BasePermissionGroup {
+    NEVER = 0,
+    ANY = 1,
+    NONIDENTIFIER = 2,
+    NETWORK = 3,
+    TOKEN = 4,
+    STORAGE = 5
+}
+interface BaseFlagRule {
+    canBeDefault: boolean;
+    entity: BasePermissionGroup;
+    principal: BasePermissionGroup;
+    target: BasePermissionGroup;
+}
+type FlagGroupType = Exclude<keyof BaseFlagRule, 'canBeDefault'>;
+/**
+ * Abstract class to hold permissions, handles storage and some basic functions
+ */
+declare abstract class PermissionSetHolder {
+    protected storage: BitField;
+    constructor(initialValue: bigint | number[]);
+    protected computeFlagsFromOffsetSet(offsets: PermissionOffsetSet): FlagOrExternalNames;
+    get bigint(): bigint;
+}
+/**
+ * Base Set permission holder
+ */
+declare class BaseSet extends PermissionSetHolder {
+    #private;
+    static isInstance: (obj: any, strict?: boolean) => obj is BaseSet;
+    static BasePermissionGroup: typeof BasePermissionGroup;
+    constructor(presetFlags: bigint | number[]);
+    static Create(presetFlags: bigint | number[] | BaseFlagNames): BaseSet;
+    hasFlags(flags: BaseFlagName | BaseFlagNames): boolean;
+    checkAccountMatchesGroup(type: FlagGroupType, account?: GenericAccount): boolean;
+    get flags(): BaseFlagNames;
+    get isValidForDefault(): boolean;
+}
+/**
+ * External permission set holder
+ */
+declare class ExternalSet extends PermissionSetHolder {
+    #private;
+    static isInstance: (obj: any, strict?: boolean) => obj is ExternalSet;
+    constructor(presetOffsets?: bigint | number[]);
+    static Create(presetFlags: bigint | number[]): ExternalSet;
+    validate(network: bigint): boolean;
+    /**
+     * Takes an offset set
+     * Returns an array of external flags that are true in relation to current storage
+     */
+    computeFlagNames(offsets: ExternalPermissionOffsetSet): FlagOrExternalNames;
+    hasOffset(offset: number): boolean;
+    setOffset(offset: number, value: boolean): void;
+    setFromTrueOffsets(trueOffset: number[]): void;
+    get trueOffsets(): number[];
+}
+export type { BaseSet, ExternalSet };
+export type AcceptedPermissionTypes = Permissions | [string, number[]] | [string, string] | [BaseFlagNames | number[], number[]] | [bigint, bigint] | false;
+/**
+ * Class to hold a Base and External permission set
+ */
+export default class Permissions {
+    #private;
+    static isInstance: (obj: any, strict?: boolean) => obj is Permissions;
+    static BaseSet: typeof BaseSet;
+    static ExternalSet: typeof ExternalSet;
+    static FromAcceptedTypes(perms: AcceptedPermissionTypes): Permissions;
+    constructor(baseFlags?: BaseSet | BaseFlagNames | bigint, externalOffsets?: ExternalSet | number[] | bigint);
+    validate(network: bigint): boolean;
+    has(flags: BaseFlagNames, offsets?: number[]): boolean;
+    has(instance: Permissions): boolean;
+    static combine(combineFrom: Permissions, toCombine: Permissions): Permissions;
+    combine(toCombine: Permissions): Permissions;
+    static remove(removeFrom: Permissions, toRemove: Permissions): Permissions;
+    remove(toRemove: Permissions): Permissions;
+    compare(toCompare?: Permissions): boolean;
+    get toUpdateRequires(): Permissions;
+    get canUseDelegation(): boolean;
+    get base(): BaseSet;
+    get external(): ExternalSet;
+    static toJSONSerializablePrefix: string;
+    static toJSONSerializable(value: Permissions): bigint[];
+}

package/lib/pubsub/index.d.ts

@@ -0,0 +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>;
+    destroy: () => Promise<void>;
+}

package/lib/pubsub/providers.d.ts

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

package/lib/pubsub/ps_memory.d.ts

@@ -0,0 +1,9 @@
+import type { JSONSerializable } from '../utils/conversion';
+import type { PubSubProviderAPI, SubscriptionCallback } from './';
+export declare class PubSubProviderMemory implements PubSubProviderAPI {
+    #private;
+    publish(channel: string, message: JSONSerializable): Promise<void>;
+    subscribe(channel: string, callback: SubscriptionCallback): Promise<void>;
+    destroy(): Promise<void>;
+}
+export default PubSubProviderMemory;

package/lib/pubsub/ps_redis.d.ts

@@ -0,0 +1,10 @@
+import type { JSONSerializable } from '../utils/conversion';
+import type { PubSubProviderAPI, SubscriptionCallback } from './';
+export declare class PubSubProviderRedis implements PubSubProviderAPI {
+    #private;
+    constructor(host: string, password: string, port?: number);
+    subscribe(channel: string, callback: SubscriptionCallback): Promise<void>;
+    publish(channel: string, message: JSONSerializable): Promise<void>;
+    destroy(): Promise<void>;
+}
+export default PubSubProviderRedis;

package/lib/stats.d.ts

@@ -0,0 +1,51 @@
+import type { KVStorageProvider } from './kv';
+import BufferStorage from './utils/buffer';
+import type { BlockHash } from './block';
+export interface StatsConfig {
+    kv: KVStorageProvider | null;
+}
+declare const durationRanges: {
+    readonly '-1ms': readonly [-1, -1];
+    readonly '0ms': readonly [0, 0];
+    readonly '10ms': readonly [1, 10];
+    readonly '100ms': readonly [11, 100];
+    readonly '200ms': readonly [101, 200];
+    readonly '300ms': readonly [201, 300];
+    readonly '400ms': readonly [301, 400];
+    readonly '500ms': readonly [401, 500];
+    readonly '600ms': readonly [501, 600];
+    readonly '700ms': readonly [601, 700];
+    readonly '800ms': readonly [701, 800];
+    readonly '900ms': readonly [801, 900];
+    readonly '1000ms': readonly [901, 1000];
+    readonly '1500ms': readonly [1001, 1500];
+    readonly '2000ms': readonly [1501, 2000];
+    readonly '5000ms': readonly [2001, 5000];
+    readonly '10000ms': readonly [5001, 10000];
+    readonly '100000ms': readonly [10001, 100000];
+    readonly ExtraLong: readonly [100000, number];
+};
+export type DurationBreakdowns = keyof typeof durationRanges;
+type TimeStat = {
+    count: number;
+    range: [number, number];
+};
+export type TimeStats = {
+    [duration in DurationBreakdowns]: TimeStat;
+};
+export declare class Stats {
+    #private;
+    constructor(config: StatsConfig);
+    static durationBreakdownList(): DurationBreakdowns[];
+    static assertDurationBreakdown(duration: string): asserts duration is DurationBreakdowns;
+    static durationBreakdown(duration: number): DurationBreakdowns;
+    static placeholderTimingData(): TimeStats;
+    incr(arena: string, key: string, change?: number): void;
+    xor(key: string, change: BlockHash | BufferStorage): void;
+    getXor(key: string): Promise<BufferStorage>;
+    addTimingPoint(arena: string, category: string, duration: number, returnOnly?: boolean): Parameters<Stats['incr']>;
+    get(arena: string, key: string): Promise<number>;
+    getTimingData(arena: string, category: string): Promise<TimeStats>;
+    sync(): Promise<void>;
+}
+export default Stats;