Skip to content

Latest commit

 

History

History
800 lines (667 loc) · 28.3 KB

波场Protobuf协议文档.md

File metadata and controls

800 lines (667 loc) · 28.3 KB

TRON protobuf protocol

TRON使用Google protobuf协议,协议内容涉及到账户,区块,传输多个层面。

  • 账户有基本账户、资产发布账户和合约账户三种类型。一个账户包含:账户名称,账户类型,地址,余额,投票,其他资产6种属性。
  • 更进一步的,基本账户可以申请成为验证节点,验证节点具有额外的属性,投票统计数目,公钥,URL,以及历史表现等参数。

3种Account类型:NormalAssetIssueContract

enum AccountType {
  
  Normal = 0;
  
  AssetIssue = 1;
  
  Contract = 2;

 }

一个Account包含7种参数:
account_name:该账户的名称——比如: ”SicCongsAccount”。
type:该账户的类型——比如: 0 代表的账户类型是Normal
balance:该账户的TRX余额——比如:4213312
votes:账户所得投票数——比如:{(“0x1b7w…9xj3”,323),(“0x8djq…j12m”,88),…,(“0x82nd…mx6i”,10001)}
asset:除TRX以外账户上的其他资产——比如:{<”WishToken”,66666>,<”Dogie”,233>}latest_operation_time: 该账户的最新活跃时间。

// Account

message Account {
  
  message Vote {
    
    bytes vote_address = 1;
    
    int64 vote_count = 2;
  
   }
  
   bytes accout_name = 1;
  
   AccountType type = 2;
  
   bytes address = 3;
  
   int64 balance = 4;
  
   repeated Vote votes = 5;
  
   map<string, int64> asset = 6;

   int64 latest_operation_time = 10;
 }

一个Witness包含8种参数:
address:验证节点的地址——比如:“0xu82h…7237”
voteCount:验证节点所得投票数——比如:234234
pubKey:验证节点的公钥——比如:“0xu82h…7237”
url:验证节点的url链接。
totalProduce:验证节点产生的区块数——比如:2434
totalMissed:验证节点丢失的区块数——比如:7
latestBlockNum:最新的区块高度——比如:4522isJobs:布尔表类型标志位。

// Witness

message Witness {
  
  bytes address = 1;
  
  int64 voteCount = 2;
  
  bytes pubKey = 3;
  
  string url = 4;
  
  int64 totalProduced = 5;
  
  int64 totalMissed = 6;
  
  int64 latestBlockNum = 7;
  bool isJobs = 9;
 
}
  • 一个区块由区块头和多笔交易构成。区块头包含时间戳,交易字典树的根,父哈希,签名等区块基本信息。

一个block包含transactionsblock_header
transactions:区块里的交易信息。
block_header:区块的组成部分之一。

// block

message Block {
  
  repeated Transaction transactions = 1;
  
  BlockHeader block_header = 2;
 
}

BlockHeader 包括raw_datawitness_signature
raw_dataraw信息。
witness_signature:区块头到验证节点的签名。

message raw包含6种参数:
timestamp:该消息体的时间戳——比如:14356325
txTrieRoot:Merkle Tree的根——比如:“7dacsa…3ed”
parentHash:上一个区块的哈希值——比如:“7dacsa…3ed”
number:区块高度——比如:13534657
witness_id:验证节点的id——比如:“0xu82h…7237”
witness_address:验证节点的地址——比如:“0xu82h…7237”

message BlockHeader {
  
  message raw {
    
    int64 timestamp = 1;
    
    bytes txTrieRoot = 2;
    
    bytes parentHash = 3;
   
    //bytes nonce = 5;
   
    //bytes difficulty = 6;
    
    uint64 number = 7;
    
    uint64 witness_id = 8;
    
    bytes witness_address = 9;
  
   }
  
   raw raw_data = 1;
  
   bytes witness_signature = 2;
 
}

消息体 ChainInventory 包括 BlockIdremain_num
BlockId: block的身份信息。
remain_num:在同步过程中,剩余的区块数量。

A BlockId contains 2 parameters:
hash:该区块的哈希值。
number:高度即为当前区块块号。

