proxmox/docs/04-configuration/FIREBLOCKS_WEB3_INTEGRATION.md

# Fireblocks Web3 Integration — Chain 138

**Last Updated:** 2026-02-21  
**Status:** Active ✅ (DNS + SSL + NPMplus complete)  
**RPC Node:** VMID 2301 (192.168.11.232) — dedicated for Fireblocks

---

## Overview

One RPC node is **dedicated for Fireblocks** Web3 integrations: VMID **2301** (`besu-rpc-private-1`, IP **192.168.11.232**). Use it for Fireblocks Console custom network, API, and SDK so Fireblocks traffic is isolated from public and other tenant RPCs.

**Canonical URLs (source: [RPC_ENDPOINTS_MASTER.md](RPC_ENDPOINTS_MASTER.md)):**

| Use | URL |
|-----|-----|
| **HTTP RPC (public)** | `https://rpc-fireblocks.d-bis.org` |
| **WebSocket RPC (public)** | `wss://ws.rpc-fireblocks.d-bis.org` |
| **HTTP RPC (LAN)** | `http://192.168.11.232:8545` |
| **WebSocket RPC (LAN)** | `ws://192.168.11.232:8546` |

**Env vars** (from `config/ip-addresses.conf`):

- `RPC_URL_138_FIREBLOCKS` = `http://192.168.11.232:8545`
- `WS_URL_138_FIREBLOCKS` = `ws://192.168.11.232:8546`

---

## 1. Fireblocks Console — Add Chain 138 (Custom Network)

1. In **Fireblocks Console** go to **Settings → Network Connections → Web3** (or **API** → custom networks).
2. **Add custom network** (or “Add chain” / “Custom RPC” depending on UI).
3. Use:
   - **Network name:** e.g. `Chain 138` or `D-BIS 138`
   - **RPC URL:** `https://rpc-fireblocks.d-bis.org`
   - **Chain ID:** `138`
   - **WebSocket URL (optional):** `wss://ws.rpc-fireblocks.d-bis.org`
4. Save. Fireblocks will use this RPC for Chain 138 for API and (where supported) Web3 provider.

---

## 2. Fireblocks Web3 Provider (SDK) — Custom RPC

Use the dedicated RPC URL when instantiating the Fireblocks Web3 provider so all Chain 138 traffic goes to the Fireblocks-dedicated node.

**Example (Node.js / ethers):**

```js
import { FireblocksWeb3Provider } from "@fireblocks/fireblocks-web3-provider";

const eip1193Provider = new FireblocksWeb3Provider({
  privateKey: process.env.FIREBLOCKS_API_PRIVATE_KEY_PATH,
  apiKey: process.env.FIREBLOCKS_API_KEY,
  vaultAccountIds: process.env.FIREBLOCKS_VAULT_ACCOUNT_IDS,
  rpcUrl: "https://rpc-fireblocks.d-bis.org",  // Chain 138 dedicated
});
// Chain ID is inferred from RPC (138). Use with ethers.js / web3.js.
```

**Environment variable (recommended):**

```bash
# .env
RPC_URL_138_FIREBLOCKS=https://rpc-fireblocks.d-bis.org
WS_URL_138_FIREBLOCKS=wss://ws.rpc-fireblocks.d-bis.org
```

Then in code:

```js
rpcUrl: process.env.RPC_URL_138_FIREBLOCKS || "https://rpc-fireblocks.d-bis.org"
```

---

## 3. Fireblocks REST API — Custom Chain

For **Create Transaction** and other REST calls that require a chain/network, use Chain ID **138** and ensure the Fireblocks backend is configured to use the custom RPC for 138 (via Console custom network above). No extra code change is needed once the custom network is set in the Console.

---

## 4. Hosting and NPMplus (Operator)

The Fireblocks-dedicated RPC is exposed via NPMplus (VMID 10233) with WebSocket support:

| NPMplus Proxy Host | Forward To | WebSocket |
|--------------------|------------|-----------|
| `rpc-fireblocks.d-bis.org` | `http://192.168.11.232:8545` | Yes |
| `ws.rpc-fireblocks.d-bis.org` | `http://192.168.11.232:8546` | Yes |

**Operator steps:**

1. **NPMplus proxy hosts:** ✅ Added by `update-npmplus-proxy-hosts-api.sh`. To re-run: `bash scripts/run-via-proxmox-ssh.sh npmplus --host 192.168.11.11` (from a host with SSH to r630-01 and `NPM_PASSWORD` in `.env`).
2. **SSL:** ✅ Let's Encrypt requested and assigned for both `rpc-fireblocks.d-bis.org` and `ws.rpc-fireblocks.d-bis.org` via `CERT_DOMAINS_FILTER=rpc-fireblocks bash scripts/request-npmplus-certificates.sh` (run from LAN or via SSH to r630-01).
3. **DNS:** ✅ A records created in Cloudflare for `rpc-fireblocks.d-bis.org` and `ws.rpc-fireblocks.d-bis.org` → `76.53.10.36` via `scripts/verify/add-missing-cloudflare-a-records.sh`.
4. **Firewall:** NPMplus (192.168.11.167) can reach `192.168.11.232` on 8545/8546 (same LAN).

See [RPC_ENDPOINTS_MASTER.md](RPC_ENDPOINTS_MASTER.md) for the full NPMplus list and [05-network/RPC_NODE_TYPES_ARCHITECTURE.md](../05-network/RPC_NODE_TYPES_ARCHITECTURE.md) for RPC node types.

---

## 5. Verify RPC and Chain ID

From LAN or a host that can reach the node:

```bash
# HTTP
curl -s -X POST https://rpc-fireblocks.d-bis.org \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
# Expected: {"jsonrpc":"2.0","id":1,"result":"0x8a"}

# Block number
curl -s -X POST https://rpc-fireblocks.d-bis.org \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
```

From project root (using config):

```bash
source config/ip-addresses.conf
curl -s -X POST "$RPC_URL_138_FIREBLOCKS" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
```

---

## 6. Optional: IP Allowlisting (Fireblocks → Your RPC)

If you use **Fireblocks Network Link / Provider Connectivity** and need to allowlist Fireblocks egress IPs, restrict access to the **Fireblocks-dedicated** node (2301) only, not the public RPC. Fireblocks publishes fixed egress IPs by region; see [Fireblocks Network Link Integration](https://developers.fireblocks.com/docs/network-link-integration-guide-for-provider-connectivity). For standard Web3 Provider + custom RPC, allowlisting is usually not required.

---

## Related Docs

- [RPC_ENDPOINTS_MASTER.md](RPC_ENDPOINTS_MASTER.md) — All RPC URLs and NPMplus
- [RPC_NODE_TYPES_ARCHITECTURE.md](../05-network/RPC_NODE_TYPES_ARCHITECTURE.md) — Type 3 Fireblocks node
- [Fireblocks Web3 Provider](https://www.npmjs.com/package/@fireblocks/fireblocks-web3-provider) — npm
- [Fireblocks Create Web3 Connection](https://developers.fireblocks.com/reference/create) — API