@dedot/api 0.18.8 → 1.0.0

package/cjs/client/explorer/LegacyBlockExplorer.js

@@ -0,0 +1,263 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LegacyBlockExplorer = void 0;
+const codecs_1 = require("@dedot/codecs");
+const utils_1 = require("@dedot/utils");
+/**
+ * @name LegacyBlockExplorer
+ * @description Block explorer implementation for LegacyClient using legacy JSON-RPC methods
+ * Optimized to share RPC subscriptions across multiple subscribers using Signal pattern
+ */
+class LegacyBlockExplorer {
+    #client;
+    // Signals for block subscriptions
+    #bestBlockSignal;
+    #finalizedBlockSignal;
+    // Track RPC subscription cleanup functions
+    #bestBlockUnsub;
+    #finalizedBlockUnsub;
+    constructor(client) {
+        this.#client = client;
+        this.#bestBlockSignal = new utils_1.Signal();
+        this.#finalizedBlockSignal = new utils_1.Signal();
+    }
+    /**
+     * Convert PinnedBlock to BlockInfo format
+     */
+    toBlockInfo(header) {
+        return {
+            hash: header.hash || this.calculateBlockHash(header),
+            number: header.number,
+            parent: header.parentHash,
+            runtimeUpgraded: this.hasNewRuntime(header),
+        };
+    }
+    /**
+     * Fill missing blocks when a gap is detected
+     * Fetches and emits all missing blocks between lastNumber and currentNumber
+     */
+    async fillMissingBlocks(lastNumber, currentNumber, subject, blockType) {
+        // No gap if no previous block or current is next sequential block
+        if (lastNumber === undefined || currentNumber <= lastNumber + 1) {
+            return;
+        }
+        // Gap detected - backfill missing blocks
+        const gapSize = currentNumber - lastNumber - 1;
+        // Create list of missing block numbers
+        const missingNums = Array.from({ length: gapSize }, (_, i) => lastNumber + 1 + i);
+        try {
+            // Fetch all hashes in parallel
+            const hashes = await Promise.all(missingNums.map((num) => this.#client.rpc.chain_getBlockHash(num)));
+            // Fetch all headers in parallel
+            const headers = await Promise.all(hashes.map((hash) => this.#client.rpc.chain_getHeader(hash)));
+            // Emit blocks in order
+            for (let i = 0; i < missingNums.length; i++) {
+                const hash = hashes[i];
+                const header = headers[i];
+                if (hash && header) {
+                    subject.next(this.toBlockInfo({ ...header, hash }));
+                }
+            }
+        }
+        catch (error) {
+            console.error(`Failed to backfill missing ${blockType} blocks:`, error);
+            // Continue despite backfill failure
+        }
+    }
+    /**
+     * Start the shared best block subscription if not already active
+     */
+    ensureBestBlockSubscription() {
+        if (this.#bestBlockUnsub) {
+            // Subscription already active
+            return;
+        }
+        // Use closure pattern to handle async subscription without race conditions
+        let done = false;
+        let unsub;
+        const blockQueue = new utils_1.AsyncQueue();
+        // Start RPC subscription (non-blocking)
+        this.#client.rpc
+            .chain_subscribeNewHeads((header) => {
+            if (done) {
+                // Unsubscribe was called before subscription completed
+                unsub && unsub();
+                return;
+            }
+            // Enqueue block processing to ensure sequential handling
+            blockQueue
+                .enqueue(async () => {
+                const currentHash = this.calculateBlockHash(header);
+                // Detect gaps in best block stream (due to reconnection)
+                const { number: lastNumber, hash: lastHash } = this.#bestBlockSignal.value || {};
+                if (lastHash === currentHash) {
+                    return;
+                }
+                // Fill missing blocks if gap detected
+                await this.fillMissingBlocks(lastNumber, header.number, this.#bestBlockSignal, 'best');
+                // Emit current block
+                const blockInfo = this.toBlockInfo({ ...header, hash: currentHash });
+                this.#bestBlockSignal.next(blockInfo);
+            })
+                .catch((error) => {
+                console.error('Error processing best block:', error);
+            });
+        })
+            .then((rpcUnsub) => {
+            unsub = rpcUnsub;
+        });
+        // Immediately set unsub wrapper to prevent race conditions
+        this.#bestBlockUnsub = () => {
+            done = true;
+            blockQueue.cancel();
+            unsub && unsub().catch(utils_1.noop);
+        };
+    }
+    hasNewRuntime(header) {
+        return header.digest.logs.some((log) => log.type === 'RuntimeEnvironmentUpdated');
+    }
+    /**
+     * Start the shared finalized block subscription if not already active
+     */
+    ensureFinalizedBlockSubscription() {
+        if (this.#finalizedBlockUnsub) {
+            // Subscription already active
+            return;
+        }
+        // Use closure pattern to handle async subscription without race conditions
+        let done = false;
+        let unsub;
+        const blockQueue = new utils_1.AsyncQueue();
+        // Start RPC subscription (non-blocking)
+        this.#client.rpc
+            .chain_subscribeFinalizedHeads((header) => {
+            if (done) {
+                // Unsubscribe was called before subscription completed
+                unsub && unsub();
+                return;
+            }
+            // Enqueue block processing to ensure sequential handling
+            blockQueue
+                .enqueue(async () => {
+                // Detect gaps in finalized block stream (due to reconnection)
+                const lastNumber = this.#finalizedBlockSignal.value?.number;
+                if (lastNumber === header.number) {
+                    return;
+                }
+                // Fill missing blocks if gap detected
+                await this.fillMissingBlocks(lastNumber, header.number, this.#finalizedBlockSignal, 'finalized');
+                // Emit current block
+                const blockInfo = this.toBlockInfo(header);
+                this.#finalizedBlockSignal.next(blockInfo);
+            })
+                .catch((error) => {
+                console.error('Error processing finalized block:', error);
+            });
+        })
+            .then((rpcUnsub) => {
+            unsub = rpcUnsub;
+        });
+        // Immediately set unsub wrapper to prevent race conditions
+        this.#finalizedBlockUnsub = () => {
+            done = true;
+            blockQueue.cancel();
+            unsub && unsub().catch(utils_1.noop);
+        };
+    }
+    /**
+     * Clean up best block subscription when no more listeners
+     */
+    cleanupBestBlockSubscription() {
+        if (this.#bestBlockSignal.listenerCount === 0 && this.#bestBlockUnsub) {
+            this.#bestBlockUnsub();
+            this.#bestBlockUnsub = undefined;
+        }
+    }
+    /**
+     * Clean up finalized block subscription when no more listeners
+     */
+    cleanupFinalizedBlockSubscription() {
+        if (this.#finalizedBlockSignal.listenerCount === 0 && this.#finalizedBlockUnsub) {
+            this.#finalizedBlockUnsub();
+            this.#finalizedBlockUnsub = undefined;
+        }
+    }
+    calculateBlockHash(header) {
+        return this.#client.registry.hashAsHex(codecs_1.$Header.tryEncode(header));
+    }
+    best(callback) {
+        if (callback) {
+            // Subscribe mode - use shared subscription
+            // Ensure RPC subscription is active (creates on first listener)
+            this.ensureBestBlockSubscription();
+            // Subscribe to subject (automatically emits current value if available)
+            const unsub = this.#bestBlockSignal.subscribe(callback);
+            // Return cleanup function
+            return () => {
+                unsub();
+                this.cleanupBestBlockSubscription();
+            };
+        }
+        else {
+            // One-time query - return cached value if available
+            if (this.#bestBlockSignal.value) {
+                return Promise.resolve(this.#bestBlockSignal.value);
+            }
+            // Fallback to RPC call if no cached value
+            return this.#client.rpc.chain_getHeader().then(async (header) => {
+                (0, utils_1.assert)(header, 'Header not found');
+                return {
+                    hash: this.calculateBlockHash(header),
+                    number: header.number,
+                    parent: header.parentHash,
+                };
+            });
+        }
+    }
+    finalized(callback) {
+        if (callback) {
+            // Subscribe mode - use shared subscription
+            // Ensure RPC subscription is active (creates on first listener)
+            this.ensureFinalizedBlockSubscription();
+            // Subscribe to subject (automatically emits current value if available)
+            const unsub = this.#finalizedBlockSignal.subscribe(callback);
+            // Return cleanup function
+            return () => {
+                unsub();
+                this.cleanupFinalizedBlockSubscription();
+            };
+        }
+        else {
+            // One-time query - return cached value if available
+            if (this.#finalizedBlockSignal.value) {
+                return Promise.resolve(this.#finalizedBlockSignal.value);
+            }
+            // Fallback to RPC call if no cached value
+            return this.#client.rpc.chain_getFinalizedHead().then(async (hash) => {
+                const header = await this.header(hash);
+                return {
+                    hash,
+                    number: header.number,
+                    parent: header.parentHash,
+                };
+            });
+        }
+    }
+    /**
+     * Get the header of a block by number or hash
+     */
+    async header(hash) {
+        const header = await this.#client.rpc.chain_getHeader(hash);
+        (0, utils_1.assert)(header, `Header not found for block ${hash}`);
+        return header;
+    }
+    /**
+     * Get the body (transactions) of a block by number or hash
+     */
+    async body(hash) {
+        const block = await this.#client.rpc.chain_getBlock(hash);
+        (0, utils_1.assert)(block, `Block not found for ${hash}`);
+        return block.block.extrinsics;
+    }
+}
+exports.LegacyBlockExplorer = LegacyBlockExplorer;

package/cjs/client/explorer/V2BlockExplorer.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.V2BlockExplorer = void 0;
+const codecs_1 = require("@dedot/codecs");
+const utils_1 = require("@dedot/utils");
+/**
+ * @name V2BlockExplorer
+ * @description Block explorer implementation for V2Client using JSON-RPC v2 (ChainHead API)
+ */
+class V2BlockExplorer {
+    #chainHead;
+    #archive;
+    constructor(client) {
+        this.#chainHead = client.chainHead;
+        this.#archive = client.archive;
+    }
+    /**
+     * Convert PinnedBlock to BlockInfo format
+     */
+    toBlockInfo(block) {
+        return {
+            hash: block.hash,
+            number: block.number,
+            parent: block.parent,
+            runtimeUpgraded: block.runtimeUpgraded === true,
+        };
+    }
+    best(callback) {
+        if (callback) {
+            // Subscribe mode
+            const handler = (block) => {
+                callback(this.toBlockInfo(block));
+            };
+            this.#chainHead.bestBlock().then((block) => {
+                handler(block);
+            });
+            return this.#chainHead.on('bestBlock', handler);
+        }
+        else {
+            // One-time query
+            return this.#chainHead.bestBlock().then((block) => this.toBlockInfo(block));
+        }
+    }
+    finalized(callback) {
+        if (callback) {
+            // Subscribe mode
+            const handler = (block) => {
+                callback(this.toBlockInfo(block));
+            };
+            this.#chainHead.finalizedBlock().then((block) => {
+                handler(block);
+            });
+            return this.#chainHead.on('finalizedBlock', handler);
+        }
+        else {
+            return this.#chainHead.finalizedBlock().then((block) => this.toBlockInfo(block));
+        }
+    }
+    /**
+     * Get the header of a block by number or hash
+     */
+    async header(hash) {
+        const rawHeader = await this.#chainHead.header(hash);
+        (0, utils_1.assert)(rawHeader, `Header not found for block ${hash}`);
+        return codecs_1.$Header.tryDecode(rawHeader);
+    }
+    /**
+     * Get the body (transactions) of a block by number or hash
+     */
+    async body(hash) {
+        return await this.#chainHead.body(hash);
+    }
+}
+exports.V2BlockExplorer = V2BlockExplorer;

