@truffle/codec

/** * # Codec Output Format * * ## Module information * * This module primarily defines TypeScript types for the output format * used in results provided by packages * `@truffle/decoder@>=4.0.0` and `@truffle/codec@>=0.1.0`. * * See below for complete listing or continue reading * [Format information](#format-information) to learn about this format. * * ### How to import * * Import either as part of Codec or by itself: * * ```typescript * // when importing entire Codec, use Codec.Format.*: * import * as Codec from "@truffle/codec"; * * // or import Format directly: * import { Format } from "@truffle/codec"; * ``` * * ![Example struct decoding](media://example-struct-decoding.png) * * ## Format information * * This format is intended for use in smart contract and dapp development * tools and libraries, and for use in display contexts, such as when * building on-screen components to show transaction and smart contract * state information. * * This format seeks to provide an exhaustive schema for JavaScript * objects to encode **lossless**, **machine-readable** representations of * all possible Solidity and ABI data types and all possible values of those * types. * * This format targets types and values understood by the * [Solidity programming language](https://docs.soliditylang.org/) and * the [Contract ABI specification](https://docs.soliditylang.org/en/v0.8.19/abi-spec.html), * within the context of the [Ethereum Virtual Machine](https://ethereum.github.io/yellowpaper/paper.pdf) * (EVM) and in raw data for transactions and logs according to the * [Ethereum JSON RPC](https://github.com/ethereum/wiki/wiki/JSON-RPC). * * Objects in this format may be deeply nested and/or contain circular * dependencies. As such, **do not** serialize objects in this format or * otherwise attempt to display them in full without considering potential * risk. **Objects in this format are for the machine to read, not humans!** * This module provides utilities for inspecting objects in this format, * including the **safe** [[Format.Utils.Inspect.ResultInspector]] wrapper * (for [util.inspect](https://nodejs.org/api/util.html#util_util_inspect_object_options)), * and the **unsafe** [[Format.Utils.Inspect.unsafeNativize]] function. For more * information, please see the documentation for those utilities. * * ### Specification * * Individual decoded values are represented by objects of the type * [[Format.Values.Result]], which contain the following fields: * 1. `type`: This is a [[Format.Types.Type|`Type`]] object describing the value's * type. Each `Type` has a `typeClass` field describing the overall broad type, * such as `"uint"` or `"bytes"`, together with additional information that gives * the specific type. For full detail, see [[Format.Types]]. * * 2. `kind`: This is either `"value"`, in which case the `Result` is a * [[Format.Values.Value|`Value`]], or `"error"`, in which case the `Result` is an * [[Format.Errors.ErrorResult|`ErrorResult`]]. In the former case, there will be * a `value` field containin the decoded value. In the latter case, there will be * an `error` field indicating what went wrong. *Warning*: When decoding a * complex type, such as an array, mapping, or array, getting a kind of `"value"` * does not necessarily mean the individual elements were decoded successfully. * Even if the `Result` for the array (mapping, struct) as a whole has kind * `"value"`, the elements might still have kind `"error"`. * * 3. `value`: As mentioned, this is included when `kind` is equal to `"value"`. * It contains information about the actual decoded value. See * [[Format.Values|`Format.Values`]] for more information. * * 4. `error`: The alternative to `value`. Generally includes information about * the raw data that led to the error. See [[Format.Errors|`Format.Errors`]] for * more information. * * 5. `interpretations`: This field will also be present when `kind` is equal * to `"value"`; it is an object that may contain additional information * about the decoded value beyond what is found in `value`. (All fields in * `interpretations` are always optional and will be included only when * applicable.) You may wonder, what is the difference between `value` * and `interpretations`? The answer is that the distinction is largely * historical; `interpretations` was not originally part of the format, and * it was added so that there would be a place to put new additional * information we wanted to include without having to expand `value`. See * [[Format.Values|`Format.Values`]] for more information. * * 6. `reference`: This field is a debugger-only feature and does not * apply to results returned by @truffle/decoder, so it won't be documented here. * * ### Values vs. errors * * It's worth taking a moment here to answer the question: What counts as a value, * and what counts as an error? * * In general, the answer is that anything that can be generated via Solidity * alone (i.e. no assembly), with correctly-encoded inputs, and without making use * of compiler bugs, is a value, not an error. That means that, for instance, the * following things are values, not errors: * - A variable of contract type whose address does not actually hold a * contract of that type; * - An external function pointer that does not correspond to a valid * function; * - A string containing invalid UTF-8; * - ..., etc. * * By contrast, the following *are* errors: * - A `bool` which is neither `false` (0) nor `true` (1); * - An `enum` which is out of range; * - ..., etc. * * (You may be wondering about the enum case here, because if you go sufficiently * far back, to Solidity 0.4.4 or earlier, it *was* possible to generate * out-of-range enums without resorting to assembly or compiler bugs. However, * enums are only supported in full mode (see * [Notes on decoding modes](../#decoding-modes)), * which only supports 0.4.12 and later, so * we consider out-of-range enums an error. There are also additional technical * reasons why supporting out-of-range enums as a value would be difficult.) * * There are three special cases here that are likely worthy of note. * * Firstly, internal function pointers currently can't be meaningfully * decoded via @truffle/decoder. However, they decode to a bare-bones value, * not an error, as it is (in a sense) our own fault that we can't decode * these, so it doesn't make sense to report an error, which would mean that * something is wrong with the encoded data itself. This value that it * decodes to will give the program counter values it corresponds to, but * will not include the function name or defining class, as @truffle/decoder * is not presently capable of that. For now, full decoding of internal * function pointers remains a debugger-only feature. (But limited support for * this via @truffle/decoder is planned for the future.) * * (When using the debugger, an invalid internal function pointer will decode to an * error. However, when using @truffle/decoder, we have no way of discerning whether * the pointer is valid or not, so internal function pointers will always decode to * a value, if an uninformative one.) * * Secondly, when decoding events, it is impossible to decode indexed parameters * of reference type. Thus, these decode to an error * (`IndexedReferenceTypeError`, which see) rather than to a value. * * Thirdly, the decoder is currently limited when it comes to decoding state * variables that are declared constant, and not all such variables are yet * supported in decoding; attempting to decode one of these that is not currently * supported will yield an error. * * Similarly, there are various things that decode to errors for technical reasons. * Objects with encoded length fields larger than what fits in a JavaScript safe * integer, or pointed to by pointers with values larger than what fits in a * JavaScript safe integer, will decode to errors, even if they may technically be * legal. Such cases are impractical to handle and should never come up in real * use so we decode them to errors. Errors may also be returned in case of an * error in attempting to read the data to be decoded. * * Finally, except when decoding events, we do not return an error if the pointers * in an ABI-encoded array or tuple are arranged in a nonstandard way, or if * strings or bytestrings are incorrectly padded, because it is not worth the * trouble to detect these conditions. * * * ## Notes on this documentation * * Most of this doesn't have explanatory documentation * because it's largely self-explanatory, but particularly * non-obvious parts have been documented for clarity. * * A note on optional fields: A number of types or values * have optional fields. These contain helpful * but non-essential information, or information which * for technical reasons we can't guarantee we can determine. * * @category Data * * @packageDocumentation */ import { Types, Values, Errors } from "./common"; import * as Utils from "./utils"; export { Types, Values, Errors, Utils };