sdk

Documentation

Index

• Constants
• Variables
• type ChainEventResult
• type Client
  • func WithTimeoutableClientInterceptor(client Client, logger *zap.Logger) Client
• type Config
• type Env
• type ManagerOption
  • func WithContext(ctx context.Context) ManagerOption
  • func WithLogSampling(sampling *zap.SamplingConfig) ManagerOption
  • func WithLogger(logger *zap.Logger) ManagerOption
• type Parser
• type Session
  • func New(manager services.SystemManager, cfg *Config) (Session, error)
• type SessionParams
• type StreamingConfiguration
• type SystemManager
  • func NewManager(opts ...ManagerOption) SystemManager

Constants

const (
	EnvProduction  = config.EnvProduction
	EnvDevelopment = config.EnvDevelopment
	EnvLocal       = config.EnvLocal
)

Variables

var Module = fx.Options(
	fx.Provide(newClient),
	fx.Provide(newSession),
)

Types

type ChainEventResult

type ChainEventResult struct {
	BlockchainEvent *api.BlockchainEvent
	Block           *api.Block
	Error           error
}

type Client

type Client interface {
	// GetTag returns the current tag used by the client.
	// It is zero by default and ChainStorage returns the latest and greatest version of the block.
	GetTag() uint32

	// SetTag sets the current tag which effectively pins the version to the specified tag.
	SetTag(tag uint32)

	// GetClientID returns the clientID which could be empty.
	GetClientID() string

	// SetClientID sets the clientID when initiate client.
	SetClientID(clientID string)

	// SetBlockValidation sets the blockValidation which by default is disabled.
	SetBlockValidation(blockValidation bool)

	// GetBlockValidation returns the blockValidation.
	GetBlockValidation() bool

	// GetLatestBlock returns the latest block height.
	// Deprecated: use GetLatestBlockWithTag instead.
	GetLatestBlock(ctx context.Context) (uint64, error)

	// GetLatestBlockWithTag returns the latest block height, tag is optional.
	// If tag is not provided, ChainStorage uses the stable tag to look up the latest height.
	GetLatestBlockWithTag(ctx context.Context, tag uint32) (uint64, error)

	// GetBlock returns the raw block. height is required and hash is optional.
	// If hash is not provided, ChainStorage returns the block on the canonical chain.
	// Deprecated: use GetBlockWithTag instead.
	GetBlock(ctx context.Context, height uint64, hash string) (*api.Block, error)

	// GetBlockWithTag returns the raw block. height is required, while tag and hash are optional.
	// If tag is not provided, ChainStorage uses the stable tag to look up the block.
	// If hash is not provided, ChainStorage returns the block on the canonical chain.
	// Note that while processing a BlockchainEvent, tag/height/hash must be provided,
	// because it is associated with a past event.
	GetBlockWithTag(ctx context.Context, tag uint32, height uint64, hash string) (*api.Block, error)

	// GetBlocksByRange returns the raw blocks between [startHeight, endHeight).
	// endHeight is optional and defaults to startHeight + 1.
	GetBlocksByRange(ctx context.Context, startHeight uint64, endHeight uint64) ([]*api.Block, error)

	// GetBlocksByRangeWithTag returns the raw blocks between [startHeight, endHeight).
	// endHeight is optional and defaults to startHeight + 1.
	// tag is optional and defaults to stable tag.
	// Note: GetBlocksByRangeWithTag is not equivalent to the batch version of GetBlockWithTag since there is no way to specify the block hash,
	// and thus you may get back FailedPrecondition errors if it goes beyond current tip due to reorg, especially for streaming case.
	GetBlocksByRangeWithTag(ctx context.Context, tag uint32, startHeight uint64, endHeight uint64) ([]*api.Block, error)

	// GetBlockByTransaction returns the raw block(s) where the transaction resides,
	// or an empty list if the transaction is not found.
	// In most networks a transaction belongs to a single block, but there are exceptions.
	// Note that this API is still experimental and may change at any time.
	GetBlockByTransaction(ctx context.Context, tag uint32, transactionHash string) ([]*api.Block, error)

	// StreamChainEvents streams raw blocks from ChainStorage.
	// The caller is responsible for keeping track of the sequence or sequence_num in BlockchainEvent.
	StreamChainEvents(ctx context.Context, cfg StreamingConfiguration) (<-chan *ChainEventResult, error)

	// GetChainEvents returns at most req.MaxNumEvents available chain events.
	// Returned size is not guaranteed. If no enough chain events, it will return as many as possible.
	// Either req.StartEventId or req.InitialPositionInStream should be provided.
	GetChainEvents(ctx context.Context, req *api.GetChainEventsRequest) ([]*api.BlockchainEvent, error)

	// GetChainMetadata returns chain metadata, e.g. LatestEventTag.
	GetChainMetadata(ctx context.Context, req *api.GetChainMetadataRequest) (*api.GetChainMetadataResponse, error)

	// GetStaticChainMetadata returns the static chain metadata, getting from the Config, instead of querying the ChainStorage server.
	// This is useful if the caller needs a consistent snapshot of chain metadata during its current lifecycle.
	GetStaticChainMetadata(ctx context.Context, req *api.GetChainMetadataRequest) (*api.GetChainMetadataResponse, error)
}

