@keetanetwork/keetanet-client 0.10.2

package/lib/ledger/index.d.ts

@@ -0,0 +1,312 @@
+import { VoteStaple, Vote, VoteBlockHashMap } from '../vote';
+import { Block, BlockHash } from '../block';
+import type { VoteBlockHash } from '../vote';
+import type { GenericAccount, IdentifierAddress, NetworkAddress, TokenAddress } from '../account';
+import Account from '../account';
+import type Node from '../node';
+import type { BloomFilter } from '../utils/bloom';
+import type { ComputedEffectOfBlocks } from './effects';
+import type { ACLRow, AccountInfo, GetAllBalancesResponse, LedgerStatistics } from './types';
+import LedgerRequestCache from './cache';
+/**
+ * Kind of ledger
+ */
+export declare enum LedgerKind {
+    REPRESENTATIVE = 0,
+    ACCOUNT = 1
+}
+/**
+ * Ledger configuration
+ */
+export interface LedgerConfig {
+    initialTrustedAccount: Account;
+    network: bigint;
+    subnet?: bigint;
+    /**
+     * Kind of ledger
+     */
+    kind: LedgerKind;
+    /**
+     * Private key for the ledger if it is acting as a representative
+     */
+    privateKey?: Account;
+    /**
+     * Storage mechanism
+     */
+    storageDriver: LedgerStorageAPI;
+    /**
+     * Options to pass to the storage driver
+     */
+    storageOptions?: any;
+    /**
+     * Is this ledger in read-only mode ?
+     *
+     * bootstrap-only: Bootstrapping can still occur
+     * read-only: No bootstrapping, no voting
+     * read-write: Normal mode (read-write enabled)
+     */
+    ledgerWriteMode?: 'bootstrap-only' | 'read-only' | 'read-write';
+    /**
+     * Logging method
+     */
+    log?: (...args: any[]) => any;
+}
+/**
+ * Which ledger to store this data in
+ */
+export type LedgerStorage = 'main' | 'side';
+/**
+ * Which ledger(s) to pull the data from
+ */
+export type LedgerSelector = LedgerStorage | 'both';
+/**
+ * A set of votes and a pointer to the next set/page
+ */
+export type PaginatedVotes = {
+    votes: Vote[];
+    nextKey?: string;
+};
+/**
+ * Options for "getVotesAfter"
+ */
+export type GetVotesAfterOptions = {
+    /**
+     * Limit the page size when requesting votes
+     */
+    maxVotesPerPage?: number;
+    /**
+     * Bloom filter to apply to VoteStaples
+     */
+    bloomFilter?: BloomFilter;
+    /**
+     * Timeout for fetching votes
+     */
+    timeout?: number;
+};
+/**
+ * Each Ledger Storage backend must implement this interface
+ */
+export interface LedgerStorageAPI {
+    /**
+     * Initialization
+     */
+    init: (config: LedgerConfig, ledger: Ledger) => void;
+    /**
+     * Optional destructor
+     */
+    destroy?: () => Promise<void>;
+    /**
+     * Begin a transaction
+     */
+    beginTransaction: (readOnly?: boolean) => Promise<any>;
+    /**
+     * Commit an active transaction
+     */
+    commitTransaction: (transaction: any) => Promise<void>;
+    /**
+     * Abort an active transaction
+     */
+    abortTransaction: (transaction: any) => Promise<void>;
+    /**
+     * Evaluate error and return expected error (eg. KeetaNetLedgerError)
+     * @param error
+     */
+    evaluateError: (error: any) => Promise<any>;
+    /**
+     * Get the amount of delegated weight for an account,
+     * if "rep" is not supplied get the total delegated weight
+     */
+    delegatedWeight: (transaction: any, rep?: Account) => Promise<bigint>;
+    /**
+     * Get the balance of an account or token
+     */
+    getBalance: (transaction: any, account: GenericAccount, token: TokenAddress) => Promise<bigint>;
+    /**
+     * Get all balances on a user account for a token
+     */
+    getAllBalances: (transaction: any, account: GenericAccount) => Promise<GetAllBalancesResponse>;
+    /**
+     * Get account information (name, description)
+     * If token account, return supply
+     * If non user account, returns default permissions
+     */
+    getAccountInfo: (transaction: any, account: GenericAccount | string) => Promise<AccountInfo>;
+    /**
+     * List all owners of an account
+     */
+    listOwners: (transaction: any, identifier: IdentifierAddress, target?: GenericAccount) => Promise<GenericAccount[]>;
+    /**
+     * List permissions principal has on all provided entity's
+     */
+    listACLsByPrincipal: (transaction: any, principal: GenericAccount, entityList?: GenericAccount[]) => Promise<ACLRow[]>;
+    /**
+     * List permissions any principal has on provided entity
+     */
+    listACLsByEntity: (transaction: any, entity: GenericAccount) => Promise<ACLRow[]>;
+    /**
+     * Adjust the ledger by performing a set of changes based on some blocks and votes
+     */
+    adjust: (transaction: any, input: VoteStaple, changes: ComputedEffectOfBlocks) => Promise<BlockHash[]>;
+    /**
+     * Add a transitional vote (to the side-ledger)
+     */
+    addPendingVote: (transaction: any, blocksAndVote: VoteStaple) => Promise<void>;
+    /**
+     * Request a block
+     */
+    getBlock: (transaction: any, block: BlockHash, from: LedgerSelector) => Promise<Block | null>;
+    /**
+     * Get the block height from a given block hash
+     */
+    getBlockHeight: (transaction: any, blockHash: BlockHash, account: GenericAccount) => Promise<{
+        blockHeight: string | null;
+    } | null>;
+    /**
+     * Get the votes for a given block
+     */
+    getVotes: (transaction: any, block: BlockHash, from: LedgerSelector) => Promise<Vote[] | null>;
+    /**
+     * Get a vote based on the previous hash of a block
+     */
+    getVotesFromPrevious: (transaction: any, block: BlockHash, from: LedgerSelector) => Promise<Vote[] | null>;
+    /**
+     * Get multiple votes based on the successors of provided block hashes (both sides)
+     */
+    getVotesFromMultiplePrevious: (transaction: any, prevBlocks: BlockHash[], from: LedgerSelector, issuer?: Account) => Promise<{
+        [hash: string]: Vote[] | null;
+    }>;
+    /**
+     * Get a vote staple from a Vote Block Hash, which uniquely identifies a set of blocks voted on together
+     */
+    getVoteStaples: (transaction: any, voteBlockHashes: VoteBlockHash[], from: LedgerSelector) => Promise<VoteBlockHashMap<VoteStaple | null>>;
+    /**
+     * Get the history for a specific account
+     */
+    getHistory: (transaction: any, account: GenericAccount, start: VoteBlockHash | null, limit?: number) => Promise<VoteBlockHash[]>;
+    /**
+     * Get multiple head blocks at the same time for a set of accounts
+     */
+    getHeadBlocks: (transaction: any, accounts: GenericAccount[], from: LedgerSelector) => Promise<{
+        [account: string]: Block | null;
+    }>;
+    /**
+     * Get the HEAD block for an account (implemented by LedgerStorageBase using getHeadBlocks())
+     */
+    getHeadBlock: (transaction: any, account: GenericAccount, from: LedgerSelector) => Promise<Block | null>;
+    /**
+     * Get a block based on the previous hash of a block
+     */
+    getBlockFromPrevious: (transaction: any, block: BlockHash, from: LedgerSelector) => Promise<Block | null>;
+    /**
+     * Get the Account Representative
+     */
+    getAccountRep: (transaction: any, account: Account | string) => Promise<Account | null>;
+    /**
+     * Get Votes after a specific moment
+     */
+    getVotesAfter: (transaction: any, moment: Date, startKey?: string, options?: GetVotesAfterOptions) => Promise<PaginatedVotes>;
+    /**
+     * Get Vote Staples from a set of block hashes (optional)
+     */
+    getVoteStaplesFromBlockHash?: (transaction: any, blocks: BlockHash[], from: LedgerSelector) => Promise<VoteStaple[]>;
+    /**
+     * Get the cache for a transaction (optional)
+     */
+    cache?: (transaction: any) => LedgerRequestCache | undefined;
+    /**
+     * Perform Garbage Collection
+     */
+    gc: (transaction: any) => Promise<true>;
+    /**
+     * Get the next serial number for a representative
+     */
+    getNextSerialNumber: (transaction?: any) => Promise<bigint>;
+    /**
+     * Get ledger statistics
+     */
+    stats: () => Promise<LedgerStatistics>;
+}
+/**
+ * Atomic transactional interface to a storage backend
+ */
+declare class LedgerAtomicInterface {
+    #private;
+    constructor(transaction: any, storage: LedgerStorageAPI, config: LedgerConfig, ledger: Ledger);
+    commit(): Promise<void>;
+    abort(): Promise<void>;
+    vote(blocks: Block[], otherVotes?: Vote[]): Promise<Vote>;
+    add(votesAndBlocks: VoteStaple, from?: 'bootstrap' | string): Promise<BlockHash[]>;
+    getBalance(account: GenericAccount, token: TokenAddress): Promise<bigint>;
+    getAllBalances(account: GenericAccount): Promise<GetAllBalancesResponse>;
+    listACLsByPrincipal(principal: GenericAccount, entityList?: GenericAccount[]): Promise<ACLRow[]>;
+    listACLsByEntity(entity: GenericAccount): Promise<ACLRow[]>;
+    votingPower(rep?: Account): Promise<bigint>;
+    getVotes(block: BlockHash, from?: LedgerStorage): Promise<Vote[] | null>;
+    getVotesFromMultiplePrevious(prevBlocks: BlockHash[], from?: LedgerSelector, issuer?: Account): Promise<{
+        [hash: string]: Vote[] | null;
+    }>;
+    getBlockFromPrevious(block: BlockHash, from: LedgerSelector): Promise<Block | null>;
+    getHeadBlocks(accounts: GenericAccount[], from: LedgerSelector): Promise<{
+        [account: string]: Block | null;
+    }>;
+    getHeadBlock(account: GenericAccount, from: LedgerSelector): Promise<Block | null>;
+    getAccountRep(account: Account | string): Promise<Account | null>;
+    getAccountInfo(account: GenericAccount | string): Promise<AccountInfo>;
+    getBlock(blockhash: BlockHash, from?: LedgerSelector): Promise<Block | null>;
+    getVoteStaple(stapleBlockHash: VoteBlockHash, from?: LedgerSelector): Promise<VoteStaple | null>;
+    getVoteStaples(stapleBlockHashes: VoteBlockHash[], from?: LedgerSelector): Promise<VoteBlockHashMap<VoteStaple | null>>;
+    getHistory(account: GenericAccount, start: VoteBlockHash | null, limit?: number): Promise<VoteStaple[]>;
+    getStaplesFromBlockHashes(hashes: BlockHash[]): Promise<VoteStaple[]>;
+    getVoteStaplesAfter(moment: Date, limit?: number, options?: GetVotesAfterOptions): Promise<VoteStaple[]>;
+    gc(): Promise<true>;
+    _testingRunStorageFunction<T>(code: (storage: LedgerStorageAPI, transaction: any) => Promise<T>): Promise<T>;
+}
+/**
+ * The core Ledger components
+ */
+export declare class Ledger implements Omit<LedgerAtomicInterface, 'commit' | 'abort'> {
+    #private;
+    static Kind: typeof LedgerKind;
+    readonly baseToken: TokenAddress;
+    readonly networkAddress: NetworkAddress;
+    readonly initialTrustedAccount: Account;
+    readonly node?: Node;
+    static isInstance: (obj: any, strict?: boolean) => obj is Ledger;
+    constructor(config: LedgerConfig, node?: Node, existingStorage?: LedgerStorageAPI);
+    get ledgerWriteMode(): NonNullable<LedgerConfig['ledgerWriteMode']>;
+    copy(newNode: Node): Ledger;
+    /**
+     * Execute some code with a transaction held, if the code fails the
+     * transaction is aborted, otherwise it is committed
+     *
+     * @param code - Code to run
+     * @returns The return value from "code"
+     */
+    run<T>(identifier: string, code: (transaction: LedgerAtomicInterface) => Promise<T>, readOnly?: boolean): Promise<T>;
+    runReadOnly<T>(identifier: string, code: (transaction: LedgerAtomicInterface) => Promise<T>): ReturnType<typeof code>;
+    beginTransaction(readOnly?: boolean): Promise<LedgerAtomicInterface>;
+    vote(...args: Parameters<LedgerAtomicInterface['vote']>): ReturnType<LedgerAtomicInterface['vote']>;
+    add(...args: Parameters<LedgerAtomicInterface['add']>): ReturnType<LedgerAtomicInterface['add']>;
+    listACLsByPrincipal(...args: Parameters<LedgerAtomicInterface['listACLsByPrincipal']>): ReturnType<LedgerAtomicInterface['listACLsByPrincipal']>;
+    listACLsByEntity(...args: Parameters<LedgerAtomicInterface['listACLsByEntity']>): ReturnType<LedgerAtomicInterface['listACLsByEntity']>;
+    getBalance(...args: Parameters<LedgerAtomicInterface['getBalance']>): ReturnType<LedgerAtomicInterface['getBalance']>;
+    getAllBalances(...args: Parameters<LedgerAtomicInterface['getAllBalances']>): ReturnType<LedgerAtomicInterface['getAllBalances']>;
+    votingPower(...args: Parameters<LedgerAtomicInterface['votingPower']>): ReturnType<LedgerAtomicInterface['votingPower']>;
+    getVotes(...args: Parameters<LedgerAtomicInterface['getVotes']>): ReturnType<LedgerAtomicInterface['getVotes']>;
+    getVotesFromMultiplePrevious(...args: Parameters<LedgerAtomicInterface['getVotesFromMultiplePrevious']>): ReturnType<LedgerAtomicInterface['getVotesFromMultiplePrevious']>;
+    getBlockFromPrevious(...args: Parameters<LedgerAtomicInterface['getBlockFromPrevious']>): ReturnType<LedgerAtomicInterface['getBlockFromPrevious']>;
+    getHeadBlocks(...args: Parameters<LedgerAtomicInterface['getHeadBlocks']>): ReturnType<LedgerAtomicInterface['getHeadBlocks']>;
+    getHeadBlock(...args: Parameters<LedgerAtomicInterface['getHeadBlock']>): ReturnType<LedgerAtomicInterface['getHeadBlock']>;
+    getAccountRep(...args: Parameters<LedgerAtomicInterface['getAccountRep']>): ReturnType<LedgerAtomicInterface['getAccountRep']>;
+    getAccountInfo(...args: Parameters<LedgerAtomicInterface['getAccountInfo']>): ReturnType<LedgerAtomicInterface['getAccountInfo']>;
+    getBlock(...args: Parameters<LedgerAtomicInterface['getBlock']>): ReturnType<LedgerAtomicInterface['getBlock']>;
+    getVoteStaple(...args: Parameters<LedgerAtomicInterface['getVoteStaple']>): ReturnType<LedgerAtomicInterface['getVoteStaple']>;
+    getVoteStaples(...args: Parameters<LedgerAtomicInterface['getVoteStaples']>): ReturnType<LedgerAtomicInterface['getVoteStaples']>;
+    getHistory(...args: Parameters<LedgerAtomicInterface['getHistory']>): ReturnType<LedgerAtomicInterface['getHistory']>;
+    getStaplesFromBlockHashes(...args: Parameters<LedgerAtomicInterface['getStaplesFromBlockHashes']>): ReturnType<LedgerAtomicInterface['getStaplesFromBlockHashes']>;
+    getVoteStaplesAfter(...args: Parameters<LedgerAtomicInterface['getVoteStaplesAfter']>): ReturnType<LedgerAtomicInterface['getVoteStaplesAfter']>;
+    gc(...args: Parameters<LedgerAtomicInterface['gc']>): ReturnType<LedgerAtomicInterface['gc']>;
+    stats(): Promise<LedgerStatistics>;
+    _testingRunStorageFunction<T>(code: (storage: LedgerStorageAPI, transaction: any) => Promise<T>): Promise<T>;
+}
+export default Ledger;

