rain.interpreter

Docs at https://rainprotocol.github.io/rain.interpreter

Overview

Standard libraries and interfaces defining and working with InterpeterState including:

• the standard eval loop
• source compilation from opcodes
• state (de)serialization (more gas efficient than abi encoding)

Interpreters are designed to be highly moddable behind the IInterpreterV1 interface, but pretty much any interpreter that uses InterpreterState will need these low level facilities verbatim. Further, these facilities (with possible exception of debugging logic), while relatively short in terms of lines of code, are surprisingly fragile to maintain in a gas efficient way so we don't recommend reinventing this wheel.

Versioning

Stability and versioning is achieved at the interface level. All interfaces and types exposed externally by an interface are versioned.

The most obvious place this fails is when a breaking change cannot be expressed in Solidity's type system.

For example, the ordering of "top to bottom" of a stack returned by an interpreter, represented as a uint256[] was reversed between eval and eval2. The compiler cannot protect downstream contracts from such a change, even if we were to scream it in the code comments, so such changes are considered dangerous and justify a version number at the method level (e.g. eval and eval2).

The goal is to intentionally loudly break things at the compiler level, or at least reliably at runtime (i.e. unconditionally erroring every call to X). We do NOT want to make silent subtle changes on the hope that nobody was relying on the old behaviours.

Unstable interfaces

An unstable interface MAY be used by a current implementation in this repo as the goal is always to move unstable interfaces to stability.

The practical challenge for achieving stability is that it has to be informed by usage, or at least attempted usage.

Stability is therefore observed in some interface, based on some (subjective) amount of usage in a concrete implementation without the kind of feedback that necessitates a modification.

Deprecated interfaces

Deprecated interfaces are those that were completely stable, with deployed concrete implementations, then replaced by a new implementation of an unstable interface.

As there are immutable concrete implementations in production of these ex-stable interfaces, we keep the interfaces so that third party contracts can continue to consume existing deployments.

This is important for existing deployments to leverage their "lindy", as often the old battletested thing can be much safer than the new shiny thing.

NO semver

We do NOT use semver because it requires us to make subjective assessments with imperfect information about concepts like "breaking" or "bug".

Branches

main includes the latest implementations of the latest interfaces, including unstable interfaces.

While we keep deprecated interfaces around for a long time, we try to avoid cruft of deprecated concrete implementations, libs and tests. This cruft can really hinder the ability to move through necessary refactors, so it has to be culled often.

As every commit is deployed to a testnet by CI, and is immutable onchain and can be cross deployed to other chains, there's no need to try to couple what's happening in this repo with onchain realities, other than at the interface level.

There are some branches that were forked from main for historical reasons, that MAY be of interest situationally, but otherwise should be ignored.

• main-np: Forked from the last commit using eval before eval2 was the primary interface into the interpreter. No longer actively developed.

Contents

• BaseRainterpreterExternNPE2
• BaseRainterpreterExternNPE2 constants
• BaseRainterpreterSubParserNPE2
• BaseRainterpreterSubParserNPE2 constants
• DeployerDiscoverableMetaV3ConstructionConfig
• DeployerDiscoverableMetaV3

BaseRainterpreterExternNPE2

Git Source

Inherits: IInterpreterExternV3, ERC165

Base implementation of IInterpreterExternV3. Inherit from this contract, and override functionPointers to provide a list of function pointers.

Functions

extern

Handles a single dispatch.

function extern(ExternDispatch dispatch, uint256[] memory inputs)
    external
    view
    virtual
    override
    returns (uint256[] memory outputs);

Parameters

Returns

externIntegrity

Checks the integrity of some extern call.

function externIntegrity(ExternDispatch dispatch, uint256 expectedInputs, uint256 expectedOutputs)
    external
    pure
    virtual
    override
    returns (uint256 actualInputs, uint256 actualOutputs);

Parameters

Returns

supportsInterface

See {IERC165-supportsInterface}.

function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool);

opcodeFunctionPointers

Overrideable function to provide the list of function pointers for word dispatches.

function opcodeFunctionPointers() internal view virtual returns (bytes memory);

integrityFunctionPointers

Overrideable function to provide the list of function pointers for integrity checks.

function integrityFunctionPointers() internal pure virtual returns (bytes memory);

Constants

Git Source

OPCODE_FUNCTION_POINTERS

Empty opcode function pointers constant. Inheriting contracts should create their own constant and override opcodeFunctionPointers to use theirs.

bytes constant OPCODE_FUNCTION_POINTERS = hex"";

INTEGRITY_FUNCTION_POINTERS

Empty integrity function pointers constant. Inheriting contracts should create their own constant and override integrityFunctionPointers to use theirs.

bytes constant INTEGRITY_FUNCTION_POINTERS = hex"";

BaseRainterpreterSubParserNPE2

Git Source

Inherits: ERC165, ISubParserV1

Base implementation of ISubParserV1. Inherit from this contract and override the virtual functions to align all the relevant pointers and metadata bytes so that it can actually run. The basic workflow for subparsing via this contract is:

• The main parser will call subParse with the subparser's compatibility version and the data to parse.
• The subparser will check the compatibility is an exact match and revert if not. This is the simplest and most conservative approach, if there's a new compatibility version, a new version of the subparser will need to be deployed even if the upstream changes are backwards compatible.
• The subparser will then parse the data, using the subParserParseMeta function to get the metadata bytes, which must be overridden by the child contract in order to be useful. The sub parser meta bytes are constructed exactly the same as the main parser meta bytes, so the same types and libs can be used to build them. The key difference is that the index of each word in the authoring meta maps to a parser function pointer, rather than a handler function pointer. What this means is that the function at index N of subParserFunctionPointers is responsible for parsing whatever data the main parser has passed to subParse into whatever the final output of the subparser is. For example, the 5th parser function might convert some word string "foo" into the bytecode that represents an extern call on the main interpreter into the contract that provides that extern logic. This decoupling allows any subparser function to generate any runtime behaviour at all, provided it knows how to construct the opcode for it.
• Currently the subparse handles literals and operands in the same way as the main parser, but this may change in future. Likely that there will be dedicated "sub literal" and "sub word" concepts, that should be more composable than the current approach.
• The final result of the subparser is returned as a tuple of success, bytecode and constants. The success flag is used to indicate whether the subparser was able to parse the data, and the bytecode and constants are the same as the main parser, and are used to construct the final bytecode of the main parser. The expectation on failure is that there may be some other subparser that can parse the data, so the main parser will handle fallback logic.

Functions

subParserParseMeta

Overrideable function to allow implementations to define their parse meta bytes.

function subParserParseMeta() internal pure virtual returns (bytes memory);

subParserFunctionPointers

Overrideable function to allow implementations to define their function pointers to each sub parser.

function subParserFunctionPointers() internal pure virtual returns (bytes memory);

subParserOperandHandlers

Overrideable function to allow implementations to define their operand handlers.

function subParserOperandHandlers() internal pure virtual returns (bytes memory);

subParserLiteralParsers

Overrideable function to allow implementations to define their literal parsers.

function subParserLiteralParsers() internal pure virtual returns (bytes memory);

subParserCompatibility

Overrideable function to allow implementations to define their compatibility version.

function subParserCompatibility() internal pure virtual returns (bytes32);

subParse

A basic implementation of sub parsing that uses encoded function pointers to dispatch everything necessary in O(1) and allows for the child contract to override all relevant functions with some modest boilerplate. This is virtual but the expectation is that it generally DOES NOT need to be overridden, as the function pointers and metadata bytes are all that need to be changed to implement a new subparser.

function subParse(bytes32 compatibility, bytes memory data)
    external
    pure
    virtual
    returns (bool success, bytes memory bytecode, uint256[] memory constants);

Parameters

Returns

supportsInterface

See {IERC165-supportsInterface}.

function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool);

Constants

Git Source

SUB_PARSER_FUNCTION_POINTERS

This is a placeholder for the subparser function pointers. The subparser function pointers are a list of 16 bit function pointers, where each subparser function is responsible for parsing a particular word into a an opcode that will be used by the main parser to build the final bytecode.

bytes constant SUB_PARSER_FUNCTION_POINTERS = hex"";

SUB_PARSER_PARSE_META

This is a placeholder for the subparser meta bytes. The subparser meta bytes are the same structure as the main parser meta bytes. The exact same process of hashing, blooming, fingeprinting and index lookup applies to the subparser meta bytes as the main parser meta bytes.

bytes constant SUB_PARSER_PARSE_META = hex"";

SUB_PARSER_OPERAND_HANDLERS

This is a placeholder for the int that encodes pointers to operand parsers. In the future this will probably be removed and the main parser will handle all operand parsing, the subparser will only be responsible for checking the validity of the operand values and encoding them into the resulting bytecode.

bytes constant SUB_PARSER_OPERAND_HANDLERS = hex"";

SUB_PARSER_LITERAL_PARSERS

This is a placeholder for the int that encodes pointers to literal parsers. In the future this will probably be removed and there will be dedicated concepts for "sub literal" and "sub word" parsing, that should be more composable than the current approach.

bytes constant SUB_PARSER_LITERAL_PARSERS = hex"";

SUB_PARSER_COMPATIBLITY

This is a placeholder for compatibility version. The child contract should override this to define its own compatibility version.

bytes32 constant SUB_PARSER_COMPATIBLITY = bytes32(0);

DeployerDiscoverableMetaV3ConstructionConfig

Git Source

Construction config for DeployerDiscoverableMetaV3.

struct DeployerDiscoverableMetaV3ConstructionConfig {
    address deployer;
    bytes meta;
}

Properties

DeployerDiscoverableMetaV3

Git Source

Inherits: IMetaV1

Upon construction, checks metadata against a known hash, emits it then touches the deployer (deploy an empty expression). This allows indexers to discover the metadata of the DeployerDiscoverableMetaV3 contract by indexing the deployer. In this way the deployer acts as a pseudo-registry by virtue of it being a natural hub for interactions with calling contracts.

Functions

constructor

constructor(bytes32 metaHash, DeployerDiscoverableMetaV3ConstructionConfig memory config);

Contents

• RainterpreterExpressionDeployerNPE2ConstructionConfig
• RainterpreterExpressionDeployerNPE2
• RainterpreterExpressionDeployerNPE2 constants
• RainterpreterNPE2
• RainterpreterNPE2 constants
• RainterpreterParserNPE2
• RainterpreterParserNPE2 constants
• LibExternOpIntIncNPE2
• LibExternOpStackOperandNPE2
• LibRainterpreterReferenceExternNPE2
• RainterpreterReferenceExternNPE2
• RainterpreterReferenceExternNPE2 constants
• OddSetLength
• RainterpreterStoreNPE2
• RainterpreterStoreNPE2 constants

RainterpreterExpressionDeployerNPE2ConstructionConfig

Git Source

All config required to construct a RainterpreterNPE2.

struct RainterpreterExpressionDeployerNPE2ConstructionConfig {
    address interpreter;
    address store;
    address parser;
    bytes meta;
}

Properties

RainterpreterExpressionDeployerNPE2

Git Source

Inherits: IExpressionDeployerV3, ERC165

State Variables

iInterpreter

The interpreter with known bytecode that this deployer is constructed for.

IInterpreterV2 public immutable iInterpreter;

iStore

The store with known bytecode that this deployer is constructed for.

IInterpreterStoreV1 public immutable iStore;

iParser

IParserV1 public immutable iParser;

Functions

constructor

constructor(RainterpreterExpressionDeployerNPE2ConstructionConfig memory config);

supportsInterface

This IS a security check. This prevents someone making an exact bytecode copy of the interpreter and shipping different meta for the copy to lie about what each op does in the interpreter.

Interface identification is specified in ERC-165. This function uses less than 30,000 gas.

function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool);

Parameters

Returns

deployExpression2

Expressions are expected to be deployed onchain as immutable contract code with a first class address like any other contract or account. Technically this is optional in the sense that all the tools required to eval some expression and define all its opcodes are available as libraries. In practise there are enough advantages to deploying the sources directly onchain as contract data and loading them from the interpreter at eval:

• Loading and storing binary data is gas efficient as immutable contract data
• Expressions need to be immutable between their deploy time integrity check and runtime evaluation
• Passing the address of an expression through calldata to an interpreter is cheaper than passing an entire expression through calldata
• Conceptually a very simple approach, even if implementations like SSTORE2 are subtle under the hood The expression deployer MUST perform an integrity check of the source code before it puts the expression onchain at a known address. The integrity check MUST at a minimum (it is free to do additional static analysis) calculate the memory required to be allocated for the stack in total, and that no out of bounds memory reads/writes occur within this stack. A simple example of an invalid source would be one that pushes one value to the stack then attempts to pops two values, clearly we cannot remove more values than we added. The IExpressionDeployerV3 MUST revert in the case of any integrity failure, all integrity checks MUST pass in order for the deployment to complete. Once the integrity check is complete the IExpressionDeployerV3 MUST do any additional processing required by its paired interpreter. For example, the IExpressionDeployerV3 MAY NEED to replace the indexed opcodes in the ExpressionConfig sources with real function pointers from the corresponding interpreter. The caller MUST check the io returned by this function to determine the number of inputs and outputs for each source are within the bounds of the caller's expectations.

function deployExpression2(bytes memory bytecode, uint256[] memory constants)
    external
    virtual
    returns (IInterpreterV2, IInterpreterStoreV1, address, bytes memory);

Parameters

Returns

integrityFunctionPointers

Defines all the function pointers to integrity checks. This is the expression deployer's equivalent of the opcode function pointers and follows a near identical dispatch process. These are never compiled into source and are instead indexed into directly by the integrity check. The indexing into integrity pointers (which has an out of bounds check) is a proxy for enforcing that all opcode pointers exist at runtime, so the length of the integrity pointers MUST match the length of opcode function pointers. This function is virtual so that it can be overridden pairwise with overrides to functionPointers on Rainterpreter.

function integrityFunctionPointers() external view virtual returns (bytes memory);

Returns

expectedConstructionMetaHash

Virtual function to return the expected construction meta hash. Public so that external tooling can read it, although this should be considered deprecated. The intended workflow is that tooling uses a real evm to deploy the full dispair and reads the hashes from errors using a trail/error approach until a full dispair is deployed.

function expectedConstructionMetaHash() public pure virtual returns (bytes32);

expectedInterpreterBytecodeHash

Virtual function to return the expected interpreter bytecode hash.

function expectedInterpreterBytecodeHash() internal pure virtual returns (bytes32);

expectedStoreBytecodeHash

Virtual function to return the expected store bytecode hash.

function expectedStoreBytecodeHash() internal pure virtual returns (bytes32);

expectedParserBytecodeHash

Virtual function to return the expected parser bytecode hash.

function expectedParserBytecodeHash() internal pure virtual returns (bytes32);

Constants

Git Source

INTEGRITY_FUNCTION_POINTERS

The function pointers for the integrity check fns.

bytes constant INTEGRITY_FUNCTION_POINTERS =
    hex"0a650adf0b480cc00cc00cca0cd30cee0d940d940df00e6c0e760e800cc00cca0cc00cc00cca0e6c0e6c0e6c0e6c0e6c0e8a0eac0ed60cc00e8a0cc00cc00e800cca0cc00cc00ef80ef80cc00cc00cca0cca0ef80ef80ef80ef80ef80ef80ef80ef80ef80ef80ef80ef80cca0f0f0f190f190f19";

CONSTRUCTION_META_HASH

Hash of the known construction meta.

bytes32 constant CONSTRUCTION_META_HASH = bytes32(0x223935e6758ce9e5968c652b47f8e98901a7b189e99f1f6274bbb1221ae28dab);

RainterpreterNPE2

Git Source

Inherits: IInterpreterV2, ERC165

Implementation of a Rainlang interpreter that is compatible with native onchain Rainlang parsing.

Functions

eval2

There are MANY ways that eval can be forced into undefined/corrupt behaviour by passing in invalid data. This is a deliberate design decision to allow for the interpreter to be as gas efficient as possible. The interpreter is provably read only, it contains no state changing evm opcodes reachable on any logic path. This means that the caller can only harm themselves by passing in invalid data and either reverting, exhausting gas or getting back some garbage data. The caller can trivially protect themselves from these OOB issues by ensuring the integrity check has successfully run over the bytecode before calling eval. Any smart contract caller can do this by using a trusted and appropriate deployer contract to deploy the bytecode, which will automatically run the integrity check during deployment, then keeping a registry of trusted expression addresses for itself in storage. This appears first in the contract in the hope that the compiler will put it in the most efficient internal dispatch location to save a few gas per eval call.

function eval2(
    IInterpreterStoreV1 store,
    FullyQualifiedNamespace namespace,
    EncodedDispatch dispatch,
    uint256[][] memory context,
    uint256[] memory inputs
) external view virtual returns (uint256[] memory, uint256[] memory);

Parameters

Returns

supportsInterface

See {IERC165-supportsInterface}.

function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool);

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. IExpressionDeployerV3 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, IExpressionDeployerV3 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 virtual returns (bytes memory);

Constants

Git Source

INTERPRETER_BYTECODE_HASH

Hash of the known interpreter bytecode.

bytes32 constant INTERPRETER_BYTECODE_HASH = bytes32(0x7cbd3b90f6e0eb55adc1bfcc00113e8050457173d7fa4261314d9b140237c009);

OPCODE_FUNCTION_POINTERS

The function pointers known to the interpreter for dynamic dispatch. By setting these as a constant they can be inlined into the interpreter and loaded at eval time for very low gas (~100) due to the compiler optimising it to a single codecopy to build the in memory bytes array.

