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