[ANN] Finalis-Core | finalized-state UTXO System

Finalis Core
Deterministic Finalized-State UTXO System

Bond state is derived from finalized UTXO set / validator registry state

https://github.com/reikagitakashi-bot

What it is

finalis-core is a finalized-state blockchain.

Its model is simple:

Code:

state(h+1) = Apply(finalized_block(h+1), state(h))
height = finalized_height + 1

Wallets, explorers, operators, and exchanges are intended to read finalized state directly.

Settlement happens only after finalization.

Who uses it and how

Users

Users use wallets to:

hold keys
receive coins
send transactions
check finalized balance and history

User flow:

Code:

create/import wallet
|
v
receive address
|
v
send or receive transaction
|
v
transaction is relayed
|
v
transaction is finalized
|
v
wallet updates finalized balance/history

Operators

Operators run infrastructure:

nodes
lightserver RPC
explorer
validator onboarding

Operator flow:

Code:

run node
|
v
connect peers
|
v
serve finalized-state RPC
|
v
if validating:
  onboard validator
  join operator set
  participate in committee/finality

Exchanges

Exchanges should use finalized-state RPC only.

They use:

`get_status`
`validate_address`
`get_history_page`
`get_utxos`
`get_tx_status`
`get_tx`

Exchange rule:

Code:

submission != settlement
finalized == settlement truth

Deposit flow:

Code:

validate address
|
v
watch finalized history / tx status
|
v
confirm finalized + credit_safe
|
v
credit user

Withdrawal flow:

Code:

build tx from finalized UTXOs
|
v
broadcast_tx
|
v
wait for finalized tx status
|
v
mark withdrawal complete

Developers

Developers use the repo to work on:

consensus/runtime
lightserver RPC
desktop wallet
explorer
mobile wallet
formal models and simulator

System parts

finalis-node — validation, finalized execution, consensus runtime
finalis-lightserver — finalized-state JSON-RPC
finalis-explorer — finalized-state HTTP UI and thin REST layer
finalis-wallet — desktop wallet
finalis-mobile — mobile wallet project
finalis-mint — service-layer finalized-depth-aware mint service

The repository also includes:

formal models
simulator tooling
conformance fixtures/tests

Ledger

The ledger is:

UTXO-based
deterministic
bounded in validation cost

Block validation requires:

block correctness
quorum certificate validity
finalized transition continuity

Finality

Let:

Code:

N = committee size
Q = floor(2N/3) + 1

Votes are bound to:

Code:

(height, round, block_id)

A block is finalized when a valid quorum certificate exists for that block at that height.

High-level rule:

Code:

finalized(H, B) := valid QC(H, B)
state(H) = Apply(B(H), state(H-1))

Finalized history is monotonic.

Transaction lifecycle

Code:

User
|
v
broadcast_tx
|
v
relay admission
|
v
proposer includes tx in block
|
v
committee votes
|
v
quorum certificate formed
|
v
block finalized
|
v
get_tx_status.finalized = true

Important rule:

Code:

relay admission != settlement
finalized inclusion == settlement

Committee and checkpoint model

Committee state is derived deterministically from finalized checkpoints.

High-level form:

Code:

committee(height) = Select(checkpoint(epoch(height)), operator set, constraints)

Checkpoint derivation uses finalized history only.

At epoch boundaries:

Code:

qualified operator depth
|
v
adaptive target committee size
adaptive minimum eligible
adaptive minimum bond
|
v
deterministic checkpoint
|
v
committee + proposer schedule

Future committee eligibility is gated by finalized availability state.

Operator model

Operators are aggregated natively.

High-level weighting form:

Code:

E_i = effective bond of operator i
w_i = floor(sqrt(E_i))

This is intended to reduce simple sybil amplification from linear splitting.

Properties:

aggregation by operator
bounded committee selection path
availability-gated future eligibility

Liveness and failure model

Safety assumption:

Code:

f < N/3

Under sufficient honest quorum participation and bounded delay, new heights eventually finalize.

If quorum participation drops below threshold, the intended behavior is halt, not unsafe progression.

Attack model

Byzantine minority below 1/3

safety preserved
conflicting finalization should not occur

Byzantine power at or above 1/3

liveness may fail
safety assumptions weaken beyond the design threshold

Sybil / splitting

operator aggregation reduces identity amplification
non-linear weighting reduces split advantage

Availability manipulation

future eligibility is gated by finalized availability state
checkpoint derivation enforces retention/eligibility rules

Relay / mempool

relay state is not settlement truth
mempool visibility is not crediting truth

RPC surface

Core external methods:

`get_status`
`get_tx_status`
`get_tx`
`get_utxos`
`get_history_page`
`validate_address`
`broadcast_tx`

Interpretation:

`broadcast_tx` = submission
`get_tx_status.finalized = true` = finalized transaction
`credit_safe = true` = safe for exchange crediting

Apps and services

Desktop wallet

