@dedot/api 0.0.1-alpha.32

package/chaintypes/substrate/types.js

@@ -0,0 +1,2 @@
+// Generated by @dedot/codegen
+export {};

package/cjs/chaintypes/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("./substrate/index.js"), exports);

package/cjs/chaintypes/substrate/consts.js

@@ -0,0 +1,3 @@
+"use strict";
+// Generated by @dedot/codegen
+Object.defineProperty(exports, "__esModule", { value: true });

package/cjs/chaintypes/substrate/errors.js

@@ -0,0 +1,3 @@
+"use strict";
+// Generated by @dedot/codegen
+Object.defineProperty(exports, "__esModule", { value: true });

package/cjs/chaintypes/substrate/events.js

@@ -0,0 +1,3 @@
+"use strict";
+// Generated by @dedot/codegen
+Object.defineProperty(exports, "__esModule", { value: true });

package/cjs/chaintypes/substrate/index.js

@@ -0,0 +1,18 @@
+"use strict";
+// Generated by @dedot/codegen
+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("./types.js"), exports);

package/cjs/chaintypes/substrate/json-rpc.js

@@ -0,0 +1,3 @@
+"use strict";
+// Generated by @dedot/codegen
+Object.defineProperty(exports, "__esModule", { value: true });

package/cjs/chaintypes/substrate/query.js

@@ -0,0 +1,3 @@
+"use strict";
+// Generated by @dedot/codegen
+Object.defineProperty(exports, "__esModule", { value: true });

package/cjs/chaintypes/substrate/runtime.js

@@ -0,0 +1,3 @@
+"use strict";
+// Generated by @dedot/codegen
+Object.defineProperty(exports, "__esModule", { value: true });

package/cjs/chaintypes/substrate/tx.js

@@ -0,0 +1,3 @@
+"use strict";
+// Generated by @dedot/codegen
+Object.defineProperty(exports, "__esModule", { value: true });

package/cjs/chaintypes/substrate/types.js

@@ -0,0 +1,3 @@
+"use strict";
+// Generated by @dedot/codegen
+Object.defineProperty(exports, "__esModule", { value: true });

package/cjs/client/BaseSubstrateClient.js

