client

Documentation

Overview

Package client provides client support for interacting with a serverless log.

See the /cmd/client package in this repo for an example of using this.

Index

• func CheckConsistency(ctx context.Context, h merkle.LogHasher, f Fetcher, cp []log.Checkpoint) error
• func FetchCheckpoint(ctx context.Context, f Fetcher, v note.Verifier, origin string) (*log.Checkpoint, []byte, *note.Note, error)
• func FetchLeafHashes(ctx context.Context, f Fetcher, first, N, logSize uint64) ([][]byte, error)
• func FetchRangeNodes(ctx context.Context, s uint64, gt GetTileFunc) ([][]byte, error)
• func GetLeaf(ctx context.Context, f Fetcher, i uint64) ([]byte, error)
• func LookupIndex(ctx context.Context, f Fetcher, lh []byte) (uint64, error)
• type ConsensusCheckpointFunc
  • func UnilateralConsensus(f Fetcher) ConsensusCheckpointFunc
• type ErrInconsistency
  • func (e ErrInconsistency) Error() string
  • func (e ErrInconsistency) Unwrap() error
• type Fetcher
• type GetTileFunc
• type LogStateTracker
  • func NewLogStateTracker(ctx context.Context, f Fetcher, h merkle.LogHasher, checkpointRaw []byte, ...) (LogStateTracker, error)
  • func (lst *LogStateTracker) Update(ctx context.Context) ([]byte, [][]byte, []byte, error)
• type ProofBuilder
  • func NewProofBuilder(ctx context.Context, cp log.Checkpoint, h compact.HashFn, f Fetcher) (*ProofBuilder, error)
  • func (pb *ProofBuilder) ConsistencyProof(ctx context.Context, smaller, larger uint64) ([][]byte, error)
  • func (pb *ProofBuilder) InclusionProof(ctx context.Context, index uint64) ([][]byte, error)

Functions

func CheckConsistency

func CheckConsistency(ctx context.Context, h merkle.LogHasher, f Fetcher, cp []log.Checkpoint) error

CheckConsistency is a wapper function which simplifies verifying consistency between two or more checkpoints.

func FetchCheckpoint

func FetchCheckpoint(ctx context.Context, f Fetcher, v note.Verifier, origin string) (*log.Checkpoint, []byte, *note.Note, error)

FetchCheckpoint retrieves and opens a checkpoint from the log. Returns both the parsed structure and the raw serialised checkpoint.

func FetchLeafHashes

func FetchLeafHashes(ctx context.Context, f Fetcher, first, N, logSize uint64) ([][]byte, error)

FetchLeafHashes fetches N consecutive leaf hashes starting with the leaf at index first.

func FetchRangeNodes

func FetchRangeNodes(ctx context.Context, s uint64, gt GetTileFunc) ([][]byte, error)

FetchRangeNodes returns the set of nodes representing the compact range covering a log of size s.

func GetLeaf

func GetLeaf(ctx context.Context, f Fetcher, i uint64) ([]byte, error)

GetLeaf fetches the raw contents committed to at a given leaf index.

func LookupIndex

func LookupIndex(ctx context.Context, f Fetcher, lh []byte) (uint64, error)

LookupIndex fetches the leafhash->seq mapping file from the log, and returns its parsed contents.

Types

type ConsensusCheckpointFunc

type ConsensusCheckpointFunc func(ctx context.Context, logSigV note.Verifier, origin string) (*log.Checkpoint, []byte, *note.Note, error)

ConsensusCheckpointFunc is a function which returns the largest checkpoint known which is signed by logSigV and satisfies some consensus algorithm.

This is intended to provide a hook for adding a consensus view of a log, e.g. via witnessing.

func UnilateralConsensus

func UnilateralConsensus(f Fetcher) ConsensusCheckpointFunc

UnilateralConsensus blindly trusts the source log, returning the checkpoint it provided.

type ErrInconsistency

type ErrInconsistency struct {
	SmallerRaw []byte
	LargerRaw  []byte
	Proof      [][]byte

	Wrapped error
}

