https://github.com/oasisprotocol/oasis-web3-gateway
Web3 Gateway for the Oasis SDK EVM ParaTime module.
https://github.com/oasisprotocol/oasis-web3-gateway
blockchain ethereum evm gateway go oasis official paratime postgresql web3
Last synced: 5 months ago
JSON representation
Web3 Gateway for the Oasis SDK EVM ParaTime module.
- Host: GitHub
- URL: https://github.com/oasisprotocol/oasis-web3-gateway
- Owner: oasisprotocol
- License: gpl-3.0
- Created: 2021-09-23T01:06:34.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-04-30T17:16:53.000Z (about 1 year ago)
- Last Synced: 2025-04-30T17:48:09.097Z (about 1 year ago)
- Topics: blockchain, ethereum, evm, gateway, go, oasis, official, paratime, postgresql, web3
- Language: Go
- Homepage:
- Size: 19.7 MB
- Stars: 28
- Watchers: 11
- Forks: 16
- Open Issues: 30
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# oasis-web3-gateway
[](https://github.com/oasisprotocol/oasis-web3-gateway/actions/workflows/ci-lint.yml)
[](https://github.com/oasisprotocol/oasis-web3-gateway/actions/workflows/ci-test.yaml)
[](https://codecov.io/gh/oasisprotocol/oasis-web3-gateway)
Web3 Gateway for Oasis-SDK Paratime EVM module.
## Building and Testing
### Prerequisites
- [Go](https://go.dev/) (at least version 1.25).
- [PostgreSQL](https://www.postgresql.org/) (at least version 13.3).
Additionally, for testing:
- [Oasis Core](https://github.com/oasisprotocol/oasis-core) at least version 24.0.x.
- [Emerald Paratime](https://github.com/oasisprotocol/emerald-paratime) at least version 11.x.x.
- (or) [Sapphire Paratime](https://github.com/oasisprotocol/sapphire-paratime) at least version 0.7.3.
### Build
To build the binary run:
```bash
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.
```bash
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 `OASIS_DOCKER_NO_GATEWAY=yes` environment variable:
```bash
docker run --rm -ti -e OASIS_DOCKER_NO_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:
```bash
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.
```bash
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:
```yaml
# ... sections not relevant are omitted ...
runtime:
mode: client
paths:
-
config:
"":
# The following allows the gateway to perform gas estimation of smart
# contract calls (not allowed by default).
estimate_gas_by_simulating_contracts: 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:
```yaml
runtime_id:
node_address: "unix:"
enable_pruning: false
pruning_step: 100000
indexing_start: 0
log:
level: debug
format: json
database:
host:
port:
db:
user:
password:
dial_timeout: 5
read_timeout: 10
write_timeout: 5
max_open_conns: 0
gateway:
chain_id:
http:
host:
port:
cors: ["*"]
ws:
host:
port:
origins: ["*"]
method_limits:
get_logs_max_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:
```bash
DATABASE__PASSWORD:
```
environment variable.
Start the gateway by running the `oasis-web3-gateway` binary:
```bash
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:
```bash
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](CONTRIBUTING.md).
### 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](https://github.com/ethereum/go-ethereum).