Giter Club home page Giter Club logo

gravity-docs's Introduction

Gravity Bridge

Gravity bridge is Cosmos <-> Ethereum bridge designed to run on the Cosmos SDK blockchains like the Cosmos Hub focused on maximum design simplicity and efficiency.

Gravity currently can transfer ERC20 assets originating on Cosmos or Ethereum to and from Ethereum, as well as move Cosmos assets to Ethereum as ERC20 representations.

Documentation

High level documentation

To understand Gravity at a high level, read this blog post. It is accessible and more concise than the rest of these docs, but does not cover every detail.

Code documentation

This documentation lives with the code it references and helps to understand the functions and data structures involved. This is useful if you are reviewing or working on the code.

Solidity Ethereum contract documentation

Go Cosmos module documentation

Specs

These specs cover specific areas of the bridge that a lot of thought went into. They explore the tradeoffs involved and decisions made.

slashing-spec

batch-creation-spec

valset-creation-spec

Design docs

These are mid-level docs which go into the most detail on various topics relating to the bridge.

design overview

Bootstrapping the bridge

Minting and locking tokens in Gravity

Oracle design

Ethereum signing

Messages

Parameters

Incentives

arbitrary logic

relaying semantics

Developer Guide

To contribute to Gravity, refer to these guides.

Development environment setup

Code structure

Adding integration tests

Security hotspots

Migrations

Status

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 bridge 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.

  • Solidity Contract
    • Multiple ERC20 support
    • Tested with 100+ validators
    • Unit tests for every throw condition
    • Audit for assets originating on Ethereum
    • Support for issuing Cosmos assets on Ethereum
  • Cosmos Module
    • Basic validator set syncing
    • Basic transaction batch generation
    • Ethereum -> Cosmos Token issuing
    • Cosmos -> Ethereum Token issuing
    • Bootstrapping
    • Genesis file save/load
    • Validator set syncing edge cases
    • Slashing
    • Relaying edge cases
    • Transaction batch edge cases
    • Support for issuing Cosmos assets on Ethereum
    • Audit
  • Orchestrator / Relayer
    • Validator set update relaying
    • Ethereum -> Cosmos Oracle
    • Transaction batch relaying
    • Tendermint KMS support
    • Audit

The design of Gravity Bridge

  • Trust in the integrity of the Gravity bridge is anchored on the Cosmos side. The signing of fraudulent validator set updates and transaction batches meant for the Ethereum contract is punished by slashing on the Cosmos chain. If you trust the Cosmos chain, you can trust the Gravity bridge operated by it, as long as it is operated within certain parameters.
  • 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 design Components

  • 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.

Operational parameters ensuring security

  • There must be a validator set update made on the Ethereum contract by calling the 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.
  • Cosmos full nodes do not verify events coming from Ethereum. These events are accepted into the Cosmos state based purely on the signatures of the current validator set. It is possible for the validators with >2/3 of the stake to put events into the Cosmos state which never happened on Ethereum. In this case observers of both chains will need to "raise the alarm". We have built this functionality into the relayer.

gravity-docs's People

Contributors

activenodes avatar alfdidnothingwrong avatar alipostaci2001 avatar ardapda avatar bakon11 avatar boycesm avatar christianborst avatar dpdanpittman avatar gadost avatar goooodnes avatar humanalgorithm avatar jkilpatr avatar kkemosabe avatar lightiv avatar maxzonder avatar mchaker avatar mt2721 avatar mturkia avatar nhhtrung avatar paddyson79 avatar pngnjhnrgstr avatar ps350 avatar randomox avatar rriehle avatar shivlim avatar svv28 avatar thosmos avatar veeloup avatar voynitskiy avatar zhangmn88 avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar

gravity-docs's Issues

describe output of `gravity eth_keys add`

In the docs in this section it says to run gravity eth_keys add but doesn't describe why or the output.

An example would be helpful:

# create the Gravity Orchestrator Cosmos Key (private: in the command output
$ gravity eth_keys add

private: 0xce124acdcca17a5715aa61dfe64f5146a4a519b451134a759fe5124e89724fe3
public: 0x04f682c57545836570421227040c782fca11c546e518bc21720ade3d09c6fc3d9e8f0cd300a22189ac1737ded8dda8cdf55e5c477de9f6c131810e895837f3d522
address: 0xBb6a1d1a3737bD8d5c35224070EC22f22D861960

