headers

Documentation

Overview

Package headers is a chain tracker over the header read API of an overlay bridge (github.com/lightwebinc/overlay-bridge).

It is the root of trust for every proof checked against it. A transaction is only as trustworthy as the headers its BUMP is checked against, so the question of WHO answers "what root does height N commit to" is the whole security question, not a configuration detail. Pointing this at a public header service would mean trusting that service to tell the truth about the chain; pointing it at a bridge that received the headers itself, off the same network that delivered the transaction, does not.

It speaks HTTP and imports nothing from the bridge. That is deliberate: this module has exactly one direct dependency, and an HTTP contract plus a vendored fixture is a cheaper coupling than a Go dependency on a service. The fixtures in testdata/fixtures are the bridge's own generated bytes, copied verbatim, so a change to its wire shape fails here rather than in production.

Index

• Variables
• type Client
  • func New(base string) *Client
  • func (c *Client) CurrentHeight(ctx context.Context) (uint32, error)
  • func (c *Client) IsValidRootForHeight(ctx context.Context, root *chainhash.Hash, height uint32) (bool, error)

Variables

var ErrBodyTooLarge = errors.New("headers: response body exceeds the bound")

ErrBodyTooLarge refuses a response above the bound.

Types

type Client

type Client struct {
	// Base is the bridge's header read API base, with no path suffix.
	Base string
	// HTTP is optional.
	HTTP *http.Client
	// Timeout defaults to 10s when HTTP is nil.
	Timeout time.Duration
}

Client reads block headers from a bridge's native /v1 routes.

func New

func New(base string) *Client

New returns a client for base.

func (*Client) CurrentHeight

func (c *Client) CurrentHeight(ctx context.Context) (uint32, error)

CurrentHeight reports the header service's tip.

Needed as well as root validation, not instead of it: a health check reports how far the header source has got, and a service that answers roots while reporting height zero is a service that has not started.

func (*Client) IsValidRootForHeight

func (c *Client) IsValidRootForHeight(ctx context.Context, root *chainhash.Hash, height uint32) (bool, error)

IsValidRootForHeight reports whether root is the merkle root committed at height.

A 404 is (false, nil): the bridge does not hold that height yet, which means the proof cannot be checked, not that anything is broken. Any OTHER non-ok status is an ERROR, and the distinction is load-bearing. Collapsing the two makes an unreachable or misconfigured header service look exactly like a forged proof, and a verifier that cannot tell those apart will either accept forgeries during an outage or reject good proofs during one, depending on which way it guessed.