Rust x Ethereum Day 2023 at The Foundry SF

Matthias Seitz presents on "Foundry"

I wrote a bunch of code for Foundry and now Rev.

And I will talk a bit about some Foundry internals and how it works internally, how we interact with the EVM, how we get cheat codes working, how forking works under the hood briefly, and what are our next steps for Foundry.

So first of all, who has used Forge or Foundry or some other tools?

Yeah, so for those who don't know, Foundry is basically a collection of tools that you can use for developing solidity or solidity adjacent work.

You can use Anvil as a local Ethereum node that has a bunch of modifications that wouldn't be possible with something like Gaff or Ref.

Then we have Cast, which is basically just a collection of subcommands that help when you want to interact with Ethereum nodes or just to convert some ABI data input output function signatures something like that and our main motivation behind all of this was that we want to get to 100% solidity in your smart contracts repository.

So getting rid of everything else, just solidity, and support writing tests in solidity directly, and use Forge for running those tests.

You have 1 best trip that downloads the latest release and you can use our Forge GitHub action to run it in CI.

Just to give you a brief overview about the style history, because it's really nice.

We hit 6K a few weeks ago, but more important, we almost had 300 contributors.

We try to be as open-minded as possible when they are triaging new issues, feature requests and help those to land their first PR in Foundry.

But this talk is not necessarily a talk how to use Foundry because there are way better resources out there, there's an entire course by Patrick Collins that is multiple hours long and is for free available on GitHub, or you can have a look at our foundry book which covers everything we have in there, references to other useful documentation, templates, things like that.

I will mostly focus on some force internals, but I want to not entirely exclude some cast features.

For example, there's cast run, which takes an Ethereum transaction hash and then replaces that transaction locally.

So it first basically forks the network at the block that this transaction was mined in, then executes all the previous transactions locally, so you get to the states the transaction used when it was first included in the node, and then it re-executes this transaction and displays all the traces.

So you can see all the calls, all the arguments and the entire trace call, which is very useful when you need to debug a transaction or just want to get a better understanding what is happening in there.

And this basically works with standard RPC provider or URL to a node that supports the regular ETH RPC methods.

Another cool thing with Anvil is that you can use it programmatically, so you can use it as a library and we see a lot of folks using that for simulations specifically.

Getting it to work is super easy, you have basically just 1 entry point, you configure your node like if you want to fork some network, chain ID, whatever, and then you just fire it and you get API interface and basically a node handle that ensures that the node is not dropped.

This way you can bypass the entire RPC layer directly and speak to the node directly without going through RPCs.

If you run simulations for example, you want to eave call, you use the API object directly and you don't need to go through RPC at all.

So I think this is pretty cool, but I wanna focus on what happens when you run Forge test under the hood.

So on the left side, you'll see the template test contract that you get when you initialize a Forge repository or Forge project.

And you see there is some test contract that inherits from the Forge STD test and you have a bunch of test functions where this is where you write your tests and you have a bunch of assert functions that you can then use to test your contract calls.

And what you see when you run Forge test is that first everything is compiled, then we run all the test functions and they either pass or fail.

If you look closely at the test fuzz function, then you see that This function takes a bunch of arguments, and those are Fuzz by default.

These are Fuzz functions where Forge internally generates a bunch of random arguments, and then calls this function multiple times.

You can have multiple arguments and yeah, go wild with the fast logic here.

But what happens internally when you call Forge test is that we first prepare the solc call that eventually is invoked.

And this includes loading all the forge CLI arguments, like if you have a filter for specific functions that you want to run or contracts, then this is handled here.

Then we load all environment variables for, I don't know, RPC endpoints that you want to use during testing.

And we also match it with our foundry tomo configuration file.

This is where you can configure a solc specific argument like optimizer settings, fast runs, things like that.

Then we go to the pre-processing phase where we read all the project graph, all the files that are included in the project, and then we apply the remapping so we get the entire call that this project consists of.

So this is how we check whether our file changed, if it needs to be recompiled, or it can be omitted because we already have it cached from a previous run.

So this speeds up recompile time drastically.

And then we populate the solc input via the standard JSON format which includes all the compiler settings, the source code, whatever.

What solc then spits out is the standard JSON output, this includes the compiled binaries, the runtime code, AST, things like that or additional properties that you also can configure.

And we write them to the output file or update no longer valid cached files.

And finally we then apply the test filter, so we filter out all the test contracts from the solidity output and call all the test functions via the Rust EVM that we use for running those tests.

Test functions are filtered out by name and we can see if this is a FUS function or a regular test function, if it is a FUS function then we generate the arguments based on the function signature and call this function over and over again and we see whether it reverts or succeeds as expected.

