verify

Documentation

Overview

Package verify provides helpers used for verifying if the ingested data is correct.

Index

• type StateVerifier
  • func (v *StateVerifier) GetLedgerKeys(count int) ([]xdr.LedgerKey, error)
  • func (v *StateVerifier) Verify(countAll int) error
  • func (v *StateVerifier) Write(entry xdr.LedgerEntry) error
• type TransformLedgerEntryFunction

Types

type StateVerifier

type StateVerifier struct {
	StateReader ingest.ChangeReader
	// TransformFunction transforms (or ignores) ledger entries streamed from
	// checkpoint buckets to match the form added by `Write`. Read
	// TransformLedgerEntryFunction godoc for more information.
	TransformFunction TransformLedgerEntryFunction
	// contains filtered or unexported fields
}

StateVerifier verifies if ledger entries provided by Add method are the same as in the checkpoint ledger entries provided by CheckpointChangeReader. The algorithm works in the following way:

0. Develop TransformFunction. It should remove all fields and objects not stored in your app. For example, if you only store accounts, all other ledger entry types should be ignored (return ignore = true).
1. In a loop, get entries from history archive by calling GetEntries() and Write() your version of entries found in the batch (in any order).
2. When GetEntries() return no more entries, call Verify with a number of entries in your storage (to find if some extra entires exist in your storage).

Functions will return StateError type if state is found to be incorrect. It's user responsibility to call `StateReader.Close()` when reading is done. Check Horizon for an example how to use this tool.

func (*StateVerifier) GetLedgerKeys

func (v *StateVerifier) GetLedgerKeys(count int) ([]xdr.LedgerKey, error)

GetLedgerKeys returns up to `count` ledger keys from history buckets storing actual entries in cache to compare in Write.

func (*StateVerifier) Verify

func (v *StateVerifier) Verify(countAll int) error

Verify should be run after all GetEntries/Write calls. If there were no errors so far it means that all entries present in history buckets matches the entries in application storage. However, it's still possible that state is invalid when:

• Not all entries have been read from history buckets (ex. due to a bug).
• Some entries were not compared using Write.
• There are some extra entries in application storage not present in history buckets.

Any `StateError` returned by this method indicates invalid state!

func (*StateVerifier) Write

func (v *StateVerifier) Write(entry xdr.LedgerEntry) error

Write compares the entry with entries in the latest batch of entries fetched using `GetEntries`. Entries don't need to follow the order in entries returned by `GetEntries`. Warning: Write will call Normalize() on `entry` that can modify it! Any `StateError` returned by this method indicates invalid state!

type TransformLedgerEntryFunction

type TransformLedgerEntryFunction func(xdr.LedgerEntry) (ignore bool, newEntry xdr.LedgerEntry)

TransformLedgerEntryFunction is a function that transforms ledger entry into a form that should be compared to checkpoint state. It can be also used to decide if the given entry should be ignored during verification. Sometimes the application needs only specific type entries or specific fields for a given entry type. Use this function to create a common form of an entry that will be used for equality check.