From b3afc7e97ea78e514609640f31737eef4e3ed357 Mon Sep 17 00:00:00 2001 From: Martin Holst Swende Date: Mon, 4 Nov 2024 11:57:10 +0100 Subject: [PATCH] core/vm/program: add warning --- core/vm/program/program.go | 5 +++++ core/vm/program/readme.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+) create mode 100644 core/vm/program/readme.md diff --git a/core/vm/program/program.go b/core/vm/program/program.go index e5b743dc5a..79c0c296d4 100644 --- a/core/vm/program/program.go +++ b/core/vm/program/program.go @@ -14,6 +14,11 @@ // You should have received a copy of the GNU Lesser General Public License // along with the goevmlab library. If not, see . +// package program is a utility to create EVM bytecode for testing, but _not_ for production. As such: +// +// - There are not package guarantees. We might iterate heavily on this package, and do backwards-incompatible changes without warning +// - There are no quality-guarantees. These utilities may produce evm-code that is non-functional. YMMV. +// - There are no stability-guarantees. The utility will `panic` if the inputs do not align / make sense. package program import ( diff --git a/core/vm/program/readme.md b/core/vm/program/readme.md new file mode 100644 index 0000000000..0e4a54d8f1 --- /dev/null +++ b/core/vm/program/readme.md @@ -0,0 +1,30 @@ +### What is this + +In many cases, we have a need to create somewhat nontrivial bytecode, for testing various +quirks related to state transition or evm execution. + +For example, we want to have a `CREATE2`- op create a contract, which is then invoked, and when invoked does a selfdestruct-to-self. + +It is overkill to go full solidity, but it is also a bit tricky do assemble this by concatenating bytes. + +This utility takes an approach from [goevmlab](https://github.com/holiman/goevmlab/) where it has been used for several years, +a go-lang utility to assemble evm bytecode. + +Using this utility, the case above can be expressed as: +```golang + // Some runtime code + runtime := program.New().Ops(vm.ADDRESS, vm.SELFDESTRUCT).Bytecode() + // A constructor returning the runtime code + initcode := program.New().ReturnData(runtime).Bytecode() + // A factory invoking the constructor + outer := program.New().Create2AndCall(initcode, nil).Bytecode() +``` + +### Warning + +This package is a utility for testing, _not_ for production. As such: + +- There are not package guarantees. We might iterate heavily on this package, and do backwards-incompatible changes without warning +- There are no quality-guarantees. These utilities may produce evm-code that is non-functional. YMMV. +- There are no stability-guarantees. The utility will `panic` if the inputs do not align / make sense. +