eteres 0.0.1-security → 6.7.1

package/src.ts/contract/factory.ts

@@ -0,0 +1,143 @@
+
+import { Interface } from "../abi/index.js";
+import { getCreateAddress } from "../address/index.js";
+import {
+    concat, defineProperties, getBytes, hexlify,
+    assert, assertArgument
+} from "../utils/index.js";
+
+import { BaseContract, copyOverrides, resolveArgs } from "./contract.js";
+
+import type { InterfaceAbi } from "../abi/index.js";
+import type { Addressable } from "../address/index.js";
+import type { ContractRunner } from "../providers/index.js";
+import type { BytesLike } from "../utils/index.js";
+
+import type {
+    ContractInterface, ContractMethodArgs, ContractDeployTransaction,
+} from "./types.js";
+import type { ContractTransactionResponse } from "./wrappers.js";
+
+
+// A = Arguments to the constructor
+// I = Interface of deployed contracts
+
+/**
+ *  A **ContractFactory** is used to deploy a Contract to the blockchain.
+ */
+export class ContractFactory<A extends Array<any> = Array<any>, I = BaseContract> {
+
+    /**
+     *  The Contract Interface.
+     */
+    readonly interface!: Interface;
+
+    /**
+     *  The Contract deployment bytecode. Often called the initcode.
+     */
+    readonly bytecode!: string;
+
+    /**
+     *  The ContractRunner to deploy the Contract as.
+     */
+    readonly runner!: null | ContractRunner;
+
+    /**
+     *  Create a new **ContractFactory** with %%abi%% and %%bytecode%%,
+     *  optionally connected to %%runner%%.
+     *
+     *  The %%bytecode%% may be the ``bytecode`` property within the
+     *  standard Solidity JSON output.
+     */
+    constructor(abi: Interface | InterfaceAbi, bytecode: BytesLike | { object: string }, runner?: null | ContractRunner) {
+        const iface = Interface.from(abi);
+
+        // Dereference Solidity bytecode objects and allow a missing `0x`-prefix
+        if (bytecode instanceof Uint8Array) {
+            bytecode = hexlify(getBytes(bytecode));
+        } else {
+            if (typeof(bytecode) === "object") { bytecode = bytecode.object; }
+            if (!bytecode.startsWith("0x")) { bytecode = "0x" + bytecode; }
+            bytecode = hexlify(getBytes(bytecode));
+        }
+
+        defineProperties<ContractFactory>(this, {
+            bytecode, interface: iface, runner: (runner || null)
+        });
+    }
+
+    attach(target: string | Addressable): BaseContract & Omit<I, keyof BaseContract> {
+        return new (<any>BaseContract)(target, this.interface, this.runner);
+    }
+
+    /**
+     *  Resolves to the transaction to deploy the contract, passing %%args%%
+     *  into the constructor.
+     */
+    async getDeployTransaction(...args: ContractMethodArgs<A>): Promise<ContractDeployTransaction> {
+        let overrides: Omit<ContractDeployTransaction, "data"> = { };
+
+        const fragment = this.interface.deploy;
+
+        if (fragment.inputs.length + 1 === args.length) {
+            overrides = await copyOverrides(args.pop());
+        }
+
+        if (fragment.inputs.length !== args.length) {
+            throw new Error("incorrect number of arguments to constructor");
+        }
+
+        const resolvedArgs = await resolveArgs(this.runner, fragment.inputs, args);
+
+        const data = concat([ this.bytecode, this.interface.encodeDeploy(resolvedArgs) ]);
+        return Object.assign({ }, overrides, { data });
+    }
+
+    /**
+     *  Resolves to the Contract deployed by passing %%args%% into the
+     *  constructor.
+     *
+     *  This will resovle to the Contract before it has been deployed to the
+     *  network, so the [[BaseContract-waitForDeployment]] should be used before
+     *  sending any transactions to it.
+     */
+    async deploy(...args: ContractMethodArgs<A>): Promise<BaseContract & { deploymentTransaction(): ContractTransactionResponse } & Omit<I, keyof BaseContract>> {
+        const tx = await this.getDeployTransaction(...args);
+
+        assert(this.runner && typeof(this.runner.sendTransaction) === "function",
+            "factory runner does not support sending transactions", "UNSUPPORTED_OPERATION", {
+            operation: "sendTransaction" });
+
+        const sentTx = await this.runner.sendTransaction(tx);
+        const address = getCreateAddress(sentTx);
+        return new (<any>BaseContract)(address, this.interface, this.runner, sentTx);
+    }
+
+    /**
+     *  Return a new **ContractFactory** with the same ABI and bytecode,
+     *  but connected to %%runner%%.
+     */
+    connect(runner: null | ContractRunner): ContractFactory<A, I> {
+        return new ContractFactory(this.interface, this.bytecode, runner);
+    }
+
+    /**
+     *  Create a new **ContractFactory** from the standard Solidity JSON output.
+     */
+    static fromSolidity<A extends Array<any> = Array<any>, I = ContractInterface>(output: any, runner?: ContractRunner): ContractFactory<A, I> {
+        assertArgument(output != null, "bad compiler output", "output", output);
+
+        if (typeof(output) === "string") { output = JSON.parse(output); }
+
+        const abi = output.abi;
+
+        let bytecode = "";
+        if (output.bytecode) {
+            bytecode = output.bytecode;
+        } else if (output.evm && output.evm.bytecode) {
+            bytecode = output.evm.bytecode;
+        }
+
+        return new this(abi, bytecode, runner);
+    }
+}

