Gravity bridge is Cosmos <-> Ethereum bridge designed to run on the Cosmos Hub focused on maximum design simplicity and efficiency.
Gravity can transfer ERC20 assets originating on Ethereum to a Cosmos based chain and back to Ethereum.
The ability to transfer assets originating on Cosmos to an ERC20 representation on Ethereum is coming within a few months.
Gravity bridge is under development and will be undergoing audits soon. Instructions for deployment and use are provided in the hope that they will be useful.
It is your responsibility to understand the financial, legal, and other risks of using this software. There is no guarantee of functionality or safety. You use Gravity entirely at your own risk.
You can keep up with the latest development by watching our public standups feel free to join yourself and ask questions.
updateValset
method at least once every Cosmos unbonding period (usually 2 weeks). This is because if there has not been an update for longer than the unbonding period, the validator set stored by the Ethereum contract could contain validators who cannot be slashed for misbehavior.We provide a one button integration test that deploys a full arbitrary validator Cosmos chain and testnet Geth chain for both development + validation. We believe having a in depth test environment reflecting the full deployment and production-like use of the code is essential to productive development.
Currently on every commit we send hundreds of transactions, dozens of validator set updates, and several transaction batches in our test environment. This provides a high level of quality assurance for the Gravity bridge.
Because the tests build absolutely everything in this repository they do take a significant amount of time to run. You may wish to simply push to a branch and have Github CI take care of the actual running of the tests.
To run the tests, you'll need to have docker installed. First, run the following to build the gravity
, orchestrator
, and ethereum
containers:
make e2e_build_images
There is a "sandbox" style test, which simply brings up the chain and allows you as the developer to perform whatever operations you want.
To interact with the ethereum side of the chain, use the JSON-RPC server located at http://localhost:8545
. You may choose to use foundry
or hardhat
to make this easier.
To interact with the gravity module itself, you'll want to build the gravity
module locally by running the following command.
cd module make build
You can then use the binary in the build directory to interact with the Cosmos side of the chain. Check out the Cosmos documentation for more information on this.
To run all the integration tests (except the sandbox test above), use the following command.
make e2e_slow_loris
There are optional tests for specific features. Check out the Makefile
for a list of all of them.
Valset stress changes the validating power randomly 25 times, in an attempt to break validator set syncing
make e2e_valset_stress
Batch stress sends 300 transactions over the bridge and then 3 batches back to Ethereum. This code can do up to 10k transactions but Github Actions does not have the horsepower.
make e2e_batch_stress
Validator out tests a validator that is not running the mandatory Ethereum node. This validator will be slashed and the bridge will remain functioning.
make e2e_validator_out
in the solidity
folder
Run HUSKY_SKIP_INSTALL=1 npm install
, then npm run typechain
.
Run npm run evm
in a separate terminal and then
Run npm run test
to run tests.
After modifying solidity files, run npm run typechain
to recompile contract
typedefs.
The Solidity contract is also covered in the Cosmos module tests, where it will be automatically deployed to the Geth test chain inside the development container for a micro testnet every integration test run.
We provide a standard container-based development environment that automatically bootstraps a Cosmos chain and Ethereum chain for testing. We believe standardization of the development environment and ease of development are essential so please file issues if you run into issues with the development flow.
These do not run the entire chain but instead test parts of the Go module code in isolation. To run them, go into /module
and run make test
This method is dictinct from the all up test described above. Although it runs the same components it's much faster when editing individual components.
./tests/build-container.sh
./tests/start-chains.sh
./tests/run-tests.sh
docker exec -it gravity_test_instance /bin/bash
should allow you to access a shell inside the test containerChange the code, and when you want to test it again, restart ./tests/start-chains.sh
and run ./tests/run-tests.sh
.
./tests/build-container.sh
builds the base container and builds the Gravity test zone for the first time. This results in a Docker container which contains cached Go dependencies (the base container).
./tests/start-chains.sh
starts a test container based on the base container and copies the current source code (including any changes you have made) into it. It then builds the Gravity test zone, benefiting from the cached Go dependencies. It then starts the Cosmos chain running on your new code. It also starts an Ethereum node. These nodes stay running in the terminal you started it in, and it can be useful to look at the logs. Be aware that this also mounts the Gravity repo folder into the container, meaning changes you make will be reflected there.
./tests/run-tests.sh
connects to the running test container and runs the integration test found in ./tests/integration-tests.sh
It can be useful to modify, recompile, and restart the testnet without restarting the container, for example if you are running a text editor in the container and would not like it to exit, or if you are editing dependencies stored in the container's /go/
folder.
In this workflow, you can use ./tests/reload-code.sh
to recompile and restart the testnet without restarting the container.
For example, you can use VS Code's "Remote-Container" extension to attach to the running container started with ./tests/start-chains.sh
, then edit the code inside the container, restart the testnet with ./tests/reload-code.sh
, and run the tests with ./tests/integration-tests.sh
.
To use a stepping debugger in VS Code, follow the "Working inside the container" instructions above, but set up a one node testnet using ./tests/reload-code.sh 1
. Now kill the node with pkill gravityd
. Start the debugger from within VS Code, and you will have a 1 node debuggable testnet.