A core part of FORGE are solidity cheat codes which you can use during tests to manipulate the EVM or the state directly.

In a way that wouldn't be valid on the real chain, but it helps during testing if you want to fake the address of a caller for example or something simple like setting the block.timestamp variable.

All of this is exposed via the VM interface, this is where all the cheat codes are defined and those are then used in the standard test contract that you use to write your test functions.

You can call them via VM.cheat code with the right arguments and then assert, for example, that the time stamp was updated as expected.

This is basically the essential part in Forge or any tool that needs to modify EVM data.

And this is the interface in the Rust EVM, which provides a bunch of functions that are invoked during EVM executions, where we can manipulate the EVM or the state directly.

For example, there are callbacks for when a call starts, when a call is ended, step functions when a new opcode was executed, and we can implement custom inspectors like a cheat code inspector, for example, which then have mutable access to the EVM and the entire state of the EVM during VM execution.

So this is how you can update the block timestamp when warp is called, for example, or you can do some more advanced things like network forking via solidity code which will swap out the entire state during execution.

So how cheat codes work under the hood is that we have a fixed cheat code address which we listen for in our cheat code inspector.

So every time the call function is called, which happens when a new call is about to be executed by the EVM, we check if this is a call to the cheat code address.

And if so, then we intercept it and apply the cheat code.

Adding cheat codes is super easy, we just merged a new PR 2 days ago that added some missing cheat codes for working with the files, like if a file exists, if it's a directory, things like that.

These are small things, but it's very easy to add them.

To add cheat codes, you just need the cheat code signature, the function code that you want to add.

Then we use internally Abhijen, which is provided by Ethos, which takes a bunch of function signatures and then generates entire RAS bindings for this function signature.

So what you get by invoking the Abhijan proc macro with a set of solid T functions is that you get an enum for all the cheat code calls that supports decoding, encoding, things like that.

So when we have intercepted a cheat code call, then we try to decode the function input into a cheat code call and then we can apply the cheat code based on the decoded variant.

So when warp is called for example, then the function input should be decoded into a warp call and we can simply match on that decoded call and apply the G code, update the block time stamp and return.

This only adds availability in Foundry or Forge directly.

The final step would be to upstream this to Forge standards by extending the Solidity VM interface.

Slightly more advanced feature is network forking via...

Because I think Emily will focus on how to simulate EVM forking later.

But basically, since you have access to the EVM data, you can also swap out the entire database under the hood and replace database look-ups with something like eve get storage add.

Curious if the build step is handled, all the caching, all the artifacts in Foundry, is that handled by either Sol-C?

And is there any, like, do you guys have any plans on the roadmap of how that will evolve, the building and the caching of the artifacts in Foundry?

Yeah, so everything pre-processing is handled by EtherSol-C.

This includes caching as well and emitting artifacts and writing them to disk.

But since we're moving to Alloy eventually, this should be moved to Foundry directly.

So this won't be a part of Alloy in the future, instead we will move it and probably Foundry would be the right place for that.

What's the best way to do integration testing, including off-chain components?

Because the last time that I tried to do it, I wanted to use Anvil as just purely a library.

What I found was I needed to do state set up, so I need to somehow run script, and I think for that I needed to basically have Anvil running and connect to it over the JSON RPC.

So ideally I'd be able to do that all natively in Rust, but what is the recommended pattern for that?

For Anvil itself, we don't have something, or I think we actually do support a genesis file which you could use to set certain account storage slots when you launch the node.

So genesis JSON file, it's a list of accounts, a list of storage keys and values which you can use for block 0 basically, or for forge directly you can set certain contract byte codes via cheat codes, but for more advanced setup routines, probably a script or something that is invoked via an FFI cheat code or something like that.

I wanted to do a question specifically around anvil methods, for example, with the JSON RPC implementations that are being rewritten in Wraith or REST.

Because I know there are some, for example, debug methods and I think it's trace methods or filter methods that are already in ref but are not on Anvil yet, for example, trace filter.

Will that also be built in Anvil, or will you share something, some component, so you can have it in both?

So all the trace implementation in Rev are based on Anvil.

And we also have standalone RPC types in Rev now.

So the roadmap for this is that RPC types will be a stand-alone component that any project can use, and All of Anvil defined types will be replaced by that, and also all the trace implementations will be replaced by the ref implementation as well.

This will add a bunch of missing calls like debug call, I believe, is still missing.

But since we have this already in ref as a separate crate, adding this will be straightforward.

I think we can catch Matt offline for any further questions, so


Speaker 0: Thank you guys for coming. I'm Matt. I wrote a bunch of code for Foundry and now Rev. And I will talk a bit about some Foundry internals and how it works internally, how we interact with the EVM, how we get cheat codes working, how forking works under the hood briefly, and what are our next steps for Foundry. So first of all, who has used Forge or Foundry or some other tools?

