package gravity.v1

Get desktop application:
View/edit binary Protocol Buffers messages

Msg defines the state transitions possible within gravity

• rpc ValsetConfirm (MsgValsetConfirm, MsgValsetConfirmResponse)

  msgs.proto:12

  message MsgValsetConfirmResponse

  msgs.proto:98

  (message has no fields)

• rpc SendToEth (MsgSendToEth, MsgSendToEthResponse)

  msgs.proto:15

  message MsgSendToEth

  msgs.proto:112

  MsgSendToEth This is the message that a user calls when they want to bridge an asset it will later be removed when it is included in a batch and successfully submitted tokens are removed from the users balance immediately ------------- AMOUNT: the coin to send across the bridge, note the restriction that this is a single coin not a set of coins that is normal in other Cosmos messages FEE: the fee paid for the bridge, distinct from the fee paid to the chain to actually send this message in the first place. So a successful send has two layers of fees for the user

  • string sender = 1

  • string eth_dest = 2

  • optional cosmos.base.v1beta1.Coin amount = 3

  • optional cosmos.base.v1beta1.Coin bridge_fee = 4

  message MsgSendToEthResponse

  msgs.proto:123

  (message has no fields)

• rpc RequestBatch (MsgRequestBatch, MsgRequestBatchResponse)

  msgs.proto:18

  message MsgRequestBatch

  msgs.proto:134

  MsgRequestBatch this is a message anyone can send that requests a batch of transactions to send across the bridge be created for whatever block height this message is included in. This acts as a coordination point, the handler for this message looks at the AddToOutgoingPool tx's in the store and generates a batch, also available in the store tied to this message. The validators then grab this batch, sign it, submit the signatures with a MsgConfirmBatch before a relayer can finally submit the batch -------------

  • string sender = 1

  • string denom = 2

  message MsgRequestBatchResponse

  msgs.proto:139

  (message has no fields)

• rpc ConfirmBatch (MsgConfirmBatch, MsgConfirmBatchResponse)

  msgs.proto:21

  message MsgConfirmBatchResponse

  msgs.proto:157

  (message has no fields)

• rpc ConfirmLogicCall (MsgConfirmLogicCall, MsgConfirmLogicCallResponse)

  msgs.proto:24

  message MsgConfirmLogicCallResponse

  msgs.proto:175

  (message has no fields)

• rpc SendToCosmosClaim (MsgSendToCosmosClaim, MsgSendToCosmosClaimResponse)

  msgs.proto:27

  message MsgSendToCosmosClaim

  msgs.proto:182

  MsgSendToCosmosClaim When more than 66% of the active validator set has claimed to have seen the deposit enter the ethereum blockchain coins are issued to the Cosmos address in question -------------

  • uint64 event_nonce = 1

  • uint64 block_height = 2

  • string token_contract = 3

  • string amount = 4

  • string ethereum_sender = 5

  • string cosmos_receiver = 6

  • string orchestrator = 7

  message MsgSendToCosmosClaimResponse

  msgs.proto:195

  (message has no fields)

• rpc BatchSendToEthClaim (MsgBatchSendToEthClaim, MsgBatchSendToEthClaimResponse)

  msgs.proto:30

  message MsgBatchSendToEthClaim

  msgs.proto:199

  BatchSendToEthClaim claims that a batch of send to eth operations on the bridge contract was executed.

  • uint64 event_nonce = 1

  • uint64 block_height = 2

  • uint64 batch_nonce = 3

  • string token_contract = 4

  • string orchestrator = 5

  message MsgBatchSendToEthClaimResponse

  msgs.proto:207

  (message has no fields)

• rpc ValsetUpdateClaim (MsgValsetUpdatedClaim, MsgValsetUpdatedClaimResponse)

  msgs.proto:33

  message MsgValsetUpdatedClaim

  msgs.proto:239

  This informs the Cosmos module that a validator set has been updated.

  • uint64 event_nonce = 1

  • uint64 valset_nonce = 2

  • uint64 block_height = 3

  • repeated BridgeValidator members = 4

  • string reward_amount = 5

  • string reward_token = 6

  • string orchestrator = 7

  message MsgValsetUpdatedClaimResponse

  msgs.proto:252

  (message has no fields)

