# Balancer Maths Python
Python implementation of mathematics for Balancer v3
> **Note**: This is the Python implementation within the [balancer-maths](https://github.com/balancer/balancer-maths) monorepo, which also contains TypeScript and Rust implementations.
## Installation
### From PyPI (recommended)
```bash
pip install balancer-maths
```
### From source
```bash
git clone https://github.com/balancer/balancer-maths.git
cd balancer-maths/python
pip install -e .
```
## Development Setup
1. Create and activate a virtual environment:
```bash
python -m venv .venv
source .venv/bin/activate # On Windows use: .venv\Scripts\activate
```
2. Install development dependencies:
```bash
pip install -e ".[dev]"
```
## Hooks Support
Hooks are supported on a case by case basis.
When a pool has a hook type included in the pool data relevant hook data must also be passed as an input to any Vault operation. See [Remove Liquidity example](#remove-liquidity) below.
Currently supported hooks:
* ExitFeeHook
* This hook implements the ExitFeeHookExample found in [mono-repo](https://github.com/balancer/balancer-v3-monorepo/blob/c848c849cb44dc35f05d15858e4fba9f17e92d5e/pkg/pool-hooks/contracts/ExitFeeHookExample.sol)
## Examples
### Swap
```python
from src.vault import Vault
from src.swap import SwapInput, SwapKind
pool = {
"poolType": "WEIGHTED",
"chainId": "11155111",
"blockNumber": "5955145",
"poolAddress": "0xb2456a6f51530053bc41b0ee700fe6a2c37282e8",
"tokens": [
"0x7b79995e5f793A07Bc00c21412e50Ecae098E7f9",
"0xb19382073c7A0aDdbb56Ac6AF1808Fa49e377B75",
],
"scalingFactors": [1000000000000000000, 1000000000000000000],
"weights": [500000000000000000, 500000000000000000],
"swapFee": 100000000000000000,
"balancesLiveScaled18": [2000000000000000000, 2000000000000000000],
"tokenRates": [1000000000000000000, 1000000000000000000],
"totalSupply": 1000000000000000000,
"aggregateSwapFee": 500000000000000000,
}
swap_input = SwapInput(
amount_raw=100000000,
swap_kind=SwapKind.GIVENIN,
token_in=pool['tokens'][0],
token_out=pool['tokens'][1],
)
vault = Vault()
calculated_result = vault.swap(
swap_input,
pool,
)
```
### Add Liquidity
```python
from src.vault import Vault
from src.add_liquidity import AddLiquidityInput, AddLiquidityKind
pool = {
"poolType": "WEIGHTED",
"chainId": "11155111",
"blockNumber": "5955145",
"poolAddress": "0xb2456a6f51530053bc41b0ee700fe6a2c37282e8",
"tokens": [
"0x7b79995e5f793A07Bc00c21412e50Ecae098E7f9",
"0xb19382073c7A0aDdbb56Ac6AF1808Fa49e377B75",
],
"scalingFactors": [1000000000000000000, 1000000000000000000],
"weights": [500000000000000000, 500000000000000000],
"swapFee": 100000000000000000,
"balancesLiveScaled18": [2000000000000000000, 2000000000000000000],
"tokenRates": [1000000000000000000, 1000000000000000000],
"totalSupply": 1000000000000000000,
"aggregateSwapFee": 500000000000000000,
}
add_liquidity_input = AddLiquidityInput(
pool="0xb2456a6f51530053bc41b0ee700fe6a2c37282e8",
max_amounts_in_raw=[200000000000000000, 100000000000000000],
min_bpt_amount_out_raw=0,
kind=AddLiquidityKind.UNBALANCED,
)
vault = Vault()
calculated_result = vault.add_liquidity(
add_liquidity_input,
pool,
)
```
### Remove Liquidity
This example shows how to calculate the result of a remove liqudity operation when the pool is registered with the ExitFee hook.
```python
from src.vault import Vault
from src.remove_liquidity import RemoveLiquidityInput, RemoveLiquidityKind
pool = {
"poolType": "WEIGHTED",
"hookType": "ExitFee",
"chainId": "11155111",
"blockNumber": "5955145",
"poolAddress": "0x03722034317d8fb16845213bd3ce15439f9ce136",
"tokens": [
"0x7b79995e5f793A07Bc00c21412e50Ecae098E7f9",
"0xb19382073c7A0aDdbb56Ac6AF1808Fa49e377B75",
],
"scalingFactors": [1000000000000000000, 1000000000000000000],
"weights": [500000000000000000, 500000000000000000],
"swapFee": 100000000000000000,
"balancesLiveScaled18": [5000000000000000, 5000000000000000000],
"tokenRates": [1000000000000000000, 1000000000000000000],
"totalSupply": 158113883008415798,
"aggregateSwapFee": 0,
}
remove_liquidity_input = RemoveLiquidityInput(
pool="0x03722034317d8fb16845213bd3ce15439f9ce136",
min_amounts_out_raw=[1, 1],
max_bpt_amount_in_raw=10000000000000,
kind=RemoveLiquidityKind.PROPORTIONAL,
)
input_hook_state = {
'removeLiquidityHookFeePercentage': 0,
'tokens': pool['tokens'],
}
vault = Vault()
calculated_result = vault.remove_liquidity(
remove_liquidity_input,
pool,
hook_state=input_hook_state
)
```
## Building and Releasing
### Local Development
To build the package locally for testing:
```bash
python build_and_release.py --all
```
This will:
- Clean previous build artifacts
- Install build dependencies
- Build the package
- Check the built package
### Releasing to PyPI
1. **Test Release** (recommended first):
```bash
python build_and_release.py --test-upload
```
2. **Production Release**:
```bash
python build_and_release.py --upload
```
**Note**: You'll need to have your PyPI credentials configured. You can set them up using:
```bash
pip install twine
twine configure
```
### Manual Build
If you prefer to build manually:
```bash
# Install build tools
pip install build twine
# Build the package
python -m build
# Check the package
twine check dist/*
# Upload to TestPyPI
twine upload --repository testpypi dist/*
# Upload to PyPI
twine upload dist/*
```
Raw data
{
"_id": null,
"home_page": null,
"name": "balancer-maths",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "amm, balancer, defi, liquidity, mathematics, pools",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/64/12/db9ac44cd9622b53f1085420177b997f2660b1b832ed4f98cff6d89fc7ab/balancer_maths-0.1.1.tar.gz",
"platform": null,
"description": "# Balancer Maths Python\n\nPython implementation of mathematics for Balancer v3\n\n> **Note**: This is the Python implementation within the [balancer-maths](https://github.com/balancer/balancer-maths) monorepo, which also contains TypeScript and Rust implementations.\n\n## Installation\n\n### From PyPI (recommended)\n\n```bash\npip install balancer-maths\n```\n\n### From source\n\n```bash\ngit clone https://github.com/balancer/balancer-maths.git\ncd balancer-maths/python\npip install -e .\n```\n\n## Development Setup\n\n1. Create and activate a virtual environment:\n```bash\npython -m venv .venv\nsource .venv/bin/activate # On Windows use: .venv\\Scripts\\activate\n```\n\n2. Install development dependencies:\n```bash\npip install -e \".[dev]\"\n```\n\n## Hooks Support\n\nHooks are supported on a case by case basis.\n\nWhen a pool has a hook type included in the pool data relevant hook data must also be passed as an input to any Vault operation. See [Remove Liquidity example](#remove-liquidity) below.\n\nCurrently supported hooks:\n\n* ExitFeeHook\n * This hook implements the ExitFeeHookExample found in [mono-repo](https://github.com/balancer/balancer-v3-monorepo/blob/c848c849cb44dc35f05d15858e4fba9f17e92d5e/pkg/pool-hooks/contracts/ExitFeeHookExample.sol)\n\n## Examples\n\n### Swap\n\n```python\nfrom src.vault import Vault\nfrom src.swap import SwapInput, SwapKind\n\npool = {\n \"poolType\": \"WEIGHTED\",\n \"chainId\": \"11155111\",\n \"blockNumber\": \"5955145\",\n \"poolAddress\": \"0xb2456a6f51530053bc41b0ee700fe6a2c37282e8\",\n \"tokens\": [\n \"0x7b79995e5f793A07Bc00c21412e50Ecae098E7f9\",\n \"0xb19382073c7A0aDdbb56Ac6AF1808Fa49e377B75\",\n ],\n \"scalingFactors\": [1000000000000000000, 1000000000000000000],\n \"weights\": [500000000000000000, 500000000000000000],\n \"swapFee\": 100000000000000000,\n \"balancesLiveScaled18\": [2000000000000000000, 2000000000000000000],\n \"tokenRates\": [1000000000000000000, 1000000000000000000],\n \"totalSupply\": 1000000000000000000,\n \"aggregateSwapFee\": 500000000000000000,\n}\n\n\nswap_input = SwapInput(\n amount_raw=100000000,\n swap_kind=SwapKind.GIVENIN,\n token_in=pool['tokens'][0],\n token_out=pool['tokens'][1],\n)\n\nvault = Vault()\n\ncalculated_result = vault.swap(\n swap_input,\n pool,\n)\n```\n\n### Add Liquidity\n\n```python\nfrom src.vault import Vault\nfrom src.add_liquidity import AddLiquidityInput, AddLiquidityKind\n\npool = {\n \"poolType\": \"WEIGHTED\",\n \"chainId\": \"11155111\",\n \"blockNumber\": \"5955145\",\n \"poolAddress\": \"0xb2456a6f51530053bc41b0ee700fe6a2c37282e8\",\n \"tokens\": [\n \"0x7b79995e5f793A07Bc00c21412e50Ecae098E7f9\",\n \"0xb19382073c7A0aDdbb56Ac6AF1808Fa49e377B75\",\n ],\n \"scalingFactors\": [1000000000000000000, 1000000000000000000],\n \"weights\": [500000000000000000, 500000000000000000],\n \"swapFee\": 100000000000000000,\n \"balancesLiveScaled18\": [2000000000000000000, 2000000000000000000],\n \"tokenRates\": [1000000000000000000, 1000000000000000000],\n \"totalSupply\": 1000000000000000000,\n \"aggregateSwapFee\": 500000000000000000,\n}\n\n\nadd_liquidity_input = AddLiquidityInput(\n pool=\"0xb2456a6f51530053bc41b0ee700fe6a2c37282e8\",\n max_amounts_in_raw=[200000000000000000, 100000000000000000],\n min_bpt_amount_out_raw=0,\n kind=AddLiquidityKind.UNBALANCED,\n)\n\nvault = Vault()\n\ncalculated_result = vault.add_liquidity(\n add_liquidity_input,\n pool,\n)\n```\n\n### Remove Liquidity\n\nThis example shows how to calculate the result of a remove liqudity operation when the pool is registered with the ExitFee hook.\n\n```python\nfrom src.vault import Vault\nfrom src.remove_liquidity import RemoveLiquidityInput, RemoveLiquidityKind\n\npool = {\n \"poolType\": \"WEIGHTED\",\n \"hookType\": \"ExitFee\",\n \"chainId\": \"11155111\",\n \"blockNumber\": \"5955145\",\n \"poolAddress\": \"0x03722034317d8fb16845213bd3ce15439f9ce136\",\n \"tokens\": [\n \"0x7b79995e5f793A07Bc00c21412e50Ecae098E7f9\",\n \"0xb19382073c7A0aDdbb56Ac6AF1808Fa49e377B75\",\n ],\n \"scalingFactors\": [1000000000000000000, 1000000000000000000],\n \"weights\": [500000000000000000, 500000000000000000],\n \"swapFee\": 100000000000000000,\n \"balancesLiveScaled18\": [5000000000000000, 5000000000000000000],\n \"tokenRates\": [1000000000000000000, 1000000000000000000],\n \"totalSupply\": 158113883008415798,\n \"aggregateSwapFee\": 0,\n}\n\nremove_liquidity_input = RemoveLiquidityInput(\n pool=\"0x03722034317d8fb16845213bd3ce15439f9ce136\",\n min_amounts_out_raw=[1, 1],\n max_bpt_amount_in_raw=10000000000000,\n kind=RemoveLiquidityKind.PROPORTIONAL,\n)\n\ninput_hook_state = {\n 'removeLiquidityHookFeePercentage': 0,\n 'tokens': pool['tokens'],\n}\n\nvault = Vault()\n\ncalculated_result = vault.remove_liquidity(\n remove_liquidity_input,\n pool,\n hook_state=input_hook_state\n)\n```\n\n## Building and Releasing\n\n### Local Development\n\nTo build the package locally for testing:\n\n```bash\npython build_and_release.py --all\n```\n\nThis will:\n- Clean previous build artifacts\n- Install build dependencies\n- Build the package\n- Check the built package\n\n### Releasing to PyPI\n\n1. **Test Release** (recommended first):\n```bash\npython build_and_release.py --test-upload\n```\n\n2. **Production Release**:\n```bash\npython build_and_release.py --upload\n```\n\n**Note**: You'll need to have your PyPI credentials configured. You can set them up using:\n```bash\npip install twine\ntwine configure\n```\n\n### Manual Build\n\nIf you prefer to build manually:\n\n```bash\n# Install build tools\npip install build twine\n\n# Build the package\npython -m build\n\n# Check the package\ntwine check dist/*\n\n# Upload to TestPyPI\ntwine upload --repository testpypi dist/*\n\n# Upload to PyPI\ntwine upload dist/*\n```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python implementation of mathematics for Balancer v3",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/balancer/balancer-maths/issues",
"Documentation": "https://github.com/balancer/balancer-maths/tree/main/python#readme",
"Homepage": "https://github.com/balancer/balancer-maths",
"Repository": "https://github.com/balancer/balancer-maths"
},
"split_keywords": [
"amm",
" balancer",
" defi",
" liquidity",
" mathematics",
" pools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "00ee1f3bfb196ff476a38ae1024a761da8aeefa38a44e37ba7569c3ab8a098da",
"md5": "8234691dc80b9ddd6fc1fb7d5b44aeea",
"sha256": "6dfbd2b57bd8126f62b938953c1c406e7221286e3cc0dc19fb74c0940935514b"
},
"downloads": -1,
"filename": "balancer_maths-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8234691dc80b9ddd6fc1fb7d5b44aeea",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 75677,
"upload_time": "2025-08-22T16:30:41",
"upload_time_iso_8601": "2025-08-22T16:30:41.399798Z",
"url": "https://files.pythonhosted.org/packages/00/ee/1f3bfb196ff476a38ae1024a761da8aeefa38a44e37ba7569c3ab8a098da/balancer_maths-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6412db9ac44cd9622b53f1085420177b997f2660b1b832ed4f98cff6d89fc7ab",
"md5": "e2b4b9b20085ce8d476c6497124afbff",
"sha256": "fe9cd468d66e34a2da81abe4970b8ffbc65f5713096abe389ad3e775c4b4dc13"
},
"downloads": -1,
"filename": "balancer_maths-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "e2b4b9b20085ce8d476c6497124afbff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 57691,
"upload_time": "2025-08-22T16:30:42",
"upload_time_iso_8601": "2025-08-22T16:30:42.626222Z",
"url": "https://files.pythonhosted.org/packages/64/12/db9ac44cd9622b53f1085420177b997f2660b1b832ed4f98cff6d89fc7ab/balancer_maths-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-22 16:30:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "balancer",
"github_project": "balancer-maths",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "balancer-maths"
}
JSON
