https://github.com/oguimbal/evm-js-emulator
https://github.com/oguimbal/evm-js-emulator
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/oguimbal/evm-js-emulator
- Owner: oguimbal
- Created: 2022-09-01T08:34:48.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2025-01-21T11:08:41.000Z (9 months ago)
- Last Synced: 2025-04-24T20:06:28.340Z (6 months ago)
- Language: TypeScript
- Size: 287 KB
- Stars: 6
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
A simple in-memory EVM JS emulator.
# Install
```
npm i evm-js-emulator
```
# Usage
```typescript
import { newSession, parseBuffer, toUint, MAX_UINT, isSuccess } from 'evm-js-emulator';
// create a blockchain fork
const session = newSession({
// let's fork Polygon
rpcUrl: 'https://polygon-rpc.com',
// when you're running node, cache RPC results in order to avoid coldstarts
// (this will freeze your runs to the current block, until you delete this folder)
cacheDir: '.evm-cache',
});
// prepare an execution
const executor = await session.prepareCall({
contract: toUint('0x ... write contract address here ...'),
origin: toUint('0x ... write sender address here ...'),
// a buffer which represents calldata
calldata: parseBuffer('0x ... write calldata here ...'),
// tx value
callvalue: U256(0),
// this is not a static call (allow mutations)
static: false,
// force timestamp to a given value (optional)
timestamp: Date.now() / 1000,
// other paramters
gasLimit: MAX_UINT,
gasPrice: U256(0xffff),
retdatasize: 0,
});
// execute !
const result = await executor.execute();
if (isSuccess(result)) {
// do something ...
}
// etc... you can chain multiple executions
```
# Debugging
- Once you get an executor, before calling `.execute()`, you can log every EVM execution instruction using the helper:
```typescript
import { watchInstructions } from 'evm-js-emulator/tests/test-utils';
// this will log all instructions down to a depth of 3 subcalls
watchInstructions(executor, 3);
```
- You can name contracts or add ABIs to have nicer logs using the `contractsNames` properties of `newSession({ contractsNames: ...})` (see types).
- Add breakpoints in codegen js files that you will find in you cache directory (subdirectory "contracts")... those are the contracts you are running, compiled to JS.
# Disclaimer
This is a best-effort reproduction of the EVM.
It has been tested on many contracts, but:
- Gas is almost not implemented (contributions welcome)
- Some opcodes might not be implemented (contributions welcome)
- Behaviours might differ
# TODO
- Implement missing opcodes
- Implement sourcemaps to be able to step in .sol files