{"id":48851179,"url":"https://github.com/trusts-stack-network/tsn","last_synced_at":"2026-05-02T14:02:21.811Z","repository":{"id":351492569,"uuid":"1211223393","full_name":"trusts-stack-network/tsn","owner":"trusts-stack-network","description":"Post-quantum privacy blockchain — Plonky3 STARKs, ML-DSA-65, Poseidon2, Shielded Transactions, Verified Snapshots, proof of work","archived":false,"fork":false,"pushed_at":"2026-05-02T09:57:17.000Z","size":53474,"stargazers_count":1,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-02T11:14:17.353Z","etag":null,"topics":["blockchain","cryptocurrency","mining","ml-dsa","plonky3","poseidon2","post-quantum","privacy","proof-of-work","rust","zero-knowledge"],"latest_commit_sha":null,"homepage":"https://tsnchain.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trusts-stack-network.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-15T07:21:44.000Z","updated_at":"2026-05-02T09:57:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/trusts-stack-network/tsn","commit_stats":null,"previous_names":["trusts-stack-network/tsn"],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/trusts-stack-network/tsn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trusts-stack-network%2Ftsn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trusts-stack-network%2Ftsn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trusts-stack-network%2Ftsn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trusts-stack-network%2Ftsn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trusts-stack-network","download_url":"https://codeload.github.com/trusts-stack-network/tsn/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trusts-stack-network%2Ftsn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32536582,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T12:25:33.646Z","status":"ssl_error","status_checked_at":"2026-05-02T12:24:51.733Z","response_time":132,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","cryptocurrency","mining","ml-dsa","plonky3","poseidon2","post-quantum","privacy","proof-of-work","rust","zero-knowledge"],"created_at":"2026-04-15T09:02:41.630Z","updated_at":"2026-05-02T14:02:21.768Z","avatar_url":"https://github.com/trusts-stack-network.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://avatars.githubusercontent.com/u/265249968?v=4\" alt=\"Trust Stack Network\" width=\"120\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eTrust Stack Network (TSN)\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003ePost-quantum privacy blockchain — Plonky3 STARKs · ML-DSA-65 · Poseidon2 · Shielded Transactions\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Version\" src=\"https://img.shields.io/badge/version-2.9.19-blue\"\u003e\n  \u003cimg alt=\"Rust\" src=\"https://img.shields.io/badge/rust-97k+_lines-orange\"\u003e\n  \u003cimg alt=\"Tests\" src=\"https://img.shields.io/badge/tests-370+_passing-brightgreen\"\u003e\n  \u003cimg alt=\"Testnet\" src=\"https://img.shields.io/badge/testnet--v9-live-success\"\u003e\n  \u003cimg alt=\"License\" src=\"https://img.shields.io/badge/license-MIT-green\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://tsnchain.com\"\u003eWebsite\u003c/a\u003e \u0026bull;\n  \u003ca href=\"https://tsnchain.com/whitepaper.html\"\u003eWhitepaper\u003c/a\u003e \u0026bull;\n  \u003ca href=\"https://tsnchain.com/docs.html\"\u003eDocs\u003c/a\u003e \u0026bull;\n  \u003ca href=\"https://tsnchain.com/blog.html\"\u003eBlog\u003c/a\u003e \u0026bull;\n  \u003ca href=\"https://explorer.tsnchain.com\"\u003eExplorer\u003c/a\u003e \u0026bull;\n  \u003ca href=\"https://tsnchain.com/run-node.html\"\u003eRun a Node\u003c/a\u003e \u0026bull;\n  \u003ca href=\"https://discord.gg/wxxNVDVn6N\"\u003eDiscord\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003e [!WARNING]\n\u003e **TSN is currently in private testnet.**\n\u003e TSN tokens have **no monetary value** at this stage — they will only become meaningful once the incentivized testnet and mainnet are launched.\n\u003e **Do not purchase or trade TSN tokens.** They can be mined for free by anyone running a node.\n\n---\n\n## What is TSN?\n\nTrust 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.\n\n## Key Features\n\n| Feature | Description |\n|---------|-------------|\n| **Plonky3 STARKs** | AIR-based zero-knowledge proofs wired into block validation — no trusted setup, truly post-quantum |\n| **ML-DSA-65 (FIPS 204)** | NIST post-quantum digital signatures for all transactions and blocks |\n| **SLH-DSA (FIPS 205)** | Stateless hash-based signatures as secondary post-quantum layer |\n| **Poseidon2 PoW** | ZK-friendly hash function over Goldilocks field — same hash for mining AND ZK proofs |\n| **Shielded Transactions** | Working V2 transactions with ZK proofs, broadcast and validated across the network |\n| **Interactive Wallet** | `./tsn wallet` — generate, restore (BIP39 24-word seed), send, receive, history |\n| **P2P Auto-Update** | Nodes detect new versions via peer handshake, download, verify, and self-update |\n| **Anti-Reorg Protection** | MAX_REORG_DEPTH=100, Fork ID verification, anchor block filtering |\n| **zkVM Smart Contracts** | Stack-based VM with 30+ opcodes, gas metering, and ZK execution traces |\n| **MIK Consensus** | Mining Identity Key — Proof of Work with numeric difficulty and 512-bit nonce |\n| **Fast Sync** | Snapshot-based synchronization — full sync in ~2 seconds |\n| **4 Node Roles** | Miner, Relay, Cortex, Light Client — each with auto-update capability |\n| **Relay Pool** | 3% of block reward distributed to relay nodes weighted by participation score |\n| **BIP-152 Compact Blocks** | Bandwidth-efficient block relay (short IDs, mempool-based reconstruction) |\n| **Checkpoint Voting** | Quorum-based finality: 4+ seeds sign a checkpoint every 100 blocks |\n\n## Security Model\n\nTSN is designed to be **fully quantum-safe** — not just signatures, but the entire stack:\n\n| Layer | Primitive | Standard | Purpose |\n|-------|-----------|----------|---------|\n| Signatures | ML-DSA-65 | FIPS 204 | Transaction \u0026 block signing |\n| Backup Signatures | SLH-DSA (SPHINCS+) | FIPS 205 | Stateless hash-based fallback |\n| ZK Proofs | Plonky3 STARKs (AIR) | — | Shielded transaction validity |\n| Hash Function | Poseidon2 | — | PoW mining, Merkle trees, commitments |\n| Field | Goldilocks | p = 2⁶⁴ - 2³² + 1 | ZK-friendly arithmetic |\n| Encryption | ChaCha20-Poly1305 | RFC 8439 | Note payload encryption |\n| Anti-Sybil | MIK | — | One identity per miner |\n\n### Mining Identity Key (MIK)\n\nEvery miner must register a **Mining Identity Key** before mining:\n\n- Derived from their ML-DSA-65 public key: `MIK_ID = SHA-256(\"TSN_MIK_ID_v1\" || pubkey || block_height)`\n- One active MIK per public key — prevents Sybil attacks\n- Lifecycle: registration → activation delay (10 blocks) → active → optional expiry/revocation\n- Block signatures verified against the miner's registered MIK\n\n### Signature Sizes\n\n| Parameter | ML-DSA-65 |\n|-----------|-----------|\n| Public Key | 1,952 bytes |\n| Secret Key | 4,032 bytes |\n| Signature | 3,309 bytes |\n\n### Commitment Scheme\n\n```\nNote Commitment = Poseidon(domain=1, value, pk_hash, randomness)\nNullifier       = Poseidon(domain=3, nullifier_key, commitment, position)\nMerkle Node     = Poseidon(domain=5, left, right)\n```\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────────────────────────┐\n│                         TSN Node v2.9.15                             │\n├──────────────┬──────────────┬──────────────┬─────────────────────────┤\n│    Core      │    Crypto    │  Consensus   │        Network          │\n│  Block       │  Poseidon2   │  PoW Mining  │  libp2p (GossipSub)     │\n│  Transaction │  ML-DSA-65   │  MIK Anti-   │  Kademlia DHT           │\n│  UTXO State  │  Plonky3 ZK  │    Sybil     │  Auto-Update (P2P)      │\n│  Validation  │  SLH-DSA     │  LWMA Diff   │  Anti-Eclipse           │\n│              │  Nullifiers  │    Adjust    │  Rate Limiting          │\n├──────────────┴──────────────┴──────────────┴─────────────────────────┤\n│  VM (zkVM)   │  Contracts (Escrow, Multisig, AMM)  │  Stablecoin    │\n├──────────────┼─────────────────────────────────────┼────────────────┤\n│  Storage     │  Wallet (Shielded ZK + BIP39)       │  RPC (REST)    │\n├──────────────┼─────────────────────────────────────┼────────────────┤\n│  Explorer    │  Metrics \u0026 Monitoring                │  CLI Tools     │\n└──────────────┴─────────────────────────────────────┴────────────────┘\n```\n\n## Built from Scratch\n\nTSN is not a fork. Every core component was designed and written from zero — no Substrate, no Cosmos SDK, no framework.\n\n| Component | Lines | Status |\n|-----------|-------|--------|\n| **Consensus engine** | 9,880 | LWMA difficulty, PoW validation, fork resolution, checkpoint voting, reorg protection |\n| **P2P network protocol** | 23,168 | Headers-first sync, BIP-152 compact blocks, peer scoring, eclipse protection, auto-update |\n| **zkVM** | 1,122 | Stack-based bytecode, 40+ opcodes, gas model, ZK execution traces |\n| **Smart contracts** | 2,458 | Executor, on-chain storage, templates (Token, Escrow, Multisig, AMM) |\n| **Cryptographic layer** | 24,070 | Poseidon2 PoW, nullifiers, commitments, Merkle trees, ZK proof adapters |\n| **Block \u0026 transaction format** | 9,640 | Custom binary format, shielded TX, binding signatures |\n| **Wallet** | 2,355 | BIP39 seed, ML-DSA-65 keygen, shielded send/receive, TX history |\n| **Stablecoin (ZST)** | 2,617 | Gold-backed stablecoin module with Djed/Zephyr model |\n| **Total** | **97,000+** | **300+ source files, 370+ tests** |\n\nWe 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.\n\n## Quick Start\n\n### Download binary (recommended)\n\n```bash\n# Download latest release\ncurl -LO https://github.com/trusts-stack-network/trust-stack-network/releases/latest/download/tsn-linux-x86_64.tar.gz\ntar xzf tsn-linux-x86_64.tar.gz\ncd tsn-*\n\n# Run a miner (4 threads)\n./tsn miner -t 4\n\n# Run a relay node\n./tsn relay\n\n# Run a light client\n./tsn light\n```\n\n### Build from source\n\nRequires **Rust nightly** (automatically selected via `rust-toolchain.toml`):\n\n```bash\n# Install Rust if needed\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n\ngit clone https://github.com/trusts-stack-network/trust-stack-network.git\ncd trust-stack-network\ncargo build --release\n\n# Run (seeds and wallet auto-detected)\n./target/release/tsn miner -t 4\n```\n\nPeer discovery is automatic via DNS seeds (seed1-4.tsnchain.com). New nodes fast-sync from a snapshot in ~2 seconds.\n\n### CLI Reference\n\n```bash\n./tsn miner -t 4           # Mine with 4 threads\n./tsn relay                 # Run relay node\n./tsn light                 # Run light client\n./tsn wallet                # Interactive wallet menu\n./tsn balance               # Check balance\n./tsn send --to \u003caddr\u003e --amount 10  # Send TSN\n./tsn new-wallet            # Generate new wallet (24-word BIP39 seed)\n./tsn --version             # Print version info\n```\n\n## Node Types\n\nTSN supports 3 distinct node roles, selectable at startup:\n\n### Miner Node (`./tsn miner`)\nFull 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.\n\n### Relay Node (`./tsn relay`)\nFull 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).\n\n### Cortex Node (`./tsn cortex`)\nService 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.\n\n### Light Client (`./tsn light`)\nMinimal 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.\n\n| Type | Stores Chain | Mines | Relays | dApps | Auto-Update | Reward |\n|------|:-:|:-:|:-:|:-:|:-:|--------|\n| **Miner** | Yes | Yes | Yes | — | Yes | 92% block reward |\n| **Relay** | Yes | — | Yes | — | Yes | 3% relay pool |\n| **Cortex** | Yes | — | Yes | Yes | Yes | dApp fees |\n| **Light Client** | — | — | — | — | Yes | — |\n\nAll node types auto-update when a new version is detected on the network.\n\n## P2P Auto-Update\n\nTSN 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.\n\n**How it works:**\n1. Peers announce their version during the libp2p Identify handshake\n2. If a peer has a newer version, the node queries the official release\n3. Binary is downloaded from GitHub (primary) or tsnchain.com (fallback)\n4. SHA256 integrity check + Ed25519 signature verification\n5. Current binary backed up, new binary installed, node restarts\n\n```\nNode A (v2.9.14) connects to Node B (v2.9.15)\n  → A detects newer version via P2P handshake\n  → A downloads v2.9.15 from GitHub, verifies Ed25519 signature\n  → A self-updates and restarts\n  → A is now v2.9.15\n  → A's other peers detect the update via handshake\n  → Network propagates the update in minutes\n```\n\nManual update: `./tsn update`\n\n## Mining \u0026 Hashrate — Poseidon2 Proof of Work\n\nTSN uses **Poseidon2** as its PoW hash function instead of SHA-256 (Bitcoin) or RandomX (Monero):\n\n- **ZK-native**: Same hash for mining AND shielded transaction proofs (Plonky3 STARKs). One hash for the entire stack.\n- **Post-quantum friendly**: Algebraic hashes over large fields resist Grover's algorithm.\n- **ASIC-resistant**: Field arithmetic is complex enough that ASICs offer limited advantage over CPUs.\n\n### How Mining Works\n\n```\n1. Build block template (transactions + coinbase)\n2. Generate random 512-bit nonce\n3. Hash: Poseidon2(header_fields, nonce) → 32 bytes\n4. Check: first_8_bytes_as_u64 \u003c (u64::MAX / difficulty)\n5. Valid → broadcast block. Invalid → new nonce.\n```\n\n### Hashrate Benchmarks\n\n| CPU | Threads | Hashrate |\n|-----|---------|----------|\n| EPYC 7742 | 1T | 121 KH/s |\n| EPYC 7742 | 4T | 257 KH/s |\n| EPYC 7742 | 8T | 454 KH/s |\n| Xeon E5-2697A v4 | 2T | ~80 KH/s |\n\n**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.\n\n### Network Hashrate Formula\n\n```\nnetwork_hashrate = difficulty / block_time\n```\n\nDisplayed in the explorer and `/chain/info` API.\n\n## Smart Contracts\n\nTSN includes a **stack-based zkVM** with gas metering and ZK execution traces:\n\n- **30+ opcodes**: arithmetic, storage, memory, crypto (Poseidon hash, signature verify), control flow, events\n- **Contract templates**: Escrow (with arbitration \u0026 timeout), Multisig (N-of-M), AMM Pool, Governance\n- **Gas model**: per-opcode costs, block gas limit 1M, max 64KB bytecode, 100K storage slots\n\n## Network Parameters\n\n| Parameter | Value |\n|-----------|-------|\n| HTTP API Port | 9333 |\n| P2P Port (libp2p) | 9334 |\n| Block Reward | 13.52 TSN at launch (92% miner, 5% dev, 3% relay) |\n| Halving Eras | 6 eras over ~10 years |\n| Target Block Time | ~10 seconds |\n| Difficulty Adjustment | LWMA per-block (N=45 window) |\n| P2P Protocol | libp2p GossipSub mesh (D=6, heartbeat 700ms) |\n| Max Reorg Depth | 100 blocks |\n| Min Difficulty | 1,500,000 |\n| Nonce Size | 512 bits |\n| Max TX Size | 1 MB |\n| Max Supply | 100,000,000 TSN (hard cap) |\n\n## Tokenomics\n\nTSN 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.\n\n### Halving Schedule\n\n| Era | Reward/block | Duration | TSN Mined | Cumulative |\n|-----|-------------|----------|-----------|------------|\n| 1 | 13.52 TSN | ~6 months | 21.5M | 21.5M |\n| 2 | 6.76 TSN | ~23 months | 40.5M | 62.0M |\n| 3 | 3.38 TSN | ~23 months | 20.3M | 82.3M |\n| 4 | 1.69 TSN | ~23 months | 10.1M | 92.4M |\n| 5 | 0.85 TSN | ~23 months | 5.1M | 97.5M |\n| 6 | 0.42 TSN | ~23 months | 2.5M | 100.0M |\n\n### Distribution\n\n- **92%** → Miners (block reward)\n- **5%** → Dev fund (protocol development)\n- **3%** → Relay pool (network infrastructure)\n\n### Timeline\n\n- **Now** — Private testnet (50 TSN/block, tokens have no monetary value)\n- **May 2027** — Incentivized testnet with real tokenomics *(subject to readiness)*\n- **~2037** — Final TSN mined (100M hard cap reached)\n\n\u003e ⚠️ The private testnet uses a simplified 50 TSN/block reward. The halving schedule above will take effect starting from the incentivized testnet phase.\n\n## Synchronization \u0026 Anti-Fork System\n\n### Fast-Sync Protocol\n\nNew nodes join the network in **seconds** by downloading a compressed state snapshot:\n\n```\n┌─────────────┐     GET /snapshot/info      ┌─────────────┐\n│  New Node   │ ──────────────────────────\u003e  │  Seed Node  │\n│             │     GET /snapshot/download   │             │\n│  --fast-sync│ \u003c────────────────────────── │  (gzip)     │\n│             │                              │             │\n│  Load state │     GET /blocks?from=N       │             │\n│  Sync rest  │ ──────────────────────────\u003e  │             │\n└─────────────┘                              └─────────────┘\n```\n\n1. New node requests a **gzip-compressed state snapshot** from a peer\n2. Loads the snapshot and verifies `state_root` integrity\n3. Syncs only the **missing blocks** since the snapshot height\n4. Ready to mine in ~2 seconds\n\n### Anti-Fork Protections\n\n| Protection | Description |\n|------------|-------------|\n| **Heaviest chain rule** | Fork choice based on cumulative work, not height |\n| **MAX_REORG_DEPTH = 100** | Hard limit — no reorg deeper than 100 blocks |\n| **Checkpoint finality** | Every 100 blocks, a checkpoint is created |\n| **Fork ID verification** | Genesis hash checked at sync — prevents silent splits |\n| **Anchor block filter** | Blocks must reference a recent valid ancestor |\n| **P2P version gate** | Nodes below MINIMUM_VERSION (v2.9.15) are rejected, with escalating IP bans on repeat offenders |\n| **Genesis HTTP check** | Peer genesis block hash verified before any sync |\n| **Protocol magic** | TSN2 magic bytes — old network nodes cannot connect |\n| **Smart auto-wipe watchdog** | Solo-fork detection with cooldown + kill-switch guards |\n| **Signed snapshots** | Ed25519-signed fast-sync snapshots, optionally mirrored on GitHub |\n\n## Testnet Status\n\nThe 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).\n\n\u003e **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.\n\n**Roadmap:**\n1. **Private Testnet** — Active now. Internal testing and development.\n2. **Open Testnet** — Code on GitHub. Anyone can run a node and mine. No value.\n3. **Incentivized Testnet** — Rewards for miners and node operators. Tokens begin to have value.\n4. **Mainnet** — Genesis block. Fair launch. No premine.\n\n## Roadmap\n\n### Phase 1 — Foundations ✅\nCore 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.\n\n### Phase 2 — Advanced Features ✅\nMulti-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).\n\n### Phase 3 — Smart Contracts \u0026 DeFi ✅\nzkVM (30+ opcodes), contract templates (Escrow, Multisig, AMM Pool, Governance), stablecoin module (ZST — gold-backed), P2P auto-update system.\n\n### Phase 4 — Launch\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│                                                                  │\n│  APRIL 2026          MAY — JULY 2026            Q3 2026          │\n│                                                                  │\n│  ┌──────────┐        ┌──────────────────┐       ┌────────────┐  │\n│  │ PRIVATE  │───────\u003e│   INCENTIVIZED   │──────\u003e│  MAINNET   │  │\n│  │ TESTNET  │        │  PUBLIC TESTNET  │       │  LAUNCH    │  │\n│  └──────────┘        └──────────────────┘       └────────────┘  │\n│                                                                  │\n│  • 5 internal nodes   • Open to everyone        • Genesis block  │\n│  • Stress testing     • Bug bounty program      • Fair launch    │\n│  • Core validation    • Node operator rewards   • No premine     │\n│  • ZK proof testing   • Security audit          • Full privacy   │\n│                       • 2-3 months duration     • zkVM live      │\n│                                                                  │\n└──────────────────────────────────────────────────────────────────┘\n```\n\n## Ecosystem\n\nTSN is more than a blockchain — it's a full ecosystem of decentralized applications.\n\n### Whispr — Decentralized Private Social Network (v0.4.0, Live)\n\nA 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.\n\n- **Whisps** (short posts) + **Articles** (long-form blog) with upvote/downvote\n- **Circles** — Community groups with rooms, roles, polls, auto-moderation\n- **E2E Encrypted DMs** — ECDH P-256 + AES-256-GCM\n- **BIP39 Identity** — 24-word seed phrase, no email, no phone\n- **5 P2P Nodes** — Rust binary, libp2p gossipsub\n- **App**: [whispr.tsnchain.com](https://whispr.tsnchain.com)\n- **GitHub**: [github.com/trusts-stack-network/whispr](https://github.com/trusts-stack-network/whispr)\n- **Releases**: [github.com/trusts-stack-network/whispr-releases](https://github.com/trusts-stack-network/whispr-releases) (Linux + Windows + macOS)\n\n### ZST — Gold-Backed Stablecoin (In Development)\n\nA 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.\n\n- **3 assets**: TSN (collateral) → ZST (stablecoin) + ZRS (reserve share)\n- **Reserve engine**: 76 tests passing, mint/burn with dynamic fees\n- **Protections**: stress fees 0.3%-5%, circuit breaker at 120%, cooldown mechanism\n\n### NetherSwap — Decentralized Exchange (In Development)\n\nA cross-chain anonymous DEX built on TSN with AMM pools, escrow P2P, yield farming, governance DAO, and prediction markets.\n\n- **AMM Swap** with smart router (multi-hop), limit orders\n- **Liquidity Pools** with yield farming rewards\n- **P2P Escrow** for trustless OTC trades\n- **DAO Governance** — community-driven proposals and voting\n- **Cross-chain** — relayers staked in TSN\n- **Privacy** — anonymous trading via TSN shielded transactions\n\n## Changelog\n\n\u003e Full history: [CHANGELOG.md](CHANGELOG.md)\n\n### v2.9.x — Checkpoint Voting \u0026 Backfill (2026-Q2)\n\n- **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.\n- **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`.\n- **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.\n- **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()`.\n- **v2.9.15** — MINIMUM_VERSION gate: nodes below v2.9.15 rejected at handshake with escalating IP bans.\n- **v2.9.14** — Backport W1+W1B+H-G+FIX-D patches; auto-recovery timeout extended to 180s.\n- **v2.9.13** — `--role` defaults to relay; full auto-recovery cycle on lost consensus.\n- **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.\n- **v2.9.8** — CHECKPOINT_QUORUM dynamic 80% with warmup limited to common circuit shapes (Plonky3 RAM fix).\n- **v2.9.7** — Persistent libp2p identity key; `network_name` in `/version.json`; Phase C HTTP fallback; checkpoint history endpoint.\n- **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.\n- **v2.9.2** — CHECKPOINT_QUORUM raised to 4; `/chain/quorum_status` endpoint; explorer quorum halo badge.\n- **v2.9.1** — RAM diet: sled cache 1G→256M, block LRU 1000→200, recompute fast-sync anchor; anchor-retry timeout.\n- **v2.9.0** — BIP-152 RAM fix: filter mempool by short_id before clone.\n\n### v2.8.x — Compact Blocks, Checkpoint \u0026 Iron Fish Wallet (2026-Q2)\n\n- **v2.8.9** — Trusted-quorum checkpoint vote; BIP-152 DoS protections (max announces, dedup window, rate limit per peer).\n- **v2.8.8** — Phase 1 hardening: invalid anchor retry with exponential backoff.\n- **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.\n- **v2.8.6** — Proactive tip-pull (Phase 0.2 simplified): nodes pull latest tip on GossipSub announcement.\n- **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).\n- **v2.8.1** — Phase A pipeline fixes; MAX_SPENDS raised from 25 to 50.\n- **v2.8.0** — Phase C wallet bootstrap; signed snapshot; auto-consolidate ON by default.\n\n### v2.7.x — Performance \u0026 Fork Hardening (2026-Q2)\n\n- **v2.7.4** — Anti-freeze HTTP timeouts; lock-free chain reads; explorer aggregate fixes.\n\n### v2.5.x — Cortex Node \u0026 Fork-Choice Fixes (2026-Q2)\n\n- **v2.5.0** — 4 fork-choice fixes; **Cortex node Phase 1** (WASM runtime for dApp service modules); testnet-v9 reset.\n\n### v2.4.x — Relay Pool, DNS Bootstrap \u0026 Testnet Resets (2026-Q2)\n\n- **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.\n- **v2.4.2** — Testnet-v7 reset (private test build).\n- **v2.4.1** — DNS-aware P2P bootstrap (`seed1-4.tsnchain.com`); MINIMUM_VERSION bumped.\n- **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).\n\n### v2.3.x — Post-quantum network hardening (2026-Q2)\n\n- **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.\n- **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).\n- **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.\n- **v2.3.4** — P2P `NewBlock` mempool cleanup in `spawn_blocking`, snapshot persistence to disk with 24h retention, `cmd_balance` orphan-aware display.\n- **v2.3.3** — Pre-validate orphan notes before `cmd_send` to avoid retry loops after chain reorgs.\n- **v2.3.2** — Wallet rescan actually deletes DB rows, metrics port auto-fallback 9090..9099, `WalletLock::try_acquire` returns an actionable error.\n- **v2.3.1** — Admin `/mempool/purge` endpoint, HTTP 429 backoff (1s → 32s) on witness fetch and tx submit, auto-consolidation multi-round orchestration.\n- **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.\n\n### v2.0.0 — Network Reset \u0026 Sync Stability\n\n**Breaking:** New network identity, protocol magic, and genesis — all previous versions are incompatible.\n\n- **Network reset**: fresh genesis (`tsn-testnet-v2`), clean chain from block 0\n- **Protocol magic**: `TSN1` → `TSN2` — old nodes cannot parse messages\n- **MINIMUM_VERSION**: `2.0.0` — old nodes explicitly rejected at handshake\n- **Genesis HTTP check**: peer's genesis block hash verified via REST before any sync\n- **EXPECTED_GENESIS_HASH**: hardcoded and verified at startup — prevents silent chain forks\n- **Sync stability (patches A+B+D)**: validated across 6 tests including 20 miners on 2 EPYC machines for 1 hour\n  - Patch A: prevent rollback thrashing to fast_sync_base\n  - Patch B: prevent peer isolation via ban cascade with 10+ peers\n  - Patch D: guard reset_for_snapshot_resync in post-fast-sync warmup window\n- **Headers-first sync**: refactored ancestor search with fast-sync blind zone detection\n- **Open network**: IP whitelist removed, compatibility enforced via version + magic + genesis\n- **Poseidon2 from genesis**: no legacy hash period, clean start\n- **node-1**: converted from miner to relay-only (dedicated to explorer/website)\n\n**Migration:** Stop node, delete `data/` directory, install v2.0.0 binary, restart. Old chain data is incompatible.\n\n### v1.4.0 — Consensus Security Overhaul\n\nMajor consensus upgrade fixing 19 bugs in fork resolution, snapshot validation, and self-healing.\n\n- **Heaviest chain rule**: Fork choice now ALWAYS uses cumulative_work (was height-based for short forks). Tiebreaker: difficulty then hash.\n- **Persistent cumulative_work**: New sled tree stores cumulative_work per height. Survives LRU eviction and restarts.\n- **PoW validation in trusted mode**: `add_block_trusted()` now verifies PoW and MIN_DIFFICULTY. Prevents importing invalid blocks during fast-sync.\n- **Orphan PoW validation**: Orphan pool rejects blocks with invalid PoW or below MIN_DIFFICULTY before storing.\n- **Graduated difficulty tolerance post fast-sync**: Within LWMA_WINDOW (45 blocks) of fast-sync base, accepts 25% margin. After that, enforces normal 10%.\n- **Accurate rollback work**: Uses DB-stored cumulative_work instead of `difficulty * depth` estimation. Falls back to summing actual block difficulties.\n- **Conservative snapshot work estimate**: When peer_cumulative_work is unavailable, uses MIN_DIFFICULTY * height (not difficulty * height).\n- **Peer selection by work**: Fast-sync, stuck detection, and auto-resync now select peers by cumulative_work, not height alone.\n- **Multi-peer agreement**: Auto-resync requires at least 2 peers agreeing (within 5% of max work) before triggering.\n- **Peer work verification**: New `verify_peer_work_sample()` helper samples blocks to validate a peer's claimed work.\n- **Faster trusted snapshots**: Snapshot interval in trusted mode reduced from 500 to 50 blocks for faster recovery.\n- **MINIMUM_VERSION**: bumped to 1.4.0\n\n### v1.3.7 — Self-Healing Nodes: Missing Snapshot Recovery\n\n- **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`\n- **MINIMUM_VERSION**: bumped to 1.3.7\n\n### v1.3.6 — Windows Fix, Snapshot Sync at Height 0, Node Role Detection\n\n- **Sync loop at height 0**: Nodes stuck at height 0 now use snapshot sync instead of block-by-block\n- **Stuck detection at height 0**: Auto-resync watchdog now catches nodes stuck at height 0\n- **Windows fix**: verification key checksum now normalizes line endings (CRLF → LF) before SHA256\n- **nodes.html fix**: P2P peers fetched from correct API endpoint (shows miner badges correctly)\n- **.gitattributes**: forces LF line endings for verification key files across platforms\n- **MINIMUM_VERSION**: bumped to 1.3.6\n\n### v1.3.0 — Chain Reset, Halving Fix \u0026 Sync Stability\n\n- **Halving interval**: 210,000 → **4,200,000 blocks** (~16 months per halving, supply max in ~10 years)\n- **Chain reset**: fresh genesis block with correct economics\n- **Critical fix**: rollback `canonical_height` bug causing infinite sync loops\n- **P2P Auto-Update**: nodes detect + download + verify + self-update\n- **Explorer URL**: points to `explorer.tsnchain.com`\n- **Default mode**: `./tsn` auto-creates wallet and mines (no subcommand needed)\n- **Verification keys**: searched next to binary + parent dirs (build from source works)\n- **Firewall**: port 9333 open on all nodes for HTTP sync\n\n### v1.1.0 — Performance \u0026 Production Hardening\n\n| Feature | Before | After |\n|---------|--------|-------|\n| Mining Hot Loop | Full header rebuilt per hash | MiningHashContext — zero heap alloc |\n| Hashrate Display | Truncated hash, no KH/s | Real-time KH/s, full hash |\n| Explorer Hashrate | Wrong formula | Corrected: `difficulty / block_time` |\n| Wallet TX History | Not saved | Sent + received persisted (WalletTxRecord) |\n| Received TX Detection | Manual | Automatic at wallet scan |\n| Nullifier Check | At send only | At scan + send (prevents double-spend) |\n| P2P Version Gate | Accept all peers | Reject peers below MINIMUM_VERSION |\n| CLI | Multiple flags required | `./tsn miner -t 4` — everything auto-detected |\n| Auto-Update | None | P2P signaling + multi-source download + SHA256 verification |\n\n### v0.8.0 — Transactions, Wallet \u0026 Security\n\n- Working V2 shielded transactions (create, sign, broadcast, validate)\n- Interactive wallet menu with BIP39 recovery\n- MAX_REORG_DEPTH = 100, Fork ID verification, anchor block filtering\n- Dual mining across multiple nodes\n\n### v0.7.1 — Security Audit \u0026 Hardening\n\nFull security audit: 29 findings, 23 fixes applied. Score: **5.4/10 → 8.1/10**. Zero critical vulnerabilities remaining.\n\n### v0.7.0 — Scaling \u0026 Reliability\n\n- LWMA per-block difficulty adjustment (N=45 window)\n- GossipSub mesh P2P (replaced flood protocol)\n- Cryptographic random nonces (zero miner collisions)\n- Concurrent block relay, canonical height in DB\n\n### v0.6.0 — Major Network Upgrade\n\n- Numeric difficulty system with 512-bit nonce\n- Poseidon2 PoW (plonky3)\n- Fast sync (~2 seconds)\n- BIP39 wallet recovery\n- DNS seed discovery\n- Chain Watchdog monitoring\n\n## Codebase\n\n| Metric | Value |\n|--------|-------|\n| Language | Rust 2021 edition |\n| Lines of code | 97,000+ |\n| Source files | 300+ |\n| Tests | 370+ passing |\n| Commits | 420+ |\n| Nodes | 5 (relay + 4 seeds) |\n\n## API\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /chain/info` | Block height, difficulty, latest hash, version |\n| `GET /peers` | Connected peers |\n| `GET /sync/status` | Sync progress and peer count |\n| `GET /block/height/:n` | Get block by height |\n| `POST /tx/submit` | Submit shielded transaction |\n| `GET /explorer` | Built-in block explorer |\n| `GET /version.json` | Node version info (used by auto-update) |\n\n## Links\n\n- **Website**: [tsnchain.com](https://tsnchain.com)\n- **Explorer**: [explorer.tsnchain.com](https://explorer.tsnchain.com)\n- **Whispr**: [whispr.tsnchain.com](https://whispr.tsnchain.com)\n- **Whitepaper**: [tsnchain.com/whitepaper.html](https://tsnchain.com/whitepaper.html)\n- **Documentation**: [tsnchain.com/docs.html](https://tsnchain.com/docs.html)\n- **Run a Node**: [tsnchain.com/run-node.html](https://tsnchain.com/run-node.html)\n- **Blog**: [tsnchain.com/blog.html](https://tsnchain.com/blog.html)\n- **X/Twitter**: [x.com/tsn_chain](https://x.com/tsn_chain)\n- **Medium**: [medium.com/@trusts-stack-network](https://medium.com/@trusts-stack-network)\n- **Discord**: [discord.gg/wxxNVDVn6N](https://discord.gg/wxxNVDVn6N)\n\n## License\n\nMIT — Open source.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrusts-stack-network%2Ftsn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrusts-stack-network%2Ftsn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrusts-stack-network%2Ftsn/lists"}