add autobalancer callback

Author: holyfuchs

cadence/contracts/interfaces/DeFiActions.cdc

@@ -687,6 +687,14 @@ access(all) contract DeFiActions {
         }
     }
 
+    /// Callback invoked every time an AutoBalancer executes (runs rebalance).
+    ///
+    access(all) resource interface AutoBalancerExecutionCallback {
+        /// Called at the end of each rebalance run.
+        /// @param balancerUUID: The AutoBalancer's UUID
+        access(all) fun onExecuted(balancerUUID: UInt64)
+    }
+
     /// AutoBalancer
     ///
     /// A resource designed to enable permissionless rebalancing of value around a wrapped Vault. An
@@ -728,6 +736,8 @@ access(all) contract DeFiActions {
         access(self) var _recurringConfig: AutoBalancerRecurringConfig?
         /// ScheduledTransaction objects used to manage automated rebalances
         access(self) var _scheduledTransactions: @{UInt64: FlowTransactionScheduler.ScheduledTransaction}
+        /// Optional callback invoked every time rebalance() runs
+        access(self) var _executionCallback: Capability<&{AutoBalancerExecutionCallback}>?
         /// An optional UniqueIdentifier tying this AutoBalancer to a given stack
         access(contract) var uniqueID: UniqueIdentifier?
 
@@ -772,6 +782,7 @@ access(all) contract DeFiActions {
             self._recurringConfig = recurringConfig
             self._recurringConfig?.setAssignedAutoBalancer(self.uuid)
             self._scheduledTransactions <- {}
+            self._executionCallback = nil
             self.uniqueID = uniqueID
 
             emit CreatedAutoBalancer(
@@ -939,6 +950,11 @@ access(all) contract DeFiActions {
             }
             self._rebalanceRange = range
         }
+        /// Sets the optional callback invoked every time this AutoBalancer runs rebalance.
+        /// Pass nil to clear the callback.
+        access(Set) fun setExecutionCallback(_ cap: Capability<&{AutoBalancerExecutionCallback}>?) {
+            self._executionCallback = cap
+        }
         /// Returns a copy of the struct's UniqueIdentifier, used in extending a stack to identify another connector in
         /// a DeFiActions stack. See DeFiActions.align() for more information.
         access(contract) view fun copyID(): UniqueIdentifier? {
@@ -1039,7 +1055,7 @@ access(all) contract DeFiActions {
             // execute as declared, otherwise execute as currently configured, otherwise default to false
             let dataDict = data as? {String: AnyStruct} ?? {}
             let force = dataDict["force"] as? Bool ?? self._recurringConfig?.forceRebalance as? Bool ?? false
-            
+
             self.rebalance(force: force)
 
             // If configured as recurring, schedule the next execution only if this is an internally-managed
@@ -1060,10 +1076,18 @@ access(all) contract DeFiActions {
                     }
                 }
             }
+            if let cap = self._executionCallback {
+                if cap.check() {
+                    if let callback = cap.borrow() {
+                        callback.onExecuted(balancerUUID: self.uuid)
+                    }
+                }
+            }
             // clean up internally-managed historical scheduled transactions
             self._cleanupScheduledTransactions()
         }
-        /// Schedules the next execution of the rebalance if the AutoBalancer is configured as such and there is not 
+
+        /// Schedules the next execution of the rebalance if the AutoBalancer is configured as such and there is not
         /// already a scheduled transaction within the desired interval. This method is written to fail as gracefully as
         /// possible, reporting any failures to schedule the next execution to the as an event. This allows
         /// `executeTransaction` to continue execution even if the next execution cannot be scheduled while still
@@ -1171,14 +1195,14 @@ access(all) contract DeFiActions {
         ///
         /// @param id: The ID of the scheduled transaction
         ///
-        /// @return &FlowTransactionScheduler.ScheduledTransaction?: The reference to the scheduled transaction, or nil 
+        /// @return &FlowTransactionScheduler.ScheduledTransaction?: The reference to the scheduled transaction, or nil
         /// if the scheduled transaction is not found
         ///
         access(all) view fun borrowScheduledTransaction(id: UInt64): &FlowTransactionScheduler.ScheduledTransaction? {
             return &self._scheduledTransactions[id]
         }
         /// Calculates the next execution timestamp for a recurring rebalance if the AutoBalancer is configured as such.
-        /// Returns nil if either unconfigured for recurring rebalancing or the interval is greater than the maximum 
+        /// Returns nil if either unconfigured for recurring rebalancing or the interval is greater than the maximum
         /// possible timestamp.
         ///
         /// @return UFix64?: The next execution timestamp, or nil if a recurring rebalance is not configured

cadence/tests/AutoBalancer_test.cdc

@@ -4,6 +4,7 @@ import "test_helpers.cdc"
 
 import "DeFiActions"
 import "FlowTransactionScheduler"
+import "ExecutionCallbackRecorder"
 
 import "TokenA"
 import "TokenB"
@@ -69,6 +70,12 @@ access(all) fun setup() {
         arguments: [tokenAIdentifier], // unitOfAccountIdentifier
     )
     Test.expect(err, Test.beNil())
+    err = Test.deployContract(
+        name: "ExecutionCallbackRecorder",
+        path: "./contracts/ExecutionCallbackRecorder.cdc",
+        arguments: [],
+    )
+    Test.expect(err, Test.beNil())
 
     // set TokenB price in MockOracle
     let setRes = executeTransaction(
@@ -161,6 +168,55 @@ access(all) fun test_SetRebalanceSourceSucceeds() {
     Test.assertEqual(0.0, tokenBBalance!)
 }
 
+access(all) fun test_ExecutionCallbackRuns() {
+    if snapshot < getCurrentBlockHeight() {
+        Test.reset(to: snapshot)
+    }
+    let user = Test.createAccount()
+    transferFlow(signer: serviceAccount, recipient: user.address, amount: 100.0)
+    let lowerThreshold = 0.9
+    let upperThreshold = 1.1
+
+    // create AutoBalancer
+    let setupRes = executeTransaction(
+        "../transactions/auto-balance-adapter/create_auto_balancer.cdc",
+        [tokenAIdentifier, nil, lowerThreshold, upperThreshold, tokenBIdentifier, autoBalancerStoragePath, autoBalancerPublicPath],
+        user
+    )
+    Test.expect(setupRes, Test.beSucceeded())
+
+    let createdEvts = Test.eventsOfType(Type<DeFiActions.CreatedAutoBalancer>())
+    Test.assertEqual(1, createdEvts.length)
+    let createdEvt = createdEvts[0] as! DeFiActions.CreatedAutoBalancer
+    let balancerUUID = createdEvt.uuid
+
+    let interval: UInt64 = 10
+    let executionEffort: UInt64 = 1_000
+    let priority: UInt8 = 2
+    let configRes = executeTransaction(
+        "../transactions/auto-balance-adapter/set_recurring_config.cdc",
+        [autoBalancerStoragePath, interval, priority, executionEffort, true],
+        user
+    )
+    Test.expect(configRes, Test.beSucceeded())
+
+    // set execution callback (invoked only from executeTransaction, not from rebalance())
+    let setCbRes = executeTransaction(
+        "./transactions/auto-balance-adapter/set_execution_callback.cdc",
+        [autoBalancerStoragePath],
+        user
+    )
+    Test.expect(setCbRes, Test.beSucceeded())
+
+    // advance time so scheduler runs executeTransaction on the AutoBalancer
+    Test.moveTime(by: 11.0)
+
+    let invokedEvts = Test.eventsOfType(Type<ExecutionCallbackRecorder.Invoked>())
+    Test.assertEqual(1, invokedEvts.length)
+    let invokedEvt = invokedEvts[0] as! ExecutionCallbackRecorder.Invoked
+    Test.assertEqual(balancerUUID, invokedEvt.balancerUUID)
+}
+
 access(all) fun test_ForceRebalanceToSinkSucceeds() {
     Test.reset(to: snapshot)
     let user = Test.createAccount()
@@ -628,7 +684,7 @@ access(all) fun test_RecurringRebalanceToSinkSucceeds() {
     now = getCurrentBlockTimestamp()
     schedEvts = Test.eventsOfType(Type<FlowTransactionScheduler.Scheduled>())
     Test.assertEqual(2, schedEvts.length)
-    
+
     schedEvts = Test.eventsOfType(Type<FlowTransactionScheduler.Scheduled>())
     schedEvt = schedEvts[schedEvts.length - 1] as! FlowTransactionScheduler.Scheduled
     Test.assertEqual(user.address, schedEvt.transactionHandlerOwner)
@@ -760,7 +816,7 @@ access(all) fun test_RecurringRebalanceFromSourceSucceeds() {
     now = getCurrentBlockTimestamp()
     schedEvts = Test.eventsOfType(Type<FlowTransactionScheduler.Scheduled>())
     Test.assertEqual(2, schedEvts.length)
-    
+
     schedEvts = Test.eventsOfType(Type<FlowTransactionScheduler.Scheduled>())
     schedEvt = schedEvts[schedEvts.length - 1] as! FlowTransactionScheduler.Scheduled
     Test.assertEqual(user.address, schedEvt.transactionHandlerOwner)

cadence/tests/contracts/ExecutionCallbackRecorder.cdc

@@ -0,0 +1,20 @@
+import "DeFiActions"
+
+///
+/// Test-only contract: resource that implements AutoBalancerExecutionCallback
+/// and emits an event so tests can assert the callback ran.
+///
+access(all) contract ExecutionCallbackRecorder {
+
+    access(all) event Invoked(balancerUUID: UInt64)
+
+    access(all) fun createRecorder(): @Recorder {
+        return <- create Recorder()
+    }
+
+    access(all) resource Recorder: DeFiActions.AutoBalancerExecutionCallback {
+        access(all) fun onExecuted(balancerUUID: UInt64) {
+            emit Invoked(balancerUUID: balancerUUID)
+        }
+    }
+}

cadence/tests/transactions/auto-balance-adapter/set_execution_callback.cdc

@@ -0,0 +1,18 @@
+import "DeFiActions"
+import "ExecutionCallbackRecorder"
+
+/// Test helper: creates an ExecutionCallbackRecorder, saves it, and sets it as the AutoBalancer's execution callback.
+///
+/// @param autoBalancerStoragePath: storage path of the AutoBalancer
+///
+transaction(autoBalancerStoragePath: StoragePath) {
+
+    prepare(signer: auth(BorrowValue, SaveValue, IssueStorageCapabilityController) &Account) {
+        let recorder <- ExecutionCallbackRecorder.createRecorder()
+        signer.storage.save(<-recorder, to: /storage/autoBalancerExecutionCallback)
+        let cap = signer.capabilities.storage.issue<&{DeFiActions.AutoBalancerExecutionCallback}>(/storage/autoBalancerExecutionCallback)
+        let ab = signer.storage.borrow<auth(DeFiActions.Set) &DeFiActions.AutoBalancer>(from: autoBalancerStoragePath)
+            ?? panic("AutoBalancer not found at \(autoBalancerStoragePath)")
+        ab.setExecutionCallback(cap)
+    }
+}

flow.json

@@ -144,6 +144,12 @@
 				"testing": "0000000000000009"
 			}
 		},
+		"ExecutionCallbackRecorder": {
+			"source": "cadence/tests/contracts/ExecutionCallbackRecorder.cdc",
+			"aliases": {
+				"testing": "0000000000000009"
+			}
+		},
 		"MorphoERC4626SinkConnectors": {
 			"source": "cadence/contracts/connectors/evm/morpho/MorphoERC4626SinkConnectors.cdc",
 			"aliases": {