eteres 0.0.1-security → 6.7.1

package/src.ts/abi/typed.ts

@@ -0,0 +1,796 @@
+/**
+ *  A Typed object allows a value to have its type explicitly
+ *  specified.
+ *
+ *  For example, in Solidity, the value ``45`` could represent a
+ *  ``uint8`` or a ``uint256``. The value ``0x1234`` could represent
+ *  a ``bytes2`` or ``bytes``.
+ *
+ *  Since JavaScript has no meaningful way to explicitly inform any
+ *  APIs which what the type is, this allows transparent interoperation
+ *  with Soldity.
+ *
+ *  @_subsection: api/abi:Typed Values
+ */
+
+import { assertPrivate, defineProperties } from "../utils/index.js";
+
+import type { Addressable } from "../address/index.js";
+import type { BigNumberish, BytesLike } from "../utils/index.js";
+
+import type { Result } from "./coders/abstract-coder.js";
+
+const _gaurd = { };
+
+function n(value: BigNumberish, width: number): Typed {
+    let signed = false;
+    if (width < 0) {
+        signed = true;
+        width *= -1;
+    }
+
+    // @TODO: Check range is valid for value
+    return new Typed(_gaurd, `${ signed ? "": "u" }int${ width }`, value, { signed, width });
+}
+
+function b(value: BytesLike, size?: number): Typed {
+    // @TODO: Check range is valid for value
+    return new Typed(_gaurd, `bytes${ (size) ? size: "" }`, value, { size });
+}
+
+// @TODO: Remove this in v7, it was replaced by TypedBigInt
+/**
+ *  @_ignore:
+ */
+export interface TypedNumber extends Typed {
+    value: number;
+    defaultValue(): number;
+    minValue(): number;
+    maxValue(): number;
+}
+
+/**
+ *  A **Typed** that represents a numeric value.
+ */
+export interface TypedBigInt extends Typed {
+    /**
+     *  The value.
+     */
+    value: bigint;
+
+    /**
+     *  The default value for all numeric types is ``0``.
+     */
+    defaultValue(): bigint;
+
+    /**
+     *  The minimum value for this type, accounting for bit-width and signed-ness.
+     */
+    minValue(): bigint;
+
+    /**
+     *  The minimum value for this type, accounting for bit-width.
+     */
+    maxValue(): bigint;
+}
+
+/**
+ *  A **Typed** that represents a binary sequence of data as bytes.
+ */
+export interface TypedData extends Typed {
+    /**
+     *  The value.
+     */
+    value: string;
+
+    /**
+     *  The default value for this type.
+     */
+    defaultValue(): string;
+}
+
+/**
+ *  A **Typed** that represents a UTF-8 sequence of bytes.
+ */
+export interface TypedString extends Typed {
+    /**
+     *  The value.
+     */
+    value: string;
+
+    /**
+     *  The default value for the string type is the empty string (i.e. ``""``).
+     */
+    defaultValue(): string;
+}
+
+const _typedSymbol = Symbol.for("_ethers_typed");
+
+/**
+ *  The **Typed** class to wrap values providing explicit type information.
+ */
+export class Typed {
+
+    /**
+     *  The type, as a Solidity-compatible type.
+     */
+    readonly type!: string;
+
+    /**
+     *  The actual value.
+     */
+    readonly value!: any;
+
+    readonly #options: any;
+
+    /**
+     *  @_ignore:
+     */
+    readonly _typedSymbol!: Symbol;
+
+    /**
+     *  @_ignore:
+     */
+    constructor(gaurd: any, type: string, value: any, options?: any) {
+        if (options == null) { options = null; }
+        assertPrivate(_gaurd, gaurd, "Typed");
+        defineProperties<Typed>(this, { _typedSymbol, type, value });
+        this.#options = options;
+
+        // Check the value is valid
+        this.format();
+    }
+
+    /**
+     *  Format the type as a Human-Readable type.
+     */
+    format(): string {
+        if (this.type === "array") {
+            throw new Error("");
+        } else if (this.type === "dynamicArray") {
+            throw new Error("");
+        } else if (this.type === "tuple") {
+            return `tuple(${ this.value.map((v: Typed) => v.format()).join(",") })`
+        }
+
+        return this.type;
+    }
+
+    /**
+     *  The default value returned by this type.
+     */
+    defaultValue(): string | number | bigint | Result {
+        return 0;
+    }
+
+    /**
+     *  The minimum value for numeric types.
+     */
+    minValue(): string | number | bigint {
+        return 0;
+    }
+
+    /**
+     *  The maximum value for numeric types.
+     */
+    maxValue(): string | number | bigint {
+        return 0;
+    }
+
+    /**
+     *  Returns ``true`` and provides a type guard is this is a [[TypedBigInt]].
+     */
+    isBigInt(): this is TypedBigInt {
+        return !!(this.type.match(/^u?int[0-9]+$/));
+    }
+
+    /**
+     *  Returns ``true`` and provides a type guard is this is a [[TypedData]].
+     */
+    isData(): this is TypedData {
+        return this.type.startsWith("bytes");
+    }
+
+    /**
+     *  Returns ``true`` and provides a type guard is this is a [[TypedString]].
+     */
+    isString(): this is TypedString {
+        return (this.type === "string");
+    }
+
+    /**
+     *  Returns the tuple name, if this is a tuple. Throws otherwise.
+     */
+    get tupleName(): null | string {
+        if (this.type !== "tuple") { throw TypeError("not a tuple"); }
+        return this.#options;
+    }
+
+    // Returns the length of this type as an array
+    // - `null` indicates the length is unforced, it could be dynamic
+    // - `-1` indicates the length is dynamic
+    // - any other value indicates it is a static array and is its length
+
+    /**
+     *  Returns the length of the array type or ``-1`` if it is dynamic.
+     *
+     *  Throws if the type is not an array.
+     */
+    get arrayLength(): null | number {
+        if (this.type !== "array") { throw TypeError("not an array"); }
+        if (this.#options === true) { return -1; }
+        if (this.#options === false) { return (<Array<any>>(this.value)).length; }
+        return null;
+    }
+
+    /**
+     *  Returns a new **Typed** of %%type%% with the %%value%%.
+     */
+    static from(type: string, value: any): Typed {
+        return new Typed(_gaurd, type, value);
+    }
+
+    /**
+     *  Return a new ``uint8`` type for %%v%%.
+     */
+    static uint8(v: BigNumberish): Typed { return n(v, 8); }
+
+    /**
+     *  Return a new ``uint16`` type for %%v%%.
+     */
+    static uint16(v: BigNumberish): Typed { return n(v, 16); }
+
+    /**
+     *  Return a new ``uint24`` type for %%v%%.
+     */
+    static uint24(v: BigNumberish): Typed { return n(v, 24); }
+
+    /**
+     *  Return a new ``uint32`` type for %%v%%.
+     */
+    static uint32(v: BigNumberish): Typed { return n(v, 32); }
+
+    /**
+     *  Return a new ``uint40`` type for %%v%%.
+     */
+    static uint40(v: BigNumberish): Typed { return n(v, 40); }
+
+    /**
+     *  Return a new ``uint48`` type for %%v%%.
+     */
+    static uint48(v: BigNumberish): Typed { return n(v, 48); }
+
+    /**
+     *  Return a new ``uint56`` type for %%v%%.
+     */
+    static uint56(v: BigNumberish): Typed { return n(v, 56); }
+
+    /**
+     *  Return a new ``uint64`` type for %%v%%.
+     */
+    static uint64(v: BigNumberish): Typed { return n(v, 64); }
+
+    /**
+     *  Return a new ``uint72`` type for %%v%%.
+     */
+    static uint72(v: BigNumberish): Typed { return n(v, 72); }
+
+    /**
+     *  Return a new ``uint80`` type for %%v%%.
+     */
+    static uint80(v: BigNumberish): Typed { return n(v, 80); }
+
+    /**
+     *  Return a new ``uint88`` type for %%v%%.
+     */
+    static uint88(v: BigNumberish): Typed { return n(v, 88); }
+
+    /**
+     *  Return a new ``uint96`` type for %%v%%.
+     */
+    static uint96(v: BigNumberish): Typed { return n(v, 96); }
+
+    /**
+     *  Return a new ``uint104`` type for %%v%%.
+     */
+    static uint104(v: BigNumberish): Typed { return n(v, 104); }
+
+    /**
+     *  Return a new ``uint112`` type for %%v%%.
+     */
+    static uint112(v: BigNumberish): Typed { return n(v, 112); }
+
+    /**
+     *  Return a new ``uint120`` type for %%v%%.
+     */
+    static uint120(v: BigNumberish): Typed { return n(v, 120); }
+
+    /**
+     *  Return a new ``uint128`` type for %%v%%.
+     */
+    static uint128(v: BigNumberish): Typed { return n(v, 128); }
+
+    /**
+     *  Return a new ``uint136`` type for %%v%%.
+     */
+    static uint136(v: BigNumberish): Typed { return n(v, 136); }
+
+    /**
+     *  Return a new ``uint144`` type for %%v%%.
+     */
+    static uint144(v: BigNumberish): Typed { return n(v, 144); }
+
+    /**
+     *  Return a new ``uint152`` type for %%v%%.
+     */
+    static uint152(v: BigNumberish): Typed { return n(v, 152); }
+
+    /**
+     *  Return a new ``uint160`` type for %%v%%.
+     */
+    static uint160(v: BigNumberish): Typed { return n(v, 160); }
+
+    /**
+     *  Return a new ``uint168`` type for %%v%%.
+     */
+    static uint168(v: BigNumberish): Typed { return n(v, 168); }
+
+    /**
+     *  Return a new ``uint176`` type for %%v%%.
+     */
+    static uint176(v: BigNumberish): Typed { return n(v, 176); }
+
+    /**
+     *  Return a new ``uint184`` type for %%v%%.
+     */
+    static uint184(v: BigNumberish): Typed { return n(v, 184); }
+
+    /**
+     *  Return a new ``uint192`` type for %%v%%.
+     */
+    static uint192(v: BigNumberish): Typed { return n(v, 192); }
+
+    /**
+     *  Return a new ``uint200`` type for %%v%%.
+     */
+    static uint200(v: BigNumberish): Typed { return n(v, 200); }
+
+    /**
+     *  Return a new ``uint208`` type for %%v%%.
+     */
+    static uint208(v: BigNumberish): Typed { return n(v, 208); }
+
+    /**
+     *  Return a new ``uint216`` type for %%v%%.
+     */
+    static uint216(v: BigNumberish): Typed { return n(v, 216); }
+
+    /**
+     *  Return a new ``uint224`` type for %%v%%.
+     */
+    static uint224(v: BigNumberish): Typed { return n(v, 224); }
+
+    /**
+     *  Return a new ``uint232`` type for %%v%%.
+     */
+    static uint232(v: BigNumberish): Typed { return n(v, 232); }
+
+    /**
+     *  Return a new ``uint240`` type for %%v%%.
+     */
+    static uint240(v: BigNumberish): Typed { return n(v, 240); }
+
+    /**
+     *  Return a new ``uint248`` type for %%v%%.
+     */
+    static uint248(v: BigNumberish): Typed { return n(v, 248); }
+
+    /**
+     *  Return a new ``uint256`` type for %%v%%.
+     */
+    static uint256(v: BigNumberish): Typed { return n(v, 256); }
+
+    /**
+     *  Return a new ``uint256`` type for %%v%%.
+     */
+    static uint(v: BigNumberish): Typed { return n(v, 256); }
+
+    /**
+     *  Return a new ``int8`` type for %%v%%.
+     */
+    static int8(v: BigNumberish): Typed { return n(v, -8); }
+
+    /**
+     *  Return a new ``int16`` type for %%v%%.
+     */
+    static int16(v: BigNumberish): Typed { return n(v, -16); }
+
+    /**
+     *  Return a new ``int24`` type for %%v%%.
+     */
+    static int24(v: BigNumberish): Typed { return n(v, -24); }
+
+    /**
+     *  Return a new ``int32`` type for %%v%%.
+     */
+    static int32(v: BigNumberish): Typed { return n(v, -32); }
+
+    /**
+     *  Return a new ``int40`` type for %%v%%.
+     */
+    static int40(v: BigNumberish): Typed { return n(v, -40); }
+
+    /**
+     *  Return a new ``int48`` type for %%v%%.
+     */
+    static int48(v: BigNumberish): Typed { return n(v, -48); }
+
+    /**
+     *  Return a new ``int56`` type for %%v%%.
+     */
+    static int56(v: BigNumberish): Typed { return n(v, -56); }
+
+    /**
+     *  Return a new ``int64`` type for %%v%%.
+     */
+    static int64(v: BigNumberish): Typed { return n(v, -64); }
+
+    /**
+     *  Return a new ``int72`` type for %%v%%.
+     */
+    static int72(v: BigNumberish): Typed { return n(v, -72); }
+
+    /**
+     *  Return a new ``int80`` type for %%v%%.
+     */
+    static int80(v: BigNumberish): Typed { return n(v, -80); }
+
+    /**
+     *  Return a new ``int88`` type for %%v%%.
+     */
+    static int88(v: BigNumberish): Typed { return n(v, -88); }
+
+    /**
+     *  Return a new ``int96`` type for %%v%%.
+     */
+    static int96(v: BigNumberish): Typed { return n(v, -96); }
+
+    /**
+     *  Return a new ``int104`` type for %%v%%.
+     */
+    static int104(v: BigNumberish): Typed { return n(v, -104); }
+
+    /**
+     *  Return a new ``int112`` type for %%v%%.
+     */
+    static int112(v: BigNumberish): Typed { return n(v, -112); }
+
+    /**
+     *  Return a new ``int120`` type for %%v%%.
+     */
+    static int120(v: BigNumberish): Typed { return n(v, -120); }
+
+    /**
+     *  Return a new ``int128`` type for %%v%%.
+     */
+    static int128(v: BigNumberish): Typed { return n(v, -128); }
+
+    /**
+     *  Return a new ``int136`` type for %%v%%.
+     */
+    static int136(v: BigNumberish): Typed { return n(v, -136); }
+
+    /**
+     *  Return a new ``int144`` type for %%v%%.
+     */
+    static int144(v: BigNumberish): Typed { return n(v, -144); }
+
+    /**
+     *  Return a new ``int52`` type for %%v%%.
+     */
+    static int152(v: BigNumberish): Typed { return n(v, -152); }
+
+    /**
+     *  Return a new ``int160`` type for %%v%%.
+     */
+    static int160(v: BigNumberish): Typed { return n(v, -160); }
+
+    /**
+     *  Return a new ``int168`` type for %%v%%.
+     */
+    static int168(v: BigNumberish): Typed { return n(v, -168); }
+
+    /**
+     *  Return a new ``int176`` type for %%v%%.
+     */
+    static int176(v: BigNumberish): Typed { return n(v, -176); }
+
+    /**
+     *  Return a new ``int184`` type for %%v%%.
+     */
+    static int184(v: BigNumberish): Typed { return n(v, -184); }
+
+    /**
+     *  Return a new ``int92`` type for %%v%%.
+     */
+    static int192(v: BigNumberish): Typed { return n(v, -192); }
+
+    /**
+     *  Return a new ``int200`` type for %%v%%.
+     */
+    static int200(v: BigNumberish): Typed { return n(v, -200); }
+
+    /**
+     *  Return a new ``int208`` type for %%v%%.
+     */
+    static int208(v: BigNumberish): Typed { return n(v, -208); }
+
+    /**
+     *  Return a new ``int216`` type for %%v%%.
+     */
+    static int216(v: BigNumberish): Typed { return n(v, -216); }
+
+    /**
+     *  Return a new ``int224`` type for %%v%%.
+     */
+    static int224(v: BigNumberish): Typed { return n(v, -224); }
+
+    /**
+     *  Return a new ``int232`` type for %%v%%.
+     */
+    static int232(v: BigNumberish): Typed { return n(v, -232); }
+
+    /**
+     *  Return a new ``int240`` type for %%v%%.
+     */
+    static int240(v: BigNumberish): Typed { return n(v, -240); }
+
+    /**
+     *  Return a new ``int248`` type for %%v%%.
+     */
+    static int248(v: BigNumberish): Typed { return n(v, -248); }
+
+    /**
+     *  Return a new ``int256`` type for %%v%%.
+     */
+    static int256(v: BigNumberish): Typed { return n(v, -256); }
+
+    /**
+     *  Return a new ``int256`` type for %%v%%.
+     */
+    static int(v: BigNumberish): Typed { return n(v, -256); }
+
+    /**
+     *  Return a new ``bytes1`` type for %%v%%.
+     */
+    static bytes1(v: BytesLike): Typed { return b(v, 1); }
+
+    /**
+     *  Return a new ``bytes2`` type for %%v%%.
+     */
+    static bytes2(v: BytesLike): Typed { return b(v, 2); }
+
+    /**
+     *  Return a new ``bytes3`` type for %%v%%.
+     */
+    static bytes3(v: BytesLike): Typed { return b(v, 3); }
+
+    /**
+     *  Return a new ``bytes4`` type for %%v%%.
+     */
+    static bytes4(v: BytesLike): Typed { return b(v, 4); }
+
+    /**
+     *  Return a new ``bytes5`` type for %%v%%.
+     */
+    static bytes5(v: BytesLike): Typed { return b(v, 5); }
+
+    /**
+     *  Return a new ``bytes6`` type for %%v%%.
+     */
+    static bytes6(v: BytesLike): Typed { return b(v, 6); }
+
+    /**
+     *  Return a new ``bytes7`` type for %%v%%.
+     */
+    static bytes7(v: BytesLike): Typed { return b(v, 7); }
+
+    /**
+     *  Return a new ``bytes8`` type for %%v%%.
+     */
+    static bytes8(v: BytesLike): Typed { return b(v, 8); }
+
+    /**
+     *  Return a new ``bytes9`` type for %%v%%.
+     */
+    static bytes9(v: BytesLike): Typed { return b(v, 9); }
+
+    /**
+     *  Return a new ``bytes10`` type for %%v%%.
+     */
+    static bytes10(v: BytesLike): Typed { return b(v, 10); }
+
+    /**
+     *  Return a new ``bytes11`` type for %%v%%.
+     */
+    static bytes11(v: BytesLike): Typed { return b(v, 11); }
+
+    /**
+     *  Return a new ``bytes12`` type for %%v%%.
+     */
+    static bytes12(v: BytesLike): Typed { return b(v, 12); }
+
+    /**
+     *  Return a new ``bytes13`` type for %%v%%.
+     */
+    static bytes13(v: BytesLike): Typed { return b(v, 13); }
+
+    /**
+     *  Return a new ``bytes14`` type for %%v%%.
+     */
+    static bytes14(v: BytesLike): Typed { return b(v, 14); }
+
+    /**
+     *  Return a new ``bytes15`` type for %%v%%.
+     */
+    static bytes15(v: BytesLike): Typed { return b(v, 15); }
+
+    /**
+     *  Return a new ``bytes16`` type for %%v%%.
+     */
+    static bytes16(v: BytesLike): Typed { return b(v, 16); }
+
+    /**
+     *  Return a new ``bytes17`` type for %%v%%.
+     */
+    static bytes17(v: BytesLike): Typed { return b(v, 17); }
+
+    /**
+     *  Return a new ``bytes18`` type for %%v%%.
+     */
+    static bytes18(v: BytesLike): Typed { return b(v, 18); }
+
+    /**
+     *  Return a new ``bytes19`` type for %%v%%.
+     */
+    static bytes19(v: BytesLike): Typed { return b(v, 19); }
+
+    /**
+     *  Return a new ``bytes20`` type for %%v%%.
+     */
+    static bytes20(v: BytesLike): Typed { return b(v, 20); }
+
+    /**
+     *  Return a new ``bytes21`` type for %%v%%.
+     */
+    static bytes21(v: BytesLike): Typed { return b(v, 21); }
+
+    /**
+     *  Return a new ``bytes22`` type for %%v%%.
+     */
+    static bytes22(v: BytesLike): Typed { return b(v, 22); }
+
+    /**
+     *  Return a new ``bytes23`` type for %%v%%.
+     */
+    static bytes23(v: BytesLike): Typed { return b(v, 23); }
+
+    /**
+     *  Return a new ``bytes24`` type for %%v%%.
+     */
+    static bytes24(v: BytesLike): Typed { return b(v, 24); }
+
+    /**
+     *  Return a new ``bytes25`` type for %%v%%.
+     */
+    static bytes25(v: BytesLike): Typed { return b(v, 25); }
+
+    /**
+     *  Return a new ``bytes26`` type for %%v%%.
+     */
+    static bytes26(v: BytesLike): Typed { return b(v, 26); }
+
+    /**
+     *  Return a new ``bytes27`` type for %%v%%.
+     */
+    static bytes27(v: BytesLike): Typed { return b(v, 27); }
+
+    /**
+     *  Return a new ``bytes28`` type for %%v%%.
+     */
+    static bytes28(v: BytesLike): Typed { return b(v, 28); }
+
+    /**
+     *  Return a new ``bytes29`` type for %%v%%.
+     */
+    static bytes29(v: BytesLike): Typed { return b(v, 29); }
+
+    /**
+     *  Return a new ``bytes30`` type for %%v%%.
+     */
+    static bytes30(v: BytesLike): Typed { return b(v, 30); }
+
+    /**
+     *  Return a new ``bytes31`` type for %%v%%.
+     */
+    static bytes31(v: BytesLike): Typed { return b(v, 31); }
+
+    /**
+     *  Return a new ``bytes32`` type for %%v%%.
+     */
+    static bytes32(v: BytesLike): Typed { return b(v, 32); }
+
+
+    /**
+     *  Return a new ``address`` type for %%v%%.
+     */
+    static address(v: string | Addressable): Typed { return new Typed(_gaurd, "address", v); }
+
+    /**
+     *  Return a new ``bool`` type for %%v%%.
+     */
+    static bool(v: any): Typed { return new Typed(_gaurd, "bool", !!v); }
+
+    /**
+     *  Return a new ``bytes`` type for %%v%%.
+     */
+    static bytes(v: BytesLike): Typed { return new Typed(_gaurd, "bytes", v); }
+
+    /**
+     *  Return a new ``string`` type for %%v%%.
+     */
+    static string(v: string): Typed { return new Typed(_gaurd, "string", v); }
+
+
+    /**
+     *  Return a new ``array`` type for %%v%%, allowing %%dynamic%% length.
+     */
+    static array(v: Array<any | Typed>, dynamic?: null | boolean): Typed {
+        throw new Error("not implemented yet");
+        return new Typed(_gaurd, "array", v, dynamic);
+    }
+
+
+    /**
+     *  Return a new ``tuple`` type for %%v%%, with the optional %%name%%.
+     */
+    static tuple(v: Array<any | Typed> | Record<string, any | Typed>, name?: string): Typed {
+        throw new Error("not implemented yet");
+        return new Typed(_gaurd, "tuple", v, name);
+    }
+
+
+    /**
+     *  Return a new ``uint8`` type for %%v%%.
+     */
+    static overrides(v: Record<string, any>): Typed {
+        return new Typed(_gaurd, "overrides", Object.assign({ }, v));
+    }
+
+    /**
+     *  Returns true only if %%value%% is a [[Typed]] instance.
+     */
+    static isTyped(value: any): value is Typed {
+        return (value
+            && typeof(value) === "object"
+            && "_typedSymbol" in value
+            && value._typedSymbol === _typedSymbol);
+    }
+
+    /**
+     *  If the value is a [[Typed]] instance, validates the underlying value
+     *  and returns it, otherwise returns value directly.
+     *
+     *  This is useful for functions that with to accept either a [[Typed]]
+     *  object or values.
+     */
+    static dereference<T>(value: Typed | T, type: string): T {
+        if (Typed.isTyped(value)) {
+            if (value.type !== type) {
+                throw new Error(`invalid type: expecetd ${ type }, got ${ value.type }`);
+            }
+            return value.value;
+        }
+        return value;
+    }
+}