Developer Update #2 – State Handling, Fee Logic, Validation Pipeline & Node Onboarding

2026-01-30

Status: Internal testnet / controlled simulation phase

---

Overview

This update documents the next phase of active development on the Bitcoin Everlight network, building directly on the transaction prototype and lifecycle validation described in Developer Update #1.

With the base transaction flow now validated end-to-end, current work has shifted toward state handling, fee calculation, deterministic validation, and preliminary node onboarding design.

The goal of this phase is to ensure predictable, reproducible behavior across Everlight nodes before introducing public participation or on-chain anchoring.

---

Scope of This Update

This update covers implementation and testing of:

• Deterministic transaction state transitions

• Canonical validation pipeline

• Fee calculation and enforcement logic

• Canonical transaction hashing

• Replay protection and internal indexing

• Transaction lifecycle sequencing

• Bitcoin anchoring interface design (non-final)

• Public node onboarding specification (initial)

Consensus finalization and live Bitcoin anchoring remain explicitly out of scope for this phase.

---

Transaction State Model

Everlight transactions move through a strict, explicit state machine once received by a node.

Transaction States

RECEIVED
  ↓
VALIDATED
  ↓
QUEUED
  ↓
ACCEPTED
  ↓
SETTLED (post-anchoring, future phase)

Each transition is:

• Deterministic

• Idempotent

• Explicitly recorded

This prevents inconsistent node behavior across restarts or repeated processing.

Internal State Representation

type TxState uint8

const (
    TxReceived TxState = iota
    TxValidated
    TxQueued
    TxAccepted
    TxSettled
)

Transaction state is persisted locally using a lightweight key-value store to allow safe recovery after node restarts.

---

Transaction Lifecycle – Sequence Overview

Submission & Validation Flow

Client
  |
  | submitTransaction(tx)
  |
  v
Everlight Node
  |
  |-- validateStructure(tx)
  |-- verifySignature(tx)
  |-- checkNonce(tx)
  |-- validateFee(tx)
  |
  v
Transaction State = VALIDATED

Only transactions that pass all validation steps are admitted into the node’s internal queue.

---

Acceptance & Indexing Flow

Queued Transaction
  |
  |-- assignCanonicalHash(tx)
  |-- indexByHash(tx)
  |-- indexBySenderNonce(tx)
  |
  v
Transaction State = ACCEPTED

At this stage, the transaction is locally accepted but not finalized or anchored to Bitcoin.

---

Validation Pipeline

Incoming transactions pass through a strict validation pipeline prior to acceptance.

Validation Stages

1. Structural validation (format, bounds, required fields)

2. Signature verification

3. Nonce and replay checks

4. Fee validation

5. State consistency verification

Validation Flow (Simplified)

func ValidateTransaction(tx *Transaction) error {
    if err := ValidateStructure(tx); err != nil {
        return err
    }

    if err := VerifySignature(tx); err != nil {
        return err
    }

    if err := CheckNonce(tx); err != nil {
        return err
    }

    if err := ValidateFee(tx); err != nil {
        return err
    }

    return nil
}

Only transactions that pass all checks transition to the VALIDATED state.

---

Fee Calculation & Enforcement

This phase introduces the initial Everlight fee model, designed to be:

• Predictable

• Transparent

• Resistant to spam

• Independent of volatile mempool bidding

Fee Inputs

Fees are derived from:

• Transaction size (bytes)

• Base network fee constant

• Optional priority multipliers (future use)

Fee Calculation Example

func CalculateFee(txSizeBytes int) uint64 {
    baseFee := uint64(100)
    sizeFee := uint64(txSizeBytes) * 2

    return baseFee + sizeFee
}

Minimum Fee Enforcement

func ValidateFee(tx *Transaction) error {
    required := CalculateFee(tx.Size())

    if tx.Fee < required {
        return errors.New("insufficient transaction fee")
    }

    return nil
}