bytes constant OPCODE_FUNCTION_POINTERS =
    hex"0c2f0c7b0cb60e7b0e8d0e9f0eb80efa0f4c0f5d0f6e100c10f0112a11e8129811e8131c13be143614651494149414e31512157415fc16a316b7170d172117361750175b176f17841801184c1864187e189518ac18ac18f71942198d198d19d819d81a231a6e1ab91ab91b041beb1c1e1c761cab";

RainterpreterParserNPE2

Git Source

Inherits: IParserV1, ERC165

Functions

supportsInterface

See {IERC165-supportsInterface}.

function supportsInterface(bytes4 interfaceId) public view override returns (bool);

parse

Parses a Rainlang string into an evaluable expression. MUST be deterministic and MUST NOT have side effects. The only inputs are the Rainlang string and the parse meta. MAY revert if the Rainlang string is invalid. This function takes bytes instead of string to allow for definitions of "string" other than UTF-8.

function parse(bytes memory data) external pure virtual override returns (bytes memory, uint256[] memory);

Parameters

Returns

parseMeta

Virtual function to return the parse meta.

function parseMeta() internal pure virtual returns (bytes memory);

operandHandlerFunctionPointers

Virtual function to return the operand handler function pointers.

function operandHandlerFunctionPointers() internal pure virtual returns (bytes memory);

literalParserFunctionPointers

Virtual function to return the literal parser function pointers.

function literalParserFunctionPointers() internal pure virtual returns (bytes memory);

buildOperandHandlerFunctionPointers

External function to build the operand handler function pointers.

function buildOperandHandlerFunctionPointers() external pure returns (bytes memory);

buildLiteralParserFunctionPointers

External function to build the literal parser function pointers.

function buildLiteralParserFunctionPointers() external pure returns (bytes memory);

Constants

Git Source

PARSER_BYTECODE_HASH

bytes32 constant PARSER_BYTECODE_HASH = bytes32(0x3e0f88a0fe55c6d407039dde744789f22e5a6bbf31652626d104829454653582);

PARSE_META

bytes constant PARSE_META =
    hex"02498808220a2013000c08021320c51020c10908004040400494201934224b00862800000000000000000000000000000000000000000000000800000000000000004023f779410dee1ce71b34b7b5359da6ea020c8489085226f6097827fe01d556492d1274f7178783b30a15fe82282279c32eb3469f29e149b12b2e1b223144b77937ad62f706963085008cdb9427ab5e491d9a2df0119741001eaeb15503f54c1625146dc00cb486333644bf3320bac6511485c0c33326583d07a6dee51f3f2f4316c4b76618c85a9a39561eec2fc2def922721d5d2a2bd7880bd7d8610fac9dd91a7da12e05797e1e327c8fab0e13dd511c8433372195f3ee2cce06352406c95d12b5795d2683722110fafb871951da9a13bef3b21566f6c2304a27d20475cf3434985d02383cf36e";

PARSE_META_BUILD_DEPTH

uint8 constant PARSE_META_BUILD_DEPTH = 2;

OPERAND_HANDLER_FUNCTION_POINTERS

bytes constant OPERAND_HANDLER_FUNCTION_POINTERS =
    hex"0eb40eb40f490fea0fea0fea0f490f490eb40eb40f490f490fea0fea0fea0fea0fea0fea0fea0fea0fea0fea0fea0fea0fea0eb40eb40fea0fea0fea0fea0fea0fea0fea0fea0fea0fea0fea102f10c310c30fea0fea0fea0fea0fea0fea0fea0fea0fea0fea0fea0fea0fea0fea0eb40eb40eb4";

LITERAL_PARSER_FUNCTION_POINTERS

bytes constant LITERAL_PARSER_FUNCTION_POINTERS = hex"07e60aae0d83";

LibExternOpIntIncNPE2

Git Source

Functions

run

Running the extern increments every input by 1. By allowing many inputs we can test multi input/output logic is implemented correctly for externs.

function run(Operand, uint256[] memory inputs) internal pure returns (uint256[] memory);

integrity

The integrity check for the extern increment opcode. The inputs and outputs are the same always.

function integrity(Operand, uint256 inputs, uint256) internal pure returns (uint256, uint256);

subParser

The sub parser for the extern increment opcode. It has no special logic so uses the default sub parser from LibSubParse.

function subParser(uint256 constantsHeight, uint256 inputsByte, Operand operand)
    internal
    view
    returns (bool, bytes memory, uint256[] memory);

LibExternOpStackOperandNPE2

Git Source

Functions

subParser

function subParser(uint256 constantsHeight, uint256, Operand operand)
    internal
    pure
    returns (bool, bytes memory, uint256[] memory);

LibRainterpreterReferenceExternNPE2

Git Source

Functions

authoringMetaV2

This mirrors the authoringMeta function in LibAllStandardOps. The goal is to produce a standard encoded AuthoringMeta[] that tooling can use to describe all the parseable words, that can be built directly into a useable parse meta with the standard libs. Note that the list of parseable words is not limited to the externs, the sub parser is free to define words that it then parses back into bytecode that is run by the interpreter itself.

function authoringMetaV2() internal pure returns (bytes memory);

RainterpreterReferenceExternNPE2

Git Source

Inherits: BaseRainterpreterSubParserNPE2, BaseRainterpreterExternNPE2

Functions

subParserParseMeta

Overrides the base parse meta for sub parsing. Simply returns the known constant value, which should allow the compiler to optimise the entire function call away.

function subParserParseMeta() internal pure virtual override returns (bytes memory);

subParserFunctionPointers

Overrides the base function pointers for sub parsing. Simply returns the known constant value, which should allow the compiler to optimise the entire function call away.

function subParserFunctionPointers() internal pure override returns (bytes memory);

subParserOperandHandlers

Overrides the base operand handlers for sub parsing. Simply returns the known constant value, which should allow the compiler to optimise the entire function call away.

function subParserOperandHandlers() internal pure override returns (bytes memory);

subParserLiteralParsers

Overrides the base literal parsers for sub parsing. Simply returns the known constant value, which should allow the compiler to optimise the entire function call away.

function subParserLiteralParsers() internal pure override returns (bytes memory);

subParserCompatibility

Overrides the compatibility version for sub parsing. Simply returns the known constant value, which should allow the compiler to optimise the entire function call away.

function subParserCompatibility() internal pure override returns (bytes32);

opcodeFunctionPointers

Overrides the base function pointers for opcodes. Simply returns the known constant value, which should allow the compiler to optimise the entire function call away.

function opcodeFunctionPointers() internal pure override returns (bytes memory);

integrityFunctionPointers

Overrides the base function pointers for integrity checks. Simply returns the known constant value, which should allow the compiler to optimise the entire function call away.

function integrityFunctionPointers() internal pure override returns (bytes memory);

buildSubParserLiteralParsers

The literal parsers are the same as the main parser. In the future this is likely to be changed so that sub parsers only have to define additional literal parsers that they provide, as it is redundant and fragile to have to define the same literal parsers in multiple places.

function buildSubParserLiteralParsers() external pure returns (bytes memory);

buildSubParserOperandHandlers

There's only one operand parser for this implementation, the disallowed parser. We haven't implemented any words with meaningful operands yet.

function buildSubParserOperandHandlers() external pure returns (bytes memory);

buildSubParserFunctionPointers

This mimics how LibAllStandardOpsNP builds bytes out of function pointers, but for sub parser functions. This is NOT intended to be called at runtime, instead tooling (e.g. the test suite) can call this function and compare it to subParserFunctionPointers to ensure they are in sync. This makes the runtime function pointer lookup much more gas efficient by allowing it to be constant. The reason this can't be done within the test itself is that the pointers need to be calculated relative to the bytecode of the current contract, not the test contract.

function buildSubParserFunctionPointers() external pure returns (bytes memory);

buildOpcodeFunctionPointers

This mimics how LibAllStandardOpsNP builds function pointers for the Rainterpreter. The same pattern applies to externs but for a different function signature for each opcode. Call this function somehow, e.g. from within a test, and then copy the output into the OPCODE_FUNCTION_POINTERS if there is a mismatch. This makes the function pointer lookup much more gas efficient. The reason this can't be done within the test itself is that the pointers need to be calculated relative to the bytecode of the current contract, not the test contract.

function buildOpcodeFunctionPointers() external pure returns (bytes memory);

buildIntegrityFunctionPointers

This applies the same pattern to integrity function pointers as the opcode and parser function pointers on this same contract. Call this function somehow, e.g. from within a test, and then check there is no mismatch with the INTEGRITY_FUNCTION_POINTERS constant. This makes the function pointer lookup at runtime much more gas efficient by allowing it to be constant. The reason this can't be done within the test itself is that the pointers need to be calculated relative to the bytecode of the current contract, not the test contract.

function buildIntegrityFunctionPointers() external pure returns (bytes memory);

supportsInterface

This is only needed because the parser and extern base contracts both implement IERC165, and the compiler needs to be told how to resolve the ambiguity.

function supportsInterface(bytes4 interfaceId)
    public
    view
    virtual
    override(BaseRainterpreterSubParserNPE2, BaseRainterpreterExternNPE2)
    returns (bool);

Constants

Git Source

SUB_PARSER_FUNCTION_POINTERS_LENGTH

The number of subparser functions available to the parser. This is NOT 1:1 with the number of opcodes provided by the extern component of this contract. It is possible to subparse words into opcodes that run entirely within the interpreter, and do not have an associated extern dispatch.

uint256 constant SUB_PARSER_FUNCTION_POINTERS_LENGTH = 2;

SUB_PARSER_FUNCTION_POINTERS

Real function pointers to the sub parser functions that produce the bytecode that this contract knows about. This is both constructing the extern bytecode that dials back into this contract at eval time, and creating to things that happen entirely on the interpreter such as well known constants and references to the context grid.

bytes constant SUB_PARSER_FUNCTION_POINTERS = hex"0a120a35";

SUB_PARSER_PARSE_META

Real sub parser meta bytes that map parsed strings to the functions that know how to parse those strings into opcodes for the main parser. Structured identically to parse meta for the main parser.

bytes constant SUB_PARSER_PARSE_META =
    hex"0100000000000000000000000000000000000000000000000000000000400000000200ae37f501f2eec7";

SUB_PARSER_OPERAND_HANDLERS

Real function pointers to the operand parsers that are available at parse time, encoded into a single 256 bit word. Each 2 bytes starting from the rightmost position is a pointer to an operand parser function. In the future this is likely to be removed, or refactored to value handling only rather than parsing.

bytes constant SUB_PARSER_OPERAND_HANDLERS = hex"066a06af";

SUB_PARSER_LITERAL_PARSERS

Real function pointers to the literal parsers that are available at parse time, encoded into a single 256 bit word. Each 2 bytes starting from the rightmost position is a pointer to a literal parser function. In the future this is likely to be removed, in favour of a dedicated literal parser feature.

bytes constant SUB_PARSER_LITERAL_PARSERS = hex"";

OPCODE_FUNCTION_POINTERS

Real function pointers to the opcodes for the extern component of this contract. These get run at eval time wehen the interpreter calls into the contract as an IInterpreterExternV3.

bytes constant OPCODE_FUNCTION_POINTERS = hex"058b";

OPCODE_FUNCTION_POINTERS_LENGTH

Number of opcode function pointers available to run at eval time.

uint256 constant OPCODE_FUNCTION_POINTERS_LENGTH = 1;

INTEGRITY_FUNCTION_POINTERS

Real function pointers to the integrity checks for the extern component of this contract. These get run at deploy time when the main integrity checks are run, the extern opcode integrity on the deployer will delegate integrity checks to the extern contract.

bytes constant INTEGRITY_FUNCTION_POINTERS = hex"0744";

OP_INDEX_INCREMENT

Opcode index of the extern increment opcode. Needs to be manually kept in sync with the extern opcode function pointers. Definitely write tests for this to ensure a mismatch doesn't happen silently.

uint256 constant OP_INDEX_INCREMENT = 0;

OddSetLength

Git Source

Thrown when a set call is made with an odd number of arguments.

error OddSetLength(uint256 length);

RainterpreterStoreNPE2

Git Source

Inherits: IInterpreterStoreV2, ERC165

Simplest possible IInterpreterStoreV2 that could work. Takes key/value pairings from the input array and stores each in an internal mapping. StateNamespace is fully qualified only by msg.sender on set and doesn't attempt to do any deduping etc. if the same key appears twice it will be set twice.

State Variables

sStore

Store is several tiers of sandbox. 0. Address hashed into FullyQualifiedNamespace is msg.sender so that callers cannot attack each other

1. StateNamespace is caller-provided namespace so that expressions cannot attack each other
2. uint256 is expression-provided key
3. uint256 is expression-provided value tiers 0 and 1 are both embodied in the FullyQualifiedNamespace.

mapping(FullyQualifiedNamespace fullyQualifiedNamespace => mapping(uint256 key => uint256 value)) internal sStore;

Functions

supportsInterface

See {IERC165-supportsInterface}.

function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool);

set

Mutates the interpreter store in bulk. The bulk values are provided in the form of a uint256[] which can be treated e.g. as pairwise keys and values to be stored in a Solidity mapping. The IInterpreterStoreV2 defines the meaning of the uint256[] for its own storage logic.

function set(StateNamespace namespace, uint256[] calldata kvs) external virtual;

Parameters

get

This would be picked up by an out of bounds index below, but it's nice to have a more specific error message.

function get(FullyQualifiedNamespace namespace, uint256 key) external view virtual returns (uint256);

Parameters

Returns

Constants

Git Source

STORE_BYTECODE_HASH

Hash of the known store bytecode.

bytes32 constant STORE_BYTECODE_HASH = bytes32(0x2a4559222e2f3600b2d393715de8af57620439684463f745059c653bbfe3727f);

Contents

• ErrBitwise
• UnsupportedBitwiseShiftAmount
• TruncatedBitwiseEncoding
• ZeroLengthBitwiseEncoding
• ErrBytecode
• SourceIndexOutOfBounds
• UnexpectedSources
• UnexpectedTrailingOffsetBytes
• TruncatedSource
• TruncatedHeader
• TruncatedHeaderOffsets
• StackSizingsNotMonotonic
• ErrDeploy
• UnexpectedPointers
• UnexpectedInterpreterBytecodeHash
• UnexpectedStoreBytecodeHash
• UnexpectedParserBytecodeHash
• UnexpectedConstructionMetaHash
• ErrExtern
• NotAnExternContract
• BadInputs
• ErrOpList
• BadDynamicLength
• ErrParse
• UnexpectedOperand
• UnexpectedOperandValue
• ExpectedOperand
• OperandOverflow
• OperandValuesOverflow
• UnclosedOperand
• UnsupportedLiteralType
• StringTooLong
• UnclosedStringLiteral
• HexLiteralOverflow
• ZeroLengthHexLiteral
• OddLengthHexLiteral
• MalformedHexLiteral
• DecimalLiteralOverflow
• MalformedExponentDigits
• ZeroLengthDecimal
• MissingFinalSemi
• UnexpectedLHSChar
• UnexpectedRHSChar
• ExpectedLeftParen
• UnexpectedRightParen
• UnclosedLeftParen
• UnexpectedComment
• UnclosedComment
• MalformedCommentStart
• DuplicateLHSItem
• ExcessLHSItems
• NotAcceptingInputs
• ExcessRHSItems
• WordSize
• UnknownWord
• MaxSources
• DanglingSource
• ParserOutOfBounds
• ParseStackOverflow
• ParseStackUnderflow
• ParenOverflow
• NoWhitespaceAfterUsingWordsFrom
• InvalidAddressLength
• BadSubParserResult
• IncompatibleSubParser
• ExternDispatchConstantsHeightOverflow

ErrBitwise

Git Source

Workaround for https://github.com/foundry-rs/foundry/issues/6572

UnsupportedBitwiseShiftAmount

Git Source

Thrown during integrity check when a bitwise shift operation is attempted with a shift amount greater than 255 or 0. As the shift amount is taken from the operand, this is a compile time error so there's no need to support behaviour that would always evaluate to 0 or be a noop.

error UnsupportedBitwiseShiftAmount(uint256 shiftAmount);

TruncatedBitwiseEncoding

Git Source

Thrown during integrity check when bitwise (en|de)coding would be truncated due to the end bit position being beyond 256.

error TruncatedBitwiseEncoding(uint256 startBit, uint256 length);

Parameters

ZeroLengthBitwiseEncoding

Git Source

Thrown during integrity check when the length of a bitwise (en|de)coding would be 0.

error ZeroLengthBitwiseEncoding();

ErrBytecode

Git Source

Workaround for https://github.com/foundry-rs/foundry/issues/6572

SourceIndexOutOfBounds

Git Source

Thrown when a bytecode source index is out of bounds.

error SourceIndexOutOfBounds(bytes bytecode, uint256 sourceIndex);

Parameters

UnexpectedSources

Git Source

Thrown when a bytecode reports itself as 0 sources but has more than 1 byte.

error UnexpectedSources(bytes bytecode);

Parameters

UnexpectedTrailingOffsetBytes

Git Source

Thrown when bytes are discovered between the offsets and the sources.

error UnexpectedTrailingOffsetBytes(bytes bytecode);

Parameters

TruncatedSource

Git Source

Thrown when the end of a source as self reported by its header doesnt match the start of the next source or the end of the bytecode.

error TruncatedSource(bytes bytecode);

Parameters

TruncatedHeader

Git Source

Thrown when the offset to a source points to a location that cannot fit a header before the start of the next source or the end of the bytecode.

error TruncatedHeader(bytes bytecode);

Parameters

TruncatedHeaderOffsets

Git Source

Thrown when the bytecode is truncated before the end of the header offsets.

error TruncatedHeaderOffsets(bytes bytecode);

Parameters

