@acala-network/chopsticks-core 0.8.0 → 0.8.2

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;
@@ -36,7 +57,7 @@ export declare class Api {
     getBlockHash(blockNumber?: number): Promise<`0x${string}` | null>;
     getHeader(hash?: string): Promise<Header | null>;
     getBlock(hash?: string): Promise<SignedBlock | null>;
-    getStorage(key: string, hash?: string): Promise<string | null>;
+    getStorage(key: string, hash?: string): Promise<`0x${string}` | null>;
     getKeysPaged(prefix: string, pageSize: number, startKey: string, hash?: string): Promise<string[]>;
 }
 export {};

package/lib/api.js

@@ -22,6 +22,28 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 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);
@@ -96,18 +118,43 @@ class Api {
     }
     getStorage(key, hash) {
         return __awaiter(this, void 0, void 0, function* () {
-            const params = [key];
-            if (hash)
-                params.push(hash);
-            return __classPrivateFieldGet(this, _Api_provider, "f").send('state_getStorage', params);
+            const [child, storageKey] = (0, utils_1.splitChildKey)(key);
+            if (child) {
+                // child storage key, use childstate_getStorage
+                const params = [child, storageKey];
+                if (hash)
+                    params.push(hash);
+                return __classPrivateFieldGet(this, _Api_provider, "f").send('childstate_getStorage', params);
+            }
+            else {
+                // main storage key, use state_getStorage
+                const params = [key];
+                if (hash)
+                    params.push(hash);
+                return __classPrivateFieldGet(this, _Api_provider, "f").send('state_getStorage', params);
+            }
         });
     }
     getKeysPaged(prefix, pageSize, startKey, hash) {
         return __awaiter(this, void 0, void 0, function* () {
-            const params = [prefix, pageSize, startKey];
-            if (hash)
-                params.push(hash);
-            return __classPrivateFieldGet(this, _Api_provider, "f").send('state_getKeysPaged', params);
+            const [child, storageKey] = (0, utils_1.splitChildKey)(prefix);
+            if (child) {
+                // child storage key, use childstate_getKeysPaged
+                // strip child prefix from startKey
+                const params = [child, storageKey, pageSize, (0, utils_1.stripChildPrefix)(startKey)];
+                if (hash)
+                    params.push(hash);
+                return __classPrivateFieldGet(this, _Api_provider, "f")
+                    .send('childstate_getKeysPaged', params)
+                    .then((keys) => keys.map((key) => (0, utils_1.prefixedChildKey)(child, key)));
+            }
+            else {
+                // main storage key, use state_getKeysPaged
+                const params = [prefix, pageSize, startKey];
+                if (hash)
+                    params.push(hash);
+                return __classPrivateFieldGet(this, _Api_provider, "f").send('state_getKeysPaged', params);
+            }
         });
     }
 }

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,25 +130,37 @@ class Block {
             }
         });
     }
