add supervisor for rebalancing

holyfuchs · holyfuchs · commit 11769e4836cf · 2026-02-04T14:47:43.000+01:00
diff --git a/RebalanceArchitecture.md b/RebalanceArchitecture.md
@@ -2,8 +2,6 @@
 
 The core philosophy is **decoupling**: each component operates independently with the least privilege necessary.
 
-The **Supervisor** is currently in the design phase (not yet implemented).
-
 ### Key Principles
 
 * **Isolation:** FCM, Rebalancer, and Supervisor are fully independent.
@@ -34,7 +32,7 @@ sequenceDiagram
     anyone->>FCMHelper: createPosition()
     FCMHelper->>FCM: createPosition()
     FCMHelper->>AB: createRebalancer(rebalanceCapability)
-    FCMHelper->>Supervisor: supervise(publicCapability)
+    FCMHelper->>Supervisor: addRebalancer(uuid)
 ```
 
 ### while running
diff --git a/cadence/contracts/FlowCreditMarketSupervisorV1.cdc b/cadence/contracts/FlowCreditMarketSupervisorV1.cdc
@@ -0,0 +1,51 @@
+import "FlowTransactionScheduler"
+import "FlowCreditMarketRebalancerPaidV1"
+import "FlowCron"
+
+access(all) contract FlowCreditMarketSupervisorV1 {
+
+    access(all) event Executed(id: UInt64)
+
+    access(all) resource Supervisor: FlowTransactionScheduler.TransactionHandler {
+
+        access(all) let rebalancers: {UInt64: Bool}
+
+        init() {
+            self.rebalancers = {}
+        }
+
+        access(all) fun addPaidRebalancer(uuid: UInt64) {
+            self.rebalancers[uuid] = true
+        }
+
+        access(all) fun removePaidRebalancer(uuid: UInt64): Bool? {
+            return self.rebalancers.remove(key: uuid)
+        }
+
+        access(FlowTransactionScheduler.Execute) fun executeTransaction(id: UInt64, data: AnyStruct?) {
+            emit Executed(id: id)
+            for rebalancerUUID in self.rebalancers.keys {
+                FlowCreditMarketRebalancerPaidV1.fixReschedule(uuid: rebalancerUUID)
+            }
+        }
+
+        access(all) view fun getViews(): [Type] {
+            return [Type<StoragePath>(), Type<PublicPath>()]
+        }
+
+        access(all) fun resolveView(_ view: Type): AnyStruct? {
+            switch view {
+                case Type<StoragePath>():
+                    return /storage/MyRecurringTaskHandler
+                case Type<PublicPath>():
+                    return /public/MyRecurringTaskHandler
+                default:
+                    return nil
+            }
+        }
+    }
+
+    access(all) fun createSupervisor(): @Supervisor {
+        return <- create Supervisor()
+    }
+}
diff --git a/cadence/tests/paid_auto_balance_test.cdc b/cadence/tests/paid_auto_balance_test.cdc
@@ -6,6 +6,7 @@ import "test_helpers_rebalance.cdc"
 import "FlowCreditMarketRebalancerV1"
 import "FlowTransactionScheduler"
 import "MOET"
+import "FlowCreditMarketSupervisorV1"
 
 access(all) let protocolAccount = Test.getAccount(0x0000000000000007)
 access(all) let protocolConsumerAccount = Test.getAccount(0x0000000000000008)
@@ -47,6 +48,13 @@ access(all) fun setup() {
     createWrappedPosition(signer: userAccount, amount: 100.0, vaultStoragePath: flowVaultStoragePath, pushToDrawDownSink: false)
     depositToWrappedPosition(signer: userAccount, amount: 100.0, vaultStoragePath: flowVaultStoragePath, pushToDrawDownSink: false)
     addPaidRebalancerToWrappedPosition(signer: userAccount)
+    createSupervisor(
+        signer: userAccount, 
+        cronExpression: "0 * * * *",
+        cronHandlerStoragePath: /storage/myRecurringTaskHandler,
+        keeperExecutionEffort: 1000,
+        executorExecutionEffort: 1000
+    )
     
     snapshot = getCurrentBlockHeight()
 }
@@ -238,8 +246,74 @@ access(all) fun test_public_fix_reschedule() {
     var evts = Test.eventsOfType(Type<FlowCreditMarketRebalancerV1.Rebalanced>())
     Test.assertEqual(1, evts.length)
     let e = evts[0] as! FlowCreditMarketRebalancerV1.Rebalanced
-    let publicPath = PublicPath(identifier: "paidRebalancerV1\(e.uuid)")!
 
     let randomAccount = Test.createAccount()
     fixPaidReschedule(signer: randomAccount, uuid: e.uuid)
+}
+
+access(all) fun test_supervisor_executed() {
+    safeReset()
+
+    Test.moveTime(by: 100.0)
+    Test.commitBlock()
+
+    var evts = Test.eventsOfType(Type<FlowCreditMarketSupervisorV1.Executed>())
+    Test.assertEqual(1, evts.length)
+
+    Test.moveTime(by: 60.0 * 60.0)
+    Test.commitBlock()
+
+    evts = Test.eventsOfType(Type<FlowCreditMarketSupervisorV1.Executed>())
+    Test.assertEqual(2, evts.length)
+}
+
+access(all) fun test_supervisor() {
+    safeReset()
+
+    Test.moveTime(by: 100.0)
+    Test.commitBlock()
+
+    var evts = Test.eventsOfType(Type<FlowCreditMarketSupervisorV1.Executed>())
+    Test.assertEqual(1, evts.length)
+
+    evts = Test.eventsOfType(Type<FlowCreditMarketRebalancerV1.Rebalanced>())
+    Test.assertEqual(1, evts.length)
+    let e = evts[0] as! FlowCreditMarketRebalancerV1.Rebalanced
+
+    addPaidRebalancerToSupervisor(signer: userAccount, uuid: e.uuid)
+
+    // drain the funding contract so the transaction reverts
+    let balance = getBalance(address: protocolAccount.address, vaultPublicPath: /public/flowTokenBalance)!
+    actuallyTransferFlowTokens(from: protocolAccount, to: userAccount, amount: balance)
+
+    Test.moveTime(by: 100.0)
+    Test.commitBlock()
+
+    // it still executed once but should have no transaction scheduled
+    evts = Test.eventsOfType(Type<FlowCreditMarketRebalancerV1.Rebalanced>())
+    Test.assertEqual(2, evts.length)
+
+    Test.moveTime(by: 1000.0)
+    Test.commitBlock()
+    evts = Test.eventsOfType(Type<FlowCreditMarketRebalancerV1.Rebalanced>())
+    Test.assertEqual(2, evts.length)
+
+    // now we fix the missing funds and call fix reschedule
+    mintFlow(to: protocolAccount, amount: 1000.0)
+    Test.moveTime(by: 60.0* 100.0)
+    Test.commitBlock()
+
+    // now supervisor will fix the rebalancer
+    evts = Test.eventsOfType(Type<FlowCreditMarketSupervisorV1.Executed>())
+    Test.assertEqual(2, evts.length)
+
+    evts = Test.eventsOfType(Type<FlowCreditMarketRebalancerV1.FixReschedule>())
+    Test.assertEqual(2, evts.length)
+
+    Test.moveTime(by: 10.0)
+    Test.commitBlock()
+
+    // now rebalancer could run the transaction again
+    evts = Test.eventsOfType(Type<FlowCreditMarketRebalancerV1.Rebalanced>())
+    Test.assertEqual(3, evts.length)
 }
diff --git a/cadence/tests/test_helpers.cdc b/cadence/tests/test_helpers.cdc
@@ -166,12 +166,33 @@ fun deployContracts() {
     )
     Test.expect(err, Test.beNil())
 
-        err = Test.deployContract(
+    err = Test.deployContract(
         name: "SimpleSinkSource",
         path: "../contracts/mocks/SimpleSinkSource.cdc",
         arguments: []
     )
     Test.expect(err, Test.beNil())
+
+    err = Test.deployContract(
+        name: "FlowCronUtils",
+        path: "../../imports/6dec6e64a13b881e/FlowCronUtils.cdc",
+        arguments: []
+    )
+    Test.expect(err, Test.beNil())
+
+    err = Test.deployContract(
+        name: "FlowCron",
+        path: "../../imports/6dec6e64a13b881e/FlowCron.cdc",
+        arguments: []
+    )
+    Test.expect(err, Test.beNil())
+
+    err = Test.deployContract(
+        name: "FlowCreditMarketSupervisorV1",
+        path: "../contracts/FlowCreditMarketSupervisorV1.cdc",
+        arguments: []
+    )
+    Test.expect(err, Test.beNil())
 }
 
 /* --- Script Helpers --- */
diff --git a/cadence/tests/test_helpers_rebalance.cdc b/cadence/tests/test_helpers_rebalance.cdc
@@ -64,7 +64,6 @@ fun changePaidInterval(
     Test.expect(setRes, expectFailure ? Test.beFailed() : Test.beSucceeded())
 }
 
-
 access(all)
 fun deletePaidRebalancer(
     signer: Test.TestAccount,
@@ -75,4 +74,33 @@ fun deletePaidRebalancer(
         signer
     )
     Test.expect(setRes, Test.beSucceeded())
+}
+
+access(all)
+fun createSupervisor(
+    signer: Test.TestAccount,
+    cronExpression: String,
+    cronHandlerStoragePath: StoragePath,
+    keeperExecutionEffort: UInt64,
+    executorExecutionEffort: UInt64
+) {
+    let setRes = _executeTransaction(
+        "./transactions/rebalancer/create_supervisor.cdc",
+        [cronExpression, cronHandlerStoragePath, keeperExecutionEffort, executorExecutionEffort],
+        signer
+    )
+    Test.expect(setRes, Test.beSucceeded())
+}
+
+access(all)
+fun addPaidRebalancerToSupervisor(
+    signer: Test.TestAccount,
+    uuid: UInt64
+) {
+    let setRes = _executeTransaction(
+        "./transactions/rebalancer/add_rebalancer_to_supervisor.cdc",
+        [uuid],
+        signer
+    )
+    Test.expect(setRes, Test.beSucceeded())
 }
diff --git a/cadence/tests/transactions/rebalancer/add_rebalancer_to_supervisor.cdc b/cadence/tests/transactions/rebalancer/add_rebalancer_to_supervisor.cdc
@@ -0,0 +1,22 @@
+import "FlowTransactionScheduler"
+import "FlowTransactionSchedulerUtils"
+import "FungibleToken"
+import "FlowToken"
+import "FlowCron"
+import "FlowCreditMarketSupervisorV1"
+
+transaction(
+    uuid: UInt64
+) {
+    let signer: auth(BorrowValue, IssueStorageCapabilityController, SaveValue) &Account
+    let supervisor: Capability<&FlowCreditMarketSupervisorV1.Supervisor>
+
+    prepare(signer: auth(BorrowValue, IssueStorageCapabilityController, SaveValue) &Account) {
+        self.supervisor = signer.capabilities.storage.issue<&FlowCreditMarketSupervisorV1.Supervisor>(/storage/flowCreditMarketSupervisor)
+        self.signer = signer
+    }
+
+    execute {
+        self.supervisor.borrow()!.addPaidRebalancer(uuid: uuid)
+    }
+}
diff --git a/cadence/tests/transactions/rebalancer/create_supervisor.cdc b/cadence/tests/transactions/rebalancer/create_supervisor.cdc
@@ -0,0 +1,115 @@
+import "FlowTransactionScheduler"
+import "FlowTransactionSchedulerUtils"
+import "FungibleToken"
+import "FlowToken"
+import "FlowCron"
+import "FlowCreditMarketSupervisorV1"
+
+transaction(
+    cronExpression: String,
+    cronHandlerStoragePath: StoragePath,
+    keeperExecutionEffort: UInt64,
+    executorExecutionEffort: UInt64,
+) {
+    let signer: auth(BorrowValue, IssueStorageCapabilityController, SaveValue) &Account
+    let feeProviderCap: Capability<auth(FungibleToken.Withdraw) &FlowToken.Vault>
+
+    prepare(signer: auth(BorrowValue, IssueStorageCapabilityController, SaveValue) &Account) {
+        self.feeProviderCap = signer.capabilities.storage.issue<auth(FungibleToken.Withdraw) &FlowToken.Vault>(/storage/flowTokenVault)
+        self.signer = signer
+    }
+
+    execute {
+        let supervisor <- FlowCreditMarketSupervisorV1.createSupervisor()
+        self.signer.storage.save(<-supervisor, to: /storage/flowCreditMarketSupervisor)
+        let wrappedHandlerCap = 
+            self.signer.capabilities.storage.issue<auth(FlowTransactionScheduler.Execute) &{FlowTransactionScheduler.TransactionHandler}
+        >(/storage/flowCreditMarketSupervisor)
+        assert(wrappedHandlerCap.check(), message: "Invalid wrapped handler capability")
+        self.signer.storage.save(<-FlowTransactionSchedulerUtils.createManager(), to: FlowTransactionSchedulerUtils.managerStoragePath)
+        let schedulerManagerCap: Capability<auth(FlowTransactionSchedulerUtils.Owner) &{FlowTransactionSchedulerUtils.Manager}> = self.signer.capabilities.storage.issue<auth(FlowTransactionSchedulerUtils.Owner) &{FlowTransactionSchedulerUtils.Manager}>(
+            FlowTransactionSchedulerUtils.managerStoragePath
+        )
+        let manager = self.signer.storage.borrow<auth(FlowTransactionSchedulerUtils.Owner) &{FlowTransactionSchedulerUtils.Manager}>(
+            from: FlowTransactionSchedulerUtils.managerStoragePath
+        ) ?? panic("Cannot borrow manager")
+        assert(schedulerManagerCap.check(), message: "Invalid scheduler manager capability")
+        let cronHandler <- FlowCron.createCronHandler(
+            cronExpression: cronExpression,
+            wrappedHandlerCap: wrappedHandlerCap,
+            feeProviderCap: self.feeProviderCap,
+            schedulerManagerCap: schedulerManagerCap
+        )
+        self.signer.storage.save(<-cronHandler, to: cronHandlerStoragePath)
+        let cronHandlerCap = self.signer.capabilities.storage.issue<auth(FlowTransactionScheduler.Execute) &{FlowTransactionScheduler.TransactionHandler}>(cronHandlerStoragePath)
+        assert(cronHandlerCap.check(), message: "Invalid cron handler capability")
+
+        let executorEstimate = FlowTransactionScheduler.estimate(
+            data: nil,
+            timestamp: UFix64(getCurrentBlock().timestamp + 1.0),
+            priority: FlowTransactionScheduler.Priority.Low,
+            executionEffort: executorExecutionEffort
+        )
+
+        let executorFee = executorEstimate.flowFee! * 2.0
+
+        let keeperEstimate = FlowTransactionScheduler.estimate(
+            data: nil,
+            timestamp: UFix64(getCurrentBlock().timestamp + 2.0),
+            priority: FlowTransactionScheduler.Priority.Low,
+            executionEffort: keeperExecutionEffort
+        )
+
+        let keeperFee = keeperEstimate.flowFee! * 2.0
+
+        let totalFee = executorFee + keeperFee
+
+        // Borrow fee vault and check balance
+        let feeVault = self.signer.storage.borrow<auth(FungibleToken.Withdraw) &FlowToken.Vault>(from: /storage/flowTokenVault)
+            ?? panic("Flow token vault not found")
+
+        if feeVault.balance < totalFee {
+            panic("Insufficient funds: required ".concat(totalFee.toString()).concat(" FLOW (executor: ").concat(executorFee.toString()).concat(", keeper: ").concat(keeperFee.toString()).concat("), available ").concat(feeVault.balance.toString()))
+        }
+
+        // Withdraw fees for BOTH transactions
+        let executorFees <- feeVault.withdraw(amount: executorFee) as! @FlowToken.Vault
+        let keeperFees <- feeVault.withdraw(amount: keeperFee) as! @FlowToken.Vault
+
+        let executorContext = FlowCron.CronContext(
+            executionMode: FlowCron.ExecutionMode.Executor,
+            executorPriority: FlowTransactionScheduler.Priority.Low,
+            executorExecutionEffort: executorExecutionEffort,
+            keeperExecutionEffort: keeperExecutionEffort,
+            wrappedData: nil
+        )
+
+        let executorTxID = manager.schedule(
+            handlerCap: cronHandlerCap,
+            data: executorContext,
+            timestamp: UFix64(getCurrentBlock().timestamp + 1.0),
+            priority: FlowTransactionScheduler.Priority.Low,
+            executionEffort: executorExecutionEffort,
+            fees: <-executorFees
+        )
+
+
+        let keeperContext = FlowCron.CronContext(
+            executionMode: FlowCron.ExecutionMode.Keeper,
+            executorPriority: FlowTransactionScheduler.Priority.Low,
+            executorExecutionEffort: executorExecutionEffort,
+            keeperExecutionEffort: keeperExecutionEffort,
+            wrappedData: nil
+        )
+
+        // Schedule KEEPER transaction (1 second after executor to prevent race conditions)
+        let keeperTxID = manager.schedule(
+            handlerCap: cronHandlerCap,
+            data: keeperContext,
+            timestamp: UFix64(getCurrentBlock().timestamp + 2.0),
+            priority: FlowCron.keeperPriority,
+            executionEffort: keeperExecutionEffort,
+            fees: <-keeperFees
+        )
+    }
+}
diff --git a/flow.json b/flow.json
