Liquidity

By using these liquidity-related functions, you can fully manage your liquidity positions: create pools, add or remove liquidity within precise price ranges, and collect accrued fees.

createPoolV3

Creates a new Pool (if it does not already exist) and initializes it with a desired starting price.

const createPoolV3 = async (
  token0: string,
  token1: string,
  desirePrice: number,
  fee: 500 | 3000 | 10000
)

Parameters:

  • token0 / token1: Addresses of the tokens in the desired pool.

  • desirePrice: The initial price you want when the pool is created.

  • fee: The fee tier for the pool (500 for 0.05%, 3000 for 0.3%, or 10000 for 1%).

Returns:

  • On success, returns a transaction hash (as a string or ethers TransactionResponse).

  • On failure, returns an Error.

Usage Example:

import { createPoolV3, ADDRESSES } from '@storyhunt/wrapper-sdk';

async function createNewPool() {
  const txHash = await createPoolV3(
    ADDRESSES.TOKENS.WIP.id,  // token0
    ADDRESSES.TOKENS.USDC.id, // token1
    1000,                     // desirePrice
    3000                      // fee tier
  );
  console.log('Transaction result:', txHash);
}

addLiquidityV3

Adds liquidity to an existing Pool between two tokens, specifying a price range.

async function addLiquidityV3(
  token0: string,
  token1: string,
  fee: 500 | 3000 | 10000,
  amount0: number,
  amount1: number,
  highPrice: number,
  lowPrice: number
)

Parameters:

  • token0 / token1: The token addresses for the pool (use WIP address if IP is involved).

  • fee: The pool’s fee tier.

  • amount0 / amount1: Decimal amounts of each token to deposit.

  • highPrice / lowPrice: Defines the upper and lower price boundaries for your liquidity.

Returns:

  • A transaction hash or an ethers TransactionResponse if successful.

  • An Error if the operation fails.

Usage Example:

import { addLiquidityV3, ADDRESSES } from '@storyhunt/wrapper-sdk';

async function provideLiquidity() {
  const txResult = await addLiquidityV3(
    ADDRESSES.TOKENS.WIP.id,
    ADDRESSES.TOKENS.USDC.id,
    3000,   // 0.3% fee
    1,      // 1 WIP
    500,    // 500 USDC
    5000,   // highPrice
    1000    // lowPrice
  );
  console.log('Liquidity added, txResult:', txResult);
}

addPositionLiquidityV3

Increases the liquidity of an existing position identified by positionId.

async function addPositionLiquidityV3(
  positionId: number,
  amount0: number,
  amount1: number
)

Parameters:

  • positionId: The StroyHunt V3 position (NFT) ID you want to add liquidity to.

  • amount0 / amount1: Decimal amounts of token0 and token1 to add.

Returns:

  • A transaction hash or TransactionResponse if successful.

  • An Error on failure.

Usage Example:

import { addPositionLiquidityV3 } from '@storyhunt/wrapper-sdk';

async function increaseExistingLiquidity() {
  const txResult = await addPositionLiquidityV3(12345, 0.5, 250);
  console.log('Liquidity increased, txResult:', txResult);
}

removeLiquidityV3

Removes a specified percentage of liquidity from an existing position.

async function removeLiquidityV3(
  positionId: number,
  percentageToRemove: number
)

Parameters:

  • positionId: The ID (NFT) of the position from which to remove liquidity.

  • percentageToRemove: A number between 0 and 100 indicating how much of the current liquidity to remove.

Returns:

  • A transaction hash or TransactionResponse if successful.

  • An Error if removal fails.

Usage Example:

import { removeLiquidityV3 } from '@storyhunt/wrapper-sdk';

async function reduceLiquidity() {
  // Remove 50% of the liquidity from position #12345
  const txResult = await removeLiquidityV3(12345, 50);
  console.log('Liquidity removed, txResult:', txResult);
}

collectFeeV3

Collects fees accrued in a given position.

export async function collectFeeV3(positionId: number)

Parameters:

  • positionId: The ID of the liquidity position (NFT) from which to collect fees.

Returns:

  • A transaction hash or TransactionResponse if successful.

  • An Error if the fee collection fails.

Usage Example:

import { collectFeeV3 } from '@storyhunt/wrapper-sdk';

async function collectFees() {
  const txResult = await collectFeeV3(12345); // position #12345
  console.log('Fees collected, txResult:', txResult);
}

getUserPoolsV3

Function:

async function getUserPoolsV3()

Retrieves all liquidity positions (pools) associated with the connected user by executing a GraphQL query against the subgraph.

Parameters:

  • None

Returns:

  • GraphPositionResponse: An object containing the user's liquidity positions, including details such as token addresses, liquidity amounts, tick ranges, and associated pools.

  • Error: An error object if the query fails or if no connected address is found.

Example:

import { getUserPoolsV3 } from '@storyhunt/wrapper-sdk';

async function fetchUserPools() {
  try {
    const userPools = await getUserPoolsV3();
    console.log('User V3 Pools:', userPools);

    if (userPools instanceof Error) {
      throw userPools;
    }

    userPools.data.positions.forEach((position) => {
      console.log(`Position ID: ${position.id}`);
      console.log(`Token0: ${position.token0.symbol} (${position.token0.id})`);
      console.log(`Token1: ${position.token1.symbol} (${position.token1.id})`);
      console.log(`Liquidity: ${position.liquidity}`);
      console.log(`Tick Range: ${position.tickLower.tickIdx} - ${position.tickUpper.tickIdx}`);
      console.log('---');
    });
  } catch (error) {
    console.error('Failed to fetch user pools:', error);
  }
}

Token Approval

V3 Non-Fungible Position Manager Approval

Function: 

 v3PositionManagertokenApproval(token: string, amount?: bigint)

Approves the Non-Fungible Position Manager to spend your tokens. Defaults to MaxUint256 if amount is not provided.

Example:

import { v3PositionManagertokenApproval, ADDRESSES } from '@storyhunt/wrapper-sdk';

await v3PositionManagertokenApproval(ADDRESSES.TOKENS.WIP.id);
console.log('WIP approved for Non-Fungible Position Manager!');
PreviousSwapNextFarming Liquidity