Skip to content

Commit

Permalink
Update README with example on how to run local EVM Gateway connected …
Browse files Browse the repository at this point in the history 
…to testnet
  • Loading branch information
@m-Peter
m-Peter committed Oct 18, 2024
1 parent b70a783 commit 6c2e536
Showing 1 changed file with 28 additions and 29 deletions.
57 changes: 28 additions & 29 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,14 @@

**EVM Gateway enables seamless interaction with EVM on Flow, mirroring the experience of engaging with any other EVM blockchain.**

EVM Gateway implements the Ethereum JSON-RPC API for [EVM on Flow](https://developers.flow.com/evm/about) which conforms to the Ethereum [JSON-RPC specification](https://ethereum.github.io/execution-apis/api-documentation/). The EVM Gateway is tailored for integration with the EVM environment on the Flow blockchain. Rather than implementing the full `geth` stack, the JSON-RPC API available in EVM Gateway is a lightweight implementation that uses Flow's underlying consensus and smart contract language, [Cadence](https://cadence-lang.org/docs/), to handle calls received by the EVM Gateway. For those interested in the underlying implementation details, please refer to the [FLIP #243](https://github.com/onflow/flips/issues/243) (EVM Gateway) and [FLIP #223](https://github.com/onflow/flips/issues/223) (EVM on Flow Core) improvement proposals.
EVM Gateway implements the Ethereum JSON-RPC API for [EVM on Flow](https://developers.flow.com/evm/about) which conforms to the Ethereum [JSON-RPC specification](https://ethereum.github.io/execution-apis/api-documentation/). The EVM Gateway is tailored for integration with the EVM environment on the Flow blockchain. Rather than implementing the full `geth` stack, the JSON-RPC API available in EVM Gateway is a lightweight implementation that uses Flow's underlying consensus and smart contract language, [Cadence](https://cadence-lang.org/docs/), to handle calls received by the EVM Gateway. For those interested in the underlying implementation details, please refer to the [FLIP #243](https://github.com/onflow/flips/issues/243) (EVM Gateway) and [FLIP #223](https://github.com/onflow/flips/issues/223) (EVM on Flow Core) improvement proposals.

EVM Gateway is compatible with the majority of standard Ethereum JSON-RPC APIs allowing seamless integration with existing Ethereum-compatible web3 tools via HTTP. EVM Gateway honors Ethereum's JSON-RPC namespace system, grouping RPC methods into categories based on their specific purpose. Each method name is constructed using the namespace, an underscore, and the specific method name in that namespace. For example, the `eth_call` method is located within the `eth` namespace. See below for details on methods currently supported or planned.

### Design

![design ](https://github.com/onflow/flow-evm-gateway/assets/75445744/3fd65313-4041-46d1-b263-b848640d019f)


The basic design of the EVM Gateway consists of a couple of components:

- Event Ingestion Engine: this component listens to all Cadence events that are emitted by the EVM core, which can be identified by the special event type ID `evm.TransactionExecuted` and `evm.BlockExecuted` and decodes and index the data they contain in the payloads.
Expand Down Expand Up @@ -46,7 +45,7 @@ To view all the available flags for running the EVM Gateway Node:
./flow-evm-gateway help run
```

The binary can then be run using the appropriate flags:
The binary can then be run by passing the necessary flags:

```bash
./flow-evm-gateway run {flags}
Expand All @@ -66,32 +65,28 @@ Operating an EVM Gateway is straightforward. It can either be deployed locally a
**Start Emulator**

To run the gateway locally you need to start the Flow Emulator:
```

```bash
flow emulator
```
_Make sure flow.json has the emulator account configured to address and private key we will use for starting gateway bellow._

Please refer to the configuration section and read through all the configuration flags before proceeding.

Then you need to start the gateway:
```
go run cmd/main/main.go \
--flow-network-id flow-emulator \
--coinbase FACF71692421039876a5BB4F10EF7A439D8ef61E \
--coa-address f8d6e0586b0a20c7 \
--coa-key 2619878f0e2ff438d17835c2a4561cb87b4d24d72d12ec34569acd0dd4af7c21 \
--coa-resource-create \
--gas-price 0
Then you can start the EVM Gateway with:

```bash
make start-local
```

Note that the gateway will be starting from the latest emulator block, so if the emulator is run before and transactions happen in the meantime, the gateway will not fetch those historical blocks & transactions.
Note that the gateway will be starting from the latest emulator block, so if the emulator is run before any transactions happen in the meantime, the gateway will not fetch those historical blocks & transactions.
This will be improved soon.

_In this example we use `coa-address` value set to the service account of the emulator, the same as `coa-key`.
This account will by default be funded with Flow which is a requirement. For `coinbase` we can
use whichever valid EVM address. It's not really useful for local running besides collecting fees. We also allow for the
`coa-resource-create` to auto-create resources needed on start-up on the `coa` account in order to operate the gateway.
`gas-price` is set at 0 so we don't have to fund EOA accounts. We can set it higher but keep in mind you will then
_In the example above we set `coa-address` value to the service account of the emulator, the same as `coa-key`.
This account will by default be funded with Flow which is a requirement. For `coinbase` we can
use whichever valid EVM address. It's not really useful when running locally besides collecting fees. We also allow for the
`coa-resource-create` to auto-create resources needed on start-up on the `coa` account in order to operate the gateway.
`gas-price` is set at 0 so we don't have to fund EOA accounts. We can set it higher but keep in mind you will then
need funded accounts for interacting with EVM._

**With Docker**
Expand Down Expand Up @@ -123,26 +118,30 @@ it should return:
}
```

**Running on Testnet**
### Running on Testnet

Running against the testnet with a local build can be done by pointing the gateway to the testnet ANs and providing the correct configuration.
Running against the testnet with a local build can be done by pointing the gateway to the testnet ANs and providing the correct configuration.
Please refer to the configuration section and read through all the configuration flags before proceeding.

Below is an example configuration for running against testnet, with an already created testnet account.

```
./evm-gateway \
```bash
./flow-evm-gateway run \
--access-node-grpc-host=access.devnet.nodes.onflow.org:9000 \
--access-node-spork-hosts=access-001.devnet51.nodes.onflow.org:9000 \
--flow-network-id=flow-testnet \
--init-cadence-height=211176670 \
--ws-enabled=true \
--coa-resource-create=true \
--coa-resource-create=false \
--coinbase=FACF71692421039876a5BB4F10EF7A439D8ef61E \
--coa-address=0x62631c28c9fc5a91 \
--coa-key=2892fba444f1d5787739708874e3b01160671924610411ac787ac1379d420f49 \
--gas-price=100
```

If you wish to test this out with your own Access Node, simply point `--access-node-grpc-host` to the location where it is hosted.
*Note:* You need to make sure that your Access Node has indexed up to Flow block height `211176670`. This is the height where the `EVM` contract was first deployed on testnet.

For the `--gas-price`, feel free to experiment with different values.

The `--coinbase` can be any EOA address.
Expand Down Expand Up @@ -186,7 +185,7 @@ Should return a response similar to:
}
```

**Running on Mainnet**
### Running on Mainnet

Running the EVM gateway for mainnet requires additional security and stability measures which are described in this document: https://flowfoundation.notion.site/EVM-Gateway-Deployment-3c41da6710af40acbaf971e22ce0a9fd?pvs=74

Expand Down Expand Up @@ -229,7 +228,7 @@ The application can be configured using the following flags at runtime:
| `traces-backfill-start-height` | `0` | Start height for backfilling transaction traces |
| `traces-backfill-end-height` | `0` | End height for backfilling transaction traces |
| `index-only` | `false` | Run in index-only mode, allowing state queries and indexing but no transaction sending |
| `profiler-enabled` | `false` | Enable the pprof profiler server |
| `profiler-enabled` | `false` | Enable the pprof profiler server |
| `profiler-host` | `localhost` | Host for the pprof profiler |
| `profiler-port` | `6060` | Port for the pprof profiler |

Expand Down Expand Up @@ -268,15 +267,15 @@ The EVM Gateway implements APIs according to the Ethereum specification: https:/
* debug_traceTransaction
* debug_traceBlockByNumber
* debug_traceBlockByHash

**Unsupported APIs**
- Wallet APIs: we don't officially support wallet APIs (eth_accounts, eth_sign, eth_signTransaction, eth_sendTransaction) due to security
concerns that come with managing the keys on production environments, however, it is possible to configure the gateway to allow these
methods for local development by using a special flag `--wallet-api-key`.
methods for local development by using a special flag `--wallet-api-key`.
- Proof API: we don't support obtaining proofs yet, Flow piggy-backs on the Flow consensus, and hence the Flow proofs can be used to verify
and trust the EVM environment. We intend to add access to EVM proofs in the future.
- Access Lists: we don't yet support creating access lists as they don't affect the fees we charge. We might support this in the future
to optimize fees, but it currently is not part of our priorities.
to optimize fees, but it currently is not part of our priorities.

# Debugging

Expand Down

0 comments on commit 6c2e536

Please sign in to comment.