Add automatic rebalancing contracts

RebalanceArchitecture.md

@@ -0,0 +1,56 @@
+## Updated Rebalance Architecture
+
+The core philosophy is **decoupling**: each component operates independently with the least privilege necessary.
+
+### Key Principles
+
+* **Isolation:** FCM, Rebalancer, and Supervisor are fully independent.
+* **Least Privilege:** The Rebalancer can *only* trigger the `rebalance` function.
+* **Resilience:** The `fixReschedule()` call is idempotent and permissionless, ensuring the system can recover without complex auth.
+
+### Rebalancer variants
+
+There are two rebalancer types; they behave the same for triggering rebalances.
+
+| | **Standard Rebalancer** | **Paid Rebalancer** |
+|---|---|---|
+| **Who pays** | User pays | Admin pays |
+| **Configuration** | User can set it | Admin sets it |
+| **Use case** | User wants full autonomy | Admin retains autonomy |
+| **Who can withdraw** | Only user | Only user |
+
+The paid rebalancer is otherwise the same: it holds a rebalance capability and runs on the same schedule/trigger model; only who pays and who controls config differ.
+
+### creating a position
+```mermaid
+sequenceDiagram
+    actor anyone
+    participant FCMHelper as FCM<br/>Helper
+    participant FCM
+    participant AB as Rebalancer
+    participant Supervisor
+    anyone->>FCMHelper: createPosition()
+    FCMHelper->>FCM: createPosition()
+    FCMHelper->>AB: createRebalancer(rebalanceCapability)
+    FCMHelper->>Supervisor: addRebalancer(uuid)
+```
+
+### while running
+
+```mermaid
+sequenceDiagram
+    participant AB1 as AutoRebalancer1
+    participant FCM
+    participant AB2 as AutoRebalancer2
+    participant SUP as Supervisor
+    loop every x min
+    AB1->>FCM: rebalance()
+    end
+    loop every y min
+    AB2->>FCM: rebalance()
+    end
+    loop every z min
+    SUP->>AB2: fixReschedule()
+    SUP->>AB1: fixReschedule()
+    end
+```

cadence/contracts/FlowCreditMarket.cdc

