Merge pull request #76 from onflow/scheduled-rebalancing

Global supervisor rebalancing + auto-register + strict proofs + E2E tests

Author: Kay-Zee

.cursor/rules/standards.mdc

@@ -3,4 +3,8 @@ description:
 globs: 
 alwaysApply: true
 ---
-Do not use emojis
+- Do not use emojis
+- All documentation markdown files (.md) should be placed in the `docs/` folder, not in the repository root
+- Keep README.md in the root as the only exception
+- When writing tests, set expectations based on the architecture and requirements, NOT to make tests pass. Never reduce expected values to match actual behavior - instead fix the implementation to meet expectations.
+- Always run all tests locally before pushing changes to verify they pass

.cursorignore

@@ -0,0 +1 @@
+*.pkey

.github/workflows/scheduled_rebalance_tests.yml

@@ -0,0 +1,49 @@
+name: Scheduled Rebalance Tests
+
+on:
+  push:
+    branches:
+      - main
+      - scheduled-rebalancing
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  scheduled-rebalance-tests:
+    name: FlowVaults Scheduled Rebalancing Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GH_PAT }}
+          submodules: recursive
+      - name: Set up Go
+        uses: actions/setup-go@v3
+        with:
+          go-version: "1.23.x"
+      - uses: actions/cache@v4
+        with:
+          path: ~/go/pkg/mod
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-go-
+      - name: Install Flow CLI
+        run: sh -ci "$(curl -fsSL https://raw.githubusercontent.com/onflow/flow-cli/master/install.sh)"
+      - name: Flow CLI Version
+        run: flow version
+      - name: Update PATH
+        run: echo "/root/.local/bin" >> $GITHUB_PATH
+      - name: Install dependencies
+        run: flow deps install --skip-alias --skip-deployments
+      - name: Run scheduled rebalancing tests
+        run: |
+          flow test \
+            cadence/tests/scheduled_rebalance_integration_test.cdc \
+            cadence/tests/scheduled_rebalance_scenario_test.cdc \
+            cadence/tests/tide_lifecycle_test.cdc \
+            cadence/tests/atomic_registration_gc_test.cdc \
+            cadence/tests/scheduled_supervisor_test.cdc \
+            cadence/tests/scheduler_edge_cases_test.cdc
+
+

.gitignore

@@ -1,5 +1,6 @@
 # local
 .DS_Store
+**/.DS_Store
 .pr-drafts/
 .vscode/
 
@@ -20,3 +21,6 @@ solidity/out/
 broadcast
 cache
 db