+    /**
+     * Get paged storage keys.
+     */
     getKeysPaged(options) {
         var _a, _b;
         return __awaiter(this, void 0, void 0, function* () {
             const layer = new storage_layer_1.StorageLayer(this.storage);
             yield layer.fold();
             const prefix = (_a = options.prefix) !== null && _a !== void 0 ? _a : '0x';
-            const startKey = (_b = options.startKey) !== null && _b !== void 0 ? _b : prefix;
+            const startKey = (_b = options.startKey) !== null && _b !== void 0 ? _b : '0x';
             const pageSize = options.pageSize;
             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;
@@ -106,13 +134,18 @@ class Blockchain {
                     .getRepository(entities_1.BlockEntity)
                     .findOne({ where: { [typeof key === 'number' ? 'number' : 'hash']: key } });
                 if (blockData) {
-                    const { hash, number, header, extrinsics, parentHash } = blockData;
-                    const parentBlock = parentHash ? __classPrivateFieldGet(this, _Blockchain_blocksByHash, "f")[parentHash] : undefined;
+                    const { hash, number, header, extrinsics } = blockData;
+                    const parentHash = blockData.parentHash || undefined;
+                    let parentBlock = parentHash ? __classPrivateFieldGet(this, _Blockchain_blocksByHash, "f")[parentHash] : undefined;
+                    if (!parentBlock) {
+                        parentBlock = yield this.getBlock(parentHash);
+                    }
                     const storageDiff = (_a = blockData.storageDiff) !== null && _a !== void 0 ? _a : undefined;
                     const registry = yield this.head.registry;
                     const block = new block_1.Block(this, number, hash, parentBlock, {
                         header: registry.createType('Header', header),
                         extrinsics,
+                        storage: parentBlock === null || parentBlock === void 0 ? void 0 : parentBlock.storage,
                         storageDiff,
                     });
                     __classPrivateFieldGet(this, _Blockchain_instances, "m", _Blockchain_registerBlock).call(this, block);
@@ -122,6 +155,9 @@ class Blockchain {
             return undefined;
         });
     }
+    /**
+     * Get block by number.
+     */
     getBlockAt(number) {
         return __awaiter(this, void 0, void 0, function* () {
             if (number === undefined) {
@@ -145,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;
@@ -181,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* () {
@@ -206,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({
@@ -220,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);
@@ -230,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));
@@ -250,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;
@@ -286,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;
@@ -302,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;
@@ -318,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;
@@ -351,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;
@@ -363,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,15 +6,27 @@ 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 {
     #private;
     constructor(api: Api, at: string, db: DataSource | undefined);
-    get(key: string): Promise<StorageValue>;
+    get(key: string, _cache: boolean): Promise<StorageValue>;
     foldInto(_into: StorageLayer): Promise<StorageLayerProvider>;
     fold(): Promise<void>;
     getKeysPaged(prefix: string, pageSize: number, startKey: string): Promise<string[]>;
@@ -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

@@ -46,7 +46,7 @@ class RemoteStorageLayer {
         __classPrivateFieldSet(this, _RemoteStorageLayer_at, at, "f");
         __classPrivateFieldSet(this, _RemoteStorageLayer_db, db, "f");
     }
-    get(key) {
+    get(key, _cache) {
         var _a, _b;
         return __awaiter(this, void 0, void 0, function* () {
             const keyValuePair = (_a = __classPrivateFieldGet(this, _RemoteStorageLayer_db, "f")) === null || _a === void 0 ? void 0 : _a.getRepository(entities_1.KeyValuePair);
@@ -124,7 +124,7 @@ class StorageLayer {
             if (key in __classPrivateFieldGet(this, _StorageLayer_store, "f")) {
                 return __classPrivateFieldGet(this, _StorageLayer_store, "f")[key];
             }
-            if (__classPrivateFieldGet(this, _StorageLayer_deletedPrefix, "f").some((prefix) => key.startsWith(prefix))) {
+            if (__classPrivateFieldGet(this, _StorageLayer_deletedPrefix, "f").some((dp) => key.startsWith(dp))) {
                 return StorageValueKind.Deleted;
             }
             if (__classPrivateFieldGet(this, _StorageLayer_parent, "f")) {
@@ -194,10 +194,10 @@ class StorageLayer {
     getKeysPaged(prefix, pageSize, startKey) {
         var _a, _b;
         return __awaiter(this, void 0, void 0, function* () {
-            if (!__classPrivateFieldGet(this, _StorageLayer_deletedPrefix, "f").some((prefix) => startKey.startsWith(prefix))) {
+            if (!__classPrivateFieldGet(this, _StorageLayer_deletedPrefix, "f").some((dp) => startKey.startsWith(dp))) {
                 const remote = (_b = (yield ((_a = __classPrivateFieldGet(this, _StorageLayer_parent, "f")) === null || _a === void 0 ? void 0 : _a.getKeysPaged(prefix, pageSize, startKey)))) !== null && _b !== void 0 ? _b : [];
                 for (const key of remote) {
-                    if (__classPrivateFieldGet(this, _StorageLayer_deletedPrefix, "f").some((prefix) => key.startsWith(prefix))) {
+                    if (__classPrivateFieldGet(this, _StorageLayer_deletedPrefix, "f").some((dp) => key.startsWith(dp))) {
                         continue;
                     }
                     __classPrivateFieldGet(this, _StorageLayer_instances, "m", _StorageLayer_addKey).call(this, key);
@@ -219,6 +219,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 {

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/schema/index.d.ts

@@ -34,12 +34,12 @@ export declare const genesisSchema: z.ZodObject<{
     }>;
 }, "strip", z.ZodTypeAny, {
     name: string;
-    id: string;
     properties: {
         ss58Format?: number | undefined;
         tokenDecimals?: number | number[] | undefined;
         tokenSymbol?: string | string[] | undefined;
     };
+    id: string;
     genesis: {
         raw: {
             top: Record<string, string>;
@@ -47,12 +47,12 @@ export declare const genesisSchema: z.ZodObject<{
     };
 }, {
     name: string;
-    id: string;
     properties: {
         ss58Format?: number | undefined;
         tokenDecimals?: number | number[] | undefined;
         tokenSymbol?: string | string[] | undefined;
     };
+    id: string;
     genesis: {
         raw: {
             top: Record<string, string>;

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/lib/utils/index.d.ts

@@ -17,3 +17,7 @@ export type Deferred<T> = {
     promise: Promise<T>;
 };
 export declare function defer<T>(): Deferred<T>;
+export declare const prefixedChildKey: (prefix: HexString, key: HexString) => string;
+export declare const isPrefixedChildKey: (key: HexString) => boolean;
+export declare const splitChildKey: (key: HexString) => never[] | [`0x${string}`, `0x${string}`];
+export declare const stripChildPrefix: (key: HexString) => `0x${string}`;

package/lib/utils/index.js

@@ -23,8 +23,9 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defer = exports.isUrl = exports.getParaId = exports.compactHex = exports.fetchKeysToArray = exports.fetchKeys = void 0;
+exports.stripChildPrefix = exports.splitChildKey = exports.isPrefixedChildKey = exports.prefixedChildKey = exports.defer = exports.isUrl = exports.getParaId = exports.compactHex = exports.fetchKeysToArray = exports.fetchKeys = void 0;
 const util_1 = require("@polkadot/util");
+const hex_1 = require("@polkadot/util/hex");
 __exportStar(require("./set-storage"), exports);
 __exportStar(require("./time-travel"), exports);
 __exportStar(require("./decoder"), exports);
@@ -87,3 +88,34 @@ function defer() {
     return deferred;
 }
 exports.defer = defer;
+// Chopsticks treats both main storage and child storage as a key-value store
+// The difference is that child storage keys are prefixed with the child storage key
+// :child_storage:default: as hex string
+const DEFAULT_CHILD_STORAGE = '0x3a6368696c645f73746f726167653a64656661756c743a';
+// length of the child storage key
+const CHILD_LENGTH = DEFAULT_CHILD_STORAGE.length + 64;
+// returns a key that is prefixed with the child storage key
+const prefixedChildKey = (prefix, key) => prefix + (0, hex_1.hexStripPrefix)(key);
+exports.prefixedChildKey = prefixedChildKey;
+// returns true if the key is a child storage key
+const isPrefixedChildKey = (key) => key.startsWith(DEFAULT_CHILD_STORAGE);
+exports.isPrefixedChildKey = isPrefixedChildKey;
+// returns a key that is split into the child storage key and the rest
+const splitChildKey = (key) => {
+    if (!key.startsWith(DEFAULT_CHILD_STORAGE))
+        return [];
+    if (key.length < CHILD_LENGTH)
+        return [];
+    const child = key.slice(0, CHILD_LENGTH);
+    const rest = key.slice(CHILD_LENGTH);
+    return [child, (0, hex_1.hexAddPrefix)(rest)];
+};
+exports.splitChildKey = splitChildKey;
+// returns a key that is stripped of the child storage key
+const stripChildPrefix = (key) => {
+    const [child, storageKey] = (0, exports.splitChildKey)(key);
+    if (!child)
+        return key;
+    return storageKey;
+};
+exports.stripChildPrefix = stripChildPrefix;

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@acala-network/chopsticks-core",
-  "version": "0.8.0",
-  "author": "Bryan Chen <xlchen1291@gmail.com>",
+  "version": "0.8.2",
+  "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.0",
+    "@acala-network/chopsticks-executor": "0.8.2",
     "@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"