• rpc ERC20DeployedClaim (MsgERC20DeployedClaim, MsgERC20DeployedClaimResponse)

  msgs.proto:36

  message MsgERC20DeployedClaim

  msgs.proto:212

  ERC20DeployedClaim allows the Cosmos module to learn about an ERC20 that someone deployed to represent a Cosmos asset

  • uint64 event_nonce = 1

  • uint64 block_height = 2

  • string cosmos_denom = 3

  • string token_contract = 4

  • string name = 5

  • string symbol = 6

  • uint64 decimals = 7

  • string orchestrator = 8

  message MsgERC20DeployedClaimResponse

  msgs.proto:223

  (message has no fields)

• rpc LogicCallExecutedClaim (MsgLogicCallExecutedClaim, MsgLogicCallExecutedClaimResponse)

  msgs.proto:40

  message MsgLogicCallExecutedClaim

  msgs.proto:227

  This informs the Cosmos module that a logic call has been executed

  • uint64 event_nonce = 1

  • uint64 block_height = 2

  • bytes invalidation_id = 3

  • uint64 invalidation_nonce = 4

  • string orchestrator = 5

  message MsgLogicCallExecutedClaimResponse

  msgs.proto:235

  (message has no fields)

• rpc SetOrchestratorAddress (MsgSetOrchestratorAddress, MsgSetOrchestratorAddressResponse)

  msgs.proto:44

  message MsgSetOrchestratorAddressResponse

  msgs.proto:74

  (message has no fields)

• rpc CancelSendToEth (MsgCancelSendToEth, MsgCancelSendToEthResponse)

  msgs.proto:47

  message MsgCancelSendToEth

  msgs.proto:257

  This call allows the sender (and only the sender) to cancel a given MsgSendToEth and recieve a refund of the tokens

  • uint64 transaction_id = 1

  • string sender = 2

  message MsgCancelSendToEthResponse

  msgs.proto:262

  (message has no fields)

• rpc SubmitBadSignatureEvidence (MsgSubmitBadSignatureEvidence, MsgSubmitBadSignatureEvidenceResponse)

  msgs.proto:50

  message MsgSubmitBadSignatureEvidence

  msgs.proto:267

  This call allows anyone to submit evidence that a validator has signed a valset, batch, or logic call that never existed. Subject contains the batch, valset, or logic call.

  • optional google.protobuf.Any subject = 1

  • string signature = 2

  • string sender = 3

  message MsgSubmitBadSignatureEvidenceResponse

  msgs.proto:273

  (message has no fields)

Query defines the gRPC querier service

• rpc Params (QueryParamsRequest, QueryParamsResponse)

  query.proto:17

  Deployments queries deployments

  message QueryParamsRequest

  query.proto:88

  (message has no fields)

  message QueryParamsResponse

  query.proto:89

  • optional Params params = 1

• rpc CurrentValset (QueryCurrentValsetRequest, QueryCurrentValsetResponse)

  query.proto:20

  message QueryCurrentValsetRequest

  query.proto:93

  (message has no fields)

  message QueryCurrentValsetResponse

  query.proto:94

  • optional Valset valset = 1

• rpc ValsetRequest (QueryValsetRequestRequest, QueryValsetRequestResponse)

  query.proto:23

  message QueryValsetRequestRequest

  query.proto:98

  • uint64 nonce = 1

  message QueryValsetRequestResponse

  query.proto:101

  • optional Valset valset = 1

• rpc ValsetConfirm (QueryValsetConfirmRequest, QueryValsetConfirmResponse)

  query.proto:26

  message QueryValsetConfirmRequest

  query.proto:105

  • uint64 nonce = 1

  • string address = 2

  message QueryValsetConfirmResponse

  query.proto:109

  • optional MsgValsetConfirm confirm = 1

