xchain

Documentation

Overview

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

Index

• func BindFlags(flags *pflag.FlagSet, endpoints *RPCEndpoints)
• type Attestation
• type Block
  • func (b Block) ShouldAttest() bool
• 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 ConfLevel
  • func ConfFromShard(shardID uint64) ConfLevel
  • func (c ConfLevel) IsFuzzy() bool
  • func (i ConfLevel) String() string
  • func (c ConfLevel) Valid() bool
• type EmitRef
• type Msg
• type MsgID
• type Provider
• type ProviderCallback
• type RPCEndpoints
  • func (e RPCEndpoints) ByNameOrID(name string, chainID uint64) (string, error)
  • func (e RPCEndpoints) Keys() []string
• type Receipt
• type SigTuple
• type Signature65
• type StreamCursor
• type StreamID
  • func (s StreamID) ConfLevel() ConfLevel
• type Submission
• type Vote

Functions

func BindFlags

func BindFlags(flags *pflag.FlagSet, endpoints *RPCEndpoints)

BindFlags binds the xchain evm rpc flag.

Types

type Attestation

type Attestation struct {
	BlockHeader                 // BlockHeader identifies the cross-chain Block
	ValidatorSetID  uint64      // Validator set that approved this attestation.
	AttestationRoot common.Hash // Attestation 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.

func (Block) ShouldAttest

func (b Block) ShouldAttest() bool

ShouldAttest returns true if the xblock should be attested by the omni consensus chain validators. All "non-empty" xblocks should be attested to and are assigned an incremented XBlockOffset.

type BlockHeader

type BlockHeader struct {
	SourceChainID uint64      // Source chain ID as per https://chainlist.org
	ConfLevel     ConfLevel   // ConfLevel defines the cross-chain block "version"; either some fuzzy version or finalized.
	BlockOffset   uint64      // MsgOffset of the cross-chain block
	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 ConfLevel

type ConfLevel byte

ConfLevel defines a xblock confirmation level. This is similar to a "version"; with ConfFinalized being the final version and fuzzy conf levels being drafts.

const (
	ConfUnknown   ConfLevel = 0
	ConfLatest    ConfLevel = 1
	ConfFast      ConfLevel = 2
	ConfSafe      ConfLevel = 3
	ConfFinalized ConfLevel = 4
)

func ConfFromShard

func ConfFromShard(shardID uint64) ConfLevel

ConfFromShard returns confirmation level encoded in the last 8 bits of the shardID.

func (ConfLevel) IsFuzzy

func (c ConfLevel) IsFuzzy() bool

IsFuzzy returns true if this confirmation level is not ConfFinalized.

func (ConfLevel) String

func (i ConfLevel) String() string

func (ConfLevel) Valid

func (c ConfLevel) Valid() bool

Valid returns true if this confirmation level is valid.

type EmitRef

type EmitRef struct {
	Height    *uint64
	ConfLevel *ConfLevel
}

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, fromOffset uint64, callback ProviderCallback) error

	// StreamAsyncNoOffset is the same as StreamAsync except that XBlockOffset is not populated in the returned XBlocks.
	StreamAsyncNoOffset(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, fromOffset uint64, callback ProviderCallback) error

	// StreamBlocksNoOffset is the same as StreamBlocks except that XBlockOffset is not populated in the returned XBlocks.
	StreamBlocksNoOffset(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. The XBlockOffset field is populated with the provided offset (if required).
	GetBlock(ctx context.Context, chainID uint64, height uint64, xOffset uint64) (Block, bool, error)

	// GetSubmittedCursor returns the submitted cursor for the provided stream,
	// or false if not available, or an error.
	// Calls the destination chain portal InXStreamOffset method.
	// Note this is only supported for EVM chains, no the consensus chain.
	GetSubmittedCursor(ctx context.Context, stream StreamID) (StreamCursor, bool, error)

	// GetEmittedCursor returns the emitted cursor for the provided stream,
	// or false if not available, or an error.
	// Calls the source chain portal OutXStreamOffset method.
	//
	// Note that the BlockOffset field is not populated for emit cursors, since it isn't stored on-chain
	// but tracked off-chain.
	GetEmittedCursor(ctx context.Context, ref EmitRef, stream StreamID) (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 RPCEndpoints

type RPCEndpoints map[string]string

func (RPCEndpoints) ByNameOrID

func (e RPCEndpoints) ByNameOrID(name string, chainID uint64) (string, error)

func (RPCEndpoints) Keys

func (e RPCEndpoints) Keys() []string

type Receipt

type Receipt struct {
	MsgID                         // Unique ID of the cross chain message that was applied.
	ConfLevel      ConfLevel      // Confirmation level of submitted attestation
	GasUsed        uint64         // Gas used during message "call"
	Success        bool           // Result, true for success, false for revert
	Error          []byte         // Error message if the message failed
	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
	MsgOffset   uint64 // Latest applied Msg offset of the Stream
	BlockOffset uint64 // Latest applied cross chain block offset
}

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/
	ShardID       uint64 // ShardID identifies a sequence of xmsgs (and maps to ConfLevel).
}

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

func (StreamID) ConfLevel

func (s StreamID) ConfLevel() ConfLevel

type Submission

type Submission struct {
	AttestationRoot common.Hash // Attestation merkle root of the cross-chain Block
	ValidatorSetID  uint64      // 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
	AttestationRoot common.Hash // Attestation merkle root of the cross-chain Block
	Signature       SigTuple    // Validator signature and public key
}

Vote by a validator of a cross-chain Block.