@cogcoin/indexer

@cogcoin/[email protected] is the pure-function Cogcoin indexer kernel for developers building clients, sync engines, explorers, and other protocol tooling. It exposes deterministic block transition APIs, rewindable block records, state hashing, and explicit query/type subpaths while delegating canonical mining settlement to @cogcoin/scoring.

Use Node 18 or newer.

Links

• Website: cogcoin.org
• Whitepaper: cogcoin.org/whitepaper.md
• Source: github.com/cogcoin/indexer
• Genesis package: npmjs.com/package/@cogcoin/genesis
• Scoring package: npmjs.com/package/@cogcoin/scoring

Quick Start

Install the package:

npm install @cogcoin/indexer

Then, from your project root, run:

node node_modules/@cogcoin/genesis/verify.mjs

Verify the installed genesis artifacts before using the indexer in a production implementation.

Dependency Surface

The published package keeps its runtime dependency surface intentionally small:

• @cogcoin/[email protected]
• @cogcoin/[email protected]

The package does not ship a store, sync loop, transport, database adapter, or CLI. Applications are expected to own persistence and orchestration around the pure state machine.

API

State lifecycle:

• loadBundledGenesisParameters()
• createInitialState(genesisParameters)
• prepareBlock(state, block, genesisParameters)
• finalizePreparedBlock(preparedBlock, miningSettlementResult)
• applyBlockWithScoring(state, block, genesisParameters)
• rewindBlock(state, blockRecord)

State hashing and serialization:

• computeStateHash(consensusState, blockHeight)
• computeStateHashHex(consensusState, blockHeight)
• serializeConsensusState(...)
• deserializeConsensusState(...)
• serializeHistoryState(...)
• deserializeHistoryState(...)
• serializeIndexerState(...)
• deserializeIndexerState(...)
• serializeBlockRecord(...)
• deserializeBlockRecord(...)

Query subpath:

• @cogcoin/indexer/queries

Type subpath:

• @cogcoin/indexer/types

Apply a Block

import {
  applyBlockWithScoring,
  createInitialState,
  loadBundledGenesisParameters,
} from "@cogcoin/indexer";
import { getBlockWinners, lookupDomain } from "@cogcoin/indexer/queries";

const genesis = await loadBundledGenesisParameters();
let state = createInitialState(genesis);

const bitcoinBlock = {
  height: 937338,
  // Block hashes use Bitcoin internal byte order, not JSON-RPC display hex.
  hash: new Uint8Array(32),
  previousHash: new Uint8Array(32),
  transactions: [],
};

const applied = await applyBlockWithScoring(state, bitcoinBlock, genesis);
state = applied.state;

const domain = lookupDomain(state, "alpha");
const winners = getBlockWinners(state, bitcoinBlock.height);

The package never mutates the input state. Every block application returns a new state plus a reversible block record.

Historical Query Support

The kernel stores the whitepaper's non-consensus query data directly in history:

• founding messages from DOMAIN_ANCHOR
• reviews from REP_COMMIT and REP_REVOKE
• mining winner history by block height
• resolved lock history by recipient domain
• field write and clear history
• chronological domain event logs
• Cogcoin explorer block and transaction result history

These values are rewinded exactly with the same journal mechanism as consensus state, but they do not participate in the state hash.

Critical Clarifications

• BitcoinBlock.hash and BitcoinBlock.previousHash must use Bitcoin internal byte order, not JSON-RPC display-order hex.
• Sender identity is always the prevout scriptPubKey of input 0.
• Transactions are processed strictly in block order, and mining settlement runs after the transaction loop for the block.
• The package uses @cogcoin/scoring for canonical mining settlement. Conforming implementations must not use the scoring WASM export settle_block_wasm as an indexer shortcut.
• Founding messages, reviews, winner history, resolved lock history, domain event logs, and explorer history are protocol-level stored data, but they do not affect validation or any state hash field.

Published Contents

• dist/index.js: public package entrypoint
• dist/index.d.ts: bundled type declarations
• dist/queries.js: selector subpath entrypoint
• dist/public-types.d.ts: public type subpath declarations
• dist/*: compiled ESM implementation
• README.md: package guide
• LICENSE: MIT license text