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":{}}'

💸 x402 Paid Agent APIs

Pay-per-request APIs for autonomous agents — USDC on Base mainnet (eip155:8453) over the open x402 protocol (Apache-2.0), settled by Animica's own self-hosted facilitator. No account, no signup, no API key: an unpaid request returns HTTP 402 with the exact terms, the client signs a USDC authorization locally, and the retry is served. The free APIs above stay free — x402 sells bulk, batching, indexes the free APIs do not have, and per-request verifiable randomness.

Discovery: https://animica.dev/.well-known/x402 (machine-readable catalog, generated from the gateway's product registry) · https://animica.dev/x402 (overview page; returns the same JSON to non-browser clients) · https://animica.dev/x402/openapi.json

Product	Endpoint	Price
Verifiable randomness (+ derived int/shuffle/pick/bulk/commit-reveal, $0.01–$0.05)	GET /x402/qrng/draw	$0.01
Bulk L1 chain data — range exports, account history, batch balances	GET /x402/chain/export	$0.05
Priority AI inference — capacity-gated, currently unavailable	POST /x402/v1/chat/completions	$0.10

Randomness is the lead product: verifiable quantum randomness for $0.01 per request, where verifiable means recomputable and signed, not hardware-attested. The serving node runs its software CSPRNG fallback today, so every draw reports source.is_quantum: false and attestation.attested: false — no hardware QRNG is connected and hardware attestation is not live. Those fields are published free in the catalog before you pay and ride verbatim on every paid response. What you can check on each draw: attestation.digest_hex == sha3_256(bytes(randomness)) and ed25519_verify(public_key_hex, raw_bytes(digest_hex), signature_hex); the derived products recompute from the same bytes by a published rule.

Priority inference exists but is gated on live serving capacity: while capacity is below the floor the catalog reports available: false and the endpoint answers 503 without requesting payment. Animica never takes money for a service it knows is unavailable.

Implementation: apps/x402-gateway/ · docs: docs/x402.md · directory/submission facts: docs/exposure/x402/dossier.md · health check: node scripts/check-x402-discovery.mjs

📋 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)

1. Install dependencies & create the venv

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

2. 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

3. 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

4. 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.

5. 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

6. 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

7. Send a transaction (with the running node):

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

8. 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

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes and commit: git commit -m "feat: add feature X"
4. Push to your fork: git push origin feature/my-feature
5. Open a Pull Request with a clear description
6. Respond to review feedback
7. 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)