dedot 0.0.1-alpha.22

package/cjs/client/Dedot.js

@@ -0,0 +1,444 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Dedot = exports.SUPPORTED_METADATA_VERSIONS = exports.CATCH_ALL_METADATA_KEY = exports.KEEP_ALIVE_INTERVAL = void 0;
+const rpc_provider_1 = require("@polkadot/rpc-provider");
+const codecs_1 = require("@dedot/codecs");
+const executor_1 = require("../executor");
+const proxychain_1 = require("../proxychain");
+const utils_1 = require("@dedot/utils");
+const localforage_1 = require("localforage");
+const util_1 = require("@polkadot/util");
+exports.KEEP_ALIVE_INTERVAL = 10_000; // in ms
+exports.CATCH_ALL_METADATA_KEY = `RAW_META/ALL`;
+exports.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);
+ * ```
+ */
+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 codecs_1.CodecRegistry();
+    }
+    /**
+     * Factory method to create a new Dedot instance
+     *
+     * @param options
+     */
+    static async create(options) {
+        const api = new Dedot(options);
+        if (api.provider instanceof rpc_provider_1.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_1.default.createInstance({
+                    driver: [localforage_1.default.INDEXEDDB, localforage_1.default.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[exports.CATCH_ALL_METADATA_KEY] || optMetadataBundles[metadataKey];
+            if (optRawMetadata) {
+                metadata = codecs_1.$Metadata.tryDecode(optRawMetadata);
+            }
+        }
+        try {
+            if (this.#localCache && this.#options.cacheMetadata) {
+                if (!metadata) {
+                    try {
+                        const cachedRawMetadata = await this.#localCache.getItem(metadataKey);
+                        if (cachedRawMetadata) {
+                            metadata = codecs_1.$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, (0, util_1.u8aToHex)(codecs_1.$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 exports.SUPPORTED_METADATA_VERSIONS) {
+            try {
+                const rawMetadata = await this.call.metadata.metadataAtVersion(version);
+                if (!rawMetadata)
+                    continue;
+                return codecs_1.$Metadata.tryDecode(rawMetadata);
+            }
+            catch { }
+        }
+        try {
+            return codecs_1.$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);
+        }, exports.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 = {
+                    [exports.CATCH_ALL_METADATA_KEY]: (0, util_1.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 rpc_provider_1.WsProvider(endpoint);
+            }
+            else if (endpoint.startsWith('http://') || endpoint.startsWith('https://')) {
+                return new rpc_provider_1.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 rpc_provider_1.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 (0, proxychain_1.newProxyChain)({ executor: new executor_1.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 (0, proxychain_1.newProxyChain)({ executor: new executor_1.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 (0, proxychain_1.newProxyChain)({ executor: new executor_1.StorageQueryExecutor(this) });
+    }
+    queryAt(blockHash) {
+        return (0, proxychain_1.newProxyChain)({ executor: new executor_1.StorageQueryExecutor(this, blockHash) });
+    }
+    /**
+     * @description Entry-point for inspecting errors from metadata
+     */
+    get errors() {
+        return (0, proxychain_1.newProxyChain)({ executor: new executor_1.ErrorExecutor(this) });
+    }
+    /**
+     * @description Entry-point for inspecting events from metadata
+     */
+    get events() {
+        return (0, proxychain_1.newProxyChain)({ executor: new executor_1.EventExecutor(this) });
+    }
+    get call() {
+        return (0, proxychain_1.newProxyChain)({ executor: new executor_1.RuntimeApiExecutor(this) });
+    }
+    callAt(blockHash) {
+        return (0, proxychain_1.newProxyChain)({ executor: new executor_1.RuntimeApiExecutor(this, blockHash) });
+    }
+    get tx() {
+        return (0, proxychain_1.newProxyChain)({ executor: new executor_1.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 (0, utils_1.ensurePresence)(this.#metadata);
+    }
+    get metadataLatest() {
+        return (0, utils_1.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[exports.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;
+    }
+}
+exports.Dedot = Dedot;

package/cjs/client/index.js

@@ -0,0 +1,17 @@
+"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("./Dedot"), exports);

package/cjs/executor/ConstantExecutor.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConstantExecutor = void 0;
+const util_1 = require("@polkadot/util");
+const Executor_1 = require("./Executor");
+/**
+ * @name ConstantExecutor
+ *
+ * Find & decode the constant value from metadata
+ */
+class ConstantExecutor extends Executor_1.Executor {
+    execute(pallet, constantName) {
+        const targetPallet = this.getPallet(pallet);
+        const constantDef = targetPallet.constants.find((one) => (0, util_1.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);
+    }
+}
+exports.ConstantExecutor = ConstantExecutor;

package/cjs/executor/ErrorExecutor.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorExecutor = void 0;
+const Executor_1 = require("./Executor");
+const utils_1 = require("@dedot/utils");
+const util_1 = require("@polkadot/util");
+/**
+ * @name ErrorExecutor
+ * @description Find pallet error information from metadata
+ */
+class ErrorExecutor extends Executor_1.Executor {
+    execute(pallet, errorName) {
+        const targetPallet = this.getPallet(pallet);
+        const errorTypeId = targetPallet.error;
+        (0, utils_1.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 ((0, util_1.isObject)(errorInfo) && errorInfo.tag === 'Module') {
+                    errorInfo = errorInfo.value;
+                }
+                if ((0, util_1.isObject)(errorInfo) && (0, util_1.isNumber)(errorInfo.index) && (0, util_1.isHex)(errorInfo.error)) {
+                    return errorInfo.index === targetPallet.index && (0, util_1.hexToU8a)(errorInfo.error)[0] === errorDef.index;
+                }
+                return false;
+            },
+        };
+    }
+    #getErrorDef(errorTypeId, errorName) {
+        const def = this.metadata.types[errorTypeId];
+        (0, utils_1.assert)(def, `Error def not found for id ${errorTypeId}`);
+        const { tag, value } = def.type;
+        (0, utils_1.assert)(tag === 'Enum', `Error type should be an enum, found: ${tag}`);
+        const errorDef = value.members.find(({ name }) => (0, util_1.stringPascalCase)(name) === errorName);
+        (0, utils_1.assert)(errorDef, `Error def not found for ${errorName}`);
+        return {
+            ...errorDef,
+            fieldCodecs: errorDef.fields.map(({ typeId }) => this.registry.findPortableCodec(typeId)),
+        };
+    }
+}
+exports.ErrorExecutor = ErrorExecutor;

package/cjs/executor/EventExecutor.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventExecutor = void 0;
+const Executor_1 = require("./Executor");
+const util_1 = require("@polkadot/util");
+const utils_1 = require("@dedot/utils");
+/**
+ * @name EventExecutor
+ * @description Find pallet event information from metadata
+ */
+class EventExecutor extends Executor_1.Executor {
+    execute(pallet, errorName) {
+        const targetPallet = this.getPallet(pallet);
+        const eventTypeId = targetPallet.event;
+        (0, utils_1.assert)(eventTypeId, `Not found event with id ${eventTypeId} in pallet ${pallet}`);
+        const eventDef = this.#getEventDef(eventTypeId, errorName);
+        const is = (event) => {
+            const palletCheck = (0, util_1.stringCamelCase)(event.pallet) === pallet;
+            if (typeof event.palletEvent === 'string') {
+                return palletCheck && (0, util_1.stringPascalCase)(event.palletEvent) === errorName;
+            }
+            else if (typeof event.palletEvent === 'object') {
+                return palletCheck && (0, util_1.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];
+        (0, utils_1.assert)(def, `Event def not found for id ${eventTypeId}`);
+        const { tag, value } = def.type;
+        (0, utils_1.assert)(tag === 'Enum', `Event type should be an enum, found: ${tag}`);
+        const eventDef = value.members.find(({ name }) => (0, util_1.stringPascalCase)(name) === errorName);
+        (0, utils_1.assert)(eventDef, `Event def not found for ${errorName}`);
+        return {
+            ...eventDef,
+            fieldCodecs: eventDef.fields.map(({ typeId }) => this.registry.findPortableCodec(typeId)),
+        };
+    }
+}
+exports.EventExecutor = EventExecutor;

package/cjs/executor/Executor.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Executor = void 0;
+const util_1 = require("@polkadot/util");
+/**
+ * @name Executor
+ * @description Execution abstraction for a specific action
+ */
+class Executor {
+    #api;
+    #atBlockHash;
+    constructor(api, atBlockHash) {
+        this.#api = api;
+        this.#atBlockHash = atBlockHash;
+    }
+    get api() {
+        return this.#api;
+    }
+    get atBlockHash() {
+        return this.#atBlockHash;
+    }
+    get provider() {
+        return this.api.provider;
+    }
+    get registry() {
+        return this.api.registry;
+    }
+    get metadata() {
+        return this.api.metadataLatest;
+    }
+    getPallet(name, throwErr = true) {
+        const targetPallet = this.metadata.pallets.find((p) => (0, util_1.stringCamelCase)(p.name) === name);
+        if (!targetPallet && throwErr) {
+            throw new Error(`Pallet not found: ${name}`);
+        }
+        return targetPallet;
+    }
+}
+exports.Executor = Executor;