Skip to content
Creditcoin Documentation
Global documentation search

RPC Guide

Prerequisites

Section titled “Prerequisites ”

Ensure Docker is installed (or install it in your OS of choice) and run the gluwa/creditcoin3 Docker image.

Using Docker to run a Mainnet RPC

Section titled “Using Docker to run a Mainnet RPC”
Terminal window
docker run \
  --name creditcoin-rpc \
  -p 30333:30333 \
  -p 9944:9944 \
  -p 9615:9615 \
  -v /path/to/your/data:/creditcoin-node/data \
  gluwa/creditcoin3:3.128.0-mainnet \
  --name "rpc name" \
  --prometheus-external \
  --telemetry-url "wss://telemetry.polkadot.io/submit/ 0" \
  --public-addr "/dns4/<host_ip>/tcp/30333" \
  --chain /mainnetSpecRaw.json \
  --bootnodes "/dns4/cc3-bootnode.creditcoin.network/tcp/30333/p2p/12D3KooWLGyvbdQ3wTGjRAEueFsDnstZnV8fN3iyPTmHeyswSPGy" \
  --pruning archive \
  --base-path /creditcoin-node/data \
  --port 30333 \
  --rpc-external \
  --rpc-cors all \
  --rpc-max-connections 1024

Configuration Notes

Section titled “Configuration Notes”
  • Port 30333: Node-to-node P2P communications port
  • Port 9944: JSON-RPC/WebSocket endpoint for blockchain interaction.
  • Port 9615: Prometheus metrics endpoint (optional)
  • -v (volume mount): Maps host directory to container path. Replace /path/to/your/data with your actual data directory path. It’s important that docker has the ability to write to this directory, otherwise you will see errors such as Error: Service(Client(Backend("IO Error: Permission denied (os error 13)"))).
  • –name: Custom name for your RPC node
  • –prometheus-external: Enable Prometheus metrics (optional)
  • –telemetry-url: Opt in to telemetry reporting (optional)
  • –public-addr: Replace <host_ip> with your actual public IP or hostname
  • –chain: Connect to mainnet using the spec file (use testnet for testnet)
  • –pruning archive: Keep full chain history
  • –base-path: Directory inside container to store node data
  • –rpc-external: Allow RPC connections from external sources
  • –rpc-cors all: Allow all CORS origins
  • –rpc-max-connections: Maximum concurrent RPC connections

Additional Flags

Section titled “Additional Flags”
  • –rpc-max-request-size: Maximum RPC request payload size in MB for HTTP and WS (default: 15)
  • –rpc-max-response-size: Maximum RPC response payload size in MB for HTTP and WS (default: 15)
  • –rpc-max-batch-request-len: Maximum number of requests per RPC batch
  • –rpc-disable-batch-requests: Disable RPC batch requests (recommended for private nodes)
  • –max-past-logs: Maximum number of logs in a query (default: 10000, effectively limited by 10s query timeout)

Using Docker to run a Testnet RPC

Section titled “Using Docker to run a Testnet RPC”
Terminal window
docker run \
  --name creditcoin-rpc \
  -p 30333:30333 \
  -p 9944:9944 \
  -p 9615:9615 \
  -v /path/to/your/data:/creditcoin-node/data \
  gluwa/creditcoin3:3.131.0-testnet \
  --name "rpc name" \
  --prometheus-external \
  --telemetry-url "wss://telemetry.polkadot.io/submit/ 0" \
  --public-addr "/dns4/<host_ip>/tcp/30333" \
  --chain testnet \
  --bootnodes "/dns4/cc3-test-bootnode.creditcoin.network/tcp/30333/p2p/12D3KooWAxmsWr6iEjFyLqQBzfLvbCRTAhYBeszyr8UWgQx6Zu7K" \
  --pruning archive \
  --base-path /creditcoin-node/data \
  --port 30333 \
  --rpc-external \
  --rpc-cors all \
  --rpc-max-connections 1024

Configuration Notes

  • Port 30333: Node-to-node P2P communications port
  • Port 9944: JSON-RPC/WebSocket endpoint for blockchain interaction.
  • Port 9615: Prometheus metrics endpoint (optional)
  • -v (volume mount): Maps host directory to container path. Replace /path/to/your/data with your actual data directory path. It’s important that docker has the ability to write to this directory, otherwise you will see errors such as Error: Service(Client(Backend("IO Error: Permission denied (os error 13)"))).
  • –name: Custom name for your RPC node
  • –prometheus-external: Enable Prometheus metrics (optional)
  • –telemetry-url: Opt in to telemetry reporting (optional)
  • –public-addr: Replace <host_ip> with your actual public IP or hostname
  • –chain: Connect to mainnet using the spec file (use testnet for testnet)
  • –pruning archive: Keep full chain history
  • –base-path: Directory inside container to store node data
  • –rpc-external: Allow RPC connections from external sources
  • –rpc-cors all: Allow all CORS origins
  • –rpc-max-connections: Maximum concurrent RPC connections

EVM Tracing

Section titled “EVM Tracing”

EVM tracing allows you to replay transactions and inspect internal calls, opcode execution, memory/stack/storage changes, and gas usage. On Frontier-based Substrate nodes, enabling tracing adds significant CPU and I/O overhead because the node re-executes transactions to produce the trace. Do not enable tracing on validators or high-throughput public RPCs. Prefer a dedicated tracing node.

How to enable EVM tracing

Section titled “How to enable EVM tracing”

Add the debug , trace and txpool RPC namespaces to the ethapi flag on a node running in archive mode:

--ethapi=debug,trace,txpool

What you get with tracing enabled

Section titled “What you get with tracing enabled”
Parameter Description
--ethapi=debug Exposes Geth debug RPCs like debug_traceTransaction, debug_traceBlockByNumber, debug_traceBlockByHash, and debug_traceCall. Use these to replay/inspect execution, internal calls, and gas usage
--ethapi=trace Exposes OpenEthereum trace RPCs, such as trace_filter for historical execution traces across blocks and transactions. Helpful for indexers and deep forensics
--ethapi=txpool Exposes transaction pool RPCs: txpool_content, txpool_inspect, txpool_status to view pending/queued transactions seen by your node

Performance considerations & best practices

Section titled “Performance considerations & best practices”

It is important to note that enabling tracing for EVM transactions significantly increases resource usage. Below are some details and best practices if you decide to enable EVM tracing on your nodes

  • Use a dedicated node: Run tracing on a separate full/archive node and point your tooling at that endpoint. Avoid enabling tracing on validators or busy public RPCs.
  • Archive pruning: Keep --pruning archive so that historical traces can be retrieved reliably.
  • Expect higher resource usage: Tracing replays execution and is CPU/IO intensive. Whole-block traces are particularly heavy.
  • Scope your traces: When calling debug_traceTransaction/debug_traceCall, consider disabling unneeded data (disableStorage, disableMemory, disableStack) to reduce payload size and processing time.
  • Access control: If exposing publicly, consider IP filtering, auth proxying, or rate limiting in front of your tracing RPC to protect node resources.

If you only need a standard RPC endpoint, use the basic guide above. Enable the tracing parameters only when you specifically need low-level EVM execution details.

Terminal window
docker run \
--name creditcoin-tracing \
-p 30333:30333 \
-p 9944:9944 \
-p 9615:9615 \
-v /path/to/your/data:/creditcoin-node/data \
gluwa/creditcoin3:3.66.0-mainnet \
--name "tracing rpc" \
--public-addr "/dns4/<host_ip>/tcp/30333" \
--chain /mainnetSpecRaw.json \
--bootnodes "/dns4/cc3-bootnode.creditcoin.network/tcp/30333/p2p/12D3KooWLGyvbdQ3wTGjRAEueFsDnstZnV8fN3iyPTmHeyswSPGy" \
--pruning archive \
--base-path /creditcoin-node/data \
--port 30333 \
--rpc-external \
--rpc-cors all \
--rpc-max-connections 1024 \
--prometheus-external \
--telemetry-url "wss://telemetry.polkadot.io/submit/ 0" \
--ethapi=debug,trace,txpool