3DPass APIs and RPC Methods: Complete Developer Guide to Runtime and JSON-RPC Interfaces

3DPass exposes both Substrate runtime APIs and JSON-RPC endpoints, including standard Ethereum-compatible methods via Frontier and custom PoSCAN consensus APIs for object retrieval, mining, and pool management.

The 3DPass blockchain (repository 3dpass/3dp) provides a layered interface for external applications, combining standard Ethereum JSON-RPC compatibility with specialized PoSCAN (Proof of Scan) consensus APIs. Whether you are building a wallet, a mining client, or an object verification tool, understanding the available 3DPass APIs and RPC methods is essential for integration. The architecture separates low-level runtime APIs defined in runtime/src/lib.rs from the public JSON-RPC surface exposed through the node’s RPC builder.

Runtime APIs: The Internal Interface

Runtime APIs are Rust traits implemented in the runtime that expose core blockchain state to the node. These are defined in runtime/src/lib.rs and provide the foundation for all JSON-RPC methods.

Ethereum-Compatible Runtime APIs

According to the 3DPass source code, the runtime implements Frontier’s Ethereum compatibility layer through fp_rpc:

• fp_rpc::EthereumRuntimeRPCApi<Block> – Exposes Ethereum state queries including chain_id(), account_basic(), gas_price(), storage_at(), call(), and create(). Located at lines 38‑81.
• fp_rpc::ConvertTransactionRuntimeApi<Block> – Converts EthereumTransaction into native Substrate extrinsics. Located at lines 81‑87.

Substrate Core Runtime APIs

The runtime includes standard Substrate pallets exposing runtime APIs for account and transaction management:

• frame_system_rpc_runtime_api::AccountNonceApi<Block, AccountId, Index> – Returns account nonces via account_nonce(). Defined at lines 32‑36.
• pallet_transaction_payment_rpc_runtime_api::TransactionPaymentApi<Block, Balance> – Provides fee estimation through query_info() and query_fee_details(). Defined at lines 89‑100.
• pallet_contracts_rpc::ContractsRuntimeApi – Enables WASM smart contract queries including call() and estimate_gas().
• substrate_frame_rpc_system::SystemApi – General system queries for health checks and chain properties.
• sc_finality_grandpa_rpc::GrandpaApi – Finality gadget queries for block finalization proofs.

PoSCAN Consensus Runtime APIs

3DPass extends the runtime with domain-specific APIs for the PoSCAN consensus mechanism:

• PoscanApi – Object retrieval and proof-of-existence queries.
• MiningPoolApi – Pool status and reward distribution data.

These custom APIs are defined in sp-consensus-poscan crates and bound to the RPC layer through the node’s service configuration.

JSON-RPC Endpoints: The Public Interface

The public JSON-RPC surface is assembled in nodes/poscan-consensus/src/rpc.rs inside the create_full function (approximately lines 190‑260). This function merges individual RPC modules into a single jsonrpsee::RpcModule.

Standard Ethereum RPC (Frontier)

Via fc_rpc, 3DPass exposes standard Ethereum JSON-RPC methods:

• eth_* – eth_call, eth_sendRawTransaction, eth_getBalance, eth_getBlockByNumber
• net_* – net_version, net_peerCount
• web3_* – web3_clientVersion, web3_sha3

These methods delegate to the EthereumRuntimeRPCApi and allow existing Ethereum tools like MetaMask to interact with 3DPass without modification.

Substrate System and Payment RPC

Core Substrate functionality is exposed through:

• system_accountNonce – Query account transaction sequence number.
• system_health – Node connectivity status.
• system_properties – Chain-specific properties (token decimals, SS58 prefix).
• payment_queryInfo – Calculate transaction fees via TransactionPaymentApi.
• payment_queryFeeDetails – Detailed fee breakdown including base and adjusted fees.
• grandpa_proveFinality – Generate finality proofs for light clients.

PoSCAN-Specific RPC Methods

The PoscanRpc module in nodes/poscan-consensus/src/poscan_rpc.rs implements consensus-specific queries:

• poscan_getPoscanObject – Retrieve a stored object by its index.
• poscan_getReplicasOf – List replica objects associated with a parent object.
• poscan_getUnspentRewards – Query available mining rewards for an account.
• poscan_getFeePayer – Identify the fee payer for a specific operation.
• poscan_getObjectIdxByProofOfExistence – Look up object indices using their proof-of-existence hash.

Mining and Pool RPC

For mining operations, 3DPass provides specialized endpoints:

Mining RPC (nodes/poscan-consensus/src/mining_rpc.rs):

• poscan_pushMiningObject – Push a mining object into the node’s in-memory queue (requires obj_id and base64-encoded object data).
• posscan_getMiningObject – Retrieve the current mining object from the block digest.

Pool RPC (nodes/poscan-consensus/src/pool_rpc.rs):

• poscan_getMiningParams – Query PoSCAN pool configuration parameters.
• poscan_pushMiningObjectToPool – Submit a signed mining object to a specific mining pool (requires payload, member ID, and signature).

Development RPC

The node also exposes development helpers via the Dev module:

• dev_generateBlock – Manually trigger block production for testing.

How Runtime APIs Connect to JSON-RPC

The architecture follows a delegation pattern:

1. Runtime Definition – Runtime APIs are declared as Rust traits in runtime/src/lib.rs using impl_runtime_apis! macros.
2. RPC Construction – The create_full function in nodes/poscan-consensus/src/rpc.rs instantiates RPC handlers and merges them into a single module using module.merge(...).
3. Client Delegation – Each RPC implementation calls client.runtime_api() to invoke the corresponding runtime function.
4. Server Exposure – In nodes/poscan-consensus/src/main.rs, the assembled RPC module is attached to the Substrate RPC server, listening on HTTP (port 9933) and WebSocket (port 9944).

Thus, when you call poscan_getPoscanObject, the RPC handler in poscan_rpc.rs delegates to the PoscanApi runtime trait, which executes the query against the runtime state.

Calling 3DPass RPC Methods: Code Examples

The following examples demonstrate how to interact with 3DPass using standard HTTP JSON-RPC calls. These work against a local node running with default ports (HTTP: 9933, WebSocket: 9944).

Query Ethereum Chain ID

curl -X POST http://127.0.0.1:9933 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'

Retrieve a PoSCAN Object by Index

curl -X POST http://127.0.0.1:9933 \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc":"2.0",
        "method":"poscan_getPoscanObject",
        "params":[42],
        "id":1
      }'

Submit a Mining Object to the Queue

curl -X POST http://127.0.0.1:9933 \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc":"2.0",
        "method":"poscan_pushMiningObject",
        "params":[123, "eyJvYmplY3QiOi..."],
        "id":1
      }'

Submit a Signed Mining Object to a Pool

curl -X POST http://127.0.0.1:9933 \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc":"2.0",
        "method":"poscan_pushMiningObjectToPool",
        "params":[
          "0xdeadbeef...",
          "0x1234abcd...",
          "0x5f8b2c1d..."
        ],
        "id":1
      }'

Calculate Transaction Fees

curl -X POST http://127.0.0.1:9933 \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc":"2.0",
        "method":"payment_queryInfo",
        "params":["0x...", 1024],
        "id":1
      }'

Summary

• 3DPass APIs and RPC methods are defined in two layers: internal runtime APIs (runtime/src/lib.rs) and public JSON-RPC endpoints (nodes/poscan-consensus/src/rpc.rs).
• Ethereum compatibility is provided via fp_rpc traits, exposing standard eth_*, net_*, and web3_* methods through Frontier.
• PoSCAN-specific functionality includes object retrieval (poscan_getPoscanObject), mining queue management (poscan_pushMiningObject), and pool operations (poscan_pushMiningObjectToPool).
• The RPC builder in nodes/poscan-consensus/src/rpc.rs assembles all modules in the create_full function, registering handlers for Ethereum, System, Contracts, Grandpa, and custom PoSCAN methods.
• All RPC methods delegate to runtime APIs via the Substrate client, ensuring consistent state access across HTTP and WebSocket interfaces.

Frequently Asked Questions

What is the difference between runtime APIs and JSON-RPC methods in 3DPass?

Runtime APIs are Rust traits defined in runtime/src/lib.rs that expose blockchain state to the node itself, while JSON-RPC methods are the public HTTP/WebSocket interface defined in nodes/poscan-consensus/src/rpc.rs. The RPC layer acts as a bridge, converting external JSON calls into runtime API invocations via client.runtime_api().

How do I access Ethereum-compatible methods on 3DPass?

3DPass implements the Frontier framework, exposing standard Ethereum JSON-RPC methods like eth_chainId, eth_call, and eth_sendRawTransaction. These are registered in the create_full function alongside native Substrate methods, allowing standard Ethereum wallets and libraries to interact with the chain without custom configuration.

What are the custom PoSCAN RPC methods used for?

PoSCAN-specific methods handle object-based consensus operations unique to 3DPass. poscan_getPoscanObject retrieves stored 3D objects, poscan_pushMiningObject submits objects for mining validation, and poscan_pushMiningObjectToPool enables collaborative mining through the pool system. These methods are implemented in poscan_rpc.rs, mining_rpc.rs, and pool_rpc.rs respectively.

Which file handles the RPC module registration in 3DPass?

The create_full function in nodes/poscan-consensus/src/rpc.rs (lines 190‑260) handles registration. It creates a jsonrpsee::RpcModule and merges all individual RPC extensions including Eth, PoscanRpc, MiningRpc, and MiningPoolRpc into the final module exposed by the node server.

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