package/lib/ledger/types.d.ts

@@ -0,0 +1,49 @@
+import type { GenericAccount, TokenAddress } from '../account';
+import type { AdjustMethod } from '../block';
+import type Permissions from '../permissions';
+import type { TimeStats } from '../stats';
+/**
+ * Account info entry
+ */
+export interface AccountInfo {
+    name: string;
+    description: string;
+    metadata: string;
+    supply?: bigint;
+    defaultPermission?: Permissions;
+}
+/**
+ * Permissions types
+ */
+export interface ACLRow {
+    principal: GenericAccount;
+    entity: GenericAccount;
+    target: GenericAccount;
+    permissions: Permissions;
+}
+export interface ACLEntry extends Omit<ACLRow, 'target'> {
+    target?: GenericAccount;
+    method?: AdjustMethod.SET;
+}
+export interface ACLUpdate extends Omit<ACLEntry, 'method' | 'permissions'> {
+    method: AdjustMethod;
+    permissions: Permissions | null;
+}
+/**
+ * All balances for each token on an account
+ */
+export type GetAllBalancesResponse = {
+    balance: bigint;
+    token: TokenAddress;
+}[];
+/**
+ * Ledger statistics
+ */
+export interface LedgerStatistics {
+    moment: string;
+    momentRange: number;
+    blockCount: number;
+    transactionCount: number;
+    representativeCount: number;
+    settlementTimes: TimeStats;
+}

