Some doc compatification

packages/evm/src/eof/constants.ts

@@ -6,31 +6,31 @@ export const MAGIC = 0x00
 export const VERSION = 0x01
 
 // The min/max sizes of valid headers
-export const MIN_HEADER_SIZE = 15 // This min size is used to invalidate an invalid container quickly
+export const MIN_HEADER_SIZE = 15 // Min size used to invalidate an invalid container quickly
 export const MAX_HEADER_SIZE = 49152 // Max initcode size, EIP 3860
 
-export const KIND_TYPE = 0x01 // The type byte of the types section
-export const KIND_CODE = 0x02 // The type byte of the code section
-export const KIND_CONTAINER = 0x03 // The type byte of the container section (this is the only optional section in the header)
-export const KIND_DATA = 0x04 // The type byte of the data section
-export const TERMINATOR = 0x00 // The terminator byte of the header
+export const KIND_TYPE = 0x01 // Type byte of types section
+export const KIND_CODE = 0x02 // Type byte of code section
+export const KIND_CONTAINER = 0x03 // Type byte of container section (the only optional section in the header)
+export const KIND_DATA = 0x04 // Type byte of  data section
+export const TERMINATOR = 0x00 // Terminator byte of header
 
-export const TYPE_MIN = 0x0004 // The minimum size of the types section
-export const TYPE_MAX = 0x1000 // The maximum size of the types section
-export const TYPE_DIVISOR = 4 // The divisor of types: the type section size should be a multiple of this
+export const TYPE_MIN = 0x0004 // Minimum size of types section
+export const TYPE_MAX = 0x1000 // Maximum size of types section
+export const TYPE_DIVISOR = 4 // Divisor of types: the type section size should be a multiple of this
 
-export const CODE_MIN = 0x0001 // The minimum size of the code section
+export const CODE_MIN = 0x0001 // Minimum size of code section
 
-export const CODE_SIZE_MIN = 1 // The minimum size of a code section in the body (the actual code)
+export const CODE_SIZE_MIN = 1 // Ninimum size of a code section in the body (the actual code)
 
-export const CONTAINER_MIN = 0x0001 // The minimum size of the container section
-export const CONTAINER_MAX = 0x0100 // The maximum size of the container section
+export const CONTAINER_MIN = 0x0001 // Minimum size of container section
+export const CONTAINER_MAX = 0x0100 // Maximum size of container section
 
-export const CONTAINER_SIZE_MIN = 1 // The minimum size of a container in the body
+export const CONTAINER_SIZE_MIN = 1 // Minimum size of a container in the body
 
 // Constants regarding the type section in the body of the container
-export const INPUTS_MAX = 0x7f // The maximum amounts of inputs to a code section in the body
-export const OUTPUTS_MAX = 0x80 // The maximum amounts of outputs of a code section in the body
-// Note: 0x80 is a special amount of outputs, this marks the code section as "terminating".
+export const INPUTS_MAX = 0x7f // Max inputs to a code section in the body
+export const OUTPUTS_MAX = 0x80 // Max outputs of a code section in the body
+// Note: 0x80 special amount, marks the code section as "terminating"
 // A terminating section will exit the current call frame, such as RETURN / STOP opcodes. It will not RETF to another code section
-export const MAX_STACK_HEIGHT = 0x03ff // The maximum stack height of a code section (this enforces that the stack of this section cannot overflow)
+export const MAX_STACK_HEIGHT = 0x03ff // Maximum stack height of a code section (enforces that the stack of this section cannot overflow)

packages/evm/src/eof/container.ts

