ethres 6.16.0

package/src.ts/providers/provider-blockscout.ts

@@ -0,0 +1,167 @@
+
+/**
+ *  [[link-blockscout]] provides a third-party service for connecting to
+ *  various blockchains over JSON-RPC.
+ *
+ *  **Supported Networks**
+ *
+ *  - Ethereum Mainnet (``mainnet``)
+ *  - Sepolia Testnet (``sepolia``)
+ *  - Holesky Testnet (``holesky``)
+ *  - Ethereum Classic (``classic``)
+ *  - Arbitrum (``arbitrum``)
+ *  - Base (``base``)
+ *  - Base Sepolia Testnet (``base-sepolia``)
+ *  - Gnosis (``xdai``)
+ *  - Optimism (``optimism``)
+ *  - Optimism Sepolia Testnet (``optimism-sepolia``)
+ *  - Polygon (``matic``)
+ *
+ *  @_subsection: api/providers/thirdparty:Blockscout  [providers-blockscout]
+ */
+import {
+    assertArgument, defineProperties, FetchRequest, isHexString
+} from "../utils/index.js";
+
+import { Network } from "./network.js";
+import { JsonRpcProvider } from "./provider-jsonrpc.js";
+
+import type { AbstractProvider, PerformActionRequest } from "./abstract-provider.js";
+import type { CommunityResourcable } from "./community.js";
+import type { Networkish } from "./network.js";
+import type { JsonRpcPayload, JsonRpcError } from "./provider-jsonrpc.js";
+
+
+function getUrl(name: string): string {
+    switch(name) {
+        case "mainnet":
+            return "https:/\/eth.blockscout.com/api/eth-rpc";
+        case "sepolia":
+            return "https:/\/eth-sepolia.blockscout.com/api/eth-rpc";
+        case "holesky":
+            return "https:/\/eth-holesky.blockscout.com/api/eth-rpc";
+
+        case "classic":
+            return "https:/\/etc.blockscout.com/api/eth-rpc";
+
+        case "arbitrum":
+            return "https:/\/arbitrum.blockscout.com/api/eth-rpc";
+
+        case "base":
+            return "https:/\/base.blockscout.com/api/eth-rpc";
+        case "base-sepolia":
+            return "https:/\/base-sepolia.blockscout.com/api/eth-rpc";
+
+        case "matic":
+            return "https:/\/polygon.blockscout.com/api/eth-rpc";
+
+        case "optimism":
+            return "https:/\/optimism.blockscout.com/api/eth-rpc";
+        case "optimism-sepolia":
+            return "https:/\/optimism-sepolia.blockscout.com/api/eth-rpc";
+
+        case "xdai":
+            return "https:/\/gnosis.blockscout.com/api/eth-rpc";
+    }
+
+    assertArgument(false, "unsupported network", "network", name);
+}
+
+
+/**
+ *  The **BlockscoutProvider** connects to the [[link-blockscout]]
+ *  JSON-RPC end-points.
+ *
+ *  By default, a highly-throttled API key is used, which is
+ *  appropriate for quick prototypes and simple scripts. To
+ *  gain access to an increased rate-limit, it is highly
+ *  recommended to [sign up here](link-blockscout).
+ */
+export class BlockscoutProvider extends JsonRpcProvider implements CommunityResourcable {
+    /**
+     *  The API key.
+     */
+    readonly apiKey!: null | string;
+
+    /**
+     *  Creates a new **BlockscoutProvider**.
+     */
+    constructor(_network?: Networkish, apiKey?: null | string) {
+        if (_network == null) { _network = "mainnet"; }
+        const network = Network.from(_network);
+
+        if (apiKey == null) { apiKey = null; }
+
+        const request = BlockscoutProvider.getRequest(network);
+        super(request, network, { staticNetwork: network });
+
+        defineProperties<BlockscoutProvider>(this, { apiKey });
+    }
+
+    _getProvider(chainId: number): AbstractProvider {
+        try {
+            return new BlockscoutProvider(chainId, this.apiKey);
+        } catch (error) { }
+        return super._getProvider(chainId);
+    }
+
+    isCommunityResource(): boolean {
+        return (this.apiKey === null);
+    }
+
+    getRpcRequest(req: PerformActionRequest): null | { method: string, args: Array<any> } {
+        // Blockscout enforces the TAG argument for estimateGas
+        const resp = super.getRpcRequest(req);
+        if (resp && resp.method === "eth_estimateGas" && resp.args.length == 1) {
+            resp.args = resp.args.slice();
+            resp.args.push("latest");
+        }
+        return resp;
+    }
+
+    getRpcError(payload: JsonRpcPayload, _error: JsonRpcError): Error {
+        const error = _error ? _error.error: null;
+
+        // Blockscout currently drops the VM result and replaces it with a
+        // human-readable string, so we need to make it machine-readable.
+        if (error && error.code === -32015 && !isHexString(error.data || "", true)) {
+            const panicCodes = <Record<string, string>>{
+                "assert(false)": "01",
+                "arithmetic underflow or overflow": "11",
+                "division or modulo by zero": "12",
+                "out-of-bounds array access; popping on an empty array": "31",
+                "out-of-bounds access of an array or bytesN": "32"
+            };
+
+            let panicCode = "";
+            if (error.message === "VM execution error.") {
+                // eth_call passes this message
+                panicCode = panicCodes[error.data] || "";
+            } else if (panicCodes[error.message || ""]) {
+                panicCode = panicCodes[error.message || ""];
+            }
+
+            if (panicCode) {
+                error.message += ` (reverted: ${ error.data })`;
+                error.data = "0x4e487b7100000000000000000000000000000000000000000000000000000000000000" + panicCode;
+            }
+
+        } else if (error && error.code === -32000) {
+            if (error.message === "wrong transaction nonce") {
+                error.message += " (nonce too low)";
+            }
+        }
+
+        return super.getRpcError(payload, _error);
+    }
+
+    /**
+     *  Returns a prepared request for connecting to %%network%%
+     *  with %%apiKey%%.
+     */
+    static getRequest(network: Network): FetchRequest {
+        const request = new FetchRequest(getUrl(network.name));
+        request.allowGzip = true;
+        return request;
+    }
+}

