---
# System prepended metadata

title: "\U0001F4E6 JIP-3: Structured Logging Codes based on JAMSNP"
tags: [on-going, Network, JIP]

---

# JAMNP + JIP-3 整合筆記

## 🔐 加密與連線基礎

- 使用 QUIC 作為基礎連線協定，TLS 1.3 進行加密與互認。
- 雙方需提供以 Ed25519 公鑰簽署的 X.509 憑證。
- 使用 ALPN（Application Layer Protocol Negotiation）辨識協定名稱與版本。

---

## 🌿 Protocol Stream 分類

### Unique Persistent（UP）

- 每個 connection 僅允許一個特定 kind 的 stream 存在。
- 長時間存活，如 `Block Announcement`。

### Common Ephemeral（CE）

- 可重複短期開啟，完成請求即關閉。
- 如：state 資料請求、work-report 傳遞等。

---

## 🧩 JAM 協定參與角色整理

JAM 協定中依照 stream 類型與責任明確定義數個角色，彼此藉由 QUIC streams 傳輸資料與任務：

| 角色名稱        | 功能簡述                                       | 常見行為（Stream 協定） |
|------------------|----------------------------------------------|--------------------------|
| **🟣Validator**（驗證人） | 區塊出產、最終化、簽名                         | CE 135, Judgment, Safrole, Preimage |
| **🔨Builder**（構建者）  | 建立 work-package，提交給 Guarantor           | CE 133                  |
| **🧱Guarantor**（擔保人）| 驗證並擔保 work-package，分享與分發           | CE 134, CE 135          |
| **📦Assurer**（保證人） | 提供 segment shard 資料給 Guarantor           | CE 137, 139, 140, 141   |
| **🧐Auditor**（審核人） | 撰寫審查證據，發佈 judgment，協助糾錯         | CE 136, 138, 144, 145   |
| **🌐Node**（通用節點）   | 任意參與者，負責同步區塊與狀態                 | CE 128–129, CE 143      |

> 📌 註：一個節點可能同時扮演多個角色，並依 `epoch` 或區塊上下文動態變化角色。

---
## 📘 JAM 協定常用型別與用途詳解

整理 JAM graypaper 與 `simple.md` 中常見欄位及其型別，並加上用途說明，便於實作與理解各角色行為。

| 名稱（Field）           | 型別（Type）         | 用途與說明 |
|------------------------|----------------------|-------------|
| `Header Hash`          | `[u8; 32]`           | 表示區塊頭的 hash，用於區塊同步、Finality 比對、區塊鏈分支識別。出現在 CE 128（區塊序列請求）、CE 135、審核等。 |
| `Work-Report Hash`     | `[u8; 32]`           | 用於辨識特定 `work-report`。在審核、請求 work-report、判斷正誤（judgment）等多個流程中皆需用此 hash。 |
| `Erasure-Root`         | `[u8; 32]`           | 某個 work-package bundle 的整體 Merkle 根，用於驗證該 bundle 中所有 shard 與 segment。出現在 CE 137～140。 |
| `Segment Shard`        | `[u8; 12]`           | 資料 segment 的一個切片，用於 erasure coding 的重建流程。主要出現在 CE 139/140（Guarantor 向 Assurer 索取 segment）。 |
| `Bundle Shard`         | `Vec<u8>`            | 完整 work-package bundle 的切片，用於重建完整 bundle 或驗證 segment。出現在 CE 138（Audit shard）。 |
| `Slot`                 | `u32`                | 區塊時序單位，代表第幾個 slot，可轉換成 Epoch Index，與共識進度密切相關。常與區塊一同傳遞。 |
| `Epoch Index`          | `u32`                | 表示第幾個 epoch，每個 epoch 包含固定數量的 slots，用於 Safrole lottery、Validator 切換等協定。 |
| `Validator Index`      | `u16`                | 表示某個驗證人在 validator set 中的位置，常用於 judgment、assurance bitmap、傳遞簽名對應。 |
| `Core Index`           | `u16`                | 計算核心（Core）的編號，用於將 work-package 與某條核心綁定，如 CE 133～135、判斷在哪個 core。 |
| `Shard Index`          | `u16`                | 指某個 erasure shard 的編號，在 CE 137～140 中辨識哪些 shard 被請求與分配。 |
| `Segment Index`        | `u16`                | 某個 segment（如 extrinsic segment、proof segment）的序號。出現在 CE 139/140 的 segment 請求。 |
| `Bitfield`             | `[u8; 43]`           | 用於 availability assurance，每個 bit 對應一條 core，Assurer 用來宣告哪些 core 的資料被保證有 shard。出現在 CE 141。 |
| `Key`                  | `[u8; 31]`           | 狀態 trie 的查詢鍵（只取前 31 bytes），用於狀態請求（CE 129）以避免多餘 Merkle 負擔。 |
| `Maximum Size`         | `u32`                | 限制 response 最大資料量（bytes），用於避免傳輸過大 payload，如 CE 129 的狀態資料上限。 |
| `Direction`            | `u8`                 | 區塊查詢方向：0 為從子區塊往下（ascending exclusive）、1 為往上找祖先（descending inclusive），見 CE 128。 |
| `Attempt`              | `u8`                 | Safrole VRF 嘗試次數，最多兩次（0 或 1），用於 ticket 的判定與 proxy 選擇（CE 131/132）。 |
| `RingVRF Proof`        | `[u8; 784]`          | Bandersnatch VRF 的完整證明，用於 Safrole ticket，證明其公平性與不可預測性。 |
| `Ed25519 Signature`    | `[u8; 64]`           | 基本簽名格式，JAM 協定中 Validator 的簽名均使用這種格式，如 Finality, Assurance, Judgment。 |
| `Bandersnatch Signature`| `[u8; 96]`          | 用於審核相關場景，比 Ed25519 更適用於產生 `s_0`, `s_n(w)` 等 audit proof。 |
| `Extrinsic`            | `Vec<u8>`            | Builder 提交的交易資料，在 CE 133 一併送出，讓 Guarantor 能完整組建 work-package。 |
| `Segments-Root`        | `[u8; 32]`           | Work-package 的 segment 集合 Merkle 根，與某筆 work-package 綁定，供 Guarantor 判斷段落正確性。 |
| `Segments-Root Mappings`| `Vec<(WP Hash, Segments-Root)>` | 傳遞 mapping 給其他 Guarantor 進行驗證與 refine 前置準備，見 CE 134。 |

> 📌 備註：
> - 所有 `[u8; N]` 表示固定長度 byte array。
> - 多數 hash 為 `Blake2b` 輸出（32 bytes）。
> - `Vec<u8>` 或 `len++[T]` 表示長度由資料決定的變長陣列。




## 🗂️ 常用 CE Stream 編號對照表（含詳細用途與完整欄位型別）

| Stream ID | 協定用途（詳細說明） | 發起角色 → 接收角色 | 資料格式（含型別） |
|-----------|----------------------|---------------------|---------------------|
| CE 128 | 🔄 **區塊序列請求**：請求某區塊的子孫（ascending）或祖先（descending）區塊，通常用於鏈同步。 | Node → Node | `Header Hash: [u8; 32]`<br>`Direction: u8`<br>`Maximum Blocks: u32` |
| CE 129 | 🧩 **狀態 trie 範圍請求**：回傳指定 key 區間的狀態鍵值對，含部分 Merkle 路徑。 | Node → Node | `Header Hash: [u8; 32]`<br>`Start Key: [u8; 31]`<br>`End Key: [u8; 31]`<br>`Maximum Size: u32` |
| CE 131/132 | 🎟️ **Safrole Ticket 傳遞**：VRF 票據從 Validator 傳給 Proxy（131）或由 Proxy 廣播（132）。 | Validator → Validator | `Epoch Index: u32`<br>`Attempt: u8`<br>`RingVRF Proof: [u8; 784]` |
| CE 133 | 🧱 **提交 work-package**：Builder 建立並送出 WP 與 extrinsic 給 Guarantor。 | Builder → Guarantor | `Core Index: u16`<br>`Work-Package: (variable)`<br>`Extrinsics: Vec<u8>` |
| CE 134 | ♻️ **Guarantor 分享 WP 給同組**：交換 WP bundle 與 segment-root 對應資料。 | Guarantor → Guarantor | `Core Index: u16`<br>`Segments-Root Mappings: Vec<(Work-Package Hash: [u8; 32], Segments-Root: [u8; 32])>`<br>`Work-Package Bundle: (variable)` |
| CE 135 | ✅ **提交 guaranteed work-report**：Guarantor 向 Validator 發送經簽名的 WP 報告。 | Guarantor → Validator | `Work-Report: (variable)`<br>`Slot: u32`<br>`Validator Signatures: Vec<(Validator Index: u16, Signature: [u8; 64])>` |
| CE 136 | 📥 **取得 work-report 本體**：Auditor 請求 report 內容，支援審核。 | Auditor → Auditor | `Work-Report Hash: [u8; 32]` |
| CE 137 | 🧩 **請求分配的 shard**：Guarantor 根據核心與 validator index 索取所屬 shard。 | Guarantor → Assurer | `Erasure-Root: [u8; 32]`<br>`Shard Index: u16` |
| CE 138 | 🕵️ **請求 audit 用 shard**：Auditor 向 Assurer 要求 shard 與 Merkle 證明。 | Auditor → Assurer | `Erasure-Root: [u8; 32]`<br>`Shard Index: u16` |
| CE 139/140 | 🔄 **請求 segment shards**：Guarantor 索取 segment 資料（CE 140 會附上證明）。 | Guarantor → Assurer | `Erasure-Root: [u8; 32]`<br>`Shard Index: u16`<br>`Segment Indexes: Vec<u16>`<br>`(CE 140 only) Justification: variable` |
| CE 141 | 📢 **Assurer 宣告 assurance**：保證哪些 core 的 shard 可用。 | Assurer → Validator | `Header Hash: [u8; 32]`<br>`Bitfield: [u8; 43]`<br>`Signature: [u8; 64]` |
| CE 142 | 📦 **Preimage 宣告**：宣告持有某 preimage 並可供請求。 | Node → Validator | `Service ID: u32`<br>`Hash: [u8; 32]`<br>`Preimage Length: u32` |
| CE 143 | 🔍 **Preimage 請求**：請求對方提供具體 preimage 內容。 | Node → Node | `Hash: [u8; 32]` |
| CE 144 | 📝 **宣告審核 intent**：Auditor 宣告打算審查哪些 WP，附根據。 | Auditor → Auditor | `Header Hash: [u8; 32]`<br>`Tranche: u8`<br>`Announcement: Vec<(Core Index: u16, WP Hash: [u8; 32])>`<br>`Evidence: variable` |
| CE 145 | ⚖️ **發佈 judgment 判定**：Auditor 對某 WP 發佈 valid/invalid 判定。 | Auditor → Validator | `Epoch Index: u32`<br>`Validator Index: u16`<br>`Validity: u8`<br>`WP Hash: [u8; 32]`<br>`Signature: [u8; 64]` |


## 🧾 Code Usage 區段分配表

| 範圍           | 用途說明                                 |
|----------------|------------------------------------------|
| 0–31           | JAM SNP/JAMNP 使用（例如 CE 協定）       |
| 32–63          | 保留給實作者自行定義                     |
| 64–95          | GRANDPA 1.0 + 2.0 Finality 協定          |
| 96–112         | BLS / Beefy 協定                         |
| 113–127        | 保留給 JAM 未來協定                      |
| 128–159        | JAM SNP/JAMNP 擴展使用（CE 協定續用）    |
| 160–191        | 實作者自訂                              |
| 192–223        | GRANDPA 相關協定                         |
| 224–240        | BLS / Beefy 擴展                         |
| 241–255        | 未來 JAM 擴展                            |

### 🧠 具體代碼說明（常見區段）

#### GRANDPA（192–207）
- 192: VoteMessage
- 193: CommitMessage
- 194: NeighborMessage
- 195: Catchup
- 196–207: 保留

#### Syncing（208–223）
- 208: Sync Start
- 209: Sync Finish
- 210: Warp Sync Start
- 211: Warp Sync Finish
- 212–223: 保留

#### BLS / Beefy（224–240）
- 224: BLS Signature Publication
- 225: BLS Aggregate Signature Publication
- 226–240: 保留

> 📌 提示：CE Stream ID 在 0–159 範圍，與 `simple.md` 中定義的 UP / CE 協定完全對應。


## 📡 Distributed Tracing 建議插入點

| 編號 / Stream 範圍    | 追蹤流程說明                             |
|------------------------|------------------------------------------|
| 0                      | Block announcement：應包含 author block 時間 |
| 131/132                | Safrole Ticket：VRF 抽籤產生與傳遞       |
| 133/134/145            | Work-package refinement + auditing       |
| 137/138/139/140        | DA 編碼、Merkle 證明與 Segment 發送       |
| 209/211                | Syncing operations（啟動與結束）         |
| 224/225                | BLS 簽名與聚合簽名                       |

### ✍️ 技術備註
- 可用 4-byte prefix 表示微秒（μs）級耗時。若為 Syncing 操作可用 ms 或 s 單位。
- 建議 telemetry server 將 trace 傳入 Jaeger 等工具，對以下 hash 做可視化：
  - `Work-Package Hash`（CE 133/134/145/137/138/139/140）
  - `Header Hash`（0 / 192 / 193 / 224 / 225）
- 可實現以 Hash 為單位的 trace：例如可觀察某筆 WP refinement 過程或某區塊 finalize 流程。

> ✅ 實作建議：將每個 CE stream 的開頭或結尾插入 trace span 標記（如 WP hash 或 slot），可視覺化出整個 work 流程。


---
參考來源：
- [jam-np simple.md](https://github.com/zdave-parity/jam-np/blob/main/simple.md)
- [JIP-3 HackMD](https://hackmd.io/@sourabhniyogi/jip3-recommendation)
