Class HeaderChain

ReadonlybaseHeight

Readonlyparams

chainwork

• get chainwork(): bigint

  cumulative work from base to tip (sum of per-header expected work)

  Returns bigint

tipHash

• get tipHash(): string

  Returns string

tipHeight

• get tipHeight(): number

  Returns number

appendBatch

• appendBatch(raw: Uint8Array, opts?: { persist?: boolean }): number

  Validate and append count = raw.length/80 headers extending the tip. All headers validate before anything is committed or persisted.

  A prev-hash mismatch on the FIRST header (i.e. at tipHeight+1) throws the typed ReorgLinkError: it is the only failure that is evidence of a chain reorganization rather than a bad batch. Every other failure (PoW, bits, median-time-past, checkpoint, deep linkage break) is a plain Error and must never trigger a rewind.

  Parameters

  • raw: Uint8Array
  • opts: { persist?: boolean } = {}

  Returns number

captureState

• captureState(): HeaderChainState

  snapshot the in-memory state (headers, work, file-divergence flag)

  Returns HeaderChainState

flush

• flush(): void

  write the in-memory chain to the persistence file if it has diverged

  Returns void

hashAt

• hashAt(height: number): string | undefined

  Parameters

  • height: number

  Returns string | undefined

headerAt

• headerAt(height: number): BlockHeader | undefined

  Parameters

  • height: number

  Returns BlockHeader | undefined

restoreState

• restoreState(state: HeaderChainState): void

  restore a snapshot taken by captureState (memory only; file untouched)

  Parameters

  • state: HeaderChainState

  Returns void

truncateTo

• truncateTo(height: number, opts?: { persist?: boolean }): void

  Drop headers above height (reorg handling). With persist: false the rewind stays in memory (the file is rewritten once by the next persisting append or an explicit flush()).

  Parameters

  • height: number
  • opts: { persist?: boolean } = {}

  Returns void

Staticopen

• open(options: HeaderChainOptions): Promise<HeaderChain>

  Open a chain; when file exists its contents are appended through FULL validation (a tampered file cannot load). The first 80 bytes must be the configured base header.

  Parameters

  • options: HeaderChainOptions

  Returns Promise<HeaderChain>