API

这里直接归类列出所有 gRPC API 和类型。所有 gRPC API 均对应有 HTTP API, HTTP API 列表参考 https://cn.developers.tron.network/reference .

提示

在使用 HTTP API 的过程中，应时刻对背后对 gRPC 或 protobuf 有一定认识。

例如 ScanShieldedNotes 相关 API, HTTP API 版本在部分值为 0, 为 false 时字段不存在，典型如is_spent = false .

交易创建和广播

以下 API 用于创建需要上链的交易，除 BroadcastTransaction 之外，其余 API 均用于创建一个供签名的交易，并填入 TaPos 信息(ref_block)。

在 ref_block_hash 已知的情况下（通过固化块 API 获得），交易可以离线构造。使用交易的 owner_address 签名后直接 BroadcastTransaction 即可。

service Wallet {
  // Transactions:
  rpc BroadcastTransaction(Transaction) returns (TransactionReturn) {}

  rpc CreateCommonTransaction(Transaction) returns (TransactionExtention) {}

  rpc CreateAccount(AccountCreateContract) returns (Transaction) {}
  rpc CreateAccount2(AccountCreateContract) returns (TransactionExtention) {}

  rpc UpdateAccount(AccountUpdateContract) returns (Transaction) {}
  rpc UpdateAccount2(AccountUpdateContract) returns (TransactionExtention) {}

  rpc SetAccountId(SetAccountIdContract) returns (Transaction) {}

  rpc AccountPermissionUpdate(AccountPermissionUpdateContract) returns (TransactionExtention) {}

  rpc CreateTransaction(TransferContract) returns (Transaction) {}
  rpc CreateTransaction2(TransferContract) returns (TransactionExtention) {}

  rpc CreateAssetIssue(AssetIssueContract) returns (Transaction) {}
  rpc CreateAssetIssue2(AssetIssueContract) returns (TransactionExtention) {}

  rpc UpdateAsset(UpdateAssetContract) returns (Transaction) {}
  rpc UpdateAsset2(UpdateAssetContract) returns (TransactionExtention) {}

  rpc TransferAsset(TransferAssetContract) returns (Transaction) {}
  rpc TransferAsset2(TransferAssetContract) returns (TransactionExtention) {}

  rpc ParticipateAssetIssue(ParticipateAssetIssueContract) returns (Transaction) {}
  rpc ParticipateAssetIssue2(ParticipateAssetIssueContract) returns (TransactionExtention) {}

  rpc UnfreezeAsset(UnfreezeAssetContract) returns (Transaction) {}
  rpc UnfreezeAsset2(UnfreezeAssetContract) returns (TransactionExtention) {}

  rpc CreateWitness(WitnessCreateContract) returns (Transaction) {}
  rpc CreateWitness2(WitnessCreateContract) returns (TransactionExtention) {}

  rpc UpdateWitness(WitnessUpdateContract) returns (Transaction) {}
  rpc UpdateWitness2(WitnessUpdateContract) returns (TransactionExtention) {}

  rpc UpdateBrokerage(UpdateBrokerageContract) returns (TransactionExtention) {}

  rpc VoteWitnessAccount(VoteWitnessContract) returns (Transaction) {}
  rpc VoteWitnessAccount2(VoteWitnessContract) returns (TransactionExtention) {}

  rpc FreezeBalance(FreezeBalanceContract) returns (Transaction) {}
  rpc FreezeBalance2(FreezeBalanceContract) returns (TransactionExtention) {}

  rpc UnfreezeBalance(UnfreezeBalanceContract) returns (Transaction) {}
  rpc UnfreezeBalance2(UnfreezeBalanceContract) returns (TransactionExtention) {}

  rpc WithdrawBalance(WithdrawBalanceContract) returns (Transaction) {}
  rpc WithdrawBalance2(WithdrawBalanceContract) returns (TransactionExtention) {}

  rpc ProposalCreate(ProposalCreateContract) returns (TransactionExtention) {}
  rpc ProposalApprove(ProposalApproveContract) returns (TransactionExtention) {}
  rpc ProposalDelete(ProposalDeleteContract) returns (TransactionExtention) {}

  rpc DeployContract(CreateSmartContract) returns (TransactionExtention) {}
  rpc UpdateSetting(UpdateSettingContract) returns (TransactionExtention) {}          // consume_user_resource_percent
  rpc UpdateEnergyLimit(UpdateEnergyLimitContract) returns (TransactionExtention) {}  // origin_energy_limit
  rpc ClearContractABI(ClearABIContract) returns (TransactionExtention) {}
  rpc TriggerContract(TriggerSmartContract) returns (TransactionExtention) {}
  rpc TriggerConstantContract(TriggerSmartContract) returns (TransactionExtention) {}  // not a txn type

  rpc ExchangeCreate(ExchangeCreateContract) returns (TransactionExtention) {}
  rpc ExchangeInject(ExchangeInjectContract) returns (TransactionExtention) {}
  rpc ExchangeWithdraw(ExchangeWithdrawContract) returns (TransactionExtention) {}
  rpc ExchangeTransaction(ExchangeTransactionContract) returns (TransactionExtention) {}
}

