xchain

package
v0.1.10 Latest Latest
Warning

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

 Go to latest Published: Jun 19, 2024 License: GPL-3.0 Imports: 9 Imported by: 0

Documentation

Overview

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

Index

Constants

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

This section is empty.

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
	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) 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 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      // Offset 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.

func (BlockHeader) ChainVersion added in v0.1.9 

func (b BlockHeader) ChainVersion() ChainVersion

type BlockTree added in v0.1.0 

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 added in v0.1.0 

func NewBlockTree(block Block) (BlockTree, error)

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

func (BlockTree) Proof added in v0.1.0 

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 added in v0.1.0 

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

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.

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
	ConfFast      ConfLevel = 2 // fast
	ConfSafe      ConfLevel = 3 // safe
	ConfFinalized ConfLevel = 4 // final

)

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

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 EmitRef 

type EmitRef struct {
	Height    *uint64
	ConfLevel *ConfLevel
}

func ConfEmitRef 

func ConfEmitRef(level ConfLevel) EmitRef

ConfEmitRef returns a EmitRef with the provided confirmation level.

func LatestEmitRef 

func LatestEmitRef() EmitRef

LatestEmitRef returns a EmitRef with the latest confirmation level.

func (EmitRef) Valid 

func (r EmitRef) Valid() bool

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

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, req ProviderRequest, 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, req ProviderRequest, 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, 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, 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 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) (EmitCursor, 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 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 (and populate in returned BlockHeader)
	Offset    uint64    // Cross-chain block offset to populate (from inclusive) in BlockHeader (if required).
}

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

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 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.
	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 SubmitCursor 

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

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

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.

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.