eteres 0.0.1-security → 6.7.1

package/src.ts/providers/abstract-signer.ts

@@ -0,0 +1,288 @@
+/**
+ *  Generally the [[Wallet]] and [[JsonRpcSigner]] and their sub-classes
+ *  are sufficent for most developers, but this is provided to
+ *  fascilitate more complex Signers.
+ *
+ *  @_section: api/providers/abstract-signer: Subclassing Signer [abstract-signer]
+ */
+import { resolveAddress } from "../address/index.js";
+import { Transaction } from "../transaction/index.js";
+import {
+    defineProperties, getBigInt, resolveProperties,
+    assert, assertArgument
+} from "../utils/index.js";
+
+import { copyRequest } from "./provider.js";
+
+import type { TypedDataDomain, TypedDataField } from "../hash/index.js";
+import type { TransactionLike } from "../transaction/index.js";
+
+import type {
+    BlockTag, Provider, TransactionRequest, TransactionResponse
+} from "./provider.js";
+import type { Signer } from "./signer.js";
+
+
+function checkProvider(signer: AbstractSigner, operation: string): Provider {
+    if (signer.provider) { return signer.provider; }
+    assert(false, "missing provider", "UNSUPPORTED_OPERATION", { operation });
+}
+
+async function populate(signer: AbstractSigner, tx: TransactionRequest): Promise<TransactionLike<string>> {
+    let pop: any = copyRequest(tx);
+
+    if (pop.to != null) { pop.to = resolveAddress(pop.to, signer); }
+
+    if (pop.from != null) {
+        const from = pop.from;
+        pop.from = Promise.all([
+            signer.getAddress(),
+            resolveAddress(from, signer)
+        ]).then(([ address, from ]) => {
+            assertArgument(address.toLowerCase() === from.toLowerCase(),
+                "transaction from mismatch", "tx.from", from);
+            return address;
+        });
+    } else {
+        pop.from = signer.getAddress();
+    }
+
+    return await resolveProperties(pop);
+}
+
+
+/**
+ *  An **AbstractSigner** includes most of teh functionality required
+ *  to get a [[Signer]] working as expected, but requires a few
+ *  Signer-specific methods be overridden.
+ *
+ */
+export abstract class AbstractSigner<P extends null | Provider = null | Provider> implements Signer {
+    /**
+     *  The provider this signer is connected to.
+     */
+    readonly provider!: P;
+
+    /**
+     *  Creates a new Signer connected to %%provider%%.
+     */
+    constructor(provider?: P) {
+        defineProperties<AbstractSigner>(this, { provider: (provider || null) });
+    }
+
+    /**
+     *  Resolves to the Signer address.
+     */
+    abstract getAddress(): Promise<string>;
+
+    /**
+     *  Returns the signer connected to %%provider%%.
+     *
+     *  This may throw, for example, a Signer connected over a Socket or
+     *  to a specific instance of a node may not be transferrable.
+     */
+    abstract connect(provider: null | Provider): Signer;
+
+    async getNonce(blockTag?: BlockTag): Promise<number> {
+        return checkProvider(this, "getTransactionCount").getTransactionCount(await this.getAddress(), blockTag);
+    }
+
+    async populateCall(tx: TransactionRequest): Promise<TransactionLike<string>> {
+        const pop = await populate(this, tx);
+        return pop;
+    }
+
+    async populateTransaction(tx: TransactionRequest): Promise<TransactionLike<string>> {
+        const provider = checkProvider(this, "populateTransaction");
+
+        const pop = await populate(this, tx);
+
+        if (pop.nonce == null) {
+            pop.nonce = await this.getNonce("pending");
+        }
+
+        if (pop.gasLimit == null) {
+            pop.gasLimit = await this.estimateGas(pop);
+        }
+
+        // Populate the chain ID
+        const network = await (<Provider>(this.provider)).getNetwork();
+        if (pop.chainId != null) {
+            const chainId = getBigInt(pop.chainId);
+            assertArgument(chainId === network.chainId, "transaction chainId mismatch", "tx.chainId", tx.chainId);
+        } else {
+            pop.chainId = network.chainId;
+        }
+
+        // Do not allow mixing pre-eip-1559 and eip-1559 properties
+        const hasEip1559 = (pop.maxFeePerGas != null || pop.maxPriorityFeePerGas != null);
+        if (pop.gasPrice != null && (pop.type === 2 || hasEip1559)) {
+            assertArgument(false, "eip-1559 transaction do not support gasPrice", "tx", tx);
+        } else if ((pop.type === 0 || pop.type === 1) && hasEip1559) {
+            assertArgument(false, "pre-eip-1559 transaction do not support maxFeePerGas/maxPriorityFeePerGas", "tx", tx);
+        }
+
+        if ((pop.type === 2 || pop.type == null) && (pop.maxFeePerGas != null && pop.maxPriorityFeePerGas != null)) {
+            // Fully-formed EIP-1559 transaction (skip getFeeData)
+            pop.type = 2;
+
+        } else if (pop.type === 0 || pop.type === 1) {
+            // Explicit Legacy or EIP-2930 transaction
+
+            // We need to get fee data to determine things
+            const feeData = await provider.getFeeData();
+
+            assert(feeData.gasPrice != null, "network does not support gasPrice", "UNSUPPORTED_OPERATION", {
+                operation: "getGasPrice" });
+
+            // Populate missing gasPrice
+            if (pop.gasPrice == null) { pop.gasPrice = feeData.gasPrice; }
+
+        } else {
+
+            // We need to get fee data to determine things
+            const feeData = await provider.getFeeData();
+
+            if (pop.type == null) {
+                // We need to auto-detect the intended type of this transaction...
+
+                if (feeData.maxFeePerGas != null && feeData.maxPriorityFeePerGas != null) {
+                    // The network supports EIP-1559!
+
+                    // Upgrade transaction from null to eip-1559
+                    pop.type = 2;
+
+                    if (pop.gasPrice != null) {
+                        // Using legacy gasPrice property on an eip-1559 network,
+                        // so use gasPrice as both fee properties
+                        const gasPrice = pop.gasPrice;
+                        delete pop.gasPrice;
+                        pop.maxFeePerGas = gasPrice;
+                        pop.maxPriorityFeePerGas = gasPrice;
+
+                    } else {
+                        // Populate missing fee data
+
+                        if (pop.maxFeePerGas == null) {
+                            pop.maxFeePerGas = feeData.maxFeePerGas;
+                        }
+
+                        if (pop.maxPriorityFeePerGas == null) {
+                            pop.maxPriorityFeePerGas = feeData.maxPriorityFeePerGas;
+                        }
+                    }
+
+                } else if (feeData.gasPrice != null) {
+                    // Network doesn't support EIP-1559...
+
+                    // ...but they are trying to use EIP-1559 properties
+                    assert(!hasEip1559, "network does not support EIP-1559", "UNSUPPORTED_OPERATION", {
+                            operation: "populateTransaction" });
+
+                    // Populate missing fee data
+                    if (pop.gasPrice == null) {
+                        pop.gasPrice = feeData.gasPrice;
+                    }
+
+                    // Explicitly set untyped transaction to legacy
+                    // @TODO: Maybe this shold allow type 1?
+                    pop.type = 0;
+
+               } else {
+                    // getFeeData has failed us.
+                    assert(false, "failed to get consistent fee data", "UNSUPPORTED_OPERATION", {
+                        operation: "signer.getFeeData" });
+                }
+
+            } else if (pop.type === 2) {
+                // Explicitly using EIP-1559
+
+                // Populate missing fee data
+                if (pop.maxFeePerGas == null) {
+                    pop.maxFeePerGas = feeData.maxFeePerGas;
+                }
+
+                if (pop.maxPriorityFeePerGas == null) {
+                    pop.maxPriorityFeePerGas = feeData.maxPriorityFeePerGas;
+                }
+            }
+        }
+
+//@TOOD: Don't await all over the place; save them up for
+// the end for better batching
+        return await resolveProperties(pop);
+    }
+
+    async estimateGas(tx: TransactionRequest): Promise<bigint> {
+        return checkProvider(this, "estimateGas").estimateGas(await this.populateCall(tx));
+    }
+
+    async call(tx: TransactionRequest): Promise<string> {
+        return checkProvider(this, "call").call(await this.populateCall(tx));
+    }
+
+    async resolveName(name: string): Promise<null | string> {
+        const provider = checkProvider(this, "resolveName");
+        return await provider.resolveName(name);
+    }
+
+    async sendTransaction(tx: TransactionRequest): Promise<TransactionResponse> {
+        const provider = checkProvider(this, "sendTransaction");
+
+        const pop = await this.populateTransaction(tx);
+        delete pop.from;
+        const txObj = Transaction.from(pop);
+        return await provider.broadcastTransaction(await this.signTransaction(txObj));
+    }
+
+    abstract signTransaction(tx: TransactionRequest): Promise<string>;
+    abstract signMessage(message: string | Uint8Array): Promise<string>;
+    abstract signTypedData(domain: TypedDataDomain, types: Record<string, Array<TypedDataField>>, value: Record<string, any>): Promise<string>;
+}
+
+/**
+ *  A **VoidSigner** is a class deisgned to allow an address to be used
+ *  in any API which accepts a Signer, but for which there are no
+ *  credentials available to perform any actual signing.
+ *
+ *  This for example allow impersonating an account for the purpose of
+ *  static calls or estimating gas, but does not allow sending transactions.
+ */
+export class VoidSigner extends AbstractSigner {
+    /**
+     *  The signer address.
+     */
+    readonly address!: string;
+
+    /**
+     *  Creates a new **VoidSigner** with %%address%% attached to
+     *  %%provider%%.
+     */
+    constructor(address: string, provider?: null | Provider) {
+        super(provider);
+        defineProperties<VoidSigner>(this, { address });
+    }
+
+    async getAddress(): Promise<string> { return this.address; }
+
+    connect(provider: null | Provider): VoidSigner {
+        return new VoidSigner(this.address, provider);
+    }
+
+    #throwUnsupported(suffix: string, operation: string): never {
+        assert(false, `VoidSigner cannot sign ${ suffix }`, "UNSUPPORTED_OPERATION", { operation });
+    }
+
+    async signTransaction(tx: TransactionRequest): Promise<string> {
+        this.#throwUnsupported("transactions", "signTransaction");
+    }
+
+    async signMessage(message: string | Uint8Array): Promise<string> {
+        this.#throwUnsupported("messages", "signMessage");
+    }
+
+    async signTypedData(domain: TypedDataDomain, types: Record<string, Array<TypedDataField>>, value: Record<string, any>): Promise<string> {
+        this.#throwUnsupported("typed-data", "signTypedData");
+    }
+}
+

