IInterpreterV1

Git Source

Functions

functionPointers

Exposes the function pointers as uint16 values packed into a single bytes in the same order as they would be indexed into by opcodes. For example, if opcode 2 should dispatch function at position 0x1234 then the start of the returned bytes would be 0xXXXXXXXX1234 where X is a placeholder for the function pointers of opcodes 0 and 1. IExpressionDeployerV1 contracts use these function pointers to "compile" the expression into something that an interpreter can dispatch directly without paying gas to lookup the same at runtime. As the validity of any integrity check and subsequent dispatch is highly sensitive to both the function pointers and overall bytecode of the interpreter, IExpressionDeployerV1 contracts SHOULD implement guards against accidentally being deployed onchain paired against an unknown interpreter. It is very easy for an apparent compatible pairing to be subtly and critically incompatible due to addition/removal/reordering of opcodes and compiler optimisations on the interpreter bytecode. This MAY return different values during construction vs. all other times after the interpreter has been successfully deployed onchain. DO NOT rely on function pointers reported during contract construction.

function functionPointers() external view returns (bytes memory);

eval

The raison d'etre for an interpreter. Given some expression and per-call additional contextual data, produce a stack of results and a set of state changes that the caller MAY OPTIONALLY pass back to be persisted by a call to IInterpreterStoreV1.set.

function eval(
    IInterpreterStoreV1 store,
    StateNamespace namespace,
    EncodedDispatch dispatch,
    uint256[][] calldata context
) external view returns (uint256[] memory stack, uint256[] memory kvs);

Parameters

NameTypeDescription
storeIInterpreterStoreV1The storage contract that the returned key/value pairs MUST be passed to IF the calling contract is in a non-static calling context. Static calling contexts MUST pass address(0).
namespaceStateNamespaceThe state namespace that will be fully qualified by the interpreter at runtime in order to perform gets on the underlying store. MUST be the same namespace passed to the store by the calling contract when sending the resulting key/value items to storage.
dispatchEncodedDispatchAll the information required for the interpreter to load an expression, select an entrypoint and return the values expected by the caller. The interpreter MAY encode dispatches differently to LibEncodedDispatch but this WILL negatively impact compatibility for calling contracts that hardcode the encoding logic.
contextuint256[][]A 2-dimensional array of data that can be indexed into at runtime by the interpreter. The calling contract is responsible for ensuring the authenticity and completeness of context data. The interpreter MUST revert at runtime if an expression attempts to index into some context value that is not provided by the caller. This implies that context reads cannot be checked for out of bounds reads at deploy time, as the runtime context MAY be provided in a different shape to what the expression is expecting. Same as eval but allowing the caller to specify a namespace under which the state changes will be applied. The interpeter MUST ensure that keys will never collide across namespaces, even if, for example: - The calling contract is malicious and attempts to craft a collision with state changes from another contract - The expression is malicious and attempts to craft a collision with other expressions evaluated by the same calling contract A malicious entity MAY have access to significant offchain resources to attempt to precompute key collisions through brute force. The collision resistance of namespaces should be comparable or equivalent to the collision resistance of the hashing algorithms employed by the blockchain itself, such as the design of mapping in Solidity that hashes each nested key to produce a collision resistant compound key.

Returns

NameTypeDescription
stackuint256[]The list of values produced by evaluating the expression. MUST NOT be longer than the maximum length specified by dispatch, if applicable.
kvsuint256[]A list of pairwise key/value items to be saved in the store.