Project Venus Documentation

The Venus API v1 is organized into several functional groups. Developers can interact with the following high-level modules:

• Account: Manage account keys and state.
• Actor: Interact with actors, list them, or subscribe to actor events.
• BlockStore: Low-level object storage operations (Put, Get, Stat, Delete).
• ChainInfo: Retrieve chain state, blocks, messages, receipts, and tipsets.
• Common: Basic node information like status and version.
• ETH: Ethereum-compatible JSON-RPC methods (e.g., EthGetBalance, EthSendRawTransaction).
• F3: F3-specific operations like certificate management and participation.
• Market: Access market participant state.
• MessagePool: Manage the pool of pending messages and gas estimation.
• MinerState: Detailed queries regarding miner allocations, sectors, and balances.
• Mining: Core mining operations like creating blocks.
• Network: Peer discovery, connectivity, and bandwidth statistics.
• Paychan: Payment channel operations (Fund, Settle, Voucher management).
• Syncer: Synchronization logic and tipset management.
• Wallet: Wallet management including signing, importing, and address handling.

A designdoc is a short document used to capture design intent. Its purpose is to articulate a problem, propose a solution, and provide the reasoning (the why) behind that solution. It is a planning tool used to discover truths and evaluate hypotheses collectively, rather than a document meant to defend a fixed position.

To be effective, a designdoc should include these core sections:

• Problem Statement: Clearly define what problem is being solved and why it matters.
• Requirements and anti-requirements: Enumerate assumptions, constraints, non-goals, and anti-requirements.
• Proposal & Rationale: A sketch of the proposed solution and the reasoning behind it (e.g., what is gained by doing this vs. what is lost if not done).
• Alternatives: Explicitly state what other approaches were considered and why they were rejected.

Key Characteristics:

• Focus on 'Why': Unlike a specification (spec), a designdoc focuses on the rationale and the big picture.
• Brevity: It should be concise and prioritize clarity over length.
• Not a Spec: A spec is a dense, detail-oriented contract for interoperability; a designdoc is a high-level tool for rationalizing a plan before implementation.
• Not a GitHub Issue: While it can be hosted in an issue, it should serve as a coherent summary of conclusions rather than a raw discussion thread.

The venus-shared/actors/builtin package provides shims used to abstract over different actor versions. These shims follow three core design principles to ensure stability across protocol upgrades:

1. Structure Agnostic: Shim interfaces are designed to remain stable even if the underlying data structure changes. To achieve this, all shims utilize an internal store object, allowing state to be moved without altering function signatures. Additionally, all functions are required to return an error to maintain a consistent signature.
2. Minimalism: Interfaces are kept minimal to reduce the maintenance burden during upgrades.
3. Queries over Field Accessors: Functions are designed to query state (e.g., asking 'is this actor active?') rather than simply acting as field assessors (e.g., 'get the status field'). Queries are more resilient to changes in the underlying specification/actor upgrades. However, developers should avoid implementing overly complex logic within the shim itself to prevent duplication across different shim implementations.