TRC: Tron event subscribe model

[jiangyy0824]

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.

[BlueHoopor]

Very useful Proposal !

This would be the official TRON event service. Many Dapp developer would like to use this.

[BlueHoopor]

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.

[jiangyy0824]

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.

[davidbongcc]

How can I setup the event subscriber to retrieve the events data and insert into the Mongodb?

[adsl2010]

Hi

[simonushie]

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......

[vahidalvandi]

i need a way from trongrid after transaction in constract call web hook
please help

[NPCSun]

@jiangyy0824 hi, after calling balanceof(address) by http api triggerconstantcontract, will contracteventTrigger have one message?

[simonushie]

Hello vahid, currently trongrid does provide a webhook service but within your contract you can emit important variables to be stored as events after which you can send a request to : https://api.trongrid.io/v1/contracts/<contract name>/events (more details on this in the picture below) you can use the following parameters for example: {"event_name":"<EventName>","only_confirmed":"true","limit":"200"} and then get the events and store in a database or output in real time if you want for more detailed options on parameters, goto https://developers.tron.network/reference/get-events-by-contract-address , you should see: [image: lafkwjefwef.PNG] just input your contract address and yu will see different ways to query the blockchain for the events on your contract via api in a sleek and understandable way hope this helps

…

On Fri, Jun 24, 2022 at 8:31 PM vahid alvandi ***@***.***> wrote: i need a way from trongrid after transaction in constract call web hook please help — Reply to this email directly, view it on GitHub <#12 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AKLQMJIR7HTEI4LMRVRS7WLVQYEIHANCNFSM4GLQQWQA> . You are receiving this because you commented.Message ID: ***@***.***>

[Wildanzr]

Hi @simonushie is there any method to get the event via Webhook or just using an event listener?