Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/trusts-stack-network/tsn

Post-quantum privacy blockchain — Plonky3 STARKs, ML-DSA-65, Poseidon2, Shielded Transactions, Verified Snapshots, proof of work
https://github.com/trusts-stack-network/tsn

blockchain cryptocurrency mining ml-dsa plonky3 poseidon2 post-quantum privacy proof-of-work rust zero-knowledge

Last synced: 2 months ago
JSON representation

Post-quantum privacy blockchain — Plonky3 STARKs, ML-DSA-65, Poseidon2, Shielded Transactions, Verified Snapshots, proof of work

Awesome Lists containing this project

README 

          


  Trust Stack Network




Trust Stack Network (TSN)





  Post-quantum privacy blockchain — Plonky3 STARKs · ML-DSA-65 · Poseidon2 · Shielded Transactions






  Version

  Rust

  Tests

  Testnet

  License






  Website •

  Whitepaper •

  Docs •

  Blog •

  Explorer •

  Run a Node •

  Discord




---



> [!WARNING]

> **TSN is currently in private testnet.**

> TSN tokens have **no monetary value** at this stage — they will only become meaningful once the incentivized testnet and mainnet are launched.

> **Do not purchase or trade TSN tokens.** They can be mined for free by anyone running a node.



---



## What is TSN?



Trust Stack Network is a **Layer 1 blockchain** designed from the ground up for **privacy** and **post-quantum security**. Every transaction is shielded by default using zero-knowledge proofs, and all cryptographic primitives are quantum-resistant — protecting funds against both classical and future quantum adversaries.



## Key Features



| Feature | Description |

|---------|-------------|

| **Plonky3 STARKs** | AIR-based zero-knowledge proofs wired into block validation — no trusted setup, truly post-quantum |

| **ML-DSA-65 (FIPS 204)** | NIST post-quantum digital signatures for all transactions and blocks |

| **SLH-DSA (FIPS 205)** | Stateless hash-based signatures as secondary post-quantum layer |

| **Poseidon2 PoW** | ZK-friendly hash function over Goldilocks field — same hash for mining AND ZK proofs |

| **Shielded Transactions** | Working V2 transactions with ZK proofs, broadcast and validated across the network |

| **Interactive Wallet** | `./tsn wallet` — generate, restore (BIP39 24-word seed), send, receive, history |

| **P2P Auto-Update** | Nodes detect new versions via peer handshake, download, verify, and self-update |

| **Anti-Reorg Protection** | MAX_REORG_DEPTH=100, Fork ID verification, anchor block filtering |

| **zkVM Smart Contracts** | Stack-based VM with 30+ opcodes, gas metering, and ZK execution traces |

| **MIK Consensus** | Mining Identity Key — Proof of Work with numeric difficulty and 512-bit nonce |

| **Fast Sync** | Snapshot-based synchronization — full sync in ~2 seconds |

| **4 Node Roles** | Miner, Relay, Cortex, Light Client — each with auto-update capability |

| **Relay Pool** | 3% of block reward distributed to relay nodes weighted by participation score |

| **BIP-152 Compact Blocks** | Bandwidth-efficient block relay (short IDs, mempool-based reconstruction) |

| **Checkpoint Voting** | Quorum-based finality: 4+ seeds sign a checkpoint every 100 blocks |



## Security Model



TSN is designed to be **fully quantum-safe** — not just signatures, but the entire stack:



| Layer | Primitive | Standard | Purpose |

|-------|-----------|----------|---------|

| Signatures | ML-DSA-65 | FIPS 204 | Transaction & block signing |

| Backup Signatures | SLH-DSA (SPHINCS+) | FIPS 205 | Stateless hash-based fallback |

| ZK Proofs | Plonky3 STARKs (AIR) | — | Shielded transaction validity |

| Hash Function | Poseidon2 | — | PoW mining, Merkle trees, commitments |

| Field | Goldilocks | p = 2⁶⁴ - 2³² + 1 | ZK-friendly arithmetic |

| Encryption | ChaCha20-Poly1305 | RFC 8439 | Note payload encryption |

| Anti-Sybil | MIK | — | One identity per miner |



### Mining Identity Key (MIK)



Every miner must register a **Mining Identity Key** before mining:



- Derived from their ML-DSA-65 public key: `MIK_ID = SHA-256("TSN_MIK_ID_v1" || pubkey || block_height)`

- One active MIK per public key — prevents Sybil attacks

- Lifecycle: registration → activation delay (10 blocks) → active → optional expiry/revocation

- Block signatures verified against the miner's registered MIK



### Signature Sizes



| Parameter | ML-DSA-65 |

|-----------|-----------|

