BTR Supply Contracts

Concentrated Liquidity Position Manager

---

Table of Contents

• Introduction
• Key Features & Innovations
• Repository Overview
• EVM Architecture (Diamond Standard)
• Getting Started
• Development Workflow
• Testing
• Releasing
• Key Scripts
• Contributing
• Project Evolution & Inspirations
• License

Introduction

BTR (Bayesian True Range), or simply 'Better', is the first open and market-aware Automated Liquidity Manager (ALM) designed for concentrated liquidity AMMs like Uniswap V3/V4, Algebra DEX, Raydium, Orca, and more.

Concentrated Liquidity AMMs offer superior capital efficiency but require active management, similar to traditional market-making. Existing ALM solutions often fall short due to:

• Lagging market data and overlooked volatility.
• Inefficient or opaque rebalancing strategies.
• Lack of true market awareness beyond a single pool.
• Complex user experiences.

BTR aims to solve these issues through a two-part system:

1. BTR Markets (Data Layer): A transparent, high-frequency data aggregator tracking prices, volumes, and depth across numerous CEXs and DEXs. It provides open statistical estimators for trend, volatility, and momentum.
2. BTR Supply (On-Chain ALM): The smart contract layer that utilizes insights from BTR Markets to execute an adaptive, transparent market-making strategy. It focuses on providing robust, auto-compounding vaults with a simplified user experience across multiple blockchains.

This repository contains the smart contracts for BTR Supply.

Key Features & Innovations

BTR Supply incorporates several unique features designed to maximize efficiency and yield:

• Predictive Range Optimization: Liquidity ranges are determined by a perpetually optimized, market-specific predictive algorithm trained on high-fidelity tick and depth data from BTR Markets. The precise triggering rules for rebalancing remain off-chain for strategic reasons but are designed for future verifiability by liquidity providers.
• MEV Protection: All protocol swaps and upkeep operations are shielded from MEV (Maximal Extractable Value) through techniques like pseudo-random execution timing, non-deterministic rule application, and the use of MEV-protecting relays/RPC nodes.
• Swapping via BTR Swap: All swaps leverage BTR Swap's aggregator, which routes orders across DEXs, and RFQ/intent-based systems to guarantee minimal slippage and fees, directly enhancing LP returns. Historical swapping performance data will be publicly available for audit.
• DEX-Agnostic Vaults: BTR Vaults operate across multiple compatible DEXs simultaneously. For instance, a single USDC-USDT vault on BNB Chain can manage liquidity positions across Uniswap V3, Uniswap V4, PancakeSwap V3, and Thena pools for that pair, automatically arbitraging and rebalancing liquidity between them. This significantly simplifies the user experience, as LPs deposit into a single vault per pair per chain.
• Gas-Efficient ERC-1155 Vaults: Vaults are implemented as ERC-1155 token instances rather than standalone contracts (similar to Uniswap V4 pools). This minimizes deployment overhead and reduces operational gas costs for actions like deposits, withdrawals, and rebalancing.

Repository Overview

This repository houses the smart contract implementations for the BTR Supply ALM system, targeting:

• EVM Chains: Primarily developed using Foundry (./evm).
• Solana: Code located in ./solana.
• Sui: Code located in ./sui.

Key top-level directories:

• ./scripts: Project-wide scripts for tasks like releasing, formatting, and utility functions.
• ./assets: Contains project metadata, descriptions (desc.yml), and potentially other assets like images.

EVM Architecture (Diamond Standard)

The EVM implementation utilizes the Diamond Standard (EIP-2535) for modularity, upgradability, and gas efficiency. The core diamond proxy is implemented in ./evm/src/BTRDiamond.sol.

Key components within ./evm/src:

• Facets (./facets): Individual units of logic plugged into the diamond. Examples include:
  • ALMFacet.sol: Core Automated Liquidity Management logic (position calculation, rebalancing).
  • ERC1155VaultsFacet.sol: Manages LP positions represented as ERC1155 tokens.
  • DEXAdapterFacet.sol (and specific implementations like UniV3AdapterFacet.sol, CakeV3AdapterFacet.sol): Interfaces with different DEX protocols.
  • SwapperFacet.sol: Handles token swaps via registered DEX adapters.
  • ManagementFacet.sol: Protocol parameter management (e.g., pausing).
  • AccessControlFacet.sol: Role-based access control.
  • DiamondCutFacet.sol / DiamondLoupeFacet.sol: Standard diamond upgrade and introspection logic.
  • (Refer to assets/desc.yml for a full list and descriptions)
