Testnet Guide | Positronic Network

🌐

Testnet Parameters

Chain ID

420420

Network Name

Positronic Testnet

RPC URL

http://localhost:8545

Block Time

12s

Currency

ASF

P2P Port

9000

Min Stake

32 ASF

Consensus

DPoS + BFT

⚡

Quick Start

1

Download the App

Get the latest release from the Download page. Available for Windows, macOS, and Linux. No installation required on Windows — just run the executable.

2

Launch & Create Wallet

Open the app. Go to the Wallet tab and click Create. Your private keys are encrypted with AES-256-GCM and stored locally.

3

Get Test ASF

Copy your wallet address and visit the Faucet to receive free test ASF coins. You can request once every 24 hours.

4

Start Validating

Go to the Validator tab. Stake at least 32 ASF and your validator activates at the next epoch (~6 minutes). You'll earn block rewards automatically.

1

Clone the Repository

git clone https://github.com/BenevolenceMessiah/Positronic-AI.git
cd Positronic-AI
pip install -r requirements.txt

2

Run as Founder Node

The founder node creates the genesis block and starts producing blocks immediately:

python -m positronic --founder --p2p-port 9000 --rpc-port 8545

3

Run Additional Validator Nodes

Connect more nodes to the founder to form a network:

# Node 2 - connects to founder
python -m positronic --p2p-port 9001 --rpc-port 8546 --bootstrap 127.0.0.1:9000

# Node 3 - connects to founder
python -m positronic --p2p-port 9002 --rpc-port 8547 --bootstrap 127.0.0.1:9000

4

Run the Test Suite

Verify everything works:

# Run all 6,848+ tests (173 test files)
python -m pytest tests/ -v --timeout=300

# Run specific test category
python -m pytest tests/test_fuzz.py -v
python -m pytest tests/test_security_encryption.py -v

# Production hardening test suites
python -m pytest tests/test_property_invariants.py -v
python -m pytest tests/test_db_resilience.py -v
python -m pytest tests/test_memory_leaks.py -v
python -m pytest tests/test_chain_reorg.py -v
python -m pytest tests/test_upgrade_migration.py -v

1

Pull & Run with Docker

# Build from Dockerfile
docker build -t positronic .

# Run founder node
docker run -d --name positronic-node \
  -p 8545:8545 -p 9000:9000 \
  -v positronic-data:/data \
  positronic --founder

2

Multi-Node with Docker Compose

# docker-compose.yml (example)
version: '3.8'
services:
  founder:
    build: .
    command: --founder --p2p-port 9000 --rpc-port 8545
    ports:
      - "8545:8545"
      - "9000:9000"
  validator-1:
    build: .
    command: --p2p-port 9001 --rpc-port 8546 --bootstrap founder:9000
    depends_on:
      - founder
  validator-2:
    build: .
    command: --p2p-port 9002 --rpc-port 8547 --bootstrap founder:9000
    depends_on:
      - founder

🦊

Connect MetaMask / Trust Wallet

Positronic exposes a full Ethereum-compatible JSON-RPC API. Any EVM wallet (MetaMask, Trust Wallet, Coinbase Wallet) can connect to the testnet.

Network Name	Positronic Testnet
RPC URL	http://localhost:8545
Chain ID	420420
Currency Symbol	ASF
Block Explorer	http://localhost:8080 (local explorer)

Add Network via RPC Call

// Add Positronic testnet to MetaMask programmatically
await window.ethereum.request({
  method: 'wallet_addEthereumChain',
  params: [{
    chainId: '0x66A14',
    chainName: 'Positronic Testnet',
    rpcUrls: ['http://localhost:8545'],
    nativeCurrency: {
      name: 'Positronic',
      symbol: 'ASF',
      decimals: 18
    }
  }]
});

📊

HTTP Endpoints

`POST /`	JSON-RPC 2.0 API (all 213 methods)
`GET /health`	Health check (Docker HEALTHCHECK compatible)
`GET /metrics`	Prometheus metrics (text exposition format)

Prometheus Scrape Config

# prometheus.yml
scrape_configs:
  - job_name: 'positronic'
    scrape_interval: 5s
    static_configs:
      - targets: ['localhost:8545']

📡

Key RPC Methods

Ethereum-Compatible Methods

# Get current block number
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

# Get account balance
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0xYOUR_ADDRESS","latest"],"id":2}'

# Send raw transaction
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0xSIGNED_TX"],"id":3}'

Positronic-Specific Methods

# Get faucet drip (testnet only)
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"positronic_faucetDrip","params":["0xYOUR_ADDRESS"],"id":1}'

# Get network info
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"positronic_getNetworkInfo","params":[],"id":2}'

# Submit game result (authenticated)
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"positronic_submitGameResult","params":["0xADDR",{"score":100}],"id":3}'

⚙

Node Configuration

Command Line Flags

python -m positronic [OPTIONS]

  --founder           Start as founder node (creates genesis block)
  --p2p-port PORT     P2P listening port (default: 9000)
  --rpc-port PORT     JSON-RPC server port (default: 8545)
  --bootstrap HOST    Bootstrap peer address (host:port)
  --data-dir PATH     Data directory for blockchain storage
  --max-peers N       Maximum number of connected peers (default: 50)
  --log-level LEVEL   Logging level: DEBUG, INFO, WARNING (default: INFO)

Data Directories

# Windows
%APPDATA%\Positronic\

# macOS
~/Library/Application Support/Positronic/

# Linux
~/.positronic/

# Contents
  blockchain.db      # Encrypted SQLite database (blocks, txs, accounts)
  wallets/           # AES-256-GCM encrypted keystores
  admin.key          # Encrypted admin API key
  peers.json         # Known peer list
  logs/              # Node log files

❓

Frequently Asked Questions

What is the difference between testnet and mainnet?

Testnet ASF coins have no real value. The testnet is for development, testing, and experimentation. All data may be reset before mainnet launch. Use the faucet to get free test coins.

How many validators are needed?

The network can run with a single founder node. For consensus testing, 3+ validators are recommended. BFT finality requires at least 4 validators with 66%+ stake attesting.

What are the system requirements?

Minimum: 2 CPU cores, 4 GB RAM, 10 GB disk, Python 3.10+. Recommended: 4+ cores, 8 GB RAM, 50 GB SSD, dedicated machine or VPS.

Can I connect multiple nodes on one machine?

Yes! Just use different ports for each node. Example: Node 1 on ports 9000/8545, Node 2 on 9001/8546, Node 3 on 9002/8547. Connect them with the --bootstrap flag.

How do I report bugs?

Check our Bug Bounty Program for rewards on security vulnerabilities. For general bugs, open an issue on GitHub Issues.

Is the database encrypted?

Yes. Positronic supports AES-256-GCM encryption at rest for the SQLite database. The admin API key is also encrypted with a machine-bound key. All wallet keystores use AES-256 with PBKDF2 (100K iterations).