client

Documentation

Overview

Package client implements a gRPC client to Libra RPC service.

Features include:

• Query ledger information
• Query account state
• Query transactions by range
• Query single transaction by account and sequence number
• Sign and submit raw transactions

All queries are cryptographically verified to proof their inclusion and integrity in the blockchain.

The client can also keep track of the consistency of the ledger. This function will detect hard forks or block chain reset.

When a client is newly constructed, it knows only the genesis block (version 0) of the ledger. The hash of the genesis block is hardcoded. After each query to the ledger, the client updates its knowledge about the latest version and the Merkle tree accumulator.

You should extract the known-version state of a client instance before destroying it, by calling GetKnownVersion(), and saving the result somewhere. Later, when a new client instance is constructed, you should use SetKnownVersion() to restore the known-version state.

Index

• func MustToAddress(str string) (out types.AccountAddress)
• func NewRawP2PTransaction(senderAddress, receiverAddress types.AccountAddress, ...) (*types.RawTransaction, error)
• func PubkeyMustToAddress(pubkey []byte) (out types.AccountAddress)
• func PubkeyMustToAuthKey(pubkey []byte) []byte
• type Client
  • func New(ServerAddr, Waypoint string) (*Client, error)
  • func NewFromState(ServerAddr string, state *State) (*Client, error)
  • func (c *Client) Close()
  • func (c *Client) GetLatestWaypoint() string
  • func (c *Client) GetState() *State
  • func (c *Client) PollSequenceUntil(ctx context.Context, addr types.AccountAddress, targetSeq uint64, ...) error
  • func (c *Client) QueryAccountSequenceNumber(ctx context.Context, addr types.AccountAddress) (uint64, error)
  • func (c *Client) QueryAccountState(ctx context.Context, addr types.AccountAddress) (*types.ProvenAccountState, error)
  • func (c *Client) QueryEventsByAccessPath(ctx context.Context, ap *types.AccessPath, start uint64, ascending bool, ...) ([]*types.ProvenEvent, error)
  • func (c *Client) QueryLedgerInfo(ctx context.Context) (*types.ProvenLedgerInfo, error)
  • func (c *Client) QueryTransactionByAccountSeq(ctx context.Context, addr types.AccountAddress, sequence uint64, ...) (*types.ProvenTransaction, error)
  • func (c *Client) QueryTransactionRange(ctx context.Context, start, limit uint64, withEvents bool) (*types.ProvenTransactionList, error)
  • func (c *Client) SetState(cs *State) error
  • func (c *Client) SubmitRawTransaction(ctx context.Context, rawTxn *types.RawTransaction, ...) (uint64, error)
• type HashValue
  • func (h HashValue) MarshalText() (text []byte, err error)
  • func (h *HashValue) UnmarshalText(txt []byte) error
• type State

Functions

func MustToAddress

func MustToAddress(str string) (out types.AccountAddress)

MustToAddress converts hex string represent of an address into types.AccountAddress. Input string should be a hex string with exactly 64 hex digits.

func NewRawP2PTransaction

func NewRawP2PTransaction(
	senderAddress, receiverAddress types.AccountAddress, receiverAuthKeyPrefix []byte,
	senderSequenceNumber uint64,
	amount, maxGasAmount, gasUnitPrice uint64,
	expiration time.Time,
) (*types.RawTransaction, error)

NewRawP2PTransaction creates a new serialized raw transaction bytes corresponding to a peer-to-peer Libra coin transaction.

func PubkeyMustToAddress

func PubkeyMustToAddress(pubkey []byte) (out types.AccountAddress)

PubkeyMustToAddress converts an ed25519 public key (32 bytes) into types.AccountAddress (16 bytes).

func PubkeyMustToAuthKey

func PubkeyMustToAuthKey(pubkey []byte) []byte

PubkeyMustToAuthKey converts an ed25519 public key (32 bytes) into auth key (32 bytes).

Types

type Client

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

Client is a Libra client. It has a gRPC client to a Libra RPC server, with public keys to trusted peers.

func New

func New(ServerAddr, Waypoint string) (*Client, error)

New creates a new Libra Client from a trusted waypoint.

For usage in golang, ServerAddr is in host:port format. For use with Javascript, ServerAddr is in http://host:port format.

Waypoint is a trusted waypoint in the format of "version:hash". Currently, version has to be 0 in order to make consistency check work.

