@acala-network/chopsticks-core 0.8.1 → 0.8.3

package/lib/api.d.ts

@@ -1,7 +1,7 @@
 import { ExtDef } from '@polkadot/types/extrinsic/signedExtensions/types';
 import { HexString } from '@polkadot/util/types';
 import { ProviderInterface } from '@polkadot/rpc-provider/types';
-type ChainProperties = {
+export type ChainProperties = {
     ss58Format?: number;
     tokenDecimals?: number[];
     tokenSymbol?: string[];
@@ -22,6 +22,27 @@ type SignedBlock = {
     };
     justifications?: HexString[];
 };
+/**
+ * API class. Calls provider to get on-chain data.
+ * Either `endpoint` or `genesis` porvider must be provided.
+ *
+ * @example Instantiate an API
+ *
+ * ```ts
+ * let provider: ProviderInterface
+ * if (options.genesis) {
+ *  if (typeof options.genesis === 'string') {
+ *    provider = await GenesisProvider.fromUrl(options.genesis)
+ *  } else {
+ *    provider = new GenesisProvider(options.genesis)
+ *  }
+ * } else {
+ *  provider = new WsProvider(options.endpoint)
+ * }
+ * const api = new Api(provider)
+ * await api.isReady
+ * ```
+ */
 export declare class Api {
     #private;
     readonly signedExtensions: ExtDef;

package/lib/api.js

@@ -23,6 +23,27 @@ var _Api_provider, _Api_ready, _Api_chain, _Api_chainProperties;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Api = void 0;
 const utils_1 = require("./utils");
+/**
+ * API class. Calls provider to get on-chain data.
+ * Either `endpoint` or `genesis` porvider must be provided.
+ *
+ * @example Instantiate an API
+ *
+ * ```ts
+ * let provider: ProviderInterface
+ * if (options.genesis) {
+ *  if (typeof options.genesis === 'string') {
+ *    provider = await GenesisProvider.fromUrl(options.genesis)
+ *  } else {
+ *    provider = new GenesisProvider(options.genesis)
+ *  }
+ * } else {
+ *  provider = new WsProvider(options.endpoint)
+ * }
+ * const api = new Api(provider)
+ * await api.isReady
+ * ```
+ */
 class Api {
     constructor(provider, signedExtensions) {
         _Api_provider.set(this, void 0);

package/lib/blockchain/block-builder.d.ts

@@ -2,7 +2,11 @@ import { Header, TransactionValidityError } from '@polkadot/types/interfaces';
 import { Block, TaskCallResponse } from './block';
 import { HexString } from '@polkadot/util/types';
 export declare const newHeader: (head: Block, unsafeBlockHeight?: number) => Promise<Header>;
-export declare const buildBlock: (head: Block, inherents: HexString[], extrinsics: HexString[], ump: Record<number, HexString[]>, onApplyExtrinsicError: (extrinsic: HexString, error: TransactionValidityError) => void, unsafeBlockHeight?: number) => Promise<[Block, HexString[]]>;
+export type BuildBlockCallbacks = {
+    onApplyExtrinsicError?: (extrinsic: HexString, error: TransactionValidityError) => void;
+    onPhaseApplied?: (phase: 'initialize' | 'finalize' | number, resp: TaskCallResponse) => void;
+};
+export declare const buildBlock: (head: Block, inherents: HexString[], extrinsics: HexString[], ump: Record<number, HexString[]>, callbacks?: BuildBlockCallbacks, unsafeBlockHeight?: number) => Promise<[Block, HexString[]]>;
 export declare const dryRunExtrinsic: (head: Block, inherents: HexString[], extrinsic: HexString | {
     call: HexString;
     address: string;

package/lib/blockchain/block-builder.js

@@ -90,7 +90,8 @@ const newHeader = (head, unsafeBlockHeight) => __awaiter(void 0, void 0, void 0,
     return header;
 });
 exports.newHeader = newHeader;
-const initNewBlock = (head, header, inherents, storageLayer) => __awaiter(void 0, void 0, void 0, function* () {
+const initNewBlock = (head, header, inherents, storageLayer, callback) => __awaiter(void 0, void 0, void 0, function* () {
+    var _c, _d;
     const blockNumber = header.number.toNumber();
     const hash = `0x${Math.round(Math.random() * 100000000)
         .toString(16)
@@ -102,19 +103,19 @@ const initNewBlock = (head, header, inherents, storageLayer) => __awaiter(void 0
     });
     {
         // initialize block
-        const { storageDiff } = yield newBlock.call('Core_initialize_block', [header.toHex()]);
-        newBlock.pushStorageLayer().setAll(storageDiff);
-        logger.trace((0, logger_1.truncate)(storageDiff), 'Initialize block');
+        const resp = yield newBlock.call('Core_initialize_block', [header.toHex()]);
+        newBlock.pushStorageLayer().setAll(resp.storageDiff);
+        (_c = callback === null || callback === void 0 ? void 0 : callback.onPhaseApplied) === null || _c === void 0 ? void 0 : _c.call(callback, 'initialize', resp);
     }
     const layers = [];
     // apply inherents
     for (const extrinsic of inherents) {
         try {
-            const { storageDiff } = yield newBlock.call('BlockBuilder_apply_extrinsic', [extrinsic]);
+            const resp = yield newBlock.call('BlockBuilder_apply_extrinsic', [extrinsic]);
             const layer = newBlock.pushStorageLayer();
-            layer.setAll(storageDiff);
+            layer.setAll(resp.storageDiff);
             layers.push(layer);
-            logger.trace((0, logger_1.truncate)(storageDiff), 'Applied inherent');
+            (_d = callback === null || callback === void 0 ? void 0 : callback.onPhaseApplied) === null || _d === void 0 ? void 0 : _d.call(callback, layers.length - 1, resp);
         }
         catch (e) {
             logger.warn('Failed to apply inherents %o %s', e, e);
@@ -126,7 +127,8 @@ const initNewBlock = (head, header, inherents, storageLayer) => __awaiter(void 0
         layers: layers,
     };
 });
-const buildBlock = (head, inherents, extrinsics, ump, onApplyExtrinsicError, unsafeBlockHeight) => __awaiter(void 0, void 0, void 0, function* () {
+const buildBlock = (head, inherents, extrinsics, ump, callbacks, unsafeBlockHeight) => __awaiter(void 0, void 0, void 0, function* () {
+    var _e, _f, _g;
     const registry = yield head.registry;
     const header = yield (0, exports.newHeader)(head, unsafeBlockHeight);
     const newBlockNumber = header.number.toNumber();
@@ -216,15 +218,15 @@ const buildBlock = (head, inherents, extrinsics, ump, onApplyExtrinsicError, uns
     // apply extrinsics
     for (const extrinsic of extrinsics) {
         try {
-            const { result, storageDiff } = yield newBlock.call('BlockBuilder_apply_extrinsic', [extrinsic]);
-            const outcome = registry.createType('ApplyExtrinsicResult', result);
+            const resp = yield newBlock.call('BlockBuilder_apply_extrinsic', [extrinsic]);
+            const outcome = registry.createType('ApplyExtrinsicResult', resp.result);
             if (outcome.isErr) {
-                onApplyExtrinsicError(extrinsic, outcome.asErr);
+                (_e = callbacks === null || callbacks === void 0 ? void 0 : callbacks.onApplyExtrinsicError) === null || _e === void 0 ? void 0 : _e.call(callbacks, extrinsic, outcome.asErr);
                 continue;
             }
-            newBlock.pushStorageLayer().setAll(storageDiff);
-            logger.trace((0, logger_1.truncate)(storageDiff), 'Applied extrinsic');
+            newBlock.pushStorageLayer().setAll(resp.storageDiff);
             includedExtrinsic.push(extrinsic);
+            (_f = callbacks === null || callbacks === void 0 ? void 0 : callbacks.onPhaseApplied) === null || _f === void 0 ? void 0 : _f.call(callbacks, includedExtrinsic.length - 1, resp);
         }
         catch (e) {
             logger.info('Failed to apply extrinsic %o %s', e, e);
@@ -233,16 +235,18 @@ const buildBlock = (head, inherents, extrinsics, ump, onApplyExtrinsicError, uns
     }
     {
         // finalize block
-        const { storageDiff } = yield newBlock.call('BlockBuilder_finalize_block', []);
-        newBlock.pushStorageLayer().setAll(storageDiff);
-        logger.trace((0, logger_1.truncate)(storageDiff), 'Finalize block');
+        const resp = yield newBlock.call('BlockBuilder_finalize_block', []);
+        newBlock.pushStorageLayer().setAll(resp.storageDiff);
+        (_g = callbacks === null || callbacks === void 0 ? void 0 : callbacks.onPhaseApplied) === null || _g === void 0 ? void 0 : _g.call(callbacks, 'finalize', resp);
     }
     const blockData = registry.createType('Block', {
         header,
         extrinsics: includedExtrinsic,
     });
     const storageDiff = yield newBlock.storageDiff();
-    logger.trace(Object.entries(storageDiff).map(([key, value]) => [key, (0, logger_1.truncate)(value)]), 'Final block');
+    if (logger.level.toLowerCase() === 'trace') {
+        logger.trace(Object.entries(storageDiff).map(([key, value]) => [key, (0, logger_1.truncate)(value)]), 'Final block');
+    }
     const finalBlock = new block_1.Block(head.chain, newBlock.number, blockData.hash.toHex(), head, {
         header,
         extrinsics: [...inherents, ...includedExtrinsic],

package/lib/blockchain/block.d.ts

@@ -11,35 +11,86 @@ export type TaskCallResponse = {
     offchainStorageDiff: [HexString, HexString | null][];
     runtimeLogs: string[];
 };
+/**
+ * Block class.
+ *
+ * @example Instantiate a block
+ *
+ * ```ts
+ * const block = new Block(chain, number, hash)
+ * ```
+ *
+ * @example Get storage
+ *
+ * ```ts
+ * const block = await chain.getBlock('0x...')
+ * block.storage()
+ * ```
+ */
 export declare class Block {
     #private;
     readonly number: number;
     readonly hash: HexString;
     constructor(chain: Blockchain, number: number, hash: HexString, parentBlock?: Block, block?: {
+        /** See `@polkadot/types/interfaces` Header */
         header: Header;
+        /** Extrinsics */
         extrinsics: HexString[];
+        /** Storage provider. Default to {@link RemoteStorageLayer} with {@link Blockchain.api chain.api} as remote. */
         storage?: StorageLayerProvider;
+        /** Storage diff to apply. */
         storageDiff?: Record<string, StorageValue | null>;
     });
     get chain(): Blockchain;
     get header(): Header | Promise<Header>;
     get extrinsics(): HexString[] | Promise<HexString[]>;
     get parentBlock(): undefined | Block | Promise<Block | undefined>;
+    /**
+     * Get the block storage.
+     */
     get storage(): StorageLayerProvider;
+    /**
+     * Get the block storage by key.
+     */
     get(key: string): Promise<string | undefined>;
+    /**
+     * Get paged storage keys.
+     */
     getKeysPaged(options: {
         prefix?: string;
         startKey?: string;
         pageSize: number;
     }): Promise<string[]>;
+    /**
+     * Push a layer to the storage stack.
+     */
     pushStorageLayer(): StorageLayer;
+    /**
+     * Pop a layer from the storage stack.
+     */
     popStorageLayer(): void;
+    /**
+     * Get storage diff.
+     */
     storageDiff(): Promise<Record<HexString, HexString | null>>;
+    /**
+     * Get the wasm string.
+     */
     get wasm(): Promise<`0x${string}`>;
+    /**
+     * Set the runtime wasm.
+     */
     setWasm(wasm: HexString): void;
+    /**
+     * Get the type registry.
+     * @see https://polkadot.js.org/docs/api/start/types.create#why-create-types
+     */
     get registry(): Promise<TypeRegistry>;
     get runtimeVersion(): Promise<RuntimeVersion>;
     get metadata(): Promise<HexString>;
     get meta(): Promise<DecoratedMeta>;
+    /**
+     * Call a runtime method.
+     */
     call(method: string, args: HexString[]): Promise<TaskCallResponse>;
 }

package/lib/blockchain/block.js

@@ -30,6 +30,22 @@ const storage_layer_1 = require("./storage-layer");
 const utils_1 = require("../utils");
 const logger_1 = require("../logger");
 const executor_1 = require("../executor");
+/**
+ * Block class.
+ *
+ * @example Instantiate a block
+ *
+ * ```ts
+ * const block = new Block(chain, number, hash)
+ * ```
+ *
+ * @example Get storage
+ *
+ * ```ts
+ * const block = await chain.getBlock('0x...')
+ * block.storage()
+ * ```
+ */
 class Block {
     constructor(chain, number, hash, parentBlock, block) {
         var _a;
@@ -93,10 +109,16 @@ class Block {
         }
         return __classPrivateFieldGet(this, _Block_parentBlock, "f");
     }
+    /**
+     * Get the block storage.
+     */
     get storage() {
         var _a;
         return (_a = __classPrivateFieldGet(this, _Block_storages, "f")[__classPrivateFieldGet(this, _Block_storages, "f").length - 1]) !== null && _a !== void 0 ? _a : __classPrivateFieldGet(this, _Block_baseStorage, "f");
     }
+    /**
+     * Get the block storage by key.
+     */
     get(key) {
         return __awaiter(this, void 0, void 0, function* () {
             const val = yield this.storage.get(key, true);
@@ -108,6 +130,9 @@ class Block {
             }
         });
     }
+    /**
+     * Get paged storage keys.
+     */
     getKeysPaged(options) {
         var _a, _b;
         return __awaiter(this, void 0, void 0, function* () {
@@ -119,14 +144,23 @@ class Block {
             return layer.getKeysPaged(prefix, pageSize, startKey);
         });
     }
+    /**
+     * Push a layer to the storage stack.
+     */
     pushStorageLayer() {
         const layer = new storage_layer_1.StorageLayer(this.storage);
         __classPrivateFieldGet(this, _Block_storages, "f").push(layer);
         return layer;
     }
+    /**
+     * Pop a layer from the storage stack.
+     */
     popStorageLayer() {
         __classPrivateFieldGet(this, _Block_storages, "f").pop();
     }
+    /**
+     * Get storage diff.
+     */
     storageDiff() {
         return __awaiter(this, void 0, void 0, function* () {
             const storage = {};
@@ -136,6 +170,9 @@ class Block {
             return storage;
         });
     }
+    /**
+     * Get the wasm string.
+     */
     get wasm() {
         if (!__classPrivateFieldGet(this, _Block_wasm, "f")) {
             __classPrivateFieldSet(this, _Block_wasm, (() => __awaiter(this, void 0, void 0, function* () {
@@ -149,6 +186,9 @@ class Block {
         }
         return __classPrivateFieldGet(this, _Block_wasm, "f");
     }
+    /**
+     * Set the runtime wasm.
+     */
     setWasm(wasm) {
         const wasmKey = (0, util_2.stringToHex)(':code');
         this.pushStorageLayer().set(wasmKey, wasm);
@@ -158,6 +198,10 @@ class Block {
         __classPrivateFieldSet(this, _Block_meta, undefined, "f");
         __classPrivateFieldSet(this, _Block_metadata, undefined, "f");
     }
+    /**
+     * Get the type registry.
+     * @see https://polkadot.js.org/docs/api/start/types.create#why-create-types
+     */
     get registry() {
         if (!__classPrivateFieldGet(this, _Block_registry, "f")) {
             __classPrivateFieldSet(this, _Block_registry, Promise.all([
@@ -198,6 +242,9 @@ class Block {
         }
         return __classPrivateFieldGet(this, _Block_meta, "f");
     }
+    /**
+     * Call a runtime method.
+     */
     call(method, args) {
         return __awaiter(this, void 0, void 0, function* () {
             const wasm = yield this.wasm;

package/lib/blockchain/index.d.ts

@@ -10,31 +10,74 @@ import { HeadState } from './head-state';
 import { InherentProvider } from './inherent';
 import { OffchainWorker } from '../offchain';
 export interface Options {
+    /** API instance, for getting on-chain data. */
     api: Api;
+    /** Build block mode. Default to Batch. */
     buildBlockMode?: BuildBlockMode;
+    /** Inherent provider, for creating inherents. */
     inherentProvider: InherentProvider;
+    /** Datasource for caching storage and blocks data. */
     db?: DataSource;
+    /** Used to create the initial head. */
     header: {
         number: number;
         hash: HexString;
     };
+    /** Whether to enable mock signature. Any signature starts with 0xdeadbeef and filled by 0xcd is considered valid */
     mockSignatureHost?: boolean;
+    /** Whether to allow wasm unresolved imports. */
     allowUnresolvedImports?: boolean;
+    /** Wasm runtime log level. */
     runtimeLogLevel?: number;
+    /** Polkadot.js custom types registration. */
     registeredTypes: RegisteredTypes;
+    /** Whether to enable offchain Worker. */
     offchainWorker?: boolean;
+    /** Max memory block count */
     maxMemoryBlockCount?: number;
 }
+/**
+ * Local blockchain which provides access to blocks, txpool and methods
+ * to manipulate the chain such as build blocks, submit extrinsics, xcm and more!
+ *
+ * @example
+ *
+ * ```ts
+ * const chain = new Blockchain({
+ *  api,
+ *  buildBlockMode: BuildBlockMode.Manual,
+ *  inherentProvider: inherents,
+ *  header: {
+ *    hash: blockHash,
+ *    number: Number(header.number),
+ *  },
+ *  mockSignatureHost: true,
+ *  allowUnresolvedImports: true,
+ *  registeredTypes: {},
+ * })
+ * // build a block
+ * chain.newBlock()
+ * ```
+ */
 export declare class Blockchain {
     #private;
     readonly uid: string;
+    /** API instance, for getting on-chain data. */
     readonly api: Api;
+    /** Datasource for caching storage and blocks data. */
     readonly db: DataSource | undefined;
+    /** Enable mock signature. Any signature starts with 0xdeadbeef and filled by 0xcd is considered valid */
     readonly mockSignatureHost: boolean;
+    /** Allow wasm unresolved imports. */
     readonly allowUnresolvedImports: boolean;
+    /** Polkadot.js custom types registration. */
     readonly registeredTypes: RegisteredTypes;
+    /** For subscribing and managing the head state. */
     readonly headState: HeadState;
     readonly offchainWorker: OffchainWorker | undefined;
+    /**
+     * @param options - Options for instantiating the blockchain
+     */
     constructor({ api, buildBlockMode, inherentProvider, db, header, mockSignatureHost, allowUnresolvedImports, runtimeLogLevel, registeredTypes, offchainWorker, maxMemoryBlockCount, }: Options);
     get head(): Block;
     get txPool(): TxPool;
@@ -42,24 +85,57 @@ export declare class Blockchain {
     set runtimeLogLevel(level: number);
     saveBlockToDB(block: Block): Promise<void>;
     /**
-     * Try to load block from db and register it
-     * If pass in number, get block by number, else get block by hash
+     * Try to load block from db and register it.
+     * If pass in number, get block by number, else get block by hash.
      */
     loadBlockFromDB(key: number | HexString): Promise<Block | undefined>;
+    /**
+     * Get block by number.
+     */
     getBlockAt(number?: number): Promise<Block | undefined>;
+    /**
+     * Get block by hash.
+     */
     getBlock(hash?: HexString): Promise<Block | undefined>;
+    /**
+     * Get all blocks in memory.
+     */
     blocksInMemory(): Block[];
+    /**
+     * Remove block from memory and db.
+     */
     unregisterBlock(block: Block): Promise<void>;
     onNewBlock(block: Block): Promise<void>;
+    /**
+     * Set block as head.
+     */
     setHead(block: Block): Promise<void>;
+    /**
+     * Submit extrinsic to txpool.
+     */
     submitExtrinsic(extrinsic: HexString): Promise<HexString>;
+    /**
+     * Validate extrinsic by calling `TaggedTransactionQueue_validate_transaction`.
+     */
     validateExtrinsic(extrinsic: HexString, source?: '0x00' | '0x01' | '0x02' /** External */): Promise<TransactionValidity>;
     submitUpwardMessages(id: number, ump: HexString[]): void;
     submitDownwardMessages(dmp: DownwardMessage[]): void;
     submitHorizontalMessages(id: number, hrmp: HorizontalMessage[]): void;
+    /**
+     * Build a new block with optional params. Use this when you don't have all the {@link BuildBlockParams}
+     */
     newBlock(params?: Partial<BuildBlockParams>): Promise<Block>;
+    /**
+     * Build a new block with {@link BuildBlockParams}.
+     */
     newBlockWithParams(params: BuildBlockParams): Promise<Block>;
+    /**
+     * Get the upcoming blocks.
+     */
     upcomingBlocks(): Promise<number>;
+    /**
+     * Dry run extrinsic in block `at`.
+     */
     dryRunExtrinsic(extrinsic: HexString | {
         call: HexString;
         address: string;
@@ -67,9 +143,27 @@ export declare class Blockchain {
         outcome: ApplyExtrinsicResult;
         storageDiff: [HexString, HexString | null][];
     }>;
+    /**
+     * Dry run hrmp messages in block `at`.
+     * Return the storage diff.
+     */
     dryRunHrmp(hrmp: Record<number, HorizontalMessage[]>, at?: HexString): Promise<[HexString, HexString | null][]>;
+    /**
+     * Dry run dmp messages in block `at`.
+     * Return the storage diff.
+     */
     dryRunDmp(dmp: DownwardMessage[], at?: HexString): Promise<[HexString, HexString | null][]>;
+    /**
+     * Dry run ump messages in block `at`.
+     * Return the storage diff.
+     */
     dryRunUmp(ump: Record<number, HexString[]>, at?: HexString): Promise<[HexString, HexString | null][]>;
+    /**
+     * Get inherents of head.
+     */
     getInherents(): Promise<HexString[]>;
+    /**
+     * Close the db.
+     */
     close(): Promise<void>;
 }

package/lib/blockchain/index.js

@@ -33,7 +33,33 @@ const utils_1 = require("../utils");
 const logger_1 = require("../logger");
 const block_builder_1 = require("./block-builder");
 const logger = logger_1.defaultLogger.child({ name: 'blockchain' });
+/**
+ * Local blockchain which provides access to blocks, txpool and methods
+ * to manipulate the chain such as build blocks, submit extrinsics, xcm and more!
+ *
+ * @example
+ *
+ * ```ts
+ * const chain = new Blockchain({
+ *  api,
+ *  buildBlockMode: BuildBlockMode.Manual,
+ *  inherentProvider: inherents,
+ *  header: {
+ *    hash: blockHash,
+ *    number: Number(header.number),
+ *  },
+ *  mockSignatureHost: true,
+ *  allowUnresolvedImports: true,
+ *  registeredTypes: {},
+ * })
+ * // build a block
+ * chain.newBlock()
+ * ```
+ */
 class Blockchain {
+    /**
+     * @param options - Options for instantiating the blockchain
+     */
     constructor({ api, buildBlockMode, inherentProvider, db, header, mockSignatureHost = false, allowUnresolvedImports = false, runtimeLogLevel = 0, registeredTypes = {}, offchainWorker = false, maxMemoryBlockCount = 2000, }) {
         _Blockchain_instances.add(this);
         this.uid = Math.random().toString(36).substring(2);
@@ -43,7 +69,9 @@ class Blockchain {
         _Blockchain_head.set(this, void 0);
         _Blockchain_blocksByNumber.set(this, new Map());
         _Blockchain_blocksByHash.set(this, {});
-        _Blockchain_loadingBlocks.set(this, {});
+        _Blockchain_loadingBlocks.set(this, {}
+        /** For subscribing and managing the head state. */
+        );
         _Blockchain_maxMemoryBlockCount.set(this, void 0);
         this.api = api;
         this.db = db;
@@ -95,8 +123,8 @@ class Blockchain {
         });
     }
     /**
-     * Try to load block from db and register it
-     * If pass in number, get block by number, else get block by hash
+     * Try to load block from db and register it.
+     * If pass in number, get block by number, else get block by hash.
      */
     loadBlockFromDB(key) {
         var _a;
@@ -127,6 +155,9 @@ class Blockchain {
             return undefined;
         });
     }
+    /**
+     * Get block by number.
+     */
     getBlockAt(number) {
         return __awaiter(this, void 0, void 0, function* () {
             if (number === undefined) {
@@ -150,6 +181,9 @@ class Blockchain {
             return __classPrivateFieldGet(this, _Blockchain_blocksByNumber, "f").get(number);
         });
     }
+    /**
+     * Get block by hash.
+     */
     getBlock(hash) {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.api.isReady;
@@ -186,9 +220,15 @@ class Blockchain {
             return __classPrivateFieldGet(this, _Blockchain_blocksByHash, "f")[hash];
         });
     }
+    /**
+     * Get all blocks in memory.
+     */
     blocksInMemory() {
         return Array.from(__classPrivateFieldGet(this, _Blockchain_blocksByNumber, "f").values());
     }
+    /**
+     * Remove block from memory and db.
+     */
     unregisterBlock(block) {
         var _a;
         return __awaiter(this, void 0, void 0, function* () {
@@ -211,6 +251,9 @@ class Blockchain {
             yield this.saveBlockToDB(block);
         });
     }
+    /**
+     * Set block as head.
+     */
     setHead(block) {
         return __awaiter(this, void 0, void 0, function* () {
             logger.debug({
@@ -225,6 +268,9 @@ class Blockchain {
             }
         });
     }
+    /**
+     * Submit extrinsic to txpool.
+     */
     submitExtrinsic(extrinsic) {
         return __awaiter(this, void 0, void 0, function* () {
             const validity = yield this.validateExtrinsic(extrinsic);
@@ -235,6 +281,9 @@ class Blockchain {
             throw validity.asErr;
         });
     }
+    /**
+     * Validate extrinsic by calling `TaggedTransactionQueue_validate_transaction`.
+     */
     validateExtrinsic(extrinsic, source = '0x02' /** External */) {
         return __awaiter(this, void 0, void 0, function* () {
             const args = (0, util_1.u8aToHex)((0, util_1.u8aConcat)(source, extrinsic, this.head.hash));
@@ -255,23 +304,35 @@ class Blockchain {
         __classPrivateFieldGet(this, _Blockchain_txpool, "f").submitHorizontalMessages(id, hrmp);
         logger.debug({ id, hrmp }, 'submitHorizontalMessages');
     }
+    /**
+     * Build a new block with optional params. Use this when you don't have all the {@link BuildBlockParams}
+     */
     newBlock(params) {
         return __awaiter(this, void 0, void 0, function* () {
             yield __classPrivateFieldGet(this, _Blockchain_txpool, "f").buildBlock(params);
             return __classPrivateFieldGet(this, _Blockchain_head, "f");
         });
     }
+    /**
+     * Build a new block with {@link BuildBlockParams}.
+     */
     newBlockWithParams(params) {
         return __awaiter(this, void 0, void 0, function* () {
             yield __classPrivateFieldGet(this, _Blockchain_txpool, "f").buildBlockWithParams(params);
             return __classPrivateFieldGet(this, _Blockchain_head, "f");
         });
     }
+    /**
+     * Get the upcoming blocks.
+     */
     upcomingBlocks() {
         return __awaiter(this, void 0, void 0, function* () {
             return __classPrivateFieldGet(this, _Blockchain_txpool, "f").upcomingBlocks();
         });
     }
+    /**
+     * Dry run extrinsic in block `at`.
+     */
     dryRunExtrinsic(extrinsic, at) {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.api.isReady;
@@ -291,6 +352,10 @@ class Blockchain {
             return { outcome, storageDiff };
         });
     }
+    /**
+     * Dry run hrmp messages in block `at`.
+     * Return the storage diff.
+     */
     dryRunHrmp(hrmp, at) {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.api.isReady;
@@ -307,6 +372,10 @@ class Blockchain {
             return (0, block_builder_1.dryRunInherents)(head, inherents);
         });
     }
+    /**
+     * Dry run dmp messages in block `at`.
+     * Return the storage diff.
+     */
     dryRunDmp(dmp, at) {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.api.isReady;
@@ -323,6 +392,10 @@ class Blockchain {
             return (0, block_builder_1.dryRunInherents)(head, inherents);
         });
     }
+    /**
+     * Dry run ump messages in block `at`.
+     * Return the storage diff.
+     */
     dryRunUmp(ump, at) {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.api.isReady;
@@ -356,6 +429,9 @@ class Blockchain {
             return (0, block_builder_1.dryRunInherents)(head, inherents);
         });
     }
+    /**
+     * Get inherents of head.
+     */
     getInherents() {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.api.isReady;
@@ -368,6 +444,9 @@ class Blockchain {
             return inherents;
         });
     }
+    /**
+     * Close the db.
+     */
     close() {
         var _a;
         return __awaiter(this, void 0, void 0, function* () {

package/lib/blockchain/storage-layer.d.ts

@@ -6,9 +6,21 @@ export declare const enum StorageValueKind {
 }
 export type StorageValue = string | StorageValueKind | undefined;
 export interface StorageLayerProvider {
+    /**
+     * Get the value of a storage key.
+     */
     get(key: string, cache: boolean): Promise<StorageValue>;
+    /**
+     * Fold the storage layer into another layer.
+     */
     foldInto(into: StorageLayer): Promise<StorageLayerProvider | undefined>;
+    /**
+     * Fold the storage layer into the parent if it exists.
+     */
     fold(): Promise<void>;
+    /**
+     * Get paged storage keys.
+     */
     getKeysPaged(prefix: string, pageSize: number, startKey: string): Promise<string[]>;
 }
 export declare class RemoteStorageLayer implements StorageLayerProvider {
@@ -28,5 +40,8 @@ export declare class StorageLayer implements StorageLayerProvider {
     foldInto(into: StorageLayer): Promise<StorageLayerProvider | undefined>;
     fold(): Promise<void>;
     getKeysPaged(prefix: string, pageSize: number, startKey: string): Promise<string[]>;
+    /**
+     * Merge the storage layer into the given object, can be used to get sotrage diff.
+     */
     mergeInto(into: Record<string, string | null>): Promise<void>;
 }

package/lib/blockchain/storage-layer.js

@@ -1,4 +1,27 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -28,7 +51,7 @@ exports.StorageLayer = exports.RemoteStorageLayer = exports.StorageValueKind = v
 const lodash_1 = __importDefault(require("lodash"));
 const entities_1 = require("../db/entities");
 const logger_1 = require("../logger");
-const key_cache_1 = __importDefault(require("../utils/key-cache"));
+const key_cache_1 = __importStar(require("../utils/key-cache"));
 const logger = logger_1.defaultLogger.child({ name: 'layer' });
 const BATCH_SIZE = 1000;
 var StorageValueKind;
@@ -76,7 +99,7 @@ class RemoteStorageLayer {
                 throw new Error(`pageSize must be less or equal to ${BATCH_SIZE}`);
             logger.trace({ at: __classPrivateFieldGet(this, _RemoteStorageLayer_at, "f"), prefix, pageSize, startKey }, 'RemoteStorageLayer getKeysPaged');
             // can't handle keyCache without prefix
-            if (prefix.length < 66) {
+            if (prefix.length < key_cache_1.PREFIX_LENGTH || startKey.length < key_cache_1.PREFIX_LENGTH) {
                 return __classPrivateFieldGet(this, _RemoteStorageLayer_api, "f").getKeysPaged(prefix, pageSize, startKey, __classPrivateFieldGet(this, _RemoteStorageLayer_at, "f"));
             }
             let batchComplete = false;
@@ -219,6 +242,9 @@ class StorageLayer {
             return res;
         });
     }
+    /**
+     * Merge the storage layer into the given object, can be used to get sotrage diff.
+     */
     mergeInto(into) {
         return __awaiter(this, void 0, void 0, function* () {
             for (const [key, maybeValue] of Object.entries(__classPrivateFieldGet(this, _StorageLayer_store, "f"))) {

package/lib/blockchain/txpool.d.ts

@@ -4,8 +4,11 @@ import { Blockchain } from '.';
 import { InherentProvider } from './inherent';
 export declare const APPLY_EXTRINSIC_ERROR = "TxPool::ApplyExtrinsicError";
 export declare enum BuildBlockMode {
+    /** One block per batch (default) */
     Batch = 0,
+    /** One block per tx */
     Instant = 1,
+    /** Only build when triggered */
     Manual = 2
 }
 export interface DownwardMessage {

package/lib/blockchain/txpool.js

@@ -34,8 +34,11 @@ const logger = logger_1.defaultLogger.child({ name: 'txpool' });
 exports.APPLY_EXTRINSIC_ERROR = 'TxPool::ApplyExtrinsicError';
 var BuildBlockMode;
 (function (BuildBlockMode) {
+    /** One block per batch (default) */
     BuildBlockMode[BuildBlockMode["Batch"] = 0] = "Batch";
+    /** One block per tx */
     BuildBlockMode[BuildBlockMode["Instant"] = 1] = "Instant";
+    /** Only build when triggered */
     BuildBlockMode[BuildBlockMode["Manual"] = 2] = "Manual";
 })(BuildBlockMode || (exports.BuildBlockMode = BuildBlockMode = {}));
 class TxPool {
@@ -206,8 +209,24 @@ _TxPool_chain = new WeakMap(), _TxPool_pool = new WeakMap(), _TxPool_ump = new W
         logger.trace({ params }, 'build block');
         const head = __classPrivateFieldGet(this, _TxPool_chain, "f").head;
         const inherents = yield __classPrivateFieldGet(this, _TxPool_inherentProvider, "f").createInherents(head, params);
-        const [newBlock, pendingExtrinsics] = yield (0, block_builder_1.buildBlock)(head, inherents, params.transactions, params.upwardMessages, (extrinsic, error) => {
-            this.event.emit(exports.APPLY_EXTRINSIC_ERROR, [extrinsic, error]);
+        const [newBlock, pendingExtrinsics] = yield (0, block_builder_1.buildBlock)(head, inherents, params.transactions, params.upwardMessages, {
+            onApplyExtrinsicError: (extrinsic, error) => {
+                this.event.emit(exports.APPLY_EXTRINSIC_ERROR, [extrinsic, error]);
+            },
+            onPhaseApplied: logger.level.toLowerCase() === 'trace'
+                ? (phase, resp) => {
+                    switch (phase) {
+                        case 'initialize':
+                            logger.trace((0, logger_1.truncate)(resp.storageDiff), 'Initialize block');
+                            break;
+                        case 'finalize':
+                            logger.trace((0, logger_1.truncate)(resp.storageDiff), 'Finalize block');
+                            break;
+                        default:
+                            logger.trace((0, logger_1.truncate)(resp.storageDiff), `Apply extrinsic ${phase}`);
+                    }
+                }
+                : undefined,
         }, params.unsafeBlockHeight);
         for (const extrinsic of pendingExtrinsics) {
             __classPrivateFieldGet(this, _TxPool_pool, "f").push({ extrinsic, signer: yield __classPrivateFieldGet(this, _TxPool_instances, "m", _TxPool_getSigner).call(this, extrinsic) });

package/lib/executor.js

@@ -18,6 +18,7 @@ const util_crypto_1 = require("@polkadot/util-crypto");
 const key_cache_1 = require("./utils/key-cache");
 const chopsticks_executor_1 = require("@acala-network/chopsticks-executor");
 const logger_1 = require("./logger");
+const utils_1 = require("./utils");
 const lodash_1 = __importDefault(require("lodash"));
 const logger = logger_1.defaultLogger.child({ name: 'executor' });
 const getRuntimeVersion = (code) => __awaiter(void 0, void 0, void 0, function* () {
@@ -78,7 +79,7 @@ const taskHandler = (block) => {
                     pageSize: 1,
                     startKey: key,
                 });
-                return nextKey;
+                return nextKey && (0, utils_1.stripChildPrefix)(nextKey);
             });
         },
         offchainGetStorage: function (key) {

package/lib/index.d.ts

@@ -1,9 +1,19 @@
+/**
+ * Chopsticks core package. A common package for usage in both server and browser.
+ * It contains a local blockchain implementation, a transaction pool, a runtime executor and more!
+ *
+ * @privateRemarks
+ * Above is the package description for `chopsticks-core` package.
+ *
+ * @packageDocumentation
+ */
 export * from './api';
 export * from './blockchain';
 export * from './blockchain/block';
 export * from './blockchain/block-builder';
 export * from './blockchain/txpool';
 export * from './blockchain/storage-layer';
+export * from './blockchain/head-state';
 export * from './utils';
 export * from './executor';
 export * from './schema';
@@ -11,3 +21,4 @@ export * from './xcm';
 export * from './setup';
 export * from './blockchain/inherent';
 export * from './logger';
+export * from './offchain';

package/lib/index.js

@@ -14,12 +14,22 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Chopsticks core package. A common package for usage in both server and browser.
+ * It contains a local blockchain implementation, a transaction pool, a runtime executor and more!
+ *
+ * @privateRemarks
+ * Above is the package description for `chopsticks-core` package.
+ *
+ * @packageDocumentation
+ */
 __exportStar(require("./api"), exports);
 __exportStar(require("./blockchain"), exports);
 __exportStar(require("./blockchain/block"), exports);
 __exportStar(require("./blockchain/block-builder"), exports);
 __exportStar(require("./blockchain/txpool"), exports);
 __exportStar(require("./blockchain/storage-layer"), exports);
+__exportStar(require("./blockchain/head-state"), exports);
 __exportStar(require("./utils"), exports);
 __exportStar(require("./executor"), exports);
 __exportStar(require("./schema"), exports);
@@ -27,3 +37,4 @@ __exportStar(require("./xcm"), exports);
 __exportStar(require("./setup"), exports);
 __exportStar(require("./blockchain/inherent"), exports);
 __exportStar(require("./logger"), exports);
+__exportStar(require("./offchain"), exports);

package/lib/setup.d.ts

@@ -3,7 +3,7 @@ import { RegisteredTypes } from '@polkadot/types/types';
 import { Blockchain } from './blockchain';
 import { BuildBlockMode } from './blockchain/txpool';
 import { Genesis } from './schema';
-type Options = {
+export type SetupOptions = {
     endpoint?: string;
     block?: string | number | null;
     genesis?: string | Genesis;
@@ -16,5 +16,4 @@ type Options = {
     offchainWorker?: boolean;
     maxMemoryBlockCount?: number;
 };
-export declare const setup: (options: Options) => Promise<Blockchain>;
-export {};
+export declare const setup: (options: SetupOptions) => Promise<Blockchain>;

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@acala-network/chopsticks-core",
-  "version": "0.8.1",
-  "author": "Bryan Chen <xlchen1291@gmail.com>",
+  "version": "0.8.3",
+  "author": "Acala Developers <hello@acala.network>",
   "license": "Apache-2.0",
   "scripts": {
     "clean": "rm -rf lib tsconfig.tsbuildinfo",
     "pack-wasm": "scripts/pack-wasm.js",
-    "build": "yarn pack-wasm; tsc -p ./tsconfig.json"
+    "build": "yarn pack-wasm; tsc -p ./tsconfig.json",
+    "docs:prep": "typedoc"
   },
   "dependencies": {
-    "@acala-network/chopsticks-executor": "0.8.1",
+    "@acala-network/chopsticks-executor": "0.8.3",
     "@polkadot/api": "^10.9.1",
     "@polkadot/util-crypto": "^12.3.2",
-    "axios": "^1.5.0",
+    "axios": "^1.5.1",
     "eventemitter3": "^5.0.1",
     "localforage": "^1.10.0",
     "lodash": "^4.17.21",
@@ -21,10 +22,10 @@
     "sql.js": "^1.8.0",
     "sqlite3": "^5.1.6",
     "typeorm": "^0.3.17",
-    "zod": "^3.22.2"
+    "zod": "^3.22.3"
   },
   "devDependencies": {
-    "@types/lodash": "^4.14.197",
+    "@types/lodash": "^4.14.199",
     "@types/sql.js": "^1.4.4",
     "fflate": "^0.8.0",
     "typescript": "^5.1.6"