Scheduled Transactions

[j1010001]

Objective: Enable autonomous on-chain behaviors by introducing Scheduled Callbacks to the Flow protocol.

Key Result: Design and implement the core protocol support for Scheduled Callbacks.

DACI

Driver	Approver	Consulted	Informed
@j1010001	@Kay-Zee, @dete	@dete, @AlexHentschel, @devbugging	@vishalchangrani

Technical proposal: onflow/flips#331

Task list

** FVM**

• Scheduled Transactions process() call should not stop block processing: [Scheduled transactions] process user Txs if process() fails #7987

** AN API**

• Access node changes to support multiple transactions within the system collection: [Access] Support scheduled callbacks system transactions in Access API #7782

Smart contract

• create struct representing all configurable metadata
• reorganize contract to a more logical order of types and functions
• convert boilerplate code to utility functions
• init() - Implement an admin resource with setters for the various callback parameters
• getStatus() - Optimize callback storage to only store canceled callback IDs
• calculateScheduledTimestamp() - Test callstack recursion to see if using recursion here will be a problem
  • Call stack limit is 2000, 1999 was tested and was still not exceeding the transaction execution effort limit, so this should not be a problem
• process() - Test efficiency of iterating through low priority callbacks to see if it will be too expensive
• process() - Test efficiency of garbage-collection of historic statuses
• process() - limit access - only FVM can call process() and execute()
• procesS() - make more efficient. can potentially do some caching to be more efficient
• How to clean up callbacks that were processed but failed execution
  • Mark as executed in process(), emit failed flag in Executed event, and store the failed status as a historic status
  • Remove Executed from the status enum and add failed and succeded
• Important - Add getName and getDescription to the callback handler interface. These should be emitted in the events
  • (estimate: 1 day)
  • FLIP 330: Scheduled Callbacks flips#331 (comment)
• Update SchedulerConfig field to be an interface field in case we need to add fields to it later
• Update historic status garbage collection to only store X number of historic status
• Store fee FLOW in the account's main vault in order to pay for storage fees
  • estimate: 1 day
• Add a getter function to get all the information about a callback by ID
  • build on top of storing Fee FLOW in the main vault to make the callback data a struct that can be returned
  • estimate: 2 days
• Add a getter function to query callbacks for a given time period
  • estimate: 1 day
• Add type identifier to the callback events to get the type that the handler implements
  • estimate: 1/2 day
• Add limits for effort used per collection to make sure callbacks don't overwhelm the network if there is an outage or a slowdown
  • WIP PR that needs significant changes: WIP Scheduler improved limits flow-core-contracts#509
  • estimate: 2 days

Non-Critical Smart Contract Changes

• Add getHandlerType and getHandlerAddress to CallbackData
• Make a callback manager resource that controls multiple callbacks
  • Probably should do it as a separate contract
• Use binary search when finding where to insert a timestamp in sorted timestamps and when sorting cancelled callbacks array
  • estimate: 1 day
  • FLIP 330: Scheduled Callbacks flips#331 (comment)
• Separate pending execution callbacks into their own dictionary so that we don't have to iterate through all callbacks both times when we process. Also, they will not conflict with callbacks that schedule other callbacks
  • Definite performance improvement for process() on its own
  • Potentially an issue to not do this with how concurrent execution works. Will need to take data on this to see if it is an issue
  • estimate: 2 days
• Figure out a way to fix the callbacks contract if it fails in the process transaction (estimate: 1 week)
  • We can "pause" the contract by setting the collection transaction limit to zero to give us time to fix it
• add a check to not process any callbacks during any of the epoch transition transactions
  • estimate: 1/2 day

Tests

• Initialization tests
• Admin setting configurable metadata tests
• Slot filling tests
  • Test filling slot limits in all different orders with all different priorities
  • Estimate: 3 days
• Cancelation tests
  • Add a bunch of cancelation tests to the modular effort and pending queue tests
  • Estimate: 1 days
• Failing callback tests
  • Estimate: 1/2 day
• Callback scheduling another callback test
  • Estimate: 1/2 day
• Test that events are emitted in the correct order
• Execution effort matches tests
  • Execute callbacks with execution efforts that match the declared effort in all configurations
  • Execute callbacks with execution efforts that don't match the declared effort in all configurations
• IMPORTANT - Test that failed callbacks are still marked as executed when finalized later
• Test that restrictions still apply properly after configurable metadata has been updated
  • Not critical, but definitely would be nice to feel confident that updating the config in the future won't screw up scheduled callbacks
  • Estimate: 3 days
• Convert boilerplate code to utility functions
• Make tests less flaky with more reliable timestamps
  • Not Critical
  • Estimate: 1 day
• Comb through all external functions, conditions, and storage in the contract to find additional edge cases
  • Not Critical
  • Estimate: 2 days

FLIP comments

• Talk with Bjarte about what additional parameters would be valuable in events
• Answer question about declared effort vs actual effort
• Reschedule transactions?
  • Not going to address now
• How do we manage this on testnet where the fees are basically meaningless?

[devbugging]

I'm not able to edit the list, what is the suggested way to contribute to the above?

[joshuahannan]

@devbugging Feel free to just post a list here in a comment and we can update the main list if we need to or we can use both lists

[devbugging]

Block Computer

• E2E test of processing empty blocks with no scheduled callbacks
• E2E test of execution of scheduled callback
• E2E test of multiple scheduled callbacks with cancelations

[vishalchangrani]

hi @devbugging - any update on these tests?

Block Computer

• E2E test of processing empty blocks with no scheduled callbacks[ ] E2E test of execution of scheduled callback[ ] E2E test of multiple scheduled callbacks with cancelations

[vishalchangrani]

• Core Contract outstanding PRs
  • Add low prio slot and correct processing flow-core-contracts#513
  • FEATURE: Transaction scheduling flow-core-contracts#489
  • WIP Scheduler improved limits flow-core-contracts#509
• flow-go outstanding PRs.
  • [Scheduled Callbacks] Integrate callback scheduler contract #7579
  • [Scheduled Callbacks] E2E Tests #7672
  • [Scheduled Callbacks] Verification #7673

[j1010001]

Additional scope for Q4 2025 - Investigate options for executing scheduled Txs from non-service account