| Public Key | 1,952 bytes |

| Secret Key | 4,032 bytes |

| Signature | 3,309 bytes |



### Commitment Scheme



```

Note Commitment = Poseidon(domain=1, value, pk_hash, randomness)

Nullifier       = Poseidon(domain=3, nullifier_key, commitment, position)

Merkle Node     = Poseidon(domain=5, left, right)

```



## Architecture



```

┌──────────────────────────────────────────────────────────────────────┐

│                         TSN Node v2.9.15                             │

├──────────────┬──────────────┬──────────────┬─────────────────────────┤

│    Core      │    Crypto    │  Consensus   │        Network          │

│  Block       │  Poseidon2   │  PoW Mining  │  libp2p (GossipSub)     │

│  Transaction │  ML-DSA-65   │  MIK Anti-   │  Kademlia DHT           │

│  UTXO State  │  Plonky3 ZK  │    Sybil     │  Auto-Update (P2P)      │

│  Validation  │  SLH-DSA     │  LWMA Diff   │  Anti-Eclipse           │

│              │  Nullifiers  │    Adjust    │  Rate Limiting          │

├──────────────┴──────────────┴──────────────┴─────────────────────────┤

│  VM (zkVM)   │  Contracts (Escrow, Multisig, AMM)  │  Stablecoin    │

├──────────────┼─────────────────────────────────────┼────────────────┤

│  Storage     │  Wallet (Shielded ZK + BIP39)       │  RPC (REST)    │

├──────────────┼─────────────────────────────────────┼────────────────┤

│  Explorer    │  Metrics & Monitoring                │  CLI Tools     │

└──────────────┴─────────────────────────────────────┴────────────────┘

```



## Built from Scratch



TSN is not a fork. Every core component was designed and written from zero — no Substrate, no Cosmos SDK, no framework.



| Component | Lines | Status |

|-----------|-------|--------|

| **Consensus engine** | 9,880 | LWMA difficulty, PoW validation, fork resolution, checkpoint voting, reorg protection |

| **P2P network protocol** | 23,168 | Headers-first sync, BIP-152 compact blocks, peer scoring, eclipse protection, auto-update |

| **zkVM** | 1,122 | Stack-based bytecode, 40+ opcodes, gas model, ZK execution traces |

| **Smart contracts** | 2,458 | Executor, on-chain storage, templates (Token, Escrow, Multisig, AMM) |

| **Cryptographic layer** | 24,070 | Poseidon2 PoW, nullifiers, commitments, Merkle trees, ZK proof adapters |

| **Block & transaction format** | 9,640 | Custom binary format, shielded TX, binding signatures |

| **Wallet** | 2,355 | BIP39 seed, ML-DSA-65 keygen, shielded send/receive, TX history |

| **Stablecoin (ZST)** | 2,617 | Gold-backed stablecoin module with Djed/Zephyr model |

| **Total** | **97,000+** | **300+ source files, 370+ tests** |



We use battle-tested cryptographic primitives (`fips204` for ML-DSA-65, `p3-poseidon2` for hashing, `plonky2`/`plonky3` for ZK proofs, `libp2p` for transport) — but everything above the primitive layer is original TSN code. We don't reinvent cryptography, we build on it.



## Quick Start



### Download binary (recommended)



```bash

# Download latest release

curl -LO https://github.com/trusts-stack-network/trust-stack-network/releases/latest/download/tsn-linux-x86_64.tar.gz

tar xzf tsn-linux-x86_64.tar.gz

cd tsn-*



# Run a miner (4 threads)

./tsn miner -t 4



# Run a relay node

./tsn relay



# Run a light client

./tsn light

```



### Build from source



Requires **Rust nightly** (automatically selected via `rust-toolchain.toml`):



```bash

# Install Rust if needed

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh



git clone https://github.com/trusts-stack-network/trust-stack-network.git

cd trust-stack-network

cargo build --release



# Run (seeds and wallet auto-detected)

./target/release/tsn miner -t 4

```



Peer discovery is automatic via DNS seeds (seed1-4.tsnchain.com). New nodes fast-sync from a snapshot in ~2 seconds.



### CLI Reference



```bash

./tsn miner -t 4           # Mine with 4 threads

./tsn relay                 # Run relay node

./tsn light                 # Run light client

./tsn wallet                # Interactive wallet menu

./tsn balance               # Check balance

./tsn send --to  --amount 10  # Send TSN

./tsn new-wallet            # Generate new wallet (24-word BIP39 seed)

./tsn --version             # Print version info

```



## Node Types



TSN supports 3 distinct node roles, selectable at startup:



### Miner Node (`./tsn miner`)

