cchain

Documentation

Overview

Package cchain defines the API to interact with the omni consensus chain.

Index

• type PortalValidator
  • func (v PortalValidator) Verify() error
• type Provider
• type ProviderCallback
• type SDKSigningInfo
  • func (i SDKSigningInfo) ConsensusCmtAddr() (cmtcrypto.Address, error)
  • func (i SDKSigningInfo) Jailed() bool
• type SDKValidator
  • func (v SDKValidator) ConsensusCmtAddr() (cmtcrypto.Address, error)
  • func (v SDKValidator) ConsensusEthAddr() (common.Address, error)
  • func (v SDKValidator) ConsensusPublicKey() (*ecdsa.PublicKey, error)
  • func (v SDKValidator) OperatorEthAddr() (common.Address, error)
  • func (v SDKValidator) Power() (uint64, error)

Types

type PortalValidator

type PortalValidator struct {
	Address common.Address
	Power   int64
}

PortalValidator is a consensus chain validator in a validator set emitted/submitted by/tp portals .

func (PortalValidator) Verify

func (v PortalValidator) Verify() error

Verify returns an error if the validator is invalid.

type Provider

type Provider interface {
	// StreamAsync starts a goroutine that streams approved attestation forever from the
	// provided source chain and attest offset (inclusive).
	//
	// It returns immediately.
	// This is the async version of StreamAttestations.
	// It retries forever (with backoff) on all fetch and callback errors.
	StreamAsync(ctx context.Context, chainVer xchain.ChainVersion, attestOffset uint64,
		workerName string, callback ProviderCallback)

	// StreamAttestations is the synchronous fail-fast version of Subscribe. It streams
	// approved attestations as they become available but returns on the first callback error.
	// This is useful for workers that need to reset on application errors.
	StreamAttestations(ctx context.Context, chainVer xchain.ChainVersion, attestOffset uint64,
		workerName string, callback ProviderCallback) error

	// AttestationsFrom returns the subsequent approved attestations for the provided source chain
	// and attestOffset (inclusive). It will return max 100 attestations per call.
	AttestationsFrom(ctx context.Context, chainVer xchain.ChainVersion, attestOffset uint64) ([]xchain.Attestation, error)

	// AllAttestationsFrom returns the all pending and approve attestations for the provided source chain
	// and attestOffset (inclusive).
	AllAttestationsFrom(ctx context.Context, chainVer xchain.ChainVersion, attestOffset uint64) ([]xchain.Attestation, error)

	// LatestAttestation returns the latest approved attestation for the provided source chain or false
	// if none exist.
	LatestAttestation(ctx context.Context, chainVer xchain.ChainVersion) (xchain.Attestation, bool, error)

	// WindowCompare returns whether the given attestation block header is behind (-1), or in (0), or ahead (1)
	// of the current vote window. The vote window is a configured number of blocks around the latest approved
	// attestation for the provided chain.
	WindowCompare(ctx context.Context, chainVer xchain.ChainVersion, attestOffset uint64) (int, error)

	// PortalValidatorSet returns the valsync/portal validators for the given validator set ID or false if none exist or an error.
	// Note the genesis validator set has ID 1.
	PortalValidatorSet(ctx context.Context, valSetID uint64) ([]PortalValidator, bool, error)

	// SDKValidator returns the cosmos staking module validator by operator address from latest height.
	SDKValidator(ctx context.Context, operator common.Address) (SDKValidator, bool, error)

	// SDKValidators returns the current cosmos staking module validators from latest height.
	SDKValidators(ctx context.Context) ([]SDKValidator, error)

	// SDKSigningInfos returns the slashing module signing infos for all validators from latest height.
	SDKSigningInfos(ctx context.Context) ([]SDKSigningInfo, error)

	// SDKRewards returns the staking module rewards for the given operator address from latest height.
	SDKRewards(ctx context.Context, operator common.Address) (float64, bool, error)

	// XBlock returns the portal module block for the given blockHeight/attestOffset (or latest) or false if none exist or an error.
	XBlock(ctx context.Context, heightAndOffset uint64, latest bool) (xchain.Block, bool, error)

	// GenesisFiles returns the execution (optional) and consensus genesis files.
	GenesisFiles(ctx context.Context) (execution []byte, consensus []byte, err error)

	// Portals returns the portals registered in the registry module.
	Portals(ctx context.Context) ([]rtypes.Portal, bool, error)

	// CurrentPlannedPlan returns the current (non-activated) upgrade plan.
	CurrentPlannedPlan(ctx context.Context) (utypes.Plan, bool, error)

	// AppliedPlan returns the applied (activated) upgrade plan by name.
	AppliedPlan(ctx context.Context, name string) (utypes.Plan, bool, error)
}

Provider abstracts connecting to the omni consensus chain and streaming approved attestations for each source chain block from a specific height.

It provides exactly once-delivery guarantees for the callback function. It will exponentially backoff and retry forever while the callback function returns an error.

type ProviderCallback

type ProviderCallback func(ctx context.Context, approved xchain.Attestation) error

ProviderCallback is the callback function signature that will be called with each approved attestation per source chain block in strictly sequential order.

type SDKSigningInfo

type SDKSigningInfo struct {
	sltypes.ValidatorSigningInfo
	// Uptime is the percentage [0,1] of blocks signed in the previous <SignedBlockWindow> (1000).
	// Note this is 100% if the validator isn't bonded, since it can't technically miss blocks.
	Uptime float64
}

SDKSigningInfo wraps the cosmos slashing signing info type and extends it with convenience functions.

func (SDKSigningInfo) ConsensusCmtAddr

func (i SDKSigningInfo) ConsensusCmtAddr() (cmtcrypto.Address, error)

func (SDKSigningInfo) Jailed

func (i SDKSigningInfo) Jailed() bool

type SDKValidator

type SDKValidator struct {
	stypes.Validator
}

SDKValidator wraps the cosmos staking validator type and extends it with convenience functions.

func (SDKValidator) ConsensusCmtAddr

func (v SDKValidator) ConsensusCmtAddr() (cmtcrypto.Address, error)

ConsensusCmtAddr returns the validator consensus cometBFT address.

func (SDKValidator) ConsensusEthAddr

func (v SDKValidator) ConsensusEthAddr() (common.Address, error)

ConsensusEthAddr returns the validator consensus eth address.

func (SDKValidator) ConsensusPublicKey

func (v SDKValidator) ConsensusPublicKey() (*ecdsa.PublicKey, error)

ConsensusPublicKey returns the validator consensus public key (eth ecdsa style).

func (SDKValidator) OperatorEthAddr

func (v SDKValidator) OperatorEthAddr() (common.Address, error)

OperatorEthAddr returns the validator operator ethereum address.

func (SDKValidator) Power

func (v SDKValidator) Power() (uint64, error)

Power returns the validators cometBFT power.