Waypoint can also be "insecure", meaning that the client will trust whatever the ledger has. This is useful with the testnet, which gets reset every now and then. Do not rely on this feature, however. It will be removed when the mainnet is online.

func NewFromState

func NewFromState(ServerAddr string, state *State) (*Client, error)

NewFromState creates a new Libra Client from a previous saved state.

For usage in golang, ServerAddr is in host:port format. For use with Javascript, ServerAddr is in http://host:port format.

The state includes validator set and known version subtrees. It can be exported by calling GetState().

func (*Client) Close

func (c *Client) Close()

Close the client.

func (*Client) GetLatestWaypoint

func (c *Client) GetLatestWaypoint() string

GetLatestWaypoint returns the latest waypoint string that this client has reached.

func (*Client) GetState

func (c *Client) GetState() *State

GetState returns the current state of a client.

func (*Client) PollSequenceUntil

func (c *Client) PollSequenceUntil(ctx context.Context, addr types.AccountAddress, targetSeq uint64, expiration time.Time) error

PollSequenceUntil blocks to repeatedly poll the sequence number of a specific account, until the sequence number is greater or equal to specified target sequence number, or the ledger state passes specified expiration time.

func (*Client) QueryAccountSequenceNumber

func (c *Client) QueryAccountSequenceNumber(ctx context.Context, addr types.AccountAddress) (uint64, error)

QueryAccountSequenceNumber queries sequence number of an account from RPC server, and does necessary crypto verifications.

func (*Client) QueryAccountState

func (c *Client) QueryAccountState(ctx context.Context, addr types.AccountAddress) (*types.ProvenAccountState, error)

QueryAccountState queries account state from RPC server by account address, and does necessary crypto verifications.

func (*Client) QueryEventsByAccessPath

func (c *Client) QueryEventsByAccessPath(ctx context.Context, ap *types.AccessPath, start uint64, ascending bool, limit uint64) ([]*types.ProvenEvent, error)

QueryEventsByAccessPath queries list of events by access path does necessary crypto verifications.

func (*Client) QueryLedgerInfo

func (c *Client) QueryLedgerInfo(ctx context.Context) (*types.ProvenLedgerInfo, error)

QueryLedgerInfo queries ledger info from RPC server, and does necessary crypto verifications.

func (*Client) QueryTransactionByAccountSeq

func (c *Client) QueryTransactionByAccountSeq(ctx context.Context, addr types.AccountAddress, sequence uint64, withEvents bool) (*types.ProvenTransaction, error)

QueryTransactionByAccountSeq queries the transaction that is sent from a specific account at a specific sequence number, and does necessary crypto verifications.

func (*Client) QueryTransactionRange

func (c *Client) QueryTransactionRange(ctx context.Context, start, limit uint64, withEvents bool) (*types.ProvenTransactionList, error)

QueryTransactionRange queries a list of transactions from RPC server, and does necessary crypto verifications.

func (*Client) SetState

func (c *Client) SetState(cs *State) error

SetState restores a client to a given state.

func (*Client) SubmitRawTransaction

func (c *Client) SubmitRawTransaction(ctx context.Context, rawTxn *types.RawTransaction, privateKey ed25519.PrivateKey) (uint64, error)

SubmitRawTransaction signes and submits a raw transaction. It returns the expected sequence number of this transaction.

type HashValue

type HashValue []byte

HashValue is a wrap of []byte. It implementes encoding.TextMarshaler and encoding.TextUnmarshaler.

func (HashValue) MarshalText

func (h HashValue) MarshalText() (text []byte, err error)

MarshalText implements encoding.TextMarshaler for HashValue

func (*HashValue) UnmarshalText

func (h *HashValue) UnmarshalText(txt []byte) error

UnmarshalText implements encoding.TextUnmarshaler for HashValue

type State

type State struct {
	Waypoint     string                 `toml:"waypoint" json:"waypoint"`
	VSScheme     string                 `toml:"validator_set_scheme" json:"validator_set_scheme,omitempty"`
	ValidatorSet []*types.ValidatorInfo `toml:"validator_set" json:"validator_set,omitempty"`
	Epoch        uint64                 `toml:"epoch" json:"epoch"`
	KnownVersion uint64                 `toml:"known_version" json:"known_version"`
	Subtrees     []HashValue            `toml:"subtrees" json:"subtrees"`
}

State represents the state of a client.