Filecoin Architecture Positioning for py-libp2p

This page positions py-libp2p within the Filecoin ecosystem so developers can choose the right stack for the right job.

How py-libp2p fits in Filecoin architecture today

py-libp2p is a Python networking toolkit that can interoperate at the libp2p layer, and this package provides a Filecoin-focused DX layer for protocol IDs, topic formats, bootstrap presets, and practical examples.

Normative references:

Where py-libp2p is production-viable today

py-libp2p is production-viable for focused networking tasks that do not require full Filecoin consensus execution:

  • protocol/tooling adapters around known Filecoin protocol IDs and topics.

  • telemetry and observer workflows (for example read-only pubsub observers).

  • integration harnesses and dev/testnet experimentation.

  • controlled research and replay tooling where Python ergonomics are preferred.

Normative references:

Where Lotus/Forest (full implementations) are still required

Lotus/Forest remain required for full node behavior tied to Filecoin chain consensus and state transitions. Examples include:

  • canonical chain sync and finality handling.

  • actor/state execution and state-root correctness.

  • full message pool policy and block production integration.

  • complete protocol-surface parity expected from production validators/miners.

Normative references:

Suggested use cases: tooling, analytics, testnets, research

Recommended use-cases for py-libp2p + libp2p.filecoin:

  • Tooling: protocol/topic inspectors, peer capability checks, and bootstrap diagnostics.

  • Analytics: read-only subscription pipelines and metadata capture.

  • Testnets: rapid prototyping of network behaviors and failure experiments.

  • Research: hypothesis testing for scoring, peer selection, and transport adaptation before upstreaming to larger clients.

Normative references:

Decision boundaries and anti-goals

This package is intentionally DX/tooling scoped.

Out of scope:

  • replacing Lotus/Forest as full production nodes.

  • implementing full chain-sync/state-validation pipeline in Python.

  • claiming consensus-equivalent behavior from helper constants alone.

In scope:

  • accurate Filecoin networking constants and presets.

  • practical developer-facing examples for connect, ping/identify, and read-only pubsub observation.

  • explicit traceability back to pinned Lotus v1.35.0 and Forest 0.32.2 references.

Normative references:

Capability matrix

Concern

py-libp2p status

Lotus/Forest requirement

Why

Recommended path

Filecoin protocol/topic constants

Implemented in libp2p.filecoin

Not required for constants themselves

Values are pinned from upstream snapshots

Use DX helpers directly

Bootstrap address handling

Implemented (canonical + runtime helpers)

Not required for helper usage

DNS-first canonical lists need runtime adaptation in Python workflows

Use get_runtime_bootstrap_addresses

Read-only gossip observation

Implemented

Not required

Observer workflows do not require consensus execution

Use filecoin-pubsub-demo observer mode

Peer diagnostics (connect/ping/identify)

Implemented as examples

Not required

Useful for interoperability checks and network diagnostics

Use filecoin-connect-demo and filecoin-ping-identify-demo

Full chain sync + state execution

Not implemented

Required

Requires full protocol semantics and actor/state machinery

Run Lotus or Forest nodes

DHT format divergence note

There is an explicit divergence between commonly cited textual spec form and the pinned Lotus helper snapshot used in this implementation:

  • Textual form often cited: fil/<network-name>/kad/1.0.0.

  • Pinned Lotus helper form: /fil/kad/<network-name>.

Implementation decision:

  • default to pinned implementation parity for dht_protocol_name in libp2p.filecoin, and document the divergence explicitly.

Rationale:

  • this implementation is parity-driven against the Lotus v1.35.0 and Forest 0.32.2 code snapshots provided for implementation review.