message ChainInventory {
  message BlockId {
    bytes hash = 1;
    int64 number = 2;
   }
 repeated BlockId ids = 1;
 int64 remain_num = 2;
 }
  • 交易合约有多种类型,包括账户创建合约、账户更新合约、转账合约、转账断言合约、资产投票合约、见证节点投票合约、见证节点创建合约、见证节点更新合约、资产发布合约、参与资产发布和与部署合约11种类型。

AccountCreatContract包含3种参数:
type:账户类型——比如:0 代表的账户类型是Normal
account_name: 账户名称——比如: "SiCongsaccount”
owner_address:合约持有人地址——比如: “0xu82h…7237”

message AccountCreateContract {
  
  AccountType type = 1;
  
  bytes account_name = 2;
  
  bytes owner_address = 3;
 
 }

AccountUpdateContract包含2种参数:
account_name: 账户名称——比如: "SiCongsaccount”
owner_address:合约持有人地址——比如: “0xu82h…7237”

message AccountUpdateContract {
  bytes account_name = 1;
  bytes owner_address = 2;
 }

TransferContract包含3种参数:
amount:TRX数量——比如:12534
to_address: 接收方地址——比如:“0xu82h…7237”
owner_address:合约持有人地址——比如:“0xu82h…7237”

message TransferContract {
  
  bytes owner_address = 1;
  
  bytes to_address = 2;
  
  int64 amount = 3;
 
}

TransferAssetContract包含4种参数:
asset_name:资产名称——比如:”SiCongsaccount”
to_address:接收方地址——比如:“0xu82h…7237”
owner_address:合约持有人地址——比如:“0xu82h…7237”
amount:目标资产数量——比如:12353

message TransferAssetContract {
  
  bytes asset_name = 1;
  
  bytes owner_address = 2;
  
  bytes to_address = 3;
  
  int64 amount = 4;

 }

VoteAssetContract包含4种参数:
vote_address:投票人地址——比如:“0xu82h…7237”
support:投票赞成与否——比如:true
owner_address:合约持有人地址——比如:“0xu82h…7237”
count:投票数目——比如:2324234

message VoteAssetContract {
  
  bytes owner_address = 1;
  
  repeated bytes vote_address = 2;
  
  bool support = 3;
  
  int32 count = 5;
 }

VoteWitnessContract包含4种参数:
vote_address:投票人地址——比如:“0xu82h…7237”
support:投票赞成与否——比如:true
owner_address:合约持有人地址——比如:“0xu82h…7237”
count:投票数目——比如:32632

message VoteWitnessContract {
  
  bytes owner_address = 1;
  
  repeated bytes vote_address = 2;
  
  bool support = 3;
  
  int32 count = 5;

 }

WitnessCreateContract包含3种参数:
private_key:合约的私钥——比如:“0xu82h…7237”
owner_address:合约持有人地址——比如:“0xu82h…7237”
url:合约的url链接。

message WitnessCreateContract {
  
  bytes owner_address = 1;
  
  bytes private_key = 2;
  
  bytes url = 12;
 
}

WitnessUpdateContract包含2种参数:
owner_address:合约持有人地址——比如:“0xu82h…7237”
update_url:合约的url链接。

message WitnessUpdateContract {
  bytes owner_address = 1;
  bytes update_url = 12;
 }

AssetIssueContract包含11种参数:
name:合约名称——比如:“SiCongcontract”
total_supply:合约的赞成总票数——比如:100000000
owner_address:合约持有人地址——比如:“0xu82h…7237”
trx_num:对应TRX数量——比如:232241
num: 对应的自定义资产数目。
start_time:开始时间——比如:20170312
end_time:结束时间——比如:20170512
decav_ratio:衰减速率。
vote_score:合约的评分——比如:12343
description:合约的描述——比如:”trondada”
url:合约的url地址链接。

message AssetIssueContract {
  
  bytes owner_address = 1;
  
  bytes name = 2;
  
  int64 total_supply = 4;
  
  int32 trx_num = 6;
  
  int32 num = 8;
  
  int64 start_time = 9;
  
  int64 end_time = 10;
  
  int32 decay_ratio = 15;
 
  int32 vote_score = 16;
 
  bytes description = 20;
  
  bytes url = 21;

 }