Nice. Yeah, so for those who don't know, Foundry is basically a collection of tools that you can use for developing solidity or solidity adjacent work. You can use Anvil as a local Ethereum node that has a bunch of modifications that wouldn't be possible with something like Gaff or Ref. So it's a full node from scratch. Then we have Cast, which is basically just a collection of subcommands that help when you want to interact with Ethereum nodes or just to convert some ABI data input output function signatures something like that and our main motivation behind all of this was that we want to get to 100% solidity in your smart contracts repository.

So getting rid of everything else, just solidity, and support writing tests in solidity directly, and use Forge for running those tests. And it's also very easy to install. You have 1 best trip that downloads the latest release and you can use our Forge GitHub action to run it in CI. Just to give you a brief overview about the style history, because it's really nice. We hit 6K a few weeks ago, but more important, we almost had 300 contributors.

We try to be as open-minded as possible when they are triaging new issues, feature requests and help those to land their first PR in Foundry. But this talk is not necessarily a talk how to use Foundry because there are way better resources out there, there's an entire course by Patrick Collins that is multiple hours long and is for free available on GitHub, or you can have a look at our foundry book which covers everything we have in there, references to other useful documentation, templates, things like that. I will mostly focus on some force internals, but I want to not entirely exclude some cast features. For example, there's cast run, which takes an Ethereum transaction hash and then replaces that transaction locally. So it first basically forks the network at the block that this transaction was mined in, then executes all the previous transactions locally, so you get to the states the transaction used when it was first included in the node, and then it re-executes this transaction and displays all the traces.

So you can see all the calls, all the arguments and the entire trace call, which is very useful when you need to debug a transaction or just want to get a better understanding what is happening in there. And this basically works with standard RPC provider or URL to a node that supports the regular ETH RPC methods. Another cool thing with Anvil is that you can use it programmatically, so you can use it as a library and we see a lot of folks using that for simulations specifically. Getting it to work is super easy, you have basically just 1 entry point, you configure your node like if you want to fork some network, chain ID, whatever, and then you just fire it and you get API interface and basically a node handle that ensures that the node is not dropped. This way you can bypass the entire RPC layer directly and speak to the node directly without going through RPCs.

If you run simulations for example, you want to eave call, you use the API object directly and you don't need to go through RPC at all. So I think this is pretty cool, but I wanna focus on what happens when you run Forge test under the hood. So on the left side, you'll see the template test contract that you get when you initialize a Forge repository or Forge project. And you see there is some test contract that inherits from the Forge STD test and you have a bunch of test functions where this is where you write your tests and you have a bunch of assert functions that you can then use to test your contract calls. And what you see when you run Forge test is that first everything is compiled, then we run all the test functions and they either pass or fail.

If you look closely at the test fuzz function, then you see that This function takes a bunch of arguments, and those are Fuzz by default. These are Fuzz functions where Forge internally generates a bunch of random arguments, and then calls this function multiple times. You can have multiple arguments and yeah, go wild with the fast logic here. But what happens internally when you call Forge test is that we first prepare the solc call that eventually is invoked. And this includes loading all the forge CLI arguments, like if you have a filter for specific functions that you want to run or contracts, then this is handled here.

Then we load all environment variables for, I don't know, RPC endpoints that you want to use during testing. And we also match it with our foundry tomo configuration file. This is where you can configure a solc specific argument like optimizer settings, fast runs, things like that. Then we go to the pre-processing phase where we read all the project graph, all the files that are included in the project, and then we apply the remapping so we get the entire call that this project consists of. So this is how we check whether our file changed, if it needs to be recompiled, or it can be omitted because we already have it cached from a previous run.

So this speeds up recompile time drastically. And then we populate the solc input via the standard JSON format which includes all the compiler settings, the source code, whatever. What solc then spits out is the standard JSON output, this includes the compiled binaries, the runtime code, AST, things like that or additional properties that you also can configure. And we write them to the output file or update no longer valid cached files. And finally we then apply the test filter, so we filter out all the test contracts from the solidity output and call all the test functions via the Rust EVM that we use for running those tests.

Test functions are filtered out by name and we can see if this is a FUS function or a regular test function, if it is a FUS function then we generate the arguments based on the function signature and call this function over and over again and we see whether it reverts or succeeds as expected. A core part of FORGE are solidity cheat codes which you can use during tests to manipulate the EVM or the state directly. In a way that wouldn't be valid on the real chain, but it helps during testing if you want to fake the address of a caller for example or something simple like setting the block.timestamp variable. All of this is exposed via the VM interface, this is where all the cheat codes are defined and those are then used in the standard test contract that you use to write your test functions. You can call them via VM.cheat code with the right arguments and then assert, for example, that the time stamp was updated as expected.