链上数据查询

以下所列出的 API 用于链上数据查询或节点状态查询，所有操作不会上链。请求参数不含隐私信息，安全可靠。

service Wallet {
  // The real APIs:
  rpc GetNodeInfo(EmptyMessage) returns (NodeInfo) {}
  rpc ListNodes(EmptyMessage) returns (NodeList) {}

  rpc GetChainParameters(EmptyMessage) returns (ChainParameters) {}
  rpc TotalTransaction(EmptyMessage) returns (NumberMessage) {}
  rpc GetNextMaintenanceTime(EmptyMessage) returns (NumberMessage) {}

  rpc GetTransactionSignWeight(Transaction) returns (TransactionSignWeight) {}
  rpc GetTransactionApprovedList(Transaction) returns (TransactionApprovedList) {}

  // FLAW: Account.address
  rpc GetAccount(Account) returns (Account) {}
  // FLAW: Account.id
  rpc GetAccountById(Account) returns (Account) {}

  rpc GetAccountNet(AccountAddressMessage) returns (AccountNetMessage) {}
  rpc GetAccountResource(AccountAddressMessage) returns (AccountResourceMessage) {}

  rpc GetAssetIssueByAccount(AccountAddressMessage) returns (AssetIssueList) {}
  rpc GetAssetIssueByName(BytesMessage) returns (AssetIssueContract) {}
  rpc GetAssetIssueListByName(BytesMessage) returns (AssetIssueList) {}
  rpc GetAssetIssueById(BytesMessage) returns (AssetIssueContract) {}
  rpc GetAssetIssueList(EmptyMessage) returns (AssetIssueList) {}
  rpc GetPaginatedAssetIssueList(PaginatedMessage) returns (AssetIssueList) {}

  rpc GetNowBlock(EmptyMessage) returns (Block) {}
  rpc GetNowBlock2(EmptyMessage) returns (BlockExtention) {}

  rpc GetBlockByNum(NumberMessage) returns (Block) {}
  rpc GetBlockByNum2(NumberMessage) returns (BlockExtention) {}

  // NOTE: `GetBlockById2` is missing. The closest is `GetBlockByLatestNum2`.
  rpc GetBlockById(BytesMessage) returns (Block) {}

  rpc GetBlockByLimitNext(BlockLimit) returns (BlockList) {}
  rpc GetBlockByLimitNext2(BlockLimit) returns (BlockListExtention) {}

  rpc GetBlockByLatestNum(NumberMessage) returns (BlockList) {}
  rpc GetBlockByLatestNum2(NumberMessage) returns (BlockListExtention) {}

  rpc GetTransactionCountByBlockNum(NumberMessage) returns (NumberMessage) {}

  rpc GetTransactionById(BytesMessage) returns (Transaction) {}

  rpc GetTransactionInfoById(BytesMessage) returns (TransactionInfo) {}
  rpc GetTransactionInfoByBlockNum(NumberMessage) returns (TransactionInfoList) {}

  rpc GetContract(BytesMessage) returns (SmartContract) {}
  // FLAW: Abusing of `info`. Should be a `GetContractCode`.
  rpc GetContractInfo(BytesMessage) returns (SmartContractDataWrapper) {}

  rpc ListWitnesses(EmptyMessage) returns (WitnessList) {}
  rpc GetBrokerageInfo(BytesMessage) returns (NumberMessage) {}
  rpc GetRewardInfo(BytesMessage) returns (NumberMessage) {}

  rpc GetDelegatedResource(DelegatedResourceMessage) returns (DelegatedResourceList) {}
  rpc GetDelegatedResourceAccountIndex(BytesMessage) returns (DelegatedResourceAccountIndex) {}

  rpc ListProposals(EmptyMessage) returns (ProposalList) {}
  rpc GetProposalById(BytesMessage) returns (Proposal) {}
  rpc GetPaginatedProposalList(PaginatedMessage) returns (ProposalList) {}

  rpc ListExchanges(EmptyMessage) returns (ExchangeList) {}
  rpc GetExchangeById(BytesMessage) returns (Exchange) {}
  rpc GetPaginatedExchangeList(PaginatedMessage) returns (ExchangeList) {}

  // Shielded TRC20 helpers:
  rpc ScanShieldedTRC20NotesByIvk(IvkDecryptTRC20Parameters) returns (DecryptNotesTRC20) {}
  rpc ScanShieldedTRC20NotesByOvk(OvkDecryptTRC20Parameters) returns (DecryptNotesTRC20) {}
  rpc IsShieldedTRC20ContractNoteSpent(NfTRC20Parameters) returns (NullifierResult) {}

  // Market API:
  rpc GetMarketOrderByAccount(BytesMessage) returns (MarketOrderList) {}
  rpc GetMarketOrderById(BytesMessage) returns (MarketOrder) {}
  rpc GetMarketPriceByPair(MarketOrderPair) returns (MarketPriceList) {}
  rpc GetMarketOrderListByPair(MarketOrderPair) returns (MarketOrderList) {}
  rpc GetMarketPairList(EmptyMessage) returns (MarketOrderPairList) {}
}

