From 60391048a60807d4e018cefa484ddcce2fb6ecaa Mon Sep 17 00:00:00 2001 From: Justin Kilpatrick Date: Mon, 18 Jan 2021 14:41:31 -0500 Subject: [PATCH] Gravity readme update This updates the readme to be in line with the new Gravity name. Some changes like the 'peggyd' binary have not yet actaully be made in the repo and we should make haste to do so before anyone is confused. This patch also includes the logo SVG. --- gravity-bridge.svg | 47 ++++++++++++++++++++++++++++++ readme.md | 71 ++++++++++++++++++++++++++++++---------------- 2 files changed, 94 insertions(+), 24 deletions(-) create mode 100644 gravity-bridge.svg diff --git a/gravity-bridge.svg b/gravity-bridge.svg new file mode 100644 index 000000000..6374a739a --- /dev/null +++ b/gravity-bridge.svg @@ -0,0 +1,47 @@ + + + + Group + Created with Sketch. + + + + + + + + + + \ No newline at end of file diff --git a/readme.md b/readme.md index da742a040..663bfae45 100644 --- a/readme.md +++ b/readme.md @@ -1,34 +1,37 @@ -# Althea Peggy +![Gravity Bridge](./gravity-bridge.svg) -Althea Peggy is a simplified vision of a Cosmos <-> Ethereum 'peg zone' focused on maximum design simplicity and efficiency. +Gravity bridge is Cosmos <-> Ethereum bridge designed to run on the [Cosmos Hub](https://github.com/cosmos/gaia) focused on maximum design simplicity and efficiency. -For now Althea Peggy is focused on only one of the major functions of an Ethereum peg zone. Bidirectional transfer of ERC20 assets originating on Ethereum to a Cosmos based chain. +Gravity is currently can transfer ERC20 assets originating on Ethereum to a Cosmos based chain and back to Ethereum. -An expansion of this feature set is expected, but will only be performed once basic transfers are in production. This gives us the opportunity to develop solid foundations and technology useful for the larger peg zone vision without getting bogged down by a larger feature surface. +The ability to transfer assets originating on Cosmos to an ERC20 representation on Ethereum is coming within a few months. ## Status -Althea Peggy is under development and unaudited. Instructions for deployment and use are provided in the hope that they will be useful. +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 Peggy entirely at your own risk. +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](https://www.youtube.com/playlist?list=PL1MwlVJloJeyeE23-UmXeIx2NSxs_CV4b) feel free to join yourself and ask questions. - Solidity Contract - [x] Multiple ERC20 support - [x] Tested with 100+ validators - - [X] Unit tests for every throw condition - - [x] Audit + - [x] Unit tests for every throw condition + - [x] Audit for assets originating on Ethereum + - [ ] Support for issuing Cosmos assets on Ethereum - Cosmos Module - [x] Basic validator set syncing - [x] Basic transaction batch generation - [x] Ethereum -> Cosmos Token issuing - [x] Cosmos -> Ethereum Token issuing - - [X] Bootstrapping - - [X] Genesis file save/load - - [X] Validator set syncing edge cases + - [x] Bootstrapping + - [x] Genesis file save/load + - [x] Validator set syncing edge cases + - [x] Slashing + - [x] Relaying edge cases - [ ] Transaction batch edge cases - - [ ] Relaying edge cases + - [ ] Support for issuing Cosmos assets on Ethereum - [ ] Audit - Orchestrator / Relayer - [x] Validator set update relaying @@ -37,25 +40,44 @@ You can keep up with the latest development by watching our [public standups](ht - [ ] Tendermint KMS support - [ ] Audit -## Design simplifications from the larger peg zone vision +## The design of Gravity Bridge - Validators are fully trusted to manage the bridge. Validator powers and votes are replicated on the Ethereum side so trust in bridge assets depends entirely on trust in the validator set of the peg zone chain. This has known problems where the assets in the bridge exceed the market cap of the native token. We accept these known issues in exchange for the dramatic design simplification combined with acceptable decentralization this design provides. -- The Althea Peggy Ethereum contract only supports ERC20 transfers and not arbitrary data. This helps keep the contract simple enough to optimize heavily and reach production quality quickly. -- The Relayer as a discrete binary only exists to facilitate the bridge fee market. All chain oracle functions will be integrated directly into the Gaiad binary. This makes it mandatory for peg zone validators to maintain a trusted Ethereum node and removes all trust and game theory implications that usually arise from independent relayers. +- The Gravity Ethereum contract only supports ERC20 transfers and not arbitrary data. This helps keep the contract simple enough to optimize heavily and reach production quality quickly. +- It is mandatory for peg zone validators to maintain a trusted Ethereum node. This removes all trust and game theory implications that usually arise from independent relayers, once again dramatically simplifying the design. -## Key Components you can run today +## Key design Components -- A highly efficient way of mirroring Cosmos validator voting onto Ethereum. The Althea-Peggy solidity contract has validator set updates costing ~500,000 gas ($2 @ 20gwei) and transaction batches have a base cost of ~500,000 gas ($2 @ 20gwei). This is tested using a snapshot of the Cosmos Hub validator set, with 100+ unique validators. We hope to further reduce these gas costs, see `solidity/possible_optimizations.md` for more details. Batches may contain arbitrary numbers of transactions within the limits of ERC20 sends per block. Allowing for costs to be heavily amortized on high volume bridges. This code will likely be re-used in any iteration of Peggy. -- All up integration tests, we provide a one button integration test that deploys a full arbitrary validator Cosmos chain and testnet Geth chain for both development and integration test 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. +- A highly efficient way of mirroring Cosmos validator voting onto Ethereum. The Gravity solidity contract has validator set updates costing ~500,000 gas ($2 @ 20gwei), tested on a snapshot of the Cosmos Hub validator set with 125 validators. Verifying the votes of the validator set is the most expensive on chain operation Gravity has to perform. Our highly optimized Solidity code provides enormous cost savings. Existing bridges incur more than double the gas costs for signature sets as small as 8 signers. +- Transactions from Cosmos to ethereum are batched, batches have a base cost of ~500,000 gas ($2 @ 20gwei). Batches may contain arbitrary numbers of transactions within the limits of ERC20 sends per block. Allowing for costs to be heavily amortized on high volume bridges. In this way a batch of 100 transactions may each pay only 2c, on top of their existing ERC20 transfer fees, to cross the bridge. +- We hope to further reduce these gas costs, see `solidity/possible_optimizations.md` for more details. -## Running the all up tests +## Run Gravity bridge right now using docker -These tests cover everything that's working in this repo (or not) currently they build the Ethereum contract, run the happy path tests and then build + deploy a small Cosmos blockchain in docker running the code in the `module` folder. This code doesn't do much at the moment as we're working on getting it to generate validator updates to relay to the Ethereum contract. +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 test simply have docker installed and run. `bash tests/all-up-test.sh` +There are optional tests for specific features + +Valset stress changes the validating power randomly 25 times, in an attempt to break validator set syncing + +`bash tests/all-up-test.sh 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. + +`bash tests/all-up-test.sh 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. + +`bash tests/all-up-test.sh VALIDATOR_OUT` + # Developer guide ## Solidity Contract @@ -78,6 +100,7 @@ The Solidity contract is also covered in the Cosmos module tests, where it will 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. ### Go unit tests + 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` ### To hand test your changes quickly @@ -87,15 +110,15 @@ This method is dictinct from the all up test described above. Although it runs t 1. run `./tests/build-container.sh` 2. run `./tests/start-chains.sh` 3. switch to a new terminal and run `./tests/run-tests.sh` -4. Or, `docker exec -it peggy_test_instance /bin/bash` should allow you to access a shell inside the test container +4. Or, `docker exec -it gravity_test_instance /bin/bash` should allow you to access a shell inside the test container Change the code, and when you want to test it again, restart `./tests/start-chains.sh` and run `./tests/run-tests.sh`. ### Explanation: -`./tests/build-container.sh` builds the base container and builds the peggy test zone for the first time. This results in a Docker container which contains cached Go dependencies (the base container). +`./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 peggy 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 peggy folder into the container, meaning changes you make will be reflected there. +`./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` @@ -114,4 +137,4 @@ For example, you can use VS Code's "Remote-Container" extension to attach to the ## Debugger -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 peggyd`. Start the debugger from within VS Code, and you will have a 1 node debuggable testnet. +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.