eteres 0.0.1-security → 6.7.1

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

@@ -0,0 +1,121 @@
+/**
+ *  [[link-pocket]] provides a third-party service for connecting to
+ *  various blockchains over JSON-RPC.
+ *
+ *  **Supported Networks**
+ *
+ *  - Ethereum Mainnet (``mainnet``)
+ *  - Goerli Testnet (``goerli``)
+ *  - Polygon (``matic``)
+ *  - Arbitrum (``arbitrum``)
+ *
+ *  @_subsection: api/providers/thirdparty:Pocket  [providers-pocket]
+ */
+import {
+    defineProperties, FetchRequest, assertArgument
+} from "../utils/index.js";
+
+import { AbstractProvider } from "./abstract-provider.js";
+import { showThrottleMessage } from "./community.js";
+import { Network } from "./network.js";
+import { JsonRpcProvider } from "./provider-jsonrpc.js";
+
+import type { CommunityResourcable } from "./community.js";
+import type { Networkish } from "./network.js";
+
+const defaultApplicationId = "62e1ad51b37b8e00394bda3b";
+
+function getHost(name: string): string {
+    switch (name) {
+        case "mainnet":
+            return  "eth-mainnet.gateway.pokt.network";
+        case "goerli":
+            return "eth-goerli.gateway.pokt.network";
+
+        case "matic":
+            return "poly-mainnet.gateway.pokt.network";
+        case "matic-mumbai":
+            return "polygon-mumbai-rpc.gateway.pokt.network";
+    }
+
+    assertArgument(false, "unsupported network", "network", name);
+}
+
+
+/**
+ *  The **PocketProvider** connects to the [[link-pocket]]
+ *  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-pocket-signup).
+ */
+export class PocketProvider extends JsonRpcProvider implements CommunityResourcable {
+
+    /**
+     *  The Application ID for the Pocket connection.
+     */
+    readonly applicationId!: string;
+
+    /**
+     *  The Application Secret for making authenticated requests
+     *  to the Pocket connection.
+     */
+    readonly applicationSecret!: null | string;
+
+    /**
+     *  Create a new **PocketProvider**.
+     *
+     *  By default connecting to ``mainnet`` with a highly throttled
+     *  API key.
+     */
+    constructor(_network?: Networkish, applicationId?: null | string, applicationSecret?: null | string) {
+        if (_network == null) { _network = "mainnet"; }
+        const network = Network.from(_network);
+        if (applicationId == null) { applicationId = defaultApplicationId; }
+        if (applicationSecret == null) { applicationSecret = null; }
+
+        const options = { staticNetwork: network };
+
+        const request = PocketProvider.getRequest(network, applicationId, applicationSecret);
+        super(request, network, options);
+
+        defineProperties<PocketProvider>(this, { applicationId, applicationSecret });
+    }
+
+    _getProvider(chainId: number): AbstractProvider {
+        try {
+            return new PocketProvider(chainId, this.applicationId, this.applicationSecret);
+        } catch (error) { }
+        return super._getProvider(chainId);
+    }
+
+    /**
+     *  Returns a prepared request for connecting to %%network%% with
+     *  %%applicationId%%.
+     */
+    static getRequest(network: Network, applicationId?: null | string, applicationSecret?: null | string): FetchRequest {
+        if (applicationId == null) { applicationId = defaultApplicationId; }
+
+        const request = new FetchRequest(`https:/\/${ getHost(network.name) }/v1/lb/${ applicationId }`);
+        request.allowGzip = true;
+
+        if (applicationSecret) {
+            request.setCredentials("", applicationSecret);
+        }
+
+        if (applicationId === defaultApplicationId) {
+            request.retryFunc = async (request, response, attempt) => {
+                showThrottleMessage("PocketProvider");
+                return true;
+            };
+        }
+
+        return request;
+    }
+
+    isCommunityResource(): boolean {
+        return (this.applicationId === defaultApplicationId);
+    }
+}

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

