TSN Documentation

⚡ Getting Started

TSN (Trust Stack Network) is a post-quantum, privacy-first blockchain built in Rust. Transactions are shielded by default using zero-knowledge proofs, and all cryptography is quantum-resistant.

System Requirements

Quick Start

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

git clone https://github.com/trusts-stack-network/trust-stack-network.git
cd trust-stack-network
cargo build --release

./target/release/tsn --data-dir ~/.tsn

⚫ Run a Node

Full Node

A full node validates all transactions and blocks, stores the complete blockchain history, and participates in block propagation.

./target/release/tsn \
    --data-dir ~/.tsn \
    --port 9333 \
    --seeds http://seed1.tsnchain.com:9333,http://seed2.tsnchain.com:9333

Configuration

Multi-Role Nodes

TSN supports 3 specialized node roles via the --role CLI flag. Each role optimizes resource usage for its specific function in the network:

# Run as a miner node (default)
./target/release/tsn --role miner --mining-address YOUR_ADDRESS --data-dir ~/.tsn --port 9333

# Run as a relay node
./target/release/tsn --role relay --data-dir ~/.tsn --port 9333

# Run as a light client
./target/release/tsn --role light --data-dir ~/.tsn --port 9333

Connect to Seed Nodes

Seed nodes help your node discover other peers on the network. TSN uses a Kademlia DHT for peer discovery after initial bootstrap.

Docker Coming Soon

docker run -d --name tsn-node \
    -p 9333:9333 \
    -v tsn-data:/root/.tsn \
    ghcr.io/trusts-stack-network/tsn:latest

⛏ Mining

TSN uses Proof of Work with the Poseidon2 hash function over the Goldilocks field. Mining is deliberately ASIC-resistant and ZK-proof friendly.

Start Mining

To mine, you need a wallet address. Start your node with the --mining-address flag:

./target/release/tsn \
    --data-dir ~/.tsn \
    --mining-address YOUR_PUBLIC_KEY \
    --seeds http://seed1.tsnchain.com:9333

Mining Parameters

Understanding Hashrate

Monitor Mining

Check your mining stats via the API:

curl http://localhost:9333/miner/stats

🔑 Wallet

TSN wallets use ML-DSA-65 (NIST FIPS 204) post-quantum signatures with BIP39 mnemonic recovery. Your keys are safe against both classical and quantum attacks, and can be restored from a 24-word seed phrase.

Generate a Wallet

# Create a new wallet
./tsn new-wallet --output wallet.json
# The terminal displays 24 words -- WRITE THEM DOWN!

This generates a new ML-DSA-65 key pair with a BIP39 mnemonic seed phrase and saves it to a wallet file. Your public key is your wallet address.

Restore from Seed Phrase

If you lose your wallet file, you can restore it using your 24-word seed phrase:

# Restore wallet from seed phrase
./tsn restore-wallet --seed "word1 word2 ... word24" --output wallet.json

# Check your balance
./tsn balance --wallet wallet.json

Key Features

Viewing Key Export & Import

Viewing keys allow you to share read-only access to your shielded balance without exposing your spending key. Useful for auditors, tax reporting, or watch-only wallets.

# Export your viewing key
./target/release/tsn wallet export-viewing-key --output viewing_key.json

# Import a viewing key (watch-only)
./target/release/tsn wallet import-viewing-key --input viewing_key.json

Send a Transaction

curl -X POST http://localhost:9333/tx/v2 \
    -H "Content-Type: application/json" \
    -d '{
        "from": "YOUR_PUBLIC_KEY",
        "to": "RECIPIENT_PUBLIC_KEY",
        "amount": 10000000000,
        "signature": "..."
    }'

Amounts are in base units. 1 TSN = 1,000,000,000 base units.

Backup & Restore

# Option 1: Restore from seed phrase (recommended)
./tsn restore-wallet --seed "word1 word2 ... word24" --output wallet.json

# Option 2: File backup
cp -r ~/.tsn/wallet/ ~/tsn-wallet-backup/

