eulith-web3js-core

import BN from "bn"; import * as Eulith from "../src/index"; /** * Module for code relating to (mostly ERC20) tokens. */ export declare module Tokens { /** * The Symbols enumeration lists the ERC20 symbol (property of the contract) values associated with * some common ERC20 token contracts. * * Historical Note: Cloned from erc20.py TokenSymbol */ enum Symbols { USDT = "USDT", BNB = "BNB", USDC = "USDC", BUSD = "BUSD", MATIC = "MATIC", STETH = "stETH", WETH = "WETH", LDO = "LDO", CRV = "CRV", CVX = "CVX", BAL = "BAL", BADGER = "BADGER", ONEINCH = "1INCH", UNI = "UNI", LINK = "LINK", APE = "APE", GMT = "GMT", WBTC = "WBTC", LUSD = "LUSD", FRAX = "FRAX", CBETH = "cbETH", GALA = "GALA", HEX = "HEX", RPL = "RPL", DYDX = "DYDX", BONE = "BONE", LOOKS = "LOOKS", AGEUR = "agEUR", OSQTH = "oSQTH", WSTETH = "wstETH", ALBT = "ALBT" } /** * Eulith.Token.getTokenContract - erc20-token-based smart contract factory * * Return the ERC20based token contract object, for the given symbol. * * This function always returns a valid ERC20 contract, or raises an exception. * * This function requires a valid 'provider' (which is bound to the returned contract), * and EITHER an valid symbol, or contract address (from which the symbol can be retrieved). * * See also Eulith.Contracts.ERC20TokenContract - if you don't have a 'symbol' - but an address/etc for the contract. * * \note - this replaces Eulith.Web3.getERCToken() */ function getTokenContract({ provider, symbol, address }: { provider: Eulith.Provider; symbol?: Symbols; address?: string; }): Promise<Eulith.Contracts.ERC20TokenContract | Eulith.Contracts.WethTokenContract>; /** * The API for web3js is somewhat confusing/flexible about units. These utility classes * make easier converting a particular value to/from its web/wire format, and to/from a * sensible numeric value in that tokens 'base' units. * * \note It would be nice to support operator overloading, and conversion operators and such * but this appears to be a weakness in typescript, that it doesn't support this (making a utility like this * far less useful) */ module Value { /** * Abstract API to capture basic interoperation of token values as exchanged. * * One key idea here - is that for ITokenValue, there are two BASIC NUMBERS you can get. * o the value in its basic atomic (fundemental) units * o and the value in its native (e.g. WETH or UDSC etc) ERC20 units. * * Then there is the ORTHOGANAL issue of how you represent that number (float, or hex string). * * It turns out - the ONLY use for the hex strings, are in fundemental units, (wire format) - * so thats the only case where we offer that representation type. Similarly, BigNum's are used * essentially always for the fundemental representation (atomic units) - so this is the prefered * data format for the fundemental representation. * * @todo DISCUSS if ITokenValue should have a readonly 'units' string property, optional, * for documentation purposes (asDisplayString method). MIGHT BE USEFUL to track * difference between ETH and USDC token values. Interoperable, but thats probably unfortunate. * * @todo DISCUSS if ITokenValue should have a readonly 'decimals' value. It has this IMPLICITLY because * of the covnersion between asFloat and asFundamentalFloat (decimals==log(asFundamentalFloat/asFloat)) */ interface ITokenValue { /** * Return the value as a native javascript number, in the units of this currency * * NOTE - this conversion to a javascript number can be lossy. * * \note - we cannot return the ERC20 token representation as BN, or BigInt, because * this will frequently be a fractional (decimal) quantity in the native token units (like USDC, or WETH). * * @todo IMHO, our use of the term 'Float' in this API could reasonably be replaced with 'Number', and would fit better * with JS - @Kristian */ get asFloat(): number; /** * Returns the token value in the native form as it goes over the wire to/from the ethereum network/contract. * * This is equivilent to asFundamentalHex */ get asWire(): string; /** * Returns the token value as an integral # float in the Fundamental (atomic) units */ get asFundamentalFloat(): number; /** * Returns the token value as an integral # BN (old BigNumber API) in the Fundamental (atomic) units * * \note - BN used internally by web3js as of 1.8.x */ get asFundamentalBN(): BN; /** * Returns the token value as an integral # BigInt (NEW BigNumber API) in the Fundamental (atomic) units */ get asFundamentalBigInt(): bigint; /** * Returns the token value as a hex string in the fundamental (atomic) units */ get asFundamentalHex(): string; /** * Return the symbol associated with this token value (from ERC20 symbol API) */ get symbol(): string; /** * Returns the number in natural (not atomic/fundemental) units, with the label of the symbol. * * Example: * 23.4 WETH * 18.45 USDC */ get asDisplayString(): string; /** * Returns a cloned value, but with the new value. newV type interpretation same as the * value constructor (number intrinsic value, BigInt fundemental, and string fundemental) * * Useful for arithmatic (like / 2) * */ cloneWithNewValue(newV: number | string | bigint): ITokenValue; } /** * An ETH token value is NOT an ERC20 compatible token value, but rather a value from the native blockchain. */ class ETH implements ITokenValue { private fundementalValue_; /** * if v is a number, its interpretted in ether units * if v is a string or bigint, its interpretted as being in fundamental units (wei). */ constructor(v: number | string | bigint); /** * Return the value as a native javascript number, in the units of this currency (ETH) */ get asFloat(): number; get asWire(): string; get asFundamentalFloat(): number; get asFundamentalBN(): BN; get asFundamentalHex(): string; get asFundamentalBigInt(): bigint; get asWeiBN(): BN; get asWeiHex(): string; get asWeiBigInt(): bigint; get symbol(): string; get asDisplayString(): string; cloneWithNewValue(newV: number | string | bigint): ITokenValue; } /** * Eulith.Tokens.Value.ERC20 is an object that refers to a value of a token from an ERC20 * contract (see https://eips.ethereum.org/EIPS/eip-20). * * This contains a number, and a level of precision, used when converting to the native form. */ class ERC20 implements ITokenValue { private fundementalValue_; private toWireFactor_; private symbol_; private decimals_; /** * if v is a number, its interpretted in ERC20 token units * if v is a string | BigInt, its interpretted as being in fundamental units. */ constructor({ v, decimals, contract, symbol }: { v: number | string | bigint | ITokenValue; decimals?: number; symbol?: string; contract?: Eulith.Contracts.ERC20TokenContract; }); get asFloat(): number; get asWire(): string; get asFundamentalHex(): string; get asFundamentalBN(): BN; get asFundamentalBigInt(): bigint; get asFundamentalFloat(): number; get symbol(): string; get asDisplayString(): string; cloneWithNewValue(newV: number | string | bigint): ITokenValue; } /** * @todo DISCUSS IF THIS SHOULD BE DEPRECATED? IMHO NO, but Kristian at one point I think thought it should... */ class USDC extends ERC20 { constructor(v: number | string); } /** * Really BEST word here would be Atomic, but too risky of confusion with atomic in "Atomic Transactions" * * This is the smallest indivisible unit of money for a given ERC20 token. */ class Fundamental extends ERC20 { constructor(v: number | string); } } }