Are any of these the keys we need later? Is one of them the Gravity Orchestrator Cosmos Key Name that is needed in the next step? I think it's maybe the private key.

Are any of these keys important to keep private? Can someone steal my funds if they know them?

Also this command seems to create files in ~/.gravity but that's not mentioned in the documentation or the gravity eth_keys add --help

typo in orchestrator metrics

There is a typo ('r' is missing in orchestrator) in the following orchestrator metrics:

  • orchestator_information{gauge="latest_cosmos_block"} 490604
  • orchestator_warnings_count_eth{warn_message="Could not contact Eth node, trying again"} 129
  • orchestator_warnings_count_total 129

"Confirm you are validating" section inconclusive

https://github.com/Gravity-Bridge/Gravity-Docs/blob/main/docs/setting-up-a-validator.md#confirm-that-you-are-validating

Says If you see one line in the response you are validating. If you don't see any output from this command you are not validating. Check that the last command ran successfully.

But what if you see multiple lines? Like this:

$ gravity query staking validator $(gravity keys show gravity1kppuvmyff24ey4hu7mct0kzskmrttsk8payzzl --bech val --address)
Enter keyring passphrase:
commission:
  commission_rates:
    max_change_rate: "0.010000000000000000"
    max_rate: "0.200000000000000000"
    rate: "0.100000000000000000"
  update_time: "2022-01-13T15:31:53.017127196Z"
consensus_pubkey:
  '@type': /cosmos.crypto.ed25519.PubKey
  key: 4dk12mGin1oh19f1xErDfn19g+W/pmzGqrVy5uDku1I=
delegator_shares: "1.000000000000000000"
description:
  details: ""
  identity: ""
  moniker: mymoniker
  security_contact: ""
  website: ""
jailed: false
min_self_delegation: "1"
operator_address: gravityvaloper1kppuvmyff24ey4hu7mct0kzskmrttsk8skaugt
status: BOND_STATUS_UNBONDED
tokens: "1"
unbonding_height: "0"
unbonding_time: "1970-01-01T00:00:00Z"

Document parameters to 'gravity keys add'

gravity keys add <my validator key name> --recover <your seed phrase>

Where do I get <my validator key name>? Is this my wallet address for my gravity bridge tokens?

What is the <your seed phrase>? Is that the mnemonic for my wallet?

If so, this seems kind of dangerous to give this info out here. If not, where do I find this info?

<your seed phrase> isn't used on the page anywhere else. Some description of what this is and what why it matters would be helpful. Like, keep his seed phrase, you'll need it later....

What is a moniker?

In the docs it says:

gravity init mymoniker --chain-id gravity-bridge-2

What is mymoniker? Should it be unique per validator? Should it be unique globally among all validators? What if it's not unique? Will this cause a problem?

The `gravity keys add <Your Gravity Orchestrator Cosmos Key Name>` is confusing

In this section it mentions <Your Gravity Orchestrator Cosmos Key Name> but there is no indication where to get that. Might be better to say:

gravity keys add <Gravity Orchestrator Cosmos Key>
# <Gravity Orchestrator Cosmos Key> is the private key from the previous command

Drop the Your and the Name. Just say Gravity Orchestrator Cosmos Key. Also add that it's the private key generated by the previous command if that's actually true.

define params `<my validator key name>` and `<your seed phrase>`

In this section you say:

gravity keys add <my validator key name> --recover <your seed phrase>

Where do I get these parameters?

is <my validator key name> one of the 4 keys mentioned below? If so, use the same name. Where do I get the <your seed phrase>? Is that something that I used before, like the mnemonic for my wallet? Or something else?

It would be helpful to understand why this command is being run. What's it doing?

Minor issues with setting-up-a-validator.md

Trying to set up a node following https://github.com/Gravity-Bridge/Gravity-Docs/blob/main/docs/setting-up-a-validator.md

Section: Add your validator key
No information on how to create new gravity bridge wallet keys (only gives --recovery and --ledger). Isn't clear that the only command needed is:
gravity keys add

Section: View your key (optional)
gives command: gravity keys show --bech val
Would be helpful to clarify that the way to get the wallet address to transfer from Keplr is
gravity keys show

Section: Setup Gravity Bridge and Orchestrator service
Line number references do not correspond to the *.service files that are currently downloaded at
wget https://raw.githubusercontent.com/Gravity-Bridge/Gravity-Docs/main/configs/

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.