+
+# logs
+run_logs/*.log

cadence/.DS_Store

@@ -231,7 +231,8 @@ access(all) contract FlowVaults {
                 remainingBalance: self.getTideBalance()
             )
             let _strategy <- self.strategy <- nil
-            Burner.burn(<-_strategy)
+            // Force unwrap to ensure burnCallback is called on the Strategy
+            Burner.burn(<-_strategy!)
         }
         /// TODO: FlowVaults specific views
         access(all) view fun getViews(): [Type] {
@@ -318,18 +319,24 @@ access(all) contract FlowVaults {
         access(all) view fun getNumberOfTides(): Int {
             return self.tides.length
         }
-        /// Creates a new Tide executing the specified Strategy with the provided funds
-        access(all) fun createTide(betaRef: auth(FlowVaultsClosedBeta.Beta) &FlowVaultsClosedBeta.BetaBadge, strategyType: Type, withVault: @{FungibleToken.Vault}) {
+        /// Creates a new Tide executing the specified Strategy with the provided funds.
+        /// Returns the newly created Tide ID.
+        access(all) fun createTide(
+            betaRef: auth(FlowVaultsClosedBeta.Beta) &FlowVaultsClosedBeta.BetaBadge,
+            strategyType: Type,
+            withVault: @{FungibleToken.Vault}
+        ): UInt64 {
             pre {
                 FlowVaultsClosedBeta.validateBeta(self.owner?.address!, betaRef):
                 "Invalid Beta Ref"
             }
             let balance = withVault.balance
             let type = withVault.getType()
             let tide <-create Tide(strategyType: strategyType, withVault: <-withVault)
+            let newID = tide.uniqueID.id
 
             emit CreatedTide(
-                id: tide.uniqueID.id,
+                id: newID,
                 uuid: tide.uuid,
                 strategyType: strategyType.identifier,
                 tokenType: type.identifier,
@@ -338,6 +345,8 @@ access(all) contract FlowVaults {
             )
 
             self.addTide(betaRef: betaRef, <-tide)
+
+            return newID
         }
         /// Adds an open Tide to this TideManager resource. This effectively transfers ownership of the newly added
         /// Tide to the owner of this TideManager
@@ -380,7 +389,7 @@ access(all) contract FlowVaults {
                 FlowVaultsClosedBeta.validateBeta(self.owner?.address!, betaRef):
                 "Invalid Beta Ref"
             }
-            return <- self._withdrawTide(id: id)!
+            return <- self._withdrawTide(id: id)
         }
         /// Withdraws funds from the specified Tide in the given amount. The resulting Vault Type will be whatever
         /// denomination is supported by the Tide, so callers should examine the Tide to know the resulting Vault to
@@ -400,6 +409,7 @@ access(all) contract FlowVaults {
                 self.tides[id] != nil:
                 "No Tide with ID \(id) found"
             }
+
             let tide <- self._withdrawTide(id: id)
             let res <- tide.withdraw(amount: tide.getTideBalance())
             Burner.burn(<-tide)

cadence/contracts/FlowVaults.cdc

@@ -4,6 +4,8 @@ import "FungibleToken"
 // DeFiActions
 import "DeFiActions"
 import "FlowTransactionScheduler"
+// Registry for global tide mapping
+import "FlowVaultsSchedulerRegistry"
 
 /// FlowVaultsAutoBalancers
 ///
@@ -14,7 +16,13 @@ import "FlowTransactionScheduler"
 /// which identifies all DeFiActions components in the stack related to their composite Strategy.
 ///
 /// When a Tide and necessarily the related Strategy is closed & burned, the related AutoBalancer and its Capabilities
-/// are destroyed and deleted
+/// are destroyed and deleted.
+///
+/// Scheduling approach:
+/// - AutoBalancers are configured with a recurringConfig at creation
+/// - After creation, scheduleNextRebalance(nil) starts the self-scheduling chain
+/// - The registry tracks all live tide IDs for global mapping
+/// - Cleanup unregisters from the registry
 ///
 access(all) contract FlowVaultsAutoBalancers {
 
@@ -36,19 +44,89 @@ access(all) contract FlowVaultsAutoBalancers {
         return self.account.capabilities.borrow<&DeFiActions.AutoBalancer>(publicPath)
     }
 
+    /// Checks if an AutoBalancer has at least one active (Scheduled) transaction.
+    /// Used by Supervisor to detect stuck tides that need recovery.
+    ///
+    /// @param id: The tide/AutoBalancer ID
+    /// @return Bool: true if there's at least one Scheduled transaction, false otherwise
+    ///
+    access(all) fun hasActiveSchedule(id: UInt64): Bool {
+        let autoBalancer = self.borrowAutoBalancer(id: id)
+        if autoBalancer == nil {
+            return false
+        }
+        
+        let txnIDs = autoBalancer!.getScheduledTransactionIDs()
+        for txnID in txnIDs {
+            if let txnRef = autoBalancer!.borrowScheduledTransaction(id: txnID) {
+                if txnRef.status() == FlowTransactionScheduler.Status.Scheduled {
+                    return true
+                }
+            }
+        }
+        return false
+    }
+
+    /// Checks if an AutoBalancer is overdue for execution.
+    /// A tide is considered overdue if:
+    /// - It has a recurring config
+    /// - The next expected execution time has passed
+    /// - It has no active schedule
+    ///
+    /// @param id: The tide/AutoBalancer ID
+    /// @return Bool: true if tide is overdue and stuck, false otherwise
+    ///
+    access(all) fun isStuckTide(id: UInt64): Bool {
+        let autoBalancer = self.borrowAutoBalancer(id: id)
+        if autoBalancer == nil {
+            return false
+        }
+        
+        // Check if tide has recurring config (should be executing periodically)
+        let config = autoBalancer!.getRecurringConfig()
+        if config == nil {
+            return false // Not configured for recurring, can't be "stuck"
+        }
+        
+        // Check if there's an active schedule
+        if self.hasActiveSchedule(id: id) {
+            return false // Has active schedule, not stuck
+        }
+        
+        // Check if tide is overdue
+        let nextExpected = autoBalancer!.calculateNextExecutionTimestampAsConfigured()
+        if nextExpected == nil {
+            return true // Can't calculate next time, likely stuck
+        }
+        
+        // If next expected time has passed and no active schedule, tide is stuck
+        return nextExpected! < getCurrentBlock().timestamp
+    }
+
     /* --- INTERNAL METHODS --- */
 
     /// Configures a new AutoBalancer in storage, configures its public Capability, and sets its inner authorized
     /// Capability. If an AutoBalancer is stored with an associated UniqueID value, the operation reverts.
