@dedot/api 0.18.8 → 1.0.0

package/executor/validation-helpers.js

@@ -0,0 +1,174 @@
+import { ApiCompatibilityError, isNumber } from '@dedot/utils';
+/**
+ * Check if a codec is an Option type
+ */
+export function isOptionCodec(codec) {
+    try {
+        const metadata = codec?.metadata?.[0];
+        return metadata?.name === '$.option';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a parameter is optional (wrapped in Option)
+ */
+export function isOptionalParam(param, registry) {
+    // Check direct codec first
+    if (param.codec) {
+        return isOptionCodec(param.codec);
+    }
+    // Check via typeId using registry
+    if (isNumber(param.typeId)) {
+        try {
+            const type = registry.findType(param.typeId);
+            return type.typeDef.type === 'Enum' && type.path.join('::') === 'Option';
+        }
+        catch {
+            // ignore
+        }
+    }
+    return false;
+}
+/**
+ * Pad args array with undefined for missing trailing optional parameters.
+ * This allows users to omit optional parameters at the end of the parameter list.
+ */
+export function padArgsForOptionalParams(args, params, registry) {
+    // If args already match params length, no padding needed
+    if (args.length === params.length) {
+        return args;
+    }
+    // If more args than params, validation will fail later
+    if (args.length > params.length) {
+        return args;
+    }
+    // Check that all missing parameters are optional
+    for (let i = args.length; i < params.length; i++) {
+        const param = params[i];
+        if (!isOptionalParam(param, registry)) {
+            // Required parameter is missing, let the validation fail naturally
+            return args;
+        }
+    }
+    // All missing parameters are optional, pad with undefined
+    return [...args, ...Array(params.length - args.length).fill(undefined)];
+}
+/**
+ * Format a value for display in error messages
+ * Stringifies and truncates to 20 characters max
+ */
+function formatValue(value) {
+    try {
+        let str;
+        if (typeof value === 'string') {
+            str = JSON.stringify(value);
+        }
+        else if (typeof value === 'undefined') {
+            str = 'undefined';
+        }
+        else if (value === null) {
+            str = 'null';
+        }
+        else if (typeof value === 'bigint') {
+            str = `${value}n`;
+        }
+        else if (typeof value === 'object') {
+            // For objects/arrays, use JSON.stringify
+            str = JSON.stringify(value);
+        }
+        else {
+            str = String(value);
+        }
+        // Truncate to 20 characters
+        if (str.length > 20) {
+            return str.slice(0, 20) + '...';
+        }
+        return str;
+    }
+    catch {
+        return '[complex value]';
+    }
+}
+/**
+ * Build a comprehensive API compatibility error with detailed information
+ */
+export function buildCompatibilityError(originalError, params, args, context) {
+    const lines = [];
+    // Header
+    if (context.itemIndex !== undefined) {
+        lines.push(`API Compatibility Error: ${context.apiName} (item ${context.itemIndex})`);
+    }
+    else {
+        lines.push(`API Compatibility Error: ${context.apiName}`);
+    }
+    lines.push('');
+    // Check parameter count mismatch
+    if (args.length !== params.length) {
+        lines.push(`Expected ${params.length} parameter${params.length !== 1 ? 's' : ''} but received ${args.length}`);
+        lines.push('');
+    }
+    // Validate each parameter and report errors
+    const paramErrors = [];
+    const maxParams = Math.max(args.length, params.length);
+    for (let i = 0; i < maxParams; i++) {
+        const param = params[i];
+        const value = args[i];
+        if (!param) {
+            // Extra argument provided
+            paramErrors.push(`  [${i}] (unexpected) - value: ${formatValue(value)}`);
+            continue;
+        }
+        if (value === undefined && i >= args.length) {
+            // Missing argument - check if it's actually optional
+            const isOptional = isOptionalParam(param, context.registry);
+            if (isOptional) {
+                paramErrors.push(`  [${i}] ${param.name}: omitted (optional)`);
+            }
+            else {
+                paramErrors.push(`  [${i}] ${param.name}: ✗ required parameter missing - value: undefined`);
+            }
+            continue;
+        }
+        // Try to validate the parameter
+        try {
+            const $codec = findCodec(param, context.registry);
+            if ($codec) {
+                $codec.assert?.(value);
+                // Valid parameter
+                paramErrors.push(`  [${i}] ${param.name}: ✓ valid`);
+            }
+        }
+        catch (error) {
+            // Invalid parameter
+            paramErrors.push(`  [${i}] ${param.name}: ✗ invalid input type - value: ${formatValue(value)}`);
+        }
+    }
+    if (paramErrors.length > 0) {
+        lines.push('Parameters:');
+        lines.push(...paramErrors);
+        lines.push('');
+    }
+    // Add suggestion
+    lines.push('This may indicate your chaintypes definitions are outdated.');
+    lines.push('Consider regenerating chaintypes with:');
+    lines.push('  npx dedot chaintypes -w <your-chain-endpoint>');
+    return new ApiCompatibilityError(lines.join('\n'));
+}
+/**
+ * Find codec for a parameter (internal helper)
+ */
+function findCodec(param, registry) {
+    if (param.codec)
+        return param.codec;
+    if (isNumber(param.typeId)) {
+        try {
+            return registry.findCodec(param.typeId);
+        }
+        catch {
+            // ignore
+        }
+    }
+    return undefined;
+}

package/extrinsic/extensions/SignedExtension.d.ts

@@ -35,7 +35,7 @@ export declare abstract class SignedExtension<Data extends any = {}, AdditionalS
         typeId: number;
         additionalSigned: number;
     };
-    get payloadOptions(): Partial<PayloadOptions>;
+    get payloadOptions(): Partial<PayloadOptions<any>>;
     toPayload(...args: any[]): Partial<SignerPayloadJSON>;
 }
 export {};

