Welcome to the new Provenance Blockchain developer documentation portal!
logo
The 'Trigger module' provides Provenance Blockchain users with the capability to schedule the execution of specific transactions to occur automatically after a predetermined event. This powerful feature creates a more sophisticated and responsive system that allows users to seamlessly react to Provenance Blockchain events and send transactions in response.

Concepts

The Provenance Blockchain trigger module enables users to delay message execution until specific blockchain events are detected, providing an automated execution framework through single-shot triggers that register to block events and fire off predefined actions when event criteria are met. The system supports transaction events based on ABCI event matching, block height events triggered by specific block heights, and block time events activated at designated timestamps, with users required to pre-purchase gas for both trigger creation and action execution, ensuring that actions only run when sufficient allocated gas is available and triggers are automatically destroyed after successful event detection and action execution.

Trigger

A Trigger is an address owned object that registers to a Block Event, and then proceeds to fire off its Actions when that Block Event has been detected by the system. A Trigger is single-shot, and it will automatically be destroyed after its Block Event has been detected.

Actions

Actions are one or more messages that should be invoked. Every Action follows the same rules as a sdk message and requires purchased gas to run. See the Gas Payment section for more information.

Gas Payment

Gas is vital in running the Actions, and in order to simplify the system as much as possible we leave it up to the user to calculate gas usage. When a user creates a Trigger they are required to purchase gas for the transaction AND the Actions. The remaining gas that is not used by the creation transaction will be rolled into a gas meter for the Actions. These Actions will only run and update state if their is enough allocated gas.

Block Event

A Block Event is a blanket term that refers to events that occur during the creation of a block. The Trigger module currently supports Transaction Events, Block Height Events, and Block Time Events.

Transaction Event

These type of events refer to the ABCI Events that are emitted by the DeliverTx transactions. An ABCI Event must have the same Type and Attributes as the user defined Transaction Event for the event criteria to be met. A user defined Attribute with an empty Value will always match as long as the Attribute Name field matches.

Block Height Events

These type of events refer to the Block Height on a newly created block. The Block Height must be greater than or equal to the defined value for the event criteria to be met.

Block Time Event

These type of events refer to the Block Time on a newly created block. The Block Time must be greater than or equal to the defined value for the event criteria to be met.

Queued Trigger

The Queued Trigger is a Trigger that is ready to have its actions be executed at a future block.

State

The Provenance Blockchain trigger module manages comprehensive state for trigger execution through structured storage systems including trigger records with unique identifiers, event listener tables for efficient event filtering, gas limit tables for predictable gas management, and execution queues with throttling mechanisms. The state encompasses multiple event types including block height events, block time events, and transaction events with attribute matching capabilities, along with a sophisticated queue system that manages trigger execution order during BeginBlock processing with configurable start indices and length tracking for optimal performance and resource management.

Trigger

A Trigger is the main data structure used by the module. It keeps track of the owner, event, and actions for a single Trigger. Every Trigger gets its own unique identifier, and a unique entry within the Event Listener and Gas Limit tables. The Event Listener table allows the event detection system to quickly filter applicable Triggers by name and type. A trigger can vary in size making it difficult to calculate gas usage on store, thus we opted to store remaining transaction gas in the Gas Limit table. It gives us a predictable way to calculate and store remaining gas.
The excess gas on a MsgCreateTrigger transaction will be used for the Trigger's Gas Limit table. The maximum Gas Limit for a Trigger is 2000000.
Storage Format:
  • Trigger: 0x01 | Trigger ID (8 bytes) -> ProtocolBuffers(Trigger)
  • Trigger ID: 0x05 -> uint64(TriggerID)
  • Event Listener: 0x02 | Event Type (32 bytes) | Order (8 bytes) -> []byte{}
  • Gas Limit: 0x04 | Trigger ID (8 bytes) -> uint64(GasLimit)
protobuf
// Source: https://github.com/provenance-io/provenance/blob/bda28e5f58a4a58e8fef21141400ad362b84518b/proto/provenance/trigger/v1/trigger.proto#L13-L26 message Trigger { // Unique identifier for this trigger uint64 id = 1; // Address that owns this trigger string owner = 2; // Event that will activate this trigger google.protobuf.Any event = 3; // Actions to execute when triggered repeated google.protobuf.Any actions = 4; }

TriggerEventI

A Trigger must have an event that implements the TriggerEventI interface. Currently, the system supports BlockHeightEvent, BlockTimeEvent, and TransactionEvent.

BlockHeightEvent

The BlockHeightEvent allows the user to configure their Trigger to fire when the current block's Block Height is greater than or equal to the defined one.
protobuf
// Source: https://github.com/provenance-io/provenance/blob/bda28e5f58a4a58e8fef21141400ad362b84518b/proto/provenance/trigger/v1/trigger.proto#L41-L49 message BlockHeightEvent { // Block height that will trigger this event uint64 block_height = 1; }

