# RPC Guide

#### Prerequisites <a href="#sync-chain-data" id="sync-chain-data"></a>

Ensure Docker is installed (or [install it in your OS of choice](https://docs.docker.com/engine/install/)) and run the `gluwa/creditcoin3` Docker image.

### Using Docker to run a Mainnet RPC

{% hint style="info" %}
Docker should automatically pull the specified `gluwa/creditcoin3` image. If not, you can try pulling it yourself from DockerHub by running `docker pull gluwa/creditcoin3:3.64.0-mainnet` and then re-running the command below.
{% endhint %}

{% tabs %}
{% tab title="Bash" %}

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

```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
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.66.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

```

{% endtab %}
{% endtabs %}

#### **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

* **--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

{% hint style="info" %}
Docker should automatically pull the specified `gluwa/creditcoin3` image. If not, you can try pulling it yourself from DockerHub by running `docker pull gluwa/creditcoin3:3.121.0-testnet` and then re-running the command below.
{% endhint %}

{% tabs %}
{% tab title="Bash" %}

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

```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
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.121.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

```

{% endtab %}
{% endtabs %}

**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

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**

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**

| 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**

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.<br>

{% tabs %}
{% tab title="Bash" %}

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

{% endtab %}

{% tab title="Powershell" %}

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

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.creditcoin.org/rpc-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.