Content
# Animica L1 Blockchain
> **Canonical repo:** `main` of [animicaorg/all](https://github.com/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](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**:
```bash
make compute-dev # Start all compute services with Docker Compose
```
See [COMPUTE_PLATFORM_QUICKSTART.md](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](docs/P2P_NETWORKING_GUIDE.md) 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:
```bash
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:
```bash
sudo apt-get update
sudo apt-get install -y build-essential pkg-config libssl-dev
```
On macOS (via Homebrew):
```bash
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**
```bash
./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):
```bash
animica network set devnet # mainnet | testnet | devnet | local-devnet
animica network get # confirm selection
```
3) **Start your node from the CLI** (Docker Compose wrapper):
```bash
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**:
```bash
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:
```bash
# 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](SNAPSHOT_VERIFICATION_GUIDE.md) for complete guide and troubleshooting.
5) **Ensure peers connect** (connectivity checklist):
```bash
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:
```bash
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):
```bash
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):
```bash
animica tx send --from mywallet --to anim1recipient... --value 1.0
animica tx status <tx_hash>
```
8) **Stop services** when done:
```bash
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`](wallet-qt/README.md) for build instructions and [`wallet-qt/docs/RELEASING.md`](wallet-qt/docs/RELEASING.md) for packaging releases.
### 1. Clone the Repository
```bash
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:
```bash
# 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:
```bash
PIP_EXTRA_INDEX_URL=https://your-index.example.com/simple ./setup.sh
```
### 3. Activate Virtual Environment
After setup completes:
```bash
source .venv/bin/activate
```
### 4. Verify Installation
```bash
# 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:
```bash
./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:
```bash
# 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
```bash
animica network get
```
### List Available Networks
```bash
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:
```bash
# 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
```bash
# 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](docs/P2P_NETWORKING_GUIDE.md)** - Complete P2P architecture and troubleshooting
- **[Multi-Node Docker Setup](docs/MULTI_NODE_DOCKER_SETUP.md)** - Test multi-node networks locally
## 🖥️ Node Operations
### Starting a Node
**Before starting a node, set the network:**
```bash
animica network set devnet
```
#### Start Node with Docker Compose
```bash
# 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:
```bash
HOST_RPC_PORT=9545 HOST_P2P_PORT=31337 animica node up
```
### Stopping a Node
```bash
# Stop node (preserve data)
animica node down
# Stop and delete all data (WARNING: irreversible!)
animica node down --volumes
```
### Check Node Status
```bash
# 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:
```bash
# 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
```bash
# 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
```bash
animica wallet list
```
Output example:
```
Idx Default Label Address Alg
--- ------- ---------------- ----------------------------------- ----------------
0 * premine anim1zqqjt3258rgnfckqxv686unmg... dilithium3
1 mywallet anim1abc123... dilithium3
```
### Show Wallet Details
```bash
# 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:
```bash
export ANIMICA_ALLOW_SECRET=1
animica wallet show mywallet --show-secret --i-know-what-im-doing
```
### Import a Wallet
```bash
# 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
```bash
# 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
```bash
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:
```bash
export ANIMICA_WALLETS_FILE=/custom/path/wallets.json
# or
animica wallet --wallet-file /custom/path/wallets.json list
```
## ⛏️ Mining
### One command — mine + AI (recommended)
```bash
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?
```bash
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.
```bash
# 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](apps/miner-gui/README.md) for detailed documentation.
### Mine Blocks via CLI
```bash
# 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`:
```bash
animica node up --with-miner
```
Or start miner separately with Docker Compose:
```bash
docker compose -f tests/devnet/docker-compose.yml -p animica-devnet up -d miner
```
### Mining Configuration
Environment variables:
```bash
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)
```bash
# 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
```bash
# 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
```bash
# Get transaction by hash
animica tx status <tx_hash>
# Get transaction receipt
animica tx receipt <tx_hash>
```
### Transaction via RPC
```bash
# 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
```bash
# 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
```bash
# 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:
```bash
# 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:
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Activate environment
source .venv/bin/activate
# Run complete test suite (Python + Node + Rust)
./testall.sh
```
### Python Tests
```bash
# 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
```bash
# Run only fast unit tests (skip slow integration tests)
pytest -m "not slow and not integration" -q
```
### Specific Test
```bash
# 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
```bash
# 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
```bash
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
```bash
# 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**:
```bash
# 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**:
```bash
# 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
```bash
# 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**:
```bash
# 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
```bash
# 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
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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:
```bash
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`](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`](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.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`](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`](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/`](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/`](docs/l2/):
- [Architecture](docs/l2/ARCHITECTURE.md) — components, pipeline, L1↔L2 relationship
- [Security assumptions](docs/l2/SECURITY_ASSUMPTIONS.md) — the honest trust model (designated sequencer; what bounds it)
- [Transaction lifecycle](docs/l2/TRANSACTION_LIFECYCLE.md) — the nine states; soft vs proven vs L1-finalized
- [Running a node](docs/l2/RUNNING.md) — all `ANIMICA_L2_*` config, modes, ports, CLI
- [Data availability](docs/l2/DATA_AVAILABILITY.md) · [Fees](docs/l2/FEES.md) · [Forced exits](docs/l2/FORCED_EXITS.md)
- [Performance](docs/l2/PERFORMANCE.md) — benchmark methodology and report template (`animica l2 bench`)
Connection Info
You Might Also Like
No recommendations available