finalis-wallet is the Qt desktop wallet.

It provides:

local keystore
finalized balance and history
send / receive
validator onboarding
advanced diagnostics

Explorer

finalis-explorer provides:

finalized height
finalized transition hash
committee view
address / tx / transition lookup

Mobile

finalis-mobile is the mobile wallet project.

It is being aligned to the same finalized-state model:

lightserver-backed state
submitted-to-finalized reconciliation
finalized-history-based activity

Mint service

finalis-mint is service-layer infrastructure built on finalized-state truth.

It handles:

deposit registration
issuance
redemption tracking

Monetary policy

Code:

Primary issuance: 7,000,000 FLS
Block interval: 180 seconds
Primary duration: 3,504,000 blocks (~20 years)
Tail emission: 0.1 FLS per block forever

This means:

primary issuance is finite: 7,000,000 FLS
after that, tail emission continues
the system is not a strict infinite-horizon hard cap

Coins are generated by protocol block issuance and distributed over time through live network participation and reward settlement.

Monetary timeline

Code:

Genesis ---------------------------------------------- Year 20 ---------->

[ primary issuance: 7,000,000 FLS total ]

After Year 20 --------------------------------------->

[ tail emission: 0.1 FLS / block forever ]

Summary

Code:

Finalis Core is a deterministic finalized-state UTXO system.

Users use wallets.
Operators run nodes and RPC.
Exchanges settle from finalized state only.

Submission is not settlement.
Finalization is settlement.
Committee and checkpoint state are derived deterministically from finalized history.

https://github.com/reikagitakashi-bot

Spec ↔ Code Mapping (Current C++ Paths)

1. Finalized-state runtime model

Spec statement

Code:

state(h+1) = Apply(finalized_block(h+1), state(h))
height = finalized_height + 1

Code surface

apps/finalis-node/main.cpp — node process entry, runtime wiring, service startup
src/node/node.hpp / src/node/node.cpp — node runtime, status surface, finalized progression, restart/rebuild behavior

What to verify in code

runtime advances from finalized state, not speculative longest-chain state
status surface reports finalized progression explicitly
restart path rebuilds consensus/runtime state from persisted finalized artifacts

2. Proposal / vote / QC binding

Spec statement

Code:

vote := sig(height, round, block_id)
QC   := signatures >= floor(2N/3)+1 on identical (height, round, block_id)

Code surface

src/consensus/ — proposal validation, vote payload validation, quorum certificate assembly and verification
docs/CONSENSUS.md — live consensus behavior reference
docs/PROTOCOL-SPEC.md / spec/SELFCOIN_CONSENSUS_V0.md equivalents in your renamed tree

What to verify in code

vote payload signs exact tuple (height, round, block_id)
QC verification rejects mixed payloads
proposal validation rejects mismatched QC height
proposal validation rejects qc.round >= proposal.round
proposal validation rejects QC whose payload does not match proposed block

3. Finalization rule

Spec statement

Code:

finalized(H,B) := exists valid QC(H,B)

Code surface

src/consensus/ — QC acceptance, finalization trigger, finalized-chain extension
src/node/node.cpp — finalized-state transition into node-visible state
src/lightserver/server.cpp — finalized-only external read surface

What to verify in code

a block becomes externally visible only after finalization path completes
finalized state is persisted before external finalized surfaces report it
finality certificate / signer set is canonicalized deterministically

4. Safety invariant: no double finalization

Spec statement

Code:

not exists B != B' such that finalized(H,B) and finalized(H,B')

Code surface

src/consensus/ — conflicting vote/QC rejection, round/height consistency checks
tests/test_integration.cpp
tests/test_lightserver.cpp

What to verify in code

conflicting QCs at same height cannot both pass validation
vote/QC checks are keyed by exact height and round
integration tests assert monotonic finalized visibility after restart

5. Committee derivation from finalized checkpoint

Spec statement

Code:

committee(H) = f(checkpoint(epoch(H)))

Code surface

docs/COMMITTEE-SELECTION.md
src/consensus/ — committee derivation and proposer schedule
src/node/node.cpp — runtime exposure of committee-related status

What to verify in code

committee for height H is derived from finalized checkpoint for epoch(H)
committee derivation is pure/deterministic from finalized inputs
restart does not depend on reconstructing non-finalized ticket visibility

6. Validator lifecycle from finalized history

Spec statement

Code:

validator lifecycle changes come only from finalized history

Code surface

src/consensus/ — validator join/active/eligibility transitions
docs/LIVE_PROTOCOL.md
docs/PROTOCOL-SPEC.md

What to verify in code

join / activation / retention / eviction are applied only from finalized transitions
future committee eligibility references finalized-derived lifecycle state
no peer-local observation changes validator lifecycle authority

7. Availability-gated future eligibility

Spec statement

Code:

future checkpoint eligibility is gated by finalized availability state

Code surface