@@ -0,0 +1,121 @@
+/**
+ *  [[link-quicknode]] provides a third-party service for connecting to
+ *  various blockchains over JSON-RPC.
+ *
+ *  **Supported Networks**
+ *
+ *  - Ethereum Mainnet (``mainnet``)
+ *  - Goerli Testnet (``goerli``)
+ *  - Arbitrum (``arbitrum``)
+ *  - Arbitrum Goerli Testnet (``arbitrum-goerli``)
+ *  - Optimism (``optimism``)
+ *  - Optimism Goerli Testnet (``optimism-goerli``)
+ *  - Polygon (``matic``)
+ *  - Polygon Mumbai Testnet (``matic-mumbai``)
+ *
+ *  @_subsection: api/providers/thirdparty:QuickNode  [providers-quicknode]
+ */
+
+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";
+
+
+const defaultToken = "919b412a057b5e9c9b6dce193c5a60242d6efadb";
+
+function getHost(name: string): string {
+    switch(name) {
+        case "mainnet":
+            return "ethers.quiknode.pro";
+        case "goerli":
+            return "ethers.ethereum-goerli.quiknode.pro";
+        //case "sepolia":
+        //    return "sepolia.infura.io";
+
+        case "arbitrum":
+            return "ethers.arbitrum-mainnet.quiknode.pro";
+        case "arbitrum-goerli":
+            return "ethers.arbitrum-goerli.quiknode.pro";
+        case "matic":
+            return "ethers.matic.quiknode.pro";
+        case "matic-mumbai":
+            return "ethers.matic-testnet.quiknode.pro";
+        case "optimism":
+            return "ethers.optimism.quiknode.pro";
+        case "optimism-goerli":
+            return "ethers.optimism-goerli.quiknode.pro";
+    }
+
+    assertArgument(false, "unsupported network", "network", name);
+}
+
+
+/**
+ *  The **QuickNodeProvider** connects to the [[link-quicknode]]
+ *  JSON-RPC end-points.
+ *
+ *  By default, a highly-throttled API token 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-quicknode).
+ */
+export class QuickNodeProvider extends JsonRpcProvider implements CommunityResourcable {
+    /**
+     *  The API token.
+     */
+    readonly token!: string;
+
+    /**
+     *  Creates a new **QuickNodeProvider**.
+     */
+    constructor(_network?: Networkish, token?: null | string) {
+        if (_network == null) { _network = "mainnet"; }
+        const network = Network.from(_network);
+        if (token == null) { token = defaultToken; }
+
+        const request = QuickNodeProvider.getRequest(network, token);
+        super(request, network, { staticNetwork: network });
+
+        defineProperties<QuickNodeProvider>(this, { token });
+    }
+
+    _getProvider(chainId: number): AbstractProvider {
+        try {
+            return new QuickNodeProvider(chainId, this.token);
+        } catch (error) { }
+        return super._getProvider(chainId);
+    }
+
+    isCommunityResource(): boolean {
+        return (this.token === defaultToken);
+    }
+
+    /**
+     *  Returns a new request prepared for %%network%% and the
+     *  %%token%%.
+     */
+    static getRequest(network: Network, token?: null | string): FetchRequest {
+        if (token == null) { token = defaultToken; }
+
+        const request = new FetchRequest(`https:/\/${ getHost(network.name) }/${ token }`);
+        request.allowGzip = true;
+        //if (projectSecret) { request.setCredentials("", projectSecret); }
+
+        if (token === defaultToken) {
+            request.retryFunc = async (request, response, attempt) => {
+                showThrottleMessage("QuickNodeProvider");
+                return true;
+            };
+        }
+
+        return request;
+    }
+}

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