Unsafe API

此类 API 有安全隐患，应避免使用，或至少确保只在可信节点上使用。

最佳实践是：

应用开发者应使用这些 API 的离线实现，或使用自己搭建的全节点。

service Wallet {
  // FLAW: Unsafe junk.
  rpc GetTransactionSign(TransactionSign) returns (Transaction) {}
  rpc GetTransactionSign2(TransactionSign) returns (TransactionExtention) {}
  rpc EasyTransferAsset(EasyTransferAssetMessage) returns (EasyTransferResponse) {}
  rpc EasyTransferAssetByPrivate(EasyTransferAssetByPrivateMessage) returns (EasyTransferResponse) {}
  rpc EasyTransfer(EasyTransferMessage) returns (EasyTransferResponse) {}
  rpc EasyTransferByPrivate(EasyTransferByPrivateMessage) returns (EasyTransferResponse) {}
  rpc CreateAddress(BytesMessage) returns (BytesMessage) {}
  rpc GenerateAddress(EmptyMessage) returns (AddressPrKeyPairMessage) {}
  rpc AddSign(TransactionSign) returns (TransactionExtention) {}

  // FLAW: Unsafe shielded random generator(might be safe).
  rpc GetRcm(EmptyMessage) returns (BytesMessage) {}  
  rpc GetDiversifier(EmptyMessage) returns (DiversifierMessage) {}

  // FLAW: Unsafe shielded junk(should be implemented offline).
  rpc GetSpendingKey(EmptyMessage) returns (BytesMessage) {}
  rpc GetExpandedSpendingKey(BytesMessage) returns (ExpandedSpendingKeyMessage) {}
  rpc GetAkFromAsk(BytesMessage) returns (BytesMessage) {}
  rpc GetNkFromNsk(BytesMessage) returns (BytesMessage) {}
  rpc GetIncomingViewingKey(ViewingKeyMessage) returns (IncomingViewingKeyMessage) {}
  rpc GetZenPaymentAddress(IncomingViewingKeyDiversifierMessage) returns (PaymentAddressMessage) {}
  rpc GetNewShieldedAddress(EmptyMessage) returns (ShieldedAddressInfo) {}
  rpc CreateShieldedContractParameters(PrivateShieldedTRC20Parameters) returns (ShieldedTRC20Parameters) {}
  rpc CreateShieldedContractParametersWithoutAsk(PrivateShieldedTRC20ParametersWithoutAsk)
      returns (ShieldedTRC20Parameters) {}
  rpc GetTriggerInputForShieldedTRC20Contract(ShieldedTRC20TriggerContractParameters) returns (BytesMessage) {}
}

固化块 API

这里列出具有实际使用意义的固化块 API, 列表之外的其他固化块 API 没有实质使用场景，应避免使用。

service WalletSolidity {
  rpc GetAccount(AccountAddressMessage) returns (Account) {}
  rpc GetNowBlock2(EmptyMessage) returns (BlockExtention) {}
  rpc GetBlockByLatestNum2(NumberMessage) returns (BlockListExtention) {}
  rpc GetTransactionById(BytesMessage) returns (Transaction) {}
  rpc GetRewardInfo(BytesMessage) returns (NumberMessage) {}
};