This ensures consistent fee behavior across nodes and prevents under-priced transaction spam.

---

Canonical Transaction Hashing

To guarantee deterministic behavior across implementations, Everlight uses canonical serialization prior to hashing.

func CanonicalHash(tx *Transaction) []byte {
    data := SerializeCanonical(tx)
    hash := sha256.Sum256(data)
    return hash[:]
}

This prevents discrepancies caused by field order or serialization differences.

---

Internal State Indexing

Nodes maintain multiple internal indexes to efficiently manage the transaction lifecycle:

type TxIndex struct {
    Pending  map[string]*Transaction
    Accepted map[string]*Transaction
    Nonces   map[string]uint64
}

Indexes currently operate in memory with periodic persistence. Disk-backed indexing will be introduced in later phases.

---

Bitcoin Anchoring – Interface & Pseudocode (Non-Final)

Bitcoin anchoring remains a core design objective but is intentionally not live.

Current work focuses on defining a clean interface and deterministic commitment structure prior to on-chain integration.

Anchoring Design Principles

• Batch-based commitments

• Fee amortization across transactions

• Deterministic commitment payloads

• Verifiable post-factum anchoring

Commitment Construction (Pseudocode)

func BuildAnchorCommitment(txs []*Transaction) []byte {
    root := ComputeMerkleRoot(txs)
    timestamp := uint64(time.Now().Unix())

    payload := AnchorPayload{
        Root:      root,
        Timestamp: timestamp,
        Version:   1,
    }

    return Serialize(payload)
}

Planned Anchoring Flow

Accepted Transactions
  |
  |-- batchTransactions()
  |
  |-- buildAnchorCommitment()
  |
  |-- submitBitcoinTransaction()
  |
  v
Transaction State = SETTLED

Final anchoring mechanics will be documented once batching behavior is finalized and tested.

---

Public Node Onboarding – Initial Specification

This phase introduces the early design for public Everlight node participation.

The goal is to allow external operators to run nodes without compromising network stability or test integrity.

---

Node Types

• Observer Nodes

  • Read-only

  • Validate transactions

  • Do not participate in anchoring

• Participant Nodes

  • Validate and queue transactions

  • Participate in batching

  • Eligible for future anchoring roles

---

Onboarding Requirements (Draft)

Public node operators must:

• Run a compatible Everlight node binary

• Expose required network endpoints

• Maintain deterministic validation behavior

• Pass initial health and synchronization checks

Node Registration Flow

Operator
  |
  | registerNode(metadata)
  |
  v
Everlight Network
  |
  |-- validateNodeConfig()
  |-- syncState()
  |
  v
Node Status = ACTIVE

During early phases, onboarding may be gated to ensure controlled testing conditions.

---

Explicitly Out of Scope

To avoid ambiguity, the following are not implemented or promised at this stage:

• Permissionless anchoring participation

• Incentive or reward distribution

• Staking or slashing mechanics

• Consensus leader election

• Mainnet guarantees

These systems require additional design and testing and will be introduced only after core correctness is proven.

---

Current Status

At the time of this update:

• Transaction state transitions are deterministic and stable

• Fee logic is implemented and tested

• Validation pipeline is consistent under simulated load

• Canonical hashing prevents replay discrepancies

• Internal indexing supports restart recovery

• Anchoring interfaces are defined but inactive

• Node onboarding design is under active development

---

Next Development Focus

Upcoming phases will focus on:

• External node onboarding tests

• Anchor batching under load

• Observability and metrics instrumentation

• Fault injection and recovery testing

• Controlled external testnet deployment

Each milestone will be documented in subsequent developer updates.

---

Closing Notes

This update reflects a transition from internal prototyping toward controlled external participation.

The development approach remains intentionally incremental, prioritizing correctness, determinism, and transparency over feature breadth or speed.

Future updates will continue to document concrete implementation progress rather than speculative design.