# animica

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/animicaorg/all  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/animica

## Description
OpenAI-compatible AI inference, code, embeddings & agent tools for bots — and mine ANM.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "animica": {
    "command": "npx",
    "args": ["-y","animica"]
  }
}
```

## Documentation & README

# Animica L1 Blockchain

**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**: Dilithium3 (ML-DSA-65) and SPHINCS+ signatures for quantum-resistant security
- **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 like `127.0.0.1` provide public discovery/sync helpers; 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.

## 📋 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 `127.0.0.1` is provided only for bootstrapping; wallets, miners, and explorers should use 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
```

## 📚 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.