> For the complete documentation index, see [llms.txt](https://bitcoin-everlight.gitbook.io/bitcoin-everlight-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bitcoin-everlight.gitbook.io/bitcoin-everlight-docs/developer-updates/developer-update-2-state-handling-fee-logic-validation-pipeline-and-node-onboarding.md).

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

{% hint style="success" %}
**Status:** Internal testnet / controlled simulation phase
{% endhint %}

***

### 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

```go
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)

```go
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

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

    return baseFee + sizeFee
}
```

#### Minimum Fee Enforcement

```go
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.

```go
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:

```go
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)

```go
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.