Understanding the 3DPass Node Structure: A Complete Directory Guide

The 3DPass node follows a Substrate-based architecture organized around seven core directories, including the POS-scan consensus client in nodes/poscan-consensus, the WASM runtime in runtime/src/lib.rs, and custom pallets in pallets/ that enable the Ledger of Things functionality.

The 3DPass node is the official client for the 3Dpass blockchain network, implemented in the 3dpass/3DP repository as a specialized Substrate-based client. Its directory structure extends the standard Substrate layout with 3DPass-specific components for the POS-scan consensus algorithm, EVM compatibility, and decentralized 3-D object recognition. Understanding this structure is essential for validators, miners, and developers building on the Ledger of Things.

Top-Level Directory Architecture

The repository organizes code into functional layers that separate the consensus engine, runtime logic, and external tooling. Each directory serves a distinct purpose in the blockchain stack:

• nodes/poscan-consensus/ – The executable binary and service orchestration
• runtime/src/lib.rs – The WASM runtime containing all state transition logic
• pallets/ – Individual FRAME pallets implementing business logic
• precompiles/ – Ethereum pre-compiles for Solidity contract integration
• frontier/ – EVM execution environment and Ethereum RPC adapters
• consensus/poscan_grid2d/ – The grid-based 3-D object hashing algorithm
• miner.js and miner-libs/ – JavaScript mining client for external hash computation

The Node Client: nodes/poscan-consensus

The nodes/poscan-consensus directory contains the executable client that wires together networking, RPC endpoints, telemetry, and consensus mechanisms. This is where the node binary is built and launched.

Entry Point and Service Construction

The bootstrapping sequence begins in nodes/poscan-consensus/src/main.rs, which invokes command::run() to parse CLI arguments and initialize the full node service. The service.rs file handles the complex orchestration of Substrate components:

// From nodes/poscan-consensus/src/service.rs
pub fn new_full(config: Configuration) -> Result<TaskManager, ServiceError> {
    let PartialComponents { client, backend, task_manager, import_queue, keystore_container, select_chain, transaction_pool, other } = new_partial(&config)?;
    // Consensus, RPC, and Frontier integration occurs here
}

The service builder establishes four critical components:

1. FullClient and FullBackend – Database and client interfaces
2. POS-scan PoW Consensus – Custom block import via PowBlockImport delegating to PoscanAlgorithm
3. Grandpa Finality – The GrandpaBlockImport gadget for block finalization
4. Frontier Integration – FrontierBlockImport wrapper for EVM compatibility

The Runtime Layer: runtime/src/lib.rs

The WASM runtime defined in runtime/src/lib.rs contains the state transition function and all blockchain business logic. This file uses the construct_runtime! macro to assemble pallets and defines type aliases for AccountId, Balance, and BlockNumber.

Key runtime configurations include:

• Consensus configuration – POS-scan parameters and validator sets
• Pallet instantiation – All custom and FRAME pallets wired together
• Runtime APIs – Implemented via impl_runtime_apis! for client communication

The runtime compiles to WebAssembly and executes within the Substrate executor, ensuring deterministic state transitions across all node implementations.

Custom Pallets and Business Logic: pallets/

The pallets/ directory contains FRAME pallets that implement the Ledger of Things functionality. Each pallet resides in its own subdirectory with a src/lib.rs entry point:

• pallet_validator_set – Manages the validator set rotation for POS-scan consensus
• pallet_mining_pool – Stores mining proposals and tracks network difficulty
• pallet_poscan – Exposes the scan_object extrinsic for 3-D object hashing
• pallet_asset_conversion – Handles asset conversion mechanisms
• pallet_balances – Modified balance management for the native token

These pallets define storage items, extrinsics (transactions), and runtime hooks that execute when blocks are finalized.

EVM Compatibility: precompiles/ and frontier/

The Frontier stack enables Ethereum compatibility, allowing developers to deploy Solidity contracts and use standard Ethereum tooling like MetaMask.

Pre-compiles Directory

The precompiles/ directory exposes native Substrate functionality to EVM contracts at specific addresses:

• precompiles/balances-erc20/src/lib.rs – Maps the native balance pallet to ERC-20 interface at address 0x000…0802
• precompiles/poscan/ – Exposes POS-scan functionality to Solidity contracts

Frontier Implementation