package/lib/node/index.d.ts

@@ -0,0 +1,114 @@
+import type { LedgerConfig } from '../ledger';
+import Ledger from '../ledger';
+import type { NetworkAddress, TokenAddress } from '../account';
+import Account from '../account';
+import type { StatsConfig } from '../stats';
+import { Stats } from '../stats';
+import type { P2PConnection, P2PPeer, P2PConfig } from '../p2p';
+import { P2PSwitch } from '../p2p';
+import { VoteStaple } from '../vote';
+import RequestTiming from './timing';
+import * as Config from '../../config';
+export declare enum NodeKind {
+    PARTICIPANT = 0,
+    REPRESENTATIVE = 1,
+    RELAY = 2,
+    ARCHIVAL = 3
+}
+interface HTTPConfig {
+    timeoutSeconds: number;
+}
+export interface NodeConfig {
+    /**
+     * Kind of node
+     */
+    kind: NodeKind;
+    /**
+     * Account that can bypass permissions for opening blocks on baseToken and networkAddress
+     * This account also will become the source of authority when there is no weight on the network
+     */
+    initialTrustedAccount: Account;
+    /**
+     * Ledger private key (for representatives to issue votes)
+     */
+    ledgerPrivateKey?: Account;
+    /**
+     * Network information
+     */
+    network: bigint;
+    subnet?: bigint;
+    /**
+     * Node alias
+     */
+    nodeAlias?: string;
+    /**
+     * Network alias
+     */
+    networkAlias: Config.Networks;
+    /**
+     * Endpoints for this node
+     */
+    endpoints?: {
+        p2p?: string;
+        api?: string;
+    };
+    /**
+     * Peer to Peer configuration
+     */
+    p2p?: P2PConfig;
+    /**
+     * HTTP Configuration
+     */
+    http?: HTTPConfig;
+    /**
+     * Manual of peers
+     */
+    manualPeers?: P2PPeer[];
+    /**
+     * Information for the ledger
+     */
+    ledger: Omit<LedgerConfig, 'baseToken' | 'network' | 'kind' | 'networkAddress' | 'initialTrustedAccount'>;
+    /**
+     * Stats manager
+     */
+    stats: StatsConfig;
+    /**
+     * Extra information for the particular kind of node
+     */
+    nodeOptions?: any;
+    /**
+     * Changes to default handlers
+     */
+    callbacks?: {
+        /**
+         * Method for calling "sendMessage"
+         */
+        sendMessage?: (node: Node, ...args: Parameters<P2PSwitch['sendMessage']>) => Promise<Awaited<ReturnType<P2PSwitch['sendMessage']>>>;
+    };
+}
+export declare class Node {
+    ledger: Ledger;
+    config: NodeConfig;
+    switch: P2PSwitch;
+    stats: Stats;
+    timing: RequestTiming;
+    readonly networkAddress: NetworkAddress;
+    readonly baseToken: TokenAddress;
+    static Kind: typeof NodeKind;
+    static isInstance: (obj: any, strict?: boolean) => obj is Node;
+    log: {
+        debug: (from: string, ...message: any[]) => void;
+        error: (from: string, ...message: any[]) => void;
+    };
+    static getDefaultConfig(network: Config.Networks): Omit<NodeConfig, 'ledger' | 'stats'>;
+    static main(config: NodeConfig): void;
+    constructor(configOrNode: Node | NodeConfig);
+    copy(): Node;
+    run(): Promise<void>;
+    stop(): Promise<void>;
+    sync(): Promise<void>;
+    addToLedger(votesAndBlocks: VoteStaple, broadcast?: boolean): Promise<boolean>;
+    recvMessageFromPeer(from: P2PConnection, id: string, type: string, data: any, ttl?: number): Promise<boolean>;
+    sendMessage(id: string, type: string, data: any, ttl?: number, exclude?: (P2PConnection | string)[]): Promise<boolean>;
+}
+export default Node;