package/src.ts/providers/provider-browser.ts

@@ -0,0 +1,334 @@
+
+import { assertArgument, makeError } from "../utils/index.js";
+
+import { JsonRpcApiPollingProvider } from "./provider-jsonrpc.js";
+
+import type {
+    JsonRpcApiProviderOptions,
+    JsonRpcError, JsonRpcPayload, JsonRpcResult,
+    JsonRpcSigner
+} from "./provider-jsonrpc.js";
+import type { Network, Networkish } from "./network.js";
+
+/**
+ *  The interface to an [[link-eip-1193]] provider, which is a standard
+ *  used by most injected providers, which the [[BrowserProvider]] accepts
+ *  and exposes the API of.
+ */
+export interface Eip1193Provider {
+    /**
+     *  See [[link-eip-1193]] for details on this method.
+     */
+    request(request: { method: string, params?: Array<any> | Record<string, any> }): Promise<any>;
+};
+
+/**
+ *  The possible additional events dispatched when using the ``"debug"``
+ *  event on a [[BrowserProvider]].
+ */
+export type DebugEventBrowserProvider = {
+    action: "sendEip1193Payload",
+    payload: { method: string, params: Array<any> }
+} | {
+    action: "receiveEip1193Result",
+    result: any
+} | {
+    action: "receiveEip1193Error",
+    error: Error
+};
+
+/**
+ *  Provider info provided by the [[link-eip-6963]] discovery mechanism.
+ */
+export interface Eip6963ProviderInfo {
+    uuid: string;
+    name: string;
+    icon: string;
+    rdns: string;
+}
+
+interface Eip6963ProviderDetail {
+    info: Eip6963ProviderInfo;
+    provider: Eip1193Provider;
+}
+
+interface Eip6963Announcement {
+    type: "eip6963:announceProvider";
+    detail: Eip6963ProviderDetail
+}
+
+export type BrowserProviderOptions = {
+    polling?: boolean;
+    staticNetwork?: null | boolean | Network;
+
+    cacheTimeout?: number;
+    pollingInterval?: number;
+
+    providerInfo?: Eip6963ProviderInfo;
+};
+
+/**
+ *  Specifies how [[link-eip-6963]] discovery should proceed.
+ *
+ *  See: [[BrowserProvider-discover]]
+ */
+export interface BrowserDiscoverOptions {
+    /**
+     *  Override provider detection with this provider.
+     */
+    provider?: Eip1193Provider;
+
+    /**
+     *  Duration to wait to detect providers. (default: 300ms)
+     */
+    timeout?: number;
+
+    /**
+     *  Return the first detected provider. Otherwise wait for %%timeout%%
+     *  and allowing filtering before selecting the desired provider.
+     */
+    anyProvider?: boolean;
+
+    /**
+     *  Use the provided window context. Useful in non-standard
+     *  environments or to hijack where a provider comes from.
+     */
+    window?: any;
+
+    /**
+     *  Explicitly choose which provider to used once scanning is complete.
+     */
+    filter?: (found: Array<Eip6963ProviderInfo>) => null | BrowserProvider |
+      Eip6963ProviderInfo;
+}
+
+
+/**
+ *  A **BrowserProvider** is intended to wrap an injected provider which
+ *  adheres to the [[link-eip-1193]] standard, which most (if not all)
+ *  currently do.
+ */
+export class BrowserProvider extends JsonRpcApiPollingProvider {
+    #request: (method: string, params: Array<any> | Record<string, any>) => Promise<any>;
+
+    #providerInfo: null | Eip6963ProviderInfo;
+
+    /**
+     *  Connect to the %%ethereum%% provider, optionally forcing the
+     *  %%network%%.
+     */
+    constructor(ethereum: Eip1193Provider, network?: Networkish, _options?: BrowserProviderOptions) {
+
+        // Copy the options
+        const options: JsonRpcApiProviderOptions = Object.assign({ },
+          ((_options != null) ? _options: { }),
+          { batchMaxCount: 1 });
+
+        assertArgument(ethereum && ethereum.request, "invalid EIP-1193 provider", "ethereum", ethereum);
+
+        super(network, options);
+
+        this.#providerInfo = null;
+        if (_options && _options.providerInfo) {
+            this.#providerInfo = _options.providerInfo;
+        }
+
+        this.#request = async (method: string, params: Array<any> | Record<string, any>) => {
+            const payload = { method, params };
+            this.emit("debug", { action: "sendEip1193Request", payload });
+            try {
+                const result = await ethereum.request(payload);
+                this.emit("debug", { action: "receiveEip1193Result", result });
+                return result;
+            } catch (e: any) {
+                const error = new Error(e.message);
+                (<any>error).code = e.code;
+                (<any>error).data = e.data;
+                (<any>error).payload = payload;
+                this.emit("debug", { action: "receiveEip1193Error", error });
+                throw error;
+            }
+        };
+    }
+
+    get providerInfo(): null | Eip6963ProviderInfo {
+        return this.#providerInfo;
+    }
+
+    async send(method: string, params: Array<any> | Record<string, any>): Promise<any> {
+        await this._start();
+
+        return await super.send(method, params);
+    }
+
+    async _send(payload: JsonRpcPayload | Array<JsonRpcPayload>): Promise<Array<JsonRpcResult | JsonRpcError>> {
+        assertArgument(!Array.isArray(payload), "EIP-1193 does not support batch request", "payload", payload);
+
+        try {
+            const result = await this.#request(payload.method, payload.params || [ ]);
+            return [ { id: payload.id, result } ];
+        } catch (e: any) {
+            return [ {
+                id: payload.id,
+                error: { code: e.code, data: e.data, message: e.message }
+            } ];
+        }
+    }
+
+    getRpcError(payload: JsonRpcPayload, error: JsonRpcError): Error {
+
+        error = JSON.parse(JSON.stringify(error));
+
+        // EIP-1193 gives us some machine-readable error codes, so rewrite
+        // them into Ethers standard errors.
+        switch (error.error.code || -1) {
+            case 4001:
+                error.error.message = `ethers-user-denied: ${ error.error.message }`;
+                break;
+            case 4200:
+                error.error.message = `ethers-unsupported: ${ error.error.message }`;
+                break;
+        }
+
+        return super.getRpcError(payload, error);
+    }
+
+    /**
+     *  Resolves to ``true`` if the provider manages the %%address%%.
+     */
+    async hasSigner(address: number | string): Promise<boolean> {
+        if (address == null) { address = 0; }
+
+        const accounts = await this.send("eth_accounts", [ ]);
+        if (typeof(address) === "number") {
+            return (accounts.length > address);
+        }
+
+        address = address.toLowerCase();
+        return accounts.filter((a: string) => (a.toLowerCase() === address)).length !== 0;
+    }
+
+    async getSigner(address?: number | string): Promise<JsonRpcSigner> {
+        if (address == null) { address = 0; }
+
+        if (!(await this.hasSigner(address))) {
+            try {
+                await this.#request("eth_requestAccounts", [ ]);
+
+            } catch (error: any) {
+                const payload = error.payload;
+                throw this.getRpcError(payload, { id: payload.id, error });
+            }
+        }
+
+        return await super.getSigner(address);
+    }
+
+    /**
+     *  Discover and connect to a Provider in the Browser using the
+     *  [[link-eip-6963]] discovery mechanism. If no providers are
+     *  present, ``null`` is resolved.
+     */
+    static async discover(options?: BrowserDiscoverOptions): Promise<null | BrowserProvider> {
+        if (options == null) { options = { }; }
+
+        if (options.provider) {
+            return new BrowserProvider(options.provider);
+        }
+
+        const context = options.window ? options.window:
+            (typeof(window) !== "undefined") ? window: null;
+
+        if (context == null) { return null; }
+
+        const anyProvider = options.anyProvider;
+        if (anyProvider && context.ethereum) {
+            return new BrowserProvider(context.ethereum);
+        }
+
+        if (!("addEventListener" in context && "dispatchEvent" in context
+          && "removeEventListener" in context)) {
+            return null;
+        }
+
+        const timeout = options.timeout ? options.timeout: 300;
+        if (timeout === 0) { return null; }
+
+        return await (new Promise((resolve, reject) => {
+            let found: Array<Eip6963ProviderDetail> = [ ];
+
+            const addProvider = (event: Eip6963Announcement) => {
+                found.push(event.detail);
+                if (anyProvider) { finalize(); }
+            };
+
+            const finalize = () => {
+                clearTimeout(timer);
+
+                if (found.length) {
+
+                    // If filtering is provided:
+                    if (options && options.filter) {
+
+                        // Call filter, with a copies of found provider infos
+                        const filtered = options.filter(found.map(i =>
+                          Object.assign({ }, (i.info))));
+
+                        if (filtered == null) {
+                            // No provider selected
+                            resolve(null);
+
+                        } else if (filtered instanceof BrowserProvider) {
+                            // Custom provider created
+                            resolve(filtered);
+
+                        } else {
+                            // Find the matching provider
+                            let match: null | Eip6963ProviderDetail = null;
+                            if (filtered.uuid) {
+                                const matches = found.filter(f =>
+                                  (filtered.uuid === f.info.uuid));
+                                // @TODO: What should happen if multiple values
+                                //        for the same UUID?
+                                match = matches[0];
+                            }
+
+                            if (match) {
+                                const { provider, info } = match;
+                                resolve(new BrowserProvider(provider, undefined, {
+                                    providerInfo: info
+                                }));
+                            } else {
+                                reject(makeError("filter returned unknown info", "UNSUPPORTED_OPERATION", {
+                                    value: filtered
+                                }));
+                            }
+                        }
+
+                    } else {
+
+                        // Pick the first found provider
+                        const { provider, info } = found[0];
+                        resolve(new BrowserProvider(provider, undefined, {
+                            providerInfo: info
+                        }));
+                    }
+
+                } else {
+                    // Nothing found
+                    resolve(null);
+                }
+
+                context.removeEventListener(<any>"eip6963:announceProvider",
+                  addProvider);
+            };
+
+            const timer = setTimeout(() => { finalize(); }, timeout);
+
+            context.addEventListener(<any>"eip6963:announceProvider",
+              addProvider);
+
+            context.dispatchEvent(new Event("eip6963:requestProvider"));
+        }));
+    }
+}

