oasis-web3-gateway

Web3 Gateway for Oasis-SDK Paratime EVM module.

Building and Testing

Prerequisites

• Go (at least version 1.25).
• PostgreSQL (at least version 13.3).

• Oasis Core at least version 24.0.x.
• Emerald Paratime at least version 11.x.x.
• (or) Sapphire Paratime at least version 0.7.3.

Build

To build the binary run:

make build

Testing on Localnet

The Docker containers can be used to test changes to the gateway or run tests by bind-mounting the runtime state directory (/serverdir/node) into your local filesystem.

docker run --rm -ti -p5432:5432 -p8544-8548:8544-8548 -v /tmp/eth-runtime-test:/serverdir/node ghcr.io/oasisprotocol/sapphire-localnet:local

If needed, the oasis-web3-gateway or sapphire-paratime executables could also be bind-mounted into the container, allowing for quick turnaround time when testing the full gateway & paratime stack together.

Running tests

For running tests, start the docker network without the gateway, by setting the OASISDOCKERNO_GATEWAY=yes environment variable:

docker run --rm -ti -e OASISDOCKERNO_GATEWAY=yes -p5432:5432 -p8544-8548:8544-8548 -v /tmp/eth-runtime-test:/serverdir/node ghcr.io/oasisprotocol/sapphire-localnet:local

Once bootstrapped, run the tests:

make test

[oasis-core]: https://github.com/oasisprotocol/oasis-core

Localnet Docker images

You can also build emerald-dev and sapphire-dev docker images with a complete confidential and non-confidential Localnet Oasis stack respectively for development, CI and testing.

make docker

Check out [docker folder] for more information.

[docker folder]: docker/README.md

Running the Gateway on Testnet/Mainnet

The gateway connects to an Emerald/Sapphire enabled [Oasis ParaTime Client Node].

In addition to the general instructions for setting up an Oasis ParaTime Client Node update the node configuration (e.g. config.yml) as follows:

# ... sections not relevant are omitted ...
runtime:
  mode: client
  paths:
    - <orcbundlepath>
config:     "<paratime_id>":       # The following allows the gateway to perform gas estimation of smart       # contract calls (not allowed by default).       estimategasbysimulatingcontracts: true       # The following allows some more resource-intensive queries to be called       # by the gateway (not allowed by default).       allowed_queries:         - all_expensive: true

Set up the config file (e.g. gateway.yml) appropriately:

runtimeid: <paratimeid>
node_address: "unix:<path-to-oasis-node-unix-socket>"
enable_pruning: false
pruning_step: 100000
indexing_start: 0
log:   level: debug   format: json
database:   host: <postgresql_host>   port: <postgresql_port>   db: <postgresql_db>   user: <postgresql_user>   password: <postgresql_password>   dial_timeout: 5   read_timeout: 10   write_timeout: 5   maxopenconns: 0
gateway:   chainid: <chainid>   http:     host: <gatewaylisteninterface>     port: <gatewaylistenport>     cors: ["*"]   ws:     host: <gatewaylisteninterface>     port: <gatewaylistenwebsocket_port>     origins: ["*"]   method_limits:     getlogsmax_rounds: 100   oasis_rpcs: true # Enable Oasis-specific requests for confidentiality etc.

Note: all configuration settings can also be set via environment variables. For example to set the database password use:

DATABASE_PASSWORD: <postgresqlpassword>

environment variable.

Start the gateway by running the oasis-web3-gateway binary:

oasis-web3-gateway --config gateway.yml

[Oasis ParaTime Client Node]: https://docs.oasis.io/node/run-your-node/paratime-client-node

Wipe state to force a complete reindex

To wipe the DB state and force a reindexing use the truncate-db subcommand:

oasis-web3-gateway truncate-db --config gateway.yml --unsafe

**Warning: this will wipe all existing state in the Postgres DB and can lead to extended downtime while the Web3 Gateway is reindexing the blocks.**

Contributing

See our Contributing Guidelines.

Versioning

See our [Versioning] document.

[Versioning]: docs/versioning.md

Release Process

See our [Release Process] document.

[Release Process]: docs/release-process.md

Credits

Parts of the code heavily based on go-ethereum.