package/src.ts/providers/community.ts

@@ -0,0 +1,49 @@
+/**
+ *  There are many awesome community services that provide Ethereum
+ *  nodes both for developers just starting out and for large-scale
+ *  communities.
+ *
+ *  @_section: api/providers/thirdparty: Community Providers  [thirdparty]
+ */
+
+/**
+ *  Providers which offer community credentials should extend this
+ *  to notify any interested consumers whether community credentials
+ *  are in-use.
+ */
+export interface CommunityResourcable {
+    /**
+     *  Returns true of the instance is connected using the community
+     *  credentials.
+     */
+    isCommunityResource(): boolean;
+}
+
+// Show the throttle message only once per service
+const shown: Set<string> = new Set();
+
+/**
+ *  Displays a warning in tht console when the community resource is
+ *  being used too heavily by the app, recommending the developer
+ *  acquire their own credentials instead of using the community
+ *  credentials.
+ *
+ *  The notification will only occur once per service.
+ */
+export function showThrottleMessage(service: string): void {
+    if (shown.has(service)) { return; }
+    shown.add(service);
+
+    console.log("========= NOTICE =========")
+    console.log(`Request-Rate Exceeded for ${ service } (this message will not be repeated)`);
+    console.log("");
+    console.log("The default API keys for each service are provided as a highly-throttled,");
+    console.log("community resource for low-traffic projects and early prototyping.");
+    console.log("");
+    console.log("While your application will continue to function, we highly recommended");
+    console.log("signing up for your own API keys to improve performance, increase your");
+    console.log("request rate/limit and enable other perks, such as metrics and advanced APIs.");
+    console.log("");
+    console.log("For more details: https:/\/docs.ethers.org/api-keys/");
+    console.log("==========================");
+}