@@ -0,0 +1,257 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseSubstrateClient = exports.ensurePresence = void 0;
+const codecs_1 = require("@dedot/codecs");
+const storage_1 = require("@dedot/storage");
+const utils_1 = require("@dedot/utils");
+const index_js_1 = require("../executor/index.js");
+const index_js_2 = require("../json-rpc/index.js");
+const proxychain_js_1 = require("../proxychain.js");
+const SUPPORTED_METADATA_VERSIONS = [15, 14];
+const MetadataApiHash = (0, utils_1.calcRuntimeApiHash)('Metadata'); // 0x37e397fc7c91f5e4
+const MESSAGE = 'Make sure to call `.connect()` method first before using the API interfaces.';
+function ensurePresence(value) {
+    return (0, utils_1.ensurePresence)(value, MESSAGE);
+}
+exports.ensurePresence = ensurePresence;
+/**
+ * @name BaseSubstrateClient
+ * @description Base & shared abstraction for Substrate API Clients
+ */
+class BaseSubstrateClient extends index_js_2.JsonRpcClient {
+    rpcVersion;
+    _options;
+    _registry;
+    _metadata;
+    _genesisHash;
+    _runtimeVersion;
+    _localCache;
+    constructor(rpcVersion, options) {
+        super(options);
+        this.rpcVersion = rpcVersion;
+        this._options = this.normalizeOptions(options);
+    }
+    /// --- Internal logics
+    normalizeOptions(options) {
+        const defaultOptions = { throwOnUnknownApi: true };
+        if ((0, index_js_2.isJsonRpcProvider)(options)) {
+            return { ...defaultOptions, provider: options };
+        }
+        else {
+            return { ...defaultOptions, ...options };
+        }
+    }
+    async initializeLocalCache() {
+        if (!this._options.cacheMetadata)
+            return;
+        // Initialize local cache
+        if (this._options.cacheStorage) {
+            this._localCache = this._options.cacheStorage;
+            return;
+        }
+        try {
+            this._localCache = new storage_1.LocalStorage();
+        }
+        catch {
+            throw new Error('localStorage is not available for caching, please provide a cacheStorage option');
+        }
+    }
+    async setupMetadata(preloadMetadata) {
+        let metadata = preloadMetadata;
+        let shouldUpdateCache = !!metadata;
+        if (!metadata) {
+            metadata = this.getMetadataFromOptions(this._runtimeVersion);
+        }
+        const metadataKey = this.currentMetadataKey;
+        try {
+            if (this._localCache && this._options.cacheMetadata) {
+                if (!metadata) {
+                    try {
+                        const cachedRawMetadata = await this._localCache.get(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.set(metadataKey, (0, utils_1.u8aToHex)(codecs_1.$Metadata.tryEncode(metadata)));
+        }
+        if (!metadata) {
+            throw new Error('Cannot load metadata');
+        }
+        this.setMetadata(metadata);
+    }
+    setMetadata(metadata) {
+        this._metadata = metadata;
+        this._registry = new codecs_1.PortableRegistry(metadata.latest, this.options.hasher);
+    }
+    getMetadataKey(runtime) {
+        return `RAW_META/${this._genesisHash || '0x'}/${runtime?.specVersion || '---'}`;
+    }
+    get currentMetadataKey() {
+        return this.getMetadataKey(this._runtimeVersion);
+    }
+    async shouldPreloadMetadata() {
+        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/'));
+    }
+    getMetadataFromOptions(runtime) {
+        if (!runtime || !this.options.metadata)
+            return;
+        const key = this.getMetadataKey(runtime);
+        if (this.options.metadata[key]) {
+            return codecs_1.$Metadata.tryDecode(this.options.metadata[key]);
+        }
+    }
+    async fetchMetadata(hash, runtime) {
+        // First try finding metadata from the provided option
+        const optionMetadata = this.getMetadataFromOptions(runtime);
+        if (optionMetadata)
+            return optionMetadata;
+        // If there is no runtime, we assume that the node supports Metadata Api V2
+        const supportedV2 = runtime ? runtime.apis[MetadataApiHash] === 2 : true;
+        if (supportedV2) {
+            // 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.callAt(hash).metadata.metadataAtVersion(version);
+                    if (!rawMetadata)
+                        continue;
+                    return codecs_1.$Metadata.tryDecode(rawMetadata);
+                }
+                catch { }
+            }
+        }
+        try {
+            return codecs_1.$Metadata.tryDecode(await this.callAt(hash).metadata.metadata());
+        }
+        catch {
+            return await this.rpc.state_getMetadata();
+        }
+    }
+    cleanUp() {
+        this._registry = undefined;
+        this._metadata = undefined;
+        this._genesisHash = undefined;
+        this._runtimeVersion = undefined;
+        this._localCache = undefined;
+    }
+    /**
+     * @description Clear local cache
+     */
+    async clearCache() {
+        await this._localCache?.clear();
+    }
+    async doConnect() {
+        this.on('connected', this.onConnected);
+        this.on('disconnected', this.onDisconnected);
+        return new Promise((resolve) => {
+            this.once('ready', () => {
+                resolve(this);
+            });
+        });
+    }
+    onConnected = async () => {
+        await this.initialize();
+    };
+    onDisconnected = async () => { };
+    async initialize() {
+        await this.initializeLocalCache();
+        await this.doInitialize();
+        this.emit('ready');
+    }
+    async doInitialize() {
+        throw new Error('Unimplemented!');
+    }
+    async beforeDisconnect() { }
+    async afterDisconnect() {
+        this.cleanUp();
+    }
+    toSubstrateRuntimeVersion(runtimeVersion) {
+        return {
+            ...runtimeVersion,
+            apis: runtimeVersion.apis.reduce((o, [name, version]) => {
+                o[name] = version;
+                return o;
+            }, {}),
+        };
+    }
+    /// --- Public APIs ---
+    /**
+     * @description Connect to blockchain node
+     */
+    async connect() {
+        const [api, _] = await Promise.all([this.doConnect(), super.connect()]);
+        return api;
+    }
+    /**
+     * @description Disconnect to blockchain node
+     */
+    async disconnect() {
+        await this.beforeDisconnect();
+        await super.disconnect();
+        await this.afterDisconnect();
+    }
+    get options() {
+        return this._options;
+    }
+    get metadata() {
+        return ensurePresence(this._metadata);
+    }
+    get registry() {
+        return ensurePresence(this._registry);
+    }
+    get genesisHash() {
+        return ensurePresence(this._genesisHash);
+    }
+    get runtimeVersion() {
+        return ensurePresence(this._runtimeVersion);
+    }
+    get consts() {
+        return (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.ConstantExecutor(this) });
+    }
+    get errors() {
+        return (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.ErrorExecutor(this) });
+    }
+    get events() {
+        return (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.EventExecutor(this) });
+    }
+    get query() {
+        throw new Error('Unimplemented!');
+    }
+    get call() {
+        return this.callAt();
+    }
+    // For internal use with caution
+    callAt(hash) {
+        throw new Error('Unimplemented!');
+    }
+    get tx() {
+        throw new Error('Unimplemented!');
+    }
+    at(hash) {
+        throw new Error('Unimplemented!');
+    }
+}
+exports.BaseSubstrateClient = BaseSubstrateClient;

