Protocol overview

Status and normative language

This documentation describes the behavior implemented by the Python reference node and JavaScript wallet at release 0.1.0. It is an alpha specification, not a frozen public-network constitution. P2P v2, consensus serialization, state rules, and local interfaces may change before a public testnet or mainnet.

Within this reference:

• MUST, MUST NOT, REQUIRED, and REJECT identify conditions the current implementation treats as consensus, framing, or trust-boundary requirements.
• SHOULD identifies operational guidance that prevents unsafe but technically possible configurations.
• MAY describes optional local behavior that does not change consensus.
• Roadmap means absent from the current implementation and must not be relied upon.

When prose, examples, and executable behavior diverge, use this authority order:

1. canonical serialization and validation source;
2. positive and negative tests plus vectors.json;
3. this documentation;
4. product mockups, screenshots, historical READMEs, and roadmap documents.

Protocol layers

Luracoin is one account-model proof-of-work chain with several adjacent protocols:

Layer	Contract	Consensus-critical
Address	Versioned Base58Check encoding of a compressed secp256k1 public-key hash.	Yes, where address validity affects transactions and miners.
Transaction	Fixed 85-byte unsigned body plus 128-byte unlocking field.	Yes
Block	Fixed 118-byte transmitted header plus zero or more 213-byte transaction slots; valid blocks require at least one transaction.	Yes
State transition	Ordered debit, nonce, credit, reward, and overflow rules over account balances.	Yes
Proof of work	Double-SHA256 block ID compared numerically with a compact target.	Yes
P2P v2	TCP framing, handshake, discovery, sync, inventory, blocks, and transactions.	Network protocol; some payloads carry consensus objects.
RPC v1	Authenticated loopback HTTP for wallets.	No; it exposes and admits consensus objects.
Explorer API	Public read-only HTTP projection of canonical state.	No
Wallet gateway	Same-origin local adapter to the private RPC.	No

The RPC, explorer API, wallet UI, and SQLite explorer index do not participate in consensus. A bug or stale value in those projections does not change what Block.validate() accepts.

Network identity

Every runtime selects exactly one namespace:

Network	Chain ID	P2P magic	Genesis state
mainnet	0	ba77d89f	Undefined; initialization rejects before disk access.
testnet	1	fbc0b6db	Fixed educational manifest with a known historical key.
devnet	2	faceb00c	Fixed educational manifest with a known historical key.

The chain ID is committed into every transaction and v2 VERSION handshake. P2P magic is committed into every transport frame. A normal transaction with the wrong chain ID is invalid even if its signature and balances would otherwise be valid.

Network selection also isolates data directories, Redis DB defaults, RPC ports, and explorer ports. Those are runtime protections rather than consensus fields, but violating the isolation can corrupt the operator’s view and is unsupported.

P2P v1 is wire-incompatible with v2. Old prototype block files, hashes, signatures, and state must not be opened as a v2 chain.

Units and integer domains

The atomic unit is the lurashi:

1 LURA = 100,000,000 lurashis

Consensus uses integers only. There is no floating-point arithmetic in balance validation, fee accounting, reward calculation, serialization, or proof of work.

Key numeric domains include:

• chain ID: unsigned 8-bit;
• transaction nonce and fee: unsigned 32-bit;
• transaction value and account balance: unsigned 64-bit;
• block version, height, timestamp, and proof nonce: unsigned 32-bit;
• transaction count: unsigned 16-bit, further constrained to 1–65,535 for a block.

The JSON interfaces serialize monetary values as decimal strings because JavaScript numbers cannot represent every uint64 exactly.

Canonical object graph

The canonical chain is a linear sequence of blocks:

genesis block
  └─ block 1 (prev = genesis.id)
      └─ block 2 (prev = block1.id)
          └─ ... one accepted local tip

Each block contains a leading coinbase and zero or more normal transactions. Each normal transaction moves value between account addresses and advances exactly one sender nonce. The coinbase creates the block subsidy and collects regular transaction fees.

The implementation currently stores only the next block extending the local tip. It does not store side branches, compare cumulative work, disconnect state, or reorganize. Therefore the graph above is the implemented storage model, not a secure fork-choice result.

Transaction lifecycle

A normal transaction moves through these conceptual stages:

1. A wallet reads confirmed account state and a contiguous pending view from local RPC.
2. The wallet creates the 85 canonical unsigned bytes.
3. The sender signs their SHA-256 digest with deterministic low-S secp256k1 ECDSA.
4. The wallet appends the raw public-key coordinates and compact signature, producing exactly 213 bytes.
5. The node validates structural fields, active chain ID, derived sender address, signature, balance, and nonce.
6. Redis atomically reserves the tuple (chain, sender, nonce) and stores the canonical payload by transaction ID.
7. The node relays the transaction to peers or retains it in a bounded process-local retry backlog.
8. A miner selects a sequentially valid fee-ordered subset.
9. A block validates the complete ordered account transition.
10. Persistence commits block bytes, account updates, and canonical indexes through separate idempotent boundaries.
11. The included payload and any competing candidate occupying the same sender/nonce slot are removed from the mempool.