package/extrinsic/submittable/BaseSubmittableExtrinsic.d.ts

@@ -1,4 +1,4 @@
-import { BlockHash, Extrinsic } from '@dedot/codecs';
+import { BlockHash, Extrinsic, Preamble } from '@dedot/codecs';
 import { AddressOrPair, Callback, IRuntimeTxCall, ISubmittableExtrinsic, ISubmittableResult, PayloadOptions, SignerOptions, TxHash, TxPaymentInfo, TxUnsub } from '@dedot/types';
 import { HexString } from '@dedot/utils';
 import type { FrameSystemEventRecord } from '../../chaintypes/index.js';
@@ -9,8 +9,8 @@ interface TxHooks {
 }
 export declare abstract class BaseSubmittableExtrinsic extends Extrinsic implements ISubmittableExtrinsic {
     #private;
-    readonly client: ISubstrateClient<any>;
-    constructor(client: ISubstrateClient<any>, call: IRuntimeTxCall);
+    readonly client: ISubstrateClient<any, any>;
+    constructor(client: ISubstrateClient<any, any>, call: IRuntimeTxCall, preamble?: Preamble);
     withHooks(hooks: TxHooks): void;
     protected transformTxResult<R extends ISubmittableResult = ISubmittableResult>(result: ISubmittableResult): R;
     paymentInfo(account: AddressOrPair, options?: Partial<PayloadOptions>): Promise<TxPaymentInfo>;
@@ -21,6 +21,10 @@ export declare abstract class BaseSubmittableExtrinsic extends Extrinsic impleme
     send(): TxHash;
     send(callback: Callback): TxUnsub;
     protected getSystemEventsAt(hash: BlockHash): Promise<FrameSystemEventRecord[]>;
+    /**
+     * Override callU8a to add transaction parameter validation before encoding
+     */
+    get callU8a(): Uint8Array;
     toU8a(): Uint8Array;
     toHex(): HexString;
 }

package/extrinsic/submittable/BaseSubmittableExtrinsic.js

@@ -1,5 +1,7 @@
 import { Extrinsic } from '@dedot/codecs';
-import { DedotError, hexToU8a, isFunction, toHex, u8aToHex } from '@dedot/utils';
+import * as $ from '@dedot/shape';
+import { DedotError, hexToU8a, isFunction, stringCamelCase, toHex, u8aToHex } from '@dedot/utils';
+import { buildCompatibilityError } from '../../executor/validation-helpers.js';
 import { ExtraSignedExtension } from '../extensions/index.js';
 import { fakeSigner } from './fakeSigner.js';
 import { isKeyringPair, signRawMessage, txDefer } from './utils.js';
