Updated type declarations

Signed-off-by: Slava Fomin II <[email protected]>

dist/types/index.d.ts

@@ -1,5 +1,7 @@
 import HttpProvider, { StackElement } from './providers';
-export { CellObject, EstimateFeeBody, HttpProviderOptions, SliceObject, StackElement, } from './providers';
+export { default as HttpProvider, CellObject, EstimateFeeBody, HttpProviderOptions, SliceObject, StackElement, } from './providers';
+import { BlockSubscription, InMemoryBlockStorage } from './providers/block-subscription';
+export { BlockSubscription, InMemoryBlockStorage, LogFunction, BlockHandler, BlockSubscriptionOptions, ShardBlock, BlockStorage, } from './providers/block-subscription';
 import { AddressType } from './utils/Address';
 export { AddressType } from './utils/Address';
 import * as utils from './utils';
@@ -14,8 +16,8 @@ export default class TonWeb {
     static Wallets: any;
     static LockupWallets: any;
     static SubscriptionContract: any;
-    static BlockSubscription: any;
-    static InMemoryBlockStorage: any;
+    static BlockSubscription: typeof BlockSubscription;
+    static InMemoryBlockStorage: typeof InMemoryBlockStorage;
     static ledger: {
         TransportWebUSB: any;
         TransportWebHID: any;
@@ -32,8 +34,8 @@ export default class TonWeb {
     Address: typeof utils.Address;
     boc: any;
     Contract: any;
-    BlockSubscription: any;
-    InMemoryBlockStorage: any;
+    BlockSubscription: typeof BlockSubscription;
+    InMemoryBlockStorage: typeof InMemoryBlockStorage;
     wallet: any;
     lockupWallet: any;
     constructor(provider?: HttpProvider);

dist/types/providers/block-subscription/block-storage.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A shardchain block definition.
+ */
+export interface ShardBlock {
+    workchain: number;
+    shardId: string;
+    shardBlockNumber: number;
+}
+/**
+ * A storage for processed block numbers with
+ * useful query functions.
+ *
+ * Used by `BlockSubscription`.
+ */
+export interface BlockStorage {
+    /**
+     * Inserts new processed masterchain block number and
+     * new unprocessed shardchain blocks numbers.
+     *
+     * Must be in single DB transaction.
+     */
+    insertBlocks(mcBlockNumber: number, shardBlocks: ShardBlock[]): Promise<void>;
+    /**
+     * Returns last processed masterchain block number.
+     */
+    getLastMasterchainBlockNumber(): (Promise<number | undefined>);
+    /**
+     * Marks the specified shardchain block number as processed and
+     * inserts new unprocessed shardchain blocks numbers.
+     *
+     * Must be in single DB transaction.
+     */
+    setBlockProcessed(workchain: number, shardId: string, shardBlockNumber: number, prevShardBlocks: ShardBlock[]): Promise<void>;
+    /**
+     * Returns any unprocessed shard block numbers
+     * (order is not important).
+     */
+    getUnprocessedShardBlock(): (Promise<ShardBlock | undefined>);
+}

dist/types/providers/block-subscription/block-subscription.d.ts

@@ -0,0 +1,81 @@
+import HttpProvider from '../index';
+import { BlockStorage } from './block-storage';
+export interface BlockSubscriptionOptions {
+    /**
+     * Start masterchain block number from which we start
+     * to process blocks. If not specified, the subscription
+     * starts from the last block of the network at the
+     * time of launch.
+     */
+    startMcBlockNumber?: number;
+    mcInterval?: number;
+    shardsInterval?: number;
+}
+export declare type BlockHandler = ((blockHeader: any, blockShards?: any) => (Promise<void> | void));
+export declare class BlockSubscription {
+    /**
+     * TonWeb HTTP provider.
+     */
+    private readonly provider;
+    /**
+     * Persistent storage for storing block numbers
+     * that we have already processed.
+     */
+    private readonly storage;
+    /**
+     * Callback which is called for each block.
+     *
+     * Callback may throw an error, in this case the block
+     * processing will be interrupted and block will not
+     * be saved in the storage as processed.
+     *
+     * Shardchain blocks are processed OUT of chronological order.
+     * Masterchain blocks are processed in chronological order.
+     *
+     * For masterchain `workchain === -1` and
+     * `shardId === -9223372036854775808`
+     */
+    private readonly onBlock;
+    /**
+     * Start masterchain block number from which we start to process blocks.
+     * if not specified, the subscription starts from the last block of the network at the time of launch.
+     */
+    private readonly options;
+    private startMcBlockNumber;
+    private readonly mcInterval;
+    private readonly shardsInterval;
+    private startLT?;
+    private mcIntervalId?;
+    private shardsIntervalId?;
+    constructor(
+    /**
+     * TonWeb HTTP provider.
+     */
+    provider: HttpProvider, 
+    /**
+     * Persistent storage for storing block numbers
+     * that we have already processed.
+     */
+    storage: BlockStorage, 
+    /**
+     * Callback which is called for each block.
+     *
+     * Callback may throw an error, in this case the block
+     * processing will be interrupted and block will not
+     * be saved in the storage as processed.
+     *
+     * Shardchain blocks are processed OUT of chronological order.
+     * Masterchain blocks are processed in chronological order.
+     *
+     * For masterchain `workchain === -1` and
+     * `shardId === -9223372036854775808`
+     */
+    onBlock: BlockHandler, 
+    /**
+     * Start masterchain block number from which we start to process blocks.
+     * if not specified, the subscription starts from the last block of the network at the time of launch.
+     */
+    options: BlockSubscriptionOptions);
+    start(): Promise<void>;
+    stop(): void;
+}

dist/types/providers/block-subscription/in-memory-block-storage.d.ts

@@ -0,0 +1,44 @@
+import { BlockStorage, ShardBlock } from './block-storage';
+export declare type LogFunction = (message: string) => void;
+/**
+ * Simple in-memory implementation of the processed
+ * block number storage.
+ */
+export declare class InMemoryBlockStorage implements BlockStorage {
+    private readonly logFunction;
+    /**
+     * @todo: should we use `Map` here?
+     * Map of the processed masterchain blocks:
+     * `key` is the block number, while
+     * `value` reflects `isProcessed` state.
+     */
+    private readonly masterBlocks;
+    /**
+     * @todo: should we use `Map` here?
+     * Map of the processed shardchain blocks:
+     * The `key` should be constructed this way:
+     * `${workchain}_${shardId}_${shardBlockNumber}`
+     * and the `value` reflects `isProcessed` state.
+     */
+    private readonly shardBlocks;
+    constructor(logFunction: LogFunction);
+    insertBlocks(mcBlockNumber: number, shardBlockNumbers: ShardBlock[]): Promise<void>;
+    getLastMasterchainBlockNumber(): Promise<number | undefined>;
+    setBlockProcessed(workchain: number, shardId: string, shardBlockNumber: number, prevShardBlocks: ShardBlock[]): Promise<void>;
+    getUnprocessedShardBlock(): (Promise<ShardBlock | undefined>);
+    /**
+     * Inserts new unprocessed shardchain block numbers.
+     * Block number (workchain + shardId + shardBlockNumber) should be IGNORED if it is already in the storage.
+     */
+    private insertShardBlocks;
+    /**
+     * Generates unique key for identifying the specified
+     * shardchain block.
+     */
+    private getShardBlockKey;
+    /**
+     * Parses the specified shardchain block key and returns
+     * a shardchain block definition.
+     */
+    private parseShardBlockKey;
+}

dist/types/providers/block-subscription/index.d.ts

@@ -0,0 +1,3 @@
+export { BlockSubscription, BlockSubscriptionOptions, BlockHandler, } from './block-subscription';
+export { BlockStorage, ShardBlock, } from './block-storage';
+export { InMemoryBlockStorage, LogFunction, } from './in-memory-block-storage';

dist/types/providers/block-subscription/sql-block-storage.d.ts

@@ -0,0 +1,11 @@
+import { BlockStorage, ShardBlock } from './block-storage';
+/**
+ * This is just a proof of concept of the
+ * RDBMS (SQL) shardchain block storage implementation.
+ */
+export declare class SqlBlockStorage implements BlockStorage {
+    insertBlocks(mcBlockNumber: number, shardBlockNumbers: ShardBlock[]): Promise<void>;
+    getLastMasterchainBlockNumber(): Promise<number | undefined>;
+    setBlockProcessed(workchain: number, shardId: string, shardBlockNumber: number, prevShardBlocks: ShardBlock[]): Promise<void>;
+    getUnprocessedShardBlock(): (Promise<ShardBlock | undefined>);
+}