ErrInconsistency should be returned when there has been an error proving consistency between log states. The raw log state representations are included as-returned by the target log, this ensures that evidence of inconsistent log updates are available to the caller of the method(s) returning this error.

func (ErrInconsistency) Error

func (e ErrInconsistency) Error() string

func (ErrInconsistency) Unwrap

func (e ErrInconsistency) Unwrap() error

type Fetcher

type Fetcher func(ctx context.Context, path string) ([]byte, error)

Fetcher is the signature of a function which can retrieve arbitrary files from a log's data storage, via whatever appropriate mechanism. The path parameter is relative to the root of the log storage.

Note that the implementation of this MUST return (either directly or wrapped) an os.ErrIsNotExit when the file referenced by path does not exist, e.g. a HTTP based implementation MUST return this error when it receives a 404 StatusCode.

type GetTileFunc

type GetTileFunc func(ctx context.Context, level, index uint64) (*api.Tile, error)

GetTileFunc is the signature of a function which knows how to fetch a specific tile.

type LogStateTracker

type LogStateTracker struct {
	Hasher  merkle.LogHasher
	Fetcher Fetcher
	// Origin is the expected first line of checkpoints from the log.
	Origin              string
	ConsensusCheckpoint ConsensusCheckpointFunc

	// LatestConsistentRaw holds the raw bytes of the latest proven-consistent
	// LogState seen by this tracker.
	LatestConsistentRaw []byte
	// LatestConsistent is the deserialised form of LatestConsistentRaw
	LatestConsistent log.Checkpoint
	// The note with signatures and other metadata about the checkpoint
	CheckpointNote *note.Note
	// ProofBuilder for building proofs at LatestConsistent checkpoint.
	ProofBuilder *ProofBuilder

	CpSigVerifier note.Verifier
}

LogStateTracker represents a client-side view of a target log's state. This tracker handles verification that updates to the tracked log state are consistent with previously seen states.

func NewLogStateTracker

func NewLogStateTracker(ctx context.Context, f Fetcher, h merkle.LogHasher, checkpointRaw []byte, nV note.Verifier, origin string, cc ConsensusCheckpointFunc) (LogStateTracker, error)

NewLogStateTracker creates a newly initialised tracker. If a serialised LogState representation is provided then this is used as the initial tracked state, otherwise a log state is fetched from the target log.

func (*LogStateTracker) Update

func (lst *LogStateTracker) Update(ctx context.Context) ([]byte, [][]byte, []byte, error)

Update attempts to update the local view of the target log's state. If a more recent logstate is found, this method will attempt to prove that it is consistent with the local state before updating the tracker's view. Returns the old checkpoint, consistency proof, and newer checkpoint used to update. If the LatestConsistent checkpoint is 0 sized, no consistency proof will be returned since it would be meaningless to do so.

type ProofBuilder

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

ProofBuilder knows how to build inclusion and consistency proofs from tiles. Since the tiles commit only to immutable nodes, the job of building proofs is slightly more complex as proofs can touch "ephemeral" nodes, so these need to be synthesized.

func NewProofBuilder

func NewProofBuilder(ctx context.Context, cp log.Checkpoint, h compact.HashFn, f Fetcher) (*ProofBuilder, error)

NewProofBuilder creates a new ProofBuilder object for a given tree size. The returned ProofBuilder can be re-used for proofs related to a given tree size, but it is not thread-safe and should not be accessed concurrently.

func (*ProofBuilder) ConsistencyProof

func (pb *ProofBuilder) ConsistencyProof(ctx context.Context, smaller, larger uint64) ([][]byte, error)

ConsistencyProof constructs a consistency proof between the two passed in tree sizes. This function uses the passed-in function to retrieve tiles containing any log tree nodes necessary to build the proof.

func (*ProofBuilder) InclusionProof

func (pb *ProofBuilder) InclusionProof(ctx context.Context, index uint64) ([][]byte, error)

InclusionProof constructs an inclusion proof for the leaf at index in a tree of the given size. This function uses the passed-in function to retrieve tiles containing any log tree nodes necessary to build the proof.