Filecoin

Skill based on Lotus (filecoin-project/lotus), generated at 2026-02-24.

Lotus is the reference implementation of the Filecoin Distributed Storage Network. It provides a full node (lotus), storage miner (lotus-miner), and worker (lotus-worker) with JSON-RPC API for chain, state, message pool, gas, market, payment channels, multisig, and (when enabled) Eth and Actor Events.

Core References

Features

Best Practices

External Links

• Lotus docs
• Filecoin spec
• filecoin-project/lotus

Generation Info

• Source: sources/filecoin
• Git SHA: e2427dabec405175131aa7b7b7b30e1f1d359411
• Generated: 2026-02-24

ChainIndexer

The ChainIndexer indexes chain data for the *Ethereum (eth_) and Actor Events** APIs. It is disabled by default. You must enable and backfill it if you use EnableEthRPC or EnableActorEventsAPI.

When required

• EnableEthRPC = true (Ethereum JSON-RPC) → ChainIndexer required.
• EnableActorEventsAPI = true (GetActorEventsRaw, SubscribeActorEventsRaw) → ChainIndexer required.
• If you do not serve public RPC and do not need Eth or Actor Events, leave these false and skip ChainIndexer.

Config

[Fevm]
  EnableEthRPC = true

[Events]
  EnableActorEventsAPI = true

[ChainIndexer]
  EnableIndexer = true
  # Optional: GC old index data. Default 0 = keep all.
  GCRetentionEpochs = 0   # or e.g. 10000

If Eth or Events are enabled but ChainIndexer is not, Lotus exits at startup.

Garbage collection

• GCRetentionEpochs > 0: Indexer periodically drops data for epochs older than (current_head_height - GCRetentionEpochs). Default 0 keeps all.
• Size and retention trade-offs are documented in the chain-indexer operator doc (backfill disk space, etc.).

Backfill

• Existing LOTUS_PATH: Follow the multi-step upgrade in the docs: create backfilled chainindex.db, optionally create a copyable db, update other nodes, cleanup. Use lotus index validate-backfill to verify.
• Snapshot import: You can enable indexer when importing from snapshot; follow “Upgrade when importing chain state from a snapshot” in the doc.
• Backfill timing and disk requirements depend on chain height and config; see operator doc for numbers and recommendations.

Usage for agents

• Enabling Eth or Events: set config as above, enable ChainIndexer, run backfill (or snapshot import) before relying on Eth/Events APIs.
• Validate: use lotus index validate-backfill and any ChainValidateIndex RPC mentioned in the doc.
• Downgrade: document describes downgrade steps if you disable indexer or APIs.

Key points

• EnableIndexer must be set explicitly so operators are aware of extra workload and storage.
• RPC providers and high-performance nodes that serve Eth or Events need backfill and regular checks as described in the operator doc.
• Regular checks and terminology (previous indexing vs ChainIndexer) are in the same doc.

<!-- Source references:

• sources/filecoin/documentation/en/chain-indexer-overview-for-operators.md
• sources/filecoin/documentation/en/default-lotus-config.toml (Fevm, Events, ChainIndexer)

-->

Config and Environment

Lotus full node config is TOML; path can be set via --config or env. Default config template is in documentation/en/default-lotus-config.toml. Many options have matching env vars (e.g. LOTUS_*).

API

• ListenAddress — bind address (e.g. /ip4/127.0.0.1/tcp/1234/http). Env: LOTUS_API_LISTENADDRESS.
• RemoteListenAddress, Timeout — optional. Env: LOTUS_API_REMOTELISTENADDRESS, LOTUS_API_TIMEOUT.
• LOTUS_API_MAXREQSIZE — max JSON-RPC request size (default 0 = no limit).

Libp2p

• ListenAddresses — multiaddrs; 0 = random port. Env: LOTUS_LIBP2P_LISTENADDRESSES.
• AnnounceAddresses, NoAnnounceAddresses — what to announce to peers.
• DisableNatPortMap — disable NAT port mapping (default false).
• ConnMgrLow / ConnMgrHigh — connection manager trim target and GC trigger.

Repo and paths

• Default repo: $HOME/.lotus (or LOTUS_PATH). Single daemon per repo; repo.lock enforces.
• LOTUS_BACKUP_BASE_PATH — required for online backups; backup command path must be under this base.
• LOTUS_ENABLE_CHAINSTORE_FALLBACK=1 — enable fallback blockstore (bitswap) for any block Get.
• LOTUS_ENABLE_MESSAGE_FETCH_INSTRUMENTATION=1 — metrics for message fetch (local vs network).

Fevm and Events