@@ -7,8 +9,8 @@ export class BaseSubmittableExtrinsic extends Extrinsic {
     client;
     #alterTx;
     #hooks;
-    constructor(client, call) {
-        super(client.registry, call);
+    constructor(client, call, preamble) {
+        super(client.registry, call, preamble);
         this.client = client;
     }
     withHooks(hooks) {
@@ -115,10 +117,69 @@ export class BaseSubmittableExtrinsic extends Extrinsic {
         const atApi = (await this.client.at(hash));
         return await atApi.query.system.events();
     }
+    /**
+     * Override callU8a to add transaction parameter validation before encoding
+     */
+    get callU8a() {
+        // Validate transaction parameters first
+        this.#validateTxParams();
+        // Then call parent implementation which does $RuntimeCall.assert and encoding
+        return super.callU8a;
+    }
+    /**
+     * Validate transaction parameters against their type definitions
+     * @private
+     */
+    #validateTxParams() {
+        // Skip if palletCall is a string (flat enum, no params)
+        if (typeof this.call.palletCall === 'string')
+            return;
+        if (!this.call.palletCall?.name)
+            return;
+        // 1. Find pallet metadata
+        const palletName = this.call.pallet;
+        const pallet = this.registry.metadata.pallets.find((p) => stringCamelCase(p.name) === stringCamelCase(palletName));
+        if (!pallet?.calls)
+            return;
+        // 2. Get calls enum type definition
+        const callsType = this.registry.metadata.types[pallet.calls.typeId];
+        if (callsType.typeDef.type !== 'Enum')
+            return;
+        // 3. Find specific call definition
+        const callName = this.call.palletCall.name;
+        const callDef = callsType.typeDef.value.members.find((m) => stringCamelCase(m.name) === stringCamelCase(callName));
+        if (!callDef)
+            return;
+        // 4. Build param specs from field definitions
+        const paramSpecs = callDef.fields.map((f) => ({
+            name: stringCamelCase(f.name || ''),
+            typeId: f.typeId,
+        }));
+        // 5. Extract args in field order from params object
+        const params = this.call.palletCall.params || {};
+        const args = paramSpecs.map((spec) => params[spec.name]);
+        // 6. Validate with tuple codec
+        const $ParamsTuple = $.Tuple(...paramSpecs.map((spec) => this.registry.findCodec(spec.typeId)));
+        try {
+            $ParamsTuple.assert?.(args);
+        }
+        catch (error) {
+            if (error instanceof $.ShapeAssertError) {
+                throw buildCompatibilityError(error, // --
+                paramSpecs, args, {
+                    apiName: `${stringCamelCase(pallet.name)}.${stringCamelCase(callDef.name)}`,
+                    registry: this.registry,
+                });
+            }
+            throw error;
+        }
+    }
     toU8a() {
         if (this.#alterTx) {
             return hexToU8a(this.#alterTx);
         }
+        // Validate transaction parameters before encoding
+        this.#validateTxParams();
         return super.toU8a();
     }
     toHex() {

package/extrinsic/submittable/SubmittableExtrinsic.d.ts

@@ -1,11 +1,14 @@
-import { BlockHash } from '@dedot/codecs';
+import { BlockHash, Extrinsic } from '@dedot/codecs';
 import { AddressOrPair, Callback, DryRunResult, ISubmittableExtrinsicLegacy, ISubmittableResult, SignerOptions, TxHash, TxUnsub } from '@dedot/types';
+import { HexString } from '@dedot/utils';
+import { LegacyClient } from '../../client/LegacyClient.js';
 import { BaseSubmittableExtrinsic } from './BaseSubmittableExtrinsic.js';
 /**
  * @name SubmittableExtrinsic
  * @description A wrapper around an Extrinsic that exposes methods to sign, send, and other utility around Extrinsic.
  */
 export declare class SubmittableExtrinsic extends BaseSubmittableExtrinsic implements ISubmittableExtrinsicLegacy {
+    static fromTx(client: LegacyClient<any>, tx: HexString | Extrinsic): SubmittableExtrinsic;
     dryRun(account: AddressOrPair, optionsOrHash?: Partial<SignerOptions> | BlockHash): Promise<DryRunResult>;
     send(): TxHash;
     send(callback: Callback<ISubmittableResult>): TxUnsub;

package/extrinsic/submittable/SubmittableExtrinsic.js

@@ -1,4 +1,4 @@
-import { assert, isHex } from '@dedot/utils';
+import { assert, isHex, noop } from '@dedot/utils';
 import { BaseSubmittableExtrinsic } from './BaseSubmittableExtrinsic.js';
 import { SubmittableResult } from './SubmittableResult.js';
 import { toTxStatus, txDefer } from './utils.js';
@@ -7,6 +7,16 @@ import { toTxStatus, txDefer } from './utils.js';
  * @description A wrapper around an Extrinsic that exposes methods to sign, send, and other utility around Extrinsic.
  */
 export class SubmittableExtrinsic extends BaseSubmittableExtrinsic {
+    static fromTx(client, tx) {
+        let extrinsic;
+        if (isHex(tx)) {
+            extrinsic = client.registry.$Extrinsic.tryDecode(tx);
+        }
+        else {
+            extrinsic = tx;
+        }
+        return new SubmittableExtrinsic(client, extrinsic.call, extrinsic.preamble);
+    }
     async dryRun(account, optionsOrHash) {
         const dryRunFn = this.client.rpc.system_dryRun;
         if (isHex(optionsOrHash)) {
@@ -20,7 +30,11 @@ export class SubmittableExtrinsic extends BaseSubmittableExtrinsic {
         const txHex = this.toHex();
         const txHash = this.hash;
         const { deferTx, onTxProgress } = txDefer();
-        const unsub = this.client.rpc.author_submitAndWatchExtrinsic(txHex, async (txStatus) => {
+        let unsub;
+        this.client.rpc
+            .author_submitAndWatchExtrinsic(txHex, async (txStatus) => {
+            let status;
+            let result;
             if (txStatus.type === 'InBlock' || txStatus.type === 'Finalized') {
                 const blockHash = txStatus.value;
                 const [signedBlock, blockEvents] = await Promise.all([
@@ -31,25 +45,33 @@ export class SubmittableExtrinsic extends BaseSubmittableExtrinsic {
                 assert(txIndex >= 0, 'Extrinsic not found!');
                 const events = blockEvents.filter(({ phase }) => phase.type === 'ApplyExtrinsic' && phase.value === txIndex);
                 const blockNumber = signedBlock.block.header.number;
-                const status = toTxStatus(txStatus, { txIndex, blockNumber });
-                const result = this.transformTxResult(new SubmittableResult({ status, txHash, events, txIndex }));
-                onTxProgress(result);
-                !isSubscription && deferTx.resolve(txHash);
-                return callback?.(result);
+                status = toTxStatus(txStatus, { txIndex, blockNumber });
+                result = this.transformTxResult(new SubmittableResult({ status, txHash, events, txIndex }));
             }
             else {
-                const status = toTxStatus(txStatus);
-                const result = this.transformTxResult(new SubmittableResult({ status, txHash }));
-                onTxProgress(result);
-                !isSubscription && deferTx.resolve(txHash);
-                return callback?.(result);
+                status = toTxStatus(txStatus);
+                result = this.transformTxResult(new SubmittableResult({ status, txHash }));
             }
-        });
-        if (isSubscription) {
-            unsub.then((x) => {
+            onTxProgress(result);
+            if (isSubscription) {
+                callback?.(result);
+            }
+            else {
+                deferTx.resolve(txHash);
+            }
+            if (status.type === 'Finalized' || // --
+                status.type === 'Invalid' ||
+                status.type === 'Drop') {
+                unsub?.().catch(noop);
+            }
+        })
+            .then((x) => {
+            unsub = x;
+            if (isSubscription) {
                 deferTx.resolve(x);
-            });
-        }
+            }
+        })
+            .catch(deferTx.reject);
         return deferTx.promise;
     }
 }

package/extrinsic/submittable/SubmittableExtrinsicV2.d.ts

@@ -1,5 +1,7 @@
+import { Extrinsic, Preamble } from '@dedot/codecs';
 import { Callback, IRuntimeTxCall, TxHash, TxUnsub } from '@dedot/types';
-import { DedotClient } from '../../client/index.js';
+import { HexString } from '@dedot/utils';
+import { V2Client } from '../../client/V2Client.js';
 import { BaseSubmittableExtrinsic } from './BaseSubmittableExtrinsic.js';
 /**
  * @name SubmittableExtrinsicV2
@@ -7,8 +9,9 @@ import { BaseSubmittableExtrinsic } from './BaseSubmittableExtrinsic.js';
  */
 export declare class SubmittableExtrinsicV2 extends BaseSubmittableExtrinsic {
     #private;
-    client: DedotClient<any>;
-    constructor(client: DedotClient<any>, call: IRuntimeTxCall);
+    client: V2Client<any>;
+    constructor(client: V2Client<any>, call: IRuntimeTxCall, preamble?: Preamble);
+    static fromTx(client: V2Client<any>, tx: HexString | Extrinsic): SubmittableExtrinsicV2;
     send(): TxHash;
     send(callback: Callback): TxUnsub;
 }

package/extrinsic/submittable/SubmittableExtrinsicV2.js

@@ -1,4 +1,4 @@
-import { AsyncQueue, noop, waitFor } from '@dedot/utils';
+import { AsyncQueue, isHex, noop, waitFor } from '@dedot/utils';
 import { BaseSubmittableExtrinsic } from './BaseSubmittableExtrinsic.js';
 import { SubmittableResult } from './SubmittableResult.js';
 import { InvalidTxError } from './errors.js';
@@ -9,10 +9,20 @@ import { txDefer } from './utils.js';
  */
 export class SubmittableExtrinsicV2 extends BaseSubmittableExtrinsic {
     client;
-    constructor(client, call) {
-        super(client, call);
+    constructor(client, call, preamble) {
+        super(client, call, preamble);
         this.client = client;
     }
+    static fromTx(client, tx) {
+        let extrinsic;
+        if (isHex(tx)) {
+            extrinsic = client.registry.$Extrinsic.tryDecode(tx);
+        }
+        else {
+            extrinsic = tx;
+        }
+        return new SubmittableExtrinsicV2(client, extrinsic.call, extrinsic.preamble);
+    }
     async #send(callback) {
         const api = this.client;
         const txHex = this.toHex();

package/json-rpc/JsonRpcClient.d.ts

@@ -1,11 +1,11 @@
 import type { ConnectionStatus, JsonRpcProvider, ProviderEvent } from '@dedot/providers';
-import type { RpcVersion, VersionedGenericSubstrateApi } from '@dedot/types';
+import type { GenericSubstrateApi } from '@dedot/types';
 import { EventEmitter } from '@dedot/utils';
 import type { SubstrateApi } from '../chaintypes/index.js';
 import type { IJsonRpcClient, JsonRpcClientOptions } from '../types.js';
 export declare const isJsonRpcProvider: (provider: any) => provider is JsonRpcProvider;
-export declare class JsonRpcClient<ChainApi extends VersionedGenericSubstrateApi = SubstrateApi, // prettier-end-here
-Events extends string = ProviderEvent> extends EventEmitter<Events> implements IJsonRpcClient<ChainApi[RpcVersion], Events> {
+export declare class JsonRpcClient<ChainApi extends GenericSubstrateApi = SubstrateApi, // prettier-end-here
+Events extends string = ProviderEvent> extends EventEmitter<Events> implements IJsonRpcClient<ChainApi, Events> {
     #private;
     constructor(options: JsonRpcClientOptions | JsonRpcProvider);
     /**
@@ -13,13 +13,13 @@ Events extends string = ProviderEvent> extends EventEmitter<Events> implements I
      *
      * @param options
      */
-    static create<ChainApi extends VersionedGenericSubstrateApi = SubstrateApi>(options: JsonRpcClientOptions | JsonRpcProvider): Promise<JsonRpcClient<ChainApi>>;
+    static create<ChainApi extends GenericSubstrateApi = SubstrateApi>(options: JsonRpcClientOptions | JsonRpcProvider): Promise<JsonRpcClient<ChainApi>>;
     /**
      * Alias for __JsonRpcClient.create__
      *
      * @param options
      */
-    static new<ChainApi extends VersionedGenericSubstrateApi = SubstrateApi>(options: JsonRpcClientOptions | JsonRpcProvider): Promise<JsonRpcClient<ChainApi>>;
+    static new<ChainApi extends GenericSubstrateApi = SubstrateApi>(options: JsonRpcClientOptions | JsonRpcProvider): Promise<JsonRpcClient<ChainApi>>;
     get options(): JsonRpcClientOptions;
     /**
      * @description Check connection status of the api instance
@@ -47,5 +47,5 @@ Events extends string = ProviderEvent> extends EventEmitter<Events> implements I
      * const result = await client.rpc.module_rpc_name();
      * ```
      */
-    get rpc(): ChainApi[RpcVersion]['rpc'];
+    get rpc(): ChainApi['rpc'];
 }

package/json-rpc/group/Archive.d.ts

@@ -13,7 +13,7 @@ import { JsonRpcGroup, JsonRpcGroupOptions } from './JsonRpcGroup.js';
  */
 export declare class Archive extends JsonRpcGroup {
     #private;
-    constructor(client: IJsonRpcClient, options?: Partial<JsonRpcGroupOptions>);
+    constructor(client: IJsonRpcClient<any>, options?: Partial<JsonRpcGroupOptions>);
     /**
      * Retrieves the body (list of transactions) of a given block.
      * Returns an array of strings containing the hexadecimal-encoded SCALE-codec-encoded

package/json-rpc/group/ChainHead/ChainHead.d.ts

@@ -1,5 +1,6 @@
 import { BlockHash, Option } from '@dedot/codecs';
 import type { ChainHeadRuntimeVersion, OperationId, StorageQuery, StorageResult } from '@dedot/types/json-rpc';
+import { HashFn } from '@dedot/utils';
 import { Deferred, HexString } from '@dedot/utils';
 import type { IJsonRpcClient } from '../../../types.js';
 import { Archive } from '../Archive.js';
@@ -10,16 +11,22 @@ export type OperationHandler<T = any> = {
     storageResults?: Array<StorageResult>;
     hash: BlockHash;
 };
+export type PendingRequest<T = any> = {
+    method: string;
+    params: any[];
+    defer: Deferred<T>;
+};
 export type PinnedBlock = {
     hash: BlockHash;
     number: number;
     parent: BlockHash;
     runtime?: ChainHeadRuntimeVersion;
+    runtimeUpgraded?: boolean;
 };
 export type ChainHeadEvent = 'newBlock' | 'bestBlock' | 'finalizedBlock' | 'bestChainChanged';
 export declare class ChainHead extends JsonRpcGroup<ChainHeadEvent> {
     #private;
-    constructor(client: IJsonRpcClient, options?: Partial<JsonRpcGroupOptions>);
+    constructor(client: IJsonRpcClient<any>, options?: Partial<JsonRpcGroupOptions>);
     /**
      * Attach an Archive instance as fallback for operations that fail due to unpinned blocks.
      * When a ChainHeadBlockNotPinnedError occurs, the operation will automatically fallback
@@ -29,12 +36,21 @@ export declare class ChainHead extends JsonRpcGroup<ChainHeadEvent> {
      * @returns this ChainHead instance for method chaining
      */
     withArchive(archive: Archive): this;
+    /**
+     * Override send() to track pending requests for retry on network disconnection
+     */
+    send<T = any>(method: string, ...params: any[]): Promise<T>;
     runtimeVersion(): Promise<ChainHeadRuntimeVersion>;
     bestRuntimeVersion(): Promise<ChainHeadRuntimeVersion>;
     finalizedHash(): Promise<BlockHash>;
     bestHash(): Promise<BlockHash>;
     bestBlock(): Promise<PinnedBlock>;
     finalizedBlock(): Promise<PinnedBlock>;
+    /**
+     * Returns the detected hasher for the chain
+     * Returns undefined if detection failed (client should use default)
+     */
+    hasher(): Promise<HashFn | undefined>;
     findBlock(hash: BlockHash): PinnedBlock | undefined;
     isPinned(hash: BlockHash): boolean;
     /**
@@ -44,7 +60,7 @@ export declare class ChainHead extends JsonRpcGroup<ChainHeadEvent> {
     /**
      * chainHead_follow
      */
-    follow(): Promise<void>;
+    follow(force?: boolean): Promise<void>;
     /**
      * chainHead_body
      */