xchain

package
v0.11.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 25, 2024 License: GPL-3.0 Imports: 18 Imported by: 0

Documentation

Overview

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

Index

Constants

View Source 
const (
	DSTUnknown merkle.DomainSeparationTag = 0
	DSTHeader  merkle.DomainSeparationTag = 1
	DSTMessage merkle.DomainSeparationTag = 2
)
View Source 
const (
	// ShardFinalized0 is the default finalized confirmation level shard.
	ShardFinalized0 = ShardID(ConfFinalized)

	// ShardLatest0 is the default latest confirmation level shard.
	ShardLatest0 = ShardID(ConfLatest)

	// ShardBroadcast0 is the default broadcast shard. It uses the finalized confirmation level.
	ShardBroadcast0 = ShardID(ConfFinalized) | 0x0100
)
View Source 
const BroadcastChainID uint64 = 0

BroadcastChainID is the chain ID used by broadcast messages.

Variables

View Source 
var (
	// LatestRef references the latest confirmation level.
	LatestRef = ConfRef(ConfLatest)
	// FinalizedRef references the latest confirmation level.
	FinalizedRef = ConfRef(ConfFinalized)
)

Functions

func AttestationRoot 

func AttestationRoot(attHeader AttestHeader, blockHeader BlockHeader, msgRoot common.Hash) (common.Hash, error)

AttestationRoot returns the attestation root of the provided block submissionHeader and message root.

func BindFlags 

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

BindFlags binds the xchain evm rpc flag.

func DecodeXSubmit 

func DecodeXSubmit(txCallData []byte) (bindings.XSubmission, error)

DecodeXSubmit decodes the xsubmit function call data.

func EncodeXSubmit 

func EncodeXSubmit(sub bindings.XSubmission) ([]byte, error)

EncodeXSubmit returns the abi encoding of the xsubmit function call.

func SubmissionToBinding 

func SubmissionToBinding(sub Submission) bindings.XSubmission

SubmissionToBinding converts a go xchain submission to a solidity binding submission.

Types

type AttestHeader 

type AttestHeader struct {
	ConsensusChainID uint64       // Omni consensus chain ID this attestation/vote belangs to. Used for replay-protection.
	ChainVersion     ChainVersion // ChainVersion defines a "version" of a chain being attested to ; either some fuzzy version or finalized.
	AttestOffset     uint64       // Monotonically increasing offset of this vote per chain version. 1-indexed.
}

AttestHeader uniquely identifies an attestation that require quorum vote. This is used to determine duplicate votes.

type Attestation 

type Attestation struct {
	AttestHeader               // AttestHeader uniquely identifies the attestation.
	BlockHeader                // BlockHeader identifies the cross-chain Block
	MsgRoot        common.Hash // Merkle root of all messages in the cross-chain Block
	Signatures     []SigTuple  // Validator signatures and public keys
	ValidatorSetID uint64      // Validator set that approved this attestation.
}

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

func (Attestation) AttestationRoot 

func (a Attestation) AttestationRoot() ([32]byte, error)

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
	ParentHash common.Hash // ParentHash is the hash of the parent 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) MsgByID 

func (b Block) MsgByID(msgID MsgID) (Msg, error)

func (Block) ReceiptByID 

func (b Block) ReceiptByID(msgID MsgID) (Receipt, error)

func (Block) ShouldAttest 

func (b Block) ShouldAttest(attestInterval uint64) bool

ShouldAttest returns true if the xblock should be attested by the omni consensus chain validators. All "non-empty" xblocks should be attested to. Every Nth block based on the chain's attest interval should be attested to. Attested blocks are assigned an incremented AttestOffset.

type BlockHeader 

type BlockHeader struct {
	ChainID     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 ChainVersion 

type ChainVersion struct {
	ID        uint64    // Source chain ID as per https://chainlist.org/
	ConfLevel ConfLevel // ConfLevel defines the block "version"; either some fuzzy version or finalized.
}

ChainVersion defines a version of a source chain; either some draft (fuzzy) version or finalized.

func NewChainVersion 

func NewChainVersion(chainID uint64, confLevel ConfLevel) ChainVersion

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 // unknown
	ConfLatest  ConfLevel = 1 // latest

	ConfFinalized ConfLevel = 4 // final

)

ConfLevel values MUST never change as they are persisted on-chain.

func FuzzyConfLevels 

func FuzzyConfLevels() []ConfLevel

FuzzyConfLevels returns a list of all fuzzy confirmation levels.

func (ConfLevel) IsFinalized 

func (c ConfLevel) IsFinalized() bool

IsFinalized returns true if this confirmation level is ConfFinalized.

func (ConfLevel) IsFuzzy 

func (c ConfLevel) IsFuzzy() bool

IsFuzzy returns true if this confirmation level is not ConfFinalized.

func (ConfLevel) Label 

func (c ConfLevel) Label() string

Label returns a short label for the confirmation level. IT is the uppercase first letter of the confirmation level.

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 EmitCursor 

type EmitCursor struct {
	StreamID         // Stream ID of the Stream this cursor belongs to
	MsgOffset uint64 // Latest emitted Msg offset of the Stream
}

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

type EventLogsCallback added in v0.11.0 

type EventLogsCallback func(ctx context.Context, height uint64, events []types.Log) error

type EventLogsReq added in v0.11.0 

type EventLogsReq struct {
	ChainID       uint64         // Source chain ID to query for xblocks.
	Height        uint64         // Height to query (from inclusive).
	ConfLevel     ConfLevel      // Confirmation level to ensure
	FilterAddress common.Address // Filter logs by optional address
	FilterTopics  []common.Hash  // Filters zero or more topics (in the first position only).
}

