Configure Typedoc for @truffle/codec

packages/codec/lib/allocate/abi.ts

@@ -10,8 +10,8 @@ import { EVM } from "../utils/evm";
 import { getterInputs } from "../utils/definition2abi";
 import * as AbiTypes from "../types/abi";
 import { AstDefinition, AstReferences } from "../types/ast";
-import { Types } from "../format/types";
-import { UnknownBaseContractIdError, UnknownUserDefinedTypeError } from "../types/errors";
+import { Types } from "../format";
+import { UnknownUserDefinedTypeError } from "../types/errors";
 import partition from "lodash.partition";
 import { DecodingMode } from "../types/decoding";
 import { CompilerVersion } from "../types/compiler";

packages/codec/lib/allocate/storage.ts

@@ -5,13 +5,30 @@ import { StoragePointer } from "../types/pointer";
 import { StorageAllocations, StorageAllocation, StorageMemberAllocation } from "../types/allocation";
 import { StorageLength, Range } from "../types/storage";
 import { isWordsLength } from "../utils/storage";
-import { UnknownBaseContractIdError, UnknownUserDefinedTypeError, DecodingError } from "../types/errors";
+import { UnknownUserDefinedTypeError } from "../types/errors";
+import { DecodingError } from "../decode/errors";
 import { AstDefinition, AstReferences } from "../types/ast";
 import * as CodecUtils from "../utils";
 import { TypeUtils } from "../utils";
 import * as Format from "../format";
 import BN from "bn.js";
 
+export class UnknownBaseContractIdError extends Error {
+  public derivedId: number;
+  public derivedName: string;
+  public derivedKind: string;
+  public baseId: number;
+  constructor(derivedId: number, derivedName: string, derivedKind: string, baseId: number) {
+    const message = `Cannot locate base contract ID ${baseId} of ${derivedKind} ${derivedName} (ID ${derivedId})`;
+    super(message);
+    this.name = "UnknownBaseContractIdError";
+    this.derivedId = derivedId;
+    this.derivedName = derivedName;
+    this.derivedKind = derivedKind;
+    this.baseId = baseId;
+  }
+}
+
 interface StorageAllocationInfo {
   size: StorageLength;
   allocations: StorageAllocations;
@@ -98,7 +115,7 @@ function allocateMembers(parentNode: AstDefinition, definitions: DefinitionPair[
         offset += 1;
     }
     //otherwise, we remain in place
-  
+
     let range: Range;
 
     if(isWordsLength(size)) {
@@ -214,7 +231,7 @@ function allocateContract(contract: AstDefinition, referenceDeclarations: AstRef
     );
   }));
 
-  return allocateMembers(contract, vars, referenceDeclarations, existingAllocations, true); 
+  return allocateMembers(contract, vars, referenceDeclarations, existingAllocations, true);
     //size is not meaningful for contracts, so we pass suppressSize=true
 }
 

packages/codec/lib/core/decoding.ts

@@ -8,7 +8,7 @@ import { Types, Values } from "../format";
 import * as AbiTypes from "../types/abi";
 import * as Pointer from "../types/pointer";
 import { EvmInfo } from "../types/evm";
-import { StopDecodingError } from "../types/errors";
+import { StopDecodingError } from "../decode/errors";
 import { DecoderRequest } from "../types/request";
 import { CalldataAllocation, EventAllocation, EventArgumentAllocation } from "../types/allocation";
 import { CalldataDecoding, LogDecoding, AbiArgument, DecodingMode } from "../types/decoding";
@@ -75,7 +75,7 @@ export function* decodeCalldata(info: EvmInfo): Generator<DecoderRequest, Callda
         dataType,
         argumentAllocation.pointer,
         info,
