Architecture

V1.0 技術架構 · 2025 年 10 月校準版（對應產品 v1.5.0.0）

11.1 專案架構模式 (Project Architecture Pattern)

Soulbound Saga 採用微服務架構模式，將不同功能模組分別部署和管理，實現高度的可擴展性和維護性。

🏗️ 核心組件架構

🎮 DungeonDelvers 生態系統
├── 🌐 前端應用 (SoulboundSaga)
├── 🔗 智能合約層 (DungeonDelversContracts)
├── 📊 數據索引層 (dungeon-delvers-subgraph)
├── 🚀 後端 API (dungeon-delvers-metadata-server)
└── 📚 文檔系統 (dungeon-delvers-whitepaper)

11.2 各子專案詳細說明

🌐 前端應用 - SoulboundSaga

技術棧: React 18 + TypeScript + Vite + wagmi v2 專案位置: /Users/sotadic/Documents/GitHub/SoulboundSaga 部署: Vercel

核心功能:

  • Web3 錢包連接與交互

  • NFT 展示和交易界面

  • 遊戲機制操作 (鑄造、探索、升級)

  • 實時數據展示和統計分析

  • 響應式設計和手機端優化

技術亮點:

// wagmi v2 + WalletConnect v2 多錢包佈局
const config = createConfig({
  chains: [bsc],
  connectors: [
    metaMask({ shimDisconnect: true }),
    walletConnect({
      projectId: import.meta.env.VITE_WALLETCONNECT_PROJECT_ID,
      disableProviderPing: true,
      mobileLinks: ['metamask', 'trust', 'okx'],
    }),
    injected({ shimDisconnect: true }),
  ],
});

const { connectAsync, connectors } = useConnect();
await connectAsync({ connector: connectors.find(c => c.id === 'walletConnect')! });

🔗 智能合約層 - DungeonDelversContracts

技術棧: Solidity + Hardhat + OpenZeppelin 專案位置: /Users/sotadic/Documents/DungeonDelversContracts 網路: BNB Chain (BSC) Mainnet

核心合約:

// NFT 與遊戲模組
Hero.sol             // 英雄 NFT
Relic.sol            // 聖物 NFT
Party.sol            // 隊伍 NFT
PlayerProfile.sol    // 玩家 SBT

// 核心流程
DungeonCore.sol      // 中央協調與權限管理
PlayerVault.sol      // 資金流與推薦
DungeonMaster.sol    // 地城／遠征機制
AltarOfAscension.sol // 升星與素材消耗
VipStaking.sol       // VIP 質押
VRFManager.sol       // Chainlink VRF v2.5

安全特性:

  • Chainlink VRF V2.5 保證隨機公平性

  • 多重簽名和時間鎖機制

  • ReentrancyGuard 防重入攻擊

  • Ownable 權限控制系統

📊 數據索引層 - dungeon-delvers-subgraph

技術棧: The Graph Protocol + GraphQL 專案位置: /Users/sotadic/Documents/GitHub/dungeon-delvers-subgraph 版本: v1.5.0.0

索引核心資料結構:

type Player {
  id: ID!
  heroCount: Int!
  relicCount: Int!
  partyCount: Int!
  referralRelation: ReferralRelation @derivedFrom(field: "user")
  referredUsers: [ReferralRelation!] @derivedFrom(field: "referrer")
}

type Hero {
  id: ID!
  tokenId: BigInt!
  contractAddress: Bytes!
  owner: Player
  rarity: Int
  power: BigInt
  status: String!
  isBurned: Boolean!
  createdAt: BigInt!
  burnedAt: BigInt
}

查詢能力:

  • 實時 NFT / VIP / Vault 事件同步

  • 玩家資產、推薦、抽稅明細

  • 遊戲事件歷史追蹤

  • 排行榜與健康檢查儀表板

🚀 後端 API - dungeon-delvers-metadata-server

技術棧: Node.js + Express.js + ethers.js 專案位置: /Users/sotadic/Documents/dungeon-delvers-metadata-server 版本: v1.5.0.0 部署: Render

API 端點設計:

GET /metadata/:type/:id        # VRF 未完成時回傳 202 + Retry-After
POST /metadata/refresh/:id     # 手動清除緩存並重新抓取
GET  /health                   # 子圖端點、快取、Redis 狀態
GET  /admin/cache-stats        # 緩存命中率與 TTL 觀察

核心特性:

  • 動態 NFT metadata 生成（純子圖資料來源，零 RPC 成本）

  • SVG / JSON 模板化輸出，支援行動裝置與市集快取

  • 多層緩存策略 (記憶體 + CDN) 與事件觸發式刷新

  • 未揭示狀態統一回傳 202 Accepted，避免市集長期快取 404

  • Goldsky / The Graph 優先級切換與健康快照 (/health 回傳 subgraphEndpoints)

  • Helmet、速率限制與 Redis backoff 保護

📚 文檔系統 - dungeon-delvers-whitepaper

技術棧: GitBook + Markdown 專案位置: /Users/sotadic/Documents/GitHub/dungeon-delvers-whitepaper 版本: V1.0 第一代遊戲

文檔結構:

  • 專案概述和遊戲機制

  • 技術架構和智能合約

  • 代幣經濟學和 NFT 系統

  • 開發指南和 API 文檔

11.3 數據流架構 (Data Flow Architecture)

🔄 用戶操作流程

graph TD
    A[用戶錢包] --> B[前端界面]
    B --> C[智能合約]
    C --> D[區塊鏈事件]
    D --> E[子圖索引]
    E --> F[GraphQL API]
    F --> B
    
    C --> G[後端 API]
    G --> H[Metadata 服務]
    H --> B

📡 配置同步系統

# 統一配置管理流程
DungeonDelversContracts/config/deployed-addresses.mainnet.json
├─ scripts/essential/extract-abis.js → SoulboundSaga/src/contracts/abi
│                                     ↳ dungeon-delvers-metadata-server/abis
├─ dungeon-delvers-subgraph/scripts/sync-subgraph-manifest.cjs → subgraph.yaml
└─ metadata-server/config/contracts.json  # 統一配置載入器依此覆寫

11.4 部署和 CI/CD 策略

🚀 部署環境

  • 前端: Vercel (自動部署)

  • 後端: Render (容器化部署)

  • 子圖: The Graph Studio (去中心化索引)

  • 智能合約: BNB Chain (永久部署)

🔄 持續集成流程

# GitHub Actions Workflow
- Code Push → Automated Tests
- Tests Pass → Build & Deploy  
- Deploy Success → Configuration Sync
- Sync Complete → Health Checks

11.5 安全和監控系統

🛡️ 安全措施

  • 智能合約: 多重簽名 + 時間鎖

  • API 服務: CORS + 速率限制 + Helmet 安全頭

  • 數據傳輸: HTTPS + 嚴格 CSP

  • 錢包集成: 官方 MetaMask Connector + WalletConnect v2 + Injected fallback

📊 監控和告警

// 健康檢查端點（例）
{
  "frontend": "https://www.dungeondelvers.xyz/health",
  "backend": "https://dungeon-delvers-metadata-server.onrender.com/health",
  "subgraph": "https://api.goldsky.com/status/dungeon-delvers",
  "contracts": "BscScan 自動化監控 + Discord Webhook"
}

11.6 性能優化策略

⚡ 前端優化

  • 代碼分割: React.lazy + Suspense

  • 圖像優化: WebP + 懶加載

  • 緩存策略: Service Worker + CDN

  • Bundle 分析: Rollup Visualizer

🔧 後端優化

  • API 緩存: 5分鐘內存緩存

  • 數據壓縮: gzip 壓縮傳輸

  • 連接池: 數據庫連接復用

  • 負載均衡: 多實例部署

📈 區塊鏈優化

  • Gas 優化: 批量操作 + 狀態壓縮

  • 事件索引: 高效的 GraphQL 查詢

  • VRF 優化: Direct Funding 模式

  • 交易排隊: 智能 Gas 價格策略

11.7 擴展性設計

🌟 水平擴展能力

  • 微服務架構: 各組件獨立擴展

  • API 網關: 統一入口和負載分散

  • 數據庫分片: 用戶數據水平分割

  • CDN 分發: 全球內容分發網路

🔮 未來技術升級

  • Layer 2 集成: Polygon, Arbitrum 支援

  • 跨鏈橋接: 多鏈資產互操作性

  • AI 增強: 智能遊戲平衡和推薦

  • VR/AR 集成: 沉浸式遊戲體驗

💡 開發者注意: 此架構文檔將依 v1.x 發布節奏滾動調整，所有決策均以使用者體驗與系統穩定性為優先。

最後更新: 2025 年 10 月 12 日 架構版本: V1.5.0.0（Soulbound Saga 第一代） 維護團隊: DungeonDelvers 開發團隊

上一页Roadmap下一页Team

最后更新于