chore: Update READMEs.

balancer · Sep 4, 2024 · 3f9320f · 3f9320f
1 parent ce31d03
commit 3f9320f
Show file tree

Hide file tree

Showing 3 changed files with 220 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -1,3 +1,15 @@
 # Balancer Maths
 
 Reference maths implementations and packages for Balancer V3 pools.
+
+## Python
+
+Python implementation. See [README](./python/README.md).
+
+## Typescript
+
+Typescript implementation. See [README](./testData/README.md) and [NPM package](https://www.npmjs.com/package/@balancer-labs/balancer-maths).
+
+## TestData
+
+Test data and helpers.
diff --git a/python/README.md b/python/README.md
@@ -0,0 +1,142 @@
+# Balancer Maths Python
+
+Python implementation of maths for Balancer pools.
+
+## 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
+
+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 = {
+    "amount_raw": 100000000,
+    "swap_kind": SwapKind.GIVENIN.value,
+    "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
+
+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 = {
+    "pool": '0xb2456a6f51530053bc41b0ee700fe6a2c37282e8',
+    "max_amounts_in_raw": [200000000000000000, 100000000000000000],
+    "min_bpt_amount_out_raw": 0,
+    "kind": Kind.UNBALANCED.value,
+}
+
+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
+
+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 = {
+    "pool": '0x03722034317d8fb16845213bd3ce15439f9ce136',
+    "min_amounts_out_raw": [1, 1],
+    "max_bpt_amount_in_raw": 10000000000000,
+    "kind": RemoveKind.PROPORTIONAL.value,
+}
+
+input_hook_state = {
+    'removeLiquidityHookFeePercentage': 0,
+    'tokens': pool['tokens'],
+}
+
+vault = Vault()
+
+calculated_result = vault.add_liquidity(
+    add_liquidity_input,
+    pool,
+    hook_state=input_hook_state
+)
+```
+
diff --git a/typescript/README.md b/typescript/README.md
@@ -1,8 +1,21 @@
 # Balancer Maths TS
 
-Typescript implementation of maths for Balancer pools.
+Typescript implementation of maths for Balancer pools. Also published as a [package on NPM](https://www.npmjs.com/package/@balancer-labs/balancer-maths).
 
-## Swap
+## Hooks Support
+
+Hooks are supported on a case by case basis.
+
+When a pool has a hook type included in the `PoolState` a `HookState` 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
 
 ```typescript
 const vault = new Vault();
@@ -35,7 +48,7 @@ const calculatedAmount = vault.swap(
 );
 ```
 
-## AddLiquidity
+### Add Liquidity
 
 ```typescript
 const vault = new Vault();
@@ -68,3 +81,53 @@ const calculatedAmounts = vault.addLiquidity(
 );
 ```
 
+### Remove Liquidity
+
+This example shows how to calculate the result of a remove liqudity operation when the pool is registered with the ExitFee hook.
+
+```typescript
+const vault = new Vault();
+
+const poolState = {
+    poolType: 'Weighted',
+    hookType: 'ExitFee',
+    chainId: '11155111',
+    blockNumber: '5955145',
+    poolAddress: '0x03722034317d8fb16845213bd3ce15439f9ce136',
+    tokens: [
+        '0x7b79995e5f793A07Bc00c21412e50Ecae098E7f9',
+        '0xb19382073c7A0aDdbb56Ac6AF1808Fa49e377B75',
+    ],
+    scalingFactors: [1000000000000000000n, 1000000000000000000n],
+    weights: [500000000000000000n, 500000000000000000n],
+    swapFee: 100000000000000000n,
+    aggregateSwapFee: 0n,
+    balancesLiveScaled18: [5000000000000000n, 5000000000000000000n],
+    tokenRates: [1000000000000000000n, 1000000000000000000n],
+    totalSupply: 158113883008415798n,
+};
+
+const inputHookState = {
+    removeLiquidityHookFeePercentage: 0n,
+    tokens: poolState.tokens,
+};
+
+const removeLiquidityInput = {
+    pool: '0xb2456a6f51530053bc41b0ee700fe6a2c37282e8',
+    minAmountsOutRaw: [1n, 1n],
+    maxBptAmountInRaw: 10000000000000n,
+    kind: RemoveKind.PROPORTIONAL,
+};
+
+const outPutAmount = vault.removeLiquidity(
+    {
+        pool: pool.poolAddress,
+        minAmountsOutRaw: amountsOutRaw,
+        maxBptAmountInRaw: bptInRaw,
+        kind,
+    },
+    pool,
+    inputHookState
+);
+```
+