StackSizingsNotMonotonic

Git Source

Thrown when the stack sizings, allocation, inputs and outputs, are not monotonically increasing.

error StackSizingsNotMonotonic(bytes bytecode, uint256 relativeOffset);

Parameters

ErrDeploy

Git Source

Workaround for https://github.com/foundry-rs/foundry/issues/6572

UnexpectedPointers

Git Source

Thrown when the pointers known to the expression deployer DO NOT match the interpreter it is constructed for. This WILL cause undefined expression behaviour so MUST REVERT.

error UnexpectedPointers(bytes actualPointers);

Parameters

UnexpectedInterpreterBytecodeHash

Git Source

Thrown when the RainterpreterExpressionDeployerNPE2 is constructed with unknown interpreter bytecode.

error UnexpectedInterpreterBytecodeHash(bytes32 expectedBytecodeHash, bytes32 actualBytecodeHash);

Parameters

UnexpectedStoreBytecodeHash

Git Source

Thrown when the RainterpreterNPE2 is constructed with unknown store bytecode.

error UnexpectedStoreBytecodeHash(bytes32 expectedBytecodeHash, bytes32 actualBytecodeHash);

Parameters

UnexpectedParserBytecodeHash

Git Source

Thrown when the RainterpreterNPE2 is constructed with unknown parser bytecode.

error UnexpectedParserBytecodeHash(bytes32 expectedBytecodeHash, bytes32 actualBytecodeHash);

Parameters

UnexpectedConstructionMetaHash

Git Source

Thrown when the RainterpreterNPE2 is constructed with unknown meta.

error UnexpectedConstructionMetaHash(bytes32 expectedConstructionMetaHash, bytes32 actualConstructionMetaHash);

Parameters

ErrExtern

Git Source

Workaround for https://github.com/foundry-rs/foundry/issues/6572

NotAnExternContract

Git Source

Thrown when the extern interface is not supported.

error NotAnExternContract(address extern);

BadInputs

Git Source

Thrown by the extern contract at runtime when the inputs don't match the expected inputs.

error BadInputs(uint256 expected, uint256 actual);

Parameters

ErrOpList

Git Source

Workaround for https://github.com/foundry-rs/foundry/issues/6572

BadDynamicLength

Git Source

Thrown when a dynamic length array is NOT 1 more than a fixed length array. Should never happen outside a major breaking change to memory layouts.

error BadDynamicLength(uint256 dynamicLength, uint256 standardOpsLength);

ErrParse

Git Source

Workaround for https://github.com/foundry-rs/foundry/issues/6572

UnexpectedOperand

Git Source

Thrown when parsing a source string and an operand opening < paren is found somewhere that we don't expect it or can't handle it.

error UnexpectedOperand();

UnexpectedOperandValue

Git Source

Thrown when there are more operand values in the operand than the handler is expecting.

error UnexpectedOperandValue();

ExpectedOperand

Git Source

Thrown when parsing an operand and some required component of the operand is not found in the source string.

error ExpectedOperand();

OperandOverflow

Git Source

Thrown when parsing an operand and the literal in the source string is too large to fit in the bits allocated for it in the operand.

error OperandOverflow();

OperandValuesOverflow

Git Source

Thrown when the number of values encountered in a single operand parsing is longer than the memory allocated to hold them.

error OperandValuesOverflow(uint256 offset);

Parameters

UnclosedOperand

Git Source

Thrown when parsing an operand and the closing > paren is not found.

error UnclosedOperand(uint256 offset);

Parameters

UnsupportedLiteralType

Git Source

The parser tried to bound an unsupported literal that we have no type for.

error UnsupportedLiteralType(uint256 offset);

StringTooLong

Git Source

Encountered a string literal that is larger than supported.

error StringTooLong(uint256 offset);

UnclosedStringLiteral

Git Source

Encountered a string that does not have a valid end, e.g. we found some char that was not printable ASCII and had to stop.

error UnclosedStringLiteral(uint256 offset);

HexLiteralOverflow

Git Source

Encountered a literal that is larger than supported.

error HexLiteralOverflow(uint256 offset);

ZeroLengthHexLiteral

Git Source

Encountered a zero length hex literal.

error ZeroLengthHexLiteral(uint256 offset);

OddLengthHexLiteral

Git Source

Encountered an odd sized hex literal.

error OddLengthHexLiteral(uint256 offset);

MalformedHexLiteral

Git Source

Encountered a hex literal with an invalid character.

error MalformedHexLiteral(uint256 offset);

DecimalLiteralOverflow

Git Source

Encountered a decimal literal that is larger than supported.

error DecimalLiteralOverflow(uint256 offset);

MalformedExponentDigits

Git Source

Encountered a decimal literal with an exponent that has too many or no digits.

error MalformedExponentDigits(uint256 offset);

ZeroLengthDecimal

Git Source

Encountered a zero length decimal literal.

error ZeroLengthDecimal(uint256 offset);

MissingFinalSemi

Git Source

The expression does not finish with a semicolon (EOF).

error MissingFinalSemi(uint256 offset);

UnexpectedLHSChar

Git Source

Enountered an unexpected character on the LHS.

error UnexpectedLHSChar(uint256 offset);

UnexpectedRHSChar

Git Source

Encountered an unexpected character on the RHS.

error UnexpectedRHSChar(uint256 offset);

ExpectedLeftParen

Git Source

More specific version of UnexpectedRHSChar where we specifically expected a left paren but got some other char.

error ExpectedLeftParen(uint256 offset);

UnexpectedRightParen

Git Source

Encountered a right paren without a matching left paren.

error UnexpectedRightParen(uint256 offset);

UnclosedLeftParen

Git Source

Encountered an unclosed left paren.

error UnclosedLeftParen(uint256 offset);

UnexpectedComment

Git Source

Encountered a comment outside the interstitial space between lines.

error UnexpectedComment(uint256 offset);

UnclosedComment

Git Source

Encountered a comment that never ends.

error UnclosedComment(uint256 offset);

MalformedCommentStart

Git Source

Encountered a comment start sequence that is malformed.

error MalformedCommentStart(uint256 offset);

DuplicateLHSItem

Git Source

Thrown when a stack name is duplicated. Shadowing in all forms is disallowed in Rainlang.

error DuplicateLHSItem(uint256 errorOffset);

ExcessLHSItems

Git Source

Encountered too many LHS items.

error ExcessLHSItems(uint256 offset);

NotAcceptingInputs

Git Source

Encountered inputs where they can't be handled.

error NotAcceptingInputs(uint256 offset);

ExcessRHSItems

Git Source

Encountered too many RHS items.

error ExcessRHSItems(uint256 offset);

WordSize

Git Source

Encountered a word that is longer than 32 bytes.

error WordSize(string word);

UnknownWord

Git Source

Parsed a word that is not in the meta.

error UnknownWord();

MaxSources

Git Source

The parser exceeded the maximum number of sources that it can build.

error MaxSources();

DanglingSource

Git Source

The parser encountered a dangling source. This is a bug in the parser.

error DanglingSource();

ParserOutOfBounds

Git Source

The parser moved past the end of the data.

error ParserOutOfBounds();

ParseStackOverflow

Git Source

The parser encountered a stack deeper than it can process in the memory region allocated for stack names.

error ParseStackOverflow();

ParseStackUnderflow

Git Source

The parser encountered a stack underflow.

error ParseStackUnderflow();

ParenOverflow

Git Source

The parser encountered a paren group deeper than it can process in the memory region allocated for paren tracking.

error ParenOverflow();

NoWhitespaceAfterUsingWordsFrom

Git Source

The parser did not find any whitespace after the pragma keyword.

error NoWhitespaceAfterUsingWordsFrom(uint256 offset);

InvalidAddressLength

Git Source

The parser encountered a hex literal that is the wrong size to be an address.

error InvalidAddressLength(uint256 offset);

BadSubParserResult

Git Source

The sub parser returned some bytecode that the main parser could not understand.

error BadSubParserResult(bytes bytecode);

IncompatibleSubParser

Git Source

When a subparser is not compatible with the main parser it MUST error on subParse calls rather than simply return false.

error IncompatibleSubParser();

ExternDispatchConstantsHeightOverflow

Git Source

Thrown when a subparser is asked to build an extern dispatch when the constants height is outside the range a single byte can represent.

error ExternDispatchConstantsHeightOverflow(uint256 constantsHeight);

Contents

• deprecated
• unstable
• EvaluableConfigV3
• EvaluableV2
• SignedContextV1
• IInterpreterCallerV2
• IInterpreterCallerV2 constants
• FullyQualifiedNamespace
• IInterpreterStoreV1
• IInterpreterStoreV1 constants
• AuthoringMeta
• AuthoringMetaV2
• IParserV1

Contents

• IDebugExpressionDeployerV1
• IDebugExpressionDeployerV2
• IDebugInterpreterV1
• IDebugInterpreterV2
• IExpressionDeployerV1
• IExpressionDeployerV1 constants
• IExpressionDeployerV2
• IExpressionDeployerV2 constants
• EvaluableConfig
• EvaluableConfigV2
• Evaluable
• SignedContext
• IInterpreterCallerV1
• IInterpreterCallerV1 constants
• EncodedExternDispatch
• ExternDispatch
• IInterpreterExternV1
• IInterpreterExternV2
• SourceIndex
• EncodedDispatch
• StateNamespace
• Operand
• IInterpreterV1
• IInterpreterV1 constants

IDebugExpressionDeployerV1

Git Source

Functions

offchainDebugEval

function offchainDebugEval(
    bytes[] memory sources,
    uint256[] memory constants,
    FullyQualifiedNamespace namespace,
    uint256[][] memory context,
    SourceIndex sourceIndex,
    uint256[] memory initialStack,
    uint8 minOutputs
) external view returns (uint256[] memory finalStack, uint256[] memory kvs);

IDebugExpressionDeployerV2

Git Source

Functions

integrityCheck

Drives an integrity check of the provided bytecode and constants. Unlike IDebugExpressionDeployerV1 this version ONLY checks the integrity of bytecode as produced by IParserV1.parse. There is an eval debug method on IDebugInterpreterV2 that can be used to check the runtime outputs of bytecode that passes the integrity check. Integrity check MUST revert with a descriptive error if the bytecode fails the integrity check.

function integrityCheck(bytes calldata bytecode, uint256[] calldata constants, uint256[] calldata minOutputs)
    external
    view;

Parameters

IDebugInterpreterV1

Git Source

Functions

offchainDebugEval

function offchainDebugEval(
    IInterpreterStoreV1 store,
    FullyQualifiedNamespace namespace,
    bytes[] calldata compiledSources,
    uint256[] calldata constants,
    uint256[][] calldata context,
    uint256[] calldata initialStack,
    SourceIndex sourceIndex_
) external view returns (uint256[] calldata finalStack, uint256[] calldata kvs);

IDebugInterpreterV2

Git Source

Functions

offchainDebugEval

A more explicit/open version of eval that is designed for offchain debugging. It MUST function identically to eval so implementations MAY call it directly internally for eval to ensure consistency at the expense of a small amount of gas. The affordances made for debugging are:

• A fully qualified namespace is passed in. This allows for storage reads from the perspective of an arbitrary caller during eval. Note that it does not allow for arbitrary writes, which are still gated by the store contract itself, so this is safe to expose.
• The bytecode is passed in directly. This allows for debugging of bytecode that has not been deployed to the chain yet.
• The components of the encoded dispatch other than the onchain expression address are passed separately. This remove the need to provide an address at all.
• Inputs to the entrypoint stack are passed in directly. This allows for debugging/simulating logic that could normally only be accessed via. some internal dispatch with a mid-flight state creating inputs for the internal call.

function offchainDebugEval(
    IInterpreterStoreV1 store,
    FullyQualifiedNamespace namespace,
    bytes calldata expressionData,
    SourceIndex sourceIndex,
    uint256 maxOutputs,
    uint256[][] calldata context,
    uint256[] calldata inputs
) external view returns (uint256[] calldata finalStack, uint256[] calldata writes);

IExpressionDeployerV1

Git Source

Companion to IInterpreterV1 responsible for onchain static code analysis and deploying expressions. Each IExpressionDeployerV1 is tightly coupled at the bytecode level to some interpreter that it knows how to analyse and deploy expressions for. The expression deployer can perform an integrity check "dry run" of candidate source code for the intepreter. The critical analysis/transformation includes:

• Enforcement of no out of bounds memory reads/writes
• Calculation of memory required to eval the stack with a single allocation
• Replacing index based opcodes with absolute interpreter function pointers
• Enforcement that all opcodes and operands used exist and are valid This analysis is highly sensitive to the specific implementation and position of all opcodes and function pointers as compiled into the interpreter. This is what makes the coupling between an interpreter and expression deployer so tight. Ideally all responsibilities would be handled by a single contract but this introduces code size issues quickly by roughly doubling the compiled logic of each opcode (half for the integrity check and half for evaluation). Interpreters MUST assume that expression deployers are malicious and fail gracefully if the integrity check is corrupt/bypassed and/or function pointers are incorrect, etc. i.e. the interpreter MUST always return a stack from eval in a read only way or error. I.e. it is the expression deployer's responsibility to do everything it can to prevent undefined behaviour in the interpreter, and the interpreter's responsibility to handle the expression deployer completely failing to do so.

Functions

deployExpression

Expressions are expected to be deployed onchain as immutable contract code with a first class address like any other contract or account. Technically this is optional in the sense that all the tools required to eval some expression and define all its opcodes are available as libraries. In practise there are enough advantages to deploying the sources directly onchain as contract data and loading them from the interpreter at eval:

• Loading and storing binary data is gas efficient as immutable contract data
• Expressions need to be immutable between their deploy time integrity check and runtime evaluation
• Passing the address of an expression through calldata to an interpreter is cheaper than passing an entire expression through calldata
• Conceptually a very simple approach, even if implementations like SSTORE2 are subtle under the hood The expression deployer MUST perform an integrity check of the source code before it puts the expression onchain at a known address. The integrity check MUST at a minimum (it is free to do additional static analysis) calculate the memory required to be allocated for the stack in total, and that no out of bounds memory reads/writes occur within this stack. A simple example of an invalid source would be one that pushes one value to the stack then attempts to pops two values, clearly we cannot remove more values than we added. The IExpressionDeployerV1 MUST revert in the case of any integrity failure, all integrity checks MUST pass in order for the deployment to complete. Once the integrity check is complete the IExpressionDeployerV1 MUST do any additional processing required by its paired interpreter. For example, the IExpressionDeployerV1 MAY NEED to replace the indexed opcodes in the ExpressionConfig sources with real function pointers from the corresponding interpreter.

function deployExpression(bytes[] memory sources, uint256[] memory constants, uint256[] memory minOutputs)
    external
    returns (IInterpreterV1 interpreter, IInterpreterStoreV1 store, address expression);

Parameters

Returns

Events

DISpair

This is the literal InterpreterOpMeta bytes to be used offchain to make sense of the opcodes in this interpreter deployment, as a human. For formats like json that make heavy use of boilerplate, repetition and whitespace, some kind of compression is recommended.

event DISpair(address sender, address deployer, address interpreter, address store, bytes opMeta);

Parameters

Constants

Git Source

IERC1820_NAME_IEXPRESSION_DEPLOYER_V1

string constant IERC1820_NAME_IEXPRESSION_DEPLOYER_V1 = "IExpressionDeployerV1";

IExpressionDeployerV2

Git Source

Companion to IInterpreterV1 responsible for onchain static code analysis and deploying expressions. Each IExpressionDeployerV2 is tightly coupled at the bytecode level to some interpreter that it knows how to analyse and deploy expressions for. The expression deployer can perform an integrity check "dry run" of candidate source code for the intepreter. The critical analysis/transformation includes:

• Enforcement of no out of bounds memory reads/writes
• Calculation of memory required to eval the stack with a single allocation
• Replacing index based opcodes with absolute interpreter function pointers
• Enforcement that all opcodes and operands used exist and are valid This analysis is highly sensitive to the specific implementation and position of all opcodes and function pointers as compiled into the interpreter. This is what makes the coupling between an interpreter and expression deployer so tight. Ideally all responsibilities would be handled by a single contract but this introduces code size issues quickly by roughly doubling the compiled logic of each opcode (half for the integrity check and half for evaluation). Interpreters MUST assume that expression deployers are malicious and fail gracefully if the integrity check is corrupt/bypassed and/or function pointers are incorrect, etc. i.e. the interpreter MUST always return a stack from eval in a read only way or error. I.e. it is the expression deployer's responsibility to do everything it can to prevent undefined behaviour in the interpreter, and the interpreter's responsibility to handle the expression deployer completely failing to do so.

Functions

deployExpression

Expressions are expected to be deployed onchain as immutable contract code with a first class address like any other contract or account. Technically this is optional in the sense that all the tools required to eval some expression and define all its opcodes are available as libraries. In practise there are enough advantages to deploying the sources directly onchain as contract data and loading them from the interpreter at eval:

• Loading and storing binary data is gas efficient as immutable contract data
• Expressions need to be immutable between their deploy time integrity check and runtime evaluation
• Passing the address of an expression through calldata to an interpreter is cheaper than passing an entire expression through calldata
• Conceptually a very simple approach, even if implementations like SSTORE2 are subtle under the hood The expression deployer MUST perform an integrity check of the source code before it puts the expression onchain at a known address. The integrity check MUST at a minimum (it is free to do additional static analysis) calculate the memory required to be allocated for the stack in total, and that no out of bounds memory reads/writes occur within this stack. A simple example of an invalid source would be one that pushes one value to the stack then attempts to pops two values, clearly we cannot remove more values than we added. The IExpressionDeployerV2 MUST revert in the case of any integrity failure, all integrity checks MUST pass in order for the deployment to complete. Once the integrity check is complete the IExpressionDeployerV2 MUST do any additional processing required by its paired interpreter. For example, the IExpressionDeployerV2 MAY NEED to replace the indexed opcodes in the ExpressionConfig sources with real function pointers from the corresponding interpreter.

