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

> Explore 3DPass APIs and RPC methods for runtime and JSON-RPC interfaces. Integrate object retrieval mining and pool management with this developer guide.

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

---

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

- **`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`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/runtime/src/lib.rs) using `impl_runtime_apis!` macros.
2. **RPC Construction** – The `create_full` function in [`nodes/poscan-consensus/src/rpc.rs`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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`](https://github.com/3dpass/3dp/blob/main/runtime/src/lib.rs)) and public JSON-RPC endpoints ([`nodes/poscan-consensus/src/rpc.rs`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/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`](https://github.com/3dpass/3dp/blob/main/poscan_rpc.rs), [`mining_rpc.rs`](https://github.com/3dpass/3dp/blob/main/mining_rpc.rs), and [`pool_rpc.rs`](https://github.com/3dpass/3dp/blob/main/pool_rpc.rs) respectively.

### Which file handles the RPC module registration in 3DPass?

The `create_full` function in [`nodes/poscan-consensus/src/rpc.rs`](https://github.com/3dpass/3dp/blob/main/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.