ParticipateAssetIssueContract包含4种参数:
owner_address:合约持有人地址——比如:“0xu82h…7237”
to_address:接收方地址——比如:“0xu82h…7237”
asset_name: 目标资产的名称。
amount: 小部分数量。

DeployContract包含2种参数:
script:脚本。
owner_address:合约持有人地址——比如:“0xu82h…7237”

message DeployContract {
  
  bytes owner_address = 1;
  
  bytes script = 2;

 }

消息体 Result 包含 fee and ret2个参数.
ret: 交易结果。
fee: 交易扣除的费用。

coderet的类型定义,有SUCCESSFAILED两种类型。

message Result {
  enum code {
    SUCESS = 0;
    FAILED = 1;
   }
   int64 fee = 1;
   code ret = 2;
 }
  • 每一个交易还包含多个输入与多个输出,以及其他一些相关属性。其中交易内的输入,交易本身,区块头均需签名。

消息体 Transaction包括raw_datasignature
raw_data: 消息体raw
signature: 所有输入节点的签名。

raw_data包含8种参数:
type:消息体raw的交易类型。
vin: 输入值。
vout: 输出值。
expiration:过期时间——比如:20170312
data: 数据。
contract: 该交易内的合约。
script: 脚本。 timestamp:该消息体的时间戳。

消息体 Contract包含typeparameter
type:合约的类型。
parameter:任意参数。

有八种账户类型合约:AccountCreateContractTransferContractTransferAssetContractVoteAssetContractVoteWitnessContractWitnessCreateContractAssetIssueContractDeployContract

TransactionType包括UtxoTypeContractType

message Transaction {
  
  enum TranscationType {
    
    UtxoType = 0;
    
    ContractType = 1;
  
   }
  
   message Contract {
   
     enum ContractType {
      
       AccountCreateContract = 0;
      
       TransferContract = 1;
      
       TransferAssetContract = 2;
      
       VoteAssetContract = 3;
      
       VoteWitnessContract = 4;
     
       WitnessCreateContract = 5;
      
       AssetIssueContract = 6;
      
       DeployContract = 7;
    
      }
    
      ContractType type = 1;
    
      google.protobuf.Any parameter = 2;
 
    }
  
    message raw {
    
      TranscationType type = 2;
    
      repeated TXInput vin = 5;
    
      repeated TXOutput vout = 7;
    
      int64 expiration = 8;
    
      bytes data = 10;
    
      repeated Contract contract = 11;
    
      bytes scripts = 16;

      in64 timestamp = 17; 
     }
  
     raw raw_data = 1;
  
     repeated bytes signature = 5;

 }

消息体 TXOutputsoutputs构成。
outputs: 元素为TXOutput的数组。

message TXOutputs {
  
  repeated TXOutput outputs = 1;
 
}

消息体 TXOutput包括valuepubKeyHash
value:输出值。
pubKeyhash:公钥的哈希。

message TXOutput {
  
  int64 value = 1;
  
  bytes pubKeyHash = 2;
 
}

消息体 TXIutput包括raw_datasignature
raw_data:消息体raw
signatureTXInput的签名。

消息体 raw包含txIDvoutpubKey
txID:交易ID。
Vout:上一个输出的值。
pubkey:公钥。

message TXInput {
  
  message raw {
    
    bytes txID = 1;
    
    int64 vout = 2;
    
    bytes pubKey = 3;
  
   }
  
   raw raw_data = 1;
 
   bytes signature = 4;
}
  • 传输涉及的协议Inventory主要用于传输中告知接收方传输数据的清单。

Inventory包括typeids
type:清单类型——比如:0 代表TRX
ids:清单中的物品ID。

InventoryType包含TRXBLOCK
TRX:交易。
BLOCK:区块。

// Inventory

message Inventory {
  
  enum InventoryType {
    
    TRX = 0;
    
    BLOCK = 1;
  
   }
  
   InventoryType type = 1;
  
   repeated bytes ids = 2;
 
}

消息体 Items包含4种参数:
type:物品类型——比如:1 代表 TRX
blocks:物品中区块。
blockheaders:区块头。
transactions:交易。

Items有四种类型,分别是 ERRTRXBLOCKBLOCKHEADER
ERR:错误。
TRX:交易。
BLOCK:区块。
BLOCKHEADER:区块头。