func WithTimeoutableClientInterceptor

func WithTimeoutableClientInterceptor(client Client, logger *zap.Logger) Client

type Config

type Config struct {
	Blockchain      common.Blockchain `mapstructure:"blockchain" validate:"required"`
	Network         common.Network    `mapstructure:"network" validate:"required"`
	Env             Env               `mapstructure:"env" validate:"required,oneof=production development local"`
	Sidechain       api.SideChain     `mapstructure:"side_chain"`
	Tag             uint32            `mapstructure:"tag"`
	ClientID        string            `mapstructure:"client_id"`
	ServerAddress   string            `mapstructure:"server_address"`
	ClientTimeout   time.Duration     `mapstructure:"client_timeout"`
	BlockValidation *bool             `mapstructure:"block_validation"`
}

type Env

type Env = config.Env

type ManagerOption

type ManagerOption = services.ManagerOption

func WithContext

func WithContext(ctx context.Context) ManagerOption

WithContext allows to set root context instead of using context.Background() by default

func WithLogSampling

func WithLogSampling(sampling *zap.SamplingConfig) ManagerOption

WithLogSampling will enable sampling on the default logger if you didn't provide one yourself. This option will have no effect if used with the WithLogger option.

func WithLogger

func WithLogger(logger *zap.Logger) ManagerOption

WithLogger allows the logger to be injected into the manager.

type Parser

type Parser interface {
	ParseNativeBlock(ctx context.Context, rawBlock *api.Block) (*api.NativeBlock, error)
	GetNativeTransaction(ctx context.Context, nativeBlock *api.NativeBlock, transactionHash string) (*api.NativeTransaction, error)
	ParseRosettaBlock(ctx context.Context, rawBlock *api.Block) (*api.RosettaBlock, error)
	ValidateBlock(ctx context.Context, nativeBlock *api.NativeBlock) error
}

type Session

type Session interface {
	Client() Client
	Parser() Parser
}

func New

func New(manager services.SystemManager, cfg *Config) (Session, error)

type SessionParams

type SessionParams struct {
	fx.In
	Client Client
	Parser parser.Parser
}

type StreamingConfiguration

type StreamingConfiguration struct {
	// See the proto for details.
	ChainEventsRequest *api.ChainEventsRequest `validate:"required"`

	// How many blocks to prefetch. If not specified. it defaults to 1.
	ChannelBufferCapacity uint64

	// Number of events to return from the stream. If not specified, streaming never ends.
	NumberOfEvents uint64

	// Not implemented.
	BlockConfirmationGap uint64

	// If specified, the Block field is omitted from ChainEventResult.
	EventOnly bool
}

type SystemManager

type SystemManager = services.SystemManager

func NewManager

func NewManager(opts ...ManagerOption) SystemManager