@paraswap/dex-lib 4.1.4 → 4.1.5-bal-v3-hooks.0

package/src/dex/balancer-v3/hooks/balancer-hook-event-subscriber.ts

@@ -0,0 +1,212 @@
+import {
+  EventFragment,
+  Fragment,
+  FunctionFragment,
+  Interface,
+} from '@ethersproject/abi';
+import _ from 'lodash';
+import { DeepReadonly } from 'ts-essentials';
+import { Log, Logger } from '../../../types';
+import { catchParseLogError } from '../../../utils';
+import { StatefulEventSubscriber } from '../../../stateful-event-subscriber';
+import { IDexHelper } from '../../../dex-helper/idex-helper';
+import { loadHooksConfig } from './loadHooksConfig';
+import {
+  DirectionalFee,
+  DirectionalFeeConfig,
+  DirectionalFeeHookState,
+  getDirectionalFeeHookState,
+} from './directionalFeeHook';
+import directionalFeeHookAbi from '../../../abi/balancer-v3/directionalFeeHook.json';
+import {
+  getStableSurgeHookState,
+  maxSurgeFeePercentageChangedEvent,
+  StableSurge,
+  StableSurgeConfig,
+  StableSurgeHookState,
+  thresholdSurgePercentageChangedEvent,
+} from './stableSurgeHook';
+import stableSurgeHookAbi from '../../../abi/balancer-v3/stableSurgeHook.json';
+
+// Add each supported hook state here
+export type HookState = DirectionalFeeHookState | StableSurgeHookState;
+
+export type HookStateMap = {
+  [address: string]: HookState;
+};
+
+export type HookConfig = DirectionalFeeConfig | StableSurgeConfig;
+
+export type HooksConfigMap = {
+  [hookAddress: string]: HookConfig;
+};
+
+/**
+ * This will handle events/state for each supported hook contract. State is used during swap calculations.
+ * Each hook should have its own implementation file for state typing, fetching state and handling events.
+ */
+export class BalancerEventHook extends StatefulEventSubscriber<HookStateMap> {
+  handlers: {
+    [event: string]: (
+      event: any,
+      state: DeepReadonly<HookStateMap>,
+      log: Readonly<Log>,
+      logger: Logger,
+    ) => DeepReadonly<HookStateMap> | null;
+  } = {};
+
+  interfaces: Interface[];
+  logDecoder: (log: Log) => any;
+
+  addressesSubscribed: string[];
+
+  hooksConfigMap: HooksConfigMap;
+
+  constructor(
+    readonly parentName: string,
+    protected network: number,
+    protected dexHelper: IDexHelper,
+    logger: Logger,
+  ) {
+    super(parentName, 'Balancer_Hooks', dexHelper, logger);
+
+    // Load supported hooks from config file
+    this.hooksConfigMap = loadHooksConfig(network);
+
+    // Add each hook ABI here
+    this.interfaces = [
+      new Interface(directionalFeeHookAbi),
+      new Interface(stableSurgeHookAbi),
+    ];
+    this.logDecoder = (log: Log) =>
+      this.combineInterfaces(this.interfaces).parseLog(log);
+
+    // Subscribe to all hooks
+    this.addressesSubscribed = Object.keys(this.hooksConfigMap);
+
+    // StableSurgeHook events
+    this.handlers['ThresholdSurgePercentageChanged'] =
+      thresholdSurgePercentageChangedEvent.bind(this);
+    this.handlers['MaxSurgeFeePercentageChanged'] =
+      maxSurgeFeePercentageChangedEvent.bind(this);
+  }
+
+  /**
+   * The function is called every time any of the subscribed
+   * addresses release log. The function accepts the current
+   * state, updates the state according to the log, and returns
+   * the updated state.
+   * @param state - Current state of event subscriber
+   * @param log - Log released by one of the subscribed addresses
+   * @returns Updates state of the event subscriber after the log
+   */
+  protected processLog(
+    state: DeepReadonly<HookStateMap>,
+    log: Readonly<Log>,
+  ): DeepReadonly<HookStateMap> | null {
+    try {
+      const event = this.logDecoder(log);
+      if (event.name in this.handlers) {
+        return this.handlers[event.name](event, state, log, this.logger);
+      }
+    } catch (e) {
+      catchParseLogError(e, this.logger);
+    }
+
+    return null;
+  }
+
+  /**
+   * The function generates state using on-chain calls. This
+   * function is called to regenerate state if the event based
+   * system fails to fetch events and the local state is no
+   * more correct.
+   * @param blockNumber - Blocknumber for which the state should
+   * should be generated
+   * @returns state of the event subscriber at blocknumber
+   */
+  async generateState(
+    blockNumber: number,
+  ): Promise<DeepReadonly<HookStateMap>> {
+    // Only hooks that are supported will be called
+    const hookState: HookStateMap = {};
+
+    await Promise.all(
+      Object.keys(this.hooksConfigMap).map(async hookAddress => {
+        const hookConfig = this.hooksConfigMap[hookAddress];
+        if (hookConfig.type === DirectionalFee.type) {
+          hookState[hookAddress] = await getDirectionalFeeHookState();
+        } else if (hookConfig.type === StableSurge.type) {
+          hookState[hookAddress] = await getStableSurgeHookState(
+            this.interfaces[1],
+            hookAddress,
+            hookConfig.factory,
+            this.dexHelper,
+            blockNumber,
+          );
+        }
+      }),
+    );
+
+    return hookState;
+  }
+
+  async updateHookState() {
+    // Not all hooks need updated, only ones with settings/state that can't be handled by events
+    const blockNumber = await this.dexHelper.provider.getBlockNumber();
+    const currentState =
+      (_.cloneDeep(this.getStaleState()) as HookStateMap) || {};
+
+    await Promise.all(
+      Object.keys(this.hooksConfigMap).map(async hookAddress => {
+        const hookConfig = this.hooksConfigMap[hookAddress];
+        // StableSurge can have new registered pools with associated hook state
+        if (hookConfig.type === StableSurge.type) {
+          currentState[hookAddress] = await getStableSurgeHookState(
+            this.interfaces[1],
+            hookAddress,
+            hookConfig.factory,
+            this.dexHelper,
+            blockNumber,
+          );
+        }
+      }),
+    );
+
+    this.setState(currentState, blockNumber);
+  }
+
+  combineInterfaces = (interfaces: Interface[]): Interface => {
+    // Use a Map to store unique fragments, keyed by their string representation
+    const uniqueFragments = new Map<string, Fragment>();
+
+    interfaces.forEach((interfaceInstance: Interface) => {
+      interfaceInstance.fragments.forEach((fragment: Fragment) => {
+        let key: string;
+
+        if (fragment instanceof FunctionFragment) {
+          // For functions, use the signature as the key
+          // This includes name and parameter types
+          key = fragment.format();
+        } else if (fragment instanceof EventFragment) {
+          // For events, use the signature as the key
+          key = fragment.format();
+        } else {
+          // For other fragment types (like errors), use their string representation
+          key = fragment.toString();
+        }
+
+        // Only add if we haven't seen this signature before
+        if (!uniqueFragments.has(key)) {
+          uniqueFragments.set(key, fragment);
+        }
+      });
+    });
+
+    // Convert the Map values back to an array
+    const dedupedFragments = Array.from(uniqueFragments.values());
+
+    // Create a new interface with the deduped fragments
+    return new Interface(dedupedFragments);
+  };
+}

package/src/dex/balancer-v3/hooks/directionalFeeHook.ts

@@ -0,0 +1,51 @@
+/**
+ * Each supported hook should implement its own version of this file making it easy to retrieve required onchain state.
+ */
+import _ from 'lodash';
+import { Log } from '../../../types';
+import { DeepReadonly } from 'ts-essentials';
+import { HookStateMap } from './balancer-hook-event-subscriber';
+
+export const DirectionalFee = {
+  type: 'DirectionalFee' as const,
+};
+
+export type DirectionalFeeConfig = {
+  type: typeof DirectionalFee.type;
+  address: string;
+};
+
+export type DirectionalFeeHookState = {
+  test: string; // Note - this is just a dummy example as this specific test hook doesn't have any required state but is used to prove concept
+};
+
+/**
+ * Retrieve any initial hook state required.
+ * @returns
+ */
+export async function getDirectionalFeeHookState(): Promise<DirectionalFeeHookState> {
+  // Note - for other hooks this function would retrieve any initial state using onchain calls
+  return { test: 'initial' };
+}
+
+/**
+ * Handles the event emitted when a new hook is registered.
+ * @param event
+ * @param state
+ * @param log
+ * @returns
+ */
+export function exitFeeHookExampleRegisteredEvent(
+  event: any,
+  state: DeepReadonly<HookStateMap>,
+  log: Readonly<Log>,
+): DeepReadonly<HookStateMap> | null {
+  // Note - This is a non-important event but demos the use case. Other hooks would implement this for any state changes required for swap maths.
+  const hookAddress = event.args.hooksContract.toLowerCase();
+  if (!state[hookAddress]) {
+    return null;
+  }
+  const newState = _.cloneDeep(state) as HookStateMap;
+  newState[hookAddress] = { test: event.args.pool };
+  return newState;
+}

package/src/dex/balancer-v3/hooks/loadHooksConfig.ts

@@ -0,0 +1,12 @@
+import { BalancerV3Config } from './../config';
+import { HooksConfigMap } from './balancer-hook-event-subscriber';
+
+export function loadHooksConfig(network: number): HooksConfigMap {
+  const hooks = BalancerV3Config.BalancerV3[network].hooks;
+
+  if (!hooks) return {};
+
+  return Object.fromEntries(
+    hooks.map(hook => [hook.address.toLowerCase(), hook]),
+  );
+}

package/src/dex/balancer-v3/hooks/stableSurgeHook.ts

@@ -0,0 +1,198 @@
+import _ from 'lodash';
+import { Log } from '../../../types';
+import { DeepReadonly } from 'ts-essentials';
+import { HookStateMap } from './balancer-hook-event-subscriber';
+import { Interface } from '@ethersproject/abi';
+import { Contract } from 'ethers';
+import { IDexHelper } from '../../../dex-helper';
+import { callData, decodeThrowError } from '../getOnChainState';
+import { Logger } from 'log4js';
+
+export const StableSurge = {
+  type: 'StableSurge' as const,
+};
+
+export type StableSurgeConfig = {
+  type: typeof StableSurge.type;
+  factory: string;
+  address: string;
+};
+
+export type StableSurgePoolSetting = {
+  surgeThresholdPercentage?: bigint;
+  maxSurgeFeePercentage?: bigint;
+};
+
+export type StableSurgeHookState = Record<string, StableSurgePoolSetting>;
+
+/**
+ * Retrieve any initial hook state required.
+ * @returns
+ */
+export async function getStableSurgeHookState(
+  hookInterface: Interface,
+  hookAddress: string,
+  factoryAddress: string,
+  dexHelper: IDexHelper,
+  blockNumber: number,
+): Promise<StableSurgeHookState> {
+  // Find all pools with hook
+  const resolverContract = new Contract(
+    factoryAddress,
+    ['function getPools() external view returns (address[])'],
+    dexHelper.provider,
+  );
+  const pools = (await resolverContract.callStatic.getPools({
+    blockTag: blockNumber,
+  })) as string[];
+  const surgeThresholdCallData: callData[] = pools.flatMap(pool => {
+    return [
+      {
+        target: hookAddress,
+        callData: hookInterface.encodeFunctionData(
+          'getSurgeThresholdPercentage',
+          [pool],
+        ),
+      },
+      {
+        target: hookAddress,
+        callData: hookInterface.encodeFunctionData('getMaxSurgeFeePercentage', [
+          pool,
+        ]),
+      },
+    ];
+  });
+
+  // 500 is an arbitrary number chosen based on the blockGasLimit
+  const slicedMultiCallData = _.chunk(surgeThresholdCallData, 500);
+
+  const multicallDataResult = (
+    await Promise.all(
+      slicedMultiCallData.map(async _multiCallData =>
+        dexHelper.multiContract.methods
+          .tryAggregate(false, _multiCallData)
+          .call({}, blockNumber),
+      ),
+    )
+  ).flat();
+
+  return mapPoolsToDecodedData(hookInterface, pools, multicallDataResult);
+}
+
+function mapPoolsToDecodedData(
+  hookInterface: Interface,
+  pools: string[],
+  data: any[],
+): StableSurgeHookState {
+  return pools.reduce((acc, pool, index) => {
+    const dataIndex = index * 2;
+
+    // Ensure we have enough data
+    if (dataIndex + 1 >= data.length) {
+      throw new Error(`Insufficient data for pool ${pool}`);
+    }
+
+    // Decode the corresponding data pairs
+    const decodedX = decodeThrowError(
+      hookInterface,
+      'getSurgeThresholdPercentage',
+      data[dataIndex],
+      pool,
+    );
+    const decodedY = decodeThrowError(
+      hookInterface,
+      'getMaxSurgeFeePercentage',
+      data[dataIndex + 1],
+      pool,
+    );
+    // Add to accumulator
+    acc[pool.toLowerCase()] = {
+      surgeThresholdPercentage: decodedX[0].toBigInt(),
+      maxSurgeFeePercentage: decodedY[0].toBigInt(),
+    };
+
+    return acc;
+  }, {} as StableSurgeHookState);
+}
+
+/**
+ * Handles the event emitted when threshold surge percentage changed.
+ * @param event
+ * @param state
+ * @param log
+ * @returns
+ */
+export function thresholdSurgePercentageChangedEvent(
+  event: any,
+  state: DeepReadonly<HookStateMap>,
+  log: Readonly<Log>,
+  logger: Logger,
+): DeepReadonly<HookStateMap> | null {
+  // ThresholdSurgePercentageChanged(pool, newSurgeThresholdPercentage)
+  const hookAddress = log.address.toLowerCase();
+
+  if (!state[hookAddress]) {
+    logger.info(`State for hook ${hookAddress} was not found...`);
+    return state;
+  }
+
+  const newState = _.cloneDeep(state) as HookStateMap;
+
+  if (
+    newState[hookAddress] &&
+    !(newState[hookAddress] as StableSurgeHookState)[
+      event.args.pool.toLowerCase()
+    ]
+  ) {
+    (newState[hookAddress] as StableSurgeHookState)[
+      event.args.pool.toLowerCase()
+    ] = {
+      surgeThresholdPercentage: BigInt(event.args.newSurgeThresholdPercentage),
+    };
+  } else {
+    (newState[hookAddress] as StableSurgeHookState)[
+      event.args.pool.toLowerCase()
+    ].surgeThresholdPercentage = BigInt(event.args.newSurgeThresholdPercentage);
+  }
+
+  return newState;
+}
+
+/**
+ * Handles the event emitted when max surge fee percentage changed.
+ * @param event
+ * @param state
+ * @param log
+ * @returns
+ */
+export function maxSurgeFeePercentageChangedEvent(
+  event: any,
+  state: DeepReadonly<HookStateMap>,
+  log: Readonly<Log>,
+): DeepReadonly<HookStateMap> | null {
+  // MaxSurgeFeePercentageChanged(pool, newMaxSurgeFeePercentage)
+  const hookAddress = log.address.toLowerCase();
+  if (!state[hookAddress]) {
+    return null;
+  }
+  const newState = _.cloneDeep(state) as HookStateMap;
+
+  if (
+    newState[hookAddress] &&
+    !(newState[hookAddress] as StableSurgeHookState)[
+      event.args.pool.toLowerCase() as string
+    ]
+  ) {
+    (newState[hookAddress] as StableSurgeHookState)[
+      event.args.pool.toLowerCase()
+    ] = {
+      maxSurgeFeePercentage: BigInt(event.args.newMaxSurgeFeePercentage),
+    };
+  } else {
+    (newState[hookAddress] as StableSurgeHookState)[
+      event.args.pool.toLowerCase()
+    ].maxSurgeFeePercentage = BigInt(event.args.newMaxSurgeFeePercentage);
+  }
+
+  return newState;
+}

package/src/dex/balancer-v3/types.ts

@@ -1,5 +1,6 @@
 import { BufferState } from '@balancer-labs/balancer-maths';
 import { Address } from '../../types';
+import { HookConfig } from './hooks/balancer-hook-event-subscriber';
 
 // Immutable data types available on all pools (Available from API)
 export type CommonImmutablePoolState = {
@@ -12,7 +13,9 @@ export type CommonImmutablePoolState = {
   weights: bigint[];
   // TODO re-introduce this once added to API
   // scalingFactors: bigint[];
+  hookAddress: string | undefined;
   hookType: string | undefined;
+  supportsUnbalancedLiquidity: boolean;
 };
 
 // Mutable data types available on all pools (Available via onchain calls/events)
@@ -26,8 +29,6 @@ export interface CommonMutableState {
   isPoolPaused: boolean;
   // TODO remove this once API provides it
   scalingFactors: bigint[];
-  // TODO remove this once API provides it
-  hasHook: boolean;
 }
 
 type CommonPoolState = CommonImmutablePoolState & CommonMutableState;
@@ -76,6 +77,7 @@ export type DexParams = {
   // https://github.com/balancer/balancer-v3-monorepo/blob/main/pkg/interfaces/contracts/vault/IRouter.sol
   balancerRouterAddress: string;
   balancerBatchRouterAddress: string;
+  hooks?: HookConfig[];
 };
 
 export type TokenInfo = {

package/tests/constants-e2e.ts

@@ -1694,6 +1694,10 @@ export const Tokens: {
       address: '0xC768c589647798a6EE01A91FdE98EF2ed046DBD6',
       decimals: 6,
     },
+    waBasGHO: {
+      address: '0x88b1Cd4b430D95b406E382C3cDBaE54697a0286E',
+      decimals: 18,
+    },
     aaveUSDC: {
       address: '0x4e65fe4dba92790696d040ac24aa414708f5c0ab',
       decimals: 6,
@@ -2145,7 +2149,7 @@ export const Holders: {
     DOG: '0xbe3ab8a87730684ef1e476064c2e43c3e982f8e8',
     stataUSDC: '0x88Cac91ADDE2208039A227B373C2A692C0700547',
     aaveUSDC: '0x5DE3c5BE52D7aDbdC3aEFe2eA061A2ECE0C7d766',
-    waBasUSDC: '0xC768c589647798a6EE01A91FdE98EF2ed046DBD6',
+    waBasUSDC: '0x450C01300B83bE379113256038b4Dd3b45d23B5e',
     USDM: '0x426c4966fC76Bf782A663203c023578B744e4C5E',
     crvUSD: '0xBbAbDB1385deA5285113581A7024d6DC04131101',
     cbETH: '0x50e011dD1e2b4906F1534623cD134B30422bb11E',
@@ -2156,6 +2160,7 @@ export const Holders: {
     waBaswstETH: '0x854B004700885A61107B458f11eCC169A019b764',
     sUSDS: '0xC9716E991396AA933Fa7A481003a5953bcBabC17',
     smUSDC: '0x88457F47c9BEC8379eB90d8dC3592F79084e555d',
+    waBasGHO: '0x450C01300B83bE379113256038b4Dd3b45d23B5e',
   },
   [Network.SEPOLIA]: {
     bal: '0xDb4ff41B4C1222c2b1869A67Be115070688989a2',