Full node that validates, stores the entire blockchain, relays transactions/blocks, **and mines new blocks**. Miners earn **92% of the block reward** (13.52 TSN per block at launch). This is the default role.



### Relay Node (`./tsn relay`)

Full node that stores the complete chain and relays blocks/transactions to peers, but **does not mine**. Relays are the backbone of the network — they ensure fast block propagation via GossipSub and BIP-152 compact blocks, and serve fast-sync snapshots to new nodes. They earn from the **3% relay reward pool** (scored by participation per block).



### Cortex Node (`./tsn cortex`)

Service layer node for decentralized applications (dApps). Runs WASM modules, serves dApp endpoints, and earns fees from dApps (NetherSwap, Whispr, ZST). Not funded by coinbase — fees come entirely from dApp activity.



### Light Client (`./tsn light`)

Minimal node that **does not store the full chain** — it syncs only block headers and verifies transactions using ZK proofs. Designed for mobile wallets and resource-constrained devices.



| Type | Stores Chain | Mines | Relays | dApps | Auto-Update | Reward |

|------|:-:|:-:|:-:|:-:|:-:|--------|

| **Miner** | Yes | Yes | Yes | — | Yes | 92% block reward |

| **Relay** | Yes | — | Yes | — | Yes | 3% relay pool |

| **Cortex** | Yes | — | Yes | Yes | Yes | dApp fees |

| **Light Client** | — | — | — | — | Yes | — |



All node types auto-update when a new version is detected on the network.



## P2P Auto-Update



TSN is one of the first blockchains with **fully decentralized automatic updates**. No other blockchain combines P2P version signaling with multi-source download and cryptographic verification.



**How it works:**

1. Peers announce their version during the libp2p Identify handshake

2. If a peer has a newer version, the node queries the official release

3. Binary is downloaded from GitHub (primary) or tsnchain.com (fallback)

4. SHA256 integrity check + Ed25519 signature verification

5. Current binary backed up, new binary installed, node restarts



```

Node A (v2.9.14) connects to Node B (v2.9.15)

  → A detects newer version via P2P handshake

  → A downloads v2.9.15 from GitHub, verifies Ed25519 signature

  → A self-updates and restarts

  → A is now v2.9.15

  → A's other peers detect the update via handshake

  → Network propagates the update in minutes

```



Manual update: `./tsn update`



## Mining & Hashrate — Poseidon2 Proof of Work



TSN uses **Poseidon2** as its PoW hash function instead of SHA-256 (Bitcoin) or RandomX (Monero):



- **ZK-native**: Same hash for mining AND shielded transaction proofs (Plonky3 STARKs). One hash for the entire stack.

- **Post-quantum friendly**: Algebraic hashes over large fields resist Grover's algorithm.

- **ASIC-resistant**: Field arithmetic is complex enough that ASICs offer limited advantage over CPUs.



### How Mining Works



```

1. Build block template (transactions + coinbase)

2. Generate random 512-bit nonce

3. Hash: Poseidon2(header_fields, nonce) → 32 bytes

4. Check: first_8_bytes_as_u64 < (u64::MAX / difficulty)

5. Valid → broadcast block. Invalid → new nonce.

```



### Hashrate Benchmarks



| CPU | Threads | Hashrate |

|-----|---------|----------|

| EPYC 7742 | 1T | 121 KH/s |

| EPYC 7742 | 4T | 257 KH/s |

| EPYC 7742 | 8T | 454 KH/s |

| Xeon E5-2697A v4 | 2T | ~80 KH/s |



**Note:** Poseidon2 hashrates are not comparable to SHA-256 or RandomX. Different hash functions have different work-per-hash. TSN's difficulty adjusts via LWMA (45-block window) to target 10-second blocks.



### Network Hashrate Formula



```

network_hashrate = difficulty / block_time

```



Displayed in the explorer and `/chain/info` API.



## Smart Contracts



TSN includes a **stack-based zkVM** with gas metering and ZK execution traces:



- **30+ opcodes**: arithmetic, storage, memory, crypto (Poseidon hash, signature verify), control flow, events

- **Contract templates**: Escrow (with arbitration & timeout), Multisig (N-of-M), AMM Pool, Governance

- **Gas model**: per-opcode costs, block gas limit 1M, max 64KB bytecode, 100K storage slots



## Network Parameters



| Parameter | Value |

|-----------|-------|

| HTTP API Port | 9333 |

| P2P Port (libp2p) | 9334 |

| Block Reward | 13.52 TSN at launch (92% miner, 5% dev, 3% relay) |

| Halving Eras | 6 eras over ~10 years |

| Target Block Time | ~10 seconds |