message Items {
  
  enum ItemType {
    
    ERR = 0;
    
    TRX = 1;
    
    BLOCK = 2;
    
    BLOCKHEADER = 3;
  
   }
  
   ItemType type = 1;
  
   repeated Block blocks = 2;
  
   repeated BlockHeader block_headers = 3;
  
   repeated Transaction transactions = 4;

 }

Inventory包含typeitems
type:清单种类。
items:清单列表。

message InventoryItems {
  
  int32 type = 1;
  
  repeated bytes items = 2;

 }

消息体 BlockInventory 包含 type
type: 清单种类.

有三种类型:SYNC, ADVTISE, FETCH

// Inventory
 message BlockInventory {
   enum Type {
     SYNC = 0;
     ADVTISE = 1;
     FETCH = 2;
   }

消息体 BlockId 包括 ids and type
ids: 区块身份信息。
type: 区块类型。

ids 包含2种参数:
hash: 区块的哈希值。
number: 哈希值和区块高度即为当前区块号。

 message BlockId {
    bytes hash = 1;
    int64 number = 2;
  }
  repeated BlockId ids = 1;
  Type type = 2;
 }

ReasonCode 有15种可能断开的原因:
REQUESTED
TCP_ERROR
BAD_PROTOCOL
USELESS_PEER
TOO_MANY_PEERS
DUPLICATE_PEER
INCOMPATIBLE_PROTOCOL
NULL_IDENTITY
PEER_QUITING
UNEXPECTED_IDENTITY
LOCAL_IDENTITY
PING_TIMEOU
USER_REASON
RESET
UNKNOWN

  enum ReasonCode {
    REQUESTED = 0;
    TCP_ERROR = 1;
    BAD_PROTOCOL = 2;
    USELESS_PEER = 3;
    TOO_MANY_PEERS = 4;
    DUPLICATE_PEER = 5;
    INCOMPATIBLE_PROTOCOL = 6;
    NULL_IDENTITY = 7;
    PEER_QUITING = 8;
    UNEXPECTED_IDENTITY = 9;
    LOCAL_IDENTITY = 10;
    PING_TIMEOUT = 11;
    USER_REASON = 12;
    RESET = 16;
    UNKNOWN = 255;
  }

消息体DisconnectMessage包含reason
DisconnectMessage:断开连接是的消息。
reason:断开连接时的原因。

消息体HelloMessage包含2个参数:
from请:求建立连接的节点。
version:建立连接的节点。

  • 钱包服务RPC和区块链浏览器。