• rpc ValsetConfirmsByNonce (QueryValsetConfirmsByNonceRequest, QueryValsetConfirmsByNonceResponse)

  query.proto:29

  message QueryValsetConfirmsByNonceRequest

  query.proto:113

  • uint64 nonce = 1

  message QueryValsetConfirmsByNonceResponse

  query.proto:116

  • repeated MsgValsetConfirm confirms = 1

• rpc LastValsetRequests (QueryLastValsetRequestsRequest, QueryLastValsetRequestsResponse)

  query.proto:32

  message QueryLastValsetRequestsRequest

  query.proto:120

  (message has no fields)

  message QueryLastValsetRequestsResponse

  query.proto:121

  • repeated Valset valsets = 1

• rpc LastPendingValsetRequestByAddr (QueryLastPendingValsetRequestByAddrRequest, QueryLastPendingValsetRequestByAddrResponse)

  query.proto:35

  message QueryLastPendingValsetRequestByAddrRequest

  query.proto:125

  • string address = 1

  message QueryLastPendingValsetRequestByAddrResponse

  query.proto:128

  • repeated Valset valsets = 1

• rpc LastPendingBatchRequestByAddr (QueryLastPendingBatchRequestByAddrRequest, QueryLastPendingBatchRequestByAddrResponse)

  query.proto:38

  message QueryLastPendingBatchRequestByAddrRequest

  query.proto:137

  • string address = 1

  message QueryLastPendingBatchRequestByAddrResponse

  query.proto:140

  • optional OutgoingTxBatch batch = 1

• rpc LastPendingLogicCallByAddr (QueryLastPendingLogicCallByAddrRequest, QueryLastPendingLogicCallByAddrResponse)

  query.proto:41

  message QueryLastPendingLogicCallByAddrRequest

  query.proto:144

  • string address = 1

  message QueryLastPendingLogicCallByAddrResponse

  query.proto:147

  • optional OutgoingLogicCall call = 1

• rpc LastEventNonceByAddr (QueryLastEventNonceByAddrRequest, QueryLastEventNonceByAddrResponse)

  query.proto:44

  message QueryLastEventNonceByAddrRequest

  query.proto:185

  • string address = 1

  message QueryLastEventNonceByAddrResponse

  query.proto:188

  • uint64 event_nonce = 1

• rpc BatchFees (QueryBatchFeeRequest, QueryBatchFeeResponse)

  query.proto:47

  message QueryBatchFeeRequest

  query.proto:132

  (message has no fields)

  message QueryBatchFeeResponse

  query.proto:133

  • repeated BatchFees batch_fees = 1

• rpc OutgoingTxBatches (QueryOutgoingTxBatchesRequest, QueryOutgoingTxBatchesResponse)

  query.proto:51

  message QueryOutgoingTxBatchesRequest

  query.proto:151

  (message has no fields)

  message QueryOutgoingTxBatchesResponse

  query.proto:152

  • repeated OutgoingTxBatch batches = 1

• rpc OutgoingLogicCalls (QueryOutgoingLogicCallsRequest, QueryOutgoingLogicCallsResponse)

  query.proto:54

  message QueryOutgoingLogicCallsRequest

  query.proto:156

  (message has no fields)

  message QueryOutgoingLogicCallsResponse

  query.proto:157

  • repeated OutgoingLogicCall calls = 1

• rpc BatchRequestByNonce (QueryBatchRequestByNonceRequest, QueryBatchRequestByNonceResponse)

  query.proto:57

  message QueryBatchRequestByNonceRequest

  query.proto:161

  • uint64 nonce = 1

  • string contract_address = 2

  message QueryBatchRequestByNonceResponse

  query.proto:165

  • optional OutgoingTxBatch batch = 1

• rpc BatchConfirms (QueryBatchConfirmsRequest, QueryBatchConfirmsResponse)

  query.proto:60

  message QueryBatchConfirmsRequest

  query.proto:169

  • uint64 nonce = 1

  • string contract_address = 2

  message QueryBatchConfirmsResponse

  query.proto:173

  • repeated MsgConfirmBatch confirms = 1