• Fevm.EnableEthRPC — enable Eth JSON-RPC (requires ChainIndexer).
• Events.EnableActorEventsAPI — enable GetActorEventsRaw / SubscribeActorEventsRaw (requires ChainIndexer).
• ChainIndexer.EnableIndexer, GCRetentionEpochs — see best-practices-chain-indexer.

Logging

• Logging.SubsystemLevels — per-subsystem log level. Env: LOTUS_LOGGING_SUBSYSTEMLEVELS_<subsystem>.

Daemon flags (override config)

• --api, --config, --lite, --bootstrap, --import-snapshot, --pprof, --manage-fdlimit — see lotus daemon --help.

Usage for agents

• Remote API: set ListenAddress or use port forwarding; use AuthNew to create tokens, pass token in RPC client. Connect with http or ws (for Subscribe*).
• Tuning: adjust ConnMgr* for peer count; set GCRetentionEpochs if you need to cap index size.
• Debug: enable MESSAGE_FETCH_INSTRUMENTATION to see bitswap vs local message fetch; set subsystem log levels for sync/mpool/vm.

Key points

• Config file is optional; defaults apply. Env vars override config.
• One repo per node type (full node vs miner); miner uses different repo (e.g. ~/.lotusstorage) and connects to full node API.
• Full option list and types are in default-lotus-config.toml with comments and env var names.

<!-- Source references:

• sources/filecoin/documentation/en/default-lotus-config.toml
• sources/filecoin/documentation/en/architecture/architecture.md (repo, node)
• sources/filecoin/README.md (env, advanced options)

-->

Gas Balancing

Gas balancing aligns syscall gas costs with a target of ~10 gas per nanosecond on reference hardware (TR3970x, 128GB RAM). Used by protocol/actor developers and node operators tuning or auditing gas.

Full gas balancing (lotus-bench)

• Enable tracing: Set EnableDetailedTracing = true in chain/vm/runtime.go before building.
• Import and trace: ./lotus-bench import --car <path-to-CAR-export> [--start-epoch N] [--end-epoch M]. State for start-epoch must be in the CAR or already computed. Produces bench.json (all syscalls and timings; can be large).
• Analyze: ./lotus-bench import analyze bench.json. Outputs means, standard deviations, covariances in nanoseconds; target gas ≈ 10× nanosecond value. Use correlation strength when covariances are used.
• Special case: OnIpldPut compute gas is based on flush-to-disk time; during execution objects are in memory. Use vm/flush_copy_ms and vm/flush_copy_count to estimate OnIpldPut compute cost.

Targeted gas balancing (single syscall)

When full balancing is infeasible (new syscall or cost), use in-vivo benchmarks: run the syscall during real block execution. In-vitro (standalone) benchmarks are often inaccurate.

• Hook: Best place is the message execution loop in chain/stmgr/stmgr.go, ApplyBlocks(). Optionally run once every N messages if the syscall is expensive.
• Measure: Time the syscall in context; convert to gas with same 10 gas/ns target.

Usage for agents

• When adding or changing syscall costs: run lotus-bench import on a representative chain export (mainnet or testnet slice), then analyze bench.json and map ns → gas. For single-syscall work, add a timed hook in ApplyBlocks and compute gas from observed time.
• Do not rely on standalone micro-benchmarks for final gas values; use chain execution context.

Key points

• Reference hardware may change; document what you used when publishing gas updates.
• bench.json size can be very large; ensure sufficient disk for import.
• OnIpldPut and any syscall that does I/O need special handling (flush metrics or in-vivo with real storage).

<!-- Source references:

• sources/filecoin/documentation/misc/gas_balancing.md
• chain/vm/runtime.go (EnableDetailedTracing)
• chain/stmgr/stmgr.go (ApplyBlocks)

-->

Lotus Architecture

Lotus implements the Filecoin Distributed Storage Network. A node comprises the Syncer, State Manager, VM, Repository, and P2P (libp2p) stack. Full user docs live at lotus.filecoin.io; this skill focuses on concepts and code paths useful for agents.

Key concepts

• Tipsets: Filecoin allows multiple blocks per round with the same parent set. A tipset is a set of blocks sharing the same parents. Chain weight is the number of blocks in the chain (not difficulty). The "head" is the heaviest tipset.
• Actors and messages: Actors are like smart contracts; builtin actors (Power, Miner, Market, Init, etc.) are pre-compiled. Messages are like transactions; the VM executes them and updates state.
• Sync: Node syncs to the heaviest chain advertised by peers. Flow: hello exchange → collect headers (StageHeaders/PersistHeaders) → fetch and validate full blocks (StageMessages) → set head (StageSyncComplete). Uses ChainExchange for bulk headers and bitswap for message retrieval when messages are missing locally.
• State: Chain state at any point is a root CID in a StateTree, managed by StateManager. Tipset state is computed by applying all messages in the tipset (and implicit Reward/Cron messages).
• VM: Applies messages, invokes builtin actor methods via an invoker (method number → Go function), meters gas, and produces MessageReceipts.
• Repo: Single directory (e.g. ~/.lotus) defines the node; one daemon per repo (enforced by repo.lock). Contains Datastore (e.g. Badger), ChainBlockstore (/blocks), metadata, keystore.
• Node types: FullNode (full validation, sync, API) and StorageMiner (miner services, own repo e.g. ~/.lotusstorage).

