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) {}
};