package/cjs/client/explorer/index.js

@@ -0,0 +1,18 @@
+"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 __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 });
+__exportStar(require("./V2BlockExplorer.js"), exports);
+__exportStar(require("./LegacyBlockExplorer.js"), exports);

package/cjs/client/utils.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectHasherFromHeader = exports.detectHasherFromMetadata = void 0;
+const codecs_1 = require("@dedot/codecs");
+const utils_1 = require("@dedot/utils");
+const HASHERS = {
+    BlakeTwo256: utils_1.blake2_256, // commonly used in polkadot-sdk based-chains
+    Keccak256: utils_1.keccak_256, // widely used in EVM-compatible chains, e.g: Hyperbridge
+};
+/**
+ * Detects the hasher from V16 metadata by looking at the System pallet's Hashing associated type
+ *
+ * @param metadata - The metadata to inspect
+ * @returns The detected HashFn or undefined if detection fails
+ */
+function detectHasherFromMetadata(metadata) {
+    try {
+        const latest = metadata.latest;
+        // Find the System pallet
+        const systemPallet = latest.pallets.find((p) => p.name === 'System');
+        if (!systemPallet)
+            return undefined;
+        // Find the Hashing associated type
+        const hashingType = systemPallet.associatedTypes.find((t) => t.name === 'Hashing');
+        if (!hashingType)
+            return undefined;
+        // Get the type definition
+        const typeDef = latest.types[hashingType.typeId];
+        if (!typeDef)
+            return undefined;
+        // Get the hasher name from the type path (last element)
+        const hasherName = typeDef.path.at(-1);
+        if (!hasherName)
+            return undefined;
+        return HASHERS[hasherName];
+    }
+    catch { }
+    return undefined;
+}
+exports.detectHasherFromMetadata = detectHasherFromMetadata;
+/**
+ * Detects the hasher by trying different hash functions on a block header
+ * and comparing the result with the expected block hash
+ *
+ * @param header - The block header to hash
+ * @param expectedHash - The expected block hash
+ * @returns The matching HashFn or undefined if no match is found
+ */
+function detectHasherFromHeader(header, expectedHash) {
+    try {
+        const encodedHeader = codecs_1.$Header.tryEncode(header);
+        return Object.values(HASHERS).find((h) => (0, utils_1.u8aToHex)(h(encodedHeader)) === expectedHash);
+    }
+    catch { }
+    return undefined;
+}
+exports.detectHasherFromHeader = detectHasherFromHeader;

