# Understanding the 3DPass Node Structure: A Complete Directory Guide

> Explore the 3DPass node structure, a Substrate-based architecture with seven key directories. Learn about the POS-scan consensus client, WASM runtime, and custom pallets for Ledger of Things functionality. Understand the code o...

- Repository: [3Dpass/3dp](https://github.com/3dpass/3dp)
- Tags: deep-dive
- Published: 2026-02-23

---

**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`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/nodes/poscan-consensus/src/main.rs), which invokes `command::run()` to parse CLI arguments and initialize the full node service. The [`service.rs`](https://github.com/3dpass/3dp/blob/main/service.rs) file handles the complex orchestration of Substrate components:

```rust
// 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`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/miner.js)** script provides a Bun-based mining client that connects to the node's RPC interface:

```bash

# 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`](https://github.com/3dpass/3dp/blob/main/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:

```bash

# 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`](https://github.com/3dpass/3dp/blob/main/main.rs) and service orchestration in [`service.rs`](https://github.com/3dpass/3dp/blob/main/service.rs).
- **[`runtime/src/lib.rs`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/service.rs).

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

The integration occurs in **[`nodes/poscan-consensus/src/service.rs`](https://github.com/3dpass/3dp/blob/main/nodes/poscan-consensus/src/service.rs)**, where the `PowBlockImport` wraps the POS-scan algorithm from [`consensus/poscan_grid2d/src/lib.rs`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/docker-compose.yml)** configurations for containerized deployment. Additionally, the **[`miner.js`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/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.