跳至主要内容

協定白皮書：EIP 1.0 規約

蛋蛋插槽協定 (EIP) 是跨界冒險的基石。它不僅定義了數據的長相，更定義了靈魂傳輸的物理定律。

1. 傳輸層編碼標準 (The Encoding Standard)​

為了確保數據能在不同瀏覽器、社群軟體與容器間無損傳遞，EIP 強制規定必須使用 URL-Safe Base64 (RFC 4648) 格式。

A. 編碼規則 (Encoding)​

  1. 標準化: 將 UPS JSON 物件進行穩定排序 (Stable Stringify)。
  2. 二進制轉換: 使用 TextEncoder 將字串轉為 UTF-8 位元組流。
  3. URL-Safe 轉換:
    • 將 + 替換為 -。
    • 將 / 替換為 _。
    • 移除末尾的填充符 =。

B. 解碼容錯 (Decoding Resilience)​

接收端必須具備「防手殘」清理能力，實作流程如下：

2. 序號防禦與重放攻擊 (Anti-Replay Mechanism)​

為了防止玩家利用「舊連結」重複覆蓋新進度（資產複製），EIP 實施 序號單調遞增 (Monotonic Increase) 規則。

  • 規則: incoming.sequenceNumber 必須 嚴格大於 local.sequenceNumber。
  • 異常處理: 若序號小於或等於本地，接收端 必須報錯 並拒絕入駐。

靈魂交接泳道圖 (Handover Swimlane)​

3. 傳輸意圖與數據合併範式 (Merge Paradigm)​

在去中心化系統中，為了避免數據衝突，我們實施 「主體覆蓋，元數據展示」 的合併範式：

  1. 主體數據 (The Core): 包含 dna, progress, status。接收端在驗證成功後，應以 Token 內的內容完全覆蓋本地狀態。
  2. 變動元數據 (Rewards Block): 包含 rewards 區塊。此區塊不應被寫入永久存檔，其存在的唯一目的是供 「結算場景 (Settlement Scene)」 渲染動態效果。

開發者誡律: 嚴禁在接收回歸時再次手動執行 pet.xp += rewards.xp。正確的做法是容器端在撤離前已經將 XP 加入 pet.xp，核心端僅負責「同步」該數值。

5. 狀態欄位衝突與分權 (State Collision Protection)​

在實作容器數據結構時，開發者必須嚴格區分 「環境狀態」 與 「寵物狀態」：

  1. gameState (環境狀態):
    • 定義: 描述寵物當前所處的空間邏輯（如 HOME, EXPEDITION）。
    • 行為: 這是核心容器（家）的私有欄位，決定了 UI 是否顯示墓碑。
  2. status (寵物狀態):
    • 定義: EIP 1.0 標準欄位。內容為一個物件，包含 effects (如中毒) 與 buffs。
    • 衝突警示: 嚴禁將 gameState (字串) 寫入 status 欄位。在數據初始化與合併時，必須顯式處理這兩個屬性，防止物件屬性碰撞導致的資料遺失。

透過這套嚴密的編碼與序號規則，我們確保了去中心化冒險中，蛋蛋的每一分進步都是真實且不可回溯的。

6. 容器資料交互範式 (Data Interaction Patterns)​

為了保護容器免受 EIP 規格演進的衝擊，開發者應採用 「快照與合約」 模式。

A. 靈魂快照範式 (The Soul Snapshot Pattern)​

容器在接收到 UPS 數據後，第一步必須 透過合約（Contract）將其扁平化。

  • 作法: 實作一個 SoulContract.fromUPS() 方法，將深層嵌套的 data.pet.stamina.current 轉化為單層的 snapshot.stamina。
  • 優點: UI 層僅與快照交互。即便未來 EIP 改版，開發者只需修正單一的 Contract 介面，無需大規模重構視圖邏輯。

B. 通訊介面標準化 (Communication Interface Consistency)​

所有跨容器通訊元件（如 P2P Service）必須遵循一致的生命週期管理：

  1. 監聽: on(type, handler) 應回傳一個 unsubscribe 函式。
  2. 清理: 組件卸載時必須執行 unsubscribe() 或 off(type, handler)。
  3. 強健性: 核心 SDK 必須 提供具備高度容錯性的 off 方法，防止開發者因呼叫不存在的清除函式而導致 Runtime Error。