function deployExpression(bytes calldata bytecode, uint256[] calldata constants, uint256[] calldata minOutputs)
    external
    returns (IInterpreterV1 interpreter, IInterpreterStoreV1 store, address expression);

Parameters

Returns

Events

DISpair

This is the literal InterpreterOpMeta bytes to be used offchain to make sense of the opcodes in this interpreter deployment, as a human. For formats like json that make heavy use of boilerplate, repetition and whitespace, some kind of compression is recommended.

event DISpair(address sender, address deployer, address interpreter, address store, bytes meta);

Parameters

Constants

Git Source

IERC1820_NAME_IEXPRESSION_DEPLOYER_V2

string constant IERC1820_NAME_IEXPRESSION_DEPLOYER_V2 = "IExpressionDeployerV2";

EvaluableConfig

Git Source

Standard struct that can be embedded in ABIs in a consistent format for tooling to read/write. MAY be useful to bundle up the data required to call IExpressionDeployerV1 but is NOT mandatory.

struct EvaluableConfig {
    IExpressionDeployerV1 deployer;
    bytes[] sources;
    uint256[] constants;
}

Properties

EvaluableConfigV2

Git Source

Standard struct that can be embedded in ABIs in a consistent format for tooling to read/write. MAY be useful to bundle up the data required to call IExpressionDeployerV2 but is NOT mandatory.

struct EvaluableConfigV2 {
    IExpressionDeployerV2 deployer;
    bytes bytecode;
    uint256[] constants;
}

Properties

Evaluable

Git Source

Struct over the return of IExpressionDeployerV1.deployExpression which MAY be more convenient to work with than raw addresses.

struct Evaluable {
    IInterpreterV1 interpreter;
    IInterpreterStoreV1 store;
    address expression;
}

Properties

SignedContext

Git Source

Typed embodiment of some context data with associated signer and signature. The signature MUST be over the packed encoded bytes of the context array, i.e. the context array concatenated as bytes without the length prefix, then hashed, then handled as per EIP-191 to produce a final hash to be signed. The calling contract (likely with the help of LibContext) is responsible for ensuring the authenticity of the signature, but not authorizing who can sign. IN ADDITION to authorisation of the signer to known-good entities the expression is also responsible for:

• Enforcing the context is the expected data (e.g. with a domain separator)
• Tracking and enforcing nonces if signed contexts are only usable one time
• Tracking and enforcing uniqueness of signed data if relevant
• Checking and enforcing expiry times if present and relevant in the context
• Many other potential constraints that expressions may want to enforce EIP-1271 smart contract signatures are supported in addition to EOA signatures via. the Open Zeppelin SignatureChecker library, which is wrapped by LibContext.build. As smart contract signatures are checked onchain they CAN BE REVOKED AT ANY MOMENT as the smart contract can simply return false when it previously returned true.

struct SignedContext {
    address signer;
    bytes signature;
    uint256[] context;
}

Properties

IInterpreterCallerV1

Git Source

A contract that calls an IInterpreterV1 via. eval. There are near zero requirements on a caller other than:

• Emit some meta about itself upon construction so humans know what the contract does
• Provide the context, which can be built in a standard way by LibContext
• Handle the stack array returned from eval
• OPTIONALLY emit the Context event
• OPTIONALLY set state on the IInterpreterStoreV1 returned from eval.

Events

Context

Calling contracts SHOULD emit Context before calling eval if they are able. Notably eval MAY be called within a static call which means that events cannot be emitted, in which case this does not apply. It MAY NOT be useful to emit this multiple times for several eval calls if they all share a common context, in which case a single emit is sufficient.

event Context(address sender, uint256[][] context);

Parameters

Constants

Git Source

SIGNED_CONTEXT_SIGNER_OFFSET

uint256 constant SIGNED_CONTEXT_SIGNER_OFFSET = 0;

SIGNED_CONTEXT_CONTEXT_OFFSET

uint256 constant SIGNED_CONTEXT_CONTEXT_OFFSET = 0x20;

SIGNED_CONTEXT_SIGNATURE_OFFSET

uint256 constant SIGNED_CONTEXT_SIGNATURE_OFFSET = 0x40;

EncodedExternDispatch

Git Source

type EncodedExternDispatch is uint256;

ExternDispatch

Git Source

type ExternDispatch is uint256;

IInterpreterExternV1

Git Source

Functions

extern

Handles a single dispatch.

function extern(ExternDispatch dispatch, uint256[] memory inputs) external view returns (uint256[] memory outputs);

Parameters

Returns

IInterpreterExternV2

Git Source

Functions

extern

Handles a single dispatch.

function extern(ExternDispatch dispatch, uint256[] calldata inputs)
    external
    view
    returns (uint256[] calldata outputs);

Parameters

Returns

SourceIndex

Git Source

The index of a source within a deployed expression that can be evaluated by an IInterpreterV1. MAY be an entrypoint or the index of a source called internally such as by the call opcode.

type SourceIndex is uint16;

EncodedDispatch

Git Source

Encoded information about a specific evaluation including the expression address onchain, entrypoint and expected return values.

type EncodedDispatch is uint256;

StateNamespace

Git Source

The namespace for state changes as requested by the calling contract. The interpreter MUST apply this namespace IN ADDITION to namespacing by caller etc.

type StateNamespace is uint256;

Operand

Git Source

Additional bytes that can be used to configure a single opcode dispatch. Commonly used to specify the number of inputs to a variadic function such as addition or multiplication.

type Operand is uint256;

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

Returns

Constants

Git Source

DEFAULT_STATE_NAMESPACE

The default state namespace MUST be used when a calling contract has no particular opinion on or need for dynamic namespaces.

StateNamespace constant DEFAULT_STATE_NAMESPACE = StateNamespace.wrap(0);

Contents

• IExpressionDeployerV3
• IExpressionDeployerV3 constants
• IInterpreterExternV3
• IInterpreterStoreV2
• SourceIndexV2
• IInterpreterV2
• IInterpreterV2 constants
• ISubParserV1
• ISubParserV1 constants

IExpressionDeployerV3

Git Source

Companion to IInterpreterV2 responsible for onchain static code analysis and deploying expressions. Each IExpressionDeployerV3 is tightly coupled at the bytecode level to some interpreter that it knows how to analyse and deploy expressions for. The expression deployer can perform an integrity check "dry run" of candidate source code for the intepreter. The critical analysis/transformation includes:

• Enforcement of no out of bounds memory reads/writes
• Calculation of memory required to eval the stack with a single allocation
• Replacing index based opcodes with absolute interpreter function pointers
• Enforcement that all opcodes and operands used exist and are valid This analysis is highly sensitive to the specific implementation and position of all opcodes and function pointers as compiled into the interpreter. This is what makes the coupling between an interpreter and expression deployer so tight. Ideally all responsibilities would be handled by a single contract but this introduces code size issues quickly by roughly doubling the compiled logic of each opcode (half for the integrity check and half for evaluation). Interpreters MUST assume that expression deployers are malicious and fail gracefully if the integrity check is corrupt/bypassed and/or function pointers are incorrect, etc. i.e. the interpreter MUST always return a stack from eval in a read only way or error. I.e. it is the expression deployer's responsibility to do everything it can to prevent undefined behaviour in the interpreter, and the interpreter's responsibility to handle the expression deployer completely failing to do so.

Functions

deployExpression2

Expressions are expected to be deployed onchain as immutable contract code with a first class address like any other contract or account. Technically this is optional in the sense that all the tools required to eval some expression and define all its opcodes are available as libraries. In practise there are enough advantages to deploying the sources directly onchain as contract data and loading them from the interpreter at eval:

• Loading and storing binary data is gas efficient as immutable contract data
• Expressions need to be immutable between their deploy time integrity check and runtime evaluation
• Passing the address of an expression through calldata to an interpreter is cheaper than passing an entire expression through calldata
• Conceptually a very simple approach, even if implementations like SSTORE2 are subtle under the hood The expression deployer MUST perform an integrity check of the source code before it puts the expression onchain at a known address. The integrity check MUST at a minimum (it is free to do additional static analysis) calculate the memory required to be allocated for the stack in total, and that no out of bounds memory reads/writes occur within this stack. A simple example of an invalid source would be one that pushes one value to the stack then attempts to pops two values, clearly we cannot remove more values than we added. The IExpressionDeployerV3 MUST revert in the case of any integrity failure, all integrity checks MUST pass in order for the deployment to complete. Once the integrity check is complete the IExpressionDeployerV3 MUST do any additional processing required by its paired interpreter. For example, the IExpressionDeployerV3 MAY NEED to replace the indexed opcodes in the ExpressionConfig sources with real function pointers from the corresponding interpreter. The caller MUST check the io returned by this function to determine the number of inputs and outputs for each source are within the bounds of the caller's expectations.

function deployExpression2(bytes calldata bytecode, uint256[] calldata constants)
    external
    returns (IInterpreterV2 interpreter, IInterpreterStoreV1 store, address expression, bytes calldata io);

Parameters

Returns

Events

NewExpression

The config of the deployed expression including uncompiled sources. MUST be emitted after the config passes the integrity check.

event NewExpression(address sender, bytes bytecode, uint256[] constants);

Parameters

DeployedExpression

The address of the deployed expression. MUST be emitted once the expression can be loaded and deserialized into an evaluable interpreter state.

event DeployedExpression(
    address sender, IInterpreterV2 interpreter, IInterpreterStoreV1 store, address expression, bytes io
);

Parameters

DISPair

This is the literal InterpreterOpMeta bytes to be used offchain to make sense of the opcodes in this interpreter deployment, as a human. For formats like json that make heavy use of boilerplate, repetition and whitespace, some kind of compression is recommended. The DISPair is a pairing of:

• Deployer (this contract)
• Interpreter
• Store
• Parser

event DISPair(address sender, address interpreter, address store, address parser, bytes meta);

Parameters

Constants

Git Source

IERC1820_NAME_IEXPRESSION_DEPLOYER_V3

string constant IERC1820_NAME_IEXPRESSION_DEPLOYER_V3 = "IExpressionDeployerV3";

IInterpreterExternV3

Git Source

Functions

externIntegrity

Checks the integrity of some extern call.

function externIntegrity(ExternDispatch dispatch, uint256 expectedInputs, uint256 expectedOutputs)
    external
    view
    returns (uint256 actualInputs, uint256 actualOutputs);

Parameters

Returns

extern

Handles a single dispatch.

function extern(ExternDispatch dispatch, uint256[] calldata inputs)
    external
    view
    returns (uint256[] calldata outputs);

Parameters

Returns

IInterpreterStoreV2

Git Source

Tracks state changes on behalf of an interpreter. A single store can handle state changes for many calling contracts, many interpreters and many expressions. The store is responsible for ensuring that applying these state changes is safe from key collisions with calls to set from different msg.sender callers. I.e. it MUST NOT be possible for a caller to modify the state changes associated with some other caller. The store defines the shape of its own state changes, which is opaque to the calling contract. For example, some store may treat the list of state changes as a pairwise key/value set, and some other store may treat it as a literal list to be stored as-is. Each interpreter decides for itself which store to use based on the compatibility of its own opcodes. The store MUST assume the state changes have been corrupted by the calling contract due to bugs or malicious intent, and enforce state isolation between callers despite arbitrarily invalid state changes. The store MUST revert if it can detect invalid state changes, such as a key/value list having an odd number of items, but this MAY NOT be possible if the corruption is undetectable.

Functions

set

Mutates the interpreter store in bulk. The bulk values are provided in the form of a uint256[] which can be treated e.g. as pairwise keys and values to be stored in a Solidity mapping. The IInterpreterStoreV2 defines the meaning of the uint256[] for its own storage logic.

function set(StateNamespace namespace, uint256[] calldata kvs) external;

Parameters

get

Given a fully qualified namespace and key, return the associated value. Ostensibly the interpreter can use this to implement opcodes that read previously set values. The interpreter MUST apply the same qualification logic as the store that it uses to guarantee consistent round tripping of data and prevent malicious behaviours. Technically also allows onchain reads of any set value from any contract, not just interpreters, but in this case readers MUST be aware and handle inconsistencies between get and set while the state changes are still in memory in the calling context and haven't yet been persisted to the store. IInterpreterStoreV2 uses the same fallback behaviour for unset keys as Solidity. Specifically, any UNSET VALUES SILENTLY FALLBACK TO 0.

function get(FullyQualifiedNamespace namespace, uint256 key) external view returns (uint256);

Parameters

Returns

Events

Set

MUST be emitted by the store on set to its internal storage.

event Set(FullyQualifiedNamespace namespace, uint256 key, uint256 value);

Parameters

SourceIndexV2

Git Source

The index of a source within a deployed expression that can be evaluated by an IInterpreterV2. MAY be an entrypoint or the index of a source called internally such as by the call opcode.

type SourceIndexV2 is uint256;

IInterpreterV2

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. IExpressionDeployerV3 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, IExpressionDeployerV3 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 calldata);

eval2

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. There are two key differences between eval and eval2:

• eval was ambiguous about whether the top value of the final stack is the first or last item of the array. eval2 is unambiguous in that the top of the stack MUST be the first item in the array.
• eval2 allows the caller to specify inputs to the entrypoint stack of the expression. This allows the eval and offchainDebugEval functions to be merged into a single function that can be used for both onchain and offchain evaluation. For example, the caller can simulate "internal" calls by specifying the inputs to the entrypoint stack of the expression as the outputs of some other expression. Legacy behaviour can be achieved by passing an empty array for inputs.

function eval2(
    IInterpreterStoreV1 store,
    FullyQualifiedNamespace namespace,
    EncodedDispatch dispatch,
    uint256[][] calldata context,
    uint256[] calldata inputs
) external view returns (uint256[] calldata stack, uint256[] calldata writes);

Parameters

Returns

Constants

Git Source

OPCODE_STACK

For maximum compatibility with external contracts, the IInterpreterV2 should implement an opcode that reads from the stack by index as opcode 0.

uint256 constant OPCODE_STACK = 0;

OPCODE_CONSTANT

For maximum compatibility with external contracts, the IInterpreterV2 should implement an opcode that reads constants by index as opcode 1.

uint256 constant OPCODE_CONSTANT = 1;

OPCODE_EXTERN

For maximum compatibility with external contracts, the IInterpreterV2 should implement an opcode that calls externs by index as opcode 2.

uint256 constant OPCODE_EXTERN = 2;

OPCODE_UNKNOWN

For maximum compatibility with opcode lists, the IInterpreterV2 should implement the opcode for locally unknown words that need sub parsing as opcode 255.

uint256 constant OPCODE_UNKNOWN = 0xFF;

ISubParserV1

Git Source

Functions

subParse

Handle parsing some data on behalf of a parser. The structure and meaning of the data is entirely up to the parser, the compatibility version indicates a unique ID for a particular parseble data convention.

function subParse(bytes32 compatibility, bytes calldata data)
    external
    pure
    returns (bool success, bytes calldata bytecode, uint256[] calldata constants);

Parameters

Returns

Constants

Git Source

COMPATIBLITY_V0

*This is the first compatibility version of the subparser interface. Likely it won't survive long, but it's here to demonstrate the concept. The structure of data for this version is:

