dedot 0.0.1-alpha.22

package/client/Dedot.js

@@ -0,0 +1,440 @@
+import { HttpProvider, WsProvider } from '@polkadot/rpc-provider';
+import { $Metadata, CodecRegistry } from '@dedot/codecs';
+import { ConstantExecutor, ErrorExecutor, EventExecutor, RpcExecutor, RuntimeApiExecutor, StorageQueryExecutor, TxExecutor, } from '../executor';
+import { newProxyChain } from '../proxychain';
+import { ensurePresence } from '@dedot/utils';
+import localforage from 'localforage';
+import { hexAddPrefix, u8aToHex } from '@polkadot/util';
+export const KEEP_ALIVE_INTERVAL = 10_000; // in ms
+export const CATCH_ALL_METADATA_KEY = `RAW_META/ALL`;
+export const SUPPORTED_METADATA_VERSIONS = [15, 14];
+/**
+ * @name Dedot
+ * @description Promised-based API Client for Polkadot & Substrate
+ *
+ * ### Initialize API instance and interact with substrate-based network
+ * ```typescript
+ * import { Dedot } from 'dedot';
+ * import { PolkadotApi } from '@dedot/chaintypes/polkadot';
+ *
+ * const run = async () => {
+ *   const api = await Dedot.new<PolkadotApi>('wss://rpc.polkadot.io');
+ *
+ *   // Call rpc `state_getMetadata` to fetch raw scale-encoded metadata and decode it.
+ *   const metadata = await api.rpc.state.getMetadata();
+ *   console.log('Metadata:', metadata);
+ *
+ *   // Query on-chain storage
+ *   const address = '14...';
+ *   const balance = await api.query.system.account(address);
+ *   console.log('Balance:', balance);
+ *
+ *
+ *   // Subscribe to on-chain storage changes
+ *   const unsub = await api.query.system.number((blockNumber) => {
+ *     console.log(`Current block number: ${blockNumber}`);
+ *   });
+ *
+ *   // Get pallet constants
+ *   const ss58Prefix = api.consts.system.ss58Prefix;
+ *   console.log('Polkadot ss58Prefix:', ss58Prefix)
+ *
+ *   // await unsub();
+ *   // await api.disconnect();
+ * }
+ *
+ * run().catch(console.error);
+ * ```
+ */
+export class Dedot {
+    #provider;
+    #registry;
+    #options;
+    #metadata;
+    #metadataLatest;
+    #genesisHash;
+    #runtimeVersion;
+    #chainProperties;
+    #runtimeChain;
+    #localCache;
+    #runtimeSubscriptionUnsub;
+    #healthTimer;
+    /**
+     * Use factory methods (`create`, `new`) to create `Dedot` instances.
+     *
+     * @param options
+     * @protected
+     */
+    constructor(options) {
+        this.#options = this.#normalizeOptions(options);
+        this.#provider = this.#getProvider();
+        this.#registry = new CodecRegistry();
+    }
+    /**
+     * Factory method to create a new Dedot instance
+     *
+     * @param options
+     */
+    static async create(options) {
+        const api = new Dedot(options);
+        if (api.provider instanceof WsProvider) {
+            await api.provider.isReady;
+        }
+        await api.init();
+        return api;
+    }
+    /**
+     * Alias for __Dedot.create__
+     * @param options
+     */
+    static async new(options) {
+        return Dedot.create(options);
+    }
+    /**
+     * Initialize APIs before usage
+     */
+    async init() {
+        await this.#initializeLocalCache();
+        // Fetching node information
+        let [genesisHash, runtimeVersion, chainName, chainProps, metadata] = await Promise.all([
+            this.rpc.chain.getBlockHash(0),
+            this.rpc.state.getRuntimeVersion(),
+            this.rpc.system.chain(),
+            this.rpc.system.properties(),
+            (await this.#shouldLoadPreloadMetadata()) ? this.#fetchMetadata() : Promise.resolve(undefined),
+        ]);
+        this.#genesisHash = genesisHash;
+        this.#runtimeVersion = runtimeVersion;
+        this.#chainProperties = chainProps;
+        this.#runtimeChain = chainName;
+        await this.#setupMetadata(metadata);
+        this.#subscribeUpdates();
+    }
+    async #initializeLocalCache() {
+        // Initialize local cache
+        if (this.#options.cacheMetadata) {
+            try {
+                // TODO add a custom driver to support nodejs
+                this.#localCache = localforage.createInstance({
+                    driver: [localforage.INDEXEDDB, localforage.LOCALSTORAGE],
+                    name: 'DedotCache',
+                    storeName: 'LocalCache',
+                });
+                // Verify the storage is working
+                await this.#localCache.setItem('testKey', 'testValue');
+                await this.#localCache.removeItem('testKey');
+            }
+            catch (e) {
+                this.#localCache = undefined;
+                this.#options.cacheMetadata = false;
+                console.error('Cannot initialize local cache in this environment, disable metadata caching');
+            }
+        }
+    }
+    async #setupMetadata(preloadMetadata) {
+        let metadata = preloadMetadata;
+        const metadataKey = this.currentMetadataKey;
+        const optMetadataBundles = this.#options.metadata;
+        let shouldUpdateCache = !!metadata;
+        if (optMetadataBundles && !metadata) {
+            const optRawMetadata = optMetadataBundles[CATCH_ALL_METADATA_KEY] || optMetadataBundles[metadataKey];
+            if (optRawMetadata) {
+                metadata = $Metadata.tryDecode(optRawMetadata);
+            }
+        }
+        try {
+            if (this.#localCache && this.#options.cacheMetadata) {
+                if (!metadata) {
+                    try {
+                        const cachedRawMetadata = await this.#localCache.getItem(metadataKey);
+                        if (cachedRawMetadata) {
+                            metadata = $Metadata.tryDecode(cachedRawMetadata);
+                        }
+                    }
+                    catch (e) {
+                        console.error('Cannot decode raw metadata, try fetching fresh metadata from chain.', e);
+                    }
+                }
+            }
+        }
+        finally {
+            if (!metadata) {
+                metadata = await this.#fetchMetadata();
+                if (this.#options.cacheMetadata)
+                    shouldUpdateCache = true;
+            }
+        }
+        if (shouldUpdateCache && this.#localCache) {
+            await this.#localCache.setItem(metadataKey, u8aToHex($Metadata.tryEncode(metadata)));
+        }
+        if (!metadata) {
+            throw new Error('Cannot load metadata');
+        }
+        this.setMetadata(metadata);
+    }
+    async #fetchMetadata() {
+        // It makes sense to call metadata.metadataVersions to fetch the list of supported metadata versions first
+        // But for now, this approach could potentially help save/reduce one rpc call to the server in case the node support v15
+        // Question: Why not having a `metadata.metadataLatest` to fetch the latest version?
+        for (const version of SUPPORTED_METADATA_VERSIONS) {
+            try {
+                const rawMetadata = await this.call.metadata.metadataAtVersion(version);
+                if (!rawMetadata)
+                    continue;
+                return $Metadata.tryDecode(rawMetadata);
+            }
+            catch { }
+        }
+        try {
+            return $Metadata.tryDecode(await this.call.metadata.metadata());
+        }
+        catch {
+            return await this.rpc.state.getMetadata();
+        }
+    }
+    #subscribeRuntimeUpgrades() {
+        // Disable runtime upgrades subscriptions if using a catch all metadata
+        if (this.#runtimeSubscriptionUnsub || !this.hasSubscriptions || this.hasCatchAllMetadata) {
+            return;
+        }
+        this.rpc.state
+            .subscribeRuntimeVersion(async (runtimeVersion) => {
+            if (runtimeVersion.specVersion !== this.#runtimeVersion?.specVersion) {
+                this.#runtimeVersion = runtimeVersion;
+                const newMetadata = await this.#fetchMetadata();
+                await this.#setupMetadata(newMetadata);
+            }
+        })
+            .then((unsub) => {
+            this.#runtimeSubscriptionUnsub = unsub;
+        });
+    }
+    #subscribeHealth() {
+        this.#unsubscribeHealth();
+        this.#healthTimer = setInterval(() => {
+            this.rpc.system.health().catch(console.error);
+        }, KEEP_ALIVE_INTERVAL);
+    }
+    #unsubscribeHealth() {
+        if (!this.#healthTimer) {
+            return;
+        }
+        clearInterval(this.#healthTimer);
+        this.#healthTimer = undefined;
+    }
+    async #unsubscribeRuntimeUpdates() {
+        if (!this.#runtimeSubscriptionUnsub) {
+            return;
+        }
+        await this.#runtimeSubscriptionUnsub();
+        this.#runtimeSubscriptionUnsub = undefined;
+    }
+    #subscribeUpdates() {
+        this.#subscribeRuntimeUpgrades();
+        this.#subscribeHealth();
+    }
+    async #unsubscribeUpdates() {
+        await this.#unsubscribeRuntimeUpdates();
+        this.#unsubscribeHealth();
+    }
+    async #shouldLoadPreloadMetadata() {
+        if (this.#options.metadata && Object.keys(this.#options.metadata).length) {
+            return false;
+        }
+        if (!this.#options.cacheMetadata || !this.#localCache) {
+            return true;
+        }
+        // TODO improve this
+        const keys = await this.#localCache.keys();
+        return !keys.some((k) => k.startsWith('RAW_META/'));
+    }
+    #normalizeOptions(options) {
+        if (typeof options === 'string') {
+            return { endpoint: options };
+        }
+        else {
+            let { metadata } = options;
+            if (metadata && typeof metadata === 'string') {
+                metadata = {
+                    [CATCH_ALL_METADATA_KEY]: hexAddPrefix(metadata),
+                };
+            }
+            return { ...options, metadata };
+        }
+    }
+    #getProvider() {
+        const { provider, endpoint } = this.#options;
+        if (provider)
+            return provider;
+        if (endpoint) {
+            if (endpoint.startsWith('ws://') || endpoint.startsWith('wss://')) {
+                return new WsProvider(endpoint);
+            }
+            else if (endpoint.startsWith('http://') || endpoint.startsWith('https://')) {
+                return new HttpProvider(endpoint);
+            }
+            else {
+                throw new Error('Invalid network endpoint, a valid endpoint should start with `wss://`, `ws://`, `https://` or `http://`');
+            }
+        }
+        // TODO support light-client
+        return new WsProvider();
+    }
+    /**
+     * @description Entry-point for executing RPCs to blockchain node.
+     *
+     * ```typescript
+     * // Subscribe to new heads
+     * api.rpc.chain.subscribeNewHeads((header) => {
+     *   console.log(header);
+     * });
+     *
+     * // Execute arbitrary rpc method: `module_rpc_name`
+     * const result = await api.rpc.module.rpc_name();
+     * ```
+     */
+    get rpc() {
+        // TODO add executable carrier to support calling arbitrary rpc methods via api.rpc(<method>)
+        return newProxyChain({ executor: new RpcExecutor(this) });
+    }
+    /**
+     * @description Entry-point for inspecting constants (parameter types) for all pallets (modules).
+     *
+     * ```typescript
+     * const ss58Prefix = api.consts.system.ss58Prefix;
+     * console.log('ss58Prefix:', ss58Prefix)
+     * ```
+     */
+    get consts() {
+        return newProxyChain({ executor: new ConstantExecutor(this) });
+    }
+    /**
+     * @description Entry-point for executing query to on-chain storage.
+     *
+     * ```typescript
+     * const balance = await api.query.system.account(<address>);
+     * console.log('Balance:', balance);
+     * ```
+     */
+    get query() {
+        return newProxyChain({ executor: new StorageQueryExecutor(this) });
+    }
+    queryAt(blockHash) {
+        return newProxyChain({ executor: new StorageQueryExecutor(this, blockHash) });
+    }
+    /**
+     * @description Entry-point for inspecting errors from metadata
+     */
+    get errors() {
+        return newProxyChain({ executor: new ErrorExecutor(this) });
+    }
+    /**
+     * @description Entry-point for inspecting events from metadata
+     */
+    get events() {
+        return newProxyChain({ executor: new EventExecutor(this) });
+    }
+    get call() {
+        return newProxyChain({ executor: new RuntimeApiExecutor(this) });
+    }
+    callAt(blockHash) {
+        return newProxyChain({ executor: new RuntimeApiExecutor(this, blockHash) });
+    }
+    get tx() {
+        return newProxyChain({ executor: new TxExecutor(this) });
+    }
+    /**
+     * @description Current provider for api connection
+     */
+    get provider() {
+        return this.#provider;
+    }
+    /**
+     * @description Codec registry
+     */
+    get registry() {
+        return this.#registry;
+    }
+    /**
+     * @description Check if metadata is present
+     */
+    get hasMetadata() {
+        return !!this.#metadata && !!this.#metadataLatest;
+    }
+    get metadata() {
+        return ensurePresence(this.#metadata);
+    }
+    get metadataLatest() {
+        return ensurePresence(this.#metadataLatest);
+    }
+    /**
+     * Setup metadata for
+     * @param metadata
+     */
+    setMetadata(metadata) {
+        this.#metadata = metadata;
+        this.#metadataLatest = metadata.latest;
+        this.registry.setMetadata(this.#metadataLatest);
+    }
+    /**
+     * @description Disconnect to blockchain node
+     */
+    async disconnect() {
+        await this.#unsubscribeUpdates();
+        await this.#provider.disconnect();
+    }
+    /**
+     * @description Clear local cache
+     */
+    async clearCache() {
+        await this.#localCache?.clear();
+    }
+    /**
+     * @description Check if current provider can make subscription request (e.: via WebSocket)
+     */
+    get hasSubscriptions() {
+        return this.provider.hasSubscriptions;
+    }
+    /**
+     * @description Check if it's connected to the blockchain node
+     */
+    get isConnected() {
+        return this.provider.isConnected;
+    }
+    /**
+     * @description Check if the api instance is using a catch-all metadata
+     */
+    get hasCatchAllMetadata() {
+        return !!this.#options.metadata && !!this.#options.metadata[CATCH_ALL_METADATA_KEY];
+    }
+    get currentMetadataKey() {
+        return `RAW_META/${this.#genesisHash || '0x'}/${this.#runtimeVersion?.specVersion || '---'}`;
+    }
+    /**
+     * @description Genesis hash of connected blockchain node
+     */
+    get genesisHash() {
+        return this.#genesisHash;
+    }
+    /**
+     * @description Runtime version of connected blockchain node
+     */
+    get runtimeVersion() {
+        return this.#runtimeVersion;
+    }
+    /**
+     * @description Chain properties of connected blockchain node
+     */
+    get chainProperties() {
+        return this.#chainProperties;
+    }
+    /**
+     * @description Runtime chain name of connected blockchain node
+     */
+    get runtimeChain() {
+        return this.#runtimeChain;
+    }
+    get options() {
+        return this.#options;
+    }
+}

package/client/index.d.ts

@@ -0,0 +1 @@
+export * from './Dedot';

package/client/index.js

@@ -0,0 +1 @@
+export * from './Dedot';

package/executor/ConstantExecutor.d.ts

@@ -0,0 +1,11 @@
+import type { SubstrateApi } from '@dedot/chaintypes';
+import { GenericSubstrateApi } from '@dedot/types';
+import { Executor } from './Executor';
+/**
+ * @name ConstantExecutor
+ *
+ * Find & decode the constant value from metadata
+ */
+export declare class ConstantExecutor<ChainApi extends GenericSubstrateApi = SubstrateApi> extends Executor<ChainApi> {
+    execute(pallet: string, constantName: string): unknown;
+}

package/executor/ConstantExecutor.js

@@ -0,0 +1,18 @@
+import { stringCamelCase } from '@polkadot/util';
+import { Executor } from './Executor';
+/**
+ * @name ConstantExecutor
+ *
+ * Find & decode the constant value from metadata
+ */
+export class ConstantExecutor extends Executor {
+    execute(pallet, constantName) {
+        const targetPallet = this.getPallet(pallet);
+        const constantDef = targetPallet.constants.find((one) => stringCamelCase(one.name) === constantName);
+        if (!constantDef) {
+            throw new Error(`Constant ${constantName} not found in pallet ${pallet}`);
+        }
+        const $codec = this.registry.findPortableCodec(constantDef.typeId);
+        return $codec.tryDecode(constantDef.value);
+    }
+}

package/executor/ErrorExecutor.d.ts

@@ -0,0 +1,11 @@
+import { GenericPalletError, GenericSubstrateApi } from '@dedot/types';
+import { SubstrateApi } from '@dedot/chaintypes';
+import { Executor } from './Executor';
+/**
+ * @name ErrorExecutor
+ * @description Find pallet error information from metadata
+ */
+export declare class ErrorExecutor<ChainApi extends GenericSubstrateApi = SubstrateApi> extends Executor<ChainApi> {
+    #private;
+    execute(pallet: string, errorName: string): GenericPalletError;
+}

package/executor/ErrorExecutor.js

@@ -0,0 +1,43 @@
+import { Executor } from './Executor';
+import { assert } from '@dedot/utils';
+import { hexToU8a, isHex, isNumber, isObject, stringPascalCase } from '@polkadot/util';
+/**
+ * @name ErrorExecutor
+ * @description Find pallet error information from metadata
+ */
+export class ErrorExecutor extends Executor {
+    execute(pallet, errorName) {
+        const targetPallet = this.getPallet(pallet);
+        const errorTypeId = targetPallet.error;
+        assert(errorTypeId, `Not found error with id ${errorTypeId} in pallet ${pallet}`);
+        const errorDef = this.#getErrorDef(errorTypeId, errorName);
+        return {
+            meta: {
+                ...errorDef,
+                pallet: targetPallet.name,
+                palletIndex: targetPallet.index,
+            },
+            is: (errorInfo) => {
+                if (isObject(errorInfo) && errorInfo.tag === 'Module') {
+                    errorInfo = errorInfo.value;
+                }
+                if (isObject(errorInfo) && isNumber(errorInfo.index) && isHex(errorInfo.error)) {
+                    return errorInfo.index === targetPallet.index && hexToU8a(errorInfo.error)[0] === errorDef.index;
+                }
+                return false;
+            },
+        };
+    }
+    #getErrorDef(errorTypeId, errorName) {
+        const def = this.metadata.types[errorTypeId];
+        assert(def, `Error def not found for id ${errorTypeId}`);
+        const { tag, value } = def.type;
+        assert(tag === 'Enum', `Error type should be an enum, found: ${tag}`);
+        const errorDef = value.members.find(({ name }) => stringPascalCase(name) === errorName);
+        assert(errorDef, `Error def not found for ${errorName}`);
+        return {
+            ...errorDef,
+            fieldCodecs: errorDef.fields.map(({ typeId }) => this.registry.findPortableCodec(typeId)),
+        };
+    }
+}

package/executor/EventExecutor.d.ts

@@ -0,0 +1,11 @@
+import { GenericPalletEvent, GenericSubstrateApi } from '@dedot/types';
+import { SubstrateApi } from '@dedot/chaintypes';
+import { Executor } from './Executor';
+/**
+ * @name EventExecutor
+ * @description Find pallet event information from metadata
+ */
+export declare class EventExecutor<ChainApi extends GenericSubstrateApi = SubstrateApi> extends Executor<ChainApi> {
+    #private;
+    execute(pallet: string, errorName: string): GenericPalletEvent<string, string>;
+}

package/executor/EventExecutor.js

@@ -0,0 +1,49 @@
+import { Executor } from './Executor';
+import { stringCamelCase, stringPascalCase } from '@polkadot/util';
+import { assert } from '@dedot/utils';
+/**
+ * @name EventExecutor
+ * @description Find pallet event information from metadata
+ */
+export class EventExecutor extends Executor {
+    execute(pallet, errorName) {
+        const targetPallet = this.getPallet(pallet);
+        const eventTypeId = targetPallet.event;
+        assert(eventTypeId, `Not found event with id ${eventTypeId} in pallet ${pallet}`);
+        const eventDef = this.#getEventDef(eventTypeId, errorName);
+        const is = (event) => {
+            const palletCheck = stringCamelCase(event.pallet) === pallet;
+            if (typeof event.palletEvent === 'string') {
+                return palletCheck && stringPascalCase(event.palletEvent) === errorName;
+            }
+            else if (typeof event.palletEvent === 'object') {
+                return palletCheck && stringPascalCase(event.palletEvent.name) === errorName;
+            }
+            return false;
+        };
+        const as = (event) => {
+            return is(event) ? event : undefined;
+        };
+        return {
+            is,
+            as,
+            meta: {
+                ...eventDef,
+                pallet: targetPallet.name,
+                palletIndex: targetPallet.index,
+            },
+        };
+    }
+    #getEventDef(eventTypeId, errorName) {
+        const def = this.metadata.types[eventTypeId];
+        assert(def, `Event def not found for id ${eventTypeId}`);
+        const { tag, value } = def.type;
+        assert(tag === 'Enum', `Event type should be an enum, found: ${tag}`);
+        const eventDef = value.members.find(({ name }) => stringPascalCase(name) === errorName);
+        assert(eventDef, `Event def not found for ${errorName}`);
+        return {
+            ...eventDef,
+            fieldCodecs: eventDef.fields.map(({ typeId }) => this.registry.findPortableCodec(typeId)),
+        };
+    }
+}