substrate

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Sep 1, 2022 License: Apache-2.0 Imports: 15 Imported by: 3

Documentation

Overview

Package substrate provides reusable functions for interacting with a substrate node.

Index

Constants

View Source 
const (
	// PlankPerDot number of planks per Dot.
	PlankPerDot = 1e12
	// PrintPrecision is the precision with which floats are printed
	// as defined by big.Float.Text.
	PrintPrecision = 3
)
View Source 
const ChanBuffSize = 1024

ChanBuffSize is the buffer size of an EventSource. GSRPC buffers up to 20k events.

View Source 
const DefaultTimeoutPollInterval = time.Second

DefaultTimeoutPollInterval default value for the PollInterval of a Timeout.

Variables

View Source 
var (
	// ErrUnknownError the error could not be decoded.
	ErrUnknownError = errors.New("unknown dispatch error type")
	// ErrCallFailed an extrinsic returned an error.
	ErrCallFailed = errors.New("call failed")
)
View Source 
var ErrWrongNodeVersion = errors.New("wrong node version")

ErrWrongNodeVersion returned if an invalid substrate node version was detected.

View Source 
var SignaturePrefix = []byte("substrate")

SignaturePrefix is prepended by substrate to all messages before signing.

Functions

func DecodeError 

func DecodeError(meta *types.Metadata, err types.DispatchError) error

DecodeError decodes an error into a human-readable form. Returns either ErrUnknownError or ErrCallFailed.

func ExtIsFinal 

func ExtIsFinal(status *types.ExtrinsicStatus) bool

ExtIsFinal returns whether an Extrinsic is final.

func Meta 

func Meta(meta *gsrpc.Metadata) (*gsrpc.MetadataV13, bool)

Meta returns the expected metadata and a success bool. Can be used to check whether the connected substrate node is running the right version.

func SS58Address 

func SS58Address(addr gsrpc.AccountID, network NetworkID) (string, error)

SS58Address returns the SS58 of an Address for a specific network.

Types

type API 

type API struct {
	log.Embedding
	// contains filtered or unexported fields
}

API wraps a gsrpc.SubstrateAPI in a thread-safe way.

func NewAPI 

func NewAPI(url string, network NetworkID) (*API, error)

NewAPI creates a new `Api` object. Can be retried in the case of an error.

func (*API) AccountInfo 

func (a *API) AccountInfo(addr types.AccountID) (AccountInfo, error)

AccountInfo returns the account info for an Address. Can be used to retrieve the free balance, nonce, and other.

func (*API) BlockHash 

func (a *API) BlockHash(n uint64) (types.Hash, error)

BlockHash returns the hash for the given block number.

func (*API) BuildKey 

func (a *API) BuildKey(pallet, variable string, args ...[]byte) (types.StorageKey, error)

BuildKey builds a storage key.

func (*API) LastHeader 

func (a *API) LastHeader() (*types.Header, error)

LastHeader returns the last header.

func (*API) Metadata 

func (a *API) Metadata() *types.Metadata

Metadata returns the metadata of the chain. The value is cached on startup.

func (*API) Network 

func (a *API) Network() NetworkID

Network returns the ID of the network that the api is connected to. The value is cached on startup.

func (*API) PastBlock 

func (a *API) PastBlock(pastBlocks types.BlockNumber) (types.Hash, error)

PastBlock queries `pastBlocks` into the past and returns the hash of the block. If `pastBlocks` is larger than the current block number, the genesis block is used.

func (*API) QueryAll 

func (a *API) QueryAll(keys []types.StorageKey, startBlock types.Hash) ([]types.StorageChangeSet, error)

QueryAll returns all entries for `keys` from `startBlock` to the last block.

func (*API) QueryOne 

func (a *API) QueryOne(pastBlocks types.BlockNumber, keys ...types.StorageKey) (*types.KeyValueOption, error)

QueryOne queries the storage and expects to read at least one value. PastBlocks defines how many blocks into the past the query should look. Returns the latest value that it read or an error if none was found within the last `pastBlocks` blocks.

func (*API) RuntimeVersion 

func (a *API) RuntimeVersion() (*types.RuntimeVersion, error)

RuntimeVersion queries and returns the last runtime version.

func (*API) Subscribe 

func (a *API) Subscribe(keys ...types.StorageKey) (*state.StorageSubscription, error)

Subscribe subscribes to multiple storage keys.