• bytes [0,1]: The current height of the constants array on the main parser.
• bytes [2,2]: The IO byte, that at the time of writing represents the number of inputs to the word.
• bytes [3, .. ]: A string slice that the parser could not parse. For well formed rainlang it will be a word and any associated operands, from the first word char to the char before the opening ( paren.*

bytes32 constant COMPATIBLITY_V0 = keccak256("2023.12.17 Rainlang Parser v0");

COMPATIBLITY_V1

*This is the second compatibility version of the subparser interface. Likely it won't survive long, but it's here to demonstrate the concept. The structure of data for this version is:

• bytes [0,1]: The current height of the constants array on the main parser.
• bytes [2,2]: The IO byte, that at the time of writing represents the number of inputs to the word.
• bytes [3,4]; Two bytes that encodes N where N is the length in bytes of the rainlang word that could not be parsed in bytes.
• bytes [5, N+5]: A string slice that the parser could not parse. For well formed rainlang it will be a word WITHOUT any associated operands. The parsing of operands is handled by the main parser, and the subparser is only expected to parse the word itself and handle the pre-parsed operand values.
• bytes [N+5,...]: The operands that the main parser has already parsed as a standard uint256[] array. The subparser is expected to handle these operands as-is, and return bytecode that is compatible with the operand values. The first word of the array is the array length.*

bytes32 constant COMPATIBLITY_V1 = keccak256("2023.12.26 Rainlang Parser v1");

EvaluableConfigV3

Git Source

Standard struct that can be embedded in ABIs in a consistent format for tooling to read/write. MAY be useful to bundle up the data required to call IExpressionDeployerV3 but is NOT mandatory.

struct EvaluableConfigV3 {
    IExpressionDeployerV3 deployer;
    bytes bytecode;
    uint256[] constants;
}

Properties

EvaluableV2

Git Source

Struct over the return of IExpressionDeployerV3.deployExpression2 which MAY be more convenient to work with than raw addresses.

struct EvaluableV2 {
    IInterpreterV2 interpreter;
    IInterpreterStoreV1 store;
    address expression;
}

Properties

SignedContextV1

Git Source

Typed embodiment of some context data with associated signer and signature. The signature MUST be over the packed encoded bytes of the context array, i.e. the context array concatenated as bytes without the length prefix, then hashed, then handled as per EIP-191 to produce a final hash to be signed. The calling contract (likely with the help of LibContext) is responsible for ensuring the authenticity of the signature, but not authorizing who can sign. IN ADDITION to authorisation of the signer to known-good entities the expression is also responsible for:

• Enforcing the context is the expected data (e.g. with a domain separator)
• Tracking and enforcing nonces if signed contexts are only usable one time
• Tracking and enforcing uniqueness of signed data if relevant
• Checking and enforcing expiry times if present and relevant in the context
• Many other potential constraints that expressions may want to enforce EIP-1271 smart contract signatures are supported in addition to EOA signatures via. the Open Zeppelin SignatureChecker library, which is wrapped by LibContext.build. As smart contract signatures are checked onchain they CAN BE REVOKED AT ANY MOMENT as the smart contract can simply return false when it previously returned true.

struct SignedContextV1 {
    address signer;
    uint256[] context;
    bytes signature;
}

Properties

IInterpreterCallerV2

Git Source

A contract that calls an IInterpreterV1 via. eval. There are near zero requirements on a caller other than:

• Emit some meta about itself upon construction so humans know what the contract does
• Provide the context, which can be built in a standard way by LibContext
• Handle the stack array returned from eval
• OPTIONALLY emit the Context event
• OPTIONALLY set state on the IInterpreterStoreV1 returned from eval.

Events

Context

Calling contracts SHOULD emit Context before calling eval if they are able. Notably eval MAY be called within a static call which means that events cannot be emitted, in which case this does not apply. It MAY NOT be useful to emit this multiple times for several eval calls if they all share a common context, in which case a single emit is sufficient.

event Context(address sender, uint256[][] context);

Parameters

Constants

Git Source

SIGNED_CONTEXT_SIGNER_OFFSET

uint256 constant SIGNED_CONTEXT_SIGNER_OFFSET = 0;

SIGNED_CONTEXT_CONTEXT_OFFSET

uint256 constant SIGNED_CONTEXT_CONTEXT_OFFSET = 0x20;

SIGNED_CONTEXT_SIGNATURE_OFFSET

uint256 constant SIGNED_CONTEXT_SIGNATURE_OFFSET = 0x40;

FullyQualifiedNamespace

Git Source

A fully qualified namespace includes the interpreter's own namespacing logic IN ADDITION to the calling contract's requested StateNamespace. Typically this involves hashing the msg.sender into the StateNamespace so that each caller operates within its own disjoint state universe. Intepreters MUST NOT allow either the caller nor any expression/word to modify this directly on pain of potential key collisions on writes to the interpreter's own storage.

type FullyQualifiedNamespace is uint256;

IInterpreterStoreV1

Git Source

Tracks state changes on behalf of an interpreter. A single store can handle state changes for many calling contracts, many interpreters and many expressions. The store is responsible for ensuring that applying these state changes is safe from key collisions with calls to set from different msg.sender callers. I.e. it MUST NOT be possible for a caller to modify the state changes associated with some other caller. The store defines the shape of its own state changes, which is opaque to the calling contract. For example, some store may treat the list of state changes as a pairwise key/value set, and some other store may treat it as a literal list to be stored as-is. Each interpreter decides for itself which store to use based on the compatibility of its own opcodes. The store MUST assume the state changes have been corrupted by the calling contract due to bugs or malicious intent, and enforce state isolation between callers despite arbitrarily invalid state changes. The store MUST revert if it can detect invalid state changes, such as a key/value list having an odd number of items, but this MAY NOT be possible if the corruption is undetectable.

Functions

set

Mutates the interpreter store in bulk. The bulk values are provided in the form of a uint256[] which can be treated e.g. as pairwise keys and values to be stored in a Solidity mapping. The IInterpreterStoreV1 defines the meaning of the uint256[] for its own storage logic.

function set(StateNamespace namespace, uint256[] calldata kvs) external;

Parameters

get

Given a fully qualified namespace and key, return the associated value. Ostensibly the interpreter can use this to implement opcodes that read previously set values. The interpreter MUST apply the same qualification logic as the store that it uses to guarantee consistent round tripping of data and prevent malicious behaviours. Technically also allows onchain reads of any set value from any contract, not just interpreters, but in this case readers MUST be aware and handle inconsistencies between get and set while the state changes are still in memory in the calling context and haven't yet been persisted to the store. IInterpreterStoreV1 uses the same fallback behaviour for unset keys as Solidity. Specifically, any UNSET VALUES SILENTLY FALLBACK TO 0.

function get(FullyQualifiedNamespace namespace, uint256 key) external view returns (uint256);

Parameters

Returns

Constants

Git Source

NO_STORE

IInterpreterStoreV1 constant NO_STORE = IInterpreterStoreV1(address(0));

AuthoringMeta

Git Source

struct AuthoringMeta {
    bytes32 word;
    uint8 operandParserOffset;
    string description;
}

AuthoringMetaV2

Git Source

Identical to AuthoringMeta but without operandParserOffset.

struct AuthoringMetaV2 {
    bytes32 word;
    string description;
}

IParserV1

Git Source

Functions

parse

Parses a Rainlang string into an evaluable expression. MUST be deterministic and MUST NOT have side effects. The only inputs are the Rainlang string and the parse meta. MAY revert if the Rainlang string is invalid. This function takes bytes instead of string to allow for definitions of "string" other than UTF-8.

function parse(bytes calldata data) external pure returns (bytes calldata bytecode, uint256[] calldata constants);

Parameters

Returns

Contents

• bitwise
• bytecode
• caller
• compile
• eval
• extern
• integrity
• ns
• op
• parse
• state

Contents

• LibCtPop
• LibCtPop constants

LibCtPop

Git Source

Functions

ctpop

Optimised version of ctpop. https://en.wikipedia.org/wiki/Hamming_weight

function ctpop(uint256 x) internal pure returns (uint256);

ctpopSlow

This is the slowest possible implementation of ctpop. It is used to verify the correctness of the optimized implementation in LibCtPop. It should be obviously correct by visual inspection, referencing the wikipedia article. https://en.wikipedia.org/wiki/Hamming_weight

function ctpopSlow(uint256 x) internal pure returns (uint256);

Constants

Git Source

CTPOP_M1

010101... for ctpop

uint256 constant CTPOP_M1 = 0x5555555555555555555555555555555555555555555555555555555555555555;

CTPOP_M2

00110011.. for ctpop

uint256 constant CTPOP_M2 = 0x3333333333333333333333333333333333333333333333333333333333333333;

CTPOP_M4

4 bits alternating for ctpop

uint256 constant CTPOP_M4 = 0x0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F0F;

CTPOP_M8

8 bits alternating for ctpop

uint256 constant CTPOP_M8 = 0x00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF00FF;

CTPOP_M16

16 bits alternating for ctpop

uint256 constant CTPOP_M16 = 0x0000FFFF0000FFFF0000FFFF0000FFFF0000FFFF0000FFFF0000FFFF0000FFFF;

CTPOP_M32

32 bits alternating for ctpop

uint256 constant CTPOP_M32 = 0x00000000FFFFFFFF00000000FFFFFFFF00000000FFFFFFFF00000000FFFFFFFF;

CTPOP_M64

64 bits alternating for ctpop

uint256 constant CTPOP_M64 = 0x0000000000000000FFFFFFFFFFFFFFFF0000000000000000FFFFFFFFFFFFFFFF;

CTPOP_M128

128 bits alternating for ctpop

uint256 constant CTPOP_M128 = 0x00000000000000000000000000000000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF;

CTPOP_H01

1 bytes for ctpop

uint256 constant CTPOP_H01 = 0x0101010101010101010101010101010101010101010101010101010101010101;

Contents

• LibBytecode

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);

Contents

• InvalidSignature
• LibContext
• LibDeployerDiscoverable
• LibEncodedDispatch
• LibEvaluable

InvalidSignature

Git Source

Thrown when the ith signature from a list of signed contexts is invalid.

error InvalidSignature(uint256 i);

LibContext

Git Source

Conventions for working with context as a calling contract. All of this functionality is OPTIONAL but probably useful for the majority of use cases. By building and authenticating onchain, caller provided and signed contexts all in a standard way the overall usability of context is greatly improved for expression authors and readers. Any calling contract that can match the context expectations of an existing expression is one large step closer to compatibility and portability, inheriting network effects of what has already been authored elsewhere.

Functions

base

The base context is the msg.sender and address of the calling contract. As the interpreter itself is called via an external interface and may be statically calling itself, it MAY NOT have any ability to inspect either of these values. Even if this were not the case the calling contract cannot assume the existence of some opcode(s) in the interpreter that inspect the caller, so providing these two values as context is sufficient to decouple the calling contract from the interpreter. It is STRONGLY RECOMMENDED that even if the calling contract has "no context" that it still provides this base to every eval. Calling contracts DO NOT need to call this directly. It is built and merged automatically into the standard context built by build.

function base() internal view returns (uint256[] memory);

Returns

hash

Standard hashing process over a single SignedContextV1. Notably used to hash a list as SignedContextV1[] but could also be used to hash a single SignedContextV1 in isolation. Avoids allocating memory by hashing each struct field in sequence within the memory scratch space.

function hash(SignedContextV1 memory signedContext) internal pure returns (bytes32 hashed);

Parameters

hash

Standard hashing process over a list of signed contexts. Situationally useful if the calling contract wants to record that it has seen a set of signed data then later compare it against some input (e.g. to ensure that many calls of some function all share the same input values). Note that unlike the internals of build, this hashes over the signer and the signature, to ensure that some data cannot be re-signed and used under a different provenance later.

function hash(SignedContextV1[] memory signedContexts) internal pure returns (bytes32 hashed);

Parameters

Returns

build

Builds a standard 2-dimensional context array from base, calling and signed contexts. Note that "columns" of a context array refer to each uint256[] and each item within a uint256[] is a "row".

function build(uint256[][] memory baseContext, SignedContextV1[] memory signedContexts)
    internal
    view
    returns (uint256[][] memory);

Parameters

LibDeployerDiscoverable

Git Source

Functions

touchDeployerV3

Hack so that some deployer will emit an event with the sender as the caller of touchDeployer. This MAY be needed by indexers such as subgraph that can only index events from the first moment they are aware of some contract. The deployer MUST be registered in ERC1820 registry before it is touched, THEN the caller meta MUST be emitted after the deployer is touched. This allows indexers such as subgraph to index the deployer, then see the caller, then see the caller's meta emitted in the same transaction. This is NOT required if ANY other expression is deployed in the same transaction as the caller meta, there only needs to be one expression on ANY deployer known to ERC1820.

function touchDeployerV3(address deployer) internal;

LibEncodedDispatch

Git Source

Establishes and implements a convention for encoding an interpreter dispatch. Handles encoding of several things required for efficient dispatch.

Functions

encode2

Builds an EncodedDispatch from its constituent parts.

function encode2(address expression, SourceIndexV2 sourceIndex, uint256 maxOutputs)
    internal
    pure
    returns (EncodedDispatch);

Parameters

Returns

decode2

function decode2(EncodedDispatch dispatch) internal pure returns (address, SourceIndexV2, uint256);

LibEvaluable

Git Source

Common logic to provide consistent implementations of common tasks that could be arbitrarily/ambiguously implemented, but work much better if consistently implemented.

Functions

hash

Hashes an Evaluable, ostensibly so that only the hash need be stored, thus only storing a single uint256 instead of 3x uint160.

function hash(EvaluableV2 memory evaluable) internal pure returns (bytes32 evaluableHash);

Parameters

Returns

Contents

• LibCompile

LibCompile

Git Source

Functions

unsafeCompile

Given a source in opcodes compile to an equivalent source with real function pointers for a given Interpreter contract. The "compilation" involves simply replacing the opcode with the pointer at the index of the opcode. i.e. opcode 4 will be replaced with pointers_[4]. Relies heavily on the integrity checks ensuring opcodes used are not OOB and that the pointers provided are valid and in the correct order. As the expression deployer is typically handling compilation during serialization, NOT the interpreter, the interpreter MUST guard against the compilation being garbage or outright hostile during eval by pointing to arbitrary internal functions of the interpreter.

function unsafeCompile(bytes memory source, bytes memory pointers) internal pure;

Parameters

Contents

• InputsLengthMismatch
• LibEvalNP

InputsLengthMismatch

Git Source

Thrown when the inputs length does not match the expected inputs length.

error InputsLengthMismatch(uint256 expected, uint256 actual);

Parameters

LibEvalNP

Git Source

Functions

evalLoopNP

function evalLoopNP(InterpreterStateNP memory state, Pointer stackTop) internal view returns (Pointer);

eval2

function eval2(InterpreterStateNP memory state, uint256[] memory inputs, uint256 maxOutputs)
    internal
    view
    returns (uint256[] memory, uint256[] memory);

Contents

• LibExtern

LibExtern

Git Source

Functions

encodeExternDispatch

Converts an opcode and operand pair into a single 32-byte word. The encoding scheme is:

• bits [0,16): the operand
• bits [16,32): the opcode IMPORTANT: The encoding process does not check that either the opcode or operand fit within 16 bits. This is the responsibility of the caller.

function encodeExternDispatch(uint256 opcode, Operand operand) internal pure returns (ExternDispatch);

decodeExternDispatch

Inverse of encodeExternDispatch.

function decodeExternDispatch(ExternDispatch dispatch) internal pure returns (uint256, Operand);

encodeExternCall

Encodes an extern address and dispatch pair into a single 32-byte word. This is the full data required to actually call an extern contract. The encoding scheme is:

• bits [0,160): the address of the extern contract
• bits [160,176): the dispatch operand
• bits [176,192): the dispatch opcode Note that the high bits are implied by a correctly encoded ExternDispatch. Use encodeExternDispatch to ensure this. IMPORTANT: The encoding process does not check that any of the values fit within their respective bit ranges. This is the responsibility of the caller.

function encodeExternCall(IInterpreterExternV3 extern, ExternDispatch dispatch)
    internal
    pure
    returns (EncodedExternDispatch);

decodeExternCall

Inverse of encodeExternCall.

function decodeExternCall(EncodedExternDispatch dispatch)
    internal
    pure
    returns (IInterpreterExternV3, ExternDispatch);

Contents

• EntrypointMissing
• EntrypointNonZeroInput
• BadOpInputsLength
• StackUnderflow
• StackUnderflowHighwater
• StackAllocationMismatch
• StackOutputsMismatch
• IntegrityCheckStateNP
• LibIntegrityCheckNP

EntrypointMissing

Git Source

There are more entrypoints defined by the minimum stack outputs than there are provided sources. This means the calling contract WILL attempt to eval a dangling reference to a non-existent source at some point, so this MUST REVERT.

error EntrypointMissing(uint256 expectedEntrypoints, uint256 actualEntrypoints);

EntrypointNonZeroInput

Git Source

Thrown when some entrypoint has non-zero inputs. This is not allowed as only internal dispatches can have source level inputs.

error EntrypointNonZeroInput(uint256 entrypointIndex, uint256 inputsLength);

BadOpInputsLength

Git Source

The bytecode and integrity function disagree on number of inputs.

error BadOpInputsLength(uint256 opIndex, uint256 calculatedInputs, uint256 bytecodeInputs);

StackUnderflow

Git Source

The stack underflowed during integrity check.

error StackUnderflow(uint256 opIndex, uint256 stackIndex, uint256 calculatedInputs);

StackUnderflowHighwater

Git Source

The stack underflowed the highwater during integrity check.

error StackUnderflowHighwater(uint256 opIndex, uint256 stackIndex, uint256 stackHighwater);

StackAllocationMismatch

Git Source

The bytecode stack allocation does not match the allocation calculated by the integrity check.

error StackAllocationMismatch(uint256 stackMaxIndex, uint256 bytecodeAllocation);

StackOutputsMismatch

Git Source

The final stack index does not match the bytecode outputs.

error StackOutputsMismatch(uint256 stackIndex, uint256 bytecodeOutputs);

IntegrityCheckStateNP

Git Source

struct IntegrityCheckStateNP {
    uint256 stackIndex;
    uint256 stackMaxIndex;
    uint256 readHighwater;
    uint256[] constants;
    uint256 opIndex;
    bytes bytecode;
}

LibIntegrityCheckNP

Git Source

Functions

newState

function newState(bytes memory bytecode, uint256 stackIndex, uint256[] memory constants)
    internal
    pure
    returns (IntegrityCheckStateNP memory);

integrityCheck2

function integrityCheck2(bytes memory fPointers, bytes memory bytecode, uint256[] memory constants)
    internal
    view
    returns (bytes memory io);

Contents

• LibNamespace

LibNamespace

Git Source

Functions

qualifyNamespace

Standard way to elevate a caller-provided state namespace to a universal namespace that is disjoint from all other caller-provided namespaces. Essentially just hashes the msg.sender into the state namespace as-is. This is deterministic such that the same combination of state namespace and caller will produce the same fully qualified namespace, even across multiple transactions/blocks.

function qualifyNamespace(StateNamespace stateNamespace, address sender)
    internal
    pure
    returns (FullyQualifiedNamespace qualifiedNamespace);

Parameters

Returns

Contents

• 00
• bitwise
• call
• context
• crypto
• erc20
• erc5313
• erc721
• evm
• logic
• math
• store
• uniswap
• LibAllStandardOpsNP
• LibAllStandardOpsNP constants

Contents

• OutOfBoundsConstantRead
• LibOpConstantNP
• OutOfBoundsConstantRead
• BadOutputsLength
• LibOpExternNP
• OutOfBoundsStackRead
• LibOpStackNP

OutOfBoundsConstantRead

Git Source