| Difficulty Adjustment | LWMA per-block (N=45 window) |

| P2P Protocol | libp2p GossipSub mesh (D=6, heartbeat 700ms) |

| Max Reorg Depth | 100 blocks |

| Min Difficulty | 1,500,000 |

| Nonce Size | 512 bits |

| Max TX Size | 1 MB |

| Max Supply | 100,000,000 TSN (hard cap) |



## Tokenomics



TSN follows a deflationary emission model with **6 halving eras** over ~10 years, converging to a hard cap of **100,000,000 TSN**. No pre-mine. No VC allocation. No pre-sale. Mining only.



### Halving Schedule



| Era | Reward/block | Duration | TSN Mined | Cumulative |

|-----|-------------|----------|-----------|------------|

| 1 | 13.52 TSN | ~6 months | 21.5M | 21.5M |

| 2 | 6.76 TSN | ~23 months | 40.5M | 62.0M |

| 3 | 3.38 TSN | ~23 months | 20.3M | 82.3M |

| 4 | 1.69 TSN | ~23 months | 10.1M | 92.4M |

| 5 | 0.85 TSN | ~23 months | 5.1M | 97.5M |

| 6 | 0.42 TSN | ~23 months | 2.5M | 100.0M |



### Distribution



- **92%** → Miners (block reward)

- **5%** → Dev fund (protocol development)

- **3%** → Relay pool (network infrastructure)



### Timeline



- **Now** — Private testnet (50 TSN/block, tokens have no monetary value)

- **May 2027** — Incentivized testnet with real tokenomics *(subject to readiness)*

- **~2037** — Final TSN mined (100M hard cap reached)



> ⚠️ The private testnet uses a simplified 50 TSN/block reward. The halving schedule above will take effect starting from the incentivized testnet phase.



## Synchronization & Anti-Fork System



### Fast-Sync Protocol



New nodes join the network in **seconds** by downloading a compressed state snapshot:



```

┌─────────────┐     GET /snapshot/info      ┌─────────────┐

│  New Node   │ ──────────────────────────>  │  Seed Node  │

│             │     GET /snapshot/download   │             │

│  --fast-sync│ <────────────────────────── │  (gzip)     │

│             │                              │             │

│  Load state │     GET /blocks?from=N       │             │

│  Sync rest  │ ──────────────────────────>  │             │

└─────────────┘                              └─────────────┘

```



1. New node requests a **gzip-compressed state snapshot** from a peer

2. Loads the snapshot and verifies `state_root` integrity

3. Syncs only the **missing blocks** since the snapshot height

4. Ready to mine in ~2 seconds



### Anti-Fork Protections



| Protection | Description |

|------------|-------------|

| **Heaviest chain rule** | Fork choice based on cumulative work, not height |

| **MAX_REORG_DEPTH = 100** | Hard limit — no reorg deeper than 100 blocks |

| **Checkpoint finality** | Every 100 blocks, a checkpoint is created |

| **Fork ID verification** | Genesis hash checked at sync — prevents silent splits |

| **Anchor block filter** | Blocks must reference a recent valid ancestor |

| **P2P version gate** | Nodes below MINIMUM_VERSION (v2.9.15) are rejected, with escalating IP bans on repeat offenders |

| **Genesis HTTP check** | Peer genesis block hash verified before any sync |

| **Protocol magic** | TSN2 magic bytes — old network nodes cannot connect |

| **Smart auto-wipe watchdog** | Solo-fork detection with cooldown + kill-switch guards |

| **Signed snapshots** | Ed25519-signed fast-sync snapshots, optionally mirrored on GitHub |



## Testnet Status



The private testnet v9 is live with a **fresh genesis**, **network identity** `tsn-testnet-v9`, and **strict version enforcement** (**v2.9.15 minimum** — older nodes are rejected at handshake).



> **TSN tokens currently have no value.** The testnet is for development and testing only. Tokens can be mined for free by anyone running a node. Economic value will only be introduced at the incentivized testnet phase.



**Roadmap:**

1. **Private Testnet** — Active now. Internal testing and development.

2. **Open Testnet** — Code on GitHub. Anyone can run a node and mine. No value.

3. **Incentivized Testnet** — Rewards for miners and node operators. Tokens begin to have value.

4. **Mainnet** — Genesis block. Fair launch. No premine.



## Roadmap



### Phase 1 — Foundations ✅

Core blockchain engine: blocks, transactions, UTXO, Poseidon2 hashing, ML-DSA-65 signatures, Proof of Work consensus with MIK anti-Sybil, P2P networking with Kademlia DHT, SledDB storage, shielded wallet, REST API, and block explorer.