@@ -165,6 +165,7 @@ access(all) contract FlowCreditMarket {
     /* --- CONSTRUCTS & INTERNAL METHODS ---- */
 
     access(all) entitlement EPosition
+    access(all) entitlement ERebalance
     access(all) entitlement EGovernance
     access(all) entitlement EImplementation
     access(all) entitlement EParticipant
@@ -3243,7 +3244,7 @@ access(all) contract FlowCreditMarket {
         /// Rebalancing is done on a best effort basis (even when force=true). If the position has no sink/source,
         /// of either cannot accept/provide sufficient funds for rebalancing, the rebalance will still occur but will
         /// not cause the position to reach its target health.
-        access(EPosition) fun rebalancePosition(pid: UInt64, force: Bool) {
+        access(EPosition | ERebalance) fun rebalancePosition(pid: UInt64, force: Bool) {
             if self.debugLogging {
                 log("    [CONTRACT] rebalancePosition(pid: \(pid), force: \(force))")
             }
@@ -3650,11 +3651,11 @@ access(all) contract FlowCreditMarket {
         access(self) let id: UInt64
 
         /// An authorized Capability to which the Position was opened
-        access(self) let pool: Capability<auth(EPosition, EParticipant) &Pool>
+        access(self) let pool: Capability<auth(EPosition, ERebalance, EParticipant) &Pool>
 
         init(
             id: UInt64,
-            pool: Capability<auth(EPosition, EParticipant) &Pool>
+            pool: Capability<auth(EPosition, ERebalance, EParticipant) &Pool>
         ) {
             pre {
                 pool.check():
@@ -3871,6 +3872,11 @@ access(all) contract FlowCreditMarket {
             let pool = self.pool.borrow()!
             pool.provideTopUpSource(pid: self.id, source: source)
         }
+
+        access(ERebalance) fun rebalance(force: Bool) {
+            let pool = self.pool.borrow()!
+            pool.rebalancePosition(pid: self.id, force: force)
+        }
     }
 
     /// PositionSink

cadence/contracts/FlowCreditMarketRebalancerPaidV1.cdc

@@ -0,0 +1,128 @@
+import "FlowCreditMarket"
+import "FlowCreditMarketRebalancerV1"
+import "FlowTransactionScheduler"
+
+// FlowCreditMarketRebalancerPaidV1 — Managed rebalancer service for Flow Credit Market positions.
+//
+// This contract hosts scheduled rebalancers on behalf of users. Instead of users storing and
+// configuring Rebalancer resources themselves, they call createPaidRebalancer with a position
+// rebalance capability and receive a lightweight RebalancerPaid resource. The contract stores
+// the underlying Rebalancer, wires it to the FlowTransactionScheduler, and applies a shared
+// defaultRecurringConfig (interval, priority, txnFunder, etc.). Users can fixReschedule by UUID
+// or delete their RebalancerPaid to stop and remove the rebalancer. Admins control the default
+// config and can update or remove individual paid rebalancers.
+access(all) contract FlowCreditMarketRebalancerPaidV1 {
+
+    access(all) var defaultRecurringConfig: FlowCreditMarketRebalancerV1.RecurringConfig?
+    access(all) var storageAdminPath: StoragePath
+    access(all) let adminCapabilityStoragePath: StoragePath
+
+    access(all) fun createPaidRebalancer(
+        positionRebalanceCapability: Capability<auth(FlowCreditMarket.ERebalance) &{FlowCreditMarketRebalancerV1.Rebalancable}>,
+    ): @RebalancerPaid {
+        assert(positionRebalanceCapability.check(), message: "Invalid position rebalance capability")
+        let rebalancer <- FlowCreditMarketRebalancerV1.createRebalancer(
+            recurringConfig: self.defaultRecurringConfig!, 
+            positionRebalanceCapability: positionRebalanceCapability
+        )
+        let uuid = rebalancer.uuid
+        self.storeRebalancer(rebalancer: <-rebalancer)
+        self.setSelfCapability(uuid: uuid)
+        self.borrowRebalancer(uuid: uuid)!.fixReschedule()
+        return <- create RebalancerPaid(rebalancerUUID: uuid)
+    }
+
+    access(all) resource Admin {
+        access(all) fun updateDefaultRecurringConfig(recurringConfig: FlowCreditMarketRebalancerV1.RecurringConfig) {
+            FlowCreditMarketRebalancerPaidV1.defaultRecurringConfig = recurringConfig
+        }
+
+        access(all) fun borrowRebalancer(
+            uuid: UInt64,
+        ): auth(FlowCreditMarket.ERebalance, FlowCreditMarketRebalancerV1.Rebalancer.Configure) &FlowCreditMarketRebalancerV1.Rebalancer? {
+            return FlowCreditMarketRebalancerPaidV1.borrowRebalancer(uuid: uuid)
+        }
+
+        access(all) fun updateRecurringConfig(
+            uuid: UInt64,
+            recurringConfig: FlowCreditMarketRebalancerV1.RecurringConfig) 
+        {
+            let rebalancer = FlowCreditMarketRebalancerPaidV1.borrowRebalancer(uuid: uuid)!
+            rebalancer.setRecurringConfig(recurringConfig)
+        }
+
+        access(account) fun removePaidRebalancer(uuid: UInt64) {
+            FlowCreditMarketRebalancerPaidV1.removePaidRebalancer(uuid: uuid)
+        }
+    }
+
+    access(all) entitlement Delete
+
+    access(all) resource RebalancerPaid {
+        access(all) var rebalancerUUID : UInt64
+
+        init(rebalancerUUID: UInt64) {
+            self.rebalancerUUID = rebalancerUUID
+        }
+
+        access(Delete) fun delete() {
+            FlowCreditMarketRebalancerPaidV1.removePaidRebalancer(uuid: self.rebalancerUUID)
+        }
+
+        access(all) fun fixReschedule() {
+            let rebalancer = FlowCreditMarketRebalancerPaidV1.borrowRebalancer(uuid: self.rebalancerUUID)!
+            rebalancer.fixReschedule()
+        }
+    }
+
+    access(all) fun fixReschedule(
+        uuid: UInt64,
+    ) {
+        let rebalancer = FlowCreditMarketRebalancerPaidV1.borrowRebalancer(uuid: uuid)!
+        rebalancer.fixReschedule()
+    }
+
+    access(self) fun borrowRebalancer(
+        uuid: UInt64,
+    ): auth(FlowCreditMarket.ERebalance, FlowCreditMarketRebalancerV1.Rebalancer.Configure) &FlowCreditMarketRebalancerV1.Rebalancer? {
+        return self.account.storage.borrow<auth(FlowCreditMarket.ERebalance, FlowCreditMarketRebalancerV1.Rebalancer.Configure) &FlowCreditMarketRebalancerV1.Rebalancer>(from: self.getPath(uuid: uuid))
+    }
+
+    access(self) fun removePaidRebalancer(uuid: UInt64) {
+        let rebalancer <- self.account.storage.load<@FlowCreditMarketRebalancerV1.Rebalancer>(from: self.getPath(uuid: uuid))
+        rebalancer?.cancelAllScheduledTransactions()
+        destroy <- rebalancer
+    }
+
+    access(self) fun storeRebalancer(
+        rebalancer: @FlowCreditMarketRebalancerV1.Rebalancer,
+    ) {
+        let path = self.getPath(uuid: rebalancer.uuid)
+        self.account.storage.save(<-rebalancer, to: path)
+    }
+
+    // issue and set the capability that the scheduler will use to call back into this rebalancer
+    access(self) fun setSelfCapability(
+        uuid: UInt64,
+    ) {
+        let selfCap = self.account.capabilities.storage.issue<auth(FlowTransactionScheduler.Execute) &{FlowTransactionScheduler.TransactionHandler}>(self.getPath(uuid: uuid))
+        // The Rebalancer is stored in the contract storage (storeRebalancer),
+        // it needs a capability pointing to itself to pass to the scheduler.
+        // We issue this capability here and set it on the Rebalancer, so that when
+        // fixReschedule is called, the Rebalancer can pass it to the transaction scheduler
+        // as a callback for executing scheduled rebalances.
+        self.borrowRebalancer(uuid: uuid)!.setSelfCapability(selfCap)
+    }
+
+    access(self) view fun getPath(uuid: UInt64): StoragePath {
+        return StoragePath(identifier: "FlowCreditMarket.RebalancerV1\(uuid)")!
+    }
+
+    init() {
+        self.adminCapabilityStoragePath = StoragePath(identifier: "FlowCreditMarket.RebalancerPaidV1.Admin")!
+        self.storageAdminPath = self.adminCapabilityStoragePath
+        self.defaultRecurringConfig = nil
+        let admin <- create Admin()
+        self.account.storage.save(<-admin, to: self.storageAdminPath)
+    }
+}