@@ -132,18 +132,18 @@ class StreamReader {
  * The EOFHeader, describing the header of the EOF container
  */
 class EOFHeader {
-  typeSize: number // Size of the types section
-  codeSizes: number[] // Sizes of the code sections
-  containerSizes: number[] // Sizes of the containers
-  dataSize: number // Size of the data section
+  typeSize: number // Size of types section
+  codeSizes: number[] // Sizes of code sections
+  containerSizes: number[] // Sizes of containers
+  dataSize: number // Size of data section
   dataSizePtr: number // Used to edit the dataSize in RETURNCONTRACT
   buffer: Uint8Array // The raw buffer of the entire header
 
   private codeStartPos: number[] // Internal array to track at which byte of the container the code starts (per section)
 
   /**
    * Create an EOF header. Performs various validation checks inside the constructor
-   * @param input The input should either be a raw header, or a complete container
+   * @param input either a raw header or a complete container
    */
   constructor(input: Uint8Array) {
     if (input.length > MAX_HEADER_SIZE) {
@@ -157,7 +157,7 @@ class EOFHeader {
     if (input.length < 15) {
       throw new Error('err: container size less than minimum valid size')
     }
-    // Verify that the types section is present, and verify that the type section length is valid
+    // Verify that the types section is present and its length is valid
     stream.verifyUint(KIND_TYPE, EOFError.KIND_TYPE)
     const typeSize = stream.readUint16(EOFError.TypeSize)
     if (typeSize < TYPE_MIN) {
@@ -169,7 +169,7 @@ class EOFHeader {
     if (typeSize > TYPE_MAX) {
       throw new Error(`err: number of code sections must not exceed 1024 (got ${typeSize})`)
     }
-    // Verify that the code section is present, and verify that the code section size is valid
+    // Verify that the code section is present and its size is valid
     stream.verifyUint(KIND_CODE, EOFError.KIND_CODE)
     const codeSize = stream.readUint16(EOFError.CodeSize)
     if (codeSize < CODE_MIN) {
@@ -178,7 +178,7 @@ class EOFHeader {
     if (codeSize !== typeSize / TYPE_DIVISOR) {
       validationError(EOFError.TypeSections, typeSize / TYPE_DIVISOR, codeSize)
     }
-    // Read the actual code sizes in the code section, and verify that each code section has the minimum size
+    // Read the actual code sizes in the code section and verify that each section has the minimum size
     const codeSizes = []
     for (let i = 0; i < codeSize; i++) {
       const codeSectionSize = stream.readUint16(EOFError.CodeSection)
@@ -202,7 +202,7 @@ class EOFHeader {
         validationError(EOFError.ContainerSectionSize)
       }
 
-      // Read the actual container sections, and validate that each container section has the minimum size
+      // Read the actual container sections and validate that each section has the minimum size
       for (let i = 0; i < containerSectionSize; i++) {
         const containerSize = stream.readUint16(EOFError.ContainerSection)
 
@@ -277,19 +277,19 @@ export interface TypeSection {
  */
 class EOFBody {
   typeSections: TypeSection[] // Array of type sections, used to index the inputs/outputs/max stack height of each section
-  codeSections: Uint8Array[] // The bytecode of each code section
-  containerSections: Uint8Array[] // The raw container bytes of each subcontainer
+  codeSections: Uint8Array[] // Bytecode of each code section
+  containerSections: Uint8Array[] // Raw container bytes of each subcontainer
   entireCode: Uint8Array // The `entireCode` are all code sections concatenated
-  dataSection: Uint8Array // The bytes of the data section
-  buffer: Uint8Array // The raw bytes of the body
+  dataSection: Uint8Array // Bytes of the data section
+  buffer: Uint8Array // Raw bytes of the body
 
   txCallData?: Uint8Array // Only available in TxInitmode. The `txCallData` are the dangling bytes after parsing the container,
   // and these are used for the CALLDATA in the EVM when trying to create a contract via a transaction, and the deployment code is an EOF container
 
   constructor(
-    buf: Uint8Array, // The buffer of the body. This should be the entire body. It is not valid to pass an entire EOF container in here
-    header: EOFHeader, // The EOFHeader corresponding to this body
-    eofMode: EOFContainerMode = EOFContainerMode.Default, // The container mode of EOF
+    buf: Uint8Array, // Buffer of the body. This should be the entire body. It is not valid to pass an entire EOF container in here
+    header: EOFHeader, // EOFHeader corresponding to this body
+    eofMode: EOFContainerMode = EOFContainerMode.Default, // Container mode of EOF
     dataSectionAllowedSmaller = false, // Only for validation: Deployment containers are allowed to have smaller data section size
   ) {
     const stream = new StreamReader(buf)

packages/evm/src/eof/setup.ts

@@ -3,7 +3,7 @@ import { EOFContainer, EOFContainerMode } from './container.js'
 import type { RunState } from '../interpreter.js'
 
 /**
- * This method setups the EOF inside the EVM. It prepares the `RunState` to start running EVM in EOF mode
+ * Setup EOF by preparing the `RunState` to run EVM in EOF mode
  * @param runState Current run state
  * @param eofMode EOF mode to run in (only changes in case of EOFCREATE)
  */
@@ -15,13 +15,13 @@ export function setupEOF(runState: RunState, eofMode: EOFContainerMode = EOFCont
     },
   }
 
-  // In case that txCallData is set, then set the `callData` of the `env` to this calldata
-  // This ensures that CALLDATA can be read when deploying EOF contracts using transactions
+  // In case that txCallData is set, set the `callData` of `env` to this calldata
+  // This ensures that CALLDATA can be read when deploying EOF contracts using txs
   if (runState.env.eof.container.body.txCallData !== undefined) {
     runState.env.callData = runState.env.eof.container.body.txCallData
   }
 
-  // Set the program counter to the first code section
+  // Set program counter to the first code section
   const pc = runState.env.eof.container.header.getCodePosition(0)
   runState.programCounter = pc
 }

packages/evm/src/eof/util.ts

@@ -7,8 +7,8 @@ export const EOFBYTES = new Uint8Array([FORMAT, MAGIC])
 export const EOFHASH = keccak256(EOFBYTES)
 
 /**
- * Returns `true` if `code` is an EOF contract, returns `false` otherwise
- * @param code Code to test if it is EOF
+ * Returns `true` if `code` is an EOF contract, otherwise `false`
+ * @param code Code to test
  */
 export function isEOF(code: Uint8Array): boolean {
   const check = code.subarray(0, EOFBYTES.length)

packages/evm/src/eof/verify.ts

@@ -115,7 +115,7 @@ function validateOpcodes(
     opcodeNumbers.delete(op)
   }
 
-  // Note: this name might be misleading since this is the list of opcodes which are OK as final opcodes in a code section
+  // Note: Name might be misleading since this is the list of opcodes which are OK as final opcodes in a code section
   // TODO if using stackDelta for EOF it is possible to add a "termination" boolean for the opcode to mark it as terminating
   // (so no need to generate this set here)
   const terminatingOpcodes = new Set<number>()
@@ -166,11 +166,11 @@ function validateOpcodes(
     const stackHeightMin: number[] = [inputs]
     const stackHeightMax: number[] = [inputs]
 
-    // This loop will loop over the entire code section and will validate various rules
+    // Loop over the entire code section and validate various rules
     // For (most) validation rules, see https://github.com/ipsilon/eof/blob/main/spec/eof.md
     // For all validation rules per opcode, find the corresponding EIP, the rules are there
     while (ptr < code.length) {
-      // This set tracks the successor opcodes of this opcode (for stack purposes)
+      // Tracks the successor opcodes of this opcode (for stack purposes)
       const successorSet = new Set<number>()
 
       // ReachableOpcodes: this can likely be deleted after implementing the 5450 algorithm
@@ -179,8 +179,7 @@ function validateOpcodes(
       }
 
       if (stackHeightMin[ptr] === undefined || stackHeightMax[ptr] === undefined) {
-        // This error either means that the code is unreachable,
-        // or it is possible that it is only reachable via a backwards jump
+        // Code is either unreachable or only reachable via a backwards jump
         validationError(EOFError.UnreachableCode)
       }
 
@@ -230,8 +229,8 @@ function validateOpcodes(
 
         if (opcode === 0xe0) {
           // For RJUMP check that the instruction after RJUMP is reachable
-          // If this is not the case, then it is not yet targeted by a forward jump
-          // And hence violates the spec
+          // If not the case then it is not yet targeted by a forward jump
+          // and hence violates the spec
           if (!reachableOpcodes.has(ptr + 3) && ptr + 3 < code.length) {
             // Note: the final condition above ensures that the bytes after ptr are there
             // This is an edge case, if the container ends with RJUMP (which is valid)