Thrown when a constant read index is outside the constants array.

error OutOfBoundsConstantRead(uint256 opIndex, uint256 constantsLength, uint256 constantRead);

LibOpConstantNP

Git Source

Functions

integrity

function integrity(IntegrityCheckStateNP memory state, Operand operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory state, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory state, Operand operand, uint256[] memory)
    internal
    pure
    returns (uint256[] memory outputs);

OutOfBoundsConstantRead

Git Source

Thrown when a constant read index is outside the constants array.

error OutOfBoundsConstantRead(uint256 opIndex, uint256 constantsLength, uint256 constantRead);

BadOutputsLength

Git Source

Thrown when the outputs length is not equal to the expected length.

error BadOutputsLength(uint256 expectedLength, uint256 actualLength);

LibOpExternNP

Git Source

Implementation of calling an external contract.

Functions

integrity

function integrity(IntegrityCheckStateNP memory state, Operand operand) internal view returns (uint256, uint256);

run

function run(InterpreterStateNP memory state, Operand operand, Pointer stackTop) internal view returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory state, Operand operand, uint256[] memory inputs)
    internal
    view
    returns (uint256[] memory outputs);

OutOfBoundsStackRead

Git Source

Thrown when a stack read index is outside the current stack top.

error OutOfBoundsStackRead(uint256 opIndex, uint256 stackTopIndex, uint256 stackRead);

LibOpStackNP

Git Source

Functions

integrity

function integrity(IntegrityCheckStateNP memory state, Operand operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory state, Operand operand, Pointer stackTop) internal pure returns (Pointer);

Contents

• LibOpBitwiseAndNP
• LibOpBitwiseOrNP
• LibOpCtPopNP
• LibOpDecodeBitsNP
• LibOpEncodeBitsNP
• LibOpShiftBitsLeftNP
• LibOpShiftBitsRightNP

LibOpBitwiseAndNP

Git Source

Opcode for computing bitwise AND from the top two items on the stack.

Functions

integrity

The operand does nothing. Always 2 inputs and 1 output.

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

Bitwise AND the top two items on the stack.

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Reference implementation for bitwise AND.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory);

LibOpBitwiseOrNP

Git Source

Opcode for computing bitwise OR from the top two items on the stack.

Functions

integrity

The operand does nothing. Always 2 inputs and 1 output.

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

Bitwise OR the top two items on the stack.

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Reference implementation for bitwise OR.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory);

LibOpCtPopNP

Git Source

An opcode that counts the number of bits set in a word. This is called ctpop because that's the name of this kind of thing elsewhere, but the more common name is "population count" or "Hamming weight". The word in the standard ops lib is called bitwise-count-ones, which follows the Rust naming convention. There is no evm opcode for this, so we have to implement it ourselves.

Functions

integrity

ctpop unconditionally takes one value and returns one value.

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

Output is the number of bits set to one in the input. Thin wrapper around LibCtPop.ctpop.

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

The reference implementation of ctpop.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory);

LibOpDecodeBitsNP

Git Source

Opcode for decoding binary data from a 256 bit value that was encoded with LibOpEncodeBitsNP.

Functions

integrity

Decode takes a single value and returns the decoded value.

function integrity(IntegrityCheckStateNP memory state, Operand operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory, Operand operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpEncodeBitsNP

Git Source

Opcode for encoding binary data into a 256 bit value.

Functions

integrity

Encode takes two values and returns one value. The first value is the source, the second value is the target.

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory, Operand operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpShiftBitsLeftNP

Git Source

Opcode for shifting bits left. The shift amount is taken from the operand so it is compile time constant.

Functions

integrity

Shift bits left by the amount specified in the operand.

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

Shift bits left by the amount specified in the operand.

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Reference implementation for shifting bits left.

function referenceFn(InterpreterStateNP memory, Operand operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory);

LibOpShiftBitsRightNP

Git Source

Opcode for shifting bits right. The shift amount is taken from the operand so it is compile time constant.

Functions

integrity

Shift bits right by the amount specified in the operand.

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

Shift bits right by the amount specified in the operand.

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Reference implementation for shifting bits right.

function referenceFn(InterpreterStateNP memory, Operand operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory);

Contents

• CallOutputsExceedSource
• LibOpCallNP

CallOutputsExceedSource

Git Source

Thrown when the outputs requested by the operand exceed the outputs available from the source.

error CallOutputsExceedSource(uint256 sourceOutputs, uint256 outputs);

Parameters

LibOpCallNP

Git Source

Contains the call operation. This allows sources to be treated in a function-like manner. Primarily intended as a way for expression authors to create reusable logic inline with their expression, in a way that mimics how words and stack consumption works at the Solidity level. Similarities between call and a traditional function:

• The source is called with a set of 0+ inputs.
• The source returns a set of 0+ outputs.
• The source has a fixed number of inputs and outputs.
• When the source executes it has its own stack/scope.
• Sources use lexical scoping rules for named LHS items.
• The source can be called from multiple places.
• The source can call other sources.
• The source is stateless across calls (although it can use words like get/set to read/write external state).
• The caller and callee have to agree on the number of inputs (but not outputs, see below).
• Generally speaking, the behaviour of a source can be reasoned about without needing to know the context in which it is called. Which is the basic requirement for reusability. Differences between call and a traditional function:
• The caller defines the number of outputs to be returned, NOT the callee. This is because the caller is responsible for allocating space on the stack for the outputs, and the callee is responsible for providing the outputs. The only limitation is that the caller cannot request more outputs than the callee has available. This means that two calls to the same source can return different numbers of outputs in different contexts.
• The inputs to a source are considered to be the top of the callee's stack from the perspective of the caller. This means that the inputs are eligible to be read as outputs, if the caller chooses to do so.
• The sources are not named, they are identified by their index in the bytecode. Tooling can provide sugar over this but the underlying representation is just an index.
• Sources are not "first class" like functions often are, i.e. they cannot be passed as arguments to other sources or otherwise be treated as values.
• Recursion is not supported. This is because currently there is no laziness in the interpreter, so a recursive call would result in an infinite loop unconditionally (even when wrapped in an if). This may change in the future.
• The memory allocation for a source must be known at compile time.
• There's no way to return early from a source. The order of inputs and outputs is designed so that the visual representation of a source call matches the visual representation of a function call. This requires some reversals of order "under the hood" while copying data around but it makes the behaviour of call more intuitive. Illustrative example:

* Final result */
* a = 2 */
* b = 9 */
a b: call<1 2>(10 5); ten five:, a b: int-div(ten five) 9;

Functions

integrity

function integrity(IntegrityCheckStateNP memory state, Operand operand) internal pure returns (uint256, uint256);

run

The call word is conceptually very simple. It takes a source index, a number of outputs, and a number of inputs. It then runs the standard eval loop for the source, with a starting stack pointer above the inputs, and then copies the outputs to the calling stack.

function run(InterpreterStateNP memory state, Operand operand, Pointer stackTop) internal view returns (Pointer);

Contents

• LibOpContextNP

LibOpContextNP

Git Source

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory state, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory state, Operand operand, uint256[] memory)
    internal
    pure
    returns (uint256[] memory outputs);

Contents

• LibOpHashNP

LibOpHashNP

Git Source

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

Contents

• LibOpERC20AllowanceNP
• LibOpERC20BalanceOfNP
• LibOpERC20TotalSupplyNP

LibOpERC20AllowanceNP

Git Source

Opcode for getting the current erc20 allowance of an account.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal view returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    view
    returns (uint256[] memory);

LibOpERC20BalanceOfNP

Git Source

Opcode for getting the current erc20 balance of an account.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal view returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    view
    returns (uint256[] memory);

LibOpERC20TotalSupplyNP

Git Source

Opcode for ERC20 totalSupply.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal view returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    view
    returns (uint256[] memory);

Contents

• LibOpERC5313OwnerNP

LibOpERC5313OwnerNP

Git Source

Opcode for ERC5313 owner.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal view returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    view
    returns (uint256[] memory);

Contents

• LibOpERC721BalanceOfNP
• LibOpERC721OwnerOfNP

LibOpERC721BalanceOfNP

Git Source

Opcode for getting the current erc721 balance of an account.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal view returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    view
    returns (uint256[] memory);

LibOpERC721OwnerOfNP

Git Source

Opcode for getting the current owner of an erc721 token.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal view returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    view
    returns (uint256[] memory);

Contents

• LibOpBlockNumberNP
• LibOpChainIdNP
• LibOpMaxUint256NP
• LibOpTimestampNP

LibOpBlockNumberNP

Git Source

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal view returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory) internal view returns (uint256[] memory);

LibOpChainIdNP

Git Source

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal view returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory) internal view returns (uint256[] memory);

LibOpMaxUint256NP

Git Source

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory) internal pure returns (uint256[] memory);

LibOpTimestampNP

Git Source

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal view returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory) internal view returns (uint256[] memory);

Contents

• LibOpAnyNP
• NoConditionsMet
• LibOpConditionsNP
• EnsureFailed
• LibOpEnsureNP
• LibOpEqualToNP
• LibOpEveryNP
• LibOpGreaterThanNP
• LibOpGreaterThanOrEqualToNP
• LibOpIfNP
• LibOpIsZeroNP
• LibOpLessThanNP
• LibOpLessThanOrEqualToNP

LibOpAnyNP

Git Source

Opcode to return the first nonzero item on the stack up to the inputs limit.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

ANY ANY is the first nonzero item, else 0.

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of ANY for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

NoConditionsMet

Git Source

Thrown if no nonzero condition is found.

error NoConditionsMet(uint256 condCode);

Parameters

LibOpConditionsNP

Git Source

Opcode to return the first nonzero item on the stack up to the inputs limit.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

conditions Pairwise list of conditions and values. The first nonzero condition evaluated puts its corresponding value on the stack. conditions is eagerly evaluated. If no condition is nonzero, the expression will revert. The number of inputs must be even. The number of outputs is 1. If an author wants to provide some default value, they can set the last condition to some nonzero constant value such as 1.

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of condition for testing.

function referenceFn(InterpreterStateNP memory, Operand operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

EnsureFailed

Git Source

Thrown if a zero condition is found.

error EnsureFailed(uint256 ensureCode, uint256 errorIndex);

Parameters

LibOpEnsureNP

Git Source

Opcode to revert if any condition is zero.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

ensure List of conditions. If any condition is zero, the expression will revert. All conditions are eagerly evaluated and there are no outputs.

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of ensure for testing.

function referenceFn(InterpreterStateNP memory, Operand operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpEqualToNP

Git Source

Opcode to return 1 if the first item on the stack is equal to the second item on the stack, else 0.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

EQ EQ is 1 if the first item is equal to the second item, else 0.

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of EQ for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpEveryNP

Git Source

Opcode to return the last item out of N items if they are all true, else 0.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

EVERY is the last nonzero item, else 0.

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of EVERY for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpGreaterThanNP

Git Source

Opcode to return 1 if the first item on the stack is greater than the second item on the stack, else 0.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

GT GT is 1 if the first item is greater than the second item, else 0.

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of GT for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpGreaterThanOrEqualToNP

Git Source

Opcode to return 1 if the first item on the stack is greater than or equal to the second item on the stack, else 0.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

GTE GTE is 1 if the first item is greater than or equal to the second item, else 0.

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of GTE for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpIfNP

Git Source

Opcode to choose between two values based on a condition. If is eager, meaning both values are evaluated before the condition is checked.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

IF IF is a conditional. If the first item on the stack is nonero, the second item is returned, else the third item is returned.

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of IF for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpIsZeroNP

Git Source

Opcode to return 1 if the top item on the stack is zero, else 0.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

ISZERO ISZERO is 1 if the top item is zero, else 0.

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of ISZERO for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpLessThanNP

Git Source

Opcode to return 1 if the first item on the stack is less than the second item on the stack, else 0.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

LT LT is 1 if the first item is less than the second item, else 0.

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of LT for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpLessThanOrEqualToNP

Git Source

Opcode to return 1 if the first item on the stack is less than or equal to the second item on the stack, else 0.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

LTE LTE is 1 if the first item is less than or equal to the second item, else 0.

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of LTE for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

Contents

• decimal18
• int

Contents

• LibOpDecimal18DivNP
• LibOpDecimal18MulNP
• LibOpDecimal18PowUNP
• LibOpDecimal18Scale18DynamicNP
• LibOpDecimal18Scale18NP
• LibOpDecimal18ScaleNNP

LibOpDecimal18DivNP

Git Source

Used for reference implementation so that we have two independent upstreams to compare against.

Opcode to div N 18 decimal fixed point values. Errors on overflow.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

decimal18-div 18 decimal fixed point division with implied overflow checks from PRB Math.

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of division for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpDecimal18MulNP

Git Source

Used for reference implementation so that we have two independent upstreams to compare against.

Opcode to mul N 18 decimal fixed point values. Errors on overflow.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

decimal18-mul 18 decimal fixed point multiplication with implied overflow checks from PRB Math.

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of multiplication for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpDecimal18PowUNP

Git Source

Opcode to pow N 18 decimal fixed point values to a uint256 power.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

decimal18-pow-u 18 decimal fixed point exponentiation with implied overflow checks from PRB Math.

function run(InterpreterStateNP memory, Operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of multiplication for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory);

LibOpDecimal18Scale18DynamicNP

Git Source

Opcode for scaling a number to 18 decimal fixed point based on runtime scale input.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

decimal18-scale18-dynamic 18 decimal fixed point scaling from runtime value.

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory, Operand operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpDecimal18Scale18NP

Git Source

Opcode for scaling a number to 18 decimal fixed point.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

decimal18-scale18 18 decimal fixed point scaling.

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory, Operand operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpDecimal18ScaleNNP

Git Source

Opcode for scaling a decimal18 number to some other scale N.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

decimal18-scale-n Scale from 18 decimal to n decimal.

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory, Operand operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

Contents

• LibOpIntAddNP
• LibOpIntDivNP
• LibOpIntExpNP
• LibOpIntMaxNP
• LibOpIntMinNP
• LibOpIntModNP
• LibOpIntMulNP
• LibOpIntSubNP

LibOpIntAddNP

Git Source

Opcode to add N integers. Errors on overflow.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

int-add Addition with implied overflow checks from the Solidity 0.8.x compiler.

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of addition for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpIntDivNP

Git Source

Opcode to divide N integers. Errors on divide by zero. Truncates towards zero.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

int-div Division with implied checks from the Solidity 0.8.x compiler.

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of division for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpIntExpNP

Git Source

Opcode to raise x successively to N integers. Errors on overflow.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

int-exp Exponentiation with implied overflow checks from the Solidity 0.8.x compiler.

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of exponentiation for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpIntMaxNP

Git Source

Opcode to find the max from N integers.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

int-max Finds the maximum value from N integers.

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of maximum for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpIntMinNP

Git Source

Opcode to find the min from N integers.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

int-min Finds the minimum value from N integers.

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of minimum for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpIntModNP

Git Source

Opcode to modulo N integers. Errors on modulo by zero.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

int-mod Modulo with implied checks from the Solidity 0.8.x compiler.

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of modulo for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpIntMulNP

Git Source

Opcode to mul N integers. Errors on overflow.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

int-mul Multiplication with implied overflow checks from the Solidity 0.8.x compiler.

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of multiplication for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

LibOpIntSubNP

Git Source

Opcode to subtract N integers.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

int-sub Subtraction with implied overflow checks from the Solidity 0.8.x compiler.

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

Gas intensive reference implementation of subtraction for testing.

function referenceFn(InterpreterStateNP memory, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory outputs);

Contents

• LibOpGetNP
• LibOpSetNP

LibOpGetNP

Git Source

Opcode for reading from storage.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

Implements runtime behaviour of the get opcode. Attempts to lookup the key in the memory key/value store then falls back to the interpreter's storage interface as an external call. If the key is not found in either, the value will fallback to 0 as per default Solidity/EVM behaviour.

function run(InterpreterStateNP memory state, Operand, Pointer stackTop) internal view returns (Pointer);

Parameters

referenceFn

function referenceFn(InterpreterStateNP memory state, Operand, uint256[] memory inputs)
    internal
    view
    returns (uint256[] memory);

LibOpSetNP

Git Source

Opcode for recording k/v state changes to be set in storage.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory state, Operand, Pointer stackTop) internal pure returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory state, Operand, uint256[] memory inputs)
    internal
    pure
    returns (uint256[] memory);

Contents

• LibOpUniswapV2AmountIn
• LibOpUniswapV2AmountOut
• LibOpUniswapV2Quote

LibOpUniswapV2AmountIn

Git Source

Opcode to calculate the amount in for a Uniswap V2 pair.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal view returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory, Operand operand, uint256[] memory inputs)
    internal
    view
    returns (uint256[] memory outputs);

LibOpUniswapV2AmountOut

Git Source

Opcode to calculate the amount out for a Uniswap V2 pair.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal view returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory, Operand operand, uint256[] memory inputs)
    internal
    view
    returns (uint256[] memory outputs);

LibOpUniswapV2Quote

Git Source

Opcode to calculate the quote for a Uniswap V2 pair.

Functions

integrity

function integrity(IntegrityCheckStateNP memory, Operand operand) internal pure returns (uint256, uint256);

run

function run(InterpreterStateNP memory, Operand operand, Pointer stackTop) internal view returns (Pointer);

referenceFn

function referenceFn(InterpreterStateNP memory, Operand operand, uint256[] memory inputs)
    internal
    view
    returns (uint256[] memory outputs);

LibAllStandardOpsNP

Git Source