• rpc LogicConfirms (QueryLogicConfirmsRequest, QueryLogicConfirmsResponse)

  query.proto:63

  message QueryLogicConfirmsRequest

  query.proto:177

  • bytes invalidation_id = 1

  • uint64 invalidation_nonce = 2

  message QueryLogicConfirmsResponse

  query.proto:181

  • repeated MsgConfirmLogicCall confirms = 1

• rpc ERC20ToDenom (QueryERC20ToDenomRequest, QueryERC20ToDenomResponse)

  query.proto:66

  message QueryERC20ToDenomRequest

  query.proto:192

  • string erc20 = 1

  message QueryERC20ToDenomResponse

  query.proto:195

  • string denom = 1

  • bool cosmos_originated = 2

• rpc DenomToERC20 (QueryDenomToERC20Request, QueryDenomToERC20Response)

  query.proto:69

  message QueryDenomToERC20Request

  query.proto:200

  • string denom = 1

  message QueryDenomToERC20Response

  query.proto:203

  • string erc20 = 1

  • bool cosmos_originated = 2

• rpc GetDelegateKeyByValidator (QueryDelegateKeysByValidatorAddress, QueryDelegateKeysByValidatorAddressResponse)

  query.proto:73

  message QueryDelegateKeysByValidatorAddress

  query.proto:208

  • string validator_address = 1

  message QueryDelegateKeysByValidatorAddressResponse

  query.proto:211

  • string eth_address = 1

  • string orchestrator_address = 2

• rpc GetDelegateKeyByEth (QueryDelegateKeysByEthAddress, QueryDelegateKeysByEthAddressResponse)

  query.proto:76

  message QueryDelegateKeysByEthAddress

  query.proto:216

  • string eth_address = 1

  message QueryDelegateKeysByEthAddressResponse

  query.proto:219

  • string validator_address = 1

  • string orchestrator_address = 2

• rpc GetDelegateKeyByOrchestrator (QueryDelegateKeysByOrchestratorAddress, QueryDelegateKeysByOrchestratorAddressResponse)

  query.proto:79

  message QueryDelegateKeysByOrchestratorAddress

  query.proto:224

  • string orchestrator_address = 1

  message QueryDelegateKeysByOrchestratorAddressResponse

  query.proto:227

  • string validator_address = 1

  • string eth_address = 2

• rpc GetPendingSendToEth (QueryPendingSendToEth, QueryPendingSendToEthResponse)

  query.proto:83

  message QueryPendingSendToEth

  query.proto:232

  • string sender_address = 1

  message QueryPendingSendToEthResponse

  query.proto:235

  • repeated OutgoingTransferTx transfers_in_batches = 1

  • repeated OutgoingTransferTx unbatched_transfers = 2

Attestation is an aggregate of `claims` that eventually becomes `observed` by all orchestrators EVENT_NONCE: EventNonce a nonce provided by the gravity contract that is unique per event fired These event nonces must be relayed in order. This is a correctness issue, if relaying out of order transaction replay attacks become possible OBSERVED: Observed indicates that >67% of validators have attested to the event, and that the event should be executed by the gravity state machine The actual content of the claims is passed in with the transaction making the claim and then passed through the call stack alongside the attestation while it is processed the key in which the attestation is stored is keyed on the exact details of the claim but there is no reason to store those exact details becuause the next message sender will kindly provide you with them.

Used in: GenesisState

• bool observed = 1

• repeated string votes = 2

• uint64 height = 3

• optional google.protobuf.Any claim = 4

Used in: QueryBatchFeeResponse

• string token = 1

• string total_fees = 2

BridgeValidator represents a validator's ETH address and its power

Used in: MsgValsetUpdatedClaim, Valset

• uint64 power = 1

• string ethereum_address = 2

• CLAIM_TYPE_UNSPECIFIED = 0

• CLAIM_TYPE_SEND_TO_COSMOS = 1

• CLAIM_TYPE_BATCH_SEND_TO_ETH = 2

• CLAIM_TYPE_ERC20_DEPLOYED = 3

• CLAIM_TYPE_LOGIC_CALL_EXECUTED = 4

• CLAIM_TYPE_VALSET_UPDATED = 5

This records the relationship between an ERC20 token and the denom of the corresponding Cosmos originated asset