EventLogsReq is the request to fetch EVM event logs.

func (EventLogsReq) ChainVersion added in v0.11.0 

func (r EventLogsReq) ChainVersion() ChainVersion

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
	Fees            *big.Int       // Fees paid for the xcall
	LogIndex        uint64         // Evm event log index in block, used for sorting
}

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 Stream (1-indexed)
}

MsgID uniquely identifies a cross-chain message.

func (MsgID) Hash 

func (m MsgID) Hash() common.Hash

Hash returns the RouteScan cross-transaction IDHash of the MsgID.

type MsgTree 

type MsgTree struct {
	// contains filtered or unexported fields
}

MsgTree is a merkle tree of all the messages in a cross-chain block. It is used as a leaf when calculating the AttestationRoot. Its proofs are used to submit messages to destination chains.

func NewMsgTree 

func NewMsgTree(msgs []Msg) (MsgTree, error)

NewMsgTree returns the merkle root of the provided messages to be submitted.

func (MsgTree) MsgRoot 

func (t MsgTree) MsgRoot() [32]byte

func (MsgTree) Proof 

func (t MsgTree) Proof(msgs []Msg) (merkle.MultiProof, error)

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

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, req ProviderRequest, callback ProviderCallback) error

	// StreamBlocks is the synchronous fail-fast version of StreamBlocks. 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, req ProviderRequest, callback ProviderCallback) error

	// StreamEventLogs streams EVM event logs as they become available.
	//
	// The callback will be called with strictly-sequential heights with logs matching the provided filter (which may be none).
	// It returns any error encountered.
	StreamEventLogs(ctx context.Context, req EventLogsReq, callback EventLogsCallback) error

	// GetBlock returns the block for the given chain and height, or false if not available (not finalized yet),
	// or an error. The AttestOffset field is populated with the provided offset (if required).
	GetBlock(ctx context.Context, req ProviderRequest) (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, ref Ref, stream StreamID) (SubmitCursor, 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 AttestOffset field is not populated for emit cursors, since it isn't stored on-chain
	// but tracked off-chain.
	GetEmittedCursor(ctx context.Context, ref Ref, stream StreamID) (EmitCursor, bool, error)

	// ChainVersionHeight returns the height for the provided chain version.
	ChainVersionHeight(ctx context.Context, chainVer ChainVersion) (uint64, error)

	// GetSubmission returns the submission for the provided chain and tx hash, or an error.
	GetSubmission(ctx context.Context, chainID uint64, txHash common.Hash) (Submission, 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 ProviderRequest 

type ProviderRequest struct {
	ChainID   uint64    // Source chain ID to query for xblocks.
	Height    uint64    // Height to query (from inclusive).
	ConfLevel ConfLevel // Confirmation level to ensure
}

ProviderRequest is the request struct for fetching cross-chain blocks. When used in streaming context, the Height defines the starting point (inclusive).

func (ProviderRequest) ChainVersion 

func (r ProviderRequest) ChainVersion() ChainVersion

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.
	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
	LogIndex       uint64         // Evm event log index in block, used for sorting
}

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

type Ref added in v0.11.0 

type Ref struct {
	// Height specifies an absolute height to query; if non-nil.
	Height *uint64
	// ConfLevel specifies a relative-to-head block to query; if non-nil.
	ConfLevel *ConfLevel
}

Ref specifies which block to query for cursors.

func ConfRef added in v0.11.0 

func ConfRef(level ConfLevel) Ref

ConfRef returns a Ref with the provided confirmation level.

func HeightRef added in v0.11.0 

func HeightRef(height uint64) Ref

HeightRef returns a Ref with the provided confirmation level.

func (Ref) Valid added in v0.11.0 

func (r Ref) Valid() bool

type ShardID 

type ShardID uint64

func (ShardID) Broadcast 

func (s ShardID) Broadcast() bool

Broadcast returns the value of the 8th flag (least significant bit).

func (ShardID) ConfLevel 

func (s ShardID) ConfLevel() ConfLevel

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

func (ShardID) Flags 

func (s ShardID) Flags() byte

Flags returns flags encoded in the 2nd-to-last byte of the shardID.

func (ShardID) Label 

func (s ShardID) Label() string

Label returns a short label for the shard. IT is the uppercase first letter of the confirmation level.

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 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       ShardID // 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) ChainVersion 

func (s StreamID) ChainVersion() ChainVersion

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.
	AttHeader       AttestHeader // AttestHeader identifies the attestation this submission belongs to.
	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.

func SubmissionFromBinding 

func SubmissionFromBinding(sub bindings.XSubmission, destChainID uint64) (Submission, error)

type SubmitCursor 

type SubmitCursor struct {
	StreamID            // Stream ID of the Stream this cursor belongs to
	MsgOffset    uint64 // Latest submitted Msg offset of the Stream
	AttestOffset uint64 // Latest submitted cross chain attest offset
}

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

type Vote 

type Vote struct {
	AttestHeader             // AttestHeader identifies the attestation this vote should be included in.
	BlockHeader              // BlockHeader identifies the cross-chain Block being voted for.
	MsgRoot      common.Hash // Merkle root of all messages in the cross-chain Block
	Signature    SigTuple    // Validator signature and public key
}

Vote by a validator for a cross-chain Block.

Source Files

View all Source files

Directories

Path Synopsis
Package provider is the implementation of the Provider interface.
 Package provider is the implementation of the Provider interface.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.