+    ///
+    /// @param oracle: The oracle used to query deposited & withdrawn value and to determine if a rebalance should execute
+    /// @param vaultType: The type of Vault wrapped by the AutoBalancer
+    /// @param lowerThreshold: The percentage below base value at which a rebalance pulls from rebalanceSource
+    /// @param upperThreshold: The percentage above base value at which a rebalance pushes to rebalanceSink
+    /// @param rebalanceSink: An optional DeFiActions Sink to which excess value is directed when rebalancing
+    /// @param rebalanceSource: An optional DeFiActions Source from which value is withdrawn when rebalancing
+    /// @param recurringConfig: Optional configuration for automatic recurring rebalancing via FlowTransactionScheduler
+    /// @param uniqueID: The DeFiActions UniqueIdentifier used for identifying this AutoBalancer
+    ///
     access(account) fun _initNewAutoBalancer(
         oracle: {DeFiActions.PriceOracle},
         vaultType: Type,
         lowerThreshold: UFix64,
         upperThreshold: UFix64,
         rebalanceSink: {DeFiActions.Sink}?,
         rebalanceSource: {DeFiActions.Source}?,
+        recurringConfig: DeFiActions.AutoBalancerRecurringConfig?,
         uniqueID: DeFiActions.UniqueIdentifier
-    ): auth(DeFiActions.Auto, DeFiActions.Set, DeFiActions.Get, FungibleToken.Withdraw) &DeFiActions.AutoBalancer {
+    ): auth(DeFiActions.Auto, DeFiActions.Set, DeFiActions.Get, DeFiActions.Schedule, FungibleToken.Withdraw) &DeFiActions.AutoBalancer {
 
         // derive paths & prevent collision
         let storagePath = self.deriveAutoBalancerPath(id: uniqueID.id, storage: true) as! StoragePath
@@ -60,15 +138,15 @@ access(all) contract FlowVaultsAutoBalancers {
         assert(!publishedCap,
             message: "Published Capability collision found when publishing AutoBalancer for UniqueIdentifier.id \(uniqueID.id) at path \(publicPath)")
 
-        // create & save AutoBalancer
+        // create & save AutoBalancer with optional recurring config
         let autoBalancer <- DeFiActions.createAutoBalancer(
                 oracle: oracle,
                 vaultType: vaultType,
                 lowerThreshold: lowerThreshold,
                 upperThreshold: upperThreshold,
                 rebalanceSink: rebalanceSink,
                 rebalanceSource: rebalanceSource,
-                recurringConfig: nil,
+                recurringConfig: recurringConfig,
                 uniqueID: uniqueID
             )
         self.account.storage.save(<-autoBalancer, to: storagePath)
@@ -89,32 +167,64 @@ access(all) contract FlowVaultsAutoBalancers {
             message: "Error when configuring AutoBalancer for UniqueIdentifier.id \(uniqueID.id) at path \(storagePath)")
         assert(publishedCap,
             message: "Error when publishing AutoBalancer Capability for UniqueIdentifier.id \(uniqueID.id) at path \(publicPath)")
+
+        // Issue handler capability for the AutoBalancer (for FlowTransactionScheduler execution)
+        let handlerCap = self.account.capabilities.storage
+            .issue<auth(FlowTransactionScheduler.Execute) &{FlowTransactionScheduler.TransactionHandler}>(storagePath)
+
+        // Issue schedule capability for the AutoBalancer (for Supervisor to call scheduleNextRebalance directly)
+        let scheduleCap = self.account.capabilities.storage
+            .issue<auth(DeFiActions.Schedule) &DeFiActions.AutoBalancer>(storagePath)
+
+        // Register tide in registry for global mapping of live tide IDs
+        FlowVaultsSchedulerRegistry.register(tideID: uniqueID.id, handlerCap: handlerCap, scheduleCap: scheduleCap)
+
+        // Start the native AutoBalancer self-scheduling chain
+        // This schedules the first rebalance; subsequent ones are scheduled automatically
+        // by the AutoBalancer after each execution (via recurringConfig)
+        let scheduleError = autoBalancerRef.scheduleNextRebalance(whileExecuting: nil)
+        if scheduleError != nil {
+            panic("Failed to schedule first rebalance for AutoBalancer \(uniqueID.id): ".concat(scheduleError!))
+        }
+
         return autoBalancerRef
     }
 
     /// Returns an authorized reference on the AutoBalancer with the associated UniqueIdentifier.id. If none is found,
     /// the operation reverts.
     access(account)
-    fun _borrowAutoBalancer(_ id: UInt64): auth(DeFiActions.Auto, DeFiActions.Set, DeFiActions.Get, FungibleToken.Withdraw) &DeFiActions.AutoBalancer {
+    fun _borrowAutoBalancer(_ id: UInt64): auth(DeFiActions.Auto, DeFiActions.Set, DeFiActions.Get, DeFiActions.Schedule, FungibleToken.Withdraw) &DeFiActions.AutoBalancer {
         let storagePath = self.deriveAutoBalancerPath(id: id, storage: true) as! StoragePath
-        return self.account.storage.borrow<auth(DeFiActions.Auto, DeFiActions.Set, DeFiActions.Get, FungibleToken.Withdraw) &DeFiActions.AutoBalancer>(
+        return self.account.storage.borrow<auth(DeFiActions.Auto, DeFiActions.Set, DeFiActions.Get, DeFiActions.Schedule, FungibleToken.Withdraw) &DeFiActions.AutoBalancer>(
                 from: storagePath
             ) ?? panic("Could not borrow reference to AutoBalancer with UniqueIdentifier.id \(id) from StoragePath \(storagePath)")
     }
 
     /// Called by strategies defined in the FlowVaults account which leverage account-hosted AutoBalancers when a
     /// Strategy is burned
     access(account) fun _cleanupAutoBalancer(id: UInt64) {
+        // Unregister from registry (removes from global tide mapping)
+        FlowVaultsSchedulerRegistry.unregister(tideID: id)
+
         let storagePath = self.deriveAutoBalancerPath(id: id, storage: true) as! StoragePath
         let publicPath = self.deriveAutoBalancerPath(id: id, storage: false) as! PublicPath
         // unpublish the public AutoBalancer Capability
-        self.account.capabilities.unpublish(publicPath)
-        // delete any CapabilityControllers targetting the AutoBalancer
+        let _ = self.account.capabilities.unpublish(publicPath)
+        
+        // Collect controller IDs first (can't modify during iteration)
+        var controllersToDelete: [UInt64] = []
         self.account.capabilities.storage.forEachController(forPath: storagePath, fun(_ controller: &StorageCapabilityController): Bool {
-            controller.delete()
+            controllersToDelete.append(controller.capabilityID)
             return true
         })
-        // load & burn the AutoBalancer
+        // Delete controllers after iteration
+        for controllerID in controllersToDelete {
+            if let controller = self.account.capabilities.storage.getController(byCapabilityID: controllerID) {
+                controller.delete()
+            }
+        }
+        
+        // load & burn the AutoBalancer (this also handles any pending scheduled transactions via burnCallback)
         let autoBalancer <-self.account.storage.load<@DeFiActions.AutoBalancer>(from: storagePath)
         Burner.burn(<-autoBalancer)
     }