package/src.ts/providers/provider-chainstack.ts

@@ -0,0 +1,113 @@
+/**
+ *  [[link-chainstack]] provides a third-party service for connecting to
+ *  various blockchains over JSON-RPC.
+ *
+ *  **Supported Networks**
+ *
+ *  - Ethereum Mainnet (``mainnet``)
+ *  - Arbitrum (``arbitrum``)
+ *  - BNB Smart Chain Mainnet (``bnb``)
+ *  - Polygon (``matic``)
+ *
+ *  @_subsection: api/providers/thirdparty:Chainstack  [providers-chainstack]
+ */
+import {
+    defineProperties, FetchRequest, assertArgument
+} from "../utils/index.js";
+
+import { showThrottleMessage } from "./community.js";
+import { Network } from "./network.js";
+import { JsonRpcProvider } from "./provider-jsonrpc.js";
+
+import type { AbstractProvider } from "./abstract-provider.js";
+import type { CommunityResourcable } from "./community.js";
+import type { Networkish } from "./network.js";
+
+
+function getApiKey(name: string): string {
+    switch (name) {
+        case "mainnet": return "39f1d67cedf8b7831010a665328c9197";
+        case "arbitrum": return "0550c209db33c3abf4cc927e1e18cea1"
+        case "bnb": return "98b5a77e531614387366f6fc5da097f8";
+        case "matic": return "cd9d4d70377471aa7c142ec4a4205249";
+    }
+
+    assertArgument(false, "unsupported network", "network", name);
+}
+
+function getHost(name: string): string {
+    switch(name) {
+        case "mainnet":
+            return "ethereum-mainnet.core.chainstack.com";
+        case "arbitrum":
+            return "arbitrum-mainnet.core.chainstack.com";
+        case "bnb":
+            return "bsc-mainnet.core.chainstack.com";
+        case "matic":
+            return "polygon-mainnet.core.chainstack.com";
+    }
+
+    assertArgument(false, "unsupported network", "network", name);
+}
+
+/**
+ *  The **ChainstackProvider** connects to the [[link-chainstack]]
+ *  JSON-RPC end-points.
+ *
+ *  By default, a highly-throttled API key is used, which is
+ *  appropriate for quick prototypes and simple scripts. To
+ *  gain access to an increased rate-limit, it is highly
+ *  recommended to [sign up here](link-chainstack).
+ */
+export class ChainstackProvider extends JsonRpcProvider implements CommunityResourcable {
+    /**
+     *  The API key for the Chainstack connection.
+     */
+    readonly apiKey!: string;
+
+    /**
+     *  Creates a new **ChainstackProvider**.
+     */
+    constructor(_network?: Networkish, apiKey?: null | string) {
+        if (_network == null) { _network = "mainnet"; }
+        const network = Network.from(_network);
+
+        if (apiKey == null) { apiKey = getApiKey(network.name); }
+
+        const request = ChainstackProvider.getRequest(network, apiKey);
+        super(request, network, { staticNetwork: network });
+
+        defineProperties<ChainstackProvider>(this, { apiKey });
+    }
+
+    _getProvider(chainId: number): AbstractProvider {
+        try {
+            return new ChainstackProvider(chainId, this.apiKey);
+        } catch (error) { }
+        return super._getProvider(chainId);
+    }
+
+    isCommunityResource(): boolean {
+        return (this.apiKey === getApiKey(this._network.name));
+    }
+
+    /**
+     *  Returns a prepared request for connecting to %%network%%
+     *  with %%apiKey%% and %%projectSecret%%.
+     */
+    static getRequest(network: Network, apiKey?: null | string): FetchRequest {
+        if (apiKey == null) { apiKey = getApiKey(network.name); }
+
+        const request = new FetchRequest(`https:/\/${ getHost(network.name) }/${ apiKey }`);
+        request.allowGzip = true;
+
+        if (apiKey === getApiKey(network.name)) {
+            request.retryFunc = async (request, response, attempt) => {
+                showThrottleMessage("ChainstackProvider");
+                return true;
+            };
+        }
+
+        return request;
+    }
+}

package/src.ts/providers/provider-cloudflare.ts

@@ -0,0 +1,24 @@
+/**
+ *  About Cloudflare
+ *
+ *  @_subsection: api/providers/thirdparty:Cloudflare  [providers-cloudflare]
+ */
+
+import { assertArgument } from "../utils/index.js";
+
+import { Network } from "./network.js";
+import { JsonRpcProvider } from "./provider-jsonrpc.js";
+
+import type { Networkish } from "./network.js";
+
+/**
+ *  About Cloudflare...
+ */
+export class CloudflareProvider extends JsonRpcProvider {
+    constructor(_network?: Networkish) {
+        if (_network == null) { _network = "mainnet"; }
+        const network = Network.from(_network);
+        assertArgument(network.name === "mainnet", "unsupported network", "network", _network);
+        super("https:/\/cloudflare-eth.com/", network, { staticNetwork: network });
+    }
+}