The frontier/ directory contains:

• frontier/rpc-core/ – Ethereum JSON-RPC method definitions
• frontier/rpc/src/eth.rs – Implementation of eth_* RPC methods
• frontier/db/ – Database adapters for Ethereum state storage
• frontier/cli/ – Command-line options for EVM configuration

Consensus Engine: consensus/poscan_grid2d

The consensus/poscan_grid2d/ directory implements the POS-scan algorithm, a grid-based proof-of-work system for 3-D object recognition. The lib.rs file defines the PoscanAlgorithm struct and integrates the randomx hash function for computational proof generation.

This algorithm operates as follows:

1. Receives 3-D object data from the mining pool
2. Applies grid-2D hashing via the PoscanAlgorithm::hash() method
3. Generates PoscanData structures (V1 or V2) containing the computational proof
4. Produces sealed blocks with ComputeV1 or ComputeV2 signatures

The consensus engine connects to the node client through the sc_consensus_poscan interface, which spawns mining workers when the node runs with the --validator flag.

External Mining Tools: miner.js and Infrastructure

Beyond the Rust codebase, the repository includes tooling for distributed mining operations:

JavaScript Miner

The miner.js script provides a Bun-based mining client that connects to the node's RPC interface:

# Install dependencies and launch miner

bun install
bun miner.js --host 127.0.0.1 --port 9933

This client fetches mining proposals from the MiningPool pallet via RPC, computes hashes using the POS-scan algorithm (via WebAssembly), and submits solutions back to the node.

Supporting Directories

• convert/ – Contains scan.mjs and slash.mjs for pre-processing 3-D objects before consensus hashing
• docker/ and docker-compose.yml – Container orchestration for running nodes and miners in production environments

Running a Complete Node

To launch a validator node with mining capabilities:

# Build the release binary

cargo build --release

# Start the node with validator and mining parameters

./target/release/poscan-consensus \
  --base-path ~/3dp-chain/ \
  --chain mainnetSpecRaw.json \
  --name My3DPassNode \
  --validator \
  --author 0x1234…abcd

For development testing, connect to the node via Polkadot-JS Apps by setting the custom endpoint to ws://127.0.0.1:9944 to interact with accounts, balances, and POS-scan extrinsics like poscan.scanObject.

Summary

• The 3DPass node structure follows Substrate conventions with seven specialized directories for consensus, runtime, and tooling.
• nodes/poscan-consensus/ contains the executable entry point at main.rs and service orchestration in service.rs.
• runtime/src/lib.rs defines the WASM runtime using construct_runtime! to assemble all pallets.
• pallets/ houses custom FRAME modules including pallet_poscan, pallet_mining_pool, and pallet_validator_set.
• consensus/poscan_grid2d/ implements the grid-2D POS-scan algorithm with randomx hashing.
• frontier/ and precompiles/ provide full EVM compatibility for Ethereum tooling.
• miner.js enables external mining via RPC connection to the node's mining pool interface.

Frequently Asked Questions

What is the main entry point for the 3DPass node binary?

The main entry point is nodes/poscan-consensus/src/main.rs, which calls command::run() to parse CLI arguments and initialize the node service. This file bootstraps the entire client by constructing the PartialComponents and full service configuration defined in service.rs.

How does the POS-scan consensus algorithm integrate with the Substrate client?

The integration occurs in nodes/poscan-consensus/src/service.rs, where the PowBlockImport wraps the POS-scan algorithm from consensus/poscan_grid2d/src/lib.rs. When running as a validator, the node spawns a mining worker via sc_consensus_poscan::start_mining_worker that pulls proposals from the pallet_mining_pool and computes hashes using the PoscanAlgorithm trait.

Can I run the 3DPass node without compiling the Rust code?

Yes, the repository provides docker-compose.yml configurations for containerized deployment. Additionally, the miner.js JavaScript client allows mining operations without running a full node, requiring only Bun to execute and an RPC connection to an existing node at http://127.0.0.1:9933.

Which directory contains the Ethereum-compatible RPC implementations?

The frontier/rpc/src/eth.rs file implements the standard Ethereum JSON-RPC methods (such as eth_getBalance and eth_sendTransaction), while precompiles/ contains native-to-EVM mappings that allow Solidity contracts to interact with Substrate pallets at specific hard-coded addresses.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}