BlockTimeEvent

The BlockTimeEvent allows the user to configure their Trigger to fire when the current block's Block Time is greater than or equal to the defined one.
protobuf
// Source: https://github.com/provenance-io/provenance/blob/bda28e5f58a4a58e8fef21141400ad362b84518b/proto/provenance/trigger/v1/trigger.proto#L51-L59 message BlockTimeEvent { // Block time that will trigger this event google.protobuf.Timestamp block_time = 1; }

TransactionEvent

The TransactionEvent allows the user to configure their Trigger to fire when a transaction event matching the user defined one has been emitted.
protobuf
// Source: https://github.com/provenance-io/provenance/blob/bda28e5f58a4a58e8fef21141400ad362b84518b/proto/provenance/trigger/v1/trigger.proto#L61-L71 message TransactionEvent { // Type of the transaction event string type = 1; // Attributes that must be present in the event repeated Attribute attributes = 2; }

Attribute

The Attribute is used by the TransactionEvent to allow the user to configure which attributes must be present on the transaction event. An Attribute with an empty value will only require the name to match.
protobuf
// Source: https://github.com/provenance-io/provenance/blob/bda28e5f58a4a58e8fef21141400ad362b84518b/proto/provenance/trigger/v1/trigger.proto#L73-L82 message Attribute { // Name of the attribute string name = 1; // Value of the attribute (empty value matches any) string value = 2; }

Queue

The Queue is an internal structure that we use to store and throttle the execution of Triggers on the BeginBlock. We store each Trigger as a QueuedTrigger, and then manipulate the Queue Start Index and Queue Length whenever we add or remove from the Queue. When we add to the Queue, the new element is added to the QueueStartIndex + Length. The QueueLength is then incremented by one. When we dequeue from the Queue, the QueueStartIndex will be incremented by 1 and the QueueLength is decremented by 1. We also ensure the key of the dequeued element is removed.
Storage Format:
  • Queue Item: 0x03 | Queue Index (8 bytes) -> ProtocolBuffers(QueuedTrigger)
  • Queue Start Index: 0x06 -> uint64(QueueStartIndex)
  • Queue Length: 0x07 -> uint64(QueueLength)
protobuf
// Source: https://github.com/provenance-io/provenance/blob/bda28e5f58a4a58e8fef21141400ad362b84518b/proto/provenance/trigger/v1/trigger.proto#L28-L39 message QueuedTrigger { // The block height when this trigger was queued uint64 block_height = 1; // Time when this trigger was queued google.protobuf.Timestamp time = 2; // The trigger to execute Trigger trigger = 3; }

Messages

The Provenance Blockchain trigger module provides two primary message types for managing automated execution triggers: MsgCreateTriggerRequest for creating triggers that fire when specific events are detected with comprehensive validation of authorities, events, and actions, and MsgDestroyTriggerRequest for removing existing triggers with ownership verification. The creation process designates the first signer as the trigger owner when multiple signers are present, validates that events implement the TriggerEventI interface, ensures actions are valid SDK messages with proper signer authorization, while the destruction process requires exact ownership matching and trigger existence validation to maintain secure trigger lifecycle management.

MsgCreateTriggerRequest

Creates a Trigger that will fire when its event has been detected. If the message has more than one signer, then the newly created Trigger will designate the first signer as the owner.

Request

protobuf
// Source: https://github.com/provenance-io/provenance/blob/bda28e5f58a4a58e8fef21141400ad362b84518b/proto/provenance/trigger/v1/tx.proto#L20-L31 message MsgCreateTriggerRequest { // The authorities/signers of the request repeated string authorities = 1; // The event that will trigger the actions google.protobuf.Any event = 2; // The actions to execute when the event is detected repeated google.protobuf.Any actions = 3; }

Response

protobuf
// Source: https://github.com/provenance-io/provenance/blob/bda28e5f58a4a58e8fef21141400ad362b84518b/proto/provenance/trigger/v1/tx.proto#L33-L37 message MsgCreateTriggerResponse { // The unique identifier of the created trigger uint64 id = 1; }

Expected Failures

The message will fail under the following conditions:
  • The authority is an invalid bech32 address
  • The event does not implement TriggerEventI
  • The actions list is empty
  • At least one action is not a valid sdk.Msg
  • The signers on one or more actions aren't in the set of the request's signers

MsgDestroyTriggerRequest

Destroys a Trigger that has been created and is still registered.

Request