Wallet钱包服务包含多个RPC。
Getbalance:采用参数Account,返回对象Account
CreatTransaction:采用参数TransferContract,返回对象Transaction
BroadcastTransaction:采用参数Transaction,返回对象Return
CreateAccount:采用参数AccountCreateContract,返回对象Transaction
CreatAssetIssue:采用参数AssetIssueContract,返回对象Transaction
ListAccounts:采用参数EmptyMessage,返回对象AccountList
UpdateAccount:采用参数AccountUpdateContract,返回对象Transaction
VoteWitnessAccount:采用参数VoteWitnessContract,返回对象Transaction
WitnessList:采用参数EmptyMessage,返回对象WitnessList
UpdateWitness:采用参数WitnessUpdateContract,返回对象Transaction
CreateWitness:采用参数WitnessCreateContract,返回对象Transaction
TransferAsset:采用参数TransferAssetContract,返回对象Transaction
ParticipateAssetIssue:采用参数ParticipateAssetIssueContract,返回对象Transaction
ListNodes:采用参数EmptyMessage,返回对象NodeList
GetAssetIssueList:采用参数EmptyMessage,返回对象GetIssueList
GetAssetIssueByAccount:采用参数Account,返回对象AssetIssueList
GetAssetIssueByName:采用参数BytesMessage,返回对象AssetIssueContract
GetNowBlock:采用参数EmptyMessage,返回对象Block
GetBlockByNum:采用参数NumberMessage,返回对象Block
TotalTransaction:采用参数EmptyMessage,返回对象NumberMessage

  service Wallet {
        
          rpc GetAccount (Account) returns (Account) {
            option (google.api.http) = {
              post: "/wallet/getaccount"
              body: "*"
            };
        
          };
        
          rpc CreateTransaction (TransferContract) returns (Transaction) {
            option (google.api.http) = {
              post: "/wallet/createtransaction"
              body: "*"
            };
          };
        
          rpc BroadcastTransaction (Transaction) returns (Return) {
            option (google.api.http) = {
              post: "/wallet/broadcasttransaction"
              body: "*"
            };
          };
        
          rpc ListAccounts (EmptyMessage) returns (AccountList) {
            option (google.api.http) = {
                  post: "/wallet/listaccount"
                  body: "*"
              };
        
          };
        
          rpc UpdateAccount (AccountUpdateContract) returns (Transaction) {
            option (google.api.http) = {
              post: "/wallet/updateaccount"
              body: "*"
            };
          };
        
          rpc CreateAccount (AccountCreateContract) returns (Transaction) {
            option (google.api.http) = {
              post: "/wallet/createaccount"
              body: "*"
            };
          };
        
          rpc VoteWitnessAccount (VoteWitnessContract) returns (Transaction) {
            option (google.api.http) = {
              post: "/wallet/votewitnessaccount"
              body: "*"
            };
          };
        
          rpc CreateAssetIssue (AssetIssueContract) returns (Transaction) {
            option (google.api.http) = {
              post: "/wallet/createassetissue"
              body: "*"
            };
          };
        
          rpc ListWitnesses (EmptyMessage) returns (WitnessList) {
            option (google.api.http) = {
              post: "/wallet/listwitnesses"
              body: "*"
            };
          };
        
          rpc UpdateWitness (WitnessUpdateContract) returns (Transaction) {
            option (google.api.http) = {
              post: "/wallet/updatewitness"
              body: "*"
            };
          };
        
          rpc CreateWitness (WitnessCreateContract) returns (Transaction) {
            option (google.api.http) = {
              post: "/wallet/createwitness"
              body: "*"
            };
          };
        
          rpc TransferAsset (TransferAssetContract) returns (Transaction) {
            option (google.api.http) = {
              post: "/wallet/transferasset"
              body: "*"
            };
          }
        
          rpc ParticipateAssetIssue (ParticipateAssetIssueContract) returns (Transaction) {
            option (google.api.http) = {
              post: "/wallet/participateassetissue"
              body: "*"
            };
          }
        
          rpc ListNodes (EmptyMessage) returns (NodeList) {
            option (google.api.http) = {
              post: "/wallet/listnodes"
              body: "*"
            };
          }
          rpc GetAssetIssueList (EmptyMessage) returns (AssetIssueList) {
            option (google.api.http) = {
              post: "/wallet/getassetissuelist"
              body: "*"
            };
          }
          rpc GetAssetIssueByAccount (Account) returns (AssetIssueList) {
            option (google.api.http) = {
              post: "/wallet/getassetissuebyaccount"
              body: "*"
            };
          }
          rpc GetAssetIssueByName (BytesMessage) returns (AssetIssueContract) {
            option (google.api.http) = {
              post: "/wallet/getassetissuebyname"
              body: "*"
            };
          }
          rpc GetNowBlock (EmptyMessage) returns (Block) {
            option (google.api.http) = {
              post: "/wallet/getnowblock"
              body: "*"
            };
          }
          rpc GetBlockByNum (NumberMessage) returns (Block) {
            option (google.api.http) = {
              post: "/wallet/getblockbynum"
              body: "*"
            };
          }
          rpc TotalTransaction (EmptyMessage) returns (NumberMessage) {
            option (google.api.http) = {
              post: "/wallet/totaltransaction"
              body: "*"
            };
          }
        };