# Option 2: File restore
cp -r ~/tsn-wallet-backup/ ~/.tsn/wallet/

Auto-Update

TSN nodes automatically detect and install new versions. When a peer announces a newer version during the P2P handshake, your node downloads the update from GitHub (or tsnchain.com fallback), verifies the SHA256 checksum, backs up the current binary, and restarts with the new version.

./tsn update    # Manual update check

⚠️ TSN tokens currently have no monetary value. This is a development testnet. Tokens can be mined for free.

🔌 API Reference

#128268; API Reference

TSN exposes a RESTful JSON API on the same port as the node (default 9333). Rate limited to prevent abuse.

Blockchain

curl http://localhost:9333/chain/info

{
    "height": 14523,
    "best_hash": "a1b2c3d4e5f6...abc123",
    "difficulty": "0000ffff00000000...",
    "version": "1.0.0",
    "peers": 12,
    "mempool_size": 3
}

curl http://localhost:9333/block/a1b2c3d4e5f6abc123

curl http://localhost:9333/block/height/1000

Transactions

curl -X POST http://localhost:9333/tx \
    -H "Content-Type: application/json" \
    -d '{"from":"...","to":"...","amount":50000000000,"signature":"..."}'

curl -X POST http://localhost:9333/tx/v2 \
    -H "Content-Type: application/json" \
    -d '{
        "from": "YOUR_PUBLIC_KEY",
        "to": "RECIPIENT_PUBLIC_KEY",
        "amount": 10000000000,
        "signature": "..."
    }'

curl http://localhost:9333/tx/a1b2c3d4...

curl http://localhost:9333/transactions/recent

Network

curl http://localhost:9333/peers

{
    "peers": [
        {"node_id": "a1b2c3...", "addr": "seed2.tsnchain.com:9333", "latency_ms": 12},
        {"node_id": "d4e5f6...", "addr": "seed3.tsnchain.com:9333", "latency_ms": 8}
    ],
    "count": 2
}

curl -X POST http://localhost:9333/peers \
    -H "Content-Type: application/json" \
    -d '{"addr": "seed2.tsnchain.com:9333"}'

curl http://localhost:9333/mempool

curl http://localhost:9333/sync/status

{
    "synced": true,
    "local_height": 14523,
    "network_height": 14523,
    "peers_syncing": 0
}

Mining

curl http://localhost:9333/miner/stats

{
    "mining": true,
    "hashrate": "1.2 MH/s",
    "blocks_mined": 42,
    "total_reward": "2100 TSN",
    "current_difficulty": "0000ffff..."
}

🌐 Network

TSN uses a Kademlia-based P2P network with gossip protocol for block and transaction propagation.

Protocol Details

Seed Nodes

The testnet currently runs 4 seed nodes across Europe. Connect to any of them to bootstrap your node.

./target/release/tsn --seeds \
    http://seed1.tsnchain.com:9333,\
    http://seed2.tsnchain.com:9333,\
    http://seed3.tsnchain.com:9333,\
    http://seed4.tsnchain.com:9333

🛠 Architecture

TSN is a modular blockchain built entirely in Rust. Every layer is designed for post-quantum security and privacy.

                     TSN Blockchain
          +---------------------------------+
          |          REST API (Axum)         |  <-- Port 9333
          +---------+-----------+-----------+
                    |           |           |
          +---------+  +-------+-------+  ++---------+
          | Mempool |  |   Consensus   |  | P2P Net  |
          | (pool)  |  | PoW+Poseidon2 |  | Kademlia |
          +----+----+  +-------+-------+  +----+-----+
               |               |               |
          +----+---------------+---------------+----+
          |              Core Engine                 |
          |   Blocks | Transactions | State (UTXO)  |
          +-----+----------+----------+-------------+
                |          |          |
          +-----+--+  +---+----+  +--+------+
          | Storage |  | Crypto |  | Wallet  |
          |  (Sled) |  | ML-DSA |  | ML-DSA  |
          |         |  | SLH-DSA|  | Shielded|
          +---------+  | Plonky3|  +---------+
                       +--------+

Cryptography Stack