protobuf
// Source: https://github.com/provenance-io/provenance/blob/bda28e5f58a4a58e8fef21141400ad362b84518b/proto/provenance/trigger/v1/tx.proto#L39-L48 message MsgDestroyTriggerRequest { // The trigger ID to destroy uint64 id = 1; // The authority/owner of the trigger string authority = 2; }

Response

protobuf
// Source: https://github.com/provenance-io/provenance/blob/bda28e5f58a4a58e8fef21141400ad362b84518b/proto/provenance/trigger/v1/tx.proto#L50-L51 message MsgDestroyTriggerResponse {}

Expected Failures

The message will fail under the following conditions:
  • The Trigger does not exist
  • The Trigger owner does not match the specified address

Events

The Provenance Blockchain trigger module emits four distinct events to track the complete lifecycle of automated trigger operations: TriggerCreated when triggers are established through CreateTriggerMsg, TriggerDestroyed when triggers are removed via DestroyTriggerMsg, TriggerDetected when trigger events are identified in the EndBlocker, and TriggerExecuted when trigger actions are processed in the BeginBlocker. These events provide comprehensive visibility into trigger management and execution, enabling applications to monitor trigger creation, destruction, detection timing, and execution outcomes including success status and owner information throughout the automated execution workflow.

Trigger Created

Fires when a trigger is created with the CreateTriggerMsg.
Type
Attribute Key
Attribute Value
TriggerCreated
trigger_id
The ID of the created trigger

Trigger Destroyed

Fires when a trigger is destroyed with the DestroyTriggerMsg.
Type
Attribute Key
Attribute Value
TriggerDestroyed
trigger_id
The ID of the trigger being destroyed

Trigger Detected

Fires when a trigger's event is detected in the EndBlocker.
Type
Attribute Key
Attribute Value
TriggerDetected
trigger_id
The ID of the trigger being detected

Trigger Executed

Fires when a trigger's actions are executed in the BeginBlocker.
Type
Attribute Key
Attribute Value
TriggerExecuted
trigger_id
The ID of the trigger being executed
TriggerExecuted
owner
The sdk.Address of the trigger's owner
TriggerExecuted
success
A boolean indicating if all the actions successfully executed

Queries

The Provenance Blockchain trigger module provides a streamlined query service for accessing and managing automated execution triggers through two primary endpoints: TriggerByID for retrieving specific triggers by their unique identifier, and Triggers for listing all registered triggers with pagination support. The query service enables applications to inspect trigger configurations, monitor trigger status, and manage automated execution workflows by providing direct access to trigger objects that contain event definitions, action specifications, and ownership information necessary for understanding and coordinating the automated execution system.

TriggerByID

Returns a trigger matching the ID.
HTTP Endpoint: GET /provenance/trigger/v1/triggers/{id}
Request: QueryTriggerByIDRequestResponse: QueryTriggerByIDResponse

QueryTriggerByIDRequest

protobuf
// Source: https://github.com/provenance-io/provenance // QueryTriggerByIDRequest queries for the Trigger with an identifier of id. message QueryTriggerByIDRequest { // The id of the trigger to query. uint64 id = 1; }

QueryTriggerByIDResponse

protobuf
// Source: https://github.com/provenance-io/provenance // QueryTriggerByIDResponse contains the requested Trigger. message QueryTriggerByIDResponse { // The trigger object that was queried for. Trigger trigger = 1; }

Triggers

Returns the list of triggers.
HTTP Endpoint: GET /provenance/trigger/v1/triggers
Request: QueryTriggersRequestResponse: QueryTriggersResponse

QueryTriggersRequest

protobuf
// Source: https://github.com/provenance-io/provenance // QueryTriggersRequest queries for all triggers. message QueryTriggersRequest { // pagination defines an optional pagination for the request. cosmos.base.query.v1beta1.PageRequest pagination = 99; }

QueryTriggersResponse

protobuf
// Source: https://github.com/provenance-io/provenance // QueryTriggersResponse contains the list of Triggers. message QueryTriggersResponse { // List of Trigger objects. repeated Trigger triggers = 1 [(gogoproto.nullable) = false]; // pagination defines an optional pagination for the response. cosmos.base.query.v1beta1.PageResponse pagination = 99; }
protobuf
// Example Query Service Definition // Source: https://github.com/provenance-io/provenance service Query { // TriggerByID returns a trigger matching the ID. rpc TriggerByID(QueryTriggerByIDRequest) returns (QueryTriggerByIDResponse) { option (google.api.http).get = "/provenance/trigger/v1/triggers/{id}"; } // Triggers returns the list of triggers. rpc Triggers(QueryTriggersRequest) returns (QueryTriggersResponse) { option (google.api.http).get = "/provenance/trigger/v1/triggers"; } }

Params

No param restrictions exist for the trigger module.

Special Topics

Begin-End BlockerGenesis