package/src.ts/providers/contracts.ts

@@ -0,0 +1,42 @@
+import type {
+    Provider, TransactionRequest, TransactionResponse
+} from "./provider.js";
+
+/**
+ *  A **ContractRunner** is a generic interface which defines an object
+ *  capable of interacting with a Contract on the network.
+ *
+ *  The more operations supported, the more utility it is capable of.
+ *
+ *  The most common ContractRunners are [Providers](Provider) which enable
+ *  read-only access and [Signers](Signer) which enable write-access.
+ */
+export interface ContractRunner {
+    /**
+     *  The provider used for necessary state querying operations.
+     *
+     *  This can also point to the **ContractRunner** itself, in the
+     *  case of an [[AbstractProvider]].
+     */
+    provider: null | Provider;
+
+    /**
+     *  Required to estimate gas.
+     */
+    estimateGas?: (tx: TransactionRequest) => Promise<bigint>;
+
+    /**
+     * Required for pure, view or static calls to contracts.
+     */
+    call?: (tx: TransactionRequest) => Promise<string>;
+
+    /**
+     *  Required to support ENS names
+     */
+    resolveName?: (name: string) => Promise<null | string>;
+
+    /**
+     *  Required for state mutating calls
+     */
+    sendTransaction?: (tx: TransactionRequest) => Promise<TransactionResponse>;
+}

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