package/cjs/client/Dedot.js

@@ -0,0 +1,250 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Dedot = void 0;
+const codecs_1 = require("@dedot/codecs");
+const index_js_1 = require("../executor/index.js");
+const proxychain_js_1 = require("../proxychain.js");
+const BaseSubstrateClient_js_1 = require("./BaseSubstrateClient.js");
+const KEEP_ALIVE_INTERVAL = 10_000; // in ms
+/**
+ * @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 type { 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 extends BaseSubstrateClient_js_1.BaseSubstrateClient {
+    #runtimeSubscriptionUnsub;
+    #healthTimer;
+    #apiAtCache = {};
+    /**
+     * Use factory methods (`create`, `new`) to create `Dedot` instances.
+     *
+     * @param options
+     */
+    constructor(options) {
+        super('legacy', options);
+    }
+    /**
+     * Factory method to create a new Dedot instance
+     *
+     * @param options
+     */
+    static async create(options) {
+        return new Dedot(options).connect();
+    }
+    /**
+     * Alias for __Dedot.create__
+     *
+     * @param options
+     */
+    static async new(options) {
+        return Dedot.create(options);
+    }
+    onDisconnected = async () => {
+        await this.#unsubscribeUpdates();
+    };
+    async beforeDisconnect() {
+        await this.#unsubscribeUpdates();
+    }
+    /**
+     * Initialize APIs before usage
+     */
+    async doInitialize() {
+        let [genesisHash, runtimeVersion, metadata] = await Promise.all([
+            this.rpc.chain_getBlockHash(0),
+            this.#getRuntimeVersion(),
+            (await this.shouldPreloadMetadata()) ? this.fetchMetadata() : Promise.resolve(undefined),
+        ]);
+        this._genesisHash = genesisHash;
+        this._runtimeVersion = runtimeVersion;
+        await this.setupMetadata(metadata);
+        this.#subscribeUpdates();
+    }
+    cleanUp() {
+        super.cleanUp();
+        this.#apiAtCache = {};
+        this.#healthTimer = undefined;
+        this.#runtimeSubscriptionUnsub = undefined;
+    }
+    #subscribeRuntimeUpgrades() {
+        if (this.#runtimeSubscriptionUnsub)
+            return;
+        this.rpc
+            .state_subscribeRuntimeVersion(async (runtimeVersion) => {
+            if (runtimeVersion.specVersion !== this.runtimeVersion?.specVersion) {
+                this._runtimeVersion = this.toSubstrateRuntimeVersion(runtimeVersion);
+                const newMetadata = await this.fetchMetadata(undefined, this._runtimeVersion);
+                await this.setupMetadata(newMetadata);
+            }
+        })
+            .then((unsub) => {
+            this.#runtimeSubscriptionUnsub = unsub;
+        });
+    }
+    async #getRuntimeVersion(at) {
+        return this.toSubstrateRuntimeVersion(await this.rpc.state_getRuntimeVersion(at));
+    }
+    #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();
+    }
+    /// --- Public APIs ---
+    /**
+     * @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_js_1.newProxyChain)({ executor: new index_js_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_js_1.newProxyChain)({ executor: new index_js_1.StorageQueryExecutor(this) });
+    }
+    /**
+     * @description Entry-point for inspecting errors from metadata
+     */
+    get errors() {
+        return (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.ErrorExecutor(this) });
+    }
+    /**
+     * @description Entry-point for inspecting events from metadata
+     */
+    get events() {
+        return (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.EventExecutor(this) });
+    }
+    /**
+     * @description Entry-point for executing runtime api
+     *
+     * ```typescript
+     * // Get account nonce
+     * const nonce = await api.call.accountNonceApi.accountNonce(<address>);
+     *
+     * // Query transaction payment info
+     * const tx = api.tx.balances.transferKeepAlive(<address>, 2_000_000_000_000n);
+     * const queryInfo = await api.call.transactionPaymentApi.queryInfo(tx.toU8a(), tx.length);
+     * ```
+     */
+    get call() {
+        return this.callAt();
+    }
+    // For internal use with caution
+    callAt(hash) {
+        return (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.RuntimeApiExecutor(this, hash) });
+    }
+    /**
+     * @description Entry-point for executing on-chain transactions
+     *
+     * ```typescript
+     * // Make a transfer balance transaction
+     * api.tx.balances.transferKeepAlive(<address>, <amount>)
+     *    .signAndSend(<keyPair|address>, { signer }, ({ status }) => {
+     *      console.log('Transaction status', status.tag);
+     *    });
+     * ```
+     */
+    get tx() {
+        return (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.TxExecutor(this) });
+    }
+    /**
+     * Create a new API instance at a specific block hash
+     * This is useful when we want to inspect the state of the chain at a specific block hash
+     *
+     * @param hash
+     */
+    async at(hash) {
+        if (this.#apiAtCache[hash])
+            return this.#apiAtCache[hash];
+        const targetVersion = await this.#getRuntimeVersion(hash);
+        let metadata = this.metadata;
+        let registry = this.registry;
+        if (targetVersion.specVersion !== this.runtimeVersion.specVersion) {
+            metadata = await this.fetchMetadata(hash, targetVersion);
+            registry = new codecs_1.PortableRegistry(metadata.latest, this.options.hasher);
+        }
+        const api = {
+            rpcVersion: 'legacy',
+            atBlockHash: hash,
+            options: this.options,
+            genesisHash: this.genesisHash,
+            runtimeVersion: targetVersion,
+            metadata,
+            registry,
+            rpc: this.rpc,
+        };
+        api.consts = (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.ConstantExecutor(api) });
+        api.query = (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.StorageQueryExecutor(api) });
+        api.call = (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.RuntimeApiExecutor(api) });
+        api.events = (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.EventExecutor(api) });
+        api.errors = (0, proxychain_js_1.newProxyChain)({ executor: new index_js_1.ErrorExecutor(api) });
+        this.#apiAtCache[hash] = api;
+        return api;
+    }
+}
+exports.Dedot = Dedot;