Animica L1 Blockchain

Canonical repo: main of animicaorg/all is the canonical source tree. Current release: 10.1.0 (pip install animica).

Animica is a fully decentralized layer-1 blockchain platform for verifiable AI and quantum-secure execution. This repository houses the complete blockchain node implementation, consensus engine, execution layer, cryptographic infrastructure, wallets, SDKs, developer tooling, and supporting services for running and extending the network.

🌟 Key Features

Fully Decentralized P2P Network: Gossip-based peer discovery and communication with no central authority
Post-Quantum Cryptography: ML-DSA-65 (FIPS 204, the successor of Dilithium3) signatures — scheme id 0x1003, the only current signature scheme. SPHINCS+ appears in older code/docs but is legacy; do not build on it. Enumerate live schemes via the tx.getSupportedSignatureSchemes RPC.
PoIES Consensus: Proof-of-Integrated-External-Services combining hash-share work with AI/Quantum/Storage proofs
Multiple Transport Protocols: TCP, QUIC, and WebSocket with end-to-end encryption
Python-VM Execution: Deterministic Python-based smart contracts with gas metering
AI & Quantum Integration: Off-chain compute coordination via AICF (AI Capability Framework)
Multi-Network Support: Mainnet, testnet, devnet configurations with isolated state
Developer Tools: Studio IDE, contract templates, multi-language SDKs (Python, TypeScript, Rust)
Fast Sync with Snapshots: Bootstrap new nodes in minutes using pre-built chain snapshots at checkpoints

📁 Repository Structure

This monorepo contains:

Core Protocol: core/, consensus/, execution/, mempool/, rpc/, p2p/, mining/
- P2P Network (p2p/): Full peer-to-peer networking with quantum-resistant handshake, gossip protocol, and multi-transport support
- Consensus (consensus/): PoIES algorithm for decentralized block validation
Cryptography & Proofs: proofs/, zk/, pq/, randomness/
Wallets & Explorer:
- wallet-qt/ - Qt desktop wallet with embedded node (macOS/Windows/Linux)
- wallet/ - Flutter mobile wallet
- wallet-extension/ - Browser extension wallet
- explorer-web/ - Block explorer
Mining: mining/ (core), apps/miner-gui/ (Qt desktop GUI miner)
Studio & Tooling: studio-web/, studio-wasm/, studio-services/, templates/
SDKs & APIs: sdk/ (Python/TypeScript/Rust), docs/ (specifications), spec/ (canonical schemas)
Operations: ops/, tests/devnet/, installers/, chains/ (network metadata)
Website: website/ (Astro + TypeScript main site)
Compute Platform: packages/ (Auth, Billing, Inference, Sandbox, GitHub App services) - See COMPUTE_PLATFORM_QUICKSTART.md

Each module has its own README with detailed information. See the Copilot instructions at the bottom of this file for coding guidelines.

🚀 Animica Compute + LLM Cloud Platform

The Animica Compute Platform provides enterprise-ready LLM inference, code execution, and GitHub integration with native ANM token payments.

Quick Start:

make compute-dev  # Start all compute services with Docker Compose

See COMPUTE_PLATFORM_QUICKSTART.md for detailed setup instructions.

🌍 Website

The production website lives in website/. See website/README.md for local dev and Docker deployment (nginx on port 4321).

🌐 Decentralized Architecture

Animica is a fully peer-to-peer network where nodes communicate directly without relying on central servers:

✅ Peer Discovery: Automatic discovery via DNS seeds, mDNS, and Kademlia DHT
✅ Gossip Protocol: Efficient block/transaction/proof propagation
✅ Consensus: Deterministic PoIES validation by all nodes
✅ No Central Authority: Public RPC nodes (e.g. https://rpc.animica.org/rpc) are convenience helpers for discovery and sync; run your own node for day-to-day queries and mining.

Run your own node to strengthen the network and maintain decentralization. See P2P Networking Guide for details.

🌐 Live Endpoints (Mainnet)

Service	Endpoint	Notes
Node JSON-RPC	`POST https://rpc.animica.org/rpc`	JSON-RPC 2.0. The `/rpc` path is required — the bare domain 301-redirects and breaks naive POST clients
Explorer REST API	`https://explorer.animica.org/api/…`	Free, no auth: `/head`, `/blocks`, `/tx/:hash`, `/address/:bech32`, `/richlist`, `/circulating-supply`, `/mining/info`, `/l2/`, `/aicf/`
Block explorer	`https://explorer.animica.org`	Web UI
Free AI inference	`https://animica.dev/v1`	OpenAI-compatible, keyless, 30 req/min/IP. Community-GPU capacity: check each model's `serving` flag in `/v1/models`
Mining pool	`stratum+tcp://pool.animica.org:3333`	PPS + sub-block shares; `:3334` = solo (95/5). Stats/Swagger: `https://pool.animica.org/api/docs`
Payments	`https://pay.animica.dev`	Merchant REST, hosted checkout, 2.00% fee, amounts in base units (1 ANM = 10^9)
PyPI	`https://pypi.org/project/animica/`	`pip install animica`

Example:

curl -s -X POST https://rpc.animica.org/rpc -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"chain.getHead","params":{}}'

📋 Prerequisites

Required Software

Python 3.11+ with venv and pip
Node.js 20+ with npm
Docker and Docker Compose (v2.0+) for running nodes
Git for repository management

Build Tools (Optional, for Rust Components)

On Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y build-essential pkg-config libssl-dev

On macOS (via Homebrew):

brew install pkg-config openssl

Operating System Notes

Linux: Recommended for production (Ubuntu 22.04+ or Debian 12+)
macOS: Fully supported for development (macOS 12+)
Windows: Use WSL2 (Windows Subsystem for Linux) with Ubuntu 22.04+

🚀 Installation & Setup

🚴‍♂️ CLI Quickstart (Everything End-to-End)

Install dependencies & create the venv

./setup.sh            # or: FRESH=1 ./setup.sh --fresh
source .venv/bin/activate

Pick the network profile (determines RPC/P2P ports, data dir, and seeds):

animica network set devnet          # mainnet | testnet | devnet | local-devnet
animica network get                 # confirm selection

Start your node from the CLI (Docker Compose wrapper):

animica node up                     # background (default)
animica node up --no-detach         # foreground with logs
animica node up --with-miner        # include miner service

Verify health and sync:

animica node status                 # chain head, peers, sync info
animica node head                   # latest block header
animica peer list                   # connected peers (expect >0)
animica sync status                 # detailed sync progress

💡 Fast Sync with Snapshots:

New nodes can bootstrap much faster using chain snapshots:

# Verify snapshot system is working
python3 scripts/verify_snapshot_system.py

# Enable snapshot sync (enabled by default)
export ANIMICA_SNAPSHOT_SYNC_ENABLED=true
export ANIMICA_SNAPSHOT_RPC_URL=http://snapshots.animica.org:8545/rpc  # Optional

# Start node - automatically downloads snapshot if available
animica node up

# Or manually download/import snapshot
animica snapshot list
animica snapshot import /path/to/snapshot

See SNAPSHOT_VERIFICATION_GUIDE.md for complete guide and troubleshooting.

Ensure peers connect (connectivity checklist):

animica peer list --verbose         # shows multiaddrs + scores
docker compose -f tests/devnet/docker-compose.yml -p animica-devnet logs -f node1 | grep p2p

If peer count stays 0: verify ANIMICA_P2P_SEEDS (or use defaults), open TCP/QUIC ports on your host, and confirm you selected the right network. For a manual seed bump, set:

export ANIMICA_P2P_SEEDS="/dns4/seed.animica.org/tcp/30333"
animica node down && animica node up

Create a wallet and fund it (dev/test only):

animica wallet create --label mywallet
animica faucet request mywallet     # devnet/testnet only
animica wallet show mywallet --source chain

Send a transaction (with the running node):

animica tx send --from mywallet --to anim1recipient... --value 1.0
animica tx status <tx_hash>

Stop services when done:

animica node down                   # keep data
animica node down --volumes         # wipe data (irreversible)

Need a deeper walkthrough? The sections below expand on each CLI area (networking, node ops, wallets, mining, RPC, Studio Services, Docker, non-Docker boot, and troubleshooting).

💰 Animica Wallet Desktop App

For users who want a simpler "just works" experience without managing the CLI, the Animica Wallet Qt provides a cross-platform desktop application with an embedded node.

Downloads

Current Release: v0.1.0 (Coming Soon)

Platform	Download	Notes
🍎 macOS	`.dmg` installer	Universal (Apple Silicon + Intel)
🪟 Windows	`.msi` installer	Windows 10/11 (x64)
🐧 Linux	`.AppImage` or `.deb`	Universal AppImage or Debian package

Installation:

macOS: Download DMG, drag to Applications folder
Windows: Download MSI, run installer
Linux AppImage: Download, chmod +x, and run
Linux DEB: sudo dpkg -i animica-wallet_*.deb

Features

✅ Embedded Animica node (no separate installation needed)
✅ Full wallet management (create, import, send, receive)
✅ Network selection (mainnet/testnet/devnet)
✅ Live sync progress and node diagnostics
✅ Transaction history and address book
✅ Secure encrypted keystore

Building from Source

See wallet-qt/README.md for build instructions and wallet-qt/docs/RELEASING.md for packaging releases.

1. Clone the Repository

git clone https://github.com/animicaorg/all.git
cd all

2. Run Setup Script

The setup.sh script installs all dependencies and configures the environment:

# Standard installation
./setup.sh

# Fresh installation (removes existing .venv)
./setup.sh --fresh

# Using environment variable
FRESH=1 ./setup.sh

Setup Options

Run ./setup.sh --help to see all options:

Options:
  --fresh       Remove existing .venv and perform a clean installation
  -h, --help    Show help message

Environment Variables:
  FRESH=1                 Same as --fresh flag
  PIP_INDEX_URL           Primary pip package index
  PIP_EXTRA_INDEX_URL     Additional pip package index (for custom packages)

Custom Package Index

For internal deployments or testing with custom package repositories:

PIP_EXTRA_INDEX_URL=https://your-index.example.com/simple ./setup.sh

3. Activate Virtual Environment

After setup completes:

source .venv/bin/activate

4. Verify Installation

# Check that the CLI is installed
animica --help

# Test PQ cryptography
python -c "from animica.pq import kem_keygen, kem_encaps, kem_decaps; ek,dk=kem_keygen(); k,ct=kem_encaps(ek); assert kem_decaps(dk,ct)==k; print('✓ KEM ok')"
python -c "from animica.pq import sig_keygen, sig_sign, sig_verify; pk,sk=sig_keygen(); m=b'hi'; s=sig_sign(sk,m); assert sig_verify(pk,m,s); print('✓ SIG ok')"

If animica is not in your PATH, use the wrapper:

./animica --help

🌐 Network Configuration

Animica supports multiple network profiles with isolated data directories and non-conflicting ports:

Network	Chain ID	RPC Port	P2P Port	Metrics Port	Use Case
mainnet	1	8545	30333	9000	Production network
testnet	2	18546	31334	19000	Public testing
devnet	1337	28545	31335	29000	Local development
local-devnet	1337	38545	31336	39000	Alternative local setup

Set Active Network

The active network determines which configuration and data directory the CLI uses:

# Option 1: Set persistent network preference
animica network set devnet

# Option 2: Set via environment variable (session-only)
export ANIMICA_NETWORK=devnet

# Option 3: Use --network flag per command
animica --network testnet node status

Check Current Network

animica network get

List Available Networks

animica network list

Data Directory Isolation

Each network uses its own data directory to prevent state contamination:

Mainnet: ~/.local/share/animica/chain-1/ (Linux) or ~/Library/Application Support/animica/chain-1/ (macOS)
Testnet: ~/.local/share/animica/chain-2/
Devnet: ~/.local/share/animica/chain-1337/
Local-devnet: ~/.local/share/animica/chain-1337/

Environment Variables

ANIMICA_NETWORK: Active network name (mainnet, testnet, devnet, local-devnet)
ANIMICA_RPC_URL: Override default RPC endpoint
ANIMICA_CHAIN_ID: Override default chain ID

🌐 Decentralized P2P Network

Animica is fully decentralized - nodes connect directly to each other via P2P without any central authority. The public RPC at https://rpc.animica.org/rpc is provided for convenience and bootstrapping; wallets, miners, and explorers should prefer a locally run node after syncing.

P2P Features

✅ Automatic Peer Discovery: DNS seeds, mDNS, Kademlia DHT
✅ Quantum-Resistant: Kyber-768 + Dilithium3 post-quantum crypto
✅ Multi-Transport: TCP, QUIC, WebSocket support
✅ Gossip Protocol: Efficient block/tx/proof propagation
✅ Consensus: Independent PoIES validation by all nodes

Quick P2P Test

Verify your node connects to the decentralized network:

# Start a node
animica node up

# Check connected peers (should show 8-16 peers)
animica peer list

# Or via RPC
curl http://localhost:8545/rpc -H 'content-type: application/json' -d '{
  "jsonrpc":"2.0","id":1,"method":"p2p.listPeers","params":[]
}' | jq .