Every opcode available from the core repository laid out as a single array to easily build function pointers for IInterpreterV2.

Functions

authoringMetaV2

function authoringMetaV2() internal pure returns (bytes memory);

literalParserFunctionPointers

function literalParserFunctionPointers() internal pure returns (bytes memory);

operandHandlerFunctionPointers

function operandHandlerFunctionPointers() internal pure returns (bytes memory);

integrityFunctionPointers

function integrityFunctionPointers() internal pure returns (bytes memory);

opcodeFunctionPointers

All function pointers for the standard opcodes. Intended to be used to build a IInterpreterV2 instance, specifically the functionPointers method can just be a thin wrapper around this function.

function opcodeFunctionPointers() internal pure returns (bytes memory);

Constants

Git Source

ALL_STANDARD_OPS_LENGTH

Number of ops currently provided by AllStandardOpsNP.

uint256 constant ALL_STANDARD_OPS_LENGTH = 58;

Contents

• LibParse
• LibParse constants
• LibParseCMask
• LibParseCMask constants
• LibParseError
• LibParseInterstitial
• LibParseLiteral
• LibParseLiteral constants
• DuplicateFingerprint
• WordIOFnPointerMismatch
• LibParseMeta
• LibParseMeta constants
• LibParseOperand
• LibParsePragma
• LibParsePragma constants
• LibParseStackName
• ParseStackTracker
• LibParseStackTracker
• ParseState
• LibParseState
• LibParseState constants
• LibSubParse

LibParse

Git Source

Functions

parseWord

Parses a word that matches a tail mask between cursor and end. The caller has several responsibilities while safely using this word.

• The caller MUST ensure that the word is not zero length. I.e. end - cursor > 0.
• The caller MUST ensure the head of the word (the first character) is valid according to some head mask. Generally it is expected that the valid chars for a head and tail may be different. This function will extract every other character from the word, starting with the second character, and check that it is valid according to the tail mask. If any invalid characters are found, the parsing will stop looping as it is assumed the remaining data is valid as something else, just not a word.

function parseWord(uint256 cursor, uint256 end, uint256 mask) internal pure returns (uint256, bytes32);

skipMask

Skip an unlimited number of chars until we find one that is not in the mask.

function skipMask(uint256 cursor, uint256 end, uint256 mask) internal pure returns (uint256);

parseLHS

function parseLHS(ParseState memory state, uint256 cursor, uint256 end) internal pure returns (uint256);

parseRHS

function parseRHS(ParseState memory state, uint256 cursor, uint256 end) internal pure returns (uint256);

parse

function parse(ParseState memory state) internal pure returns (bytes memory bytecode, uint256[] memory);

Constants

Git Source

NOT_LOW_16_BIT_MASK

uint256 constant NOT_LOW_16_BIT_MASK = ~uint256(0xFFFF);

ACTIVE_SOURCE_MASK

uint256 constant ACTIVE_SOURCE_MASK = NOT_LOW_16_BIT_MASK;

SUB_PARSER_BYTECODE_HEADER_SIZE

uint256 constant SUB_PARSER_BYTECODE_HEADER_SIZE = 5;

LibParseCMask

Git Source

Workaround for https://github.com/foundry-rs/foundry/issues/6572

Constants

Git Source

CMASK_NULL

ASCII null

uint128 constant CMASK_NULL = uint128(1) << uint128(uint8(bytes1("\x00")));

CMASK_START_OF_HEADING

ASCII start of heading

uint128 constant CMASK_START_OF_HEADING = uint128(1) << uint128(uint8(bytes1("\x01")));

CMASK_START_OF_TEXT

ASCII start of text

uint128 constant CMASK_START_OF_TEXT = uint128(1) << uint128(uint8(bytes1("\x02")));

CMASK_END_OF_TEXT

ASCII end of text

uint128 constant CMASK_END_OF_TEXT = uint128(1) << uint128(uint8(bytes1("\x03")));

CMASK_END_OF_TRANSMISSION

ASCII end of transmission

uint128 constant CMASK_END_OF_TRANSMISSION = uint128(1) << uint128(uint8(bytes1("\x04")));

CMASK_ENQUIRY

ASCII enquiry

uint128 constant CMASK_ENQUIRY = uint128(1) << uint128(uint8(bytes1("\x05")));

CMASK_ACKNOWLEDGE

ASCII acknowledge

uint128 constant CMASK_ACKNOWLEDGE = uint128(1) << uint128(uint8(bytes1("\x06")));

CMASK_BELL

ASCII bell

uint128 constant CMASK_BELL = uint128(1) << uint128(uint8(bytes1("\x07")));

CMASK_BACKSPACE

ASCII backspace

uint128 constant CMASK_BACKSPACE = uint128(1) << uint128(uint8(bytes1("\x08")));

CMASK_HORIZONTAL_TAB

ASCII horizontal tab

uint128 constant CMASK_HORIZONTAL_TAB = uint128(1) << uint128(uint8(bytes1("\t")));

CMASK_LINE_FEED

ASCII line feed

uint128 constant CMASK_LINE_FEED = uint128(1) << uint128(uint8(bytes1("\n")));

CMASK_VERTICAL_TAB

ASCII vertical tab

uint128 constant CMASK_VERTICAL_TAB = uint128(1) << uint128(uint8(bytes1("\x0B")));

CMASK_FORM_FEED

ASCII form feed

uint128 constant CMASK_FORM_FEED = uint128(1) << uint128(uint8(bytes1("\x0C")));

CMASK_CARRIAGE_RETURN

ASCII carriage return

uint128 constant CMASK_CARRIAGE_RETURN = uint128(1) << uint128(uint8(bytes1("\r")));

CMASK_SHIFT_OUT

ASCII shift out

uint128 constant CMASK_SHIFT_OUT = uint128(1) << uint128(uint8(bytes1("\x0E")));

CMASK_SHIFT_IN

ASCII shift in

uint128 constant CMASK_SHIFT_IN = uint128(1) << uint128(uint8(bytes1("\x0F")));

CMASK_DATA_LINK_ESCAPE

ASCII data link escape

uint128 constant CMASK_DATA_LINK_ESCAPE = uint128(1) << uint128(uint8(bytes1("\x10")));

CMASK_DEVICE_CONTROL_1

ASCII device control 1

uint128 constant CMASK_DEVICE_CONTROL_1 = uint128(1) << uint128(uint8(bytes1("\x11")));

CMASK_DEVICE_CONTROL_2

ASCII device control 2

uint128 constant CMASK_DEVICE_CONTROL_2 = uint128(1) << uint128(uint8(bytes1("\x12")));

CMASK_DEVICE_CONTROL_3

ASCII device control 3

uint128 constant CMASK_DEVICE_CONTROL_3 = uint128(1) << uint128(uint8(bytes1("\x13")));

CMASK_DEVICE_CONTROL_4

ASCII device control 4

uint128 constant CMASK_DEVICE_CONTROL_4 = uint128(1) << uint128(uint8(bytes1("\x14")));

CMASK_NEGATIVE_ACKNOWLEDGE

ASCII negative acknowledge

uint128 constant CMASK_NEGATIVE_ACKNOWLEDGE = uint128(1) << uint128(uint8(bytes1("\x15")));

CMASK_SYNCHRONOUS_IDLE

ASCII synchronous idle

uint128 constant CMASK_SYNCHRONOUS_IDLE = uint128(1) << uint128(uint8(bytes1("\x16")));

CMASK_END_OF_TRANSMISSION_BLOCK

ASCII end of transmission block

uint128 constant CMASK_END_OF_TRANSMISSION_BLOCK = uint128(1) << uint128(uint8(bytes1("\x17")));

CMASK_CANCEL

ASCII cancel

uint128 constant CMASK_CANCEL = uint128(1) << uint128(uint8(bytes1("\x18")));

CMASK_END_OF_MEDIUM

ASCII end of medium

uint128 constant CMASK_END_OF_MEDIUM = uint128(1) << uint128(uint8(bytes1("\x19")));

CMASK_SUBSTITUTE

ASCII substitute

uint128 constant CMASK_SUBSTITUTE = uint128(1) << uint128(uint8(bytes1("\x1A")));

CMASK_ESCAPE

ASCII escape

uint128 constant CMASK_ESCAPE = uint128(1) << uint128(uint8(bytes1("\x1B")));

CMASK_FILE_SEPARATOR

ASCII file separator

uint128 constant CMASK_FILE_SEPARATOR = uint128(1) << uint128(uint8(bytes1("\x1C")));

CMASK_GROUP_SEPARATOR

ASCII group separator

uint128 constant CMASK_GROUP_SEPARATOR = uint128(1) << uint128(uint8(bytes1("\x1D")));

CMASK_RECORD_SEPARATOR

ASCII record separator

uint128 constant CMASK_RECORD_SEPARATOR = uint128(1) << uint128(uint8(bytes1("\x1E")));

CMASK_UNIT_SEPARATOR

ASCII unit separator

uint128 constant CMASK_UNIT_SEPARATOR = uint128(1) << uint128(uint8(bytes1("\x1F")));

CMASK_SPACE

ASCII space

uint128 constant CMASK_SPACE = uint128(1) << uint128(uint8(bytes1(" ")));

CMASK_EXCLAMATION_MARK

ASCII !

uint128 constant CMASK_EXCLAMATION_MARK = uint128(1) << uint128(uint8(bytes1("!")));

CMASK_QUOTATION_MARK

ASCII "

uint128 constant CMASK_QUOTATION_MARK = uint128(1) << uint128(uint8(bytes1("\"")));

CMASK_NUMBER_SIGN

ASCII #

uint128 constant CMASK_NUMBER_SIGN = uint128(1) << uint128(uint8(bytes1("#")));

CMASK_DOLLAR_SIGN

ASCII $

uint128 constant CMASK_DOLLAR_SIGN = uint128(1) << uint128(uint8(bytes1("$")));

CMASK_PERCENT_SIGN

ASCII %

uint128 constant CMASK_PERCENT_SIGN = uint128(1) << uint128(uint8(bytes1("%")));

CMASK_AMPERSAND

ASCII &

uint128 constant CMASK_AMPERSAND = uint128(1) << uint128(uint8(bytes1("&")));

CMASK_APOSTROPHE

ASCII '

uint128 constant CMASK_APOSTROPHE = uint128(1) << uint128(uint8(bytes1("'")));

CMASK_LEFT_PAREN

ASCII (

uint128 constant CMASK_LEFT_PAREN = uint128(1) << uint128(uint8(bytes1("(")));

CMASK_RIGHT_PAREN

ASCII )

uint128 constant CMASK_RIGHT_PAREN = uint128(1) << uint128(uint8(bytes1(")")));

CMASK_ASTERISK

*ASCII **

uint128 constant CMASK_ASTERISK = uint128(1) << uint128(uint8(bytes1("*")));

CMASK_PLUS_SIGN

ASCII +

uint128 constant CMASK_PLUS_SIGN = uint128(1) << uint128(uint8(bytes1("+")));

CMASK_COMMA

ASCII ,

uint128 constant CMASK_COMMA = uint128(1) << uint128(uint8(bytes1(",")));

CMASK_DASH

ASCII -

uint128 constant CMASK_DASH = uint128(1) << uint128(uint8(bytes1("-")));

CMASK_FULL_STOP

ASCII .

uint128 constant CMASK_FULL_STOP = uint128(1) << uint128(uint8(bytes1(".")));

CMASK_SLASH

ASCII /

uint128 constant CMASK_SLASH = uint128(1) << uint128(uint8(bytes1("/")));

CMASK_ZERO

ASCII 0

uint128 constant CMASK_ZERO = uint128(1) << uint128(uint8(bytes1("0")));

CMASK_ONE

ASCII 1

uint128 constant CMASK_ONE = uint128(1) << uint128(uint8(bytes1("1")));

CMASK_TWO

ASCII 2

uint128 constant CMASK_TWO = uint128(1) << uint128(uint8(bytes1("2")));

CMASK_THREE

ASCII 3

uint128 constant CMASK_THREE = uint128(1) << uint128(uint8(bytes1("3")));

CMASK_FOUR

ASCII 4

uint128 constant CMASK_FOUR = uint128(1) << uint128(uint8(bytes1("4")));

CMASK_FIVE

ASCII 5

uint128 constant CMASK_FIVE = uint128(1) << uint128(uint8(bytes1("5")));

CMASK_SIX

ASCII 6

uint128 constant CMASK_SIX = uint128(1) << uint128(uint8(bytes1("6")));

CMASK_SEVEN

ASCII 7

uint128 constant CMASK_SEVEN = uint128(1) << uint128(uint8(bytes1("7")));

CMASK_EIGHT

ASCII 8

uint128 constant CMASK_EIGHT = uint128(1) << uint128(uint8(bytes1("8")));

CMASK_NINE

ASCII 9

uint128 constant CMASK_NINE = uint128(1) << uint128(uint8(bytes1("9")));

CMASK_COLON

ASCII :

uint128 constant CMASK_COLON = uint128(1) << uint128(uint8(bytes1(":")));

CMASK_SEMICOLON

ASCII ;

uint128 constant CMASK_SEMICOLON = uint128(1) << uint128(uint8(bytes1(";")));

CMASK_LESS_THAN_SIGN

ASCII <

uint128 constant CMASK_LESS_THAN_SIGN = uint128(1) << uint128(uint8(bytes1("<")));

CMASK_EQUALS_SIGN

ASCII =

uint128 constant CMASK_EQUALS_SIGN = uint128(1) << uint128(uint8(bytes1("=")));

CMASK_GREATER_THAN_SIGN

ASCII >

uint128 constant CMASK_GREATER_THAN_SIGN = uint128(1) << uint128(uint8(bytes1(">")));

CMASK_QUESTION_MARK

ASCII ?

uint128 constant CMASK_QUESTION_MARK = uint128(1) << uint128(uint8(bytes1("?")));

CMASK_AT_SIGN

ASCII @

uint128 constant CMASK_AT_SIGN = uint128(1) << uint128(uint8(bytes1("@")));

CMASK_UPPER_A

ASCII A

uint128 constant CMASK_UPPER_A = uint128(1) << uint128(uint8(bytes1("A")));

CMASK_UPPER_B

ASCII B

uint128 constant CMASK_UPPER_B = uint128(1) << uint128(uint8(bytes1("B")));

CMASK_UPPER_C

ASCII C

uint128 constant CMASK_UPPER_C = uint128(1) << uint128(uint8(bytes1("C")));

CMASK_UPPER_D

ASCII D

uint128 constant CMASK_UPPER_D = uint128(1) << uint128(uint8(bytes1("D")));

CMASK_UPPER_E

ASCII E

uint128 constant CMASK_UPPER_E = uint128(1) << uint128(uint8(bytes1("E")));

CMASK_UPPER_F

ASCII F

uint128 constant CMASK_UPPER_F = uint128(1) << uint128(uint8(bytes1("F")));

CMASK_UPPER_G

ASCII G

uint128 constant CMASK_UPPER_G = uint128(1) << uint128(uint8(bytes1("G")));

CMASK_UPPER_H

ASCII H

uint128 constant CMASK_UPPER_H = uint128(1) << uint128(uint8(bytes1("H")));

CMASK_UPPER_I

ASCII I

uint128 constant CMASK_UPPER_I = uint128(1) << uint128(uint8(bytes1("I")));

CMASK_UPPER_J

ASCII J

uint128 constant CMASK_UPPER_J = uint128(1) << uint128(uint8(bytes1("J")));

CMASK_UPPER_K

ASCII K

uint128 constant CMASK_UPPER_K = uint128(1) << uint128(uint8(bytes1("K")));

CMASK_UPPER_L

ASCII L

uint128 constant CMASK_UPPER_L = uint128(1) << uint128(uint8(bytes1("L")));

CMASK_UPPER_M

ASCII M

uint128 constant CMASK_UPPER_M = uint128(1) << uint128(uint8(bytes1("M")));

CMASK_UPPER_N

ASCII N

uint128 constant CMASK_UPPER_N = uint128(1) << uint128(uint8(bytes1("N")));

CMASK_UPPER_O

ASCII O

uint128 constant CMASK_UPPER_O = uint128(1) << uint128(uint8(bytes1("O")));

CMASK_UPPER_P

ASCII P

uint128 constant CMASK_UPPER_P = uint128(1) << uint128(uint8(bytes1("P")));

CMASK_UPPER_Q

ASCII Q

uint128 constant CMASK_UPPER_Q = uint128(1) << uint128(uint8(bytes1("Q")));

CMASK_UPPER_R

ASCII R

uint128 constant CMASK_UPPER_R = uint128(1) << uint128(uint8(bytes1("R")));

CMASK_UPPER_S

ASCII S

uint128 constant CMASK_UPPER_S = uint128(1) << uint128(uint8(bytes1("S")));

CMASK_UPPER_T

ASCII T

uint128 constant CMASK_UPPER_T = uint128(1) << uint128(uint8(bytes1("T")));

CMASK_UPPER_U

ASCII U

uint128 constant CMASK_UPPER_U = uint128(1) << uint128(uint8(bytes1("U")));

CMASK_UPPER_V

ASCII V

uint128 constant CMASK_UPPER_V = uint128(1) << uint128(uint8(bytes1("V")));

CMASK_UPPER_W

ASCII W

uint128 constant CMASK_UPPER_W = uint128(1) << uint128(uint8(bytes1("W")));

CMASK_UPPER_X

ASCII X

uint128 constant CMASK_UPPER_X = uint128(1) << uint128(uint8(bytes1("X")));

CMASK_UPPER_Y

ASCII Y

uint128 constant CMASK_UPPER_Y = uint128(1) << uint128(uint8(bytes1("Y")));

CMASK_UPPER_Z

ASCII Z