So there's more code. This is basically the essential part in Forge or any tool that needs to modify EVM data. And this is the interface in the Rust EVM, which provides a bunch of functions that are invoked during EVM executions, where we can manipulate the EVM or the state directly. For example, there are callbacks for when a call starts, when a call is ended, step functions when a new opcode was executed, and we can implement custom inspectors like a cheat code inspector, for example, which then have mutable access to the EVM and the entire state of the EVM during VM execution. So this is how you can update the block timestamp when warp is called, for example, or you can do some more advanced things like network forking via solidity code which will swap out the entire state during execution.

So how cheat codes work under the hood is that we have a fixed cheat code address which we listen for in our cheat code inspector. So every time the call function is called, which happens when a new call is about to be executed by the EVM, we check if this is a call to the cheat code address. And if so, then we intercept it and apply the cheat code. Adding cheat codes is super easy, we just merged a new PR 2 days ago that added some missing cheat codes for working with the files, like if a file exists, if it's a directory, things like that. These are small things, but it's very easy to add them.

To add cheat codes, you just need the cheat code signature, the function code that you want to add. Then we use internally Abhijen, which is provided by Ethos, which takes a bunch of function signatures and then generates entire RAS bindings for this function signature. So what you get by invoking the Abhijan proc macro with a set of solid T functions is that you get an enum for all the cheat code calls that supports decoding, encoding, things like that. So when we have intercepted a cheat code call, then we try to decode the function input into a cheat code call and then we can apply the cheat code based on the decoded variant. So when warp is called for example, then the function input should be decoded into a warp call and we can simply match on that decoded call and apply the G code, update the block time stamp and return.

This only adds availability in Foundry or Forge directly. The final step would be to upstream this to Forge standards by extending the Solidity VM interface. Slightly more advanced feature is network forking via... Okay, last slide. Because I think Emily will focus on how to simulate EVM forking later.

But basically, since you have access to the EVM data, you can also swap out the entire database under the hood and replace database look-ups with something like eve get storage add. All right. Yeah. Questions? Yeah.

Speaker 1: Q. Curious if the build step is handled, all the caching, all the artifacts in Foundry, is that handled by either Sol-C? And is there any, like, do you guys have any plans on the roadmap of how that will evolve, the building and the caching of the artifacts in Foundry?

Speaker 0: Yeah, so everything pre-processing is handled by EtherSol-C. This includes caching as well and emitting artifacts and writing them to disk. But since we're moving to Alloy eventually, this should be moved to Foundry directly. So this won't be a part of Alloy in the future, instead we will move it and probably Foundry would be the right place for that.

Speaker 2: What's the best way to do integration testing, including off-chain components? Because the last time that I tried to do it, I wanted to use Anvil as just purely a library. What I found was I needed to do state set up, so I need to somehow run script, and I think for that I needed to basically have Anvil running and connect to it over the JSON RPC. So ideally I'd be able to do that all natively in Rust, but what is the recommended pattern for that?

Speaker 0: For Anvil itself, we don't have something, or I think we actually do support a genesis file which you could use to set certain account storage slots when you launch the node. So genesis JSON file, it's a list of accounts, a list of storage keys and values which you can use for block 0 basically, or for forge directly you can set certain contract byte codes via cheat codes, but for more advanced setup routines, probably a script or something that is invoked via an FFI cheat code or something like that. Okay. Okay.

Speaker 3: Checking, okay. Hey, Matt. I wanted to do a question specifically around anvil methods, for example, with the JSON RPC implementations that are being rewritten in Wraith or REST. How will the future of that look like? Because I know there are some, for example, debug methods and I think it's trace methods or filter methods that are already in ref but are not on Anvil yet, for example, trace filter.

How will that look like in the future? Will that also be built in Anvil, or will you share something, some component, so you can have it in both?

Speaker 0: Thanks for asking. So all the trace implementation in Rev are based on Anvil. We fixed a lot of bugs in there. And we also have standalone RPC types in Rev now. So the roadmap for this is that RPC types will be a stand-alone component that any project can use, and All of Anvil defined types will be replaced by that, and also all the trace implementations will be replaced by the ref implementation as well.

This will add a bunch of missing calls like debug call, I believe, is still missing. But since we have this already in ref as a separate crate, adding this will be straightforward.

Speaker 2: I think we can catch Matt offline for any further questions, so

Speaker 0: let's give

Speaker 2: him a round of applause.

See all Paradigm transcripts on Youtube

Rust x Ethereum Day - Foundry