@acala-network/chopsticks-core 1.4.2 → 1.5.0

package/dist/cjs/api.d.ts

@@ -36,6 +36,11 @@ export declare class Api {
     getStorage(key: string, hash?: string): Promise<`0x${string}` | null>;
     getKeysPaged(prefix: string, pageSize: number, startKey: string, hash?: string): Promise<`0x${string}`[]>;
     getStorageBatch(prefix: HexString, keys: HexString[], hash?: HexString): any;
+    /** Upstream `state_getReadProof`. Throws if upstream doesn't expose it. */
+    getReadProof(keys: HexString[], hash?: HexString): Promise<{
+        at: HexString;
+        proof: HexString[];
+    }>;
     subscribeRemoteNewHeads(cb: ProviderInterfaceCallback): Promise<string | number>;
     subscribeRemoteFinalizedHeads(cb: ProviderInterfaceCallback): Promise<string | number>;
 }

package/dist/cjs/api.js

@@ -234,6 +234,15 @@ class Api {
         if (hash) params.push(hash);
         return _class_private_field_get(this, _provider).send('state_queryStorageAt', params, !!hash).then((result)=>result[0]?.['changes'] || []).catch(retryOnError);
     }
+    /** Upstream `state_getReadProof`. Throws if upstream doesn't expose it. */ async getReadProof(keys, hash) {
+        const params = hash ? [
+            keys,
+            hash
+        ] : [
+            keys
+        ];
+        return this.send('state_getReadProof', params, !!hash);
+    }
     async subscribeRemoteNewHeads(cb) {
         if (!_class_private_field_get(this, _provider).hasSubscriptions) {
             throw new Error('subscribeRemoteNewHeads only works with subscriptions');

package/dist/cjs/bridge/encode.d.ts

@@ -0,0 +1,5 @@
+import type { HexString } from '@polkadot/util/types';
+/** `ParaInfo { best_head_hash: { at_relay_block_number: u32, head_hash: H256 }, next_imported_hash_position: u32 }` */
+export declare const encodeParaInfo: (atRelayBlockNumber: number, headHash: Uint8Array, nextImportedHashPosition: number) => HexString;
+/** `ParaStoredHeaderData(Vec<u8>)` wrapping SCALE-encoded `StoredHeaderData { number: u32, state_root: H256 }`. */
+export declare const encodeParaStoredHeaderData: (blockNumber: number, stateRoot: Uint8Array) => HexString;

package/dist/cjs/bridge/encode.js

@@ -0,0 +1,38 @@
+// Value encoders for `pallet_bridge_parachains` storage items. The bridge connector forges
+// these values via `dev_setStorage`, so they're SCALE-encoded by hand — runtime metadata
+// describes their types but can't construct them. Storage *keys*, by contrast, are derived
+// from metadata by the callers (`api.query[pallet].item.key(...)`), never hand-hashed.
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get encodeParaInfo () {
+        return encodeParaInfo;
+    },
+    get encodeParaStoredHeaderData () {
+        return encodeParaStoredHeaderData;
+    }
+});
+const _util = require("@polkadot/util");
+const u32LE = (v)=>(0, _util.nToU8a)(v, {
+        bitLength: 32,
+        isLe: true
+    });
+const requireBytes = (label, b, len)=>{
+    if (b.length !== len) throw new Error(`${label} must be ${len} bytes, got ${b.length}`);
+};
+const encodeParaInfo = (atRelayBlockNumber, headHash, nextImportedHashPosition)=>{
+    requireBytes('headHash', headHash, 32);
+    return (0, _util.u8aToHex)((0, _util.u8aConcat)(u32LE(atRelayBlockNumber), headHash, u32LE(nextImportedHashPosition)));
+};
+const encodeParaStoredHeaderData = (blockNumber, stateRoot)=>{
+    requireBytes('stateRoot', stateRoot, 32);
+    return (0, _util.u8aToHex)((0, _util.compactAddLength)((0, _util.u8aConcat)(u32LE(blockNumber), stateRoot)));
+};

package/dist/cjs/bridge/index.d.ts

@@ -0,0 +1,2 @@
+export declare const bridgeLogger: import("pino").Logger<never, boolean>;
+export * from './encode.js';

package/dist/cjs/bridge/index.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "bridgeLogger", {
+    enumerable: true,
+    get: function() {
+        return bridgeLogger;
+    }
+});
+const _logger = require("../logger.js");
+_export_star(require("./encode.js"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}
+const bridgeLogger = _logger.defaultLogger.child({
+    name: 'bridge'
+});

package/dist/cjs/index.d.ts

@@ -37,6 +37,7 @@ export * from './blockchain/index.js';
 export * from './blockchain/inherent/index.js';
 export * from './blockchain/storage-layer.js';
 export * from './blockchain/txpool.js';
+export * from './bridge/index.js';
 export * from './chopsticks-provider.js';
 export * from './database.js';
 export * from './env.js';

package/dist/cjs/index.js

@@ -18,6 +18,7 @@ _export_star(require("./blockchain/index.js"), exports);
 _export_star(require("./blockchain/inherent/index.js"), exports);
 _export_star(require("./blockchain/storage-layer.js"), exports);
 _export_star(require("./blockchain/txpool.js"), exports);
+_export_star(require("./bridge/index.js"), exports);
 _export_star(require("./chopsticks-provider.js"), exports);
 _export_star(require("./database.js"), exports);
 _export_star(require("./env.js"), exports);

package/dist/cjs/rpc/dev/get-read-proof.d.ts

@@ -0,0 +1,20 @@
+import type { HexString } from '@polkadot/util/types';
+import type { Handler } from '../shared.js';
+/**
+ * @param context
+ * @param params - [`keys`, `blockhash?`]
+ *
+ * @return `{ at, proof, stateRoot }`
+ *
+ * Chopsticks-specific variant of `state_getReadProof` that also returns `stateRoot` — the
+ * root the composed proof verifies against, which verifiers must check instead of the header
+ * state root (see `buildReadProof`). Kept out of the spec method so it stays `{ at, proof }`.
+ */
+export declare const dev_getReadProof: Handler<[
+    HexString[],
+    HexString | undefined
+], {
+    at: HexString;
+    proof: HexString[];
+    stateRoot: HexString;
+}>;

package/dist/cjs/rpc/dev/get-read-proof.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "dev_getReadProof", {
+    enumerable: true,
+    get: function() {
+        return dev_getReadProof;
+    }
+});
+const _readproof = require("../read-proof.js");
+const dev_getReadProof = async (context, [keys, hash])=>(0, _readproof.buildReadProof)(context, keys, hash);

package/dist/cjs/rpc/dev/index.d.ts

@@ -1,4 +1,9 @@
 declare const handlers: {
+    dev_getReadProof: import("../shared.js").Handler<[`0x${string}`[], `0x${string}` | undefined], {
+        at: import("@polkadot/util/types").HexString;
+        proof: import("@polkadot/util/types").HexString[];
+        stateRoot: import("@polkadot/util/types").HexString;
+    }>;
     dev_newBlock: (context: import("../shared.js").Context, [params]: [import("./new-block.js").NewBlockParams]) => Promise<`0x${string}`>;
     dev_setBlockBuildMode: (context: import("../shared.js").Context, [mode]: [import("../../index.js").BuildBlockMode]) => Promise<void>;
     dev_setHead: (context: import("../shared.js").Context, [params]: [number | `0x${string}`]) => Promise<`0x${string}`>;
@@ -7,6 +12,7 @@ declare const handlers: {
     dev_timeTravel: (context: import("../shared.js").Context, [date]: [string | number]) => Promise<number>;
 };
 export default handlers;
+export * from './get-read-proof.js';
 export * from './new-block.js';
 export * from './set-block-build-mode.js';
 export * from './set-head.js';

package/dist/cjs/rpc/dev/index.js

@@ -8,6 +8,7 @@ Object.defineProperty(exports, "default", {
         return _default;
     }
 });
+const _getreadproof = _export_star(require("./get-read-proof.js"), exports);
 const _newblock = _export_star(require("./new-block.js"), exports);
 const _setblockbuildmode = _export_star(require("./set-block-build-mode.js"), exports);
 const _sethead = _export_star(require("./set-head.js"), exports);
@@ -28,6 +29,7 @@ function _export_star(from, to) {
     return from;
 }
 const handlers = {
+    dev_getReadProof: _getreadproof.dev_getReadProof,
     dev_newBlock: _newblock.dev_newBlock,
     dev_setBlockBuildMode: _setblockbuildmode.dev_setBlockBuildMode,
     dev_setHead: _sethead.dev_setHead,

package/dist/cjs/rpc/read-proof.d.ts

@@ -0,0 +1,15 @@
+import type { HexString } from '@polkadot/util/types';
+import { type Context } from './shared.js';
+/**
+ * Compose a storage read proof: chopsticks keeps no trie of its own, so it fetches a base
+ * proof from upstream (falling back to upstream head for chopsticks-only blocks) and
+ * re-applies chopsticks-side values via `createProof`. Returns the proof nodes and the
+ * recomputed trie root — which diverges from `chain_getHeader(at).state_root` once local
+ * overrides are applied. Shared by `state_getReadProof` (drops the root, spec shape) and
+ * `dev_getReadProof` (keeps it). Child-storage keys are rejected.
+ */
+export declare const buildReadProof: (context: Context, keys: HexString[], hash: HexString | undefined) => Promise<{
+    at: HexString;
+    proof: HexString[];
+    stateRoot: HexString;
+}>;

package/dist/cjs/rpc/read-proof.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "buildReadProof", {
+    enumerable: true,
+    get: function() {
+        return buildReadProof;
+    }
+});
+const _logger = require("../logger.js");
+const _index = require("../utils/index.js");
+const _index1 = require("../wasm-executor/index.js");
+const _shared = require("./shared.js");
+const logger = _logger.defaultLogger.child({
+    name: 'rpc-read-proof'
+});
+const buildReadProof = async (context, keys, hash)=>{
+    if (keys.length === 0) {
+        throw new _shared.ResponseError(-32602, 'getReadProof requires a non-empty array of keys');
+    }
+    for (const key of keys){
+        if ((0, _index.isPrefixedChildKey)(key)) {
+            throw new _shared.ResponseError(-32601, `getReadProof does not support child-storage keys (got ${key}); use state_getChildReadProof`);
+        }
+    }
+    const block = await context.chain.getBlock(hash);
+    if (!block) {
+        throw new _shared.ResponseError(1, `Block ${hash ?? 'head'} not found`);
+    }
+    // Upstream rejects chopsticks-only blocks with UnknownBlock; fall back to upstream
+    // head whose trie is guaranteed available.
+    const fetchUpstreamProof = async ()=>{
+        try {
+            return await context.chain.api.getReadProof(keys, block.hash);
+        } catch (err) {
+            logger.debug({
+                err: err.message,
+                blockHash: block.hash
+            }, 'getReadProof at block failed; retrying at head');
+            try {
+                return await context.chain.api.getReadProof(keys);
+            } catch (err2) {
+                throw new _shared.ResponseError(-32603, `getReadProof: upstream rejected at block ${block.hash} and at head (${err2.message})`);
+            }
+        }
+    };
+    // The local reads and the upstream proof are independent — overlap their round trips.
+    const [updates, upstreamProof] = await Promise.all([
+        Promise.all(keys.map(async (key)=>[
+                key,
+                await block.get(key) ?? null
+            ])),
+        fetchUpstreamProof()
+    ]);
+    const { trieRootHash, nodes } = await (0, _index1.createProof)(upstreamProof.proof, updates);
+    return {
+        at: block.hash,
+        proof: nodes,
+        stateRoot: trieRootHash
+    };
+};

package/dist/cjs/rpc/substrate/index.d.ts

@@ -35,6 +35,10 @@ declare const handlers: {
         changes: [string, string | null][];
     }]>;
     state_call: import("../shared.js").Handler<[import("@polkadot/util/types").HexString, import("@polkadot/util/types").HexString, import("@polkadot/util/types").HexString], import("@polkadot/util/types").HexString>;
+    state_getReadProof: import("../shared.js").Handler<[import("@polkadot/util/types").HexString[], import("@polkadot/util/types").HexString | undefined], {
+        at: import("@polkadot/util/types").HexString;
+        proof: import("@polkadot/util/types").HexString[];
+    }>;
     state_subscribeRuntimeVersion: import("../shared.js").Handler<[], string>;
     state_unsubscribeRuntimeVersion: import("../shared.js").Handler<[import("@polkadot/util/types").HexString], void>;
     state_subscribeStorage: import("../shared.js").Handler<[string[]], string>;

package/dist/cjs/rpc/substrate/state.d.ts

@@ -51,6 +51,24 @@ export declare const state_queryStorageAt: Handler<[
  * @return result in hash
  */
 export declare const state_call: Handler<[HexString, HexString, HexString], HexString>;
+/**
+ * @param context
+ * @param params - [`keys`, `blockhash?`]
+ *
+ * @return `{ at, proof }` — proof is a list of SCALE-encoded trie nodes.
+ *
+ * Spec-compatible response shape. The composed proof's root diverges from
+ * `chain_getHeader(at).state_root` once local overrides are applied (see `buildReadProof`);
+ * callers that need the recomputed root should use chopsticks's `dev_getReadProof`.
+ * Child-storage keys are rejected — use `state_getChildReadProof`.
+ */
+export declare const state_getReadProof: Handler<[
+    HexString[],
+    HexString | undefined
+], {
+    at: HexString;
+    proof: HexString[];
+}>;
 /**
  * @return subscription id
  */

package/dist/cjs/rpc/substrate/state.js

@@ -24,6 +24,9 @@ _export(exports, {
     get state_getMetadata () {
         return state_getMetadata;
     },
+    get state_getReadProof () {
+        return state_getReadProof;
+    },
     get state_getRuntimeVersion () {
         return state_getRuntimeVersion;
     },
@@ -52,6 +55,7 @@ _export(exports, {
 const _util = require("@polkadot/util");
 const _logger = require("../../logger.js");
 const _index = require("../../utils/index.js");
+const _readproof = require("../read-proof.js");
 const _shared = require("../shared.js");
 const logger = _logger.defaultLogger.child({
     name: 'rpc-state'
@@ -103,6 +107,13 @@ const state_call = async (context, [method, data, hash])=>{
     ]);
     return resp.result;
 };
+const state_getReadProof = async (context, [keys, hash])=>{
+    const { at, proof } = await (0, _readproof.buildReadProof)(context, keys, hash);
+    return {
+        at,
+        proof
+    };
+};
 const state_subscribeRuntimeVersion = async (context, _params, { subscribe })=>{
     let update = (_block)=>{};
     const id = await context.chain.headState.subscribeStorage([

package/dist/esm/api.d.ts

@@ -36,6 +36,11 @@ export declare class Api {
     getStorage(key: string, hash?: string): Promise<`0x${string}` | null>;
     getKeysPaged(prefix: string, pageSize: number, startKey: string, hash?: string): Promise<`0x${string}`[]>;
     getStorageBatch(prefix: HexString, keys: HexString[], hash?: HexString): any;
+    /** Upstream `state_getReadProof`. Throws if upstream doesn't expose it. */
+    getReadProof(keys: HexString[], hash?: HexString): Promise<{
+        at: HexString;
+        proof: HexString[];
+    }>;
     subscribeRemoteNewHeads(cb: ProviderInterfaceCallback): Promise<string | number>;
     subscribeRemoteFinalizedHeads(cb: ProviderInterfaceCallback): Promise<string | number>;
 }

package/dist/esm/api.js

@@ -191,6 +191,15 @@ const CACHEABLE_METHODS = new Set([
         if (hash) params.push(hash);
         return this.#provider.send('state_queryStorageAt', params, !!hash).then((result)=>result[0]?.['changes'] || []).catch(retryOnError);
     }
+    /** Upstream `state_getReadProof`. Throws if upstream doesn't expose it. */ async getReadProof(keys, hash) {
+        const params = hash ? [
+            keys,
+            hash
+        ] : [
+            keys
+        ];
+        return this.send('state_getReadProof', params, !!hash);
+    }
     async subscribeRemoteNewHeads(cb) {
         if (!this.#provider.hasSubscriptions) {
             throw new Error('subscribeRemoteNewHeads only works with subscriptions');

package/dist/esm/bridge/encode.d.ts

@@ -0,0 +1,5 @@
+import type { HexString } from '@polkadot/util/types';
+/** `ParaInfo { best_head_hash: { at_relay_block_number: u32, head_hash: H256 }, next_imported_hash_position: u32 }` */
+export declare const encodeParaInfo: (atRelayBlockNumber: number, headHash: Uint8Array, nextImportedHashPosition: number) => HexString;
+/** `ParaStoredHeaderData(Vec<u8>)` wrapping SCALE-encoded `StoredHeaderData { number: u32, state_root: H256 }`. */
+export declare const encodeParaStoredHeaderData: (blockNumber: number, stateRoot: Uint8Array) => HexString;

package/dist/esm/bridge/encode.js

@@ -0,0 +1,20 @@
+// Value encoders for `pallet_bridge_parachains` storage items. The bridge connector forges
+// these values via `dev_setStorage`, so they're SCALE-encoded by hand — runtime metadata
+// describes their types but can't construct them. Storage *keys*, by contrast, are derived
+// from metadata by the callers (`api.query[pallet].item.key(...)`), never hand-hashed.
+import { compactAddLength, nToU8a, u8aConcat, u8aToHex } from '@polkadot/util';
+const u32LE = (v)=>nToU8a(v, {
+        bitLength: 32,
+        isLe: true
+    });
+const requireBytes = (label, b, len)=>{
+    if (b.length !== len) throw new Error(`${label} must be ${len} bytes, got ${b.length}`);
+};
+/** `ParaInfo { best_head_hash: { at_relay_block_number: u32, head_hash: H256 }, next_imported_hash_position: u32 }` */ export const encodeParaInfo = (atRelayBlockNumber, headHash, nextImportedHashPosition)=>{
+    requireBytes('headHash', headHash, 32);
+    return u8aToHex(u8aConcat(u32LE(atRelayBlockNumber), headHash, u32LE(nextImportedHashPosition)));
+};
+/** `ParaStoredHeaderData(Vec<u8>)` wrapping SCALE-encoded `StoredHeaderData { number: u32, state_root: H256 }`. */ export const encodeParaStoredHeaderData = (blockNumber, stateRoot)=>{
+    requireBytes('stateRoot', stateRoot, 32);
+    return u8aToHex(compactAddLength(u8aConcat(u32LE(blockNumber), stateRoot)));
+};

package/dist/esm/bridge/index.d.ts

@@ -0,0 +1,2 @@
+export declare const bridgeLogger: import("pino").Logger<never, boolean>;
+export * from './encode.js';

package/dist/esm/bridge/index.js

@@ -0,0 +1,5 @@
+import { defaultLogger } from '../logger.js';
+export const bridgeLogger = defaultLogger.child({
+    name: 'bridge'
+});
+export * from './encode.js';

package/dist/esm/index.d.ts

@@ -37,6 +37,7 @@ export * from './blockchain/index.js';
 export * from './blockchain/inherent/index.js';
 export * from './blockchain/storage-layer.js';
 export * from './blockchain/txpool.js';
+export * from './bridge/index.js';
 export * from './chopsticks-provider.js';
 export * from './database.js';
 export * from './env.js';

package/dist/esm/index.js

@@ -14,6 +14,7 @@ export * from './blockchain/index.js';
 export * from './blockchain/inherent/index.js';
 export * from './blockchain/storage-layer.js';
 export * from './blockchain/txpool.js';
+export * from './bridge/index.js';
 export * from './chopsticks-provider.js';
 export * from './database.js';
 export * from './env.js';

package/dist/esm/rpc/dev/get-read-proof.d.ts

@@ -0,0 +1,20 @@
+import type { HexString } from '@polkadot/util/types';
+import type { Handler } from '../shared.js';
+/**
+ * @param context
+ * @param params - [`keys`, `blockhash?`]
+ *
+ * @return `{ at, proof, stateRoot }`
+ *
+ * Chopsticks-specific variant of `state_getReadProof` that also returns `stateRoot` — the
+ * root the composed proof verifies against, which verifiers must check instead of the header
+ * state root (see `buildReadProof`). Kept out of the spec method so it stays `{ at, proof }`.
+ */
+export declare const dev_getReadProof: Handler<[
+    HexString[],
+    HexString | undefined
+], {
+    at: HexString;
+    proof: HexString[];
+    stateRoot: HexString;
+}>;

package/dist/esm/rpc/dev/get-read-proof.js

@@ -0,0 +1,11 @@
+import { buildReadProof } from '../read-proof.js';
+/**
+ * @param context
+ * @param params - [`keys`, `blockhash?`]
+ *
+ * @return `{ at, proof, stateRoot }`
+ *
+ * Chopsticks-specific variant of `state_getReadProof` that also returns `stateRoot` — the
+ * root the composed proof verifies against, which verifiers must check instead of the header
+ * state root (see `buildReadProof`). Kept out of the spec method so it stays `{ at, proof }`.
+ */ export const dev_getReadProof = async (context, [keys, hash])=>buildReadProof(context, keys, hash);

package/dist/esm/rpc/dev/index.d.ts

@@ -1,4 +1,9 @@
 declare const handlers: {
+    dev_getReadProof: import("../shared.js").Handler<[`0x${string}`[], `0x${string}` | undefined], {
+        at: import("@polkadot/util/types").HexString;
+        proof: import("@polkadot/util/types").HexString[];
+        stateRoot: import("@polkadot/util/types").HexString;
+    }>;
     dev_newBlock: (context: import("../shared.js").Context, [params]: [import("./new-block.js").NewBlockParams]) => Promise<`0x${string}`>;
     dev_setBlockBuildMode: (context: import("../shared.js").Context, [mode]: [import("../../index.js").BuildBlockMode]) => Promise<void>;
     dev_setHead: (context: import("../shared.js").Context, [params]: [number | `0x${string}`]) => Promise<`0x${string}`>;
@@ -7,6 +12,7 @@ declare const handlers: {
     dev_timeTravel: (context: import("../shared.js").Context, [date]: [string | number]) => Promise<number>;
 };
 export default handlers;
+export * from './get-read-proof.js';
 export * from './new-block.js';
 export * from './set-block-build-mode.js';
 export * from './set-head.js';

package/dist/esm/rpc/dev/index.js

@@ -1,3 +1,4 @@
+import { dev_getReadProof } from './get-read-proof.js';
 import { dev_newBlock } from './new-block.js';
 import { dev_setBlockBuildMode } from './set-block-build-mode.js';
 import { dev_setHead } from './set-head.js';
@@ -5,6 +6,7 @@ import { dev_setRuntimeLogLevel } from './set-runtime-log-level.js';
 import { dev_setStorage } from './set-storage.js';
 import { dev_timeTravel } from './time-travel.js';
 const handlers = {
+    dev_getReadProof,
     dev_newBlock,
     dev_setBlockBuildMode,
     dev_setHead,
@@ -13,6 +15,7 @@ const handlers = {
     dev_timeTravel
 };
 export default handlers;
+export * from './get-read-proof.js';
 export * from './new-block.js';
 export * from './set-block-build-mode.js';
 export * from './set-head.js';

package/dist/esm/rpc/read-proof.d.ts

@@ -0,0 +1,15 @@
+import type { HexString } from '@polkadot/util/types';
+import { type Context } from './shared.js';
+/**
+ * Compose a storage read proof: chopsticks keeps no trie of its own, so it fetches a base
+ * proof from upstream (falling back to upstream head for chopsticks-only blocks) and
+ * re-applies chopsticks-side values via `createProof`. Returns the proof nodes and the
+ * recomputed trie root — which diverges from `chain_getHeader(at).state_root` once local
+ * overrides are applied. Shared by `state_getReadProof` (drops the root, spec shape) and
+ * `dev_getReadProof` (keeps it). Child-storage keys are rejected.
+ */
+export declare const buildReadProof: (context: Context, keys: HexString[], hash: HexString | undefined) => Promise<{
+    at: HexString;
+    proof: HexString[];
+    stateRoot: HexString;
+}>;

package/dist/esm/rpc/read-proof.js

@@ -0,0 +1,59 @@
+import { defaultLogger } from '../logger.js';
+import { isPrefixedChildKey } from '../utils/index.js';
+import { createProof } from '../wasm-executor/index.js';
+import { ResponseError } from './shared.js';
+const logger = defaultLogger.child({
+    name: 'rpc-read-proof'
+});
+/**
+ * Compose a storage read proof: chopsticks keeps no trie of its own, so it fetches a base
+ * proof from upstream (falling back to upstream head for chopsticks-only blocks) and
+ * re-applies chopsticks-side values via `createProof`. Returns the proof nodes and the
+ * recomputed trie root — which diverges from `chain_getHeader(at).state_root` once local
+ * overrides are applied. Shared by `state_getReadProof` (drops the root, spec shape) and
+ * `dev_getReadProof` (keeps it). Child-storage keys are rejected.
+ */ export const buildReadProof = async (context, keys, hash)=>{
+    if (keys.length === 0) {
+        throw new ResponseError(-32602, 'getReadProof requires a non-empty array of keys');
+    }
+    for (const key of keys){
+        if (isPrefixedChildKey(key)) {
+            throw new ResponseError(-32601, `getReadProof does not support child-storage keys (got ${key}); use state_getChildReadProof`);
+        }
+    }
+    const block = await context.chain.getBlock(hash);
+    if (!block) {
+        throw new ResponseError(1, `Block ${hash ?? 'head'} not found`);
+    }
+    // Upstream rejects chopsticks-only blocks with UnknownBlock; fall back to upstream
+    // head whose trie is guaranteed available.
+    const fetchUpstreamProof = async ()=>{
+        try {
+            return await context.chain.api.getReadProof(keys, block.hash);
+        } catch (err) {
+            logger.debug({
+                err: err.message,
+                blockHash: block.hash
+            }, 'getReadProof at block failed; retrying at head');
+            try {
+                return await context.chain.api.getReadProof(keys);
+            } catch (err2) {
+                throw new ResponseError(-32603, `getReadProof: upstream rejected at block ${block.hash} and at head (${err2.message})`);
+            }
+        }
+    };
+    // The local reads and the upstream proof are independent — overlap their round trips.
+    const [updates, upstreamProof] = await Promise.all([
+        Promise.all(keys.map(async (key)=>[
+                key,
+                await block.get(key) ?? null
+            ])),
+        fetchUpstreamProof()
+    ]);
+    const { trieRootHash, nodes } = await createProof(upstreamProof.proof, updates);
+    return {
+        at: block.hash,
+        proof: nodes,
+        stateRoot: trieRootHash
+    };
+};

package/dist/esm/rpc/substrate/index.d.ts

@@ -35,6 +35,10 @@ declare const handlers: {
         changes: [string, string | null][];
     }]>;
     state_call: import("../shared.js").Handler<[import("@polkadot/util/types").HexString, import("@polkadot/util/types").HexString, import("@polkadot/util/types").HexString], import("@polkadot/util/types").HexString>;
+    state_getReadProof: import("../shared.js").Handler<[import("@polkadot/util/types").HexString[], import("@polkadot/util/types").HexString | undefined], {
+        at: import("@polkadot/util/types").HexString;
+        proof: import("@polkadot/util/types").HexString[];
+    }>;
     state_subscribeRuntimeVersion: import("../shared.js").Handler<[], string>;
     state_unsubscribeRuntimeVersion: import("../shared.js").Handler<[import("@polkadot/util/types").HexString], void>;
     state_subscribeStorage: import("../shared.js").Handler<[string[]], string>;

package/dist/esm/rpc/substrate/state.d.ts

@@ -51,6 +51,24 @@ export declare const state_queryStorageAt: Handler<[
  * @return result in hash
  */
 export declare const state_call: Handler<[HexString, HexString, HexString], HexString>;
+/**
+ * @param context
+ * @param params - [`keys`, `blockhash?`]
+ *
+ * @return `{ at, proof }` — proof is a list of SCALE-encoded trie nodes.
+ *
+ * Spec-compatible response shape. The composed proof's root diverges from
+ * `chain_getHeader(at).state_root` once local overrides are applied (see `buildReadProof`);
+ * callers that need the recomputed root should use chopsticks's `dev_getReadProof`.
+ * Child-storage keys are rejected — use `state_getChildReadProof`.
+ */
+export declare const state_getReadProof: Handler<[
+    HexString[],
+    HexString | undefined
+], {
+    at: HexString;
+    proof: HexString[];
+}>;
 /**
  * @return subscription id
  */

package/dist/esm/rpc/substrate/state.js

@@ -1,6 +1,7 @@
 import { stringToHex } from '@polkadot/util';
 import { defaultLogger } from '../../logger.js';
 import { isPrefixedChildKey, prefixedChildKey, stripChildPrefix } from '../../utils/index.js';
+import { buildReadProof } from '../read-proof.js';
 import { ResponseError } from '../shared.js';
 const logger = defaultLogger.child({
     name: 'rpc-state'
@@ -82,6 +83,23 @@ const logger = defaultLogger.child({
     ]);
     return resp.result;
 };
+/**
+ * @param context
+ * @param params - [`keys`, `blockhash?`]
+ *
+ * @return `{ at, proof }` — proof is a list of SCALE-encoded trie nodes.
+ *
+ * Spec-compatible response shape. The composed proof's root diverges from
+ * `chain_getHeader(at).state_root` once local overrides are applied (see `buildReadProof`);
+ * callers that need the recomputed root should use chopsticks's `dev_getReadProof`.
+ * Child-storage keys are rejected — use `state_getChildReadProof`.
+ */ export const state_getReadProof = async (context, [keys, hash])=>{
+    const { at, proof } = await buildReadProof(context, keys, hash);
+    return {
+        at,
+        proof
+    };
+};
 /**
  * @return subscription id
  */ export const state_subscribeRuntimeVersion = async (context, _params, { subscribe })=>{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acala-network/chopsticks-core",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "author": "Acala Developers <hello@acala.network>",
   "license": "Apache-2.0",
   "type": "module",
@@ -14,7 +14,7 @@
     "depcheck": "npx depcheck"
   },
   "dependencies": {
-    "@acala-network/chopsticks-executor": "1.4.2",
+    "@acala-network/chopsticks-executor": "1.5.0",
     "@polkadot/rpc-provider": "^16.4.1",
     "@polkadot/types": "^16.4.1",
     "@polkadot/types-codec": "^16.4.1",