Skip to main content

Messages

This is a reference document for Peggy message types. For code reference and exact arguments see the proto definitions.

User messages​

These are messages sent on the Injective Chain peggy module. See workflow for a more detailed summary of the entire deposit and withdraw process.

SendToEth​


// 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 Injective 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
type MsgSendToEth struct {
    Sender    string     
    EthDest   string     
    Amount    types.Coin 
    BridgeFee types.Coin 
}

SendToEth allows the user to specify an Ethereum destination, a token to send to Ethereum and a fee denominated in that same token to pay the relayer. Note that this transaction will contain two fees. One fee amount to submit to the Injective Chain, that can be paid in any token and one fee amount for the Ethereum relayer that must be paid in the same token that is being bridged.

CancelSendToEth​

// This call allows the sender (and only the sender)
// to cancel a given MsgSendToEth and receive a refund
// of the tokens
type MsgCancelSendToEth struct {
    TransactionId uint64 
    Sender        string 
}

CancelSendToEth allows a user to retrieve a transaction that is in the batch pool but has not yet been packaged into a transaction batch by a relayer running RequestBatch.

SubmitBadSignatureEvidence​

// This call allows anyone to submit evidence that a
// validator has signed a valset or batch that never
// existed. Subject contains the batch or valset.
type MsgSubmitBadSignatureEvidence struct {
    Subject   *types1.Any 
    Signature string      
    Sender    string      
}

SubmitBadSignatureEvidence allows anyone to submit evidence that a validator has signed a valset or batch that never existed.

Relayer Messages​

These are messages run by relayers. Relayers are unpermissioned and simply work to move things from the Injective Chain to Ethereum.

RequestBatch​

// 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
// -------------
type MsgRequestBatch struct {
    Orchestrator string 
    Denom        string
}

Relayers use QueryPendingSendToEth in query.proto to query the potential fees for a batch of each token type. When they find a batch that they wish to relay they send in a RequestBatch message and the Peggy module creates a batch.

This then triggers the Ethereum Signers to send in ConfirmBatch messages, which the signatures required to submit the batch to the Ethereum chain.

At this point any relayer can package these signatures up into a transaction and send them to Ethereum.

As noted above this message is unpermissioned and it is safe to allow anyone to call this message at any time.

Oracle Messages​

All validators run two processes in addition to their Injective node. An Ethereum oracle and Ethereum signer, these are bundled into a single Orchestrator binary for ease of use.

The oracle observes the Ethereum chain for events from the Peggy.sol contract before submitting them as messages to the Injective Chain.

DepositClaim​


// EthereumBridgeDepositClaim
// 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 Injective address in question
// -------------
type MsgDepositClaim struct {
    EventNonce     uint64                                
    BlockHeight    uint64                                
    TokenContract  string                                
    Amount         sdkmath.Int 
    EthereumSender string                                 
    CosmosReceiver string                                 
    Orchestrator   string                                 
}

Deposit claims represent a SendToCosmosEvent emitted by the Peggy contract. After 2/3 of the validators confirm a deposit claim, the representative tokens will be issued to the specified CosmosReceiver Injective Chain account.

WithdrawClaim​

// WithdrawClaim claims that a batch of withdrawal
// operations on the bridge contract was executed.
type MsgWithdrawClaim struct {
    EventNonce    uint64 
    BlockHeight   uint64 
    BatchNonce    uint64 
    TokenContract string 
    Orchestrator  string 
}

Withdraw claims represent a TransactionBatchExecutedEvent from the Peggy contract. When this passes the oracle vote the batch in state is cleaned up and tokens are burned/locked.

ValsetUpdateClaim​


// This informs the peggy module that a validator
// set has been updated.
type MsgValsetUpdatedClaim struct {
    EventNonce   uint64                           
    ValsetNonce  uint64                           
    BlockHeight  uint64                           
    Members      []*BridgeValidator               
    RewardAmount sdkmath.Int 
    RewardToken  string                                 
    Orchestrator string                                 
}

claim representing a ValsetUpdatedEvent from the Peggy contract. When this passes the oracle vote reward amounts are tallied and minted.

ERC20DeployedClaim​


// ERC20DeployedClaim allows the peggy module
// to learn about an ERC-20 that someone deployed
// to represent a Cosmos asset
type MsgERC20DeployedClaim struct {
    EventNonce    uint64 
    BlockHeight   uint64 
    CosmosDenom   string 
    TokenContract string 
    Name          string 
    Symbol        string 
    Decimals      uint64 
    Orchestrator  string 
}

claim representing a ERC20DeployedEvent from the Peggy contract. When this passes the oracle vote it is checked for accuracy and adopted or rejected as the ERC-20 representation of a Cosmos SDK based asset.

Ethereum Signer Messages​

All validators run two processes in addition to their Injective Chain node. An Ethereum oracle and Ethereum signer, these are bundled into a single Orchestrator binary for ease of use.

The Ethereum signer watches several query endpoints and it's only job is to submit a signature for anything that appears on those endpoints. For this reason the validator must provide a secure RPC to an Injective Chain node following chain consensus. Or they risk being tricked into signing the wrong thing.

ConfirmBatch​


// 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
// This message includes the batch as well as an Ethereum signature over this batch by the validator
// -------------
type MsgConfirmBatch struct {
    Nonce         uint64 
    TokenContract string 
    EthSigner     string 
    Orchestrator  string 
    Signature     string 
}

Submits an Ethereum signature over a batch appearing in the LastPendingBatchRequestByAddr query.

ValsetConfirm​


// 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.
type MsgValsetConfirm struct {
    Nonce        uint64 
    Orchestrator string 
    EthAddress   string 
    Signature    string 
}

Submits an Ethereum signature over a batch appearing in the LastPendingValsetRequestByAddr query.

Validator Messages​

These are messages sent directly using the validator's message key.

SetOrchestratorAddresses​


// MsgSetOrchestratorAddresses
// 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 injvaloper1... string (i.e. sdk.ValAddress)
// that references a validator in the active set
// ORCHESTRATOR
// The orchestrator field is a inj1... 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
type MsgSetOrchestratorAddresses struct {
    Sender       string
    Orchestrator string
    EthAddress   string
}

This message sets the Orchestrator's delegate keys.