Used in: GenesisState

• string erc20 = 1

• string denom = 2

ERC20Token unique identifier for an Ethereum ERC20 token. CONTRACT: The contract address on ETH of the token, this could be a Cosmos originated token, if so it will be the ERC20 address of the representation (note: developers should look up the token symbol using the address on ETH to display for UI)

Used in: OutgoingLogicCall, OutgoingTransferTx

• string contract = 1

• string amount = 2

GenesisState struct

• optional Params params = 1

• uint64 last_observed_nonce = 2

• repeated Valset valsets = 3

• repeated MsgValsetConfirm valset_confirms = 4

• repeated OutgoingTxBatch batches = 5

• repeated MsgConfirmBatch batch_confirms = 6

• repeated OutgoingLogicCall logic_calls = 7

• repeated MsgConfirmLogicCall logic_call_confirms = 8

• repeated Attestation attestations = 9

• repeated MsgSetOrchestratorAddress delegate_keys = 10

• repeated ERC20ToDenom erc20_to_denoms = 11

• repeated OutgoingTransferTx unbatched_transfers = 12

IDSet represents a set of IDs

• repeated uint64 ids = 1

LastObservedEthereumBlockHeight stores the last observed Ethereum block height along with the Cosmos block height that it was observed at. These two numbers can be used to project outward and always produce batches with timeouts in the future even if no Ethereum block height has been relayed for a long time

• uint64 cosmos_block_height = 1

• uint64 ethereum_block_height = 2

MsgConfirmBatch When validators observe a MsgRequestBatch they form a batch by ordering transactions currently in the txqueue in order of highest to lowest fee, cutting off when the batch either reaches a hardcoded maximum size (to be decided, probably around 100) or when transactions stop being profitable (TODO determine this without nondeterminism) This message includes the batch as well as an Ethereum signature over this batch by the validator -------------

Used as request type in: Msg.ConfirmBatch

Used as field type in: GenesisState, QueryBatchConfirmsResponse

• uint64 nonce = 1

• string token_contract = 2

• string eth_signer = 3

• string orchestrator = 4

• string signature = 5

MsgConfirmLogicCall When validators observe a MsgRequestBatch they form a batch by ordering transactions currently in the txqueue in order of highest to lowest fee, cutting off when the batch either reaches a hardcoded maximum size (to be decided, probably around 100) or when transactions stop being profitable (TODO determine this without nondeterminism) This message includes the batch as well as an Ethereum signature over this batch by the validator -------------

Used as request type in: Msg.ConfirmLogicCall

Used as field type in: GenesisState, QueryLogicConfirmsResponse

• string invalidation_id = 1

• uint64 invalidation_nonce = 2

• string eth_signer = 3

• string orchestrator = 4

• string signature = 5

MsgSetOrchestratorAddress this message allows validators to delegate their voting responsibilities to a given key. This key is then used as an optional authentication method for sigining oracle claims VALIDATOR The validator field is a cosmosvaloper1... string (i.e. sdk.ValAddress) that references a validator in the active set ORCHESTRATOR The orchestrator field is a cosmos1... string (i.e. sdk.AccAddress) that references the key that is being delegated to ETH_ADDRESS This is a hex encoded 0x Ethereum public key that will be used by this validator on Ethereum

Used as request type in: Msg.SetOrchestratorAddress

Used as field type in: GenesisState

• string validator = 1

• string orchestrator = 2

• string eth_address = 3

MsgValsetConfirm this is the message sent by the validators when they wish to submit their signatures over the validator set at a given block height. A validator must first call MsgSetEthAddress to set their Ethereum address to be used for signing. Then someone (anyone) must make a ValsetRequest, the request is essentially a messaging mechanism to determine which block all validators should submit signatures over. Finally validators sign the validator set, powers, and Ethereum addresses of the entire validator set at the height of a ValsetRequest and submit that signature with this message. If a sufficient number of validators (66% of voting power) (A) have set Ethereum addresses and (B) submit ValsetConfirm messages with their signatures it is then possible for anyone to view these signatures in the chain store and submit them to Ethereum to update the validator set -------------

