SwapRouter

Variables

Structs

struct SwapCallbackData {
    bytes path;
    address payer;
}

Description: Encapsulates the data passed to the storyHuntV3SwapCallback during a swap operation. It includes the swap path and the payer who is responsible for paying the tokens owed.

---

Functions

---

constructor(address _factory, address _WIP9, address _tokenDescriptor_) 
    PeripheryImmutableState(_factory, _WIP9) 
    ERC721Permit('StoryHunt V3 Positions NFT-V1', 'STH-V3-POS', '1') 
{
    _tokenDescriptor = _tokenDescriptor_;
}

Description: Initializes the SwapRouter contract with the factory address, Wrapped IP (WIP9) token address, and the token descriptor address. It also initializes inherited contracts.

Parameters

Name	Type	Description
_factory	address	The address of the StoryHunt V3 factory.
_WIP9	address	The address of the Wrapped IP (WIP9) token.
tokenDescriptor	address	The address of the token descriptor contract.

---

function storyHuntV3SwapCallback(int256 amount0Delta, int256 amount1Delta, bytes calldata _data) external override

Description: Callback function invoked by the StoryHuntV3Pool during a swap operation. It ensures that the necessary tokens are paid to the pool after a swap.

Parameters

Name	Type	Description
amount0Delta	int256	The change in token0 balance of the pool. Positive if the pool needs to receive tokens.
amount1Delta	int256	The change in token1 balance of the pool. Positive if the pool needs to receive tokens.
_data	bytes	Encoded data containing the swap path and payer information.

Return Values

None

Requirements

• At least one of amount0Delta or amount1Delta must be positive.

• Validates the callback using the CallbackValidation library to ensure it originates from a legitimate pool.

---

function exactInputSingle(ExactInputSingleParams calldata params) external payable override returns (uint256 amountOut)

Description: Performs a single exact input swap from one token to another within a specified pool.

Parameters

Name	Type	Description
params	ExactInputSingleParams	The parameters defining the exact input swap (details below).

ExactInputSingleParams Struct Definition:

struct ExactInputSingleParams {
    address tokenIn;
    address tokenOut;
    uint24 fee;
    address recipient;
    uint256 deadline;
    uint256 amountIn;
    uint256 amountOutMinimum;
    uint160 sqrtPriceLimitX96;
}

Return Values

Name	Type	Description
amountOut	uint256	The amount of tokenOut received from the swap.

Requirements

• The swap must be completed before the specified deadline.

• The received amount must be at least amountOutMinimum to prevent excessive slippage.

---

function exactInput(ExactInputParams memory params) external payable override returns (uint256 amountOut)

Description: Performs a multi-hop exact input swap along the specified path, allowing swaps across multiple pools.

Parameters

Name	Type	Description
params	ExactInputParams	The parameters defining the exact input multi-hop swap (details below).

ExactInputParams Struct Definition:

struct ExactInputParams {
    bytes path;
    address recipient;
    uint256 deadline;
    uint256 amountIn;
    uint256 amountOutMinimum;
}

Return Values

Name	Type	Description
amountOut	uint256	The total amount of tokenOut received from all swaps.

Requirements

• The entire swap sequence must be completed before the specified deadline.

• The total received amount must be at least amountOutMinimum to prevent excessive slippage.

---

function exactOutputSingle(ExactOutputSingleParams calldata params) external payable override returns (uint256 amountIn)

Description: Performs a single exact output swap from one token to another within a specified pool.

Parameters

Name	Type	Description
params	ExactOutputSingleParams	The parameters defining the exact output swap (details below).

ExactOutputSingleParams Struct Definition:

struct ExactOutputSingleParams {
    address tokenIn;
    address tokenOut;
    uint24 fee;
    address recipient;
    uint256 deadline;
    uint256 amountOut;
    uint256 amountInMaximum;
    uint160 sqrtPriceLimitX96;
}

Return Values

Name	Type	Description
amountIn	uint256	The amount of tokenIn used to achieve the swap.

Requirements

• The swap must be completed before the specified deadline.

• The input amount used must not exceed amountInMaximum to prevent excessive spending.

---

function exactOutput(ExactOutputParams calldata params) external payable override returns (uint256 amountIn)