func (*API) SubscribeHeaders 

func (a *API) SubscribeHeaders() (*chain.NewHeadsSubscription, error)

SubscribeHeaders subscribes to new headers.

func (*API) Transact 

func (a *API) Transact(ext *types.Extrinsic) (*ExtStatusSub, error)

Transact sends an Extrinsic and returns a Sub for its updates.

type AccountInfo 

type AccountInfo struct {
	Nonce       types.U32
	Consumers   types.U32
	Providers   types.U32
	Sufficients types.U32

	Free       types.U128
	Reserved   types.U128
	MiscFrozen types.U128
	FreeFrozen types.U128
}

AccountInfo replaces substrate.AccountInfo since it is outdated. This is advised by the GSRPC team.

type ChainReader 

type ChainReader interface {
	// Metadata returns the latest metadata.
	Metadata() *gsrpc.Metadata
	// BlockHash returns the block hash for the given block number.
	BlockHash(gsrpc.BlockNumber) (gsrpc.Hash, error)
	// HeaderLatest returns the last header.
	HeaderLatest() *gsrpc.Header
}

ChainReader is used to query the on-chain state.

type Dot 

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

Dot wraps a *big.Int and provides conversion and formatting for Dot values.

func NewDotFromPlank 

func NewDotFromPlank(plank *big.Int) *Dot

NewDotFromPlank creates a new Dot from the given amount of Planks.

func NewDotsFromPlanks 

func NewDotsFromPlanks(plank ...*big.Int) []*Dot

NewDotsFromPlanks creates new Dots from the given amounts of Planks.

func (*Dot) Abs 

func (d *Dot) Abs() *Dot

Abs returns the absolute value.

func (*Dot) Plank 

func (d *Dot) Plank() *big.Int

Plank converts a Dot to Planks.

func (*Dot) String 

func (d *Dot) String() string

String formats a Dot with the correct unit. Works for positive and negative values.

type EventKey 

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

EventKey identifies an event type that an EventSource can listen on.

func SystemAccountKey 

func SystemAccountKey(accountID types.AccountID) *EventKey

SystemAccountKey is the key to query an account.

func SystemEventsKey 

func SystemEventsKey() *EventKey

SystemEventsKey is the key of all system events.

func (*EventKey) Key 

func (k *EventKey) Key(meta *types.Metadata) (types.StorageKey, error)

Key returns the EventKey as GSRPC key.

type EventSource 

type EventSource struct {
	*pkgsync.Closer
	log.Embedding
	// contains filtered or unexported fields
}

EventSource collects all events from the chain. Can then be used to filter out events, eg. for a specific pallet.

func NewEventSource 

func NewEventSource(api *API, pastBlocks types.BlockNumber, keys ...*EventKey) (*EventSource, error)

NewEventSource returns a new EventSource. It queries pastBlocks into the past to retrieve old events and starts listening for new events with the passed EventKeys.

func (*EventSource) Err 

func (s *EventSource) Err() <-chan error

Err returns the error channel. Will be closed when the EventSource is closed.

func (*EventSource) Events 

func (s *EventSource) Events() <-chan types.EventRecordsRaw

Events returns a channel that contains all events that the EventSource found. This channel will never be closed.

type ExpiredTimeout 

type ExpiredTimeout struct{}

ExpiredTimeout is always expired. Implements the Perun Timeout interface.

func NewExpiredTimeout 

func NewExpiredTimeout() *ExpiredTimeout

NewExpiredTimeout returns a new ExpiredTimeout.

func (*ExpiredTimeout) IsElapsed 

func (*ExpiredTimeout) IsElapsed(context.Context) bool

IsElapsed returns true.

func (*ExpiredTimeout) Wait 

func (*ExpiredTimeout) Wait(context.Context) error

Wait returns nil.

type ExtFactory 

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

ExtFactory can be used to build Extrinsics.

func NewExtFactory 

func NewExtFactory(sub *API) *ExtFactory

NewExtFactory returns a new ExtFactory.

func (*ExtFactory) BuildExt 

func (b *ExtFactory) BuildExt(name *ExtName, args []interface{}) (*types.Extrinsic, error)

BuildExt returns a new Extrinsic with the given args.

func (*ExtFactory) SigOptions 

func (b *ExtFactory) SigOptions(addr types.AccountID) (*types.SignatureOptions, error)

SigOptions returns the default signature options for an address.

