chaintoolkit

README

chaintoolkit

a simple toolkit to instrument blockchain blocks (essentially linked lists).

BlockGapsFinder

The finder allows to spot gaps in blocks, it finds all possible chains that blocks may form and returns result that can be inspected by code or printed in a human readable table format. The algorithm only tracks head and tail of a chain but not blocks in between. Therefore it is possible to feed blocks by batches and save resource usage. It also has drawbacks such as not all possible fork blocks nor cycled chains can be spotted, the algorithm is sensitive to duplicates, the calling code must make sure to not provide them. For instance:

SELECT COUNT(*), block_hash FROM blocks GROUP BY block_hash HAVING COUNT(*) > 1;
SELECT COUNT(*), prev_hash FROM blocks GROUP BY prev_hash HAVING COUNT(*) > 1;

Keep in mind that LIMIT OFFSET pagination consumes a lot of memory if there huge amounts of blocks, such a pagination also gives duplicates without sorting. The better way to paginate blocks is by height, since most of blockchains use height of a block as its id that increments sequentially.

code example

blks := []*chaintoolkit.Block{
  &chaintoolkit.Block{BlockHash: "h1", PrevHash: "h0", Time: time.Now()},
  &chaintoolkit.Block{BlockHash: "h2", PrevHash: "h1", Time: time.Now()},
}

blks2 := []*chaintoolkit.Block{
  &chaintoolkit.Block{BlockHash: "b1", PrevHash: "b0", Time: time.Now()},
  &chaintoolkit.Block{BlockHash: "h3", PrevHash: "h2", Time: time.Now()},
}

bg := chaintoolkit.NewBlockGapsFinder()

if err := bg.Append(blks...); err != nil {
	log.Fatal(err)
}

if err := bg.Append(blks2...); err != nil {
	log.Fatal(err)
}

res := bg.Result()

chains := res.Chains()

for _, c := range chains {
  fmt.Println(c.Length, c.Head, c.Tail)
}

res.Print(os.Stdout)

ForkBlocksFinder

not implemented

CycledChainsFinder

not implemented

Documentation

Index

• type Block
• type BlockGapsFinder
  • func NewBlockGapsFinder() *BlockGapsFinder
  • func (bg *BlockGapsFinder) Append(blks ...*Block) error
  • func (bg *BlockGapsFinder) Result() *BlockGapsResult
• type BlockGapsResult
  • func (bgr *BlockGapsResult) Chains() map[string]*Chain
  • func (bgr *BlockGapsResult) ChainsAsArray() []*Chain
  • func (bgr *BlockGapsResult) Print(w io.Writer)
• type Chain

Types

type Block

type Block struct {
	// BlockHash is a current block hash.
	BlockHash string

	// PrevHash is a hash that points to the previouse block.
	PrevHash string

	// Time is time of a block.
	Time time.Time
}

Block represents a link in the chain with a block hash and previous hash.

type BlockGapsFinder

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

BlockGapsFinder searches for all possible chains that blocks may form, a head, tail and length are found for each chain. It doesn't track all blocks along a chain, but keeps only head and tail, therefore not all forks and cycles can be spotted, also the current algorithm doesn't find duplicates.

func NewBlockGapsFinder

func NewBlockGapsFinder() *BlockGapsFinder

NewBlockGapsFinder returns an instance of *BlockGapsFinder.

func (*BlockGapsFinder) Append

func (bg *BlockGapsFinder) Append(blks ...*Block) error

Append inpects given blocks and appends info to already inspected. It helps to reduce resource usage during debugging large amount of blocks.

func (*BlockGapsFinder) Result

func (bg *BlockGapsFinder) Result() *BlockGapsResult

type BlockGapsResult

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

BlogGapsResult is a result returned after inspecting blocks, it contains info about chains that blocks organized.

func (*BlockGapsResult) Chains

func (bgr *BlockGapsResult) Chains() map[string]*Chain

Chains returns all found chains.

func (*BlockGapsResult) ChainsAsArray

func (bgr *BlockGapsResult) ChainsAsArray() []*Chain

ChainsAsArray returns all found chains, it converts a map of chains to an array.

func (*BlockGapsResult) Print

func (bgr *BlockGapsResult) Print(w io.Writer)

Print prints a debug info to w.

type Chain

type Chain struct {
	Head   *Block
	Tail   *Block
	Length int
}

Chain represents an info of a single chain.