Add Strategy composition & AutoBalancer management contracts

.github/workflows/cadence_tests.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on: pull_request
+
+jobs:
+  tests:
+    name: Flow CLI Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GH_PAT }}
+          submodules: "true"
+      - 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 tests
+        run: flow test --cover --covercode="contracts" --coverprofile="coverage.lcov" ./cadence/tests/*_test.cdc

.gitmodules

@@ -1,3 +1,3 @@
 [submodule "DeFiBlocks"]
 	path = DeFiBlocks
-	url = https://github.com/onflow/DeFiBlocks
+	url = git@github.com:onflow/DeFiBlocks.git

cadence/contracts/TidalYieldAutoBalancers.cdc

@@ -0,0 +1,123 @@
+// standards
+import "Burner"
+import "FungibleToken"
+// DeFiBlocks
+import "DFB"
+
+/// TidalYieldAutoBalancers
+///
+/// This contract deals with the storage, retrieval and cleanup of DeFiBlocks AutoBalancers as they are used in
+/// TidalYield defined Strategies.
+///
+/// AutoBalancers are stored in contract account storage at paths derived by their related DFB.UniqueIdentifier.id
+/// which identifies all DeFiBlocks 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
+///
+access(all) contract TidalYieldAutoBalancers {
+
+    /// The path prefix used for StoragePath & PublicPath derivations
+    access(all) let pathPrefix: String
+
+    /* --- PUBLIC METHODS --- */
+
+    /// Returns the path (StoragePath or PublicPath) at which an AutoBalancer is stored with the associated
+    /// UniqueIdentifier.id.
+    access(all) view fun deriveAutoBalancerPath(id: UInt64, storage: Bool): Path {
+        return storage ? StoragePath(identifier: "\(self.pathPrefix)\(id)")! : PublicPath(identifier: "\(self.pathPrefix)\(id)")!
+    }
+
+    /// Returns an unauthorized reference to an AutoBalancer with the given UniqueIdentifier.id value. If none is
+    /// configured, `nil` will be returned.
+    access(all) fun borrowAutoBalancer(id: UInt64): &DFB.AutoBalancer? {
+        let publicPath = self.deriveAutoBalancerPath(id: id, storage: false) as! PublicPath
+        return self.account.capabilities.borrow<&DFB.AutoBalancer>(publicPath)
+    }
+
+    /* --- 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.
+    access(account) fun _initNewAutoBalancer(
+        oracle: {DFB.PriceOracle},
+        vaultType: Type,
+        lowerThreshold: UFix64,
+        upperThreshold: UFix64,
+        rebalanceSink: {DFB.Sink}?,
+        rebalanceSource: {DFB.Source}?,
+        uniqueID: DFB.UniqueIdentifier
+    ): auth(DFB.Auto, DFB.Set, DFB.Get, FungibleToken.Withdraw) &DFB.AutoBalancer {
+
+        // derive paths & prevent collision
+        let storagePath = self.deriveAutoBalancerPath(id: uniqueID.id, storage: true) as! StoragePath
+        let publicPath = self.deriveAutoBalancerPath(id: uniqueID.id, storage: false) as! PublicPath
+        var storedType = self.account.storage.type(at: storagePath)
+        var publishedCap = self.account.capabilities.exists(publicPath)
+        assert(storedType == nil,
+            message: "Storage collision when creating AutoBalancer for UniqueIdentifier.id \(uniqueID.id) at path \(storagePath)")
+        assert(!publishedCap,
+            message: "Published Capability collision found when publishing AutoBalancer for UniqueIdentifier.id \(uniqueID.id) at path \(publicPath)")
+
+        // create & save AutoBalancer
+        let autoBalancer <- DFB.createAutoBalancer(
+                oracle: oracle,
+                vaultType: vaultType,
+                lowerThreshold: lowerThreshold,
+                upperThreshold: upperThreshold,
+                rebalanceSink: rebalanceSink,
+                rebalanceSource: rebalanceSource,
+                uniqueID: uniqueID
+            )
+        self.account.storage.save(<-autoBalancer, to: storagePath)
+        let autoBalancerRef = self._borrowAutoBalancer(uniqueID.id)
+
+        // issue & publish public capability
+        let publicCap = self.account.capabilities.storage.issue<&DFB.AutoBalancer>(storagePath)
+        self.account.capabilities.publish(publicCap, at: publicPath)
+
+        // issue private capability & set within AutoBalancer
+        let authorizedCap = self.account.capabilities.storage.issue<auth(FungibleToken.Withdraw) &DFB.AutoBalancer>(storagePath)
+        autoBalancerRef.setSelfCapability(authorizedCap)
+
+        // ensure proper configuration before closing
+        storedType = self.account.storage.type(at: storagePath)
+        publishedCap = self.account.capabilities.exists(publicPath)
+        assert(storedType == Type<@DFB.AutoBalancer>(),
+            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)")
+        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(DFB.Auto, DFB.Set, DFB.Get, FungibleToken.Withdraw) &DFB.AutoBalancer {
+        let storagePath = self.deriveAutoBalancerPath(id: id, storage: true) as! StoragePath
+        return self.account.storage.borrow<auth(DFB.Auto, DFB.Set, DFB.Get, FungibleToken.Withdraw) &DFB.AutoBalancer>(
+                from: storagePath
+            ) ?? panic("Could not borrow reference to AutoBalancer with UniqueIdentifier.id \(id) from StoragePath \(storagePath)")
+    }
+
+    /// Called by strategies defined in the TidalYield account which leverage account-hosted AutoBalancers when a
+    /// Strategy is burned
+    access(account) fun _cleanupAutoBalancer(id: UInt64) {
+        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
+        self.account.capabilities.storage.forEachController(forPath: storagePath, fun(_ controller: &StorageCapabilityController): Bool {
+            controller.delete()
+            return true
+        })
+        // load & burn the AutoBalancer
+        let autoBalancer <-self.account.storage.load<@DFB.AutoBalancer>(from: storagePath)
+        Burner.burn(<-autoBalancer)
+    }
+
+    init() {
+        self.pathPrefix = "TidalYieldAutoBalancer_"
+    }
+}

cadence/contracts/TidalYieldStrategies.cdc

@@ -0,0 +1,210 @@
+// standards
+import "FungibleToken"
+import "FlowToken"
+// DeFiBlocks
+import "DFBUtils"
+import "DFB"
+import "SwapStack"
+// Lending protocol
+import "TidalProtocol"
+// TidalYield platform
+import "Tidal"
+import "TidalYieldAutoBalancers"
+// tokens
+import "YieldToken"
+import "MOET"
+// mocks
+import "MockOracle"
+import "MockSwapper"
+
+/// THIS CONTRACT IS A MOCK AND IS NOT INTENDED FOR USE IN PRODUCTION
+/// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+///
+/// TidalYieldStrategies
+///
+/// This contract defines Strategies used in the TidalYield platform.
+///
+/// A Strategy instance can be thought of as objects wrapping a stack of DeFiBlocks connectors wired together to
+/// (optimally) generate some yield on initial deposits. Strategies can be simple such as swapping into a yield-bearing
+/// asset (such as stFLOW) or more complex DeFiBlocks stacks.
+///
+/// A StrategyComposer is tasked with the creation of a supported Strategy. It's within the stacking of DeFiBlocks
+/// connectors that the true power of the components lies.
+///
+access(all) contract TidalYieldStrategies {
+
+    /// Canonical StoragePath where the StrategyComposerIssuer should be stored
+    access(all) let IssuerStoragePath: StoragePath
+
+    /// This is the first Strategy implementation, wrapping a TidalProtocol Position along with its related Sink &
+    /// Source. While this object is a simple wrapper for the top-level collateralized position, the true magic of the
+    /// DeFiBlocks is in the stacking of the related connectors. This stacking logic can be found in the
+    /// TracerStrategyComposer construct.
+    access(all) resource TracerStrategy : Tidal.Strategy {
+        /// An optional identifier allowing protocols to identify stacked connector operations by defining a protocol-
+        /// specific Identifier to associated connectors on construction
+        access(contract) let uniqueID: DFB.UniqueIdentifier?
+        access(self) let position: TidalProtocol.Position
+        access(self) var sink: {DFB.Sink}
+        access(self) var source: {DFB.Source}
+
+        init(id: DFB.UniqueIdentifier, collateralType: Type, position: TidalProtocol.Position) {
+            self.uniqueID = id
+            self.position = position
+            self.sink = position.createSink(type: collateralType)
+            self.source = position.createSourceWithOptions(type: collateralType, pullFromTopUpSource: true)
+        }
+
+        // Inherited from Tidal.Strategy default implementation
+        // access(all) view fun isSupportedCollateralType(_ type: Type): Bool
+
+        access(all) view fun getSupportedCollateralTypes(): {Type: Bool} {
+            return { self.sink.getSinkType(): true }
+        }
+        /// Returns the amount available for withdrawal via the inner Source
+        access(all) fun availableBalance(ofToken: Type): UFix64 {
+            return ofToken == self.source.getSourceType() ? self.source.minimumAvailable() : 0.0
+        }
+        /// Deposits up to the inner Sink's capacity from the provided authorized Vault reference
+        access(all) fun deposit(from: auth(FungibleToken.Withdraw) &{FungibleToken.Vault}) {
+            self.sink.depositCapacity(from: from)
+        }
+        /// Withdraws up to the max amount, returning the withdrawn Vault. If the requested token type is unsupported,
+        /// an empty Vault is returned.
+        access(FungibleToken.Withdraw) fun withdraw(maxAmount: UFix64, ofToken: Type): @{FungibleToken.Vault} {
+            if ofToken != self.source.getSourceType() {
+                return <- DFBUtils.getEmptyVault(ofToken)
+            }
+            return <- self.source.withdrawAvailable(maxAmount: maxAmount)
+        }
+        /// Executed when a Strategy is burned, cleaning up the Strategy's stored AutoBalancer
+        access(contract) fun burnCallback() {
+            TidalYieldAutoBalancers._cleanupAutoBalancer(id: self.id()!)
+        }
+    }
+
+    /// This StrategyComposer builds a TracerStrategy
+    access(all) resource TracerStrategyComposer : Tidal.StrategyComposer {
+        /// Returns the Types of Strategies composed by this StrategyComposer
+        access(all) view fun getComposedStrategyTypes(): {Type: Bool} {
+            return { Type<@TracerStrategy>(): true }
+        }
+
+        /// Returns the Vault types which can be used to initialize a given Strategy
+        access(all) view fun getSupportedInitializationVaults(forStrategy: Type): {Type: Bool} {
+            return { Type<@FlowToken.Vault>(): true }
+        }
+
+        /// Returns the Vault types which can be deposited to a given Strategy instance if it was initialized with the
+        /// provided Vault type
+        access(all) view fun getSupportedInstanceVaults(forStrategy: Type, initializedWith: Type): {Type: Bool} {
+            return { Type<@FlowToken.Vault>(): true }
+        }
+
+        /// Composes a Strategy of the given type with the provided funds
+        access(all) fun createStrategy(
+            _ type: Type,
+            uniqueID: DFB.UniqueIdentifier,
+            withFunds: @{FungibleToken.Vault}
+        ): @{Tidal.Strategy} {
+            // this PriceOracle is mocked and will be shared by all components used in the TracerStrategy
+            let oracle = MockOracle.PriceOracle()
+
+            // assign token types
+            let collateralType = withFunds.getType()
+            let yieldTokenType = Type<@YieldToken.Vault>()
+            let moetTokenType = Type<@MOET.Vault>()
+            let flowTokenType = Type<@FlowToken.Vault>()
+
+            // configure and AutoBalancer for this stack
+            let autoBalancer = TidalYieldAutoBalancers._initNewAutoBalancer(
+                oracle: oracle,             // used to determine value of deposits & when to rebalance
+                vaultType: yieldTokenType,  // the type of Vault held by the AutoBalancer
+                lowerThreshold: 0.95,       // set AutoBalancer to pull from rebalanceSource when balance is 5% below value of deposits
+                upperThreshold: 1.05,       // set AutoBalancer to push to rebalanceSink when balance is 5% below value of deposits
+                rebalanceSink: nil,         // nil on init - will be set once a PositionSink is available
+                rebalanceSource: nil,       // nil on init - not set for TracerStrategy
+                uniqueID: uniqueID          // identifies AutoBalancer as part of this Strategy
+            )
+            // enables deposits of YieldToken to the AutoBalancer
+            let abaSink = autoBalancer.createBalancerSink() ?? panic("Could not retrieve Sink from AutoBalancer with id \(uniqueID.id)")
+            // enables withdrawals of YieldToken from the AutoBalancer
+            let abaSource = autoBalancer.createBalancerSource() ?? panic("Could not retrieve Sink from AutoBalancer with id \(uniqueID.id)")
+
+            // init MOET <> YIELD swappers
+            //
+            // MOET -> YieldToken
+            let moetToYieldSwapper = MockSwapper.Swapper(
+                    inVault: moetTokenType,
+                    outVault: yieldTokenType,
+                    uniqueID: uniqueID
+                )
+            // YieldToken -> MOET
+            let yieldToMoetSwapper = MockSwapper.Swapper(
+                    inVault: yieldTokenType,
+                    outVault: moetTokenType,
+                    uniqueID: uniqueID
+                )
+
+            // init SwapSink directing swapped funds to AutoBalancer
+            //
+            // Swaps provided MOET to YieldToken & deposits to the AutoBalancer
+            let abaSwapSink = SwapStack.SwapSink(swapper: moetToYieldSwapper, sink: abaSink, uniqueID: uniqueID)
+            // Swaps YieldToken & provides swapped MOET, sourcing YieldToken from the AutoBalancer
+            let abaSwapSource = SwapStack.SwapSource(swapper: yieldToMoetSwapper, source: abaSource, uniqueID: uniqueID)
+
+            // open a TidalProtocol position
+            let position = TidalProtocol.openPosition(
+                    collateral: <-withFunds,
+                    issuanceSink: abaSwapSink,
+                    repaymentSource: abaSwapSource,
+                    pushToDrawDownSink: true
+                )
+            // get Sink & Source connectors relating to the new Position
+            let positionSink = position.createSinkWithOptions(type: collateralType, pushToDrawDownSink: true)
+            let positionSource = position.createSourceWithOptions(type: collateralType, pullFromTopUpSource: true) // TODO: may need to be false
+
+            // init YieldToken -> FLOW Swapper
+            let yieldToFlowSwapper = MockSwapper.Swapper(
+                    inVault: yieldTokenType,
+                    outVault: flowTokenType, // TODO: before 
+                    uniqueID: uniqueID
+                )
+            // allows for YieldToken to be deposited to the Position
+            let positionSwapSink = SwapStack.SwapSink(swapper: yieldToFlowSwapper, sink: positionSink, uniqueID: uniqueID)
+
+            // set the AutoBalancer's rebalance Sink which it will use to deposit overflown value,
+            // recollateralizing the position
+            autoBalancer.setSink(positionSwapSink)
+
+            return <-create TracerStrategy(
+                id: DFB.UniqueIdentifier(),
+                collateralType: collateralType,
+                position: position
+            )
+        }
+    }
+
+    /// This resource enables the issuance of StrategyComposers, thus safeguarding the issuance of Strategies which
+    /// may utilize resource consumption (i.e. account storage). Since TracerStrategy creation consumes account storage
+    /// via configured AutoBalancers
+    access(all) resource StrategyComposerIssuer : Tidal.StrategyComposerIssuer {
+        access(all) view fun getSupportedComposers(): {Type: Bool} {
+            return { Type<@TracerStrategyComposer>(): true }
+        }
+        access(all) fun issueComposer(_ type: Type): @{Tidal.StrategyComposer} {
+            switch type {
+            case Type<@TracerStrategyComposer>():
+                return <- create TracerStrategyComposer()
+            default:
+                panic("Unsupported StrategyComposer requested: \(type.identifier)")
+            }
+        }
+    }
+
+    init() {
+        self.IssuerStoragePath = StoragePath(identifier: "TidalYieldStrategyComposerIssuer_\(self.account.address)")!
+
+        self.account.storage.save(<-create StrategyComposerIssuer(), to: self.IssuerStoragePath)
+    }
+}