Description: Performs a multi-hop exact output swap along the specified path, allowing swaps across multiple pools to achieve the desired output amount.

Parameters

Name	Type	Description
params	ExactOutputParams	The parameters defining the exact output multi-hop swap (details below).

ExactOutputParams Struct Definition:

struct ExactOutputParams {
    bytes path;
    address recipient;
    uint256 deadline;
    uint256 amountOut;
    uint256 amountInMaximum;
}

Return Values

Name	Type	Description
amountIn	uint256	The total amount of tokenIn used to achieve the desired tokenOut.

Requirements

• The entire swap sequence must be completed before the specified deadline.

• The total input amount used must not exceed amountInMaximum to prevent excessive spending.

---

Modifiers

---

modifier checkDeadline(uint256 deadline)

Description: Ensures that the transaction is executed before the specified deadline. If the current block timestamp exceeds the deadline, the transaction is reverted.

Parameters

Name	Type	Description
deadline	uint256	The timestamp by which the transaction must be completed.

Usage

• Applied to functions to enforce time constraints, preventing transactions from being executed after a certain time.

---

Structs (Continued)

While previously covered, additional structs used in function parameters are documented below for clarity.

---

struct ExactInputSingleParams {
    address tokenIn;
    address tokenOut;
    uint24 fee;
    address recipient;
    uint256 deadline;
    uint256 amountIn;
    uint256 amountOutMinimum;
    uint160 sqrtPriceLimitX96;
}

Description: Parameters for performing a single exact input swap.

---

struct ExactInputParams {
    bytes path;
    address recipient;
    uint256 deadline;
    uint256 amountIn;
    uint256 amountOutMinimum;
}

Description: Parameters for performing a multi-hop exact input swap.

---

struct ExactOutputSingleParams {
    address tokenIn;
    address tokenOut;
    uint24 fee;
    address recipient;
    uint256 deadline;
    uint256 amountOut;
    uint256 amountInMaximum;
    uint160 sqrtPriceLimitX96;
}

Description: Parameters for performing a single exact output swap.

---

struct ExactOutputParams {
    bytes path;
    address recipient;
    uint256 deadline;
    uint256 amountOut;
    uint256 amountInMaximum;
}

Description: Parameters for performing a multi-hop exact output swap.

---

Events

---

The SwapRouter contract does not define its own events. It relies on events emitted by the StoryHuntV3Pool during swap operations and other interactions. Users can monitor these events through the pool contracts.

---

Usage Notes

1. Performing Exact Input Swaps

   • Function: exactInputSingle() and exactInput()

   • Description:

     • Use exactInputSingle() for single-hop swaps between two tokens within a specific pool.

     • Use exactInput() for multi-hop swaps across multiple pools.

   • Steps:

     1. Define the tokens involved and the fee tier.

     2. Specify the desired input amount and the minimum acceptable output.

     3. Call the appropriate function with the required parameters.

     4. Ensure that the transaction is executed before the deadline.

2. Performing Exact Output Swaps

   • Function: exactOutputSingle() and exactOutput()

   • Description:

     • Use exactOutputSingle() for single-hop swaps where you specify the exact amount of output tokens you want.

     • Use exactOutput() for multi-hop swaps to achieve a specific output amount across multiple pools.

   • Steps:

     1. Define the tokens involved and the fee tier.

     2. Specify the desired output amount and the maximum acceptable input.

     3. Call the appropriate function with the required parameters.

     4. Ensure that the transaction is executed before the deadline.

3. Handling Callbacks

   • Function: storyHuntV3SwapCallback()

   • Description:

     • After initiating a swap, the pool contract will call this callback to request the payment of tokens owed.

     • Ensure that your contract correctly implements the callback to handle the token transfers.

   • Requirements:

     • Only the legitimate pool contract can invoke this callback.

     • Proper validation using CallbackValidation is essential to prevent unauthorized calls.

4. Path Encoding

   • Description:

     • The path parameter in multi-hop swaps must be encoded using the Path library.

     • Each segment of the path consists of a token address followed by the fee tier.

   • Usage:

     • For example, to swap Token A → Token B → Token C, the path would be encoded as abi.encodePacked(tokenA, feeAB, tokenB, feeBC, tokenC).