uint128 constant CMASK_UPPER_Z = uint128(1) << uint128(uint8(bytes1("Z")));

CMASK_LEFT_SQUARE_BRACKET

ASCII [

uint128 constant CMASK_LEFT_SQUARE_BRACKET = uint128(1) << uint128(uint8(bytes1("[")));

CMASK_BACKSLASH

*ASCII *

uint128 constant CMASK_BACKSLASH = uint128(1) << uint128(uint8(bytes1("\\")));

CMASK_RIGHT_SQUARE_BRACKET

ASCII ]

uint128 constant CMASK_RIGHT_SQUARE_BRACKET = uint128(1) << uint128(uint8(bytes1("]")));

CMASK_CIRCUMFLEX_ACCENT

ASCII ^

uint128 constant CMASK_CIRCUMFLEX_ACCENT = uint128(1) << uint128(uint8(bytes1("^")));

CMASK_UNDERSCORE

ASCII _

uint128 constant CMASK_UNDERSCORE = uint128(1) << uint128(uint8(bytes1("_")));

CMASK_GRAVE_ACCENT

ASCII `

uint128 constant CMASK_GRAVE_ACCENT = uint128(1) << uint128(uint8(bytes1("`")));

CMASK_LOWER_A

ASCII a

uint128 constant CMASK_LOWER_A = uint128(1) << uint128(uint8(bytes1("a")));

CMASK_LOWER_B

ASCII b

uint128 constant CMASK_LOWER_B = uint128(1) << uint128(uint8(bytes1("b")));

CMASK_LOWER_C

ASCII c

uint128 constant CMASK_LOWER_C = uint128(1) << uint128(uint8(bytes1("c")));

CMASK_LOWER_D

ASCII d

uint128 constant CMASK_LOWER_D = uint128(1) << uint128(uint8(bytes1("d")));

CMASK_LOWER_E

ASCII e

uint128 constant CMASK_LOWER_E = uint128(1) << uint128(uint8(bytes1("e")));

CMASK_LOWER_F

ASCII f

uint128 constant CMASK_LOWER_F = uint128(1) << uint128(uint8(bytes1("f")));

CMASK_LOWER_G

ASCII g

uint128 constant CMASK_LOWER_G = uint128(1) << uint128(uint8(bytes1("g")));

CMASK_LOWER_H

ASCII h

uint128 constant CMASK_LOWER_H = uint128(1) << uint128(uint8(bytes1("h")));

CMASK_LOWER_I

ASCII i

uint128 constant CMASK_LOWER_I = uint128(1) << uint128(uint8(bytes1("i")));

CMASK_LOWER_J

ASCII j

uint128 constant CMASK_LOWER_J = uint128(1) << uint128(uint8(bytes1("j")));

CMASK_LOWER_K

ASCII k

uint128 constant CMASK_LOWER_K = uint128(1) << uint128(uint8(bytes1("k")));

CMASK_LOWER_L

ASCII l

uint128 constant CMASK_LOWER_L = uint128(1) << uint128(uint8(bytes1("l")));

CMASK_LOWER_M

ASCII m

uint128 constant CMASK_LOWER_M = uint128(1) << uint128(uint8(bytes1("m")));

CMASK_LOWER_N

ASCII n

uint128 constant CMASK_LOWER_N = uint128(1) << uint128(uint8(bytes1("n")));

CMASK_LOWER_O

ASCII o

uint128 constant CMASK_LOWER_O = uint128(1) << uint128(uint8(bytes1("o")));

CMASK_LOWER_P

ASCII p

uint128 constant CMASK_LOWER_P = uint128(1) << uint128(uint8(bytes1("p")));

CMASK_LOWER_Q

ASCII q

uint128 constant CMASK_LOWER_Q = uint128(1) << uint128(uint8(bytes1("q")));

CMASK_LOWER_R

ASCII r

uint128 constant CMASK_LOWER_R = uint128(1) << uint128(uint8(bytes1("r")));

CMASK_LOWER_S

ASCII s

uint128 constant CMASK_LOWER_S = uint128(1) << uint128(uint8(bytes1("s")));

CMASK_LOWER_T

ASCII t

uint128 constant CMASK_LOWER_T = uint128(1) << uint128(uint8(bytes1("t")));

CMASK_LOWER_U

ASCII u

uint128 constant CMASK_LOWER_U = uint128(1) << uint128(uint8(bytes1("u")));

CMASK_LOWER_V

ASCII v

uint128 constant CMASK_LOWER_V = uint128(1) << uint128(uint8(bytes1("v")));

CMASK_LOWER_W

ASCII w

uint128 constant CMASK_LOWER_W = uint128(1) << uint128(uint8(bytes1("w")));

CMASK_LOWER_X

ASCII x

uint128 constant CMASK_LOWER_X = uint128(1) << uint128(uint8(bytes1("x")));

CMASK_LOWER_Y

ASCII y

uint128 constant CMASK_LOWER_Y = uint128(1) << uint128(uint8(bytes1("y")));

CMASK_LOWER_Z

ASCII z

uint128 constant CMASK_LOWER_Z = uint128(1) << uint128(uint8(bytes1("z")));

CMASK_LEFT_CURLY_BRACKET

ASCII {

uint128 constant CMASK_LEFT_CURLY_BRACKET = uint128(1) << uint128(uint8(bytes1("{")));

CMASK_VERTICAL_BAR

ASCII |

uint128 constant CMASK_VERTICAL_BAR = uint128(1) << uint128(uint8(bytes1("|")));

CMASK_RIGHT_CURLY_BRACKET

ASCII }

uint128 constant CMASK_RIGHT_CURLY_BRACKET = uint128(1) << uint128(uint8(bytes1("}")));

CMASK_TILDE

ASCII ~

uint128 constant CMASK_TILDE = uint128(1) << uint128(uint8(bytes1("~")));

CMASK_DELETE

ASCII delete

uint128 constant CMASK_DELETE = uint128(1) << uint128(uint8(bytes1("\x7F")));

CMASK_PRINTABLE

ASCII printable characters is everything 0x20 and above, except 0x7F

uint128 constant CMASK_PRINTABLE = ~(
    CMASK_NULL | CMASK_START_OF_HEADING | CMASK_START_OF_TEXT | CMASK_END_OF_TEXT | CMASK_END_OF_TRANSMISSION
        | CMASK_ENQUIRY | CMASK_ACKNOWLEDGE | CMASK_BELL | CMASK_BACKSPACE | CMASK_HORIZONTAL_TAB | CMASK_LINE_FEED
        | CMASK_VERTICAL_TAB | CMASK_FORM_FEED | CMASK_CARRIAGE_RETURN | CMASK_SHIFT_OUT | CMASK_SHIFT_IN
        | CMASK_DATA_LINK_ESCAPE | CMASK_DEVICE_CONTROL_1 | CMASK_DEVICE_CONTROL_2 | CMASK_DEVICE_CONTROL_3
        | CMASK_DEVICE_CONTROL_4 | CMASK_NEGATIVE_ACKNOWLEDGE | CMASK_SYNCHRONOUS_IDLE | CMASK_END_OF_TRANSMISSION_BLOCK
        | CMASK_CANCEL | CMASK_END_OF_MEDIUM | CMASK_SUBSTITUTE | CMASK_ESCAPE | CMASK_FILE_SEPARATOR
        | CMASK_GROUP_SEPARATOR | CMASK_RECORD_SEPARATOR | CMASK_UNIT_SEPARATOR | CMASK_DELETE
);

CMASK_NUMERIC_0_9

numeric 0-9

uint128 constant CMASK_NUMERIC_0_9 = CMASK_ZERO | CMASK_ONE | CMASK_TWO | CMASK_THREE | CMASK_FOUR | CMASK_FIVE
    | CMASK_SIX | CMASK_SEVEN | CMASK_EIGHT | CMASK_NINE;

CMASK_E_NOTATION

e notation eE

uint128 constant CMASK_E_NOTATION = CMASK_LOWER_E | CMASK_UPPER_E;

CMASK_LOWER_ALPHA_A_Z

lower alpha a-z

uint128 constant CMASK_LOWER_ALPHA_A_Z = CMASK_LOWER_A | CMASK_LOWER_B | CMASK_LOWER_C | CMASK_LOWER_D | CMASK_LOWER_E
    | CMASK_LOWER_F | CMASK_LOWER_G | CMASK_LOWER_H | CMASK_LOWER_I | CMASK_LOWER_J | CMASK_LOWER_K | CMASK_LOWER_L
    | CMASK_LOWER_M | CMASK_LOWER_N | CMASK_LOWER_O | CMASK_LOWER_P | CMASK_LOWER_Q | CMASK_LOWER_R | CMASK_LOWER_S
    | CMASK_LOWER_T | CMASK_LOWER_U | CMASK_LOWER_V | CMASK_LOWER_W | CMASK_LOWER_X | CMASK_LOWER_Y | CMASK_LOWER_Z;

CMASK_UPPER_ALPHA_A_Z

upper alpha A-Z

uint128 constant CMASK_UPPER_ALPHA_A_Z = CMASK_UPPER_A | CMASK_UPPER_B | CMASK_UPPER_C | CMASK_UPPER_D | CMASK_UPPER_E
    | CMASK_UPPER_F | CMASK_UPPER_G | CMASK_UPPER_H | CMASK_UPPER_I | CMASK_UPPER_J | CMASK_UPPER_K | CMASK_UPPER_L
    | CMASK_UPPER_M | CMASK_UPPER_N | CMASK_UPPER_O | CMASK_UPPER_P | CMASK_UPPER_Q | CMASK_UPPER_R | CMASK_UPPER_S
    | CMASK_UPPER_T | CMASK_UPPER_U | CMASK_UPPER_V | CMASK_UPPER_W | CMASK_UPPER_X | CMASK_UPPER_Y | CMASK_UPPER_Z;

CMASK_LOWER_ALPHA_A_F

lower alpha a-f (hex)

uint128 constant CMASK_LOWER_ALPHA_A_F =
    CMASK_LOWER_A | CMASK_LOWER_B | CMASK_LOWER_C | CMASK_LOWER_D | CMASK_LOWER_E | CMASK_LOWER_F;

CMASK_UPPER_ALPHA_A_F

upper alpha A-F (hex)

uint128 constant CMASK_UPPER_ALPHA_A_F =
    CMASK_UPPER_A | CMASK_UPPER_B | CMASK_UPPER_C | CMASK_UPPER_D | CMASK_UPPER_E | CMASK_UPPER_F;

CMASK_HEX

hex 0-9 a-f A-F

uint128 constant CMASK_HEX = CMASK_NUMERIC_0_9 | CMASK_LOWER_ALPHA_A_F | CMASK_UPPER_ALPHA_A_F;

CMASK_EOL

Rainlang end of line is ,

uint128 constant CMASK_EOL = CMASK_COMMA;

CMASK_LHS_RHS_DELIMITER

Rainlang LHS/RHS delimiter is :

uint128 constant CMASK_LHS_RHS_DELIMITER = CMASK_COLON;

CMASK_EOS

Rainlang end of source is ;

uint128 constant CMASK_EOS = CMASK_SEMICOLON;

CMASK_LHS_STACK_HEAD

Rainlang stack head is lower alpha and underscore a-z _

uint128 constant CMASK_LHS_STACK_HEAD = CMASK_LOWER_ALPHA_A_Z | CMASK_UNDERSCORE;

CMASK_IDENTIFIER_HEAD

Rainlang identifier head is lower alpha a-z

uint128 constant CMASK_IDENTIFIER_HEAD = CMASK_LOWER_ALPHA_A_Z;

CMASK_RHS_WORD_HEAD

uint128 constant CMASK_RHS_WORD_HEAD = CMASK_IDENTIFIER_HEAD;

CMASK_IDENTIFIER_TAIL

Rainlang stack/identifier tail is lower alphanumeric kebab a-z 0-9 -

uint128 constant CMASK_IDENTIFIER_TAIL = CMASK_IDENTIFIER_HEAD | CMASK_NUMERIC_0_9 | CMASK_DASH;

CMASK_LHS_STACK_TAIL

uint128 constant CMASK_LHS_STACK_TAIL = CMASK_IDENTIFIER_TAIL;

CMASK_RHS_WORD_TAIL

uint128 constant CMASK_RHS_WORD_TAIL = CMASK_IDENTIFIER_TAIL;

CMASK_OPERAND_START

Rainlang operand start is <

uint128 constant CMASK_OPERAND_START = CMASK_LESS_THAN_SIGN;

CMASK_OPERAND_END

Rainlang operand end is >

uint128 constant CMASK_OPERAND_END = CMASK_GREATER_THAN_SIGN;

CMASK_NOT_IDENTIFIER_TAIL

NOT lower alphanumeric kebab

uint128 constant CMASK_NOT_IDENTIFIER_TAIL = ~CMASK_IDENTIFIER_TAIL;

CMASK_WHITESPACE

Rainlang whitespace is \n \r \t space

uint128 constant CMASK_WHITESPACE = CMASK_LINE_FEED | CMASK_CARRIAGE_RETURN | CMASK_HORIZONTAL_TAB | CMASK_SPACE;

CMASK_LHS_STACK_DELIMITER

Rainlang stack item delimiter is whitespace

uint128 constant CMASK_LHS_STACK_DELIMITER = CMASK_WHITESPACE;

CMASK_NUMERIC_LITERAL_HEAD

Rainlang supports numeric literals as anything starting with 0-9

uint128 constant CMASK_NUMERIC_LITERAL_HEAD = CMASK_NUMERIC_0_9;

CMASK_STRING_LITERAL_HEAD

Rainlang supports string literals as anything starting with "

uint128 constant CMASK_STRING_LITERAL_HEAD = CMASK_QUOTATION_MARK;

CMASK_STRING_LITERAL_END

Rainlang string end is "

uint128 constant CMASK_STRING_LITERAL_END = CMASK_QUOTATION_MARK;

CMASK_STRING_LITERAL_TAIL

Rainlang string tail is any printable ASCII except " which ends it.

uint128 constant CMASK_STRING_LITERAL_TAIL = ~CMASK_STRING_LITERAL_END & CMASK_PRINTABLE;

CMASK_LITERAL_HEAD

Rainlang literal head

uint128 constant CMASK_LITERAL_HEAD = CMASK_NUMERIC_LITERAL_HEAD | CMASK_STRING_LITERAL_HEAD;

CMASK_COMMENT_HEAD

Rainlang comment head is /

uint128 constant CMASK_COMMENT_HEAD = CMASK_SLASH;

CMASK_INTERSTITIAL_HEAD

Rainlang interstitial head could be some whitespace or a comment head.

uint128 constant CMASK_INTERSTITIAL_HEAD = CMASK_WHITESPACE | CMASK_COMMENT_HEAD;

COMMENT_START_SEQUENCE

Rainlang comment starting sequence is /*

uint256 constant COMMENT_START_SEQUENCE = uint256(uint16(bytes2("/*")));

COMMENT_END_SEQUENCE

*Rainlang comment ending sequence is /

uint256 constant COMMENT_END_SEQUENCE = uint256(uint16(bytes2("*/")));

CMASK_COMMENT_END_SEQUENCE_END

*Rainlang comment end sequence end byte is / /

uint256 constant CMASK_COMMENT_END_SEQUENCE_END = COMMENT_END_SEQUENCE & 0xFF;

CMASK_LITERAL_HEX_DISPATCH

Rainlang literal hexadecimal dispatch is 0x We compare the head and dispatch together to avoid a second comparison. This is safe because the head is prefiltered to be 0-9 due to the numeric literal head, therefore the only possible match is 0x (not x0).

uint128 constant CMASK_LITERAL_HEX_DISPATCH = CMASK_ZERO | CMASK_LOWER_X;

CMASK_LITERAL_HEX_DISPATCH_START

We may want to match the exact start of a hex literal.

uint256 constant CMASK_LITERAL_HEX_DISPATCH_START = uint256(uint16(bytes2("0x")));

LibParseError

Git Source

Functions

parseErrorOffset

function parseErrorOffset(ParseState memory state, uint256 cursor) internal pure returns (uint256 offset);

LibParseInterstitial

Git Source

Functions

skipComment

The cursor currently points at the head of a comment. We need to skip over all data until we find the end of the comment. This MAY REVERT if the comment is malformed, e.g. if the comment doesn't start with /*.

function skipComment(ParseState memory state, uint256 cursor, uint256 end) internal pure returns (uint256);

Parameters

Returns

skipWhitespace

function skipWhitespace(ParseState memory state, uint256 cursor, uint256 end) internal pure returns (uint256);

parseInterstitial

function parseInterstitial(ParseState memory state, uint256 cursor, uint256 end) internal pure returns (uint256);

LibParseLiteral

Git Source

Functions

selectLiteralParserByIndex

function selectLiteralParserByIndex(ParseState memory state, uint256 index)
    internal
    pure
    returns (function(ParseState memory, uint256, uint256) pure returns (uint256));

boundLiteral

Find the bounds for some literal at the cursor. The caller is responsible for checking that the cursor is at the start of a literal and that the cursor is less than the end. As each literal type has a different format, this function returns the bounds for the literal and the type of the literal. The bounds are:

• innerStart: the start of the literal, e.g. after the 0x in 0x1234
• innerEnd: the end of the literal, e.g. after the 1234 in 0x1234
• outerEnd: the end of the literal including any suffixes, MAY be the same as innerEnd if there is no suffix. The outerStart is the cursor, so it is not returned.

function boundLiteral(ParseState memory state, uint256 cursor, uint256 end)
    internal
    pure
    returns (function(ParseState memory, uint256, uint256) pure returns (uint256), uint256, uint256, uint256);

Parameters

Returns