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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bitcoin-everlight.gitbook.io/bitcoin-everlight-docs/developer-updates/developer-update-2-state-handling-fee-logic-validation-pipeline-and-node-onboarding.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.