# JIP-2: Node RPC 筆記整理

JAM Node 提供 JSON-RPC 接口，供外部工具（如清錢包、block explorer、service 測試套件）查詢鏈上狀態或提交資料。JIP-2 定義了這些 RPC 的型別、命名與行為。

## 🧠 JAM RPC 是什麼？與 Light Client 有什麼關係？

### 📡 RPC 的角色

RPC（Remote Procedure Call）是外部工具與 JAM 節點（Full Node）溝通的橋樑，使用 JSON-RPC 協定，常見用途包括：

- 查詢區塊、狀態、service 的值
- 提交 work package 或 preimage
- 訂閱 finalized block 更新

---

### 👥 誰跟誰溝通？

- **Client（例如錢包、前端工具）** → 發送 RPC 請求
- **Full Node** → 接收請求並回傳資料

[Wallet or dApp] → JSON-RPC → [Full Node] → 回傳區塊 / 狀態

### 🔍 Full Node vs Light Client 簡易比較

| 類型 | 是否驗證資料 | 是否同步整條鏈 | 啟動速度 | 適合用途 |
|--------------|---------------|----------------|-----------|------------------|
| Full Node | ✅ 是 | ✅ 是 | ❌ 較慢 | 節點、驗證者、基礎設施 |
| Light Client | ✅ 是（用 proof）| ❌ 否 | ✅ 快速 | 錢包、前端工具 |

> 例如：Cardano 的 Daedalus（Full Node） vs Yoroi（Light Client）

---

## 📌 為什麼需要 RPC？

- JAM 尚未有 light client 實作
- 全節點資源消耗高，不適合內嵌在前端工具中
- 工具暫時只能透過可信任的 full node 提供資訊
- 一旦有 light client，應逐步棄用 RPC（去中心化原則）

---

## 📡 JIP-2 Node RPC methods

## 🧭 協議說明

- 通訊協定：`JSON-RPC`
- 傳輸協定：`WebSocket`
- 端口：預設為 `19800`
- 方法參數格式：array-style（`params: []`）
- 支援訂閱（subscribe）與資料提交（submit）

---

### 📦 類型定義（Types）

所有參數、回傳值與通知訊息皆透過 **JSON 陣列** 傳遞，部分結果允許為 `null`（會特別標示）。

| 類型 | 說明 |
|-------------|------|
| `Hash` | array size 32，數字介於 0–255（byte） |
| `Slot` | 單一整數值，範圍為 `0` 到 `2³² - 1`（slot 編號） |
| `Blob` | 任意長度的 byte array，每個元素 0–255（原始資料 blob） |
| `ServiceId` | 單一整數值，範圍為 `0` 到 `2³² - 1`（服務 ID） |
| `Parameters`| 目前運作的 Serice 參數設定 |

---
### 🔔 訂閱與通知（subscribe）

- 所有 `subscribeXXX` 類型的 RPC 都可搭配 `unsubscribeXXX` 終止
- 採用標準 JSON-RPC 訂閱方式（細節略）

## 🧾 鏈狀態與參數相關RPC

### `parameters`
- 📌 回傳鏈的設定參數
- Type: `Method`
- Args: 無
- Result: `Parameters` 物件（含 epoch 長度、驗證者數量等）

---

### `bestBlock`
- 📌 查詢當前「最佳鏈頭」的區塊
- Type: `Method`
- Result:
- `Hash`: header hash
- `Slot`: slot 編號

---

### `subscribeBestBlock`
- 📌 訂閱 bestBlock 更新
- Type: `Subscription`
- 回傳內容：
- `Hash`: 最新 header hash
- `Slot`: slot

---

### `finalizedBlock`
- 📌 查詢當前 finalized 區塊
- Type: `Method`
- Result:
- `Hash`, `Slot`

---

### `subscribeFinalizedBlock`
- 📌 訂閱 finalized block 更新
- Type: `Subscription`

---

### `statistics`
- 📌 查詢鏈上統計數據（如出塊速率）
- Type: `Method`
- Result: 統計欄位（依實作）

---

### `subscribeStatistics`
- 📌 訂閱統計數據更新
- Type: `Subscription`

---

## 🧠 區塊相關RPC

### `parent`
- 📌 查某個區塊的 parent hash
- Type: `Method`
- Args: `Hash`
- Result: `Hash`（parent）

---

### `stateRoot`
- 📌 查某區塊的 posterior state root
- Type: `Method`
- Args: `Hash`
- Result: `Hash`

---

## 🧬 Service 資料查詢RPC

### `serviceData`
- 📌 查某 slot 中 service 的資料 blob
- Type: `Method`
- Args: `Slot`, `ServiceId`
- Result: `Blob`

---

### `serviceValue`
- 📌 查某 slot 中 service 某個 key 的值
- Type: `Method`
- Args: `Slot`, `ServiceId`, `Key`
- Result: `Blob`

---

### `servicePreimage`
- 📌 查某 preimage 的值
- Type: `Method`
- Args: `Hash`
- Result: `Blob`

---

### `serviceRequest`
- 📌 查某 preimage request 的資訊
- Type: `Method`
- Args: `Hash`
- Result: 詳細結構（message、service ID 等）

---

## 📬 交易資料提交類RPC

### `submitWorkPackage`
- 📌 提交一個包含 messages 的工作包（類似交易）
- Type: `Method`
- Args: `Blob`（encoded work package）

---

### `submitPreimage`
- 📌 提交一個 preimage blob
- Type: `Method`
- Args: `Blob`（preimage content）

---

## 🏷 Service 管理RPC

### `listServices`
- 📌 回傳目前可見的 service ID 清單
- Type: `Method`
- Result: `ServiceId[]`

---

## 🧮 Chain Parameters（`Parameters` Object）

`Parameters` 是描述 JAM Chain 的運作參數（非一定與 Gray Paper 完全一致），所有欄位皆為數值型別，供節點與 light client 使用。

---

### 📦 Fields 一覽

| 欄位名稱 | 說明 |
|---------------------------|------|
| `deposit_per_account` | 每個帳戶需要支付的基本押金（𝐵𝑆） |
| `deposit_per_item` | 每個帳戶中每筆 preimage 或 storage 的額外押金（𝐵𝐼） |
| `deposit_per_byte` | 每 byte 資料所需額外押金（包含 preimage / storage）（𝐵𝐿） |
| `min_turnaround_period` | 從 Available → Zombie → 消失的最短時間間隔（𝐷） |
| `epoch_period` | 每個 epoch 包含的 slot 數量（𝐸） |
| `max_accumulate_gas` | 單次 Accumulate 可用的最大 gas（𝐺𝐴） |
| `max_is_authorized_gas` | 單次 IsAuthorized 可用的最大 gas（𝐺𝐼） |
| `max_refine_gas` | 單次 Refine 可用的最大 gas（𝐺𝑅） |
| `block_gas_limit` | 每個區塊的最大 gas 限制（𝐺𝑇） |
| `recent_block_count` | recent block cache 保留的區塊數（𝐻） |
| `max_work_items` | 每個 Work Package 中最多的 Work Item 數（𝐼） |
| `max_dependencies` | 最多的 dependency 數（𝐽） |
| `max_tickets_per_block` | 每區塊允許的最大票據數量（𝐾） |
| `max_lookup_anchor_age` | lookup anchor 可接受的最舊區塊年齡（𝐿） |
| `tickets_attempts_number` | 每位驗證者每個 epoch 可嘗試的票據數（𝑁） |
| `auth_window` | 授權視窗的長度（𝑂） |
| `auth_queue_len` | 每個 core 分配到的授權佇列長度（𝑄） |
| `rotation_period` | Key rotation 的 slot 週期（𝑅） |
| `max_extrinsics` | 每個 Work Package 中最多的 extrinsics 數（𝑇） |
| `availability_timeout` | 可取代失效工作的最長等待時間（𝑈） |
| `val_count` | 總驗證者數量（𝑉） |
| `max_input` | Work Package + extrinsics + imported segments 的最大資料量（𝑊𝐵） |
| `max_refine_code_size` | Refine/Accumulate 程式碼最大長度（𝑊𝐶） |
| `basic_piece_len` | 每個 erasure-coded piece 的 byte 數（𝑊𝐸） |
| `max_imports` | 每個 Work Package 中的最大 imports 數（𝑊𝑀） |

---

### 🔍 其他參數（Graypaper 未完全定義，但客戶端可用）

| 欄位名稱 | 說明 |
|---------------------------------|------|
| `max_is_authorized_code_size` | IsAuthorized 程式碼最大長度（𝑊𝐼） |
| `max_exports` | Work Package 中的最大 exports 數（𝑊𝑋） |
| `max_refine_memory` | Refine/Accumulate 可使用的最大記憶體 |
| `max_is_authorized_memory` | IsAuthorized 可使用的最大記憶體 |

---

### 🧠 固定邏輯與推導參數

- `C = V / 3`：每個 core 分配 3 位驗證者
- `WG = 4,104`：每個重建 segment 的固定大小
- `WP = WG / WE`：每個 segment 中的 erasure-coded pieces 數量（WP）

---