LibBytecode

Git Source

A library for inspecting the bytecode of an expression. Largely focused on reading the source headers rather than the opcodes themselves. Designed to be efficient enough to be used in the interpreter directly. As such, it is not particularly safe, notably it always assumes that the headers are not lying about the structure and runtime behaviour of the bytecode. This is by design as it allows much more simple, efficient and decoupled implementation of authoring/parsing logic, which makes the author of an expression responsible for producing well formed bytecode, such as balanced LHS/RHS stacks. The deployment integrity checks are responsible for checking that the headers match the structure and behaviour of the bytecode.

Functions

sourceCount

The number of sources in the bytecode. If the bytecode is empty, returns 0. Otherwise, returns the first byte of the bytecode, which is the number of sources. Implies that 0x and 0x00 are equivalent, both having 0 sources. For this reason, contracts that handle bytecode MUST NOT rely on simple data length checks to determine if the bytecode is empty or not. DOES NOT check the integrity or even existence of the sources.

function sourceCount(bytes memory bytecode) internal pure returns (uint256 count);

Parameters

Returns

checkNoOOBPointers

Checks the structural integrity of the bytecode from the perspective of potential out of bounds reads. Will revert if the bytecode is not well-formed. This check MUST be done BEFORE any attempts at per-opcode integrity checks, as the per-opcode checks assume that the headers define valid regions in memory to iterate over. Checks:

• The offsets are populated according to the source count.
• The offsets point to positions within the bytecode bytes.
• There exists at least the 4 byte header for each source at the offset, within the bounds of the bytecode bytes.
• The number of opcodes specified in the header of each source locates the end of the source exactly at either the offset of the next source or the end of the bytecode bytes.

function checkNoOOBPointers(bytes memory bytecode) internal pure;

sourceRelativeOffset

The relative byte offset of a source in the bytecode. This is the offset from the start of the first source header, which is after the source count byte and the source offsets. This function DOES NOT check that the relative offset is within the bounds of the bytecode. Callers MUST checkNoOOBPointers BEFORE attempting to traverse the bytecode, otherwise the relative offset MAY point to memory outside the bytecode bytes.

function sourceRelativeOffset(bytes memory bytecode, uint256 sourceIndex) internal pure returns (uint256 offset);

Parameters

Returns

sourcePointer

The absolute byte pointer of a source in the bytecode. Points to the header of the source, NOT the first opcode. This function DOES NOT check that the source index is within the bounds of the bytecode. Callers MUST checkNoOOBPointers BEFORE attempting to traverse the bytecode, otherwise the relative offset MAY point to memory outside the bytecode bytes.

function sourcePointer(bytes memory bytecode, uint256 sourceIndex) internal pure returns (Pointer pointer);

Parameters

Returns

sourceOpsCount

The number of opcodes in a source. This function DOES NOT check that the source index is within the bounds of the bytecode. Callers MUST checkNoOOBPointers BEFORE attempting to traverse the bytecode, otherwise the relative offset MAY point to memory outside the bytecode bytes.

function sourceOpsCount(bytes memory bytecode, uint256 sourceIndex) internal pure returns (uint256 opsCount);

Parameters

Returns

sourceStackAllocation

The number of stack slots allocated by a source. This is the number of 32 byte words that MUST be allocated for the stack for the given source index to avoid memory corruption when executing the source. This function DOES NOT check that the source index is within the bounds of the bytecode. Callers MUST checkNoOOBPointers BEFORE attempting to traverse the bytecode, otherwise the relative offset MAY point to memory outside the bytecode bytes.

function sourceStackAllocation(bytes memory bytecode, uint256 sourceIndex) internal pure returns (uint256 allocation);

Parameters

Returns

sourceInputsOutputsLength

The number of inputs and outputs of a source. This function DOES NOT check that the source index is within the bounds of the bytecode. Callers MUST checkNoOOBPointers BEFORE attempting to traverse the bytecode, otherwise the relative offset MAY point to memory outside the bytecode bytes. Note that both the inputs and outputs are always returned togther, this is because the caller SHOULD be checking both together whenever using some bytecode. Returning two values is more efficient than two separate function calls.

function sourceInputsOutputsLength(bytes memory bytecode, uint256 sourceIndex)
    internal
    pure
    returns (uint256 inputs, uint256 outputs);

Parameters

Returns

bytecodeToSources

Backwards compatibility with the old way of representing sources. Requires allocation and copying so it isn't particularly efficient, but allows us to use the new bytecode format with old interpreter code. Not recommended for production code but useful for testing.

function bytecodeToSources(bytes memory bytecode) internal pure returns (bytes[] memory);