TRC: Tron event subscribe model
jiangyy0824 opened this issue · 9 comments
tip: 12
title: TRC-12 Tron event subscribes model
author: jiangyy<jiangyangyang@tron.network>
discussions to: https://github.com/tronprotocol/TIPs/issues/12
status: accepted
type: Standards Track
category: TRC
created: 2018-12-20
Simple Summary
This doc describes event subscribe model of Tron.
Abstract
The following describes a model which is used to subscribe to block chain events, transaction events, contract logs and contract events from Tron FullNode. Developers can set up filters to subscribe to specific events. Plug-ins can be developed to export these events for further development.
Motivation
This will allow dapps developers or exchange to subscribe any event triggered on Tron.
Specification
Events to subscribe
- transactionTrigger, triggered after the transaction is processed
- blockTrigger, triggered after a block is inserted into block chain
- contractLogTrigger, triggered after smart contract is executed
- contractEventTrigger, triggered after smart contract is executed
Filter
- fromBlock: the beginning of the queried range, it could be set to "", "earliest", "latest" or specified block number, the default value is "latest". "earliest" is the oldest block number from the beginning of the subscription. "latest" is the latest block number when the filter is set.
- toBlock: end of the range, it could be set to "", "latest" or specified block number, the default value is "latest".
- contractAddress: restricts matches to events created by specific contracts.
- contractTopics: The Topic list restricts matches to particular event topics. Each event has a list of topics. Topics match a prefix of that list. An empty element slice matches any.
Notice: No support the historical data query.
Smart Contract log
contractLogTrigger is used to represent the object of smart contract log, which has following parameters:
- transactionId, transaction id.
- contractAddress, contract address.
- callerAddress, contract caller address.
- blockNumber, the block number of transaction.
- blockTimestamp, the packing time of a transaction in block.
- contractTopics, list of topics that Log can output in Solidity language.
- data, data filed that Log can output in Solidity language.
Smart Contract event
contracteventTrigger is used to represent the object of smart contract log, which has following parameters:
- transactionId, transaction id.
- contractAddress, contract address.
- callerAddress, contract caller address.
- blockNumber, the block number of transaction.
- blockTimestamp, the packing time of a transaction in block.
- eventSignature, signature string of event.
- contractTopicMap, It is a map from a topic name to topic value that event can output in Solidity language.
- data, data filed that log can output in Solidity language.
Trigger event
- Triggering block event, create a blockTrigger when the block is inserted.
- Triggering transaction event, create a txsTrigger before the transaction is executed.
- Triggeingr smart contract log, create a contractLogTrigger after the contract is executed.
- Triggering smart contract event, create a contractEventTrigger after the contract is executed.
Send trigger
java-tron sends the trigger to the plugin asynchronously, and the trigger must satisfy the filter condition. The following is a filter example, the block number of the trigger must be between fromBlock and toBlock, the contractAddress must be "AddressA", the topics must include "TopicA", and only the Trigger that satisfies the condition will be sent.
- fromBlock: 0x1000000
- toBlock: 0x1200000
- contractAddress: "AddressA"
- topics: ["TopicA"]
Plugin implementation
The function of the plugin is to implement event dump. Developers can customize it according to their needs, such as Message queue, Kafka, MongoDB or writing to local files.
The plugin is independent of java-tron and is not loaded by default. It can be enabled by configuring command line parameters. By default, only subscriptions to smart contract event are supported. Developers could subscribe to other triggers by modifying configuration files.
Developers are flexible in defining plug-in configuration files, including message queue server addresses, defined Trigger types, and so on.
Take Kafka plug-in as an example, define the Kafka server address in the configuration file, Kafka topics (corresponding to the Trigger category). After receiving the Trigger sent by java-tron, the plug-in sends the Trigger to the corresponding Kafka topic according to the Trigger category.
The plug-in implements the ILogsFilterPlugin interface, including the initialization and start-up of the plug-in, receiving Trigger, and loading the plug-in according to the configuration file.
Very useful Proposal !
This would be the official TRON event service. Many Dapp developer would like to use this.
Plugin would help build decoupled, customizable event service.
I think asynchronous log&event processing is necessary. Any long-term operation wouldn't affect the Java-Tron.
I think asynchronous log&event processing is necessary. Any long-term operation wouldn't affect the Java-Tron.
That's right. Plug-ins shouldn't affect the performance of nodes. We'll also make some optimization.
How can I setup the event subscriber to retrieve the events data and insert into the Mongodb?
Hi
Plugin would help build decoupled, customizable event service.
I think asynchronous log&event processing is necessary. Any long-term operation wouldn't affect the Java-Tron.
really interesting, i was thinking more a webhook implementation......
i need a way from trongrid after transaction in constract call web hook
please help
@jiangyy0824 hi, after calling balanceof(address) by http api triggerconstantcontract, will contracteventTrigger have one message?