kylefang/alexlab-doc
1
0
Fork 0
mirror of https://github.com/alexgo-io/alexlab-doc.git synced 2026-01-12 06:23:59 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: update Trading Pool v2 documentation with comprehensive v1 to v2 comparison

Browse Source
This commit is contained in:
fiftyeightandeight
2025-12-17 18:35:58 +08:00
parent de532602b4
commit 7f4b05b461
1 changed files with 348 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

443
developers/products/automated-market-making/trading-pool-v2.md
View File

@@ -1,112 +1,188 @@
# Trading Pool v2
## What It Is
## Overview
Trading Pool v2 is an upgrade to ALEX's automated market maker (AMM) for token swaps. It implements the Solidly formula and Clarity v4 security features.
Trading Pool v2 (`amm-pool-v2-02.clar`) is a version of `amm-pool-v2-01.clar` that addresses security issues, accuracy problems, and code quality concerns identified through code review. v2 replaces the power-based Generalized Mean formula with the Solidly formula (`x^n·y + x·y^n = k`) and integrates Clarity v4 `restrict-assets?` for enhanced security.
**Key improvements over v1**:
- Security: Division-by-zero protection, balance underflow prevention, fee validation, input validation
- Accuracy: Improved pow-down/pow-up error model, better threshold handling
- Performance: 60-77% gas cost reduction using native `sqrti` instead of iterative power calculations
- Code Quality: Constants organization, standardized error handling, Clarity 3 compatibility
---
## What Are the Biggest Changes Over v1?
## Changes from v1 to v2
### 1. **New Mathematical Formula (Generalized Mean → Solidly)**
### Security Improvements
**Before (v1)**: Used a power-based Generalized Mean Equation with parameter $$t$$
- Small swaps often failed or returned zero
- High gas costs (expensive transactions)
- Precision issues with decimal amounts
- Formula: $$x^{1-t} + y^{1-t} = L$$
**1. Division-by-Zero Protection**
- Added explicit checks for `balance-x > 0` before division in price calculations
- Prevents runtime errors in edge cases
**Now (v2)**: Uses the Solidly formula, used by Velodrome and Aerodrome DEXs
- All swap sizes work correctly, even tiny amounts
- 60% lower gas costs for most swaps
- Perfect precision for all transaction sizes
- Formula: $$x^n \cdot y + x \cdot y^n = k$$
**2. Balance Underflow Prevention**
- Replaced conditional logic with explicit assertions
- Example: `(asserts! (> balance-y dy) ERR-NO-LIQUIDITY)` before `(- balance-y dy)`
- Applied to: `swap-x-for-y`, `swap-y-for-x`, `reduce-position`
**3. Fee Validation**
- Explicit validation to prevent zero swaps
- Validates: `dx > 0`, `dx > fee`, `fee-rebate <= fee`
**4. Input Validation**
- Added `validate-pool-params` helper function
- Validates: `token-x ≠ token-y`, `factor <= ONE_8`
- Applied to: `create-pool`, `add-to-position`
**5. Threshold Handling**
- Improved handling to prevent division by zero when `t >= ONE_8`
- Safe division because `t-comp` only used when `t < threshold`
### Accuracy Improvements
**1. pow-down/pow-up Error Model**
v1 used `mul-up` which compounded error:
```clarity
(max-error (+ u1 (mul-up raw MAX_POW_RELATIVE_ERROR)))
```
v2 uses direct division with proper rounding:
```clarity
(relative-error-part (if (is-eq raw u0)
u0
(/ (+ (* raw MAX_POW_RELATIVE_ERROR) (- ONE_8 u1)) ONE_8)))
(max-error (if (< relative-error-part MIN_POW_ABSOLUTE_ERROR)
MIN_POW_ABSOLUTE_ERROR
relative-error-part))
```
Changes:
- Removed `mul-up` to avoid compounding error
- Direct division with round-up for error calculation
- Added `MIN_POW_ABSOLUTE_ERROR` constant
- Uses `<=` instead of `<` for comparison
**2. get-switch-threshold Usage**
- Result cached at function start instead of multiple calls
- Reduces redundant computation
### Code Quality Improvements
**1. Constants Organization**
- All constants defined at top (lines 27-58)
- Replaced magic numbers with named constants (e.g., `MAX_UINT`)
**2. Address References**
- Changed from relative (`.executor-dao`) to absolute addresses (`'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.executor-dao'`)
**3. Clarity 3 Compatibility**
- Uses `stacks-block-height` instead of `block-height`
**4. Error Handling**
- Standardized patterns across all functions
---
## What Are the Biggest Changes?
### 1. **New Mathematical Formula (Power-Based → Solidly)**
**Before (v1)**: Used power calculations with `pow-fixed` function
- Small swaps (0.0001 units) often returned zero
- High gas costs: 800k for swaps
- Precision loss when subtracting nearly equal fixed-point numbers
- Example: Pool with 0.1 units each, t=0.05, swap 0.0001 → returned 0
**Now (v2)**: Uses Solidly formula with native `sqrti`
- All swap sizes work correctly
- 60-77% gas reduction (180k-320k for swaps)
- Closed-form solutions: no iteration needed
- Formula: $$x^n \cdot y + x \cdot y^n = k$$ where $$n \in \{1, 2\}$$
### 2. **Enhanced Security with restrict-assets?**
**Before (v1)**: Relied on trust that tokens behave correctly
**Before (v1)**: Relied on token behavior
**Now (v2)**: Built-in protection against malicious tokens using Clarity v4's `restrict-assets?`
- Automatic rollback if a token tries to transfer more than allowed
**Now (v2)**: Clarity v4 `restrict-assets?` enforcement
- Automatic rollback if token transfers exceed specified amount
- Protection against reentrancy attacks
- Enforced swap amounts—what you see is what you get
Malicious tokens cannot transfer more than the specified amount due to `restrict-assets?` enforcement.
- Enforced swap amounts
### 3. **Better Price Accuracy**
**Before**: Power calculations could lose precision, especially for stablecoin pairs
**Before (v1)**: Power calculations lost precision in small swaps
**Now**: Uses closed-form mathematical solutions with native blockchain functions
- Accurate prices for all pool sizes
- Consistent behavior whether the pool has $100 or $100M
- No iterative calculations (faster and more predictable)
**Now (v2)**: Closed-form solutions with native `sqrti`
- Accurate for all pool sizes
- Scale-invariant behavior
- No precision loss from subtracting similar numbers
---
## Why Are We Introducing These Changes?
## Problems Addressed
### Problem 1: Small Swaps Were Failing
### Problem 1: Small Swap Precision Loss
**Issue**: Small swaps (0.001 STX or less) failed or returned zero.
**Root cause**: For small swaps, `x^α - (x+dx)^α` loses precision when subtracting nearly equal fixed-point numbers.
**Root cause**: Power calculations in v1 lose precision when numbers are close together. Subtracting nearly equal numbers in fixed-point arithmetic causes precision loss.
**Example**:
```
Pool: 0.1 units each, t=0.05 (α=0.95)
Swap: 0.0001 units
v1: Returns 0
v2: Returns 0.00009995 (correct)
```
**Solution**: Solidly formula uses square roots instead of powers, which Stacks blockchain handles natively and accurately through the `sqrti` function. The formula can be solved directly without subtraction of similar numbers.
**Solution**: Solidly formula uses quadratic formula `y' = (-x' + √(x'² + 4k/x')) / 2` with native `sqrti`, avoiding subtraction of similar numbers.
### Problem 2: Gas Costs Were Too High
### Problem 2: High Gas Costs
**Issue**: High gas costs relative to swap size.
**Root cause**: Complex power calculations require many computational steps and iterations.
**Root cause**: Power calculations require multiple iterations to achieve acceptable precision.
**Solution**: Solidly formula has closed-form solutions:
- n=1 (volatile): Direct division, 77% gas reduction (800k → 180k)
- n=2 (stable): Quadratic formula with `sqrti`, 60% gas reduction (800k → 320k)
**Solution**: Solidly formula has direct mathematical solutions (no iteration needed):
- Volatile pairs ($$t \geq 0.8$$, mapped to $$n=1$$): 77% gas reduction
- Stable pairs ($$t < 0.8$$, mapped to $$n=2$$): 60% gas reduction
### Problem 3: Security Gaps
### Problem 3: Security Concerns
**Root cause**: v1 relied on token behavior without blockchain-level enforcement.
**Issue**: Risk of malicious token behavior.
**Solution**:
- Clarity v4 `restrict-assets?` enforces transfer limits at blockchain level
- Explicit validation: division-by-zero protection, balance underflow prevention, fee validation
- Input validation via `validate-pool-params` helper
**Root cause**: v1 relies on tokens following expected behavior. Contract-level enforcement adds an additional security layer.
### Problem 4: Scale Dependence
**Solution**: Clarity v4's `restrict-assets?` enforces rules at the blockchain level:
- Tokens can't transfer more than specified amounts
- Failed swaps roll back automatically
- No way to bypass the restrictions
**Root cause**: v1 formula behavior varied with absolute pool size due to fixed-point precision.
### Problem 4: Inconsistent Behavior
**Issue**: Inconsistent swap results across pools of different sizes.
**Root cause**: v1 formula behavior varies with absolute pool size due to fixed-point precision limitations.
**Solution**: Solidly formula is "scale-invariant"—works the same whether the pool has $100 or $100M in liquidity.
**Solution**: Solidly formula is scale-invariant—pool with [1, 1] behaves identically to [1000, 1000] in terms of price impact and slippage.
---
## What Needs to Be in Place Before We Can Go Live?
## Implementation Status
### Current Status
### Development Complete (December 2025)
✅ **Core Implementation**: Complete
- New Solidly formula implemented and tested
- Solidly formula implemented and tested
- `restrict-assets?` security integration complete
- Gas optimizations applied
- All existing v1 features working
- 44/44 tests passing
✅ **Development Environment**: Complete
- Clarinet SDK upgraded to v3.11.0 with full Clarity v4 support
- Comprehensive test suite passing
- Security scenarios validated (normal, token drain, STX drain)
- Mathematical properties verified (price bounds, function symmetry)
- Error code behavior confirmed
⏸️ **Development Environment**: Blocked
- Clarity v4 is already activated on Stacks mainnet
- Clarinet CLI v3.10.0 includes full `restrict-assets?` support (type-checking works)
- **Blocker**: Clarinet SDK v3.8.1 (used by test runner) does not yet support `restrict-assets?`
- Cannot run comprehensive tests until SDK is updated to match CLI capabilities
- Contract compiles and type-checks successfully, but test execution fails
- Waiting for SDK update before implementing comprehensive test coverage
📋 **Security Audit**: Pending
- Will be scheduled once development environment testing is completed
- Comprehensive audit of both mathematical implementation and security features
📋 **Next Steps**: External Security Audit
- Contract ready for professional security audit
- Testnet deployment for user testing
- Mainnet deployment via DAO proposal after audit approval
### Deployment Approach
@@ -155,7 +231,7 @@ All existing pools will automatically benefit from the improved formula and enha
### Gas Cost Comparison (Simnet Testing)
| Operation | v1 | v2 (n=2) | v2 (n=1) | Reduction |
|-----------|----|---------|---------|----|
|-----------|-------|-----------|-----------|-----------|
| create-pool | 150k | 130k | 110k | 13-27% |
| add-to-position | 200k | 160k | 140k | 20-30% |
| **swap** | **800k** | **320k** | **180k** | **60-77%** |
@@ -170,6 +246,119 @@ All existing pools will automatically benefit from the improved formula and enha
| 1e-4 to 1e-2 | 5% | 0% |
| > 1e-2 | <1% | 0% |
### Contract Size
| Metric | v1 | v2 |
|--------|-----|-----|
| Lines | 761 | 728 |
| Functions | 48 | 52 |
| Tests | 18 | 22 |
---
## Alternative Methodologies Evaluated
Before selecting Solidly, we evaluated several alternative AMM formulas:
### 1. Wombat Exchange
**Invariant**: `(x - A/x) + (y - A/y) = D`
- Pros: Good precision for stable pairs, proven in production
- Cons: Not scale-invariant (A must equal `α × L²` for consistent behavior), requires custom square root
### 2. Solidly (Selected)
**Invariant**: `x^n·y + x·y^n = k`
- Pros: Scale-invariant, closed-form for n=1,2 using native `sqrti`, deployed on Solidly, Velodrome, Aerodrome
- Cons: Limited to n≤2 for closed-form solutions
### 3. Saddle Finance
**Invariant**: `A(x + y) + xy = k`
- Pros: Simpler than Curve, decent for stable pairs
- Cons: Not scale-invariant (similar to Wombat), limited production usage
### 4. Hybrid Constant Function
**Invariant**: `w(x + y) + (1-w)(xy)/(x+y) = k`
- Pros: Interesting theoretical properties
- Cons: Limited production testing, partially scale-invariant
### Selection Rationale
| Criterion | Wombat | Solidly | Saddle | Hybrid |
|-----------|--------|---------|--------|--------|
| Scale Invariant | No | Yes | No | Partial |
| Small Swap Precision | Good | Excellent | Good | Moderate |
| Native Clarity Support | No (custom sqrt) | Yes (sqrti) | No | Yes |
| Production Use | Yes | Yes | Limited | No |
**Decision**: Solidly selected for scale invariance and native `sqrti` support.
### Why Not n≥3?
n=3+ requires Newton's method iteration:
- Non-deterministic gas costs
- Precision issues in fixed-point
- <1% of pools would use it
Decision: Prioritize closed-form solutions (n=1,2).
---
## Implementation Details
### Invariant Calculation
```clarity
(define-read-only (get-invariant (balance-x uint) (balance-y uint) (t uint))
(let ((n (t-to-n t)))
(if (is-eq n u1)
(* u2 (mul-down balance-x balance-y)) ;; k = 2xy
;; n=2: k = x²y + xy²
(let (
(x-squared (mul-down balance-x balance-x))
(y-squared (mul-down balance-y balance-y))
)
(+ (mul-down x-squared balance-y) (mul-down balance-x y-squared))))))
```
### Swap Calculation (n=2)
```clarity
;; Solve: (y')² + x'·y' - k/x' = 0
(let (
(discriminant (+ x-new-squared (div-down (* u4 k) x-new)))
(sqrt-discriminant (sqrti (* discriminant ONE_8)))
(y-new (/ (- sqrt-discriminant x-new) u2))
)
(- balance-y y-new))
```
### Mapping Strategy
```clarity
(define-read-only (t-to-n (t uint))
(if (< t (get-switch-threshold)) ;; Default: 0.8
u2 ;; Stable pairs
u1 ;; Volatile pairs
))
```
| ALEX t | Solidly n | Formula | Use Case |
|--------|-----------|---------|----------|
| 0.8-1.0 | n=1 | 2xy = k | Volatile |
| 0.2-0.8 | n=2 | x²y + xy² = k | Semi-stable |
| <0.2 | n=2 | x²y + xy² = k | Stable |
### New API Functions
v2 adds 4 read-only functions:
1. `get-y-in-given-x-out` - Calculate Y needed when withdrawing X
2. `get-x-in-given-y-out` - Calculate X needed when withdrawing Y
3. `get-x-given-price` - Calculate X to reach target price
4. `get-y-given-price` - Calculate Y to reach target price
---
## Frequently Asked Questions
@@ -196,14 +385,16 @@ A: The Solidly formula is used by:
- Velodrome Finance: ~$50M daily volume
- Aerodrome: ~$100M daily volume
- Solidly (original): Production deployment
- Combined: $150M+ daily volume
Implementation tested on Stacks testnet. Security audit scheduled before mainnet deployment.
Implementation tested on Stacks testnet with 44/44 tests passing. Security audit scheduled before mainnet deployment.
**Q: When can we expect deployment?**
A: Deployment timeline depends on:
1. ⏸️ **Current Blocker**: Clarinet SDK update to support `restrict-assets?` (CLI v3.10.0 supports it, but SDK v3.8.1 does not)
2. Completing comprehensive testing with the updated SDK tooling
3. Security audit scheduling and completion
A: Development is complete with 44/44 tests passing. Timeline:
1. ✅ **Development & Testing**: Complete (Clarinet SDK v3.11.0 with Clarity v4 support)
2. 📋 **External Security Audit**: Contract ready for professional audit
3. 📋 **Testnet Deployment**: User testing after audit completion
4. 📋 **Mainnet Deployment**: Via DAO proposal after audit approval
Updates will be provided as milestones are reached.
@@ -227,11 +418,11 @@ Plus four new functions for advanced use cases.
| Phase | Status | Notes |
|-------|--------|-------|
| Core Development | ✅ Complete | Solidly formula + restrict-assets? implemented |
| Initial Testing | ✅ Complete | Comprehensive test suite passing |
| SDK Tooling | ⏸️ Blocked | Clarinet CLI v3.10.0 supports restrict-assets?, but SDK v3.8.1 does not |
| Final Testing | ⏸️ Blocked | Waiting for SDK update to run tests |
| Security Audit | 📋 Planned | After testing completion |
| Mainnet Deployment | 📋 Planned | After audit approval |
| SDK Tooling | ✅ Complete | Clarinet SDK v3.11.0 with Clarity v4 support |
| Testing | ✅ Complete | 44/44 tests passing (functionality, security, mathematics) |
| Security Audit | 📋 Ready | Contract ready for external audit |
| Testnet Deployment | 📋 Planned | User testing after audit |
| Mainnet Deployment | 📋 Planned | Via DAO proposal after audit approval |
---
@@ -239,23 +430,45 @@ Plus four new functions for advanced use cases.
Trading Pool v2 improvements:
1. **Better Math**: Solidly formula fixes precision issues and reduces gas costs by 60-77%
2. **Enhanced Security**: Clarity v4's `restrict-assets?` provides built-in protection against malicious tokens
3. **Proven Technology**: Used by leading DEXs with billions in cumulative volume
4. **Seamless Upgrade**: Logic-only replacement—no pool migration required
5. **Backward Compatible**: Same API, same $$t$$ parameter, familiar interface
1. **Mathematical Formula**: Solidly formula fixes precision issues and reduces gas costs by 60-77%
2. **Security Enhancements**:
- Clarity v4 `restrict-assets?` for malicious token protection
- Division-by-zero protection, balance underflow prevention, fee validation
- Input validation via `validate-pool-params` helper
3. **Accuracy Improvements**:
- Improved pow-down/pow-up error model
- Better threshold handling
- No precision loss in small swaps
4. **Code Quality**:
- Constants organization, standardized error handling
- Clarity 3 compatibility (`stacks-block-height`)
- Absolute address references
5. **Proven Technology**: Solidly formula used by DEXs with $150M+ daily volume
6. **Backward Compatible**: Same API, same $$t$$ parameter (mapped to $$n$$), same error codes
Deployment occurs as a contract replacement after tooling support and security audits are complete. No user action required.
### Migration
The $$t$$ parameter from v1 remains, mapped to the underlying formula. Existing integrations continue working.
Logic-only upgrade. No pool migration required. No user action required.
### Breaking Changes
- Address references changed from relative to absolute
- Requires Clarity 3 compatible environment
### Non-Breaking Changes
- Public API: All function signatures unchanged
- Error codes: All error codes unchanged
- Return types: All return types unchanged
- Mathematical formulas: Core formulas unchanged (only error handling improved)
---
## Technical Details: The Math Behind v2
### Formula Comparison
### Formula Evolution
**v1 (Generalized Mean)**:
**v1 (Power-Based)**:
$$x^{1-t} + y^{1-t} = L$$
Where $$t$$ is a parameter between 0 and 1:
@@ -263,6 +476,11 @@ Where $$t$$ is a parameter between 0 and 1:
- $$t=0$$: Constant sum (mStable-like)
- $$0<t<1$$: Curve-like behavior
Issues:
- Small swaps lose precision when subtracting nearly equal numbers
- Power calculations require iterative methods
- High gas costs (800k per swap)
**v2 (Solidly)**:
$$x^n \cdot y + x \cdot y^n = k$$
@@ -270,6 +488,11 @@ Where $$n$$ is derived from $$t$$:
- $$t \geq 0.8$$: $$n=1$$ (volatile pairs)
- $$t < 0.8$$: $$n=2$$ (stable pairs)
Improvements:
- Closed-form solutions using native `sqrti`
- No precision loss from subtraction
- 60-77% gas reduction
### Why Solidly?
Alternative AMM formulas were evaluated to address v1 limitations.
@@ -303,39 +526,55 @@ Alternative AMM formulas were evaluated to address v1 limitations.
#### Comprehensive Comparison
| Criterion | v1 (Gen. Mean) | **v2 (Solidly)** | Wombat | Curve | Saddle | Hybrid |
|-----------|----------------|------------------|---------|--------|---------|---------|
| Criterion | v1 (Power) | **v2 (Solidly)** | Wombat | Curve | Saddle | Hybrid |
|-----------|---------------|---------------------|---------|--------|---------|---------|
| **Formula** | $$x^{1-t} + y^{1-t} = L$$ | $$x^n \cdot y + x \cdot y^n = k$$ | $$(x-A/x)+(y-A/y)=D$$ | Complex | $$A(x+y)+xy=k$$ | $$w(x+y)+(1-w)xy/(x+y)=k$$ |
| **Scale Invariant** | Partial | ✅ Yes | ❌ No | ✅ Yes | ❌ No | Partial |
| **Small Swap Precision** | ❌ Poor | ✅ Excellent | Good | ✅ Excellent | Good | Moderate |
| **Native Clarity Support** | Partial (pow issues) | ✅ Yes (sqrti) | ❌ No | ❌ No | Partial | ✅ Yes |
| **Gas Efficiency** | Low | ✅ High | Moderate | Low | Moderate | High |
| **Gas Efficiency** | Low (800k) | ✅ High (180-320k) | Moderate | Low | Moderate | High |
| **Deterministic Gas** | ❌ No (iterations) | ✅ Yes | ❌ No | ❌ No | Moderate | ✅ Yes |
| **Production Use** | ALEX only | ✅ Major DEXs | Yes | ✅ Major DEXs | Limited | No |
| **Daily Volume** | ~$500K | ~$150M+ | ~$20M | ~$100M+ | ~$1M | N/A |
| **Implementation Complexity** | High | Low | Moderate | High | Moderate | Low |
| **Supports All t Values** | ✅ Yes (0-1) | Partial (2 modes) | N/A | N/A | N/A | N/A |
| **Security Features** | Basic | ✅ restrict-assets? | Basic | Basic | Basic | Basic |
### Implementation: Direct Solutions
### Direct Solutions
For $$n=1$$ (volatile pairs):
$$k = 2xy$$
**For $$n=1$$ (volatile pairs)**:
Invariant: $$k = 2xy$$
Given new $$x' = x + dx$$, solve for $$y'$$:
$$y' = \frac{k}{2x'}$$
Output: $$dy = y - y'$$
For $$n=2$$ (stable pairs):
$$k = x^2y + xy^2$$
Gas: 180k per swap (77% reduction from v1)
Given new $$x' = x + dx$$, solve quadratic equation:
$$(y')^2 + x' \cdot y' - \frac{k}{x'} = 0$$
**For $$n=2$$ (stable pairs)**:
Invariant: $$k = x^2y + xy^2$$
Given new $$x' = x + dx$$, factor and rearrange:
$$
\begin{align}
x'y'(x' + y') &= k \\
(y')^2 + x' \cdot y' - \frac{k}{x'} &= 0
\end{align}
$$
Using quadratic formula:
$$y' = \frac{-x' + \sqrt{(x')^2 + 4k/x'}}{2}$$
This uses Clarity's native `sqrti` function for the square root, providing exact results.
Output: $$dy = y - y'$$
Gas: 320k per swap (60% reduction from v1)
This uses Clarity's native `sqrti` function for the square root, providing exact results without iteration.
---
@@ -364,5 +603,17 @@ A Clarity v4 security feature that enforces maximum transfer amounts at the bloc
---
## References
1. Solidly Exchange: https://solidly.exchange
2. Velodrome Finance: https://velodrome.finance
3. Aerodrome: https://aerodrome.finance
4. Wombat Whitepaper: https://www.wombat.exchange/Wombat_Whitepaper_Public.pdf
5. Curve StableSwap: https://curve.fi/whitepaper
6. Clarity sqrti: https://docs.stacks.co/reference/clarity/functions#sqrti
7. Clarity restrict-assets?: https://docs.stacks.co/clarity/keywords#restrict-assets
---
**Questions or feedback?** Join the discussion in the [ALEX Discord](https://discord.gg/alexlab) or [GitHub](https://github.com/alexgo-io/alex-dao-2).