> For the complete documentation index, see [llms.txt](https://docs.bearnetwork.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bearnetwork.net/developers/bear-network-chain-sdk.md).

# Bear Network Chain SDK

## BearNetworkChain SDK (bnessdk)

`bnessdk` 是 BearNetworkChain (BNC) 的官方轉接套件，其核心功能是作為開發者 DApp 與 BNC 物理引擎之間的資料封裝橋樑。本 SDK 旨在確保交易在進入引擎前，已完成符合規格的**詞法規範化 (Normalization)** 與 **證據耦合 (Evidence Coupling)**。

### 核心職責與邊界

開發者在使用本 SDK 時應明確以下職責邊界：

* **介面層**：提供與 Web3 生態相容的 JSON-RPC 轉譯，隱藏底層複雜的物理投影邏輯。
* **證據層**：自動為交易附加 PQC (後量子密碼學) 簽章與 ZK 物理守恆提交。
* **不干涉原則**：SDK 不會過濾或攔截流量，其唯一的職責是「誠實標記」。若開發者傳送不合規交易，SDK 會將其標記為低權重態，交由引擎執行物理脫鉤。

### 快速開始

#### 1. 啟動 RPC 門戶 (JSONRPCFacade)

這是與狐狸錢包 (MetaMask) 或 `ethers.js` 對接的最直接方式。

```go
import (
    "bnessdk/sdk/rpc"
    "bnessdk/core_binding"
    "bnessdk/srsg"
)

func main() {
    // 1. 準備外部相應組件
    signer := corebinding.NewRealPQCSigner(myKey)
    engine := srsg.NewPhysicalEngine() 

    // 2. 初始化門戶
    facade := rpc.NewJSONRPCFacade(chainId, signer, engine, observer)

    // 3. 啟動 HTTP 服務
    http.ListenAndServe(":8545", facade)
}
```

#### 2. 開發者義務：正確使用交易類型

根據 BNES v1.3 規格，欲獲得全量物理權重，交易必須採取 **`0x7F`** 擴展類型：

* **Type 0x7F**: 具備 PQC 簽章，SDK 會自動執行量子隧道對齊。
* **Legacy Type**: SDK 會將其標記為 `PoliceWatchlist`。這將導致該交易在引擎端的權重被擠壓至 $10^{-18}$。

### 技術指標與物理不變量 (Invariants)

本 SDK 實施以下工程硬化，確保 1,600 萬 TPS 負載下的物理等價性：

1. **硬體自適應對齊 (Binary Determinism)**：內置指令集偵測系統，自動匹配 **AMD64 (AVX2)** 或 **ARM64 (NEON)** 彙編路徑。此機制旨在確保跨平台設備在計算 64-byte 證據時，產出的指紋達成 **二進位級別的絕對一致 \[1]**，消除因 CPU 架構差異導致的狀態分歧。
2. **暴力定價鎖死 (Economic Anchor)**：`eth_gasPrice` 強制回傳為 **`0x7A120` (0.0005 Gwei)**。開發者應知悉此不變量，任何試圖動態協商 Gas Price 的請求將被系統忽略，以穩定物理場能級。
3. **效能靜默 (RF-ZERO)**：核心路徑維持實測 **8 allocs/op** 的超低分配率，徹底規避在大數據量下因 Runtime GC 導致的執行阻尼。
4. **1MB 流量閘門**：RPC 接口強制受限於 1MB 物理報文長度，直接阻斷非法大報文對緩衝區池的滲透。

### 目錄結構引導

* `/sdk/rpc`: JSON-RPC 命令解析與回覆構造邏輯。
* `/srsg/adapter`: 負責將不同鏈（EVM, BSC）的原始數據規範化。
* `/gamma`: 包含用於計算指紋的彙編優化與 SIMD 邏輯。
* `/zk`: 實施物理多項式提交 (Π-Commitment) 的電路層。
* `/witness`: 證據束的驗證與序列化器。

### 授權條款

本項目採用 GNU GPL v3 授權條款。

### 聯繫我們

如果您在使用 SDK 的過程中有任何問題，歡迎通過以下方式聯繫我們：

* **網站**: [Bear Network Official](https://bearnetwork.net/)
* **Email**: <bearnetwork.net@gmail.com>