package/src.ts/contract/index.ts

@@ -0,0 +1,31 @@
+/**
+ *  A **Contract** object is a meta-class (a class whose definition is
+ *  defined at runtime), which communicates with a deployed smart contract
+ *  on the blockchain and provides a simple JavaScript interface to call
+ *  methods, send transaction, query historic logs and listen for its events.
+ *
+ *  @_section: api/contract:Contracts  [about-contracts]
+ */
+export {
+    BaseContract, Contract
+} from "./contract.js";
+
+export {
+    ContractFactory
+} from "./factory.js";
+
+export {
+    ContractEventPayload, ContractUnknownEventPayload,
+    ContractTransactionReceipt, ContractTransactionResponse,
+    EventLog, UndecodedEventLog
+} from "./wrappers.js";
+
+export type {
+    BaseContractMethod, ConstantContractMethod,
+    PostfixOverrides,
+    ContractEvent, ContractEventArgs, ContractEventName,
+    ContractDeployTransaction,
+    ContractInterface, ContractMethod, ContractMethodArgs, ContractTransaction,
+    DeferredTopicFilter, Overrides,
+    WrappedFallback
+} from "./types.js";

package/src.ts/contract/types.ts

@@ -0,0 +1,236 @@
+import type {
+    EventFragment, FunctionFragment, Result, Typed
+} from "../abi/index.js";
+import type {
+    TransactionRequest, PreparedTransactionRequest, TopicFilter
+} from "../providers/index.js";
+
+import type { ContractTransactionResponse } from "./wrappers.js";
+
+
+/**
+ *  The name for an event used for subscribing to Contract events.
+ *
+ *  **``string``** - An event by name. The event must be non-ambiguous.
+ *  The parameters will be dereferenced when passed into the listener.
+ *
+ *  [[ContractEvent]] - A filter from the ``contract.filters``, which will
+ *  pass only the EventPayload as a single parameter, which includes a
+ *  ``.signature`` property that can be used to further filter the event.
+ *
+ *  [[TopicFilter]] - A filter defined using the standard Ethereum API
+ *  which provides the specific topic hash or topic hashes to watch for along
+ *  with any additional values to filter by. This will only pass a single
+ *  parameter to the listener, the EventPayload which will include additional
+ *  details to refine by, such as the event name and signature.
+ *
+ *  [[DeferredTopicFilter]] - A filter created by calling a [[ContractEvent]]
+ *  with parameters, which will create a filter for a specific event
+ *  signautre and dereference each parameter when calling the listener.
+ */
+export type ContractEventName = string | ContractEvent | TopicFilter | DeferredTopicFilter;
+
+/**
+ *  A Contract with no method constraints.
+ */
+export interface ContractInterface {
+    [ name: string ]: BaseContractMethod;
+};
+
+/**
+ *  When creating a filter using the ``contract.filters``, this is returned.
+ */
+export interface DeferredTopicFilter {
+    getTopicFilter(): Promise<TopicFilter>;
+    fragment: EventFragment;
+}
+
+/**
+ *  When populating a transaction this type is returned.
+ */
+export interface ContractTransaction extends PreparedTransactionRequest {
+    /**
+     *  The target address.
+     */
+    to: string;
+
+    /**
+     *  The transaction data.
+     */
+    data: string;
+
+    /**
+     *  The from address, if any.
+     */
+    from?: string;
+}
+
+/**
+ *  A deployment transaction for a contract.
+ */
+export interface ContractDeployTransaction extends Omit<ContractTransaction, "to"> { }
+
+/**
+ *  The overrides for a contract transaction.
+ */
+export interface Overrides extends Omit<TransactionRequest, "to" | "data"> { };
+
+
+/**
+ *  Arguments to a Contract method can always include an additional and
+ *  optional overrides parameter.
+ *
+ *  @_ignore:
+ */
+export type PostfixOverrides<A extends Array<any>> = A | [ ...A, Overrides ];
+
+/**
+ *  Arguments to a Contract method can always include an additional and
+ *  optional overrides parameter, and each parameter can optionally be
+ *  [[Typed]].
+ *
+ *  @_ignore:
+ */
+export type ContractMethodArgs<A extends Array<any>> = PostfixOverrides<{ [ I in keyof A ]-?: A[I] | Typed }>;
+
+// A = Arguments passed in as a tuple
+// R = The result type of the call (i.e. if only one return type,
+//     the qualified type, otherwise Result)
+// D = The type the default call will return (i.e. R for view/pure,
+//     TransactionResponse otherwise)
+
+/**
+ *  A Contract method can be called directly, or used in various ways.
+ */
+export interface BaseContractMethod<A extends Array<any> = Array<any>, R = any, D extends R | ContractTransactionResponse = R | ContractTransactionResponse> {
+    (...args: ContractMethodArgs<A>): Promise<D>;
+
+    /**
+     *  The name of the Contract method.
+     */
+    name: string;
+
+    /**
+     *  The fragment of the Contract method. This will throw on ambiguous
+     *  method names.
+     */
+    fragment: FunctionFragment;
+
+    /**
+     *  Returns the fragment constrained by %%args%%. This can be used to
+     *  resolve ambiguous method names.
+     */
+    getFragment(...args: ContractMethodArgs<A>): FunctionFragment;
+
+    /**
+     *  Returns a populated transaction that can be used to perform the
+     *  contract method with %%args%%.
+     */
+    populateTransaction(...args: ContractMethodArgs<A>): Promise<ContractTransaction>;
+
+    /**
+     *  Call the contract method with %%args%% and return the value.
+     *
+     *  If the return value is a single type, it will be dereferenced and
+     *  returned directly, otherwise the full Result will be returned.
+     */
+    staticCall(...args: ContractMethodArgs<A>): Promise<R>;
+
+    /**
+     *  Send a transaction for the contract method with %%args%%.
+     */
+    send(...args: ContractMethodArgs<A>): Promise<ContractTransactionResponse>;
+
+    /**
+     *  Estimate the gas to send the contract method with %%args%%.
+     */
+    estimateGas(...args: ContractMethodArgs<A>): Promise<bigint>;
+
+    /**
+     *  Call the contract method with %%args%% and return the Result
+     *  without any dereferencing.
+     */
+    staticCallResult(...args: ContractMethodArgs<A>): Promise<Result>;
+}
+
+/**
+ *  A contract method on a Contract.
+ */
+export interface ContractMethod<
+    A extends Array<any> = Array<any>,
+    R = any,
+    D extends R | ContractTransactionResponse = R | ContractTransactionResponse
+> extends BaseContractMethod<A, R, D> { }
+
+/**
+ *  A pure of view method on a Contract.
+ */
+export interface ConstantContractMethod<
+    A extends Array<any>,
+    R = any
+> extends ContractMethod<A, R, R> { }
+
+
+/**
+ *  Each argument of an event is nullable (to indicate matching //any//.
+ *
+ *  @_ignore:
+ */
+export type ContractEventArgs<A extends Array<any>> = { [ I in keyof A ]?: A[I] | Typed | null };
+
+export interface ContractEvent<A extends Array<any> = Array<any>> {
+    (...args: ContractEventArgs<A>): DeferredTopicFilter;
+
+    /**
+     *  The name of the Contract event.
+     */
+    name: string;
+
+    /**
+     *  The fragment of the Contract event. This will throw on ambiguous
+     *  method names.
+     */
+    fragment: EventFragment;
+
+    /**
+     *  Returns the fragment constrained by %%args%%. This can be used to
+     *  resolve ambiguous event names.
+     */
+    getFragment(...args: ContractEventArgs<A>): EventFragment;
+};
+
+/**
+ *  A Fallback or Receive function on a Contract.
+ */
+export interface WrappedFallback {
+    (overrides?: Omit<TransactionRequest, "to">): Promise<ContractTransactionResponse>;
+
+    /**
+     *  Returns a populated transaction that can be used to perform the
+     *  fallback method.
+     *
+     *  For non-receive fallback, ``data`` may be overridden.
+     */
+    populateTransaction(overrides?: Omit<TransactionRequest, "to">): Promise<ContractTransaction>;
+
+    /**
+     *  Call the contract fallback and return the result.
+     *
+     *  For non-receive fallback, ``data`` may be overridden.
+     */
+    staticCall(overrides?: Omit<TransactionRequest, "to">): Promise<string>;
+
+    /**
+     *  Send a transaction to the contract fallback.
+     *
+     *  For non-receive fallback, ``data`` may be overridden.
+     */
+    send(overrides?: Omit<TransactionRequest, "to">): Promise<ContractTransactionResponse>;
+
+    /**
+     *  Estimate the gas to send a transaction to the contract fallback.
+     *
+     *  For non-receive fallback, ``data`` may be overridden.
+     */
+    estimateGas(overrides?: Omit<TransactionRequest, "to">): Promise<bigint>;
+}