### Phase 2 — Advanced Features ✅

Multi-role nodes (Miner, Relay, Light Client), Plonky3 STARK migration (AIR-based proofs via p3-uni-stark), enhanced shielded wallet with BIP39 recovery and viewing keys, hardened fast-sync with state_root verification, security audit (8.1/10 score).



### Phase 3 — Smart Contracts & DeFi ✅

zkVM (30+ opcodes), contract templates (Escrow, Multisig, AMM Pool, Governance), stablecoin module (ZST — gold-backed), P2P auto-update system.



### Phase 4 — Launch



```

┌──────────────────────────────────────────────────────────────────┐

│                                                                  │

│  APRIL 2026          MAY — JULY 2026            Q3 2026          │

│                                                                  │

│  ┌──────────┐        ┌──────────────────┐       ┌────────────┐  │

│  │ PRIVATE  │───────>│   INCENTIVIZED   │──────>│  MAINNET   │  │

│  │ TESTNET  │        │  PUBLIC TESTNET  │       │  LAUNCH    │  │

│  └──────────┘        └──────────────────┘       └────────────┘  │

│                                                                  │

│  • 5 internal nodes   • Open to everyone        • Genesis block  │

│  • Stress testing     • Bug bounty program      • Fair launch    │

│  • Core validation    • Node operator rewards   • No premine     │

│  • ZK proof testing   • Security audit          • Full privacy   │

│                       • 2-3 months duration     • zkVM live      │

│                                                                  │

└──────────────────────────────────────────────────────────────────┘

```



## Ecosystem



TSN is more than a blockchain — it's a full ecosystem of decentralized applications.



### Whispr — Decentralized Private Social Network (v0.4.0, Live)



A peer-to-peer social network with zero tracking, no email/phone required, and end-to-end encrypted messaging. Think Discord + Twitter + Medium, but decentralized and private.



- **Whisps** (short posts) + **Articles** (long-form blog) with upvote/downvote

- **Circles** — Community groups with rooms, roles, polls, auto-moderation

- **E2E Encrypted DMs** — ECDH P-256 + AES-256-GCM

- **BIP39 Identity** — 24-word seed phrase, no email, no phone

- **5 P2P Nodes** — Rust binary, libp2p gossipsub

