FlowALP (FlowALPv0) - DeFi Lending Protocol on Flow
Naming: FlowALP refers to the protocol. The current Cadence implementation in this repo is the FlowALPv0 contract (plus supporting v1 contracts like FlowALPRebalancerv1, FlowALPRebalancerPaidv1, and FlowALPSupervisorv1).
๐ Project Status
- Contract: โ
Implemented in Cadence (token-agnostic via
FungibleToken.Vault)
- Tests: โ
Cadence test suite under
cadence/tests/ (*_test.cdc)
- Coverage: ๐ Run
flow test --cover locally (coverage artifacts are not committed)
- Documentation: โ
Complete
- Standards: โ
Uses
FungibleToken + integrates with DeFiActions
- FlowVault Removal: โ
FlowVault is not required by the
FlowALPv0 implementation (legacy cadence/contracts/AlpenFlow_dete_original.cdc remains for reference)
๐ฏ Integration Milestones
Current Status (Tracer Bullet Phase)
- โ
Smart Contract Integration: FlowALP provides sink/source interfaces for token swapping
- โ
Development & Testing: Automated testing framework for FlowALP and DefiActions
- โ
Repository Structure: FlowALP code in this repo; DeFiActions comes from the
FlowActions/ submodule
- ๐ Test Coverage: Working towards comprehensive test suite
- ๐ AMM Integration: Currently using dummy swapper, real AMM deployment planned
Upcoming (Limited Beta)
- โ
Documentation: First pass documentation of FlowALP (this README)
- โ
Testing: Extensive test suite for FlowALP and DefiActions
- ๐ Sample Code: DefiActions sample code and tutorials needed
- ๐ Advanced Features: Per-user limits and controlled testing capabilities
Future (Open Beta)
- โ
Open Access: Full public access to FlowALP and DefiActions
- ๐ Documentation: Improved documentation and tutorials
- โ
Sample Code: Complete tutorials for DefiActions integration
๐ฆ About FlowALP
FlowALP is a decentralized lending and borrowing protocol built on the Flow blockchain. This repository contains the current Cadence implementation deployed as the FlowALPv0 contract. It is token-agnostic (operates over any FungibleToken.Vault) and integrates with DeFi Actions for composability.
Key Features
- Token Agnostic: Supports any
FungibleToken.Vault implementation (no FlowVault dependency)
- DeFi Actions Integration: Composable with other DeFi protocols via Sink/Source interfaces
- Vault Operations: Secure deposit and withdraw functionality
- Position Management: Create and manage lending/borrowing positions
- Interest Mechanics: Compound interest calculations with configurable rates
- Health Monitoring: Real-time position health calculations and overdraft protection
- Access Control: Secure entitlement-based access with proper authorization
Technical Highlights
- Provides
DeFiActions.Sink and DeFiActions.Source for DeFi composability
- Uses scaled balance tracking with
UFix128 interest indices for efficient interest accrual
- Supports multiple positions per pool with independent tracking
- Includes a deposit-capacity mechanism for rate limiting and fair throughput
๐งช Test Suite
The project includes comprehensive tests covering all functionality. IMPORTANT: On a fresh clone, you must install dependencies before running tests.
# First-time setup: Install dependencies
flow deps install
# Run all tests using the test runner script (RECOMMENDED)
./run_tests.sh
# Alternative: Run all tests directly
flow test --cover
# Run specific test file
flow test cadence/tests/position_lifecycle_happy_test.cdc
Test Results Summary
The suite includes test files under cadence/tests/:
- โ
Core vault operations and token state management
- โ
Position lifecycle (creation, deposits, withdrawals, rebalancing)
- โ
Interest accrual and rate calculations (debit/credit, insurance)
- โ
Position health constraints and liquidation
- โ
Governance parameters and access control
- โ
Stability and insurance collection mechanisms
- โ
Auto-rebalancing (overcollateralized and undercollateralized)
- โ
Security tests (type spoofing, recursive withdrawal)
- โ
Integration tests and platform compatibility
- โ
Mathematical precision (FlowALPMath, interest curves)
For detailed test running instructions, see TEST_RUNNING_INSTRUCTIONS.md
๐ Quick Start
Prerequisites
Installation
- Clone the repository:
git clone https://github.com/onflow/FlowALP.git
cd FlowALP
git submodule update --init --recursive
- Install dependencies (REQUIRED):
flow deps install
- Run tests:
# Recommended: Use the test runner script
./run_tests.sh
# Alternative: Run directly
flow test --cover
Deploy to Emulator
- Start the Flow emulator:
flow emulator --start
- Deploy the contracts:
flow project deploy --network=emulator
๐ฆ Project Structure
FlowALP/
โโโ cadence/
โ โโโ contracts/
โ โ โโโ FlowALPv0.cdc # Main lending protocol contract
โ โ โโโ FlowALPRebalancerv1.cdc # Rebalancer (scheduled/manual)
โ โ โโโ FlowALPRebalancerPaidv1.cdc # Managed rebalancer service
โ โ โโโ FlowALPSupervisorv1.cdc # Supervisor/registry utilities
โ โ โโโ mocks/ # Mock contracts used by tests
โ โโโ lib/
โ โ โโโ FlowALPMath.cdc # Shared math helpers (UFix128)
โ โโโ tests/
โ โ โโโ test_helpers.cdc # Shared test utilities
โ โ โโโ position_lifecycle_happy_test.cdc
โ โ โโโ interest_accrual_integration_test.cdc
โ โ โโโ ... # Other test files
โ โโโ transactions/ # Transaction templates
โ โโโ scripts/ # Query scripts
โโโ FlowActions/
โ โโโ cadence/contracts/interfaces/
โ โโโ DeFiActions.cdc # DeFi Actions interface
โโโ imports/ # Generated Flow standard contracts (`flow deps install`)
โโโ flow.json # Flow configuration
โโโ run_tests.sh # Test runner
โโโ README.md # This file
๐ง Contract Architecture
Core Components
- Pool: Main lending pool managing positions and reserves
- Position: User positions tracking deposits and borrows
- TokenState: Per-token state including interest indices
- FlowALP Sink/Source: DeFi Actions integration for composability
Key Interfaces
FungibleToken.Vault: Standard token operations
DeFiActions.Sink/Source: DeFi protocol composability
- Entitlements:
FlowALPModels.EParticipant, FlowALPModels.EPosition, FlowALPModels.EGovernance, FlowALPModels.ERebalance
๐ ๏ธ Development
Creating a Position
The FlowALPv0 contract uses entitlements and capability-based access. This repo provides transaction templates for common operations:
- Create and store the Pool (admin):
cadence/transactions/flow-alp/pool-factory/create_and_store_pool.cdc
- Grant and claim the beta Pool capability (admin/user):
cadence/transactions/flow-alp/beta/publish_beta_cap.cdc and cadence/transactions/flow-alp/beta/claim_and_save_beta_cap.cdc
- Create a Position (user):
cadence/transactions/flow-alp/position/create_position.cdc (uses pushToDrawDownSink to control auto-borrowing)
Running Tests
On a fresh clone, always install dependencies first:
# Step 1: Install dependencies (REQUIRED)
flow deps install
# Step 2: Run tests using the test runner script (RECOMMENDED)
./run_tests.sh
# Alternative: Run all tests directly
flow test --cover
# Run specific test file
flow test cadence/tests/interest_accrual_integration_test.cdc
# Run specific test by name
flow test cadence/tests/interest_curve_advanced_test.cdc --name test_exact_compounding_verification_one_year
๐ Documentation
Current Documentation
Planning & Roadmap
๐ค Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
๐ License
This project is licensed under the MIT License.
๐ Resources