diff --git a/packages/evm/src/eof/constants.ts b/packages/evm/src/eof/constants.ts index 42ec1cc74b6..a6473175699 100644 --- a/packages/evm/src/eof/constants.ts +++ b/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) diff --git a/packages/evm/src/eof/container.ts b/packages/evm/src/eof/container.ts index a2be68d86c0..fe4a08e83dd 100644 --- a/packages/evm/src/eof/container.ts +++ b/packages/evm/src/eof/container.ts @@ -132,10 +132,10 @@ 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 @@ -143,7 +143,7 @@ class EOFHeader { /** * 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) diff --git a/packages/evm/src/eof/setup.ts b/packages/evm/src/eof/setup.ts index 6d977ecfb35..5af23327f0c 100644 --- a/packages/evm/src/eof/setup.ts +++ b/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 } diff --git a/packages/evm/src/eof/util.ts b/packages/evm/src/eof/util.ts index b28a5943e01..054760abe74 100644 --- a/packages/evm/src/eof/util.ts +++ b/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) diff --git a/packages/evm/src/eof/verify.ts b/packages/evm/src/eof/verify.ts index 428b4daf7d1..3d2ac06c0d7 100644 --- a/packages/evm/src/eof/verify.ts +++ b/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() @@ -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() // 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)