package/src.ts/contract/wrappers.ts

@@ -0,0 +1,225 @@
+// import from provider.ts instead of index.ts to prevent circular dep
+// from EtherscanProvider
+import {
+    Block, Log, TransactionReceipt, TransactionResponse
+} from "../providers/provider.js";
+import { defineProperties, EventPayload } from "../utils/index.js";
+
+import type { EventFragment, Interface, Result } from "../abi/index.js";
+import type { Listener } from "../utils/index.js";
+import type {
+    Provider
+} from "../providers/index.js";
+
+import type { BaseContract } from "./contract.js";
+import type { ContractEventName } from "./types.js";
+
+/**
+ *  An **EventLog** contains additional properties parsed from the [[Log]].
+ */
+export class EventLog extends Log {
+    /**
+     *  The Contract Interface.
+     */
+    readonly interface!: Interface;
+
+    /**
+     *  The matching event.
+     */
+    readonly fragment!: EventFragment;
+
+    /**
+     *  The parsed arguments passed to the event by ``emit``.
+     */
+    readonly args!: Result;
+
+    /**
+     * @_ignore:
+     */
+    constructor(log: Log, iface: Interface, fragment: EventFragment) {
+        super(log, log.provider);
+        const args = iface.decodeEventLog(fragment, log.data, log.topics);
+        defineProperties<EventLog>(this, { args, fragment, interface: iface });
+    }
+
+    /**
+     *  The name of the event.
+     */
+    get eventName(): string { return this.fragment.name; }
+
+    /**
+     *  The signature of the event.
+     */
+    get eventSignature(): string { return this.fragment.format(); }
+}
+
+/**
+ *  An **EventLog** contains additional properties parsed from the [[Log]].
+ */
+export class UndecodedEventLog extends Log {
+
+    /**
+     *  The error encounted when trying to decode the log.
+     */
+    readonly error!: Error;
+
+    /**
+     * @_ignore:
+     */
+    constructor(log: Log, error: Error) {
+        super(log, log.provider);
+        defineProperties<UndecodedEventLog>(this, { error });
+    }
+}
+
+/**
+ *  A **ContractTransactionReceipt** includes the parsed logs from a
+ *  [[TransactionReceipt]].
+ */
+export class ContractTransactionReceipt extends TransactionReceipt {
+    readonly #iface: Interface;
+
+    /**
+     *  @_ignore:
+     */
+    constructor(iface: Interface, provider: Provider, tx: TransactionReceipt) {
+        super(tx, provider);
+        this.#iface = iface;
+    }
+
+    /**
+     *  The parsed logs for any [[Log]] which has a matching event in the
+     *  Contract ABI.
+     */
+    get logs(): Array<EventLog | Log> {
+        return super.logs.map((log) => {
+            const fragment = log.topics.length ? this.#iface.getEvent(log.topics[0]): null;
+            if (fragment) {
+                try {
+                    return new EventLog(log, this.#iface, fragment)
+                } catch (error: any) {
+                    return new UndecodedEventLog(log, error);
+                }
+            }
+
+            return log;
+        });
+    }
+
+}
+
+/**
+ *  A **ContractTransactionResponse** will return a
+ *  [[ContractTransactionReceipt]] when waited on.
+ */
+export class ContractTransactionResponse extends TransactionResponse {
+    readonly #iface: Interface;
+
+    /**
+     *  @_ignore:
+     */
+    constructor(iface: Interface, provider: Provider, tx: TransactionResponse) {
+        super(tx, provider);
+        this.#iface = iface;
+    }
+
+    /**
+     *  Resolves once this transaction has been mined and has
+     *  %%confirms%% blocks including it (default: ``1``) with an
+     *  optional %%timeout%%.
+     *
+     *  This can resolve to ``null`` only if %%confirms%% is ``0``
+     *  and the transaction has not been mined, otherwise this will
+     *  wait until enough confirmations have completed.
+     */
+    async wait(confirms?: number): Promise<null | ContractTransactionReceipt> {
+        const receipt = await super.wait(confirms);
+        if (receipt == null) { return null; }
+        return new ContractTransactionReceipt(this.#iface, this.provider, receipt);
+    }
+}
+
+/**
+ *  A **ContractUnknownEventPayload** is included as the last parameter to
+ *  Contract Events when the event does not match any events in the ABI.
+ */
+export  class ContractUnknownEventPayload extends EventPayload<ContractEventName> {
+    /**
+     *  The log with no matching events.
+     */
+    readonly log!: Log;
+
+    /**
+     *  @_event:
+     */
+    constructor(contract: BaseContract, listener: null | Listener, filter: ContractEventName, log: Log) {
+        super(contract, listener, filter);
+        defineProperties<ContractUnknownEventPayload>(this, { log });
+    }
+
+    /**
+     *  Resolves to the block the event occured in.
+     */
+    async getBlock(): Promise<Block> {
+        return await this.log.getBlock();
+    }
+
+    /**
+     *  Resolves to the transaction the event occured in.
+     */
+    async getTransaction(): Promise<TransactionResponse> {
+        return await this.log.getTransaction();
+    }
+
+    /**
+     *  Resolves to the transaction receipt the event occured in.
+     */
+    async getTransactionReceipt(): Promise<TransactionReceipt> {
+        return await this.log.getTransactionReceipt();
+    }
+}
+
+/**
+ *  A **ContractEventPayload** is included as the last parameter to
+ *  Contract Events when the event is known.
+ */
+export class ContractEventPayload extends ContractUnknownEventPayload {
+
+    /**
+     *  The matching event.
+     */
+    declare readonly fragment: EventFragment;
+
+    /**
+     *  The log, with parsed properties.
+     */
+    declare readonly log: EventLog;
+
+    /**
+     *  The parsed arguments passed to the event by ``emit``.
+     */
+    declare readonly args: Result;
+
+    /**
+     *  @_ignore:
+     */
+    constructor(contract: BaseContract, listener: null | Listener, filter: ContractEventName, fragment: EventFragment, _log: Log) {
+        super(contract, listener, filter, new EventLog(_log, contract.interface, fragment));
+        const args = contract.interface.decodeEventLog(fragment, this.log.data, this.log.topics);
+        defineProperties<ContractEventPayload>(this, { args, fragment });
+    }
+
+    /**
+     *  The event name.
+     */
+    get eventName(): string {
+        return this.fragment.name;
+    }
+
+    /**
+     *  The event signature.
+     */
+    get eventSignature(): string {
+        return this.fragment.format();
+    }
+}

package/src.ts/crypto/crypto-browser.ts

@@ -0,0 +1,64 @@
+/* Browser Crypto Shims */
+
+import { hmac } from "@noble/hashes/hmac";
+import { pbkdf2 } from "@noble/hashes/pbkdf2";
+import { sha256 } from "@noble/hashes/sha256";
+import { sha512 } from "@noble/hashes/sha512";
+
+import { assert, assertArgument } from "../utils/index.js";
+
+
+declare global {
+    interface Window { }
+
+    const window: Window;
+    const self: Window;
+}
+
+
+function getGlobal(): any {
+  if (typeof self !== 'undefined') { return self; }
+  if (typeof window !== 'undefined') { return window; }
+  if (typeof global !== 'undefined') { return global; }
+  throw new Error('unable to locate global object');
+};
+
+const anyGlobal = getGlobal();
+const crypto: any = anyGlobal.crypto || anyGlobal.msCrypto;
+
+
+export interface CryptoHasher {
+    update(data: Uint8Array): CryptoHasher;
+    digest(): Uint8Array;
+}
+
+export function createHash(algo: string): CryptoHasher {
+    switch (algo) {
+        case "sha256": return sha256.create();
+        case "sha512": return sha512.create();
+    }
+    assertArgument(false, "invalid hashing algorithm name", "algorithm", algo);
+}
+
+export function createHmac(_algo: string, key: Uint8Array): CryptoHasher {
+    const algo = ({ sha256, sha512 }[_algo]);
+    assertArgument(algo != null, "invalid hmac algorithm", "algorithm", _algo);
+    return hmac.create(algo, key);
+}
+
+export function pbkdf2Sync(password: Uint8Array, salt: Uint8Array, iterations: number, keylen: number, _algo: "sha256" | "sha512"): Uint8Array {
+    const algo = ({ sha256, sha512 }[_algo]);
+    assertArgument(algo != null, "invalid pbkdf2 algorithm", "algorithm", _algo);
+    return pbkdf2(algo, password, salt, { c: iterations, dkLen: keylen });
+}
+
+export function randomBytes(length: number): Uint8Array {
+    assert(crypto != null, "platform does not support secure random numbers", "UNSUPPORTED_OPERATION", {
+        operation: "randomBytes" });
+
+    assertArgument(Number.isInteger(length) && length > 0 && length <= 1024, "invalid length", "length", length);
+
+    const result = new Uint8Array(length);
+    crypto.getRandomValues(result);
+    return result;
+}

package/src.ts/crypto/crypto.ts

@@ -0,0 +1,4 @@
+
+export {
+    createHash, createHmac, pbkdf2Sync, randomBytes
+} from "crypto";