exchange

Documentation

Index

• Constants
• Variables
• type BSTipSet
  • func (t *BSTipSet) MarshalCBOR(w io.Writer) error
  • func (t *BSTipSet) UnmarshalCBOR(r io.Reader) (err error)
• type Client
• type CompactedMessages
  • func (t *CompactedMessages) MarshalCBOR(w io.Writer) error
  • func (t *CompactedMessages) UnmarshalCBOR(r io.Reader) (err error)
• type CompactedMessagesCBOR
  • func (t *CompactedMessagesCBOR) MarshalCBOR(w io.Writer) error
  • func (t *CompactedMessagesCBOR) UnmarshalCBOR(r io.Reader) (err error)
• type Options
  • func ParseOptions(optfield uint64) *Options
  • func (opt *Options) IsEmpty() bool
  • func (opt *Options) ToBits() uint64
• type Request
  • func (t *Request) MarshalCBOR(w io.Writer) error
  • func (t *Request) UnmarshalCBOR(r io.Reader) (err error)
• type Response
  • func (t *Response) MarshalCBOR(w io.Writer) error
  • func (res *Response) StatusToError() error
  • func (t *Response) UnmarshalCBOR(r io.Reader) (err error)

Constants

const (
	Headers = 1 << iota
	Messages
)

Request options. When fetching the chain segment we can fetch either block headers, messages, or both.

const (
	Ok status = 0
	// We could not fetch all blocks requested (but at least we returned
	// the `Head` requested). Not considered an error.
	Partial = 101

	// Errors
	NotFound      = 201
	GoAway        = 202
	InternalError = 203
	BadRequest    = 204
)

const (
	// ChainExchangeProtocolID is the protocol ID of the chain exchange
	// protocol.
	ChainExchangeProtocolID = "/fil/chain/xchg/0.0.1"
)

Variables

var MaxRequestLength = uint64(policy.ChainFinality)

FIXME: Bumped from original 800 to this to accommodate `syncFork()` use of `GetBlocks()`. It seems the expectation of that API is to fetch any amount of blocks leaving it to the internal logic here to partition and reassemble the requests if they go above the maximum. (Also as a consequence of this temporarily removing the `const` qualifier to avoid "const initializer [...] is not a constant" error.)

Types

type BSTipSet

type BSTipSet struct {
	// List of blocks belonging to a single tipset to which the
	// `CompactedMessages` are linked.
	Blocks   []*types.BlockHeader
	Messages *CompactedMessages
}

FIXME: Rename.

func (*BSTipSet) MarshalCBOR

func (t *BSTipSet) MarshalCBOR(w io.Writer) error

func (*BSTipSet) UnmarshalCBOR

func (t *BSTipSet) UnmarshalCBOR(r io.Reader) (err error)

type Client

type Client interface {
	// GetBlocks fetches block headers from the network, from the provided
	// tipset *backwards*, returning as many tipsets as the count parameter,
	// or less.
	GetBlocks(ctx context.Context, tsk types.TipSetKey, count int) ([]*types.TipSet, error)

	// GetChainMessages fetches messages from the network, starting from the first provided tipset
	// and returning messages from as many tipsets as requested or less.
	GetChainMessages(ctx context.Context, tipsets []*types.TipSet) ([]*CompactedMessages, error)

	// GetFullTipSet fetches a full tipset from a given peer. If successful,
	// the fetched object contains block headers and all messages in full form.
	GetFullTipSet(ctx context.Context, peer peer.ID, tsk types.TipSetKey) (*types.FullTipSet, error)

	// AddPeer adds a peer to the pool of peers that the Client requests
	// data from.
	AddPeer(ctx context.Context, peer peer.ID)

	// RemovePeer removes a peer from the pool of peers that the Client
	// requests data from.
	RemovePeer(ctx context.Context, peer peer.ID)
}

Client is the requesting side of the ChainExchange protocol. It acts as a proxy for other components to request chain data from peers. It is chiefly used by the Syncer.

type CompactedMessages

type CompactedMessages struct {
	Bls         []*types.Message
	BlsIncludes [][]uint64

	Secpk         []*types.SignedMessage
	SecpkIncludes [][]uint64
}

All messages of a single tipset compacted together instead of grouped by block to save space, since there are normally many repeated messages per tipset in different blocks.

`BlsIncludes`/`SecpkIncludes` matches `Bls`/`Secpk` messages to blocks in the tipsets with the format: `BlsIncludes[BI][MI]`

• BI: block index in the tipset.
• MI: message index in `Bls` list

FIXME: The logic to decompress this structure should belong

to itself, not to the consumer.

NOTE: Max messages is: BlockMessageLimit (10k) * MaxTipsetSize (15) = 150k

func (*CompactedMessages) MarshalCBOR

func (t *CompactedMessages) MarshalCBOR(w io.Writer) error

Copy into the encoding struct, then marshal.

func (*CompactedMessages) UnmarshalCBOR

func (t *CompactedMessages) UnmarshalCBOR(r io.Reader) (err error)

Unmarshal into the "decoding" struct, then copy into the actual struct.

type CompactedMessagesCBOR

type CompactedMessagesCBOR struct {
	Bls         []*types.Message `cborgen:"maxlen=150000"`
	BlsIncludes []messageIndices

	Secpk         []*types.SignedMessage `cborgen:"maxlen=150000"`
	SecpkIncludes []messageIndices
}

Type used for encoding/decoding compacted messages. This is a ustom type as we need custom limits. - Max messages is 150,000 as that's 15 times the max block size (in messages). It needs to be large enough to cover a full tipset full of full blocks.

func (*CompactedMessagesCBOR) MarshalCBOR

func (t *CompactedMessagesCBOR) MarshalCBOR(w io.Writer) error

func (*CompactedMessagesCBOR) UnmarshalCBOR

func (t *CompactedMessagesCBOR) UnmarshalCBOR(r io.Reader) (err error)

type Options

type Options struct {
	IncludeHeaders  bool
	IncludeMessages bool
}

Decompressed options into separate struct members for easy access during internal processing..

func ParseOptions

func ParseOptions(optfield uint64) *Options

func (*Options) IsEmpty

func (opt *Options) IsEmpty() bool

func (*Options) ToBits

func (opt *Options) ToBits() uint64

type Request

type Request struct {
	// List of ordered CIDs comprising a `TipSetKey` from where to start
	// fetching backwards.
	// FIXME: Consider using `TipSetKey` now (introduced after the creation
	//  of this protocol) instead of converting back and forth.
	Head []cid.Cid
	// Number of block sets to fetch from `Head` (inclusive, should always
	// be in the range `[1, MaxRequestLength]`).
	Length uint64
	// Request options, see `Options` type for more details. Compressed
	// in a single `uint64` to save space.
	Options uint64
}

FIXME: Rename. Make private.

func (*Request) MarshalCBOR

func (t *Request) MarshalCBOR(w io.Writer) error

func (*Request) UnmarshalCBOR

func (t *Request) UnmarshalCBOR(r io.Reader) (err error)

type Response

type Response struct {
	Status status
	// String that complements the error status when converting to an
	// internal error (see `statusToError()`).
	ErrorMessage string

	Chain []*BSTipSet
}

FIXME: Rename. Make private.

func (*Response) MarshalCBOR

func (t *Response) MarshalCBOR(w io.Writer) error

func (*Response) StatusToError

func (res *Response) StatusToError() error

Convert status to internal error.

func (*Response) UnmarshalCBOR

func (t *Response) UnmarshalCBOR(r io.Reader) (err error)