Smart Contracts - Triggers

Contract triggered by a transaction

To trigger a SC execution, the incoming transaction must add the SC address in the recipients part of the transaction.

tip

This allows to activate a SC without sending funds to it, or to send funds to it without activating the code execution.

Because the recipients field is a list, you can trigger multiple contracts in the same transaction 😉

In this scenario:

• a condition transaction may be used to check the incoming transaction (before executing the trigger).
• a transaction variable is available in the blocks.

@version 1
condition triggered_by: transaction do
    ...
end

actions triggered_by: transaction do
    ...
end

Contract triggered by a transaction with a named action

The SC caller may be able to execute a specific "named" action with specified arguments on the Smart Contract.

In this scenario:

• a condition transaction may be used to check the incoming transaction (before executing the trigger).
• a transaction variable is available in the blocks.
• every argument defined is available in the blocks.

@version 1
condition triggered_by: transaction, on: vote_for_class_president(firstname, lastname) do
    ...
end

actions triggered_by: transaction, on: vote_for_class_president(firstname, lastname) do
    ...
end

Contract triggered at a specific date and time

You may trigger a contract at a specific date and time. You need to specify a Unix time (seconds since epoch).

The datetime must be rounded to the minute

A contract will not parse if the datetime isn't rounded.

@version 1
actions triggered_by: datetime, at: 1676332800 do
    ...
end

Contract triggered at a specific interval

You may trigger a contract at a specific interval. You need to specify a CRON Format String.

note

The minimum granularity is the minute. Except in local development where the minimum granularity is the second.

@version 1

#                                    ┌───────────── minute (0 - 59)
#                                    │ ┌───────────── hour (0 - 23)
#                                    │ │ ┌───────────── day of the month (1 - 31)
#                                    │ │ │ ┌───────────── month (1 - 12)
#                                    │ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday)
#                                    │ │ │ │ │
#                                    │ │ │ │ │
#                                    │ │ │ │ │
#                                    * * * * *
actions triggered_by: interval, at: "0 8 * * *" do
  # do something each day at 8AM UTC
end

Contract triggered on every Oracle transaction

You may trigger a contract on every Oracle transaction.

In this scenario:

• a condition oracle must be used to check the oracle transaction (to avoid running a contract if the oracle does not contain what you require)
• a transaction variable is available in the blocks.

@version 1
condition triggered_by: oracle do
  # use transaction.content to make sure the oracle has the data you require
end
actions triggered_by: oracle do
  # do something with transaction.content
end

Multiple triggers

Only named action triggers may have multiple triggers. Other triggers are limited to 1 per type.

DO:

@version 1

actions triggered_by: transaction do
    ...
end

actions triggered_by: transaction, on: upgrade() do
    ...
end

actions triggered_by: transaction, on: calculate(x, y) do
    ...
end

actions triggered_by: interval, at: "0 8 * * *" do
    ...
end

DON'T:

@version 1

actions triggered_by: interval, at: "0 9 * * *" do
    ...
end

actions triggered_by: interval, at: "0 8 * * *" do
    ...
end

DON'T:

@version 1

actions triggered_by: transaction do
    ...
end

actions triggered_by: transaction do
    ...
end

DON'T:

@version 1

actions triggered_by: datetime, at:  1693519200 do
    ...
end

actions triggered_by: datetime, at:  1693605600 do
    ...
end

DON'T:

@version 1

actions triggered_by: transaction, on: lock(x, y) do
    ...
end

actions triggered_by: transaction, on: lock(x, y) do
    ...
end