package/lib/node/local.d.ts

@@ -0,0 +1,30 @@
+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 & {
+    bootstrap?: BootstrapConfig;
+    invokeSecret?: string;
+};
+export type ApiErrorResponse = {
+    error: boolean;
+    message: string;
+    type?: string | null;
+    code?: ErrorCode | null;
+};
+type LocalNodeRunOptions = {
+    startWebSocketServer?: boolean;
+};
+export declare class LocalNode extends Node {
+    #private;
+    static isInstance: (obj: any, strict?: boolean) => obj is LocalNode;
+    constructor(config: LocalNodeConfig);
+    addRoutes(prefix?: string): void;
+    get _app(): import("express-serve-static-core").Express;
+    run(options?: LocalNodeRunOptions): Promise<void>;
+    static main(config: LocalNodeConfig): void;
+    stop(): Promise<void>;
+    get bootstrap(): BootstrapClient | undefined;
+}
+export default LocalNode;

package/lib/node/timing.d.ts

@@ -0,0 +1,12 @@
+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;
+    getAllTiming(): {
+        [section: string]: number;
+    };
+    counter(): number;
+}
+export default RequestTiming;

package/lib/node/utils.d.ts

@@ -0,0 +1,4 @@
+import type { NodeConfig } from '.';
+export declare function getConfigFromEnv(type: 'local' | 'lambda'): Partial<Omit<NodeConfig, 'ledger'> & {
+    ledger: Partial<NodeConfig['ledger']>;
+}>;