xchain

Documentation

Overview

Package xchain defines the types and interfaces used by the omni cross-chain protocol.

Index

• type Attestation
• type Block
• type BlockHeader
• type BlockTree
  • func NewBlockTree(block Block) (BlockTree, error)
  • func (t BlockTree) Proof(header BlockHeader, msgs []Msg) (merkle.MultiProof, error)
  • func (t BlockTree) Root() [32]byte
• type Msg
• type MsgID
• type Provider
• type ProviderCallback
• type Receipt
• type SigTuple
• type Signature65
• type StreamCursor
• type StreamID
• type Submission
• type Vote

Types

type Attestation

type Attestation struct {
	BlockHeader                  // BlockHeader identifies the cross-chain Block
	ValidatorSetHash common.Hash // Merkle root hash of the validator set that approved this attestation.
	BlockRoot        common.Hash // Merkle root of the cross-chain Block
	Signatures       []SigTuple  // Validator signatures and public keys
}

Attestation containing quorum votes by the validator set of a cross-chain Block.

type Block

type Block struct {
	BlockHeader
	Msgs      []Msg     // All cross-chain messages sent/emittted in the block
	Receipts  []Receipt // Receipts of all submitted cross-chain messages applied in the block
	Timestamp time.Time // Timestamp of the source chain block
}

Block is a deterministic representation of the omni cross-chain properties of a source chain EVM block.

type BlockHeader

type BlockHeader struct {
	SourceChainID uint64      // Source chain ID as per https://chainlist.org
	BlockHeight   uint64      // Height of the source chain block
	BlockHash     common.Hash // Hash of the source chain block
}

BlockHeader uniquely identifies a cross chain block.

type BlockTree

type BlockTree [][32]byte

BlockTree is a merkle tree of a cross chain block. It is attested to by the consensus chain validators. It's proofs are used to submit messages to destination chains.

func NewBlockTree

func NewBlockTree(block Block) (BlockTree, error)

NewBlockTree returns the merkle root of the provided block to be attested to.

func (BlockTree) Proof

func (t BlockTree) Proof(header BlockHeader, msgs []Msg) (merkle.MultiProof, error)

Proof returns the merkle multi proof for the provided header and messages.

func (BlockTree) Root

func (t BlockTree) Root() [32]byte

type Msg

type Msg struct {
	MsgID                          // Unique ID of the message
	SourceMsgSender common.Address // Sender on source chain, set to msg.Sender
	DestAddress     common.Address // Target/To address to "call" on destination chain
	Data            []byte         // Data to provide to "call" on destination chain
	DestGasLimit    uint64         // Gas limit to use for "call" on destination chain
	TxHash          common.Hash    // Hash of the source chain transaction that emitted the message
}

Msg is a cross-chain message.

type MsgID

type MsgID struct {
	StreamID            // Unique ID of the Stream this message belongs to
	StreamOffset uint64 // Monotonically incremented offset of Msg in the Steam
}

MsgID uniquely identifies a cross-chain message.

type Provider

type Provider interface {
	// StreamAsync starts a goroutine that streams xblocks forever from the provided source chain and height (inclusive).
	// It returns immediately. It only returns an error if the chainID in invalid.
	// This is the async version of StreamBlocks.
	// It retries forever (with backoff) on all fetch and callback errors.
	StreamAsync(ctx context.Context, chainID uint64, fromHeight uint64, callback ProviderCallback) error

	// StreamBlocks is the synchronous fail-fast version of Subscribe. It streams
	// xblocks as they become available but returns on the first callback error.
	// This is useful for workers that need to reset on application errors.
	StreamBlocks(ctx context.Context, chainID uint64, fromHeight uint64, callback ProviderCallback) error

	// GetBlock returns the block for the given chain and height, or false if not available (not finalized yet),
	// or an error.
	GetBlock(ctx context.Context, chainID uint64, height uint64) (Block, bool, error)

	// GetSubmittedCursor returns the submitted cursor for the source chain on the destination chain,
	// or false if not available, or an error. Calls the destination chain portal InXStreamOffset method.
	GetSubmittedCursor(ctx context.Context, destChainID uint64, sourceChainID uint64) (StreamCursor, bool, error)

	// GetEmittedCursor returns the emitted cursor for the destination chain on the source chain,
	// or false if not available, or an error. Calls the source chain portal OutXStreamOffset method.
	GetEmittedCursor(ctx context.Context, srcChainID uint64, destChainID uint64) (StreamCursor, bool, error)
}

Provider abstracts fetching cross chain data from any supported chain. This is basically a cross-chain data client for all supported chains.

type ProviderCallback

type ProviderCallback func(context.Context, Block) error

ProviderCallback is the callback function signature that will be called with every finalized.

type Receipt

type Receipt struct {
	MsgID                         // Unique ID of the cross chain message that was applied.
	GasUsed        uint64         // Gas used during message "call"
	Success        bool           // Result, true for success, false for revert
	RelayerAddress common.Address // Address of relayer that submitted the message
	TxHash         common.Hash    // Hash of the relayer submission transaction
}

Receipt is a cross-chain message receipt, the result of applying the Msg on the destination chain.

type SigTuple

type SigTuple struct {
	ValidatorAddress common.Address // Validator Ethereum address
	Signature        Signature65    // Validator signature over XBlockRoot; Ethereum 65 bytes [R || S || V] format.
}

SigTuple is a validator signature and address.

type Signature65

type Signature65 [65]byte

Signature65 is a 65 byte Ethereum signature [R || S || V] format.

type StreamCursor

type StreamCursor struct {
	StreamID                 // Stream ID of the Stream this cursor belongs to
	Offset            uint64 // Latest applied Msg offset of the Stream
	SourceBlockHeight uint64 // Height of the source chain block
}

StreamCursor is a cursor that tracks the progress of a cross-chain stream on destination portal contracts.

type StreamID

type StreamID struct {
	SourceChainID uint64 // Source chain ID as per https://chainlist.org/
	DestChainID   uint64 // Destination chain ID as per https://chainlist.org/
}

StreamID uniquely identifies a cross-chain stream. A stream is a logical representation of a cross-chain connection between two chains.

type Submission

type Submission struct {
	AttestationRoot  common.Hash // Merkle root of the cross-chain Block
	ValidatorSetHash common.Hash // Merkle root hash of the validator set that approved the attestation.
	BlockHeader      BlockHeader // BlockHeader identifies the cross-chain Block
	Msgs             []Msg       // Messages to be submitted
	Proof            [][32]byte  // Merkle multi proofs of the messages
	ProofFlags       []bool      // Flags indicating whether the proof is a left or right proof
	Signatures       []SigTuple  // Validator signatures and public keys
	DestChainID      uint64      // Destination chain ID, for internal use only
}

Submission is a cross-chain submission of a set of messages and their proofs.

type Vote

type Vote struct {
	BlockHeader             // BlockHeader identifies the cross-chain Block
	BlockRoot   common.Hash // Merkle root of the cross-chain Block
	Signature   SigTuple    // Validator signature and public key
}

Vote by a validator of a cross-chain Block.