Used as request type in: Msg.ValsetConfirm

Used as field type in: GenesisState, QueryValsetConfirmResponse, QueryValsetConfirmsByNonceResponse

• uint64 nonce = 1

• string orchestrator = 2

• string eth_address = 3

• string signature = 4

OutgoingLogicCall represents an individual logic call from gravity to ETH

Used in: GenesisState, QueryLastPendingLogicCallByAddrResponse, QueryOutgoingLogicCallsResponse

• repeated ERC20Token transfers = 1

• repeated ERC20Token fees = 2

• string logic_contract_address = 3

• bytes payload = 4

• uint64 timeout = 5

• bytes invalidation_id = 6

• uint64 invalidation_nonce = 7

• uint64 block = 8

OutgoingTransferTx represents an individual send from gravity to ETH

Used in: GenesisState, OutgoingTxBatch, QueryPendingSendToEthResponse

• uint64 id = 1

• string sender = 2

• string dest_address = 3

• optional ERC20Token erc20_token = 4

• optional ERC20Token erc20_fee = 5

OutgoingTxBatch represents a batch of transactions going from gravity to ETH

Used in: GenesisState, QueryBatchRequestByNonceResponse, QueryLastPendingBatchRequestByAddrResponse, QueryOutgoingTxBatchesResponse

• uint64 batch_nonce = 1

• uint64 batch_timeout = 2

• repeated OutgoingTransferTx transactions = 3

• string token_contract = 4

• uint64 block = 5

The slashing fractions for the various gravity related slashing conditions. The first three refer to not submitting a particular message, the third for submitting a different claim for the same Ethereum event unbond_slashing_valsets_window The unbond slashing valsets window is used to determine how many blocks after starting to unbond a validator needs to continue signing blocks. The goal of this paramater is that when a validator leaves the set, if their leaving creates enough change in the validator set to justify an update they will sign a validator set update for the Ethereum bridge that does not include themselves. Allowing us to remove them from the Ethereum bridge and replace them with the new set gracefully. valset_reward Valset rewards are the amount of tokens this chain issues to relayers of validator sets. These can be any ERC20 token in the bridge, but it's strongly advised that chains use only Cosmos originated tokens, which the bridge effectively mints on Ethereum. If you run out of the token you are using for validator set rewards valset updates will fail and the bridge will be vulnerable to highjacking. For these paramaters the zero values are special and indicate not to attempt any reward. This is the default for bootstrapping.

Used in: GenesisState, QueryParamsResponse

• string gravity_id = 1

• string contract_source_hash = 2

• string bridge_ethereum_address = 4

• uint64 bridge_chain_id = 5

• uint64 signed_valsets_window = 6

• uint64 signed_batches_window = 7

• uint64 signed_logic_calls_window = 8

• uint64 target_batch_timeout = 9

• uint64 average_block_time = 10

• uint64 average_ethereum_block_time = 11

• bytes slash_fraction_valset = 12

• bytes slash_fraction_batch = 13

• bytes slash_fraction_logic_call = 14

• uint64 unbond_slashing_valsets_window = 15

• bytes slash_fraction_bad_eth_signature = 16

• optional cosmos.base.v1beta1.Coin valset_reward = 17

SignType defines messages that have been signed by an orchestrator

• SIGN_TYPE_UNSPECIFIED = 0

• SIGN_TYPE_ORCHESTRATOR_SIGNED_MULTI_SIG_UPDATE = 1

• SIGN_TYPE_ORCHESTRATOR_SIGNED_WITHDRAW_BATCH = 2

Valset is the Ethereum Bridge Multsig Set, each gravity validator also maintains an ETH key to sign messages, these are used to check signatures on ETH because of the significant gas savings

Used in: GenesisState, QueryCurrentValsetResponse, QueryLastPendingValsetRequestByAddrResponse, QueryLastValsetRequestsResponse, QueryValsetRequestResponse

• uint64 nonce = 1

• repeated BridgeValidator members = 2

• uint64 height = 3

• string reward_amount = 4

• string reward_token = 5

  the reward token in it's Ethereum hex address representation