@@ -0,0 +1,334 @@
+/**
+ *  Generic long-lived socket provider.
+ *
+ *  Sub-classing notes
+ *  - a sub-class MUST call the `_start()` method once connected
+ *  - a sub-class MUST override the `_write(string)` method
+ *  - a sub-class MUST call `_processMessage(string)` for each message
+ *
+ *  @_subsection: api/providers/abstract-provider:Socket Providers  [about-socketProvider]
+ */
+
+import { UnmanagedSubscriber } from "./abstract-provider.js";
+import { assert, assertArgument, makeError } from "../utils/index.js";
+import { JsonRpcApiProvider } from "./provider-jsonrpc.js";
+
+import type { Subscriber, Subscription } from "./abstract-provider.js";
+import type { EventFilter } from "./provider.js";
+import type { JsonRpcError, JsonRpcPayload, JsonRpcResult } from "./provider-jsonrpc.js";
+import type { Networkish } from "./network.js";
+
+
+type JsonRpcSubscription = {
+    method: string,
+    params: {
+        result: any,
+        subscription: string
+    }
+};
+
+/**
+ *  A **SocketSubscriber** uses a socket transport to handle events and
+ *  should use [[_emit]] to manage the events.
+ */
+export class SocketSubscriber implements Subscriber {
+    #provider: SocketProvider;
+
+    #filter: string;
+
+    /**
+     *  The filter.
+     */
+    get filter(): Array<any> { return JSON.parse(this.#filter); }
+
+    #filterId: null | Promise<string |number>;
+    #paused: null | boolean;
+
+    #emitPromise: null | Promise<void>;
+
+    /**
+     *  Creates a new **SocketSubscriber** attached to %%provider%% listening
+     *  to %%filter%%.
+     */
+    constructor(provider: SocketProvider, filter: Array<any>) {
+        this.#provider = provider;
+        this.#filter = JSON.stringify(filter);
+        this.#filterId = null;
+        this.#paused = null;
+        this.#emitPromise = null;
+    }
+
+    start(): void {
+        this.#filterId = this.#provider.send("eth_subscribe", this.filter).then((filterId) => {;
+            this.#provider._register(filterId, this);
+            return filterId;
+        });
+    }
+
+    stop(): void {
+        (<Promise<number>>(this.#filterId)).then((filterId) => {
+            this.#provider.send("eth_unsubscribe", [ filterId ]);
+        });
+        this.#filterId = null;
+    }
+
+    // @TODO: pause should trap the current blockNumber, unsub, and on resume use getLogs
+    //        and resume
+    pause(dropWhilePaused?: boolean): void {
+        assert(dropWhilePaused, "preserve logs while paused not supported by SocketSubscriber yet",
+            "UNSUPPORTED_OPERATION", { operation: "pause(false)" });
+        this.#paused = !!dropWhilePaused;
+    }
+
+    resume(): void {
+        this.#paused = null;
+    }
+
+    /**
+     *  @_ignore:
+     */
+    _handleMessage(message: any): void {
+        if (this.#filterId == null) { return; }
+        if (this.#paused === null) {
+            let emitPromise: null | Promise<void> = this.#emitPromise;
+            if (emitPromise == null) {
+                emitPromise = this._emit(this.#provider, message);
+            } else {
+                emitPromise = emitPromise.then(async () => {
+                    await this._emit(this.#provider, message);
+                });
+            }
+            this.#emitPromise = emitPromise.then(() => {
+                if (this.#emitPromise === emitPromise) {
+                    this.#emitPromise = null;
+                }
+            });
+        }
+    }
+
+    /**
+     *  Sub-classes **must** override this to emit the events on the
+     *  provider.
+     */
+    async _emit(provider: SocketProvider, message: any): Promise<void> {
+        throw new Error("sub-classes must implemente this; _emit");
+    }
+}
+
+/**
+ *  A **SocketBlockSubscriber** listens for ``newHeads`` events and emits
+ *  ``"block"`` events.
+ */
+export class SocketBlockSubscriber extends SocketSubscriber {
+    /**
+     *  @_ignore:
+     */
+    constructor(provider: SocketProvider) {
+        super(provider, [ "newHeads" ]);
+    }
+
+    async _emit(provider: SocketProvider, message: any): Promise<void> {
+        provider.emit("block", parseInt(message.number));
+    }
+}
+
+/**
+ *  A **SocketPendingSubscriber** listens for pending transacitons and emits
+ *  ``"pending"`` events.
+ */
+export class SocketPendingSubscriber extends SocketSubscriber {
+
+    /**
+     *  @_ignore:
+     */
+    constructor(provider: SocketProvider) {
+        super(provider, [ "newPendingTransactions" ]);
+    }
+
+    async _emit(provider: SocketProvider, message: any): Promise<void> {
+        provider.emit("pending", message);
+    }
+}
+
+/**
+ *  A **SocketEventSubscriber** listens for event logs.
+ */
+export class SocketEventSubscriber extends SocketSubscriber {
+    #logFilter: string;
+
+    /**
+     *  The filter.
+     */
+    get logFilter(): EventFilter { return JSON.parse(this.#logFilter); }
+
+    /**
+     *  @_ignore:
+     */
+    constructor(provider: SocketProvider, filter: EventFilter) {
+        super(provider, [ "logs", filter ]);
+        this.#logFilter = JSON.stringify(filter);
+    }
+
+    async _emit(provider: SocketProvider, message: any): Promise<void> {
+        provider.emit(this.logFilter, provider._wrapLog(message, provider._network));
+    }
+}
+
+/**
+ *  A **SocketProvider** is backed by a long-lived connection over a
+ *  socket, which can subscribe and receive real-time messages over
+ *  its communication channel.
+ */
+export class SocketProvider extends JsonRpcApiProvider {
+    #callbacks: Map<number, { payload: JsonRpcPayload, resolve: (r: any) => void, reject: (e: Error) => void }>;
+
+    // Maps each filterId to its subscriber
+    #subs: Map<number | string, SocketSubscriber>;
+
+    // If any events come in before a subscriber has finished
+    // registering, queue them
+    #pending: Map<number | string, Array<any>>;
+
+    /**
+     *  Creates a new **SocketProvider** connected to %%network%%.
+     *
+     *  If unspecified, the network will be discovered.
+     */
+    constructor(network?: Networkish) {
+        super(network, { batchMaxCount: 1 });
+        this.#callbacks = new Map();
+        this.#subs = new Map();
+        this.#pending = new Map();
+    }
+
+    // This value is only valid after _start has been called
+    /*
+    get _network(): Network {
+        if (this.#network == null) {
+            throw new Error("this shouldn't happen");
+        }
+        return this.#network.clone();
+    }
+    */
+
+    _getSubscriber(sub: Subscription): Subscriber {
+        switch (sub.type) {
+            case "close":
+                return new UnmanagedSubscriber("close");
+            case "block":
+                return new SocketBlockSubscriber(this);
+            case "pending":
+                return new SocketPendingSubscriber(this);
+            case "event":
+                return new SocketEventSubscriber(this, sub.filter);
+            case "orphan":
+                // Handled auto-matically within AbstractProvider
+                // when the log.removed = true
+                if (sub.filter.orphan === "drop-log") {
+                    return new UnmanagedSubscriber("drop-log");
+                }
+        }
+        return super._getSubscriber(sub);
+    }
+
+    /**
+     *  Register a new subscriber. This is used internalled by Subscribers
+     *  and generally is unecessary unless extending capabilities.
+     */
+    _register(filterId: number | string, subscriber: SocketSubscriber): void {
+        this.#subs.set(filterId, subscriber);
+        const pending = this.#pending.get(filterId);
+        if (pending) {
+            for (const message of pending) {
+                subscriber._handleMessage(message);
+            }
+            this.#pending.delete(filterId);
+        }
+    }
+
+    async _send(payload: JsonRpcPayload | Array<JsonRpcPayload>): Promise<Array<JsonRpcResult | JsonRpcError>> {
+        // WebSocket provider doesn't accept batches
+        assertArgument(!Array.isArray(payload), "WebSocket does not support batch send", "payload", payload);
+
+        // @TODO: stringify payloads here and store to prevent mutations
+
+        // Prepare a promise to respond to
+        const promise = new Promise((resolve, reject) => {
+            this.#callbacks.set(payload.id, { payload, resolve, reject });
+        });
+
+        // Wait until the socket is connected before writing to it
+        await this._waitUntilReady();
+
+        // Write the request to the socket
+        await this._write(JSON.stringify(payload));
+
+        return <Array<JsonRpcResult | JsonRpcError>>[ await promise ];
+    }
+
+    // Sub-classes must call this once they are connected
+    /*
+    async _start(): Promise<void> {
+        if (this.#ready) { return; }
+
+        for (const { payload } of this.#callbacks.values()) {
+            await this._write(JSON.stringify(payload));
+        }
+
+        this.#ready = (async function() {
+            await super._start();
+        })();
+    }
+    */
+
+    /**
+     *  Sub-classes **must** call this with messages received over their
+     *  transport to be processed and dispatched.
+     */
+    async _processMessage(message: string): Promise<void> {
+        const result = <JsonRpcResult | JsonRpcError | JsonRpcSubscription>(JSON.parse(message));
+
+        if (result && typeof(result) === "object" && "id" in result) {
+            const callback = this.#callbacks.get(result.id);
+            if (callback == null) {
+                this.emit("error", makeError("received result for unknown id", "UNKNOWN_ERROR", {
+                    reasonCode: "UNKNOWN_ID",
+                    result
+                }));
+                return;
+            }
+            this.#callbacks.delete(result.id);
+
+            callback.resolve(result);
+
+        } else if (result && result.method === "eth_subscription") {
+            const filterId = result.params.subscription;
+            const subscriber = this.#subs.get(filterId);
+            if (subscriber) {
+                subscriber._handleMessage(result.params.result);
+            } else {
+                let pending = this.#pending.get(filterId);
+                if (pending == null) {
+                    pending = [ ];
+                    this.#pending.set(filterId, pending);
+                }
+                pending.push(result.params.result);
+            }
+
+        } else {
+            this.emit("error", makeError("received unexpected message", "UNKNOWN_ERROR", {
+                reasonCode: "UNEXPECTED_MESSAGE",
+                result
+            }));
+            return;
+        }
+    }
+
+    /**
+     *  Sub-classes **must** override this to send %%message%% over their
+     *  transport.
+     */
+    async _write(message: string): Promise<void> {
+        throw new Error("sub-classes must override this");
+    }
+}

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

@@ -0,0 +1,102 @@
+
+
+import { WebSocket as _WebSocket } from "./ws.js"; /*-browser*/
+
+import { SocketProvider } from "./provider-socket.js";
+
+import type { Networkish } from "./network.js";
+
+/**
+ *  A generic interface to a Websocket-like object.
+ */
+export interface WebSocketLike {
+    onopen: null | ((...args: Array<any>) => any);
+    onmessage: null | ((...args: Array<any>) => any);
+    onerror: null | ((...args: Array<any>) => any);
+
+    readyState: number;
+
+    send(payload: any): void;
+    close(code?: number, reason?: string): void;
+}
+
+/**
+ *  A function which can be used to re-create a WebSocket connection
+ *  on disconnect.
+ */
+export type WebSocketCreator = () => WebSocketLike;
+
+/**
+ *  A JSON-RPC provider which is backed by a WebSocket.
+ *
+ *  WebSockets are often preferred because they retain a live connection
+ *  to a server, which permits more instant access to events.
+ *
+ *  However, this incurs higher server infrasturture costs, so additional
+ *  resources may be required to host your own WebSocket nodes and many
+ *  third-party services charge additional fees for WebSocket endpoints.
+ */
+export class WebSocketProvider extends SocketProvider {
+    #connect: null | WebSocketCreator;
+
+    #websocket: null | WebSocketLike;
+    get websocket(): WebSocketLike {
+        if (this.#websocket == null) { throw new Error("websocket closed"); }
+        return this.#websocket;
+    }
+
+    constructor(url: string | WebSocketLike | WebSocketCreator, network?: Networkish) {
+        super(network);
+        if (typeof(url) === "string") {
+            this.#connect = () => { return new _WebSocket(url); };
+            this.#websocket = this.#connect();
+        } else if (typeof(url) === "function") {
+            this.#connect = url;
+            this.#websocket = url();
+        } else {
+            this.#connect = null;
+            this.#websocket = url;
+        }
+
+        this.websocket.onopen = async () => {
+            try {
+                await this._start()
+                this.resume();
+            } catch (error) {
+                console.log("failed to start WebsocketProvider", error);
+                // @TODO: now what? Attempt reconnect?
+            }
+        };
+
+        this.websocket.onmessage = (message: { data: string }) => {
+            this._processMessage(message.data);
+        };
+/*
+        this.websocket.onclose = (event) => {
+            // @TODO: What event.code should we reconnect on?
+            const reconnect = false;
+            if (reconnect) {
+                this.pause(true);
+                if (this.#connect) {
+                    this.#websocket = this.#connect();
+                    this.#websocket.onopen = ...
+                    // @TODO: this requires the super class to rebroadcast; move it there
+                }
+                this._reconnect();
+            }
+        };
+*/
+    }
+
+    async _write(message: string): Promise<void> {
+        this.websocket.send(message);
+    }
+
+    async destroy(): Promise<void> {
+        if (this.#websocket != null) {
+            this.#websocket.close();
+            this.#websocket = null;
+        }
+        super.destroy();
+    }
+}