- **App**: [whispr.tsnchain.com](https://whispr.tsnchain.com)

- **GitHub**: [github.com/trusts-stack-network/whispr](https://github.com/trusts-stack-network/whispr)

- **Releases**: [github.com/trusts-stack-network/whispr-releases](https://github.com/trusts-stack-network/whispr-releases) (Linux + Windows + macOS)



### ZST — Gold-Backed Stablecoin (In Development)



A stablecoin pegged to gold (1 ZST = 1g XAU), over-collateralized in TSN. Djed/Zephyr-inspired reserve model with stress fees, circuit breaker, and oracle price feeds.



- **3 assets**: TSN (collateral) → ZST (stablecoin) + ZRS (reserve share)

- **Reserve engine**: 76 tests passing, mint/burn with dynamic fees

- **Protections**: stress fees 0.3%-5%, circuit breaker at 120%, cooldown mechanism



### NetherSwap — Decentralized Exchange (In Development)



A cross-chain anonymous DEX built on TSN with AMM pools, escrow P2P, yield farming, governance DAO, and prediction markets.



- **AMM Swap** with smart router (multi-hop), limit orders

- **Liquidity Pools** with yield farming rewards

- **P2P Escrow** for trustless OTC trades

- **DAO Governance** — community-driven proposals and voting

- **Cross-chain** — relayers staked in TSN

- **Privacy** — anonymous trading via TSN shielded transactions



## Changelog



> Full history: [CHANGELOG.md](CHANGELOG.md)



### v2.9.x — Checkpoint Voting & Backfill (2026-Q2)



- **v2.9.19** — Fix: pinned `EXPECTED_GENESIS_HASH` for testnet-v12 (was empty for 8 days, source of silent forks); auto-update reuses existing `TSN_SNAPSHOT_GH_TOKEN` on seeds.

- **v2.9.18** — Fix: auto-update blocked by GitHub API rate limit; `TSN_GITHUB_TOKEN` env var support added; fallback manifest deployed at `https://tsnchain.com/releases/latest.json`.

- **v2.9.17** — Fix: version-ban fast-path blocked upgraded peers for up to 24h; nodes banned for using an old version remained blocked even after upgrading.

- **v2.9.16** — Critical fix: `reorg_lock` held too long after PoW — sync write-lock timed out (15s), orphaning every community-mined block. Lock now released immediately after `add_block()`.

- **v2.9.15** — MINIMUM_VERSION gate: nodes below v2.9.15 rejected at handshake with escalating IP bans.

- **v2.9.14** — Backport W1+W1B+H-G+FIX-D patches; auto-recovery timeout extended to 180s.

- **v2.9.13** — `--role` defaults to relay; full auto-recovery cycle on lost consensus.

- **v2.9.11/10/9** — Background backfill of historical blocks missing post-fast-sync; descending walk so seeds catch up to tip; treats `[0u8;32]` placeholder entries as missing.

- **v2.9.8** — CHECKPOINT_QUORUM dynamic 80% with warmup limited to common circuit shapes (Plonky3 RAM fix).

- **v2.9.7** — Persistent libp2p identity key; `network_name` in `/version.json`; Phase C HTTP fallback; checkpoint history endpoint.

- **v2.9.6/5/3** — `checkpoint_vote` anchor scan at `fast_sync_base`; shallow fallback window for post-fast-sync transition; always publish snapshot on tick.

- **v2.9.2** — CHECKPOINT_QUORUM raised to 4; `/chain/quorum_status` endpoint; explorer quorum halo badge.

- **v2.9.1** — RAM diet: sled cache 1G→256M, block LRU 1000→200, recompute fast-sync anchor; anchor-retry timeout.

- **v2.9.0** — BIP-152 RAM fix: filter mempool by short_id before clone.



### v2.8.x — Compact Blocks, Checkpoint & Iron Fish Wallet (2026-Q2)



- **v2.8.9** — Trusted-quorum checkpoint vote; BIP-152 DoS protections (max announces, dedup window, rate limit per peer).

- **v2.8.8** — Phase 1 hardening: invalid anchor retry with exponential backoff.

- **v2.8.7** — Full **Compact Block Relay** (BIP-152 inspired): `cmpctblock`/`getblocktxn`/`blocktxn` messages, short IDs (SipHash-2-4), mempool-based reconstruction. Bandwidth savings up to 98% on well-connected peers.

- **v2.8.6** — Proactive tip-pull (Phase 0.2 simplified): nodes pull latest tip on GossipSub announcement.

- **v2.8.5** — Cumulative work drift fix; **Iron Fish wallet integration** (BIP44 derivation path); **anchored mempool** (tx anchored to a recent block to prevent replays after reorgs).

- **v2.8.1** — Phase A pipeline fixes; MAX_SPENDS raised from 25 to 50.

- **v2.8.0** — Phase C wallet bootstrap; signed snapshot; auto-consolidate ON by default.



### v2.7.x — Performance & Fork Hardening (2026-Q2)



- **v2.7.4** — Anti-freeze HTTP timeouts; lock-free chain reads; explorer aggregate fixes.



### v2.5.x — Cortex Node & Fork-Choice Fixes (2026-Q2)



- **v2.5.0** — 4 fork-choice fixes; **Cortex node Phase 1** (WASM runtime for dApp service modules); testnet-v9 reset.



### v2.4.x — Relay Pool, DNS Bootstrap & Testnet Resets (2026-Q2)



- **v2.4.3** — `wallet-cleanup` command; balance shows spendable notes only; `/leaves/bulk` endpoint for wallet pre-validation; `calculate_chain_work` fast-path parent canonical check; seed PeerID dedup in peer tracking; testnet-v8 reset; persist `cumulative_work` on snapshot import.

- **v2.4.2** — Testnet-v7 reset (private test build).

- **v2.4.1** — DNS-aware P2P bootstrap (`seed1-4.tsnchain.com`); MINIMUM_VERSION bumped.

- **v2.4.0** — Testnet-v6 reset; miner attribution in explorer; V2 shielded TX inclusion; **relay pool payouts** (3% block reward distributed to relay nodes by per-block participation score).



### v2.3.x — Post-quantum network hardening (2026-Q2)



- **v2.3.9** — LWMA fast-sync fix (eliminates the post-fast-sync fork loop), seeds migrated from hardcoded IPs to DNS (`nexus.tsnchain.com`, `seed1..4.tsnchain.com`), explorer gets typed traffic particles + `/stats/activity` + SSE event stream, wallet rescan discrepancy fix, snapshot GitHub dedup, watchdog logs in cyan, README refresh.

- **v2.3.6** — Anti-spam middleware with escalating IP bans (1h → 6h → 24h) keyed on X-TSN-Version / X-TSN-Network / X-TSN-Genesis, fork-work recovery (`prefix_estimate`), snapshot cache stale protection (500-block gap).

- **v2.3.5** — Testnet-v5 reset with genesis hash derived deterministically from `NETWORK_NAME`, auto-wipe at boot on genesis mismatch, signed GitHub snapshot mirror + retention pruning, HTTP CLOSE-WAIT fix.

- **v2.3.4** — P2P `NewBlock` mempool cleanup in `spawn_blocking`, snapshot persistence to disk with 24h retention, `cmd_balance` orphan-aware display.

- **v2.3.3** — Pre-validate orphan notes before `cmd_send` to avoid retry loops after chain reorgs.

- **v2.3.2** — Wallet rescan actually deletes DB rows, metrics port auto-fallback 9090..9099, `WalletLock::try_acquire` returns an actionable error.

- **v2.3.1** — Admin `/mempool/purge` endpoint, HTTP 429 backoff (1s → 32s) on witness fetch and tx submit, auto-consolidation multi-round orchestration.

- **v2.3.0** — LRU dedup (tip / block / fork-recovery), snapshot auto-trigger from miner path, `agent_version` height hint in libp2p Identify, wallet `resolve_pq_commitment` fallback on server leaf.



### v2.0.0 — Network Reset & Sync Stability



**Breaking:** New network identity, protocol magic, and genesis — all previous versions are incompatible.



- **Network reset**: fresh genesis (`tsn-testnet-v2`), clean chain from block 0

- **Protocol magic**: `TSN1` → `TSN2` — old nodes cannot parse messages

- **MINIMUM_VERSION**: `2.0.0` — old nodes explicitly rejected at handshake

- **Genesis HTTP check**: peer's genesis block hash verified via REST before any sync

- **EXPECTED_GENESIS_HASH**: hardcoded and verified at startup — prevents silent chain forks

- **Sync stability (patches A+B+D)**: validated across 6 tests including 20 miners on 2 EPYC machines for 1 hour

  - Patch A: prevent rollback thrashing to fast_sync_base

  - Patch B: prevent peer isolation via ban cascade with 10+ peers

  - Patch D: guard reset_for_snapshot_resync in post-fast-sync warmup window

- **Headers-first sync**: refactored ancestor search with fast-sync blind zone detection

- **Open network**: IP whitelist removed, compatibility enforced via version + magic + genesis

- **Poseidon2 from genesis**: no legacy hash period, clean start

- **node-1**: converted from miner to relay-only (dedicated to explorer/website)



**Migration:** Stop node, delete `data/` directory, install v2.0.0 binary, restart. Old chain data is incompatible.



### v1.4.0 — Consensus Security Overhaul



Major consensus upgrade fixing 19 bugs in fork resolution, snapshot validation, and self-healing.



- **Heaviest chain rule**: Fork choice now ALWAYS uses cumulative_work (was height-based for short forks). Tiebreaker: difficulty then hash.

- **Persistent cumulative_work**: New sled tree stores cumulative_work per height. Survives LRU eviction and restarts.

- **PoW validation in trusted mode**: `add_block_trusted()` now verifies PoW and MIN_DIFFICULTY. Prevents importing invalid blocks during fast-sync.

- **Orphan PoW validation**: Orphan pool rejects blocks with invalid PoW or below MIN_DIFFICULTY before storing.

- **Graduated difficulty tolerance post fast-sync**: Within LWMA_WINDOW (45 blocks) of fast-sync base, accepts 25% margin. After that, enforces normal 10%.

- **Accurate rollback work**: Uses DB-stored cumulative_work instead of `difficulty * depth` estimation. Falls back to summing actual block difficulties.

- **Conservative snapshot work estimate**: When peer_cumulative_work is unavailable, uses MIN_DIFFICULTY * height (not difficulty * height).

- **Peer selection by work**: Fast-sync, stuck detection, and auto-resync now select peers by cumulative_work, not height alone.

- **Multi-peer agreement**: Auto-resync requires at least 2 peers agreeing (within 5% of max work) before triggering.

- **Peer work verification**: New `verify_peer_work_sample()` helper samples blocks to validate a peer's claimed work.

- **Faster trusted snapshots**: Snapshot interval in trusted mode reduced from 500 to 50 blocks for faster recovery.

- **MINIMUM_VERSION**: bumped to 1.4.0



### v1.3.7 — Self-Healing Nodes: Missing Snapshot Recovery



- **Missing snapshot recovery**: If state snapshot is lost but fast-sync placeholders exist, the node auto-wipes and re-syncs instead of crashing with `Missing block data at height 0`

- **MINIMUM_VERSION**: bumped to 1.3.7



### v1.3.6 — Windows Fix, Snapshot Sync at Height 0, Node Role Detection



- **Sync loop at height 0**: Nodes stuck at height 0 now use snapshot sync instead of block-by-block

- **Stuck detection at height 0**: Auto-resync watchdog now catches nodes stuck at height 0

- **Windows fix**: verification key checksum now normalizes line endings (CRLF → LF) before SHA256

- **nodes.html fix**: P2P peers fetched from correct API endpoint (shows miner badges correctly)

- **.gitattributes**: forces LF line endings for verification key files across platforms

- **MINIMUM_VERSION**: bumped to 1.3.6



### v1.3.0 — Chain Reset, Halving Fix & Sync Stability



- **Halving interval**: 210,000 → **4,200,000 blocks** (~16 months per halving, supply max in ~10 years)

- **Chain reset**: fresh genesis block with correct economics

- **Critical fix**: rollback `canonical_height` bug causing infinite sync loops

- **P2P Auto-Update**: nodes detect + download + verify + self-update

- **Explorer URL**: points to `explorer.tsnchain.com`

- **Default mode**: `./tsn` auto-creates wallet and mines (no subcommand needed)

- **Verification keys**: searched next to binary + parent dirs (build from source works)

- **Firewall**: port 9333 open on all nodes for HTTP sync



### v1.1.0 — Performance & Production Hardening



| Feature | Before | After |

|---------|--------|-------|

| Mining Hot Loop | Full header rebuilt per hash | MiningHashContext — zero heap alloc |

| Hashrate Display | Truncated hash, no KH/s | Real-time KH/s, full hash |

| Explorer Hashrate | Wrong formula | Corrected: `difficulty / block_time` |

| Wallet TX History | Not saved | Sent + received persisted (WalletTxRecord) |

| Received TX Detection | Manual | Automatic at wallet scan |

| Nullifier Check | At send only | At scan + send (prevents double-spend) |

| P2P Version Gate | Accept all peers | Reject peers below MINIMUM_VERSION |

| CLI | Multiple flags required | `./tsn miner -t 4` — everything auto-detected |

| Auto-Update | None | P2P signaling + multi-source download + SHA256 verification |



### v0.8.0 — Transactions, Wallet & Security



- Working V2 shielded transactions (create, sign, broadcast, validate)

- Interactive wallet menu with BIP39 recovery

- MAX_REORG_DEPTH = 100, Fork ID verification, anchor block filtering

- Dual mining across multiple nodes



### v0.7.1 — Security Audit & Hardening



Full security audit: 29 findings, 23 fixes applied. Score: **5.4/10 → 8.1/10**. Zero critical vulnerabilities remaining.



### v0.7.0 — Scaling & Reliability



- LWMA per-block difficulty adjustment (N=45 window)

- GossipSub mesh P2P (replaced flood protocol)

- Cryptographic random nonces (zero miner collisions)

- Concurrent block relay, canonical height in DB



### v0.6.0 — Major Network Upgrade



- Numeric difficulty system with 512-bit nonce

- Poseidon2 PoW (plonky3)

- Fast sync (~2 seconds)

- BIP39 wallet recovery

- DNS seed discovery

- Chain Watchdog monitoring



## Codebase



| Metric | Value |

|--------|-------|

| Language | Rust 2021 edition |

| Lines of code | 97,000+ |

| Source files | 300+ |

| Tests | 370+ passing |

| Commits | 420+ |

| Nodes | 5 (relay + 4 seeds) |



## API



| Endpoint | Description |

|----------|-------------|

| `GET /chain/info` | Block height, difficulty, latest hash, version |

| `GET /peers` | Connected peers |

| `GET /sync/status` | Sync progress and peer count |

| `GET /block/height/:n` | Get block by height |

| `POST /tx/submit` | Submit shielded transaction |

| `GET /explorer` | Built-in block explorer |

| `GET /version.json` | Node version info (used by auto-update) |



## Links



- **Website**: [tsnchain.com](https://tsnchain.com)

- **Explorer**: [explorer.tsnchain.com](https://explorer.tsnchain.com)

- **Whispr**: [whispr.tsnchain.com](https://whispr.tsnchain.com)

- **Whitepaper**: [tsnchain.com/whitepaper.html](https://tsnchain.com/whitepaper.html)

- **Documentation**: [tsnchain.com/docs.html](https://tsnchain.com/docs.html)

- **Run a Node**: [tsnchain.com/run-node.html](https://tsnchain.com/run-node.html)

- **Blog**: [tsnchain.com/blog.html](https://tsnchain.com/blog.html)

- **X/Twitter**: [x.com/tsn_chain](https://x.com/tsn_chain)

- **Medium**: [medium.com/@trusts-stack-network](https://medium.com/@trusts-stack-network)

- **Discord**: [discord.gg/wxxNVDVn6N](https://discord.gg/wxxNVDVn6N)



## License



MIT — Open source.