type ExtName 

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

ExtName identifies an Extrinsic by its name.

func NewExtName 

func NewExtName(pallet, function string) *ExtName

NewExtName creates a new ExtName for the given pallet and function name. Example: NewExtName("PerunModule", "deposit").

func (*ExtName) String 

func (f *ExtName) String() string

String formats an ExtrinsicName in the form `Pallet.Function`.

type ExtSigner 

type ExtSigner interface {
	// SignExt signs the extrinsic with the specified options and network.
	SignExt(*gsrpc.Extrinsic, gsrpc.SignatureOptions, NetworkID) error
}

ExtSigner signs an Extrinsic by modifying it.

type ExtStatusPred 

type ExtStatusPred func(*types.ExtrinsicStatus) bool

ExtStatusPred can be used to filter the status of an Extrinsic.

type ExtStatusSub 

type ExtStatusSub struct {
	pkgsync.Closer
	// contains filtered or unexported fields
}

ExtStatusSub can be used to subscribe to the status of an Extrinsic.

func NewExtStatusSub 

func NewExtStatusSub(sub *author.ExtrinsicStatusSubscription) *ExtStatusSub

NewExtStatusSub returns a new ExtStatusSub and takes ownership of the passed sub.

func (*ExtStatusSub) Close 

func (e *ExtStatusSub) Close()

Close closes the subscription.

func (*ExtStatusSub) WaitUntil 

func (e *ExtStatusSub) WaitUntil(ctx context.Context, until ExtStatusPred) error

WaitUntil waits until the predicate returns true or the context is cancelled. Can be used for example to wait until an Extrinsic is final with `ExtIsFinal`.

type NetworkID 

type NetworkID uint8

NetworkID ID of the substrate chain.

type Pallet 

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

Pallet binds to a pallet that is deployed on a substrate chain.

func NewPallet 

func NewPallet(api *API, name string) *Pallet

NewPallet returns a new pallet.

func (*Pallet) BuildExt 

func (p *Pallet) BuildExt(call *ExtName, args []interface{}, addr types.AccountID, signer ExtSigner) (*types.Extrinsic, error)

BuildExt builds and signs an extrinsic.

func (*Pallet) BuildQuery 

func (p *Pallet) BuildQuery(variable string, args ...[]byte) (types.StorageKey, error)

func (*Pallet) Subscribe 

func (p *Pallet) Subscribe(pastBlocks types.BlockNumber) (*EventSource, error)

Subscribe subscribes on all events of the pallet.

func (*Pallet) Transact 

func (p *Pallet) Transact(ext *types.Extrinsic) (*ExtStatusSub, error)

Transact sends an Extrinsic and returns a status sub for it.

type StorageQueryer 

type StorageQueryer interface {
	// QueryOne queries the storage and expects to read at least one value.
	// PastBlocks defines how many blocks into the past the query should look.
	// Returns the latest value that it read or an error if none was found
	// within the last `pastBlocks` blocks.
	QueryOne(pastBlocks gsrpc.BlockNumber, keys ...gsrpc.StorageKey) (*gsrpc.KeyValueOption, error)

	// Subscribe subscribes to the changes of a storage key.
	Subscribe(keys ...gsrpc.StorageKey) (*state.StorageSubscription, error)

	// StorageKey builds a storage key.
	BuildKey(prefix, method string, args ...[]byte) (gsrpc.StorageKey, error)
}

StorageQueryer can be used to query the on-chain state.

type TimePoint 

type TimePoint uint64

TimePoint as defined by pallet Timestamp.

type Timeout 

type Timeout struct {
	log.Embedding
	// contains filtered or unexported fields
}

Timeout can be used to wait until a specific timepoint is reached by the blockchain. Implements the Perun Timeout interface.

func NewTimeout 

func NewTimeout(storage StorageQueryer, when time.Time, pollInterval time.Duration) *Timeout

NewTimeout returns a new Timeout which expires at the given time.

func (*Timeout) IsElapsed 

func (t *Timeout) IsElapsed(context.Context) bool

IsElapsed returns whether the timeout is elapsed.

func (*Timeout) Wait 

func (t *Timeout) Wait(ctx context.Context) error

Wait waits for the timeout or until the context is cancelled.

Source Files

View all Source files

Directories

Path Synopsis
Package test provides helper and setup functions to test the substrate package.
 Package test provides helper and setup functions to test the substrate package.

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.