WalletSolidity钱包服务包含多个RPC。
GetAccount:采用参数Account,返回对象Account
ListAccounts:采用参数EmptyMessage,返回对象AccountList
ListWitness:采用参数EmptyMessage,返回对象WitnessList
ListNodes:采用参数EmptyMessage,返回对象NodeList
GetAssetIssueList:采用参数EmptyMessage,返回对象AssetIssueList
GetAssetIssueByTimeStamp:采用参数NumberMessage,返回对象AssetIssueList
GetAssetIssueByAccount:采用参数Account,返回对象AssetIssueList获取发行资产。
GetAssetIssueByName:采用参数BytesMessage,返回对象AssetIssueContract
GetNowBlock:采用参数EmptyMessage,返回对象AssetIssueList
GetBlockByNum:采用参数EmptyMessage,返回对象Block
TotalTransaction:采用参数EmptyMessage,返回对象NumberMessage
getTransactionById:采用参数EmptyMessage,返回对象Transaction
getTransactionInfoById:采用参数BytesMessage,返回对象Transaction
getTransactionsByTimestamp:采用参数TimeMessage,返回对象Transactionlist
getTransactionsFromThis:采用参数Account,返回对象Transactionlist
getTransactionsToThis:采用参数Account,返回对象NumberMessage

        service WalletSolidity {
        
          rpc GetAccount (Account) returns (Account) {
        
          };
        
          rpc ListAccounts (EmptyMessage) returns (AccountList) {
        
          };
        
          rpc ListWitnesses (EmptyMessage) returns (WitnessList) {
        
          };
        
          rpc ListNodes (EmptyMessage) returns (NodeList) {
        
          }
          rpc GetAssetIssueList (EmptyMessage) returns (AssetIssueList) {
        
          }
          rpc GetAssetIssueListByTimestamp (NumberMessage) returns (AssetIssueList) {
        
          }
          rpc GetAssetIssueByAccount (Account) returns (AssetIssueList) {
        
          }
          rpc GetAssetIssueByName (BytesMessage) returns (AssetIssueContract) {
        
          }
          rpc GetNowBlock (EmptyMessage) returns (Block) {
        
          }
          rpc GetBlockByNum (NumberMessage) returns (Block) {
        
          }
          
          //获取交易。

          rpc TotalTransaction (EmptyMessage) returns (NumberMessage) {
        
          }
          rpc getTransactionById (BytesMessage) returns (Transaction) {
        
          }
          rpc getTransactionsByTimestamp (TimeMessage) returns (TransactionList) {
        
          }
          rpc getTransactionsFromThis (Account) returns (TransactionList) {
        
          }
          rpc getTransactionsToThis (Account) returns (NumberMessage) {
        
          }
        };

Address: 节点地址。
消息体Address 包含2个参数:
host:节点所有者。
port:节点的端口号。

message Address {
  bytes host = 1;
  int32 port = 2;
 }

消息体Return只含有一个参数:
result: 布尔表类型标志位。

message `Return` {
  
  bool result = 1;

 }
  • 网络UDP消息结构。

Endpoint:网络中节点信息存储结构.
消息体Endpoint 包含3个参数:
address:节点地址。
port:端口号。
nodeId: 节点ID信息。

message Endpoint {
  bytes address = 1;
  int32 port = 2;
  bytes nodeId = 3;
 }

PingMessage:节点建立连接时所发送的消息。
消息体PingMessage 包含4个参数:
from:消息来自的节点。
to: 消息发送的节点。
version: 网络版本。
timestamp:消息创建时的时间戳。

message PingMessage {
   Endpoint from = 1;
   Endpoint to = 2;
   int32 version = 3;
   int64 timestamp = 4;
 }

PongMessage:连接建立成功时的回复消息。
消息体PongMessage 包含3个参数:
from:消息来自的节点。
echo
timestamp:消息创建时的时间戳。

message PongMessage {
  Endpoint from = 1;
  int32 echo = 2;
  int64 timestamp = 3;
 }

FindNeighbours:节点查询相邻节点时所发送的消息。
消息体FindNeighbours 包含3个参数:
from: 消息来自的节点。
targetId: 目标节点的信息。
timestamp: 消息创建时的时间戳。

message FindNeighbours {
  Endpoint from = 1;
  bytes targetId = 2;
  int64 timestamp = 3;
 }

Neighbour:相邻接点回复消息。
消息体Neighbours 包含3个参数:
from: 消息来自的节点。
neighbours: 相邻节点。
timestamp: 消息创建时的时间戳。

message Neighbours {
  Endpoint from = 1;
  repeated Endpoint neighbours = 2;
  int64 timestamp = 3;
 }

详细的协议见附属文件。详细协议随着程序的迭代随时都可能发生变化,请以最新的版本为准。