@@ -0,0 +1,142 @@
+
+import { assert } from "../utils/index.js";
+
+import { AnkrProvider } from "./provider-ankr.js";
+import { AlchemyProvider } from "./provider-alchemy.js";
+import { CloudflareProvider } from "./provider-cloudflare.js";
+import { EtherscanProvider } from "./provider-etherscan.js";
+import { InfuraProvider } from "./provider-infura.js";
+//import { PocketProvider } from "./provider-pocket.js";
+import { QuickNodeProvider } from "./provider-quicknode.js";
+
+import { FallbackProvider } from "./provider-fallback.js";
+import { JsonRpcProvider } from "./provider-jsonrpc.js";
+import { Network } from "./network.js";
+import { WebSocketProvider } from "./provider-websocket.js";
+
+import type { AbstractProvider } from "./abstract-provider.js";
+import type { Networkish } from "./network.js";
+import { WebSocketLike } from "./provider-websocket.js";
+
+function isWebSocketLike(value: any): value is WebSocketLike {
+    return (value && typeof(value.send) === "function" &&
+        typeof(value.close) === "function");
+}
+
+const Testnets = "goerli kovan sepolia classicKotti optimism-goerli arbitrum-goerli matic-mumbai bnbt".split(" ");
+
+export function getDefaultProvider(network: string | Networkish | WebSocketLike, options?: any): AbstractProvider {
+    if (options == null) { options = { }; }
+
+    const allowService = (name: string) => {
+        if (options[name] === "-") { return false; }
+        if (typeof(options.exclusive) === "string") {
+            return (name === options.exclusive);
+        }
+        if (Array.isArray(options.exclusive)) {
+            return (options.exclusive.indexOf(name) !== -1);
+        }
+        return true;
+    };
+
+    if (typeof(network) === "string" && network.match(/^https?:/)) {
+        return new JsonRpcProvider(network);
+    }
+
+    if (typeof(network) === "string" && network.match(/^wss?:/) || isWebSocketLike(network)) {
+        return new WebSocketProvider(network);
+    }
+
+    // Get the network and name, if possible
+    let staticNetwork: null | Network = null;
+    try {
+        staticNetwork = Network.from(network);
+    } catch (error) { }
+
+
+    const providers: Array<AbstractProvider> = [ ];
+
+    if (allowService("publicPolygon") && staticNetwork) {
+        if (staticNetwork.name === "matic") {
+            providers.push(new JsonRpcProvider("https:/\/polygon-rpc.com/", staticNetwork, { staticNetwork }));
+        }
+    }
+
+    if (allowService("alchemy")) {
+        try {
+            providers.push(new AlchemyProvider(network, options.alchemy));
+        } catch (error) { }
+    }
+
+    if (allowService("ankr") && options.ankr != null) {
+        try {
+            providers.push(new AnkrProvider(network, options.ankr));
+        } catch (error) { }
+    }
+
+    if (allowService("cloudflare")) {
+        try {
+            providers.push(new CloudflareProvider(network));
+        } catch (error) { }
+    }
+
+    if (allowService("etherscan")) {
+        try {
+            providers.push(new EtherscanProvider(network, options.etherscan));
+        } catch (error) { }
+    }
+
+    if (allowService("infura")) {
+        try {
+            let projectId = options.infura;
+            let projectSecret: undefined | string = undefined;
+            if (typeof(projectId) === "object") {
+                projectSecret = projectId.projectSecret;
+                projectId = projectId.projectId;
+            }
+            providers.push(new InfuraProvider(network, projectId, projectSecret));
+        } catch (error) { }
+    }
+/*
+    if (options.pocket !== "-") {
+        try {
+            let appId = options.pocket;
+            let secretKey: undefined | string = undefined;
+            let loadBalancer: undefined | boolean = undefined;
+            if (typeof(appId) === "object") {
+                loadBalancer = !!appId.loadBalancer;
+                secretKey = appId.secretKey;
+                appId = appId.appId;
+            }
+            providers.push(new PocketProvider(network, appId, secretKey, loadBalancer));
+        } catch (error) { console.log(error); }
+    }
+*/
+    if (allowService("quicknode")) {
+        try {
+            let token = options.quicknode;
+            providers.push(new QuickNodeProvider(network, token));
+        } catch (error) { }
+    }
+
+    assert(providers.length, "unsupported default network", "UNSUPPORTED_OPERATION", {
+        operation: "getDefaultProvider"
+    });
+
+    // No need for a FallbackProvider
+    if (providers.length === 1) { return providers[0]; }
+
+    // We use the floor because public third-party providers can be unreliable,
+    // so a low number of providers with a large quorum will fail too often
+    let quorum = Math.floor(providers.length / 2);
+    if (quorum > 2) { quorum = 2; }
+
+    // Testnets don't need as strong a security gaurantee and speed is
+    // more useful during testing
+    if (staticNetwork && Testnets.indexOf(staticNetwork.name) !== -1) { quorum = 1; }
+
+    // Provided override qorum takes priority
+    if (options && options.quorum) { quorum = options.quorum; }
+
+    return new FallbackProvider(providers, undefined, { quorum });
+}