• Libraries (./libraries): Reusable code modules used by facets. Examples include:
  • LibALM.sol: Core ALM calculations.
  • LibDEXMaths.sol: DEX-specific math (tick calculations, price conversions).
  • LibDiamond.sol: Diamond storage interaction helpers.
  • BTRStorage.sol: Defines the diamond's storage layout (AppStorage pattern).
  • (Refer to assets/desc.yml for a full list and descriptions)
• Scripts (../scripts): Foundry scripts for deployment and contract interaction (DeployDiamond.s.sol, etc.).
• Tests (../tests): Unit and integration tests.

Getting Started

Prerequisites

• Git: Installation Guide
• Foundry: Installation Guide (Installs forge, cast, anvil)
• Python: >= 3.10 recommended.
• uv: Fast Python package installer/resolver. Installation Guide
• pre-commit: Git hook manager. Installation Guide

Installation

1. Clone the repository:

   git clone <repository_url>
   cd contracts # Or your cloned directory name

2. Install dependencies and setup hooks:

   make install-deps

   This command will:

   • Run scripts/install_deps.sh to ensure necessary system dependencies are present.
   • Use uv sync to create a virtual environment (if needed) and install Python packages listed in pyproject.toml.
   • Install git hooks using pre-commit for automated formatting, linting, and commit checks.

Environment Configuration

Certain operations, particularly integration tests involving chain forks or deployments, require environment variables (e.g., RPC URLs, private keys).

• Copy the example environment file:

  cp evm/.env.example evm/.env

• Edit evm/.env and populate it with your specific values. Never commit your .env file.

Development Workflow

Formatting

Ensure code conforms to project standards:

make format

This runs forge fmt for Solidity and custom formatters (scripts/format_code.sh, scripts/format_headers.py).

Linting

Check and fix Python code style using Ruff:

make python-lint-fix

Git Hooks (Pre-commit)

The pre-commit hooks installed via make install-deps automatically run checks before certain git actions. The configured hooks include:

• pre-commit: Runs formatters (forge fmt, custom scripts) and linters (ruff).
• commit-msg: Validates commit message format using scripts/check_name.py -c.
• pre-push: Validates branch name and commit messages before pushing using scripts/check_name.py -p.
• post-checkout: Can be used for environment synchronization after switching branches.

These ensure code quality and consistency.

Testing

Run the test suite using Foundry:

make test

This command typically executes scripts/test.sh, which runs forge test.

• Unit Tests: Located in evm/tests/unit, focusing on isolated contract logic.
• Integration Tests: Located in evm/tests/integration, verifying interactions between facets and external contracts, often using mainnet forks (configured via evm/.env). See evm/tests/integration/spec.md for detailed test scenarios.

Releasing

The release process is automated using Make commands:

# For a new patch version (e.g., 0.1.0 -> 0.1.1)
make publish-patch

# For a new minor version (e.g., 0.1.1 -> 0.2.0)
make publish-minor

# For a new major version (e.g., 0.2.0 -> 1.0.0)
make publish-major

These commands execute scripts/release.sh, which in turn runs scripts/release.py. The process involves:

1. Checking if the current branch is main.
2. Calculating the next version number.
3. Updating the version in pyproject.toml.
4. Generating/updating CHANGELOG.md based on commit messages since the last tag (using prefixes like [feat], [fix], [refac], etc.).
5. Committing the version bump and changelog changes ([ops] Release vX.Y.Z).
6. Creating a Git tag (vX.Y.Z).
7. Pushing the commit and tag to the origin remote.

Make sure your commit messages follow the convention expected by scripts/release.py (see COMMIT_PREFIX_MAP in the script) for accurate changelog generation.

Key Scripts

Beyond testing and releasing, several utility scripts exist in ./scripts:

• generate_deployer.py: Generates the DiamondDeployer.gen.sol contract used in deployment scripts based on facets.json.
• get_swap_data.sh: Example script demonstrating how to use an external btr-swap tool to fetch optimal swap data from aggregators.
• check_name.py: Validates branch names and commit messages (used by pre-commit hooks).
• format_code.sh / format_headers.py: Code formatting utilities.

Project Evolution & Inspirations

BTR Supply originated as a fork of Arrakis V2, subsequently extended to support a wider range of DEXs including Uniswap V3 forks and Algebra DEX deployments. Over time, it has evolved into a largely re-implemented, optimized, and more comprehensive liquidity management solution.

While now distinct, BTR Supply draws inspiration from pioneering work in the ALM space, including:

• Arrakis Finance (V2 & V3/Modular)
• Maverick Protocol
• Steer Protocol
• Kamino Liquidity

Contributing

Please follow standard development practices: lint code, ensure tests pass, and adhere to commit message conventions for automated changelog generation. Refer to the project's contribution guidelines in ./CONTRIBUTING.md for more details.

License

This project is licensed under the MIT License - see the ./LICENSE file for details.