P2P Configuration

# P2P is enabled by default
export ANIMICA_P2P_ENABLE=true

# Set listen addresses (for public nodes)
export ANIMICA_P2P_LISTEN_TCP=0.0.0.0:30333
export ANIMICA_P2P_LISTEN_QUIC=0.0.0.0:443

# Set max peers
export ANIMICA_P2P_MAX_PEERS=64

# Use custom seeds
export ANIMICA_P2P_SEEDS="/dns4/my-seed.com/tcp/30333"

Documentation

P2P Networking Guide - Complete P2P architecture and troubleshooting
Multi-Node Docker Setup - Test multi-node networks locally

🖥️ Node Operations

Starting a Node

Before starting a node, set the network:

animica network set devnet

Start Node with Docker Compose

# Background mode (default)
animica node up

# Foreground mode with logs
animica node up --no-detach

# Include miner service
animica node up --with-miner

# Skip image rebuild
animica node up --no-build

Network-Specific Ports

When you start a node, it automatically uses the correct ports for your active network:

Mainnet: RPC 8545, P2P 30333, Metrics 9000
Testnet: RPC 18546, P2P 31334, Metrics 19000
Devnet: RPC 28545, P2P 31335, Metrics 29000
Local-devnet: RPC 38545, P2P 31336, Metrics 39000

Custom Port Configuration

Override default ports with environment variables:

HOST_RPC_PORT=9545 HOST_P2P_PORT=31337 animica node up

Stopping a Node

# Stop node (preserve data)
animica node down

# Stop and delete all data (WARNING: irreversible!)
animica node down --volumes

Check Node Status

# Get chain status and head block
animica node status

# Get just the chain head
animica node head

# Get specific block
animica node block --height 100
animica node block --hash 0xabc...

# Get transaction
animica node tx --hash 0x123...

View Node Logs

With Docker Compose directly:

# For devnet
docker compose -f tests/devnet/docker-compose.yml -p animica-devnet logs -f node1

# For mainnet (when using ops/docker/docker-compose.mainnet.yml)
docker compose -f ops/docker/docker-compose.mainnet.yml logs -f node

💼 Wallet Management

Create a Wallet

# Create new wallet with label
animica wallet create --label mywallet

# For development/testing only (uses fallback crypto if PQ unavailable)
animica wallet create --label devwallet --allow-insecure-fallback

List Wallets

animica wallet list

Output example:

Idx Default Label             Address                              Alg
--- ------- ----------------  -----------------------------------  ----------------
  0   *     premine           anim1zqqjt3258rgnfckqxv686unmg...   dilithium3
  1         mywallet          anim1abc123...                        dilithium3

Show Wallet Details

# By label
animica wallet show mywallet

# By address
animica wallet show anim1abc123...

# Show balance from chain (requires node running)
animica wallet show mywallet --source chain

# Show secret key (WARNING: sensitive!)
animica wallet show mywallet --show-secret --i-know-what-im-doing

Set the required environment variable:

export ANIMICA_ALLOW_SECRET=1
animica wallet show mywallet --show-secret --i-know-what-im-doing

Import a Wallet

# From JSON file
animica wallet import --file /path/to/wallet.json

# Override label on import
animica wallet import --file wallet.json --label imported

# Force overwrite existing
animica wallet import --file wallet.json --force

Export a Wallet

# Export by label
animica wallet export mywallet --out /secure/path/wallet-backup.json

# Export by address
animica wallet export anim1abc... --out wallet-backup.json

Set Default Wallet

animica wallet set-default mywallet

Wallet File Location

By default, wallets are stored in:

Linux: ~/.animica/wallets.json
macOS: ~/.animica/wallets.json
Windows (WSL): ~/.animica/wallets.json

Override with:

export ANIMICA_WALLETS_FILE=/custom/path/wallets.json
# or
animica wallet --wallet-file /custom/path/wallets.json list

⛏️ Mining

One command — mine + AI (recommended)

pip install --upgrade animica
animica up

animica up is the whole setup. It creates a wallet if you don't have one, then a single process joins pool.animica.org and the one global model, running — by capability — SHA3 proof-of-work, ENA useful-work, and (on a GPU) model training

OpenAI-compatible serving, plus Bittensor serving on qualified GPUs (≥16 GB VRAM). Every reward — PoW, useful-work, training, serving, Bittensor — pays out in ANM to your address. No flags, no separate daemons. Preview what will run with animica up --plan.

Which install?

pip install animica          # the complete client (what most people want)
pip install "animica[all]"   # everything above + every optional extra

pip install animica — the complete client. Everything to mine, run a node, use the wallet, deploy Python contracts, run animica up (the unified miner: PoW
- useful-work + GPU train/serve + Studio functions), and use the Studio SDK. The native CPU miner (animica-fastpow) is included by default. This is what most people want.
pip install "animica[all]" — everything above plus every optional extra: Qt desktop-wallet QR codes, the full distributed Studio client (cloudpickle for closures + omni-sdk for on-chain ANM escrow), and all server/operator dependencies pinned. Use it if you want the kitchen sink or are running pool/API infrastructure.

Quote the extras form as pip install "animica[all]" (with quotes) so zsh/macOS does not glob the brackets.

The pool enforces a minimum miner version (1.0.0) and rejects older miners, so keep animica upgraded. Full guide: https://pool.animica.org/mining-onboard.

The sections below are advanced/manual paths (animica up runs these for you).

GUI Miner (Recommended)

NEW: Production-quality Qt desktop GUI miner with first-run wizard, real-time dashboard, device auto-detection, and live stats.

# Install GUI miner dependencies
cd apps/miner-gui
pip install -e .

# Launch GUI miner
animica gui miner

# Or use the alias
animica-miner-gui

Features:

First-run wizard for easy setup (network, RPC, wallet, devices)
Real-time dashboard with hashrate, shares, and blocks
Auto-detect CPU/GPU devices with recommendations
Configuration editor with JSON schema validation
Live logs with filtering and search
Hashrate and shares graphs (matplotlib)
Dark theme and system tray support
Auto-start mining and crash recovery

See apps/miner-gui/README.md for detailed documentation.

Mine Blocks via CLI

# Mine 5 blocks to a wallet (by label)
animica miner mine-blocks --count 5 premine

# Mine to a bech32 address
animica miner mine-blocks --count 10 anim1abc123...

# Mine with verbose output (shows transaction details)
animica miner mine-blocks --count 5 --verbose premine

# Specify RPC URL
animica miner mine-blocks --count 5 --rpc-url http://localhost:8545 mywallet

Continuous Mining (Docker)

The miner service is included when using --with-miner:

animica node up --with-miner

Or start miner separately with Docker Compose:

docker compose -f tests/devnet/docker-compose.yml -p animica-devnet up -d miner

Mining Configuration

Environment variables:

export ANIMICA_MINER_ADDRESS=anim1...      # Default payout address
export ANIMICA_MINER_MAX_NONCE=100000      # Max nonce iterations
export ANIMICA_MINER_THREADS=4             # CPU mining threads

Stratum Mining Pool (Advanced)

# Generate pool payout address
animica miner generate-payout-address --label pool-operator

# Write a starter pool env file
animica pool init --path animica-pool.env

# Run a managed Stratum pool
animica pool up --daemon \
  --profile asic_sha256 \
  --rpc-url http://localhost:8545/rpc \
  --host 0.0.0.0 \
  --port 3333 \
  --api-host 127.0.0.1 \
  --api-port 8550

# Diagnose the node/pool/template path
animica pool doctor
animica pool test-job
animica pool list-workers

# Show status / stop
animica pool status
animica pool down

animica stratum ... remains available as a compatibility alias for the same managed pool commands.

💸 Transactions

Send a Transaction

# Send tokens (by wallet label)
animica tx send --from mywallet --to anim1recipient... --value 1.5

# Send with specific nonce
animica tx send --from mywallet --to anim1... --value 1.0 --nonce 5

# Send to a label (resolves address from wallet)
animica tx send --from sender --to recipient --value 0.5

Check Transaction Status

# Get transaction by hash
animica tx status <tx_hash>

# Get transaction receipt
animica tx receipt <tx_hash>

Transaction via RPC

# Using the CLI RPC command
animica rpc call state.getBalance '{"params": ["anim1..."]}'

# Get nonce
animica rpc call state.getNonce '{"params": ["anim1..."]}'

🔌 RPC Interaction

Using animica CLI

# Call RPC method (no params)
animica rpc call chain.getHead

# Call with parameters (JSON)
animica rpc call state.getBalance '{"params": ["anim1..."]}'

# Call with params (array)
animica rpc call chain.getBlockByNumber '{"params": [100, true]}'

Using curl

# Get chain head
curl -X POST http://127.0.0.1:8545/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"chain.getHead","params":[],"id":1}'

# Get balance
curl -X POST http://127.0.0.1:8545/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"state.getBalance","params":["anim1..."],"id":1}'

# Get block by height
curl -X POST http://127.0.0.1:8545/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"chain.getBlockByNumber","params":[100],"id":1}'

Available RPC Methods

See spec/openrpc.json for the complete RPC API specification, or visit the OpenAPI documentation when running a node:

http://127.0.0.1:8545/docs

🚰 Faucet (Devnet/Testnet Only)

Request test tokens for development and testing:

# Request tokens to a wallet label
animica faucet request mywallet

# Request tokens to a bech32 address
animica faucet request anim1abc123...

# Request specific amount (in nANM)
animica faucet request mywallet --amount 1000000000000000

Note: Faucet is only available on devnet and testnet. Mainnet requires acquiring ANM through exchanges or mining.

🎨 Studio Services (Optional)

Studio Services provide additional developer tools including contract deployment/verification API, artifact storage, and the Explorer web UI.

Start Studio Services

Studio Services are optional and separate from the node. Start the node first, then start Studio Services:

# Set network
animica network set devnet

# Start node
animica node up

# Start Studio Services (in separate terminal or after)
animica studio up

Or start both together by using docker-compose profiles directly (see Docker Compose section).

Studio Services Commands

# Start Studio Services
animica studio up
animica studio up --no-detach  # Foreground mode

# Check status
animica studio status

# View logs
animica studio logs
animica studio logs --follow

# Stop Studio Services
animica studio down
animica studio down --volumes  # Also delete storage

Studio Services Endpoints

When Studio Services is running:

API: http://127.0.0.1:8081
OpenAPI Docs: http://127.0.0.1:8081/docs
Explorer: http://127.0.0.1:5173 (if enabled)

Configure Studio Services

# Validate configuration
animica studio config

# Override configuration
animica studio up \
  --rpc-url http://localhost:8545 \
  --chain-id 1337 \
  --storage-dir ./studio-data

🐳 Docker Compose Manual Usage

For users who prefer direct Docker Compose commands:

Devnet

# Set network context
export ANIMICA_NETWORK=devnet

# Start node + miner (dev profile)
docker compose -f tests/devnet/docker-compose.yml -p animica-devnet \
  --profile dev up -d

# Start node + miner + Studio Services + Explorer (dev + studio profiles)
docker compose -f tests/devnet/docker-compose.yml -p animica-devnet \
  --profile dev --profile studio up -d

# Check running containers
docker compose -f tests/devnet/docker-compose.yml -p animica-devnet ps

# View logs
docker compose -f tests/devnet/docker-compose.yml -p animica-devnet logs -f node1
docker compose -f tests/devnet/docker-compose.yml -p animica-devnet logs -f miner

# Stop everything
docker compose -f tests/devnet/docker-compose.yml -p animica-devnet down

# Stop and remove volumes (deletes all data)
docker compose -f tests/devnet/docker-compose.yml -p animica-devnet down -v

Mainnet

# Start mainnet node
docker compose -f ops/docker/docker-compose.mainnet.yml up -d

# View logs
docker compose -f ops/docker/docker-compose.mainnet.yml logs -f node

# Stop
docker compose -f ops/docker/docker-compose.mainnet.yml down

Testnet

# Start testnet node
docker compose -f ops/docker/docker-compose.testnet.yml up -d

# View logs
docker compose -f ops/docker/docker-compose.testnet.yml logs -f node

# Stop
docker compose -f ops/docker/docker-compose.testnet.yml down

Custom Port Configuration

# Override ports via environment variables
HOST_RPC_PORT=9545 HOST_P2P_PORT=31337 HOST_METRICS_PORT=9090 \
  docker compose -f tests/devnet/docker-compose.yml -p animica-devnet up -d

🔧 Running Without Docker (Advanced)

For development or when Docker is not available:

Boot Node Directly

# Activate environment
source .venv/bin/activate

# Set network
export ANIMICA_NETWORK=devnet

# Boot the node
python -m core.boot \
  --genesis core/genesis/genesis.json \
  --db sqlite:///data/animica.db

Start RPC Server

# Start RPC server
python -m rpc.server \
  --db sqlite:///data/animica.db \
  --genesis core/genesis/genesis.json \
  --chain-id 1337 \
  --host 0.0.0.0 \
  --port 8545 \
  --cors "[*]" \
  --log-level INFO

Start Miner

# Start CPU miner
python -m mining.cli.miner start \
  --threads 4 \
  --device cpu \
  --rpc-url http://127.0.0.1:8545

🌍 Environment Variables Reference

Network & RPC

Variable	Description	Default	Example
`ANIMICA_NETWORK`	Active network profile	mainnet	`devnet`
`ANIMICA_RPC_URL`	Node RPC endpoint	Network-specific	`http://127.0.0.1:8545/rpc`
`ANIMICA_CHAIN_ID`	Override chain ID	Network-specific	`1337`
`ANIMICA_RPC_HOST`	RPC server bind host	`0.0.0.0`	`127.0.0.1`
`ANIMICA_RPC_PORT`	RPC server bind port	`8545`	`9545`
`ANIMICA_RPC_DB_URI`	Database URI for RPC	`sqlite:///animica.db`	`sqlite:////data/chain.db`
`ANIMICA_LOG_LEVEL`	Logging level	`INFO`	`DEBUG`
`ANIMICA_RPC_CORS_ORIGINS`	CORS allowed origins	`[*]`	`["http://localhost:3000"]`

Mining

Variable	Description	Default	Example
`ANIMICA_MINER_ADDRESS`	Default miner payout address	None	`anim1abc...`
`ANIMICA_MINER_MAX_NONCE`	Max nonce iterations per block	`100000`	`1000000`
`MINER_DEVICE`	Mining device	`cpu`	`cuda`, `opencl`
`MINER_THREADS`	CPU mining threads	Auto	`4`
`MINER_LOG_LEVEL`	Miner log level	`INFO`	`DEBUG`

P2P Networking

Bootstrap-only mode is disabled by default. Enable it explicitly with ANIMICA_BOOTSTRAP_NODE=true (or animica node up --bootstrap-node) and disable it with ANIMICA_BOOTSTRAP_NODE=false or by unsetting the variable. You can also override the bootstrap RPC endpoint via ANIMICA_BOOTSTRAP_RPC_URL.

Variable	Description	Default	Example
`ANIMICA_P2P_SEEDS`	Seed node addresses	Network-specific	`node1.example.com:30333`
`ANIMICA_P2P_LISTEN`	P2P listen address	`0.0.0.0:30333`	`0.0.0.0:31337`
`ANIMICA_BOOTSTRAP_NODE`	Enable bootstrap-only RPC mode	`false`	`true`
`ANIMICA_BOOTSTRAP_RPC_URL`	Override bootstrap RPC endpoint	Network-specific	`http://127.0.0.1:8545/rpc`
`ANIMICA_BOOTSTRAP_PASSWORD`	Bootstrap password (mainnet only)	None	`<secure-password>`

Wallet & Keys

Variable	Description	Default	Example
`ANIMICA_WALLETS_FILE`	Wallet store location	`~/.animica/wallets.json`	`/secure/wallets.json`
`ANIMICA_ALLOW_SECRET`	Allow secret key display	`0`	`1` (enable)
`ANIMICA_DEFAULT_ADDRESS`	Default wallet address	None	`anim1...`

Studio Services

Variable	Description	Default	Example
`RPC_URL`	Node RPC endpoint	Required	`http://127.0.0.1:8545`
`CHAIN_ID`	Chain ID	`1337`	`1`
`STORAGE_DIR`	Storage directory	`./.data`	`/var/studio-data`
`HOST`	Studio API bind host	`0.0.0.0`	`127.0.0.1`
`PORT`	Studio API bind port	`8081`	`8080`
`ALLOWED_ORIGINS`	CORS origins	None	`http://localhost:3000`
`FAUCET_KEY`	Faucet private key (dev only)	None	`<hex-encoded-key>`

Docker Compose

Variable	Description	Default	Example
`HOST_RPC_PORT`	Host RPC port mapping	Network-specific	`9545`
`HOST_P2P_PORT`	Host P2P port mapping	Network-specific	`31337`
`HOST_METRICS_PORT`	Host metrics port mapping	Network-specific	`9090`

Testing & Development

Variable	Description	Default	Example
`ANIMICA_TESTALL_NO_LINT`	Skip linting in testall.sh	`0`	`1`
`ANIMICA_TEST_SIG_ALG`	Force signature algorithm in tests	Auto	`dilithium3`
`ANIMICA_PQ_MODE`	Post-quantum mode	`enabled`	`disabled`
`ANIMICA_ALLOW_PQ_PURE_FALLBACK`	Allow pure Python PQ fallback	`0`	`1` (dev only)

✅ Testing

Run All Tests

# Activate environment
source .venv/bin/activate

# Run complete test suite (Python + Node + Rust)
./testall.sh

Python Tests

# All Python tests
pytest -q

# Specific modules
pytest consensus/tests/ -v
pytest execution/tests/ -v
pytest rpc/tests/ -v
pytest mempool/tests/ -v
pytest p2p/tests/ -v
pytest wallet/tests/ -v

# With coverage
pytest --cov=consensus consensus/tests/
pytest --cov=execution execution/tests/

Fast Smoke Tests

# Run only fast unit tests (skip slow integration tests)
pytest -m "not slow and not integration" -q

Specific Test

# Run specific test file
pytest tests/test_mining_manual.py -v

# Run specific test function
pytest tests/test_mining_manual.py::test_mining_flow -v

# Run with verbose output and stop on first failure
pytest tests/test_mining_manual.py::test_mining_flow -vv -x --tb=long

Test with Devnet

# Start devnet
animica network set devnet
animica node up

# Run integration tests against devnet
pytest tests/integration/ --rpc http://127.0.0.1:28545

# Stop devnet
animica node down

🔍 Troubleshooting

"Network not set" Error

Problem: Commands fail with "Error: No network configured"

Solution: Set a network first

animica network set devnet
# or
export ANIMICA_NETWORK=devnet
# or use --network flag
animica --network devnet node status

Port Already in Use

Problem: docker compose up fails with "port is already allocated"

Solution: Check for existing containers or use custom ports

# Check for existing containers
docker ps

# Stop existing containers
docker compose -f tests/devnet/docker-compose.yml -p animica-devnet down

# Or use custom ports
HOST_RPC_PORT=9545 animica node up

Node Not Syncing

Problem: Node doesn't sync or can't connect to peers

Solution:

# Check P2P connectivity
docker compose -f tests/devnet/docker-compose.yml -p animica-devnet logs node1 | grep p2p

# Verify seed nodes
echo $ANIMICA_P2P_SEEDS

# Check network configuration
animica network get

Wallet Not Found

Problem: animica wallet show returns "Wallet not found"

Solution:

# List all wallets
animica wallet list

# Verify wallet file exists
ls -la ~/.animica/wallets.json

# Check wallet file location
echo $ANIMICA_WALLETS_FILE

Transaction Pending Forever

Problem: Transaction stays pending and never confirms

Solution: Mine blocks to include the transaction

# Mine blocks to process pending transactions
animica miner mine-blocks --count 5 premine

# Check transaction status
animica tx status <tx_hash>

Genesis File Not Found

Problem: Node fails to start with "Genesis file not found"

Solution:

# Copy appropriate genesis file
bash genesis/devnet.sh

# Or specify path explicitly
python -m core.boot --genesis /path/to/genesis.json

DB Initialization Failed

Problem: Database initialization or corruption errors

Solution: Remove DB and reinitialize

# For devnet (chain ID 1337)
rm -rf ~/.local/share/animica/chain-1337/
animica node up

# Or use Docker volumes
animica node down --volumes
animica node up

Docker Compose Issues

Problem: Docker Compose fails or containers crash

Solution: Reset and rebuild

# Stop everything and remove volumes
docker compose -f tests/devnet/docker-compose.yml -p animica-devnet down -v

# Clean Docker system (careful!)
docker system prune -af

# Rebuild and start
animica node up --build

PQ Cryptography Issues

Problem: Wallet creation fails with PQ errors

Solution:

# Test PQ availability
python -c "from animica.pq import sig_keygen; print('PQ available')"

# For development only: use fallback
animica wallet create --label devwallet --allow-insecure-fallback

# Reinstall PQ package
pip install -e pq/ --force-reinstall

RPC Connection Refused

Problem: CLI commands fail with "connection refused"

Solution:

# Check if node is running
docker ps | grep animica

# Check node logs
docker compose -f tests/devnet/docker-compose.yml -p animica-devnet logs node1

# Verify RPC URL
echo $ANIMICA_RPC_URL

# Try connecting manually
curl http://127.0.0.1:8545/rpc

Test Collection Errors

Problem: pytest fails to collect tests

Solution:

# Some test modules require optional dependencies - these are automatically skipped
# Check which tests are being skipped
pytest --collect-only -q | grep SKIPPED

# Install missing dependencies
pip install -e ".[dev]"

# Reinstall all
./setup.sh --fresh

🤖 MCP / AI Agents

Animica ships a Model Context Protocol (MCP) server so AI agents (Claude, Cursor, and any MCP-capable client) can query the chain directly:

pip install animica-mcp     # standalone wrapper (uvx animica-mcp also works)
animica-mcp                 # stdio transport (default)

# or, with the main package installed:
animica mcp serve           # --transport streamable-http | sse also supported

15 read+compute tools: chain head/block/account lookups, AI ask/models, quantum beacon + verify, pool stats, network hashrate, Studio estimate/functions, and animica_info. No private keys — read-only chain access by design.
MCP registry name: org.animica/animica.
Agent-readable site index: https://animica.org/llms.txt — plus the in-repo agent guide AGENTS.md.
Keyless inference for agents: https://animica.dev/v1 is OpenAI-compatible with no API key (30 req/min/IP). Check each model's boolean serving flag in /v1/models; requests to non-serving models may 503 or queue.

📚 Documentation Links

Quickstart Guide: QUICKSTART.md - Fast setup and basic operations
Architecture Overview: docs/ARCHITECTURE.md - System design and data flow
Contract Development: docs/dev/CONTRACTS_START.md - Write Python-VM smart contracts
RPC API Reference: spec/openrpc.json - Complete JSON-RPC API specification
ABI Schemas: spec/abi.schema.json - Contract ABI format
Governance: governance/GOVERNANCE.md - Protocol upgrade process
Security: SECURITY.md - Security policies and reporting
Wallet Guide: wallet/README.md - Flutter wallet documentation
Explorer: explorer-web/README.md - Block explorer setup
Module READMEs: Each <module>/README.md - Component-specific documentation

Specifications

PoIES Consensus: spec/poies_math.md - Consensus algorithm details
Gas & VM: vm_py/specs/GAS.md, vm_py/specs/DETERMINISM.md - Execution model
Receipts: execution/specs/RECEIPTS.md - Transaction receipt format
AICF: aicf/README.md - AI Capability Framework lifecycle

🤝 Contributing

We welcome contributions! Please follow these guidelines:

Keep changes scoped: Focus on a single area or feature per PR
Follow existing patterns: Review similar code and maintain consistency
Write tests: Add unit tests for new features and bug fixes
Update documentation: Keep README and module docs in sync with code changes
Run tests locally: Ensure ./testall.sh passes before submitting
Use clear commit messages: Explain what and why, not just how

Code Style

Python: Follow PEP 8, use ruff for linting
TypeScript: Follow project ESLint configuration
Rust: Use rustfmt and clippy

Pull Request Process

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Make your changes and commit: git commit -m "feat: add feature X"
Push to your fork: git push origin feature/my-feature
Open a Pull Request with a clear description
Respond to review feedback
Squash and merge once approved

See CONTRIBUTING.md for detailed guidelines.

💬 Support

Getting Help

Documentation: Check module-specific READMEs and docs/ folder
Examples: Review test files for usage patterns
Issues: Search existing issues or create a new one
Discussions: Use GitHub Discussions for questions

Reporting Issues

When filing an issue, include:

Purpose: What you're trying to accomplish
Environment: OS, Python version, Docker version
Steps to reproduce: Minimal commands to reproduce the issue
Expected vs. actual behavior: What should happen vs. what happens
Logs: Relevant error messages and stack traces

Security Issues

DO NOT open public issues for security vulnerabilities. Instead:

Email security@animica.org (if available)
Or file a private security advisory on GitHub
See SECURITY.md for our security policy

For security-sensitive topics (keys, proofs, VKs, installer signing), request a security review before merging.

⚡ Animica 10.0.0 L2

Animica 10.0.0 adds an ANM-native Layer 2 payment rollup in the top-level l2/ package: post-quantum (ML-DSA-65) transactions, deterministic parallel execution, authenticated state (SMT), reconstructable DA blobs, a pluggable proof system (validity-by-re-execution today, a ZK backend slot for later), and an L1 bridge with a strict conservation invariant plus forced exits. Enable it with ANIMICA_L2_ENABLE=1; the l2_* JSON-RPC methods and the animica l2 CLI ride the existing node.

Documentation lives in docs/l2/:

Architecture — components, pipeline, L1↔L2 relationship
Security assumptions — the honest trust model (designated sequencer; what bounds it)
Transaction lifecycle — the nine states; soft vs proven vs L1-finalized
Running a node — all ANIMICA_L2_* config, modes, ports, CLI
Data availability · Fees · Forced exits
Performance — benchmark methodology and report template (animica l2 bench)

Name		Name	Last commit message	Last commit date
.build		.build
.deps_system_liboqs_backup_20251213T042853Z/usr/local/lib		.deps_system_liboqs_backup_20251213T042853Z/usr/local/lib
.devcontainer		.devcontainer
.github		.github
.pnpm-store/v3/files		.pnpm-store/v3/files
.studio-services/storage/blobs/sha3-256/7b/fb		.studio-services/storage/blobs/sha3-256/7b/fb
.zencoder/chats		.zencoder/chats
.zenflow/tasks		.zenflow/tasks
AnimicaWallet.app/Contents		AnimicaWallet.app/Contents
Testing/Temporary		Testing/Temporary
academy		academy
ai		ai
aicf		aicf
animica-mcp-py		animica-mcp-py
animica-mcp		animica-mcp
animica-net		animica-net
animica-pool		animica-pool
animica-studio-qt		animica-studio-qt
animica.egg-info		animica.egg-info
apps		apps
artifacts		artifacts
billing		billing
buy.animica.org/src/server		buy.animica.org/src/server
capabilities		capabilities
cex		cex
chains		chains
clients		clients
consensus		consensus
contracts		contracts
contrib		contrib
core		core
coretx		coretx
crates/animica-native/tests		crates/animica-native/tests
da		da
docs		docs
evm/banm-bridge		evm/banm-bridge
examples/agents		examples/agents
execution		execution
explorer-web		explorer-web
explorer2		explorer2
extras		extras
genesis		genesis
governance		governance
infra		infra
installers		installers
l2		l2
logs		logs
mainnet		mainnet
mempool		mempool
mempool2		mempool2
mining		mining
native		native
node-pkg		node-pkg
ops		ops
p2p		p2p
packages		packages
pool-web		pool-web
pool.animica.org-app		pool.animica.org-app
pq		pq
proofs		proofs
provider-daemon		provider-daemon
python		python
queue		queue
randomness		randomness
relayer		relayer
rpc		rpc
schemas		schemas
scripts		scripts
sdk		sdk
services		services
sites		sites
spec		spec
stdlib		stdlib
studio-host		studio-host
studio-ide		studio-ide
studio-services		studio-services
studio-wasm		studio-wasm
studio-web		studio-web
studio		studio
templates		templates
tests		tests
tools		tools
vendor/dotenv		vendor/dotenv
vm_py		vm_py
wallet-extension		wallet-extension
wallet-qt		wallet-qt
wallet		wallet
web		web
website		website
zk		zk
-		-
.DS_Store		.DS_Store
.codex		.codex
.coverage		.coverage
.dockerignore		.dockerignore
.env.aicf.example		.env.aicf.example
.env.compute.example		.env.compute.example
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore

Latest commit

History

Folders and files

Repository files navigation

Animica L1 Blockchain

🌟 Key Features

📁 Repository Structure

🚀 Animica Compute + LLM Cloud Platform

🌍 Website

🌐 Decentralized Architecture

🌐 Live Endpoints (Mainnet)

📋 Prerequisites

Required Software

Build Tools (Optional, for Rust Components)

Operating System Notes

🚀 Installation & Setup

🚴‍♂️ CLI Quickstart (Everything End-to-End)

💰 Animica Wallet Desktop App

Downloads

Features

Building from Source

1. Clone the Repository

2. Run Setup Script

Setup Options

Custom Package Index

3. Activate Virtual Environment

4. Verify Installation

🌐 Network Configuration

Set Active Network

Check Current Network

List Available Networks

Data Directory Isolation

Environment Variables

🌐 Decentralized P2P Network

P2P Features

Quick P2P Test

P2P Configuration

Documentation

🖥️ Node Operations

Starting a Node

Start Node with Docker Compose

Network-Specific Ports

Custom Port Configuration

Stopping a Node

Check Node Status

View Node Logs

💼 Wallet Management

Create a Wallet

List Wallets

Show Wallet Details

Import a Wallet

Export a Wallet

Set Default Wallet

Wallet File Location

⛏️ Mining

One command — mine + AI (recommended)

Which install?

GUI Miner (Recommended)

Mine Blocks via CLI

Continuous Mining (Docker)

Mining Configuration

Stratum Mining Pool (Advanced)

💸 Transactions

Send a Transaction

Check Transaction Status

Transaction via RPC

🔌 RPC Interaction

Using animica CLI

Using curl

Available RPC Methods

🚰 Faucet (Devnet/Testnet Only)

🎨 Studio Services (Optional)

Start Studio Services

Studio Services Commands

Studio Services Endpoints

Configure Studio Services

🐳 Docker Compose Manual Usage

Devnet

Mainnet

Testnet