src/availability/ — availability state, retention, projected eligibility, suite evaluation
docs/spec/AVAILABILITY_STATE_COMPLETENESS.md
docs/spec/CHECKPOINT_DERIVATION_SPEC.md

What to verify in code

eligibility input is derived from finalized availability state, not local gossip
checkpoint builder consumes projected/qualified operator depth deterministically
fallback or sticky fallback modes are explicit and observable

8. Adaptive checkpoint parameters

Spec statement

Code:

D := qualified operator depth

target_committee = f1(D)
min_eligible     = f2(D)
min_bond         = f3(D)

Code surface

src/availability/retention.hpp
src/availability/retention.cpp
tests/test_availability.cpp

What to verify in code

derivation is deterministic and parameterized only by finalized-derived inputs
target/min-eligible/min-bond are surfaced in diagnostics/status
default baseline and sensitivity helpers agree with live derivation formulas

9. Operator aggregation and anti-sybil weighting

Spec statement

Code:

E_i := effective bond of operator i
w_i := floor(sqrt(E_i))
one selection path per operator

Code surface

docs/OPERATOR-MODEL.md
docs/ECONOMICS.md
scripts/attack_model.py or renamed attack simulator path
src/consensus/ — operator aggregation in committee input formation

What to verify in code

operator identity is derived from finalized registry / payout identity, not local aliasing
multiple validator pubkeys under one operator collapse to one operator path for selection purposes
effective weight uses the live non-linear rule, not raw split stake sum

10. Bounded ticket PoW as secondary input

Spec statement

Code:

ticket PoW is bounded and secondary inside committee selection

Code surface

docs/POW-AND-DIFFICULTY.md
src/consensus/ — ticket generation / ranking / committee admission pipeline

What to verify in code

nonce/work range per validator or operator is bounded
best-ticket selection is deterministic for identical finalized inputs
ticket competition affects ordering/admission only inside the bounded committee rule

11. Deterministic reward settlement

Spec statement

Code:

new coins = scheduled issuance
reward settlement = deterministic on-chain rule

Code surface

src/consensus/monetary/
docs/REWARD-SETTLEMENT.md
src/common/network.cpp — economics schedule / activation gating

What to verify in code

fee and issuance paths are separated exactly as specified
epoch settlement uses finalized signer set only
inactive signers receive zero reward weight
activation height changes economics without changing consensus ambiguity

12. Finalized-only RPC contract

Spec statement

Code:

broadcast_tx -> submission
finalized inclusion -> settlement

Code surface

src/lightserver/server.cpp
tests/test_lightserver.cpp

Methods

get_status
get_tx_status
get_tx
get_utxos
get_history_page
validate_address
broadcast_tx — submission only

What to verify in code

no method leaks speculative/non-finalized chain state
get_status reports finalized height/hash semantics, not generic tip semantics
get_tx_status distinguishes submission from finalization cleanly

13. Explorer as thin finalized-state consumer

Spec statement

Code:

explorer reads finalized state through lightserver

Code surface

finalis-explorer app paths
src/lightserver/server.cpp

What to verify in code

explorer does not maintain its own speculative consensus view
address / tx / transition routes resolve only against finalized data
pagination and cursor behavior are deterministic for finalized history

14. Address / key model

Spec statement

Code:

Ed25519 keys
P2PKH
HASH160(pubkey)
HRP: sc / tsc

Code surface

docs/ADDRESSES.md
src/common/ and wallet/address utility code

What to verify in code

pubkey serialization is fixed-width and canonical
address encoding/decoding rejects malformed payloads deterministically
validate_address matches wallet/address library behavior exactly

15. Persistence / restart determinism

Spec statement

Code:

same finalized history => identical reconstructed runtime state

Code surface

src/node/node.cpp
src/consensus/
tests/test_integration.cpp

What to verify in code

restart rebuilds committee/finality/reward state from finalized artifacts only
persisted finality certificates are canonicalized before reuse
node does not require hidden transient caches for correct replay

16. Adversarial / quantitative model linkage

Spec statement

Code:

operator aggregation + non-linear weighting constrain split amplification

Code surface

scripts/attack_model.py
docs/QUANTITATIVE_ATTACK_MODEL.md
scripts/protocol_attack_sim.py if this is the live renamed simulator

What to verify in code and models

the simulator uses the same operator aggregation rule as live committee selection
seat-budget / threshold math matches live economics assumptions
split-amplification comparisons use common randomness/seed streams across scenarios

17. Minimum audit checklist

Every externally visible finalized-state claim should map to either src/node/, src/consensus/, or src/lightserver/
Every adaptive checkpoint claim should map to src/availability/
Every monetary-policy claim should map to src/consensus/monetary/ and src/common/network.cpp
Every adversarial claim should be consistent across docs, simulator, and runtime rule names

18. Reviewer rule

If a spec statement cannot be pointed to in:

Code:


* a live C++ path
* a test
* or a deterministic diagnostic surface

https://github.com/reikagitakashi-bot