Mempool admission is not consensus finality. A different valid transaction can consume the same sender/nonce in a received block, and a node restart does not reconstruct pending state from the chain.

Block lifecycle

A mining node builds the next block only while it is locally ready:

1. Read the current tip and choose height = tip + 1.
2. Select sequentially valid normal transactions from Redis.
3. Sum their fees.
4. Construct a unique leading coinbase whose nonce equals the block height.
5. Set version 1, previous ID, monotonic timestamp, and the only permitted difficulty bits.
6. Iterate the unsigned 32-bit proof nonce until int(block.id, 16) <= target.
7. Revalidate and persist the complete block.
8. Announce its hash through inventory to peers.

Mining is interrupted when a peer delivers the expected valid block or when a higher peer begins synchronization. If a peer wins after the last proof iteration but before persistence, saving the stale block fails and the miner rebuilds from the new tip.

Consensus validation boundary

A non-genesis block is accepted only if all of the following hold:

• every field has the exact expected type, width, and supported value;
• the miner and transaction addresses are valid Luracoin addresses;
• there is between 1 and 65,535 transactions;
• the block’s bits equals Block.expected_bits(height);
• the previous block exists and its ID equals prev_block_hash;
• the timestamp is strictly greater than the predecessor and at most 500 seconds ahead of the validator’s local clock;
• there is exactly one coinbase at transaction index zero;
• coinbase chain, nonce, fee, origin, destination, and value are exact;
• all transactions select the active chain and transaction IDs are unique inside the block;
• serialized size does not exceed the active height schedule;
• the block ID satisfies proof of work;
• every normal transaction is valid against a single ordered account snapshot;
• no debit underflows and no receiver or miner credit exceeds uint64.

The coinbase is present at position zero but is credited after all normal transaction transitions. Newly minted value therefore cannot be spent inside the same block.

Genesis manifests

Testnet and devnet share these fixed public fields:

version:          1
height:           0
previous hash:    64 zero hex characters
miner/recipient:  LM6jpRVE2TYoZKc1onms6d6N9rXh16r38N
timestamp:        1623168442
bits:             1dffffff
coinbase value:   100,000 LURA

Network-specific manifest values are:

Network	Coinbase chain	Proof nonce	Block ID
testnet	1	14,121,310	0000009e2bcc8e56cee8b5e0fbdac9edc04513542af5c5791ea6165179c468bf
devnet	2	11,943,016	00000033e4111007fd85423c7a527595e8efefe158a1250db62a32870857ef91

The node constructs the manifest from compiled values, recalculates the ID, verifies proof of work, and compares every fixed field during height-zero validation. An existing genesis is revalidated when the chain initializes.

The historical development address is compromised by design. No future mainnet ceremony may reuse it.

Implemented guarantees

The alpha enforces:

• canonical binary transaction and block hashing;
• network-scoped transactions and handshakes;
• deterministic compact low-S signatures;
• address ownership verification;
• exact sender nonce progression;
• ordered balance accounting with overflow bounds;
• exact link, difficulty, proof, coinbase, fee, and reward validation;
• fixed genesis manifests for testnet and devnet;
• atomic Redis sender/nonce reservation;
• bounded P2P frames, caches, peer counts, replay, and synchronization batches;
• authenticated loopback RPC;
• rebuildable, identity-scoped explorer projection.

These are implementation properties, not an independent audit or proof of economic security.

Explicitly absent

The following are not part of the protocol today:

• cumulative-chainwork fork choice;
• side-branch storage;
• disconnect/undo data and atomic reorganizations;
• headers-first synchronization or checkpoints;
• median-time-past;
• persistent peer scoring, bans, subnet diversity, or Sybil defense;
• a defined transaction replacement-by-fee policy;
• mempool expiration, global byte quota, or persistence;
• Merkle roots, Merkle proofs, light-client proofs, or compact blocks;
• staking, burning, contracts, multisig, or protocol-level memo fields;
• a maximum supply—the one-LURA subsidy floor creates tail emission;
• mainnet genesis, distribution, governance, or final specification.

Do not infer one of these features from familiar Bitcoin or Ethereum terminology. If it is not encoded and validated by this implementation, it is not a Luracoin 0.1.0 rule.

Compatibility and change discipline

Changing any consensus byte, field order, integer width, endian convention, hash, signing rule, address version, genesis value, difficulty rule, reward rule, state order, or P2P compatibility field can split nodes.

A deliberate incompatible change requires, at minimum:

1. a new protocol/consensus version and documented activation boundary;
2. regenerated positive vectors and new negative vectors;
3. coordinated Python node and JavaScript wallet changes;
4. a clean data migration or explicit new network;
5. coordinated peer rollout and rejection rules;
6. independent review before any public-value network.

Continue with Addresses & keys, then Transactions and Blocks & validation.