Documentation

Animica reference documentation: consensus (PoIES), transaction signing, the Python VM and its tutorials, the L2 rollup, AICF compute, wallets, mining, and the Ethereum/Bitcoin RPC compatibility layers.

/

Animica is an open-source proof-of-work Layer-1 (chain id 1) with ML-DSA-65 post-quantum signatures, bech32m anim1… addresses, deterministic Python-VM contracts, PoIES consensus, an ANM-native Layer-2 rollup and an off-chain AI-compute layer (AICF). This section collects 51 reference pages (70k words) mirrored from the repository documentation , plus four hand-written guides. Each mirrored page links to its source file; when they disagree, the repository wins. If you are new, the Learn section explains the same material from the ground up.

Install

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. Public RPC: POST https://rpc.animica.org/rpc (the /rpc path is required).

Guides

Hand-written pages for the most common integrations.

Mining & animica up

The unified miner: PoW + useful-work + GPU train/serve + Studio functions. Native CPU miner included by default.

mininganimica upfastpowcpu

Ethereum / EVM RPC

Connect ethers.js, web3.js & MetaMask. eth_*/net_*/web3_* facade on chain id 149, address bridge, honest boundaries.

evmethereummetamaskethers

Bitcoin Core RPC

Point bitcoin-cli, BTCPay & Bitcoin RPC tooling at a node. Bitcoin Core 30.x method names and shapes over Animica.

bitcoinbitcoin-clibtcpayrpc

Studio SDK

Serverless compute SDK: @app.function, .remote()/.map(), images, secrets, volumes, GPUs — settled in ANM.

studioserverlesssdkmodal

Getting started

The current state of the network, the CLI, the transaction workflow, and what to do when something does not work.

Animica — Current State (2026) and How to Learn It

The authoritative 2026 overview: ML-DSA-65 as the only accepted signature scheme, the height-gated consensus forks, the free AI layer at animica.dev, and how mining and AI serving fit together. When older documents disagree with this page, this page is correct.

CLI command guide

Reference for the command-line tools shipped in the repository: network profiles, the node, wallet, pool and miner CLIs, with their key flags and example invocations.

Transaction Workflow Guide

Step by step on a local devnet: create a wallet, submit a signed transaction over RPC, watch it in the mempool, see it included in a block, and verify balances.

Troubleshooting Guide

Solutions to common node, RPC, wallet, ENA and AICF problems, starting with the doctor commands that diagnose misconfigurations and suggest exact fixes.

Protocol

Consensus and difficulty, canonical transaction signing, the HD wallet derivation standard, and the peer-to-peer layer.

PoIES Overview — Proof-of-Integrated-External-Services

How Proof-of-Integrated-External-Services scores hash work and verified useful-work proofs against the threshold Θ, and the caps and policy that bound each proof type.

Difficulty Adjustment Mechanism

How the Θ (theta) difficulty threshold retargets to hold the target block interval, how retargeting is wired into block import, and how to monitor and configure it.

Transaction signing canonical specification

The canonical signing pipeline: the unsigned canonical-CBOR body, the domain-separated animica.tx.v1 preimage, the SHA3-512 sign-hash, and how nodes verify the signature envelope.

Animica HD wallet derivation (BIP-39 / BIP-44 / SLIP-0010 → ML-DSA-65)

The normative HD wallet standard for third-party wallets: BIP-39 mnemonic, SLIP-0010 hardened derivation along m/44'/4279885'/…, the 32-byte ML-DSA-65 seed, and a test vector.

Animica P2P Networking Guide

How nodes discover peers, complete the post-quantum handshake, gossip blocks and transactions, and sync, with seed lists, ports and configuration for mainnet and development networks.

Smart contracts (Python VM)

The deterministic Python VM: architecture, gas, the sandbox, host capabilities, the ABI, the compiler, patterns, examples, and debugging.

VM(Py) Overview — Deterministic Python Subset & Runtime Architecture

Architecture of the deterministic Python VM: the safe Python subset, compilation to IR, the gas-metered interpreter, and how contracts interact with state and host capabilities.

VM(Py) Gas Model — Metering, Memory/IO, Op Caps

How execution is metered: opcode costs from the gas table, memory and I/O charges, per-operation caps, and what contract authors should budget for.

VM(Py) Sandbox — Forbidding Nondeterminism & Allowed Libraries

What the VM forbids to guarantee determinism (I/O, clocks, floats, ambient randomness) and which stdlib modules contracts may import.

VM(Py) Contract Capabilities — Syscalls (AI / Quantum / DA / Random / ZK)

The host syscalls contracts can call for AI jobs, quantum randomness, data availability and the randomness beacon, with their determinism and gas rules.

VM(Py) ABI — Call/Data Encoding & Event Topics

The canonical byte encoding for function calls, return values and event topics, so SDKs and nodes agree on every contract interaction.

VM(Py) Compiler — AST → IR → Bytecode, Static Gas Estimation

How contract source becomes bytecode: validation, AST-to-IR lowering, type checks, encoding, and static gas estimation.

Contract Patterns (VM(Py))

Recommended contract patterns for upgrades, proxy pinning, access control and pausability in the deterministic Python VM.

VM(Py) Contract Examples

Annotated example contracts (Counter, Escrow, Token, AI Agent, Quantum RNG) written in the deterministic Python subset with the provided stdlib.

Debugging Contracts on VM(Py)

Strategies for tracing contract execution: structured logs, receipts, gas reports, and how to reproduce a failing call locally.

Tutorials

End-to-end walkthroughs: deploy a counter, write a token and an escrow, build an indexer, use AI, DA and randomness syscalls, run a GPU provider.

Hello, Counter — Deploy & Call Your First Contract

Deploy the Counter contract on a local devnet and call inc() and get() from the Python and TypeScript SDKs.

Animica-20 (A20) — Fungible Token with Permits

Implement a minimal Animica-20 (A20) fungible token on the Python VM, with ERC-20-style transfers and signed permits.

Escrow — Disputes & Events

Build an escrow contract with disputes and events, then exercise the full deposit, release and dispute flow from the SDK.

Indexer Lite — Ingest Blocks and Plot Γ (Gamma) Utilization

Build a small indexer in one Python process with SQLite that ingests blocks over RPC and plots Γ (gamma) utilization on a static Chart.js page.

AI Agent — Enqueue AI Job & Consume Results

Have a contract enqueue an AI job through the AICF syscall and deterministically consume the result in the next block.

DA Oracle — Post a Blob, then Verify It On-Chain

Post a blob to the data-availability layer, obtain its NMT commitment, and verify inclusion on-chain from a contract.

Quantum RNG — Consume the Beacon mixed with QRNG

Consume the chain randomness beacon (commit-reveal and VDF, optionally mixed with QRNG) from a contract safely.

AICF Provider — Stand Up a GPU Worker

Stand up a GPU-backed AICF provider that accepts AI jobs, runs them on NVIDIA hardware, and returns verifiable output digests.

Layer 2 rollup

The ANM-native Layer 2 payment rollup shipped in 10.0.0: architecture, lifecycle, fees, data availability, forced exits, security assumptions, and operations.

Animica L2 — Architecture

The ANM-native Layer 2 payment rollup added in 10.0.0: the components of the l2/ package, sequencing, SMT state, parallel execution, validity by re-execution, and the L1 bridge.

Animica L2 — Transaction Lifecycle

The explicit state machine every L2 transaction moves through, from submission to L1 settlement, and what each status does and does not guarantee about finality.

Animica L2 — Fees

The deterministic, integer-nanos L2 fee schedule in l2/fees.py and why its constants are consensus-relevant.

Animica L2 — Data Availability

The DA blob the L2 publishes for every batch so that any independent node can rebuild the ledger from published data alone.

Animica L2 — Forced Inclusion & Forced Exits

Forced inclusion and forced exits through the L1 bridge: the mechanism that bounds what a censoring or dead sequencer can do.

Animica L2 — Security Assumptions (10.0.0)

What the 10.0.0 L2 protects, what it assumes, and what remains trusted, written to under-claim rather than over-claim.

Animica L2 — Performance Report Template

The report template and benchmark harness (animica l2 bench) for L2 throughput claims, with the rule that the real TPS is the slowest pipeline stage.

Animica L2 — Running a Node

Running an L2 node: every ANIMICA_L2_* configuration variable, its default, and the operational checks to run.

AICF and compute

The AI Compute Fund: how jobs are funded, requested, executed, verified and paid, plus provider onboarding, SLAs, and the platform threat model.

AICF (AI Compute Fund) - User Guide

How the AI Compute Fund pool is funded from block rewards and fees, how miners earn and claim credits, and the CLI and RPC calls involved.

AI Compute Fund (AICF) — Overview

How AICF coordinates off-chain AI and quantum compute with on-chain accounting: jobs, providers, verification and payouts.

AICF Job API — Schemas, Statuses, Receipts & Proofs

Contract-facing and operator-facing job schemas, status transitions, receipts and proof formats for the AICF job pipeline.

AICF Client Guide — How Contracts & Users Request Compute

How contracts and end users request AI or quantum compute: the call flow, budgets, result retrieval, SDK usage and common errors.

AICF Provider Registry — Onboarding, Staking, Deregistration

Provider identity, attestation, staking and lifecycle: how AI and quantum providers onboard, stay registered, and deregister.

AICF SLA — Latency, Quality, Redundancy, Penalty Schedule

Measured latency, quality and redundancy metrics for providers, how they are evaluated, and the penalty schedule.

AICF Security — TEE Attestations, Trap Calibration, Audits

Security guarantees and controls for AICF: TEE attestations for runners, trap-job calibration, and audit procedures.

Animica Compute Platform - Security Threat Model

Threat model for the Animica compute and LLM cloud platform: trust boundaries and the threats across authentication, billing, inference, the code sandbox and GitHub integration, with mitigations.

Wallets

Recovery, day-to-day security, hardware-backed keys, and the address book for the extension, mobile and desktop wallets.

Wallet Recovery — Social Recovery & Splitting Secrets

Human-friendly wallet recovery: social recovery for account access and secret splitting for seed custody, and how to combine them.

Wallet Security — Phishing, Blind Signing, and Safe Simulation

Practical defenses for the extension and Flutter wallets: phishing resistance, avoiding blind signing, and safe transaction simulation.

Hardware Security Keys & Devices — Ledger/Trezor/FIDO/WebAuthn

Hardware-backed key flows for Animica accounts and sessions: what Ledger, Trezor, FIDO and WebAuthn can and cannot do for post-quantum signing today.

Wallet Address Book — Watch-Only & Light-Client Flows

The wallet address book: watch-only accounts, light-client verification, and integrity checks that do not require a full node.

Mining

Running the miner from source against a local node and fixing the most common mining problems.

Mine Animica locally (devnet or pool)

A full local mining setup from source: start a devnet with RPC and WebSocket, run the built-in CPU or GPU miner, and expose a Stratum pool for external miners.

Mining Troubleshooting Guide

Common mining problems and fixes: RPC parameter errors, device selection, rewards not appearing, Θ adjustment, connectivity, and performance.

Compatibility and payments

Repository references for the Ethereum and Bitcoin RPC compatibility modes and the complete x402 agent-payments reference.