Network flow

• PubSub: /fil/blocks/{network} for block headers, /fil/msgs/{network} for messages. Messages are usually received via pubsub before blocks; when a block is processed, messages are fetched from local blockstore or via bitswap if missing.
• Bitswap: Session-based bitswap fetches missing messages during block processing. Optional LOTUS_ENABLE_CHAINSTORE_FALLBACK=1 wraps blockstores for transparent network fetch on any missing Get. Monitor with LOTUS_ENABLE_MESSAGE_FETCH_INSTRUMENTATION=1.

Usage for agents

• Reason about chain growth in terms of tipsets and weight; use ChainHead/ChainGetTipSet for current head.
• To push transactions use MpoolPushMessage (assigns nonce, signs, pushes) or MpoolPush for pre-signed messages.
• State queries go through State APIs; chain data through Chain APIs. Gas estimation: GasEstimateMessageGas, GasEstimateFeeCap, GasEstimateGasPremium.

Key points

• Heaviest tipset wins; no single "block difficulty."
• Builtin actors only; no user-deployed contracts in the native VM (FEVM is separate).
• Sync and block validation are multi-stage; block validation includes beacon, VRF, winning PoSt, message validity, and state root checks.

<!-- Source references:

• sources/filecoin/documentation/en/architecture/architecture.md
• sources/filecoin/documentation/en/about.md
• https://spec.filecoin.io

-->

Lotus CLI

Three binaries: lotus (node + wallet + chain/state/mpool), lotus-miner (storage miner), lotus-worker (sealing/mining tasks). All content in English; agent-oriented usage only.

lotus

• daemon: lotus daemon — start node. Options: --api, --config, --lite, --import-snapshot, --bootstrap, --pprof. lotus daemon stop to stop.
• Wallet: lotus wallet new (secp256k1 default; BLS optional), lotus wallet list, lotus send <target> <amount>.
• Chain/state: lotus chain head, lotus state call, lotus state replay, lotus state wait-msg.
• mpool: lotus mpool pending, lotus mpool sub, lotus mpool stat, lotus mpool replace, lotus mpool find, lotus mpool config, lotus mpool clear (use with care).
• Auth: lotus auth for API tokens. Network: lotus net, lotus sync, lotus status. F3: lotus f3 for Fast Finality. EVM: lotus evm for Filecoin EVM runtime.
• Config: lotus config default, lotus config updated. Backup: lotus backup [path] (respects LOTUS_BACKUP_BASE_PATH for online backups).

lotus-miner

• Init: lotus-miner init — creates StorageMiner node; requires synced full node and proof params. Owner/worker addresses and peer ID define the miner; CreateMiner message is sent to Power Actor.
• Run: lotus-miner run (with API connection to lotus). Commands for storage, deals, sectors, proving, etc. (see lotus-miner docs on lotus.filecoin.io for full list).

lotus-worker

• Used by miners to run sealing and other compute-heavy tasks; connects to lotus-miner. See cli-lotus-worker.md and miner docs for subcommands.

Usage for agents

• Start/stop node: lotus daemon / lotus daemon stop. Check readiness: lotus wait-api then lotus status or lotus chain head.
• Send FIL: lotus send <addr> <amount>. Create wallet: lotus wallet new.
• Inspect mpool: lotus mpool pending, lotus mpool find --from <addr>. Replace tx: lotus mpool replace --gas-feecap <cap> --gas-premium <premium> --gas-limit <limit> <from> <nonce>.
• For miner creation flow (owner, worker, Power Actor, Init Actor), see create-miner doc; use lotus-miner init with defaults or specified owner/worker.

Key points

• Default repo: ~/.lotus (lotus), ~/.lotusstorage (lotus-miner). Only one daemon per repo (repo.lock).
• Nonce handling: prefer MpoolPushMessage (API) for atomic nonce+sign+push; MpoolGetNonce is not atomic.
• Full install/get-started docs are at lotus.filecoin.io; this skill omits them.

<!-- Source references:

• sources/filecoin/documentation/en/cli-lotus.md
• sources/filecoin/documentation/en/cli-lotus-miner.md
• sources/filecoin/documentation/en/cli-lotus-worker.md
• sources/filecoin/documentation/en/create-miner.md

-->