There are many simple utilities required to interact with Ethereum and to simplify the library, without increasing the library dependencies for simple functions.
- Base58 Encoding
- Base64 Encoding
- Data Helpers
- Math Helpers
- Properties
- Recursive-Length Prefix
- Strings and UTF-8
- Unit Conversion
- UUID
The Base58 Encoding scheme allows a numeric value to be encoded as a compact string using a radix of 58 using only alpha-numeric characters. Confusingly similar characters are omitted (i.e. "l0O").
Note that Base58 encodes a numeric value, not arbitrary bytes, since any zero-bytes on the left would get removed. To mitigate this issue most schemes that use Base58 choose specific high-order values to ensure non-zero prefixes.
Decode the Base58-encoded value.
Base64 encoding using 6-bit words to encode arbitrary bytes into a string using 65 printable symbols, the upper-case and lower-case alphabet, the digits 0 through 9, "+" and "/" with the "=" used for padding.
Decodes the base-64 encoded value.
An object that can be used to represent binary data.
A HexString whose length is even, which ensures it is a valid representation of binary data.
A string which is prefixed with 0x and followed by any number of case-agnostic hexadecimal characters.
It must match the regular expression /0x[0-9A-Fa-f]*/.
Returns a DataHexString by concatenating all values within data.
Returns a DataHexString by slicing data from the start offset to the end offset.
By default start is 0 and end is the length of data.
Get a typed Uint8Array for value. If already a Uint8Array the original value is returned; if a copy is required use getBytesCopy.
Get a typed Uint8Array for value, creating a copy if necessary to prevent any modifications of the returned value from being reflected elsewhere.
Returns a DataHexString representation of data.
Returns true if value is a valid representation of arbitrary data (i.e. a valid DataHexString or a Uint8Array).
Returns true if value is a valid HexString.
If length is true or a number, it also checks that value is a valid DataHexString of length (if a number) bytes of data (e.g. 0x1234 is 2 bytes).
Return the DataHexString result by stripping all leading * zero bytes from data.
Return the DataHexString of data padded on the right to length bytes.
If data already exceeds length, a BufferOverrun is thrown.
This pads data the same as bytes are in Solidity (e.g. bytes16).
Return the DataHexString of data padded on the left to length bytes.
If data already exceeds length, a BufferOverrun is thrown.
This pads data the same as values are in Solidity (e.g. uint128).
Any type that can be used where a numeric value is needed.
Convert value from a twos-compliment representation of width bits to its value.
If the highest bit is 1, the result will be negative.
Gets a BigInt from value. If it is an invalid value for a BigInt, then an ArgumentError will be thrown for name.
Gets a number from value. If it is an invalid value for a number, then an ArgumentError will be thrown for name.
Mask value with a bitmask of bits ones.
Converts value to a Big Endian Uint8Array.
Converts value to a Big Endian hexstring, optionally padded to width bytes.
Converts value to a number. If value is a Uint8Array, it is treated as Big Endian data. Throws if the value is not safe.
Returns a HexString for value safe to use as a Quantity.
A Quantity does not have and leading 0 values unless the value is the literal value `0x0`. This is most commonly used for JSSON-RPC numeric values.
Convert value to a twos-compliment representation of width bits.
The result will always be positive.
Assigns the values to target as read-only values.
It types is specified, the values are checked.
Resolves to a new object that is a copy of value, but with all values resolved.
The Recursive-Length Prefix (RLP) encoding is used throughout Ethereum to serialize nested structures of Arrays and data.
An RLP-encoded structure.
Decodes data into the structured data it represents.
Encodes object as an RLP-encoded DataHexString.
Using strings in Ethereum (or any security-basd system) requires additional care. These utilities attempt to mitigate some of the safety issues as well as provide the ability to recover and analyse strings.
The stanard normalization forms.
A callback that can be used with toUtf8String to analysis or recovery from invalid UTF-8 data.
Parsing UTF-8 data is done through a simple Finite-State Machine (FSM) which calls the Utf8ErrorFunc if a fault is detected.
The reason indicates where in the FSM execution the fault occurred and the offset indicates where the input failed.
The bytes represents the raw UTF-8 data that was provided and output is the current array of UTF-8 code-points, which may be updated by the Utf8ErrorFunc.
The value of the badCodepoint depends on the reason. See Utf8ErrorReason for details.
The function should return the number of bytes that should be skipped when control resumes to the FSM.
When using the UTF-8 error API the following errors can be intercepted and processed as the reason passed to the Utf8ErrorFunc.
"UNEXPECTED_CONTINUE" - a continuation byte was present where there was nothing to continue.
"BAD_PREFIX" - an invalid (non-continuation) byte to start a UTF-8 codepoint was found.
"OVERRUN" - the string is too short to process the expected codepoint length.
"MISSING_CONTINUE" - a missing continuation byte was expected but not found. The offset indicates the index the continuation byte was expected at.
"OUT_OF_RANGE" - the computed code point is outside the range for UTF-8. The badCodepoint indicates the computed codepoint, which was outside the valid UTF-8 range.
"UTF16_SURROGATE" - the UTF-8 strings contained a UTF-16 surrogate pair. The badCodepoint is the computed codepoint, which was inside the UTF-16 surrogate range.
"OVERLONG" - the string is an overlong representation. The badCodepoint indicates the computed codepoint, which has already been bounds checked.
Returns the UTF-8 byte representation of str.
If form is specified, the string is normalized.
Returns the UTF-8 code-points for str.
If form is specified, the string is normalized.
Returns the string represented by the UTF-8 data bytes.
When onError function is specified, it is called on UTF-8 errors allowing recovery using the Utf8ErrorFunc API. (default: error)
Most interactions with Ethereum requires integer values, which use the smallest magnitude unit.
For example, imagine dealing with dollars and cents. Since dollars are divisible, non-integer values are possible, such as $10.77. By using the smallest indivisible unit (i.e. cents), the value can be kept as the integer 1077.
When receiving decimal input from the user (as a decimal string), the value should be converted to an integer and when showing a user a value, the integer value should be converted to a decimal string.
This creates a clear distinction, between values to be used by code (integers) and values used for display logic to users (decimals).
The native unit in Ethereum, ether is divisible to 18 decimal places, where each individual unit is called a wei.
Converts value into a decimal string using 18 decimal places.
Converts value into a decimal string, assuming unit decimal places. The unit may be the number of decimal places or the name of a unit (e.g. "gwei" for 9 decimal places).
Converts the decimal string ether to a BigInt, using 18 decimal places.