package/cjs/executor/EventExecutor.js

@@ -59,6 +59,7 @@ class EventExecutor extends Executor_js_1.Executor {
             palletIndex: targetPallet.index,
         };
         return {
+            // @ts-ignore
             is,
             find,
             filter,

package/cjs/executor/RuntimeApiExecutor.js

@@ -1,9 +1,34 @@
 "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;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RuntimeApiExecutor = exports.FallbackRuntimeApiSpecs = exports.FallbackRuntimeApis = void 0;
 const runtime_specs_1 = require("@dedot/runtime-specs");
+const $ = __importStar(require("@dedot/shape"));
 const utils_1 = require("@dedot/utils");
 const Executor_js_1 = require("./Executor.js");
+const validation_helpers_js_1 = require("./validation-helpers.js");
 exports.FallbackRuntimeApis = { '0x37e397fc7c91f5e4': 2 };
 exports.FallbackRuntimeApiSpecs = { Metadata: runtime_specs_1.Metadata };
 /**
@@ -22,8 +47,30 @@ class RuntimeApiExecutor extends Executor_js_1.Executor {
         (0, utils_1.assert)(callSpec, new utils_1.UnknownApiError(`Runtime api spec not found for ${callName}`));
         const callFn = async (...args) => {
             const { params } = callSpec;
-            const formattedInputs = params.map((param, index) => this.tryEncode(param, args[index]));
-            const bytes = (0, utils_1.u8aToHex)((0, utils_1.concatU8a)(...formattedInputs));
+            // Pad args with undefined for missing trailing optional parameters
+            const withCodecs = params.every((p) => !!p.codec);
+            const paddedArgs = (0, validation_helpers_js_1.padArgsForOptionalParams)(args, params, withCodecs
+                ? {} // intentional trick to pass-by client initialization
+                : this.registry);
+            const $ParamsTuple = $.Tuple(...params.map((param) => this.#findCodec(param, // --
+            `Codec not found for param ${param.name}`)));
+            // Enhanced validation with detailed error messages
+            try {
+                $ParamsTuple.assert?.(paddedArgs);
+            }
+            catch (error) {
+                // Enhance Shape assertion errors with detailed compatibility information
+                if (error instanceof $.ShapeAssertError) {
+                    throw (0, validation_helpers_js_1.buildCompatibilityError)(error, // --
+                    params, args, {
+                        apiName: `${runtimeApi}.${method}`,
+                        registry: this.registry,
+                    });
+                }
+                throw error;
+            }
+            const formattedInputs = $ParamsTuple.tryEncode(paddedArgs);
+            const bytes = (0, utils_1.u8aToHex)(formattedInputs);
             const callParams = {
                 func: callName,
                 params: bytes,

package/cjs/executor/StorageQueryExecutor.js

@@ -1,9 +1,34 @@
 "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;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StorageQueryExecutor = void 0;
+const $ = __importStar(require("@dedot/shape"));
 const utils_1 = require("@dedot/utils");
 const index_js_1 = require("../storage/index.js");
 const Executor_js_1 = require("./Executor.js");
+const validation_helpers_js_1 = require("./validation-helpers.js");
 const DEFAULT_KEYS_PAGE_SIZE = 1000;
 const DEFAULT_ENTRIES_PAGE_SIZE = 250;
 /**
@@ -32,6 +57,8 @@ class StorageQueryExecutor extends Executor_js_1.Executor {
         };
         const queryFn = async (...args) => {
             const [inArgs, callback] = extractArgs(args);
+            // Validate storage inputs before encoding
+            this.#validateStorageInputs(entry, inArgs.at(0));
             const encodedKey = entry.encodeKey(inArgs.at(0));
             // if a callback is passed, make a storage subscription and return an unsub function
             if (callback) {
@@ -58,6 +85,10 @@ class StorageQueryExecutor extends Executor_js_1.Executor {
                 const [inArgs, callback] = extractArgs(args);
                 const multiArgs = inArgs.at(0);
                 (0, utils_1.assert)(Array.isArray(multiArgs), 'First param for multi query should be an array');
+                // Validate each argument before encoding
+                multiArgs.forEach((arg, index) => {
+                    this.#validateStorageInputs(entry, arg, index);
+                });
                 const encodedKeys = multiArgs.map((arg) => entry.encodeKey(arg));
                 // if a callback is passed, make a storage subscription and return an unsub function
                 if (callback) {
@@ -79,7 +110,7 @@ class StorageQueryExecutor extends Executor_js_1.Executor {
     exposeStorageMapMethods(entry) {
         const rawKeys = async (partialInput, pagination) => {
             const pageSize = pagination?.pageSize || DEFAULT_KEYS_PAGE_SIZE;
-            const startKey = pagination?.startKey || entry.prefixKey;
+            const startKey = pagination?.startKey;
             return await this.client.rpc.state_getKeysPaged(entry.encodeKey(partialInput, true), pageSize, startKey, this.atBlockHash);
         };
         const extractArgs = (args) => {
@@ -99,7 +130,88 @@ class StorageQueryExecutor extends Executor_js_1.Executor {
             const storageMap = await this.queryStorage(storageKeys, this.atBlockHash);
             return storageKeys.map((key) => [entry.decodeKey(key), entry.decodeValue(storageMap[key])]);
         };
-        return { pagedKeys, pagedEntries };
+        const entries = async (...args) => {
+            const [inArgs] = extractArgs(args);
+            const allEntries = [];
+            let startKey;
+            while (true) {
+                const pagination = {
+                    pageSize: DEFAULT_ENTRIES_PAGE_SIZE,
+                    ...(startKey ? { startKey } : {}),
+                };
+                const storageKeys = await rawKeys(inArgs, pagination);
+                if (storageKeys.length === 0)
+                    break;
+                const storageMap = await this.queryStorage(storageKeys, this.atBlockHash);
+                const pageEntries = storageKeys.map((key) => [
+                    entry.decodeKey(key),
+                    entry.decodeValue(storageMap[key]),
+                ]);
+                allEntries.push(...pageEntries);
+                if (storageKeys.length < DEFAULT_ENTRIES_PAGE_SIZE)
+                    break;
+                startKey = storageKeys[storageKeys.length - 1];
+            }
+            return allEntries;
+        };
+        return { entries, pagedKeys, pagedEntries };
+    }
+    /**
+     * Validate storage query inputs before encoding
+     * @param entry - QueryableStorage instance
+     * @param keyInput - Input keys to validate
+     * @param itemIndex - Optional index for multi query error messages
+     */
+    #validateStorageInputs(entry, keyInput, itemIndex) {
+        const { storageType } = entry.storageEntry;
+        // Plain storage doesn't require validation
+        if (storageType.type === 'Plain') {
+            return;
+        }
+        if (storageType.type === 'Map') {
+            const { hashers, keyTypeId } = storageType.value;
+            const requiredKeys = hashers.length;
+            // Extract keyTypeIds for multi-key storage
+            let keyTypeIds = [keyTypeId];
+            if (hashers.length > 1) {
+                const { typeDef } = this.registry.findType(keyTypeId);
+                (0, utils_1.assert)(typeDef.type === 'Tuple', 'Key type should be a tuple!');
+                keyTypeIds = typeDef.value.fields;
+            }
+            // Normalize input to array format
+            let keys;
+            if (requiredKeys === 1) {
+                // Single key: accept both single value or array
+                keys = Array.isArray(keyInput) ? keyInput : [keyInput];
+            }
+            else {
+                // Multiple keys: must be array
+                (0, utils_1.assert)(Array.isArray(keyInput), 'Multi-key storage requires array input');
+                keys = keyInput;
+            }
+            // Build parameter specs for error messages
+            const paramSpecs = keyTypeIds.map((typeId, index) => ({
+                name: `key${index}`,
+                typeId,
+            }));
+            // Create tuple codec for validation
+            const $ParamsTuple = $.Tuple(...keyTypeIds.map((id) => this.registry.findCodec(id)));
+            // Validate inputs
+            try {
+                $ParamsTuple.assert?.(keys);
+            }
+            catch (error) {
+                if (error instanceof $.ShapeAssertError) {
+                    throw (0, validation_helpers_js_1.buildCompatibilityError)(error, // -
+                    paramSpecs, keys, {
+                        apiName: `${(0, utils_1.stringCamelCase)(entry.pallet.name)}.${(0, utils_1.stringCamelCase)(entry.storageEntry.name)}`,
+                        registry: this.registry,
+                        itemIndex,
+                    });
+                }
+                throw error;
+            }
+        }
     }
     getStorageQuery() {
         return new index_js_1.LegacyStorageQuery(this.client);

package/cjs/executor/ViewFunctionExecutor.js

@@ -27,6 +27,7 @@ exports.ViewFunctionExecutor = void 0;
 const $ = __importStar(require("@dedot/shape"));
 const utils_1 = require("@dedot/utils");
 const Executor_js_1 = require("./Executor.js");
+const validation_helpers_js_1 = require("./validation-helpers.js");
 const RUNTIME_API_NAME = 'RuntimeViewFunction';
 const METHOD_NAME = 'execute_view_function';
 /**
@@ -40,8 +41,26 @@ class ViewFunctionExecutor extends Executor_js_1.Executor {
         (0, utils_1.assert)(viewFunctionDef, new utils_1.UnknownApiError(`View function not found: ${pallet}.${viewFunction}`));
         const callFn = async (...args) => {
             const { inputs, id, output } = viewFunctionDef;
-            const formattedInputs = inputs.map(({ typeId }, index) => this.registry.findCodec(typeId).tryEncode(args[index]));
-            const bytes = (0, utils_1.u8aToHex)((0, utils_1.concatU8a)(id, $.Vec($.u8).tryEncode((0, utils_1.concatU8a)(...formattedInputs))));
+            // Pad args with undefined for missing trailing optional parameters
+            const paddedArgs = (0, validation_helpers_js_1.padArgsForOptionalParams)(args, inputs, this.registry);
+            const $ParamsTuple = $.Tuple(...inputs.map((param) => this.registry.findCodec(param.typeId)));
+            // Enhanced validation with detailed error messages
+            try {
+                $ParamsTuple.assert?.(paddedArgs);
+            }
+            catch (error) {
+                // Enhance Shape assertion errors with detailed compatibility information
+                if (error instanceof $.ShapeAssertError) {
+                    throw (0, validation_helpers_js_1.buildCompatibilityError)(error, // --
+                    inputs, args, {
+                        apiName: `${pallet}.${viewFunction}`,
+                        registry: this.registry,
+                    });
+                }
+                throw error;
+            }
+            const formattedInputs = $ParamsTuple.tryEncode(paddedArgs);
+            const bytes = (0, utils_1.u8aToHex)((0, utils_1.concatU8a)(id, $.Vec($.u8).tryEncode(formattedInputs)));
             const func = `${RUNTIME_API_NAME}_${METHOD_NAME}`;
             const callParams = {
                 func,