bea1903ac9
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Co-authored-by: Cursor <cursoragent@cursor.com>
148 lines
6.1 KiB
Markdown
148 lines
6.1 KiB
Markdown
# Fireblocks Web3 Integration — Chain 138
|
||
|
||
**Last Updated:** 2026-02-21
|
||
**Status:** Active
|
||
**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:** Already added by `scripts/nginx-proxy-manager/update-npmplus-proxy-hosts-api.sh` (run via SSH to r630-01). To re-run: `REMOTE_SSH_USER=root bash scripts/run-via-proxmox-ssh.sh npmplus --host 192.168.11.11` (or run the script from a host on LAN with `NPM_PASSWORD` in `.env`).
|
||
2. **SSL:** In NPMplus UI (https://192.168.11.167:81), open each proxy host for `rpc-fireblocks.d-bis.org` and `ws.rpc-fireblocks.d-bis.org`, then request **SSL Certificate** (Let's Encrypt) and enable **Force SSL** so HTTPS/WSS work.
|
||
3. **DNS:** Add A records (or CNAME if using tunnel) for:
|
||
- `rpc-fireblocks.d-bis.org` → your edge IP (e.g. `76.53.10.36`) or tunnel.
|
||
- `ws.rpc-fireblocks.d-bis.org` → same.
|
||
2. **NPMplus:** Add two Proxy Hosts:
|
||
- Domain: `rpc-fireblocks.d-bis.org`, scheme **http**, forward to `192.168.11.232:8545`, enable **WebSocket Support**.
|
||
- Domain: `ws.rpc-fireblocks.d-bis.org`, scheme **http**, forward to `192.168.11.232:8546`, enable **WebSocket Support**.
|
||
3. **SSL:** Use NPMplus SSL (e.g. Let’s Encrypt) for both.
|
||
4. **Firewall:** Ensure NPMplus host can reach `192.168.11.232` on 8545 and 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
|