-        { 
+        {
           abiPointerBase: allocation.offset, //note the use of the offset for decoding pointers!
           allowRetry: decodingMode === "full"
         }

packages/codec/lib/decode/abi.ts

@@ -13,7 +13,7 @@ import { abiSizeInfo } from "../allocate/abi";
 import { EvmInfo } from "../types/evm";
 import { DecoderOptions } from "../types/options";
 import { DecoderRequest } from "../types/request";
-import { DecodingError, StopDecodingError } from "../types/errors";
+import { DecodingError, StopDecodingError } from "../decode/errors";
 
 type AbiLocation = "calldata" | "eventdata"; //leaving out "abi" as it shouldn't occur here
 
@@ -79,7 +79,7 @@ export function* decodeAbiReferenceByAddress(dataType: Types.ReferenceType | Typ
     rawValueAsNumber = rawValueAsBN.toNumber();
   }
   catch(_) {
-    let error = { 
+    let error = {
       kind: "OverlargePointersNotImplementedError" as const,
       pointerAsBN: rawValueAsBN,
     };
@@ -149,7 +149,7 @@ export function* decodeAbiReferenceByAddress(dataType: Types.ReferenceType | Typ
         //just to prevent huge numbers from DOSing us, other errors will still
         //be caught regardless
         throw new StopDecodingError(
-          { 
+          {
             kind: "OverlongArrayOrStringStrictModeError" as const,
             lengthAsBN,
             dataLength: state[location].length
@@ -215,7 +215,7 @@ export function* decodeAbiReferenceByAddress(dataType: Types.ReferenceType | Typ
         //just to prevent huge numbers from DOSing us, other errors will still
         //be caught regardless
         throw new StopDecodingError(
-          { 
+          {
             kind: "OverlongArraysAndStringsNotImplementedError" as const,
             lengthAsBN,
             dataLength: state[location].length
@@ -270,7 +270,7 @@ export function* decodeAbiReferenceByAddress(dataType: Types.ReferenceType | Typ
           )
         ); //pointer base is always start of list, never the length
       }
-      return { 
+      return {
         type: dataType,
         kind: "value" as const,
         value: decodedChildren
@@ -302,7 +302,7 @@ export function* decodeAbiReferenceStatic(dataType: Types.ReferenceType | Types.
         //strict-mode guard against getting DOSed by large array sizes, since in this
         //case we're not reading the size from the input; if there's a huge static size
         //array, well, we'll just have to deal with it
-        let error = { 
+        let error = {
           kind: "OverlongArraysAndStringsNotImplementedError" as const,
           lengthAsBN
         };
@@ -344,7 +344,7 @@ export function* decodeAbiReferenceStatic(dataType: Types.ReferenceType | Types.
           )
         );
       }
-      return { 
+      return {
         type: dataType,
         kind: "value" as const,
         value: decodedChildren
@@ -419,7 +419,7 @@ function* decodeAbiStructByPosition(dataType: Types.StructType, location: AbiLoc
       //note that the base option is only needed in the dynamic case, but we're being indiscriminate
     });
   }
-  return { 
+  return {
     type: dataType,
     kind: "value" as const,
     value: decodedMembers
@@ -449,7 +449,7 @@ function* decodeAbiTupleByPosition(dataType: Types.TupleType, location: AbiLocat
     });
     position += memberSize;
   }
-  return { 
+  return {
     type: dataType,
     kind: "value" as const,
     value: decodedMembers

packages/codec/lib/decode/constant.ts

@@ -8,7 +8,7 @@ import decodeValue from "./value";
 import { ConstantDefinitionPointer} from "../types/pointer";
 import { EvmInfo } from "../types/evm";
 import { DecoderRequest } from "../types/request";
-import { DecodingError } from "../types/errors";
+import { DecodingError } from "../decode/errors";
 import BN from "bn.js";
 
 export default function* decodeConstant(dataType: Types.Type, pointer: ConstantDefinitionPointer, info: EvmInfo): Generator<DecoderRequest, Values.Result, Uint8Array> {

packages/codec/lib/decode/errors.ts

@@ -0,0 +1,33 @@
+import { Errors } from "../format";
+import { message } from "../utils/errors";
+
+//For when we need to throw an error, here's a wrapper class that extends Error.
+//Apologies about the confusing name, but I wanted something that would make
+//sense should it not be caught and thus accidentally exposed to the outside.
+export class DecodingError extends Error {
+  public error: Errors.ErrorForThrowing;
+  constructor(error: Errors.ErrorForThrowing) {
+    super(message(error));
+    this.error = error;
+    this.name = "DecodingError";
+  }
+}
+
+//used to stop decoding; like DecodingError, but used in contexts
+//where I don't expect it to be caught
+//NOTE: currently we don't actually check the type of a thrown error,
+//we just rely on context.  still, I think it makes sense to be a separate
+//type.
+export class StopDecodingError extends Error {
+  public error: Errors.DecoderError;
+  public allowRetry: boolean; //setting this to true means that, if the error occurs
+  //when decoding in full mode, we allow an ABI-mode retry.  (if we were already in
+  //ABI mode, we give up.)
+  constructor(error: Errors.DecoderError, allowRetry?: boolean) {
+    const message = `Stopping decoding: ${error.kind}`; //sorry about the bare-bones message,
+    //but again, users shouldn't actually see this, so I think this should suffice for now
+    super(message);
+    this.error = error;
+    this.allowRetry = Boolean(allowRetry);
+  }
+}

packages/codec/lib/decode/event.ts

@@ -9,7 +9,7 @@ import { EventTopicPointer } from "../types/pointer";
 import { EvmInfo } from "../types/evm";
 import { DecoderOptions } from "../types/options";
 import { DecoderRequest } from "../types/request";
-import { StopDecodingError } from "../types/errors";
+import { StopDecodingError } from "../decode/errors";
 
 export default function* decodeTopic(dataType: Types.Type, pointer: EventTopicPointer, info: EvmInfo, options: DecoderOptions = {}): Generator<DecoderRequest, Values.Result, Uint8Array> {
   if(TypeUtils.isReferenceType(dataType)) {

packages/codec/lib/decode/memory.ts

@@ -11,7 +11,7 @@ import { MemoryPointer, DataPointer } from "../types/pointer";
 import { MemoryMemberAllocation } from "../types/allocation";
 import { EvmInfo } from "../types/evm";
 import { DecoderRequest } from "../types/request";
-import { DecodingError } from "../types/errors";
+import { DecodingError } from "../decode/errors";
 
 export default function* decodeMemory(dataType: Types.Type, pointer: MemoryPointer, info: EvmInfo): Generator<DecoderRequest, Values.Result, Uint8Array> {
   if(TypeUtils.isReferenceType(dataType)) {

packages/codec/lib/decode/stack.ts

@@ -13,7 +13,7 @@ import { decodeAbiReferenceByAddress } from "./abi";
 import { StackPointer, StackLiteralPointer } from "../types/pointer";
 import { EvmInfo } from "../types/evm";
 import { DecoderRequest } from "../types/request";
-import { DecodingError } from "../types/errors";
+import { DecodingError } from "../decode/errors";
 
 export default function* decodeStack(dataType: Types.Type, pointer: StackPointer, info: EvmInfo): Generator<DecoderRequest, Values.Result, Uint8Array> {
   let rawValue: Uint8Array;

packages/codec/lib/decode/storage.ts

@@ -13,7 +13,7 @@ import * as StorageTypes from "../types/storage";
 import { isWordsLength, slotAddress } from "../utils/storage";
 import BN from "bn.js";
 import { DecoderRequest } from "../types/request";
-import { DecodingError } from "../types/errors";
+import { DecodingError } from "../decode/errors";
 
 export default function* decodeStorage(dataType: Types.Type, pointer: StoragePointer, info: EvmInfo): Generator<DecoderRequest, Values.Result, Uint8Array> {
   if(TypeUtils.isReferenceType(dataType)) {
@@ -137,7 +137,7 @@ export function* decodeStorageReference(dataType: Types.ReferenceType, pointer:
         };
       }
       debug("baseSize %o", baseSize);
-      
+
       //we are going to make a list of child ranges, pushing them one by one onto
       //this list, and then decode them; the first part will vary based on whether
       //we're in the words case or the bytes case, the second will not

packages/codec/lib/decode/value.ts

@@ -12,7 +12,7 @@ import { DataPointer } from "../types/pointer";
 import { EvmInfo } from "../types/evm";
 import { DecoderOptions } from "../types/options";
 import { DecoderRequest } from "../types/request";
-import { DecodingError, StopDecodingError } from "../types/errors";
+import { DecodingError, StopDecodingError } from "../decode/errors";
 import { ContractInfoAndContext } from "../types/decoding";
 
 export default function* decodeValue(dataType: Types.Type, pointer: DataPointer, info: EvmInfo, options: DecoderOptions = {}): Generator<DecoderRequest, Values.Result, Uint8Array> {
@@ -59,7 +59,7 @@ export default function* decodeValue(dataType: Types.Type, pointer: DataPointer,
         };
       }
       else {
-        let error = { 
+        let error = {
           kind: "BoolOutOfRangeError" as const,
           rawAsBN: numeric
         };
@@ -77,7 +77,7 @@ export default function* decodeValue(dataType: Types.Type, pointer: DataPointer,
     case "uint":
       //first, check padding (if needed)
       if(!permissivePadding && !checkPaddingLeft(bytes, dataType.bits/8)) {
-        let error = { 
+        let error = {
           kind: "UintPaddingError" as const,
           raw: CodecUtils.Conversion.toHexString(bytes)
         };
@@ -103,7 +103,7 @@ export default function* decodeValue(dataType: Types.Type, pointer: DataPointer,
     case "int":
       //first, check padding (if needed)
       if(!permissivePadding && !checkPaddingSigned(bytes, dataType.bits/8)) {
-        let error = { 
+        let error = {
           kind: "IntPaddingError" as const,
           raw: CodecUtils.Conversion.toHexString(bytes)
         };
@@ -129,7 +129,7 @@ export default function* decodeValue(dataType: Types.Type, pointer: DataPointer,
 
     case "address":
       if(!permissivePadding && !checkPaddingLeft(bytes, CodecUtils.EVM.ADDRESS_SIZE)) {
-        let error = { 
+        let error = {
           kind: "AddressPaddingError" as const,
           raw: CodecUtils.Conversion.toHexString(bytes)
         };
@@ -153,7 +153,7 @@ export default function* decodeValue(dataType: Types.Type, pointer: DataPointer,
 
     case "contract":
       if(!permissivePadding && !checkPaddingLeft(bytes, CodecUtils.EVM.ADDRESS_SIZE)) {
-        let error = { 
+        let error = {
           kind: "ContractPaddingError" as const,
           raw: CodecUtils.Conversion.toHexString(bytes)
         };
@@ -179,7 +179,7 @@ export default function* decodeValue(dataType: Types.Type, pointer: DataPointer,
         case "static":
           //first, check padding (if needed)
           if(!permissivePadding && !checkPaddingRight(bytes, dataType.length)) {
-            let error = { 
+            let error = {
               kind: "BytesPaddingError" as const,
               raw: CodecUtils.Conversion.toHexString(bytes)
             };
@@ -225,7 +225,7 @@ export default function* decodeValue(dataType: Types.Type, pointer: DataPointer,
       switch(dataType.visibility) {
         case "external":
           if(!checkPaddingRight(bytes, CodecUtils.EVM.ADDRESS_SIZE + CodecUtils.EVM.SELECTOR_SIZE)) {
-            let error = { 
+            let error = {
               kind: "FunctionExternalNonStackPaddingError" as const,
               raw: CodecUtils.Conversion.toHexString(bytes)
             };
@@ -334,7 +334,7 @@ export default function* decodeValue(dataType: Types.Type, pointer: DataPointer,
     case "fixed": {
       //first, check padding (if needed)
       if(!permissivePadding && !checkPaddingSigned(bytes, dataType.bits/8)) {
-        let error = { 
+        let error = {
           kind: "FixedPaddingError" as const,
           raw: CodecUtils.Conversion.toHexString(bytes)
         };
@@ -365,7 +365,7 @@ export default function* decodeValue(dataType: Types.Type, pointer: DataPointer,
     case "ufixed": {
       //first, check padding (if needed)
       if(!permissivePadding && !checkPaddingLeft(bytes, dataType.bits/8)) {
-        let error = { 
+        let error = {
           kind: "UfixedPaddingError" as const,
           raw: CodecUtils.Conversion.toHexString(bytes)
         };

packages/codec/lib/encode/abi.ts

@@ -1,7 +1,7 @@
 import debugModule from "debug";
 const debug = debugModule("codec:encode:abi");
 
-import { Values } from "../format/values";
+import { Values } from "../format";
 import { Conversion as ConversionUtils } from "../utils/conversion";
 import { EVM as EVMUtils } from "../utils/evm";
 import { AbiAllocations, AbiSizeInfo } from "../types/allocation";

packages/codec/lib/encode/key.ts

@@ -1,7 +1,7 @@
 import debugModule from "debug";
 const debug = debugModule("codec:encode:key");
 
-import { Values } from "../format/values";
+import { Values } from "../format";
 import { Conversion as ConversionUtils } from "../utils/conversion";
 import { EVM as EVMUtils } from "../utils/evm";
 import { stringToBytes } from "./abi";