=============== LIBRARY RULES =============== From library maintainers: - Addresses are bech32m with prefix anim1; there is no 0x address format on L1 - All amounts are integer base units: 1 ANM = 10^9 base units (nano-ANM); never send floats - Sign only with ML-DSA-65 (FIPS 204, scheme id 0x1003) — the sole current signature scheme; SPHINCS+ is legacy, do not build on it - The JSON-RPC endpoint is POST https://rpc.animica.org/rpc — always include the /rpc path; the bare domain 301-redirects and breaks naive POST clients - AI-compute RPC methods are under the aicf.* namespace (L2 uses flat l2_* methods); there is no ai.* namespace and no chain.getHeight — use chain.getHead - Free keyless OpenAI-compatible inference lives at https://animica.dev/v1 (30 req/min/IP); check each model's serving flag in /v1/models before relying on it - Chain id is 1 (mainnet); faucet.request works on devnet/testnet only — there is no mainnet faucet ### Run Setup Script Source: https://github.com/animicaorg/all/blob/main/README.md Executes the setup script to install dependencies and configure the environment, with options for fresh installations. ```bash # Standard installation ./setup.sh # Fresh installation (removes existing .venv) ./setup.sh --fresh # Using environment variable FRESH=1 ./setup.sh ``` -------------------------------- ### Install and Start Mainnet Genesis Source: https://github.com/animicaorg/all/blob/main/docs/mainnet_genesis_checklist.md Commands to initialize the mainnet environment and launch the node. ```bash bash genesis/use.sh mainnet ``` ```bash ops/run.sh --profile mainnet node ``` -------------------------------- ### Initial Setup and Verification Source: https://github.com/animicaorg/all/blob/main/docs/ai.md Commands to install the package, verify system requirements, configure the environment, and perform a test chat. ```bash pip install animica # base install stays light animica ai doctor # 14 checks: python/cpu/ram/gpu/cuda/torch/extras/ # ollama/network/node-rpc/wallet/pool/studio/bittensor animica ai setup # pick mode + default model (auto-detects Ollama) animica ai chat "hello" # one-shot, or `animica ai chat` for a REPL ``` -------------------------------- ### Initialize dependencies Source: https://github.com/animicaorg/all/blob/main/docs/devnet_quickstart.md Run the setup script to install Node and Python dependencies and prepare the environment file. ```bash ./setup.sh ``` -------------------------------- ### Clone and Setup Repository Source: https://github.com/animicaorg/all/blob/main/docs/tutorials/HELLO_COUNTER.md Commands to clone the repository and install necessary dependencies for development. ```bash git clone https://example.com/animica/animica.git cd animica (Optional) create a virtualenv: python -m venv .venv && source .venv/bin/activate Install local packages you’ll use in this tutorial: # Python SDK + VM (compiler/runtime) + RPC server deps pip install -e sdk/python -e vm_py -e rpc -e core -e mining Or, if you prefer TypeScript SDK too: pnpm i --filter @animica/sdk --workspace-root # or: npm i --workspace=sdk/typescript ``` -------------------------------- ### Install and Run Provider Daemon Source: https://github.com/animicaorg/all/blob/main/docs/aicf-cloud/provider-daemon-install.md Navigate to the daemon directory, configure the environment file, and start the service. ```bash cd provider-daemon cp .env.example .env # fill AICF_PROVIDER_ID, AICF_PROVIDER_TOKEN, AICF_NODE_ID pnpm --filter @animica/aicf-provider-daemon dev ``` -------------------------------- ### View Setup Options Source: https://github.com/animicaorg/all/blob/main/README.md Displays help information for the setup script. ```text 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) ``` -------------------------------- ### Quick start and stream commands Source: https://github.com/animicaorg/all/blob/main/docs/ANIMAL_LIVESTREAM.md Commands to install the package, perform a local preview render, and initiate a live YouTube broadcast. ```bash pip install -U animica # Render a local preview first — no account needed: animica animal stream --preview out.mp4 --seconds 20 # Go live (after connecting YouTube in the console, see §3): animica animal stream --youtube --record-dir ./vods ``` ```bash animica animal stream --help ``` -------------------------------- ### Initialize Unified Mining Source: https://github.com/animicaorg/all/blob/main/README.md The recommended setup command to install or upgrade the client and start the unified mining process. ```bash pip install --upgrade animica animica up ``` -------------------------------- ### Setup pre-commit hooks Source: https://github.com/animicaorg/all/blob/main/docs/dev/BUILD_FROM_SOURCE.md Install and initialize pre-commit hooks for development quality-of-life. ```bash python -m pip install pre-commit pre-commit install ``` -------------------------------- ### Setup Development Environment Source: https://github.com/animicaorg/all/blob/main/docs/dev/QUICKSTART.md Commands to create a virtual environment, install dependencies, and configure the Python path. ```bash python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install --upgrade pip wheel # RPC server deps (FastAPI, Uvicorn, Prometheus client) pip install -r requirements.txt # All modules live side-by-side; add repo root to PYTHONPATH for -m usage: export PYTHONPATH="$PWD" ``` -------------------------------- ### Manual Devnet Setup and Execution Source: https://github.com/animicaorg/all/blob/main/docs/useful-work-demo.md Initializes a local devnet node, deploys quantum contracts, starts a worker, and submits a job. Requires the aicf and vm_py packages to be installed. ```bash # 1) Start devnet node python -m aicf.node --network devnet --rpc-addr 127.0.0.1 --rpc-port 18545 & RPC_PID=$! sleep 2 # 2) Deploy QuantumJobs and QuantumWorkers contracts # (Assuming contracts are compiled) python -m vm_py.cli.deploy \ --manifest contracts/examples/quantum/quantum_jobs_manifest.json \ --rpc http://127.0.0.1:18545 python -m vm_py.cli.deploy \ --manifest contracts/examples/quantum/quantum_workers_manifest.json \ --rpc http://127.0.0.1:18545 # 3) Start quantum worker export AICF_URL=http://127.0.0.1:18545 python -m mining.quantum_worker & WORKER_PID=$! # 4) Submit a job via contract python -m vm_py.cli.call \ --contract QuantumJobs \ --method submit_job \ --args '{"job_id": "0x01", "job_spec": "0x...", "fee_escrow": 1000}' \ --rpc http://127.0.0.1:18545 # 5) Mine a block (worker will complete job) curl -X POST http://127.0.0.1:18545/ -H 'content-type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"animica_generate","params":[1]}' # 6) Check block was accepted with quantum contribution curl -X POST http://127.0.0.1:18545/ -H 'content-type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"eth_getBlockByNumber","params":["latest",true]}' # Cleanup kill $RPC_PID $WORKER_PID ``` -------------------------------- ### Deploy Counter Contract Source: https://github.com/animicaorg/all/blob/main/docs/dev/QUICKSTART.md Steps to install the Python SDK and deploy the example contract. ```bash # Install Python SDK in editable mode pip install -e sdk/python # (Optional) ensure deps for msgspec, httpx, websockets are present pip install msgspec httpx websockets # Run the example against your local RPC (chainId=1337 devnet) python sdk/python/examples/deploy_counter.py \ --rpc http://127.0.0.1:8545 \ --chain-id 1337 ``` -------------------------------- ### Configure Devnet Environment Source: https://github.com/animicaorg/all/blob/main/docs/devnet-node1-container-exits.md Copy the example environment file to the required location before starting the stack. ```bash cd /root/animica cp tests/devnet/env.devnet.example tests/devnet/.env # optional edits: ports, faucet key, miner threads ``` -------------------------------- ### Install Blake3 Source: https://github.com/animicaorg/all/blob/main/docs/dev/BUILD_FROM_SOURCE.md Install the Blake3 hash acceleration library. ```bash python -m pip install blake3 ``` -------------------------------- ### Start Node and Studio Services Source: https://github.com/animicaorg/all/blob/main/README.md Commands to initialize the network, start the node, and launch 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 ``` -------------------------------- ### Install and Run Animica MCP Server Source: https://github.com/animicaorg/all/blob/main/README.md Commands to install the MCP wrapper and start the server using stdio or streamable-http/sse transports. ```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 ``` -------------------------------- ### Manual Smoke Test Setup Source: https://github.com/animicaorg/all/blob/main/python/animica/stratum_pool/README.md Manual steps to start a testnet node and pool for verification. ```bash animica node up --network testnet --rpc ``` ```bash animica miner run-pool \ --mode pps \ --pool-address anim1... \ --rpc-url http://127.0.0.1:8545/rpc ``` ```bash ./animica-miner \ --pool-url stratum+tcp://127.0.0.1:3333 \ --address anim1... \ --worker rig-01 \ --threads 4 \ --pool-mode pps ``` -------------------------------- ### Serve an OpenAI-compatible API Source: https://github.com/animicaorg/all/blob/main/docs/ai.md Commands to install the backend and start the local API server with optional network and authentication configurations. ```bash pip install "animica[backend]" # FastAPI/uvicorn (lazy; friendly hint if missing) animica ai serve --port 8080 # open, local animica ai serve --host 0.0.0.0 --api-key $KEY # network + bearer auth ``` -------------------------------- ### TypeScript SDK Setup Source: https://github.com/animicaorg/all/blob/main/docs/tutorials/HELLO_COUNTER.md Initial imports and setup for the TypeScript SDK implementation. ```typescript import { HttpRpc, Config, Wallet, Signer, Tx, Contracts } from "@animica/sdk"; import fs from "node:fs"; ``` -------------------------------- ### Install the SDK Source: https://github.com/animicaorg/all/blob/main/docs/dev/SDK_PY.md Installation commands for the omni-sdk package via PyPI or local source. ```bash # From PyPI (recommended) pip install omni-sdk # Or from source (repo root): pip install -e ./sdk/python ``` -------------------------------- ### Clone and install dependencies Source: https://github.com/animicaorg/all/blob/main/docs/quickstart-devnet.md Initializes the project environment and installs the package in editable mode with stratum support. ```bash git clone https://github.com/animicaorg/all.git cd all python -m venv .venv source .venv/bin/activate python -m pip install -e "python[stratum]" ``` -------------------------------- ### Initialize Benchmark Environment Source: https://github.com/animicaorg/all/blob/main/docs/benchmarks/METHODOLOGY.md Commands to prepare the database and start the RPC node. ```bash python -m core.boot --genesis core/genesis/genesis.json --db sqlite:///bench.db ``` ```bash python -m rpc.server --config rpc/config.py ``` -------------------------------- ### Install and run tests Source: https://github.com/animicaorg/all/blob/main/docs/dev/TESTING.md Standard commands to install dependencies and execute unit or end-to-end tests. ```bash pnpm i pnpm test:unit pnpm test:e2e # Playwright ``` -------------------------------- ### Install the SDK Source: https://github.com/animicaorg/all/blob/main/docs/dev/SDK_TS.md Use npm or pnpm to add the SDK to your project. ```bash # app project npm i @animica/sdk # or pnpm add @animica/sdk ``` -------------------------------- ### Install VM(Py) and SDK tools Source: https://github.com/animicaorg/all/blob/main/docs/dev/CONTRACTS_START.md Install the necessary development tools for the Animica VM and Python SDK. ```bash # VM(Py) & Studio tools (from repo root if editable), otherwise pip install when published pip install -e vm_py/ studio-wasm/ sdk/python/ studio-services/ || true # Or just install the Python SDK if you only want deployment & calls: pip install omni-sdk ``` -------------------------------- ### Deploy USDAN Frontend Source: https://github.com/animicaorg/all/blob/main/docs/usdan/deployment.md Builds the frontend application and starts a preview server. ```bash pnpm --filter @animica/usdan-web build pnpm --filter @animica/usdan-web preview ``` -------------------------------- ### Initialize Environment Source: https://github.com/animicaorg/all/blob/main/README.md Install project dependencies and activate the virtual environment. ```bash ./setup.sh # or: FRESH=1 ./setup.sh --fresh source .venv/bin/activate ``` -------------------------------- ### Install Dependencies Source: https://github.com/animicaorg/all/blob/main/spec/test_vectors/README.md Commands to set up the Python virtual environment and install required dependencies from the repository root. ```bash # from repo root python -m venv .venv && source .venv/bin/activate pip install -r requirements.txt -r requirements-dev.txt ``` -------------------------------- ### Start Node Source: https://github.com/animicaorg/all/blob/main/docs/BOOTSTRAP.md Starts the node normally after genesis has been created. No password is required. ```bash python -m core.boot ``` -------------------------------- ### Install Quantum Dependencies Source: https://github.com/animicaorg/all/blob/main/docs/quantum-experiments.md Installs optional Qiskit and PennyLane libraries for enhanced simulation capabilities. ```bash pip install .[quantum] ``` -------------------------------- ### Manually Start Node with Environment Variables Source: https://github.com/animicaorg/all/blob/main/docs/p2p_sync.md Configure P2P networking and network parameters manually via environment variables before starting the node process. ```bash # Set network export ANIMICA_NETWORK=mainnet export ANIMICA_CHAIN_ID=1 # Enable P2P (enabled by default) export ANIMICA_P2P_ENABLE=true export ANIMICA_P2P_CHAIN_ID=1 # Auto-loads mainnet seeds # Optional: Override default listen addresses export ANIMICA_P2P_LISTEN_TCP=0.0.0.0:30333 export ANIMICA_P2P_LISTEN_QUIC=0.0.0.0:443 # Optional: Override seeds (not recommended - use auto-selected seeds) # export ANIMICA_P2P_SEEDS="/dns4/mainnet.animica.org/tcp/30333,/dns4/mainnet.animica.org/udp/443/quic-v1" # Start node python -m rpc ``` -------------------------------- ### Install Prerequisites on Ubuntu/Debian Source: https://github.com/animicaorg/all/blob/main/docs/dev/BUILD_FROM_SOURCE.md Commands to install system dependencies, Python, and Rust on Linux systems. ```bash sudo apt-get update sudo apt-get install -y \ python3.11 python3.11-venv python3-pip \ build-essential pkg-config cmake \ libssl-dev clang curl git # Rust curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y # (Optional) Speed: echo 'export RUSTFLAGS="-C target-cpu=native"' >> ~/.bashrc ``` -------------------------------- ### Verify Installation Source: https://github.com/animicaorg/all/blob/main/README.md Checks the CLI installation and validates post-quantum cryptographic functions. ```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')" ``` -------------------------------- ### Install and Initialize Animica CLI Source: https://github.com/animicaorg/all/blob/main/python/animica/cli/README.md Commands to install the package in editable mode and verify the CLI installation. ```bash pip install -e python/ ``` ```bash animica --help ``` -------------------------------- ### Install liboqs and Python bindings Source: https://github.com/animicaorg/all/blob/main/docs/quantum/PQ_PRECOMPILE_PLAN.md Installs the necessary system libraries and Python packages for quantum-safe cryptography on Ubuntu. ```bash sudo apt-get install liboqs-dev liboqs0 python -m pip install oqs ``` -------------------------------- ### Start Development Server Source: https://github.com/animicaorg/all/blob/main/docs/BUILD_DOCS.md Launch the local development environment to preview documentation changes. ```bash pnpm -C website dev ``` -------------------------------- ### Verification cURL Examples Source: https://github.com/animicaorg/all/blob/main/docs/dev/CONTRACTS_VERIFY.md Command-line examples for submitting a verification request and fetching the results. ```bash curl -sS -X POST "$SERVICES_URL/verify" \ -H "Content-Type: application/json" \ --data-binary @<(jq -n --arg addr "anim1..." \ --argjson manifest "$(cat counter/manifest.json)" \ --arg source "$(cat counter/contract.py)" \ '{address:$addr, manifest:$manifest, source:$source}') ``` ```bash curl -sS "$SERVICES_URL/verify/anim1..." ``` -------------------------------- ### Install systemd Service Source: https://github.com/animicaorg/all/blob/main/docs/providers/linux.md Runs the installation script to configure the worker as a systemd service. ```bash sudo ./install-systemd.sh ``` -------------------------------- ### Install WebSocket Client Source: https://github.com/animicaorg/all/blob/main/docs/dev/SDK_TS.md Initialize the WebSocket client with a custom factory. ```typescript import WebSocket from 'ws' const ws = new WsClient({ url: RPC_URL.replace(/^http/,'ws') + '/ws', wsFactory: (url) => new WebSocket(url) }) ``` -------------------------------- ### Contract Workflow Example Source: https://github.com/animicaorg/all/blob/main/python/animica/cli/README.md A sequence of commands to compile, deploy, and interact with a smart contract. ```bash animica contract compile vm_py/examples/counter/contract.py --out build/counter.avm --abi-out build/counter.abi.json --overwrite animica contract deploy build/counter.avm --from main --abi build/counter.abi.json --save --name counter --wait animica contract call counter get animica contract send counter inc --from main --wait ``` -------------------------------- ### Install and Configure Quantum Useful Work Node Source: https://github.com/animicaorg/all/blob/main/docs/QUANTUM_USEFUL_WORK.md Commands to install the animica package, verify hardware, and set up a production worker service. ```bash pip install -U animica # 5.0.0+ animica quantum quw detect # what sources are present animica quantum quw healthcheck --bytes 8192 # SP 800-90B health on a live batch animica quantum quw selftest # full local build→verify→reward roundtrip # Production worker (systemd): sudo cp ops/quantum/animica-quw.service /etc/systemd/system/ sudo cp ops/quantum/udev-quantis.rules /etc/udev/rules.d/99-animica-quantis.rules sudo mkdir -p /etc/animica && sudo cp ops/quantum/quw.env.example /etc/animica/quw.env sudo $EDITOR /etc/animica/quw.env # set address, RPC, signer=yubihsm2 sudo udevadm control --reload && sudo udevadm trigger sudo systemctl enable --now animica-quw ``` -------------------------------- ### Start Local Node Source: https://github.com/animicaorg/all/blob/main/python/animica/stratum_pool/README.md Initializes a local development node with RPC enabled. ```bash animica node up --network devnet --rpc ``` -------------------------------- ### Start JSON-RPC Node Source: https://github.com/animicaorg/all/blob/main/docs/dev/QUICKSTART.md Methods to start the RPC server and verify connectivity using curl. ```bash # Default: host 127.0.0.1, port 8545, db ./animica_devnet.db, chainId=1337 python -m rpc.server ``` ```bash pip install uvicorn[standard] uvicorn rpc.server:app --host 127.0.0.1 --port 8545 --log-level info ``` ```bash curl -s http://127.0.0.1:8545/healthz curl -s http://127.0.0.1:8545/rpc \ -H 'content-type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"chain.getParams","params":[]}' | jq curl -s http://127.0.0.1:8545/rpc \ -H 'content-type: application/json' \ -d '{"jsonrpc":"2.0","id":2,"method":"chain.getHead","params":[]}' | jq ``` -------------------------------- ### Start Local Devnet Services Source: https://github.com/animicaorg/all/blob/main/docs/tutorials/HELLO_COUNTER.md Commands to initialize the database, start the RPC server, and run the CPU miner. ```bash python -m core.boot \ --genesis core/genesis/genesis.json \ --db sqlite:///animica_dev.db Export the DB path so the RPC server can find it: export ANIMICA_DB=sqlite:///animica_dev.db Run the RPC server (HTTP JSON-RPC on :8545, WS on :8546): python -m rpc.server --host 127.0.0.1 --port 8545 In another terminal, start the built-in CPU miner so blocks get produced: python -m mining.cli.miner --threads 2 --device cpu ``` -------------------------------- ### Configure and Start a Mining Node Source: https://github.com/animicaorg/all/blob/main/docs/P2P_NETWORKING_GUIDE.md Enable mining features and start the RPC server to participate in block production. ```bash # Enable mining export ANIMICA_MINING_ENABLE=true export ANIMICA_MINING_ADDRESS= # Choose proof types export ANIMICA_MINING_HASH_WORK=true # CPU/GPU mining export ANIMICA_MINING_AI_PROOFS=true # Submit AI computations export ANIMICA_MINING_QUANTUM_PROOFS=true # Quantum circuit results # Start node with miner python -m rpc.server --enable-miner ``` -------------------------------- ### Network Switching Workflow Source: https://github.com/animicaorg/all/blob/main/docs/network-docker-compose.md Example sequence for switching between different network environments. ```bash # Start on testnet animica network set testnet animica node up # ... work on testnet ... animica node down # Switch to mainnet animica network set mainnet animica node up # ... work on mainnet ... animica node down ``` -------------------------------- ### Start an all-in-one L2 node Source: https://github.com/animicaorg/all/blob/main/docs/l2/RUNNING.md Enables the L2 node process and starts it alongside the L1 node. ```bash ANIMICA_L2_ENABLE=1 animica node up ``` -------------------------------- ### Get Chain Head Method Source: https://github.com/animicaorg/all/blob/main/docs/rpc/JSONRPC.md Example request to retrieve the current canonical chain head. ```json {"jsonrpc":"2.0","id":1,"method":"chain.getHead","params":[]} ``` -------------------------------- ### Manage Node Lifecycle Source: https://github.com/animicaorg/all/blob/main/README.md Commands to start the node in various modes. ```bash animica node up # background (default) animica node up --no-detach # foreground with logs animica node up --with-miner # include miner service ``` -------------------------------- ### Setup AICF Provider Worker Source: https://github.com/animicaorg/all/blob/main/docs/providers/python.md Extracts the worker package, creates a virtual environment, installs dependencies, and initializes the configuration. ```bash tar -xzf aicf-provider-worker-0.2.0-python.tar.gz cd aicf-provider-worker python3 -m venv .venv . .venv/bin/activate pip install -r requirements.txt python worker.py init-config --config provider.config.json ``` -------------------------------- ### Initialize Backend Environment Variables Source: https://github.com/animicaorg/all/blob/main/docs/usdan/environment-setup.md Copies the example environment file to the active configuration file for the backend service. ```bash cp services/usdan-api/.env.example services/usdan-api/.env ``` -------------------------------- ### Run Local Documentation Preview Source: https://github.com/animicaorg/all/blob/main/docs/README.md Commands to synchronize and start the local documentation development server. ```bash node website/scripts/sync_docs_from_repo.mjs ``` ```bash npm -w website install npm -w website run dev ``` -------------------------------- ### Initialize and use RpcProxy Source: https://github.com/animicaorg/all/blob/main/docs/MINING_PROXY.md Demonstrates creating a proxy instance with default or custom configurations and executing both async and sync requests. ```python from rpc.proxy import create_proxy, ProxyConfig # Create proxy with default config proxy = create_proxy() # Create proxy with custom config config = ProxyConfig( trusted_rpc_url="https://custom-rpc.example.com", max_retries=5, retry_delay_ms=2000, timeout_seconds=60.0, ) proxy = create_proxy(config) # Forward async request result = await proxy.forward_request( "miner.mine", {"count": 1, "address": "anim1..."}, fallback_handler=my_fallback_fn, ) # Forward sync request (from non-async context) result = proxy.sync_forward_request( "miner.mine", {"count": 1, "address": "anim1..."}, ) ``` -------------------------------- ### SUMMARY.json Example Source: https://github.com/animicaorg/all/blob/main/docs/benchmarks/APPENDIX.md Computed rollup metrics for a benchmark run. ```json { "tps_mean": 232.8, "tps_p95_block": 258.4, "lat_ms": { "p50": 328, "p90": 662, "p99": 1240 }, "blocks": 228, "block_time_ms_avg": 2591, "txs_total": 139521, "reject_rate_pct": 1.3, "da": { "posts": 1821, "bytes": 241172480 }, "zk": { "scheme_mix": {"groth16": 0.6, "plonk": 0.4}, "verifies": 9120, "fail": 0 }, "energy": { "joules_per_block": 820.5, "joules_per_tx": 3.9 }, "notes": "Warmup=120s excluded; open-loop λ=180/s." } ``` -------------------------------- ### Install Lean 4 Toolchain Source: https://github.com/animicaorg/all/blob/main/spec/formal/README.md Commands to install the Elan toolchain manager and verify the installation. ```bash curl https://raw.githubusercontent.com/leanprover/elan/master/elan-init.sh -sSf | sh -s -- --default-toolchain stable exec $SHELL # Check versions lean --version lake --version ``` -------------------------------- ### Initialize SDK Clients Source: https://github.com/animicaorg/all/blob/main/docs/STYLE_GUIDE.md Examples for initializing SDK clients in Python, TypeScript, and Rust. ```python from omni_sdk.tx.build import transfer tx = transfer(to="anim1xyz...", amount=123_000) ``` ```typescript import { Client } from "@animica/sdk"; const c = new Client({ rpcUrl: import.meta.env.PUBLIC_RPC_URL }); ``` ```rust let client = animica_sdk::rpc::http::Client::new(rpc_url)?; ``` -------------------------------- ### Node and Miner Initialization Source: https://github.com/animicaorg/all/blob/main/docs/benchmarks/SCENARIOS.md Commands to start the core node and the CPU miner. ```bash python -m core.boot --genesis core/genesis/genesis.json --db sqlite:///bench.db python -m mining.cli.miner --threads 8 --device cpu ``` -------------------------------- ### Minimal End-to-End Workflow Source: https://github.com/animicaorg/all/blob/main/docs/dev/SDK_RS.md A complete example demonstrating keystore initialization, signer creation, and nonce retrieval. ```rust use animica_sdk::{ rpc::http::HttpClient, wallet::{mnemonic, keystore::Keystore, signer::Signer}, address::bech32_address, tx::{build, send::send_tx}, }; use anyhow::Result; #[tokio::main] async fn main() -> Result<()> { let rpc = HttpClient::new("https://rpc.animica.dev")?; let seed = mnemonic::mnemonic_to_seed("... 24 words ...")?; let mut ks = Keystore::create("./ks.json", "pw")?; ks.import_seed(&seed)?; let signer = Signer::from_keystore(&ks, Some("dilithium3"))?; let from = bech32_address(&signer.public_key(), "anim")?; let nonce: u64 = rpc.call("state.getNonce", serde_json::json!([from])).await? .as_u64().unwrap(); ``` -------------------------------- ### Install Animica with ENA Support Source: https://github.com/animicaorg/all/blob/main/docs/ENA_UPGRADE.md Install the package in editable mode with ENA dependencies and verify the CLI installation. ```bash # Install Animica with ENA support pip install -e ".[ena]" # Verify installation animica ena upgrade --help ``` -------------------------------- ### Clone Repository and Setup Python Environment Source: https://github.com/animicaorg/all/blob/main/docs/dev/BUILD_FROM_SOURCE.md Steps to clone the project and initialize a Python virtual environment. ```bash git clone https://example.com/animica/animica.git cd animica # Python venv (choose your interpreter) python3.11 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate # Upgrade pip & install base tooling python -m pip install -U pip wheel setuptools # (Optional) If the repo has extras for dev: # python -m pip install -e ".[dev]" ``` -------------------------------- ### Start Node After Bootstrap Source: https://github.com/animicaorg/all/blob/main/docs/BOOTSTRAP.md Use the boot command for normal node startup once the genesis is initialized. ```bash python -m core.boot \ --genesis genesis/genesis.sample.mainnet.json \ --db sqlite:///animica.db ``` -------------------------------- ### Start Compute Services Source: https://github.com/animicaorg/all/blob/main/README.md Initializes all compute services using Docker Compose. ```bash make compute-dev # Start all compute services with Docker Compose ``` -------------------------------- ### Install contract dependencies Source: https://github.com/animicaorg/all/blob/main/docs/studio_deploy_quickstart.md Install the required Python dependencies for contract development. ```bash pip install -r contracts/requirements.txt ``` -------------------------------- ### Sync and Run Development Server Source: https://github.com/animicaorg/all/blob/main/docs/BUILD_DOCS.md Commands to install dependencies, synchronize documentation files from the repository, and launch the local development server. ```bash # one-time install pnpm install # pull the latest docs into website/src/docs (idempotent) node scripts/sync_docs_from_repo.mjs # start the dev server pnpm dev ``` -------------------------------- ### Install ENA Operator Source: https://github.com/animicaorg/all/blob/main/docs/ena_operator_quickstart.md Install the package in editable mode and initialize the configuration. ```bash cd /root/animica/python python -m pip install -e '.[dev,ena]' python -m animica ena config init python -m animica ena doctor ``` -------------------------------- ### Bootstrap devnet and start RPC server Source: https://github.com/animicaorg/all/blob/main/docs/tutorials/MINING_GUIDE.md Initializes the database from the genesis file and launches the RPC/WS server to handle mining requests. ```bash python -m core.boot \ --genesis core/genesis/genesis.json \ --db sqlite:///animica_dev.db export ANIMICA_DB=sqlite:///animica_dev.db python -m rpc.server --host 127.0.0.1 --port 8545 ``` -------------------------------- ### Install RocksDB dependencies Source: https://github.com/animicaorg/all/blob/main/docs/dev/BUILD_FROM_SOURCE.md Install RocksDB development libraries for Ubuntu or macOS. ```bash sudo apt-get install -y librocksdb-dev ``` ```bash brew install rocksdb ``` -------------------------------- ### Manage memory, config, and services Source: https://github.com/animicaorg/all/blob/main/docs/ena/cli.md Add memory entries, initialize configuration, and start the local API service. ```bash animica ena memory add "Sync uses header-first validation" --source docs/sync.md animica ena memory query "header-first sync" animica ena config init animica ena config show animica ena serve --host 127.0.0.1 --port 8787 ``` -------------------------------- ### Install ENA dependencies Source: https://github.com/animicaorg/all/blob/main/docs/ENA.md Install the necessary packages to interact with the ENA service. ```bash # Install dependencies pip install httpx # Or install Animica with extras pip install -e ".[ena]" ``` -------------------------------- ### Mining output example Source: https://github.com/animicaorg/all/blob/main/docs/tutorials/MINING_GUIDE.md Example of the log output generated during the mining process. ```text INFO mining.templates refreshing work from head height=0 theta=… INFO mining.hash_search found share d_ratio_ppm=712345 nonce=0x... INFO mining.share_submitter accepted share template=… ``` -------------------------------- ### Initialize Pool Environment Source: https://github.com/animicaorg/all/blob/main/python/animica/stratum_pool/README.md Generates a starter configuration file for the pool. ```bash animica pool init --path animica-pool.env ``` -------------------------------- ### Install Animica SDK Dependencies Source: https://github.com/animicaorg/all/blob/main/sdk/docs/USAGE.md Installation commands for Python, TypeScript, and Rust environments. ```bash # from repo root (editable dev install) python -m pip install -U pip python -m pip install -e ./sdk/python # runtime deps often used in examples python -m pip install anyio httpx websockets msgspec cbor2 ``` ```bash cd sdk/typescript npm ci npm run build # consume via workspace import or pack: npm pack # then in your app: # npm i ../path/to/@animica-sdk-*.tgz ``` ```bash cd sdk/rust cargo build ``` -------------------------------- ### Validate Studio Configuration Source: https://github.com/animicaorg/all/blob/main/python/animica/cli/README.md Check studio configuration settings before starting services. ```bash animica studio config ``` -------------------------------- ### Build the website Source: https://github.com/animicaorg/all/blob/main/docs/CONTRIBUTING.md Run the build process to verify Markdown and imports. ```bash # using npm with a subdir npm --prefix website install npm --prefix website run build ``` -------------------------------- ### Emit Event Example Source: https://github.com/animicaorg/all/blob/main/docs/vm/ABI.md Example of emitting an 'Inc' event with a single integer argument. ```python events.emit(b"Inc", {"value": 1}) ``` -------------------------------- ### Transfer Event Example Source: https://github.com/animicaorg/all/blob/main/docs/spec/RECEIPTS_EVENTS.md Example of emitting a 'Transfer' event with two indexed arguments. ```python events.emit(b"Transfer", {"from": A, "to": B, "value": 1000}, indexed=["from", "to"]) ``` -------------------------------- ### Native Coin Permit Example Source: https://github.com/animicaorg/all/blob/main/docs/pq/KEYS.md Example of a Permit payload for native coin transactions. ```json { "domain": "ANIMICA/PERMIT/V1", "chainId": 1, "owner": "<33B payload hex>", "spender": "<33B payload hex>", "token": "00…00", // 33 zero bytes for native "value": 1000000000, "nonce": 5, "deadline": 1924992000 // 2031-01-01 } ``` -------------------------------- ### SERIES.jsonl Payload Examples Source: https://github.com/animicaorg/all/blob/main/docs/benchmarks/APPENDIX.md Examples of time-series data entries for different metric kinds. ```json {"ts":"2025-03-18T19:22:10.012Z","kind":"mempool","admit_per_s":212.3,"reject_per_s":3.4,"evict_per_s":0.0,"min_fee":1200} ``` ```json {"ts":"2025-03-18T19:22:10.512Z","kind":"tx_lat","p50_ms":312,"p90_ms":640,"p99_ms":1182,"max_ms":2301,"inflight":800} ``` ```json {"ts":"2025-03-18T19:22:11.004Z","kind":"da","posts":36,"bytes":4718592,"proof_fail":0} ``` ```json {"ts":"2025-03-18T19:22:11.007Z","kind":"zk","scheme":"groth16","verifies":22,"avg_ms":4.9,"p99_ms":7.8,"fail":0} ``` ```json {"ts":"2025-03-18T19:22:11.100Z","kind":"power","cpu_w":142.3,"gpu_w":0.0,"pkg_w":158.7} ``` -------------------------------- ### Install ENA CLI Source: https://github.com/animicaorg/all/blob/main/docs/ena_cli_reference.md Install the ENA package in editable mode with development and ENA dependencies. ```bash cd /root/animica/python python -m pip install -e '.[dev,ena]' ``` -------------------------------- ### Create or Import Wallets Source: https://github.com/animicaorg/all/blob/main/docs/TROUBLESHOOTING.md Initialize a new wallet or import an existing one from a backup file. ```bash # Create new wallet animica wallet new # Or import existing animica wallet import --file backup.json ``` -------------------------------- ### Start an all-in-one development node Source: https://github.com/animicaorg/all/blob/main/docs/l2/RUNNING.md Launches a node with sequencer, prover, and RPC roles enabled in a single process. ```bash export ANIMICA_L2_ENABLE=1 animica node up animica l2 status ``` -------------------------------- ### Counter Contract Event Example Source: https://github.com/animicaorg/all/blob/main/docs/spec/RECEIPTS_EVENTS.md Example of emitting an 'Inc' event with one indexed argument. ```python # Contract events.emit(b"Inc", {"by": 1, "new": 42}, indexed=["new"]) ``` -------------------------------- ### Structured JSON Log Example Source: https://github.com/animicaorg/all/blob/main/docs/dev/DEBUGGING.md Example of a single-line JSON log entry with canonical fields. ```json {"ts":"2025-10-10T14:21:53.214Z","lvl":"info","mod":"rpc.methods.tx","evt":"tx.send", "req_id":"6yP2wG","txHash":"0x2f...ab","bytes":372,"dur_ms":11} ``` -------------------------------- ### Manage Node Lifecycle Source: https://github.com/animicaorg/all/blob/main/python/animica/cli/README.md Commands to start and stop nodes with various configuration flags for debugging, profiles, and data management. ```bash animica node up ``` ```bash animica node up --no-detach ``` ```bash animica node up --profile prod ``` ```bash animica node up --auto-reset-genesis-mismatch ``` ```bash animica node down ``` ```bash animica node down --volumes ``` -------------------------------- ### Quick Start Node Operations Source: https://github.com/animicaorg/all/blob/main/docs/network-docker-compose.md Basic commands to set the network and manage the node lifecycle. ```bash # Set the active network animica network set mainnet # Start the node (automatically uses mainnet compose file) animica node up # Check node status animica node status # Stop the node animica node down ``` -------------------------------- ### Manage Miner Pool Source: https://github.com/animicaorg/all/blob/main/python/animica/cli/README.md Commands for displaying pool configuration and starting the miner pool process. ```bash animica miner show-config animica miner run-pool --rpc-url http://localhost:8545 \ --db-url postgresql://... --stratum-bind 0.0.0.0:3334 ``` -------------------------------- ### Build and Install Native ZK Accelerator Source: https://github.com/animicaorg/all/blob/main/docs/dev/BUILD_FROM_SOURCE.md Commands to install maturin and build the native ZK module. ```bash python -m pip install maturin # From repo root maturin develop --release -m zk/native/pyproject.toml --features pairing,kzg,python python -c "import animica_zk_native as m; print('ok', m.__name__)" # => ok animica_zk_native maturin build --release -m zk/native/pyproject.toml --features pairing,kzg,python # Wheels land under zk/native/target/wheels/ ``` -------------------------------- ### Manage Wallet and Funds Source: https://github.com/animicaorg/all/blob/main/README.md Create a wallet and request funds from the faucet for development networks. ```bash animica wallet create --label mywallet animica faucet request mywallet # devnet/testnet only animica wallet show mywallet --source chain ``` -------------------------------- ### Orchestrate Multiple Networks Source: https://github.com/animicaorg/all/blob/main/python/animica/cli/README.md Starts all configured networks simultaneously or resets specific network states. ```bash animica node up-all # Start mainnet, testnet, devnet, local-devnet animica node up-all --with-miner # Start all networks with miners animica node up-all --no-detach # Run all in foreground (not recommended) # Override ports globally for all networks (not recommended when using up-all) HOST_RPC_PORT=9545 animica node up-all # Hard-reset a network (new genesis, chain_id stays 1) animica node reset --network mainnet --yes animica node reset --network mainnet --yes --up # reset + restart ``` -------------------------------- ### Node Startup and Debugging Source: https://github.com/animicaorg/all/blob/main/docs/network-docker-compose.md Various flags and workflows for starting nodes across different environments. ```bash # Start mainnet node (default production network) animica network set mainnet animica node up # Start testnet node (for testing with public testnet) animica network set testnet animica node up # Start devnet node (local development with 2 nodes + miner) animica network set devnet animica node up # Start mainnet node with miner (for mining operations) animica network set mainnet animica node up --with-miner # Start node in foreground (for debugging) animica node up --no-detach # Start node without rebuilding images animica node up --no-build ``` -------------------------------- ### Start RPC Server Source: https://github.com/animicaorg/all/blob/main/README.md Launches the RPC interface for the node, specifying database, genesis, and network connectivity settings. ```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 RPC Server in Free Mode Source: https://github.com/animicaorg/all/blob/main/docs/monetization.md Launch the RPC server using default free settings. ```bash # Start RPC server (free mode by default) python -m rpc.server ``` -------------------------------- ### Rejected Sandbox Code Example Source: https://github.com/animicaorg/all/blob/main/docs/vm/SANDBOX.md Example of code that is rejected due to non-deterministic imports like time. ```python import time # forbidden import def now(): return time.time() # nondeterministic ``` -------------------------------- ### Create a new wallet Source: https://github.com/animicaorg/all/blob/main/docs/ENA.md Initialize a new wallet file when the default configuration is missing. ```bash # Create a new wallet animica wallet new ``` -------------------------------- ### JSON-RPC Request Examples Source: https://github.com/animicaorg/all/blob/main/docs/FAUCET.md Examples of requesting test funds using the default amount or a custom amount. ```json { "jsonrpc": "2.0", "method": "faucet.request", "params": { "address": "anim1zqqjt3258rgnfckqxv686unmgtvkl2hn6y7afdgxthummydzr6exw9spuqzdz" }, "id": 1 } ``` ```json { "jsonrpc": "2.0", "method": "faucet.request", "params": { "address": "anim1zqqjt3258rgnfckqxv686unmgtvkl2hn6y7afdgxthummydzr6exw9spuqzdz", "amount": 1000000000000000 }, "id": 1 } ``` -------------------------------- ### Start P2P nodes for snapshot testing Source: https://github.com/animicaorg/all/blob/main/docs/P2P_SNAPSHOT_PROTOCOL.md Initializes two nodes where one acts as a seed for the other to test P2P connectivity. ```bash # Node 1 (has snapshot) animica node --p2p-port 30333 --chain-id 1 # Node 2 (will query node 1) animica node --p2p-port 30334 --chain-id 1 --seed /ip4/127.0.0.1/tcp/30333 ``` -------------------------------- ### Address Usage Examples Source: https://github.com/animicaorg/all/blob/main/docs/MINING_TROUBLESHOOTING.md Demonstrates using wallet labels versus explicit Bech32 addresses. ```bash # If using a label, ensure it exists in your wallet animica wallet list # Or use the full Bech32 address explicitly animica miner mine-blocks --address anim1zqqjt... --count 5 ``` -------------------------------- ### Start Devnet Stack Source: https://github.com/animicaorg/all/blob/main/docs/devnet-node1-container-exits.md Commands to navigate to the project directory and execute the spinup script. ```bash cd /root/animica ./ops/spinup/spin_all.sh ``` -------------------------------- ### Sync Documentation Locally Source: https://github.com/animicaorg/all/blob/main/docs/BUILD_DOCS.md Run this script to sync documentation files from the repository into the local website directory. ```bash node website/scripts/sync_docs_from_repo.mjs ``` -------------------------------- ### Install mining and RPC dependencies Source: https://github.com/animicaorg/all/blob/main/docs/tutorials/MINING_GUIDE.md Configures the Python virtual environment and installs all required packages for mining and RPC communication. ```bash ./setup.sh source .venv/bin/activate ``` -------------------------------- ### Manage Wallets and PQ Signers Source: https://github.com/animicaorg/all/blob/main/docs/dev/SDK_PY.md Examples for creating keystores and using ephemeral in-memory signers for post-quantum cryptography. ```python from pathlib import Path from omni_sdk.wallet.mnemonic import mnemonic_to_seed from omni_sdk.wallet.keystore import Keystore from omni_sdk.wallet.signer import Signer from omni_sdk.address import bech32_address mnemonic = "abandon ... (24 words) ..." seed = mnemonic_to_seed(mnemonic) # bytes ks_path = Path("./keystore.json") ks = Keystore.create(ks_path, password="strong-passphrase") ks.import_seed(seed) signer = Signer.from_keystore(ks, alg="dilithium3") # or "sphincs_shake_128s" addr = bech32_address(signer.public_key(), hrp="anim") print("Address:", addr) # anim1... ``` ```python from omni_sdk.wallet.signer import InMemorySigner signer = InMemorySigner.from_seed(seed, alg="dilithium3") ``` -------------------------------- ### Install and verify script artifacts Source: https://github.com/animicaorg/all/blob/main/docs/mining_scripts.md Commands to verify the integrity of a script artifact and install it locally with pinning for consensus verification. ```bash # Verify artifact hash animica script verify ./script_artifact.json # Install locally (stored under ~/.animica/scripts//) animica script install ./script_artifact.json --pin ``` -------------------------------- ### Start Stratum Pool and API Source: https://github.com/animicaorg/all/blob/main/docs/ops/mining-portal.md Initialize the Stratum pool and API services using environment variables for binding. ```bash export ANIMICA_STRATUM_BIND=0.0.0.0:3333 export ANIMICA_POOL_API_BIND=0.0.0.0:8550 animica stratum up --daemon ``` -------------------------------- ### Install Prerequisites on macOS Source: https://github.com/animicaorg/all/blob/main/docs/dev/BUILD_FROM_SOURCE.md Commands to install Xcode command line tools, Homebrew, Python, and Rust toolchains on macOS. ```bash # Xcode CLT xcode-select --install # Homebrew (if not installed): https://brew.sh brew update # Python & tooling brew install python@3.11 pyenv pipx # Rust & build deps brew install rustup cmake pkg-config openssl@3 rustup-init -y # (Optional) Speed: optimize for local CPU echo 'export RUSTFLAGS="-C target-cpu=native"' >> ~/.zshrc ``` -------------------------------- ### Install and Configure MCP Tools Source: https://github.com/animicaorg/all/blob/main/docs/ai.md Commands to install the Animica MCP package and integrate it with Claude, Cursor, or VS Code. ```bash pip install "animica[mcp]" animica mcp install claude # also: cursor | vscode (merges, never clobbers) animica mcp install vscode --print # preview the JSON without writing ``` -------------------------------- ### Initialize and Start Animica Node Source: https://github.com/animicaorg/all/blob/main/docs/P2P_NETWORKING_GUIDE.md Commands to clone the repository, set environment variables, and launch the node process. ```bash # 1. Clone and setup git clone https://github.com/animicaorg/all.git cd all ./setup.sh source .venv/bin/activate # 2. Set your network (mainnet, testnet, or devnet) export ANIMICA_NETWORK=mainnet # 3. Enable P2P (enabled by default) export ANIMICA_P2P_ENABLE=true # 4. Start the node python -m rpc.server --db ~/.animica/chain-1/mainnet.db ``` -------------------------------- ### Start Mainnet/Testnet Services Source: https://github.com/animicaorg/all/blob/main/docs/network-docker-compose.md Use these commands to manage mainnet and testnet service profiles. ```bash # Start mainnet node only animica node up # Start mainnet node with miner animica node up --with-miner # Start studio services animica studio up ``` -------------------------------- ### VDF Bonus Proof Worked Example Source: https://github.com/animicaorg/all/blob/main/docs/spec/proofs/ENVELOPE.md An annotated example showing the mapping of a VDF bonus proof into a serialized envelope. ```text type_id = 0x05 ; VDF bonus v1 body_map = { "domain": "VDF_V1/Wesolowski", "chainId": 1, "height": 123456, "seed": h'8f…21', ; 32 bytes "modulus_id":"rsa2048-netA", "g": h'02…7b', "y": h'43…19', "pi": h'a9…55', "T": 33554432, "params": {"lambda":128, "l_bits":256}, "provider":{"id":"prov-01", "pubkey":h'…', "nonce":h'00112233445566778899aabbccddeeff'}, "bind_sig": h'30…01' } body_bytes = CBOR_CANON(body_map) ; bstr of ~ 300–800 bytes domain = "PROOF_NULLIFIER/VDF_V1" nullifier = SHA3_256(domain || body_bytes)[:32] = h'c4…5a' envelope = { type_id: 5, body: h'58…', nullifier: h'c4…5a' } ``` -------------------------------- ### Prepare ENA training dataset Source: https://github.com/animicaorg/all/blob/main/docs/ena_training.md Initializes the training manifest using a dataset and a custom launcher command. ```bash cd /root/animica/python python -m animica ena train prepare \ --dataset /tmp/train.jsonl \ --out /tmp/train_manifest.json \ --base-model tiny-local-model \ --backend command \ --auto-split \ --launcher-command "python external_trainer.py --manifest {manifest} --output-dir {output_dir}" ``` -------------------------------- ### GET /v1/receipts Source: https://github.com/animicaorg/all/blob/main/docs/ena/studio-integration.md Lists all receipts. ```APIDOC ## GET /v1/receipts ### Description Lists all receipts. ### Method GET ### Endpoint /v1/receipts ``` -------------------------------- ### GET /v1/jobs Source: https://github.com/animicaorg/all/blob/main/docs/ena/studio-integration.md Lists all jobs. ```APIDOC ## GET /v1/jobs ### Description Lists all jobs. ### Method GET ### Endpoint /v1/jobs ```