> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# TRON Streams

> TRON 網路的 Protobuf 資料流

TRON 約每 3 秒出一個區塊，支援高吞吐的交易和智慧合約執行。TRON 使用獨特的資源模型（Energy 和 Bandwidth）和 Witness（超級代表）共識機制。

**Schema 倉庫**：[github.com/chainstream-io/streaming\_protobuf/tron](https://github.com/chainstream-io/streaming_protobuf/tree/main/tron)

***

## Message Types 總覽

TRON Streams 提供以下訊息型別：

| Message Type      | 說明       | Topic                     |
| :---------------- | :------- | :------------------------ |
| TradeEvents       | DEX 交易事件 | `tron.dex.trades`         |
| TokenEvents       | Token 事件 | `tron.tokens`             |
| BalanceEvents     | 餘額變動事件   | `tron.balances`           |
| DexPoolEvents     | 流動性池事件   | `tron.dex.pools`          |
| TransfersMessage  | 轉賬訊息     | `tron.v1.transfers.proto` |
| CandlestickEvents | K線資料     | `tron.candlesticks`       |

***

## Block-Level Data

### BlockHeader 核心欄位

| 欄位           | 型別        | 說明    |
| :----------- | :-------- | :---- |
| `Number`     | uint64    | 區塊號   |
| `Hash`       | bytes     | 區塊雜湊  |
| `ParentHash` | bytes     | 父區塊雜湊 |
| `Timestamp`  | Timestamp | 出塊時間  |
| `TxTrieRoot` | bytes     | 交易樹根  |
| `Version`    | uint32    | 區塊版本  |

### Witness（超級代表）資訊

| 欄位          | 說明         |
| :---------- | :--------- |
| `Address`   | Witness 地址 |
| `Id`        | Witness ID |
| `Signature` | 區塊簽名       |

<Note>
  TRON 使用 DPoS 共識機制，由 27 個超級代表（Witness）輪流出塊。
</Note>

***

## Transaction-Level Data

### TransactionHeader

| 欄位           | 型別        | 說明    |
| :----------- | :-------- | :---- |
| `Hash`       | bytes     | 交易雜湊  |
| `Fee`        | uint64    | 交易費用  |
| `Index`      | uint32    | 區塊內索引 |
| `Expiration` | Timestamp | 過期時間  |
| `FeeLimit`   | uint64    | 費用上限  |
| `Signatures` | \[]bytes  | 簽名列表  |
| `FeePayer`   | bytes     | 費用支付方 |

### Result — 執行結果

| 欄位        | 說明       |
| :-------- | :------- |
| `Status`  | 執行狀態     |
| `Success` | 是否成功     |
| `Message` | 失敗時的錯誤資訊 |

### Receipt — 資源消耗

| 欄位                 | 說明          |
| :----------------- | :---------- |
| `EnergyUsageTotal` | 總 Energy 消耗 |
| `EnergyFee`        | Energy 費用   |
| `NetUsage`         | 頻寬消耗        |
| `NetFee`           | 頻寬費用        |

### Contract

包含合約執行詳情：

| 欄位                     | 說明                                            |
| :--------------------- | :-------------------------------------------- |
| `Address`              | 合約地址                                          |
| `Type`                 | 合約型別（TransferContract、TriggerSmartContract 等） |
| `Parameters`           | 呼叫引數                                          |
| `InternalTransactions` | 內部交易                                          |
| `Logs`                 | 事件日誌                                          |
| `ExecutionTrace`       | 執行 Trace                                      |
| `WithdrawInfo`         | 獎勵提取資訊                                        |

***

## Transfer Data

`TransfersMessage` 提供 TRON 鏈的轉賬資訊（Topic: `tron.v1.transfers.proto`）。

### TransfersMessage 結構

```protobuf theme={null}
message TransfersMessage {
  Chain Chain = 1;
  BlockHeader Header = 2;
  repeated Transfer Transfers = 3;
}
```

### Transfer 結構

| 欄位                  | 型別                | 說明            |
| :------------------ | :---------------- | :------------ |
| `CallIndex`         | uint64            | 呼叫索引          |
| `LogIndex`          | uint64            | 日誌索引          |
| `Sender`            | string            | 傳送方地址         |
| `Receiver`          | string            | 接收方地址         |
| `Amount`            | string            | 轉賬金額          |
| `Id`                | string            | Token ID（NFT） |
| `URI`               | string            | Token URI     |
| `Currency`          | TokenInfo         | Token 資訊      |
| `Success`           | bool              | 是否成功          |
| `Index`             | uint32            | 轉賬索引          |
| `TransactionHeader` | TransactionHeader | 交易頭資訊         |

### TokenInfo 結構

| 欄位              | 型別     | 說明            |
| :-------------- | :----- | :------------ |
| `SmartContract` | string | 合約地址          |
| `Delegated`     | bool   | 是否委託          |
| `DelegatedTo`   | string | 委託地址          |
| `ProtocolName`  | string | 協議名稱          |
| `Name`          | string | Token 名稱      |
| `Symbol`        | string | Token 符號      |
| `Decimals`      | int32  | 精度            |
| `HasURI`        | bool   | 是否有 URI       |
| `Fungible`      | bool   | 是否同質化         |
| `AssetId`       | string | 資產 ID（TRC-10） |

### TRON Token 標準

| 標準      | 說明                    |
| :------ | :-------------------- |
| TRC-10  | TRON 原生 Token，無需智慧合約  |
| TRC-20  | 智慧合約 Token（類似 ERC-20） |
| TRC-721 | NFT Token（類似 ERC-721） |

<Note>
  TRC-10 是 TRON 獨有的原生 Token 標準，建立和轉賬更便宜，但功能不如 TRC-20 靈活。
</Note>

***

## DEX Data

`TradeEvents` 提供 DEX 交易資料（Topic: `tron.dex.trades`），使用通用的 TradeEvent 結構。

### Trade 核心欄位

| 欄位                                    | 說明          |
| :------------------------------------ | :---------- |
| `token_a_address` / `token_b_address` | 交易對代幣地址     |
| `user_a_amount` / `user_b_amount`     | 使用者交易數量     |
| `pool_address`                        | 池子地址        |
| `vault_a` / `vault_b`                 | 池子 Vault 地址 |
| `vault_a_amount` / `vault_b_amount`   | Vault 數量    |

### DApp 資訊

| 欄位                      | 說明                  |
| :---------------------- | :------------------ |
| `program_address`       | DEX 合約地址（如 SunSwap） |
| `inner_program_address` | 內部程式地址              |
| `chain`                 | 鏈標識（CHAIN\_TRON）    |

### DexPoolEvent - 流動性池

| 欄位                                    | 說明                                                            |
| :------------------------------------ | :------------------------------------------------------------ |
| `type`                                | 事件型別（INITIALIZE/INCREASE\_LIQUIDITY/DECREASE\_LIQUIDITY/SWAP） |
| `address`                             | 池子地址                                                          |
| `token_a_address` / `token_b_address` | 代幣地址                                                          |
| `token_a_amount` / `token_b_amount`   | 代幣數量                                                          |
| `lp_wallet`                           | LP 錢包地址                                                       |

***

## TRON 鏈特性

### Energy 和 Bandwidth 資源模型

不同於 EVM 的 Gas 模型，TRON 使用兩種資源：

| 資源                  | 說明         | 獲取方式       |
| :------------------ | :--------- | :--------- |
| **Energy**          | 計量智慧合約執行消耗 | 質押 TRX 或付費 |
| **Bandwidth (Net)** | 計量交易資料大小消耗 | 質押 TRX 或付費 |

Receipt 中分別體現兩種資源的用量和費用：

```
Receipt {
  EnergyUsageTotal: 50000    // 智能合约消耗
  EnergyFee: 0               // 如有质押则为 0
  NetUsage: 265              // 交易数据大小
  NetFee: 0                  // 如有质押则为 0
}
```

### Witness 系統

| 特性 | 說明            |
| :- | :------------ |
| 名稱 | Witness（超級代表） |
| 數量 | 27 個活躍超級代表    |
| 選舉 | 持幣者投票選舉       |
| 出塊 | 輪流出塊，約 3 秒/塊  |

`BlockMessage` 中包含 Witness 的地址、ID 和簽名。

### 預定義合約型別

TRON 為常見操作預定義了合約型別：

| 型別                          | 說明        |
| :-------------------------- | :-------- |
| `TransferContract`          | TRX 轉賬    |
| `TransferAssetContract`     | TRC-10 轉賬 |
| `TriggerSmartContract`      | 呼叫智慧合約    |
| `CreateSmartContract`       | 建立智慧合約    |
| `FreezeBalanceV2Contract`   | 質押 TRX    |
| `UnfreezeBalanceV2Contract` | 解除質押      |
| `DelegateResourceContract`  | 資源委託      |
| `WithdrawBalanceContract`   | 提取獎勵      |

透過 Contract 的 `Type` 欄位標識。

### 資源委託

使用者可以將 Energy 和 Bandwidth 委託給其他賬戶使用，這在 TRON 生態中常用於：

* 降低使用者交易成本
* DApp 為使用者代付資源

***

## Topic → Message Type 對映表

| Topic                               | Proto File                    | Message Type      | 說明            |
| :---------------------------------- | :---------------------------- | :---------------- | :------------ |
| `tron.dex.trades`                   | trade\_event.proto            | TradeEvents       | DEX 交易事件      |
| `tron.dex.trades.processed`         | trade\_event.proto            | TradeEvents       | 含 USD 價格、可疑標記 |
| `tron.tokens`                       | token\_event.proto            | TokenEvents       | Token 事件      |
| `tron.tokens.processed`             | token\_event.proto            | TokenEvents       | 含描述、圖片、社交連結   |
| `tron.balances`                     | balance\_event.proto          | BalanceEvents     | 餘額變動事件        |
| `tron.v1.transfers.proto`           | tron/transfers\_message.proto | TransfersMessage  | TRON 轉賬訊息     |
| `tron.v1.transfers.processed.proto` | tron/transfers\_message.proto | TransfersMessage  | 處理後的轉賬訊息      |
| `tron.dex.pools`                    | dex\_pool\_event.proto        | DexPoolEvents     | 流動性池事件        |
| `tron.candlesticks`                 | candlestick.proto             | CandlestickEvents | K線資料          |

***

## 程式碼示例

### Python 示例：消費 TRON DEX 交易

```python theme={null}
from kafka import KafkaConsumer
from common import trade_event_pb2  # 从 streaming_protobuf 仓库获取

# 创建 consumer
consumer = KafkaConsumer(
    'tron.dex.trades',
    bootstrap_servers=['<your_broker_address>'],
    security_protocol='SASL_SSL',
    sasl_mechanism='SCRAM-SHA-512',
    sasl_plain_username='your_username',
    sasl_plain_password='your_password',
    auto_offset_reset='latest',
    enable_auto_commit=False,
    group_id='my-tron-consumer'
)

# 消费并解析消息
for message in consumer:
    trade_events = trade_event_pb2.TradeEvents()
    trade_events.ParseFromString(message.value)
    
    for event in trade_events.events:
        print(f"Pool: {event.trade.pool_address}")
        print(f"Token A: {event.trade.token_a_address}")
        print(f"Token B: {event.trade.token_b_address}")
        print(f"Amount A: {event.trade.user_a_amount}")
        print(f"Amount B: {event.trade.user_b_amount}")
        print(f"Block: {event.block.height}")
        print(f"DEX: {event.d_app.program_address}")
        print("---")
```

### 監控 TRC-20 Token 事件

```python theme={null}
from kafka import KafkaConsumer
from common import token_event_pb2

consumer = KafkaConsumer(
    'tron.tokens',
    bootstrap_servers=['<your_broker_address>'],
    security_protocol='SASL_SSL',
    sasl_mechanism='SCRAM-SHA-512',
    sasl_plain_username='your_username',
    sasl_plain_password='your_password',
    auto_offset_reset='latest',
    group_id='my-tron-token-consumer'
)

# USDT on TRON
USDT_ADDRESS = 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t'

for message in consumer:
    token_events = token_event_pb2.TokenEvents()
    token_events.ParseFromString(message.value)
    
    for event in token_events.events:
        # 过滤 USDT 事件
        if event.token.address == USDT_ADDRESS:
            print(f"Event Type: {event.type}")  # CREATED or UPDATED
            print(f"Token: {event.token.symbol}")
            print(f"Name: {event.token.name}")
            print(f"Decimals: {event.token.decimals}")
            print("---")
```

***

## 相關文件

<CardGroup cols={2}>
  <Card title="概念與接入指南" icon="book-open" href="/zh-Hant/docs/access-methods/kafka-streams/overview">
    Kafka Streams 接入基礎
  </Card>

  <Card title="EVM Streams" icon="ethereum" href="/zh-Hant/docs/access-methods/kafka-streams/evm-streams">
    EVM 鏈資料流
  </Card>

  <Card title="Solana Streams" icon="bolt" href="/zh-Hant/docs/access-methods/kafka-streams/solana-streams">
    Solana 高吞吐資料流
  </Card>

  <Card title="WebSocket 實時資料" icon="bolt" href="/zh-Hant/docs/access-methods/websocket">
    WebSocket 接入方式
  </Card>
</CardGroup>