### Retry Payload Data Structure

Source: https://docs.superform.xyz/core-contracts/amb-implementations/layerzerov2implementation

Defines the data structure required for retrying payloads, which includes origin details, receiver address, GUID, message, and extra data.

```solidity
(Origin memory origin, address receiver, bytes32 guid, bytes memory message, bytes memory extraData)
```

--------------------------------

### Burning SuperPositions

Source: https://docs.superform.xyz/periphery-contracts/superpositions

Functions for burning SuperPositions, typically called optimistically at the start of a withdrawal action. These functions are initiated via calls from a SuperformRouter.

```APIDOC
function burnBatch(
    address srcSender_,
    uint256[] memory ids_,
    uint256[] memory amounts_
)
    external
    virtual
    override;

Parameters:
  srcSender_: address of user who owns the `SuperPositions`
  ids_: uint256 ids of `Superforms`
  amounts_: uint256 amounts of the `SuperPositions` being burned
```

```APIDOC
function burnSingle(address srcSender_, uint256 id_, uint256 amount_) external virtual override;

Parameters:
  srcSender_: address of user who owns the `SuperPositions`
  id_: uint256 id of a `Superform`
  amount_: uint256 amount of the `SuperPosition` being burned
```

--------------------------------

### LayerZeroV2 Configuration Setters

Source: https://docs.superform.xyz/core-contracts/amb-implementations/layerzerov2implementation

Provides API documentation for configuration setters within the LayerzeroV2Implementation contract, accessible only by addresses with the PROTOCOL_ADMIN_ROLE.

```apidoc
setChainId
  Sets the mapping between Superform's internal chain IDs and LayerZeroV2's allocated chain IDs.
  Parameters:
    - superChainId_ (uint64): The internal chain ID used by the Superform protocol, derived from block.chainid.
    - ambChainId_ (uint16): The chain ID allocated to the chain by LayerZeroV2.
  Usage:
    setChainId(uint64 superChainId_, uint16 ambChainId_) external

setLzEndpoint
  Updates or sets the LayerZeroV2 endpoint contract address.
  Parameters:
    - endpoint_ (address): The address of the LayerZeroV2's endpoint contract.
  Usage:
    setLzEndpoint(address endpoint_) external

setPeer
  Associates a peer address with a specific LayerZero endpoint ID.
  Parameters:
    - eid_ (uint32): The endpoint ID of the peer.
    - peer_ (bytes32): The address of the peer to be associated.
  Usage:
    setPeer(uint32 eid_, bytes32 peer_) external override onlyProtocolAdmin

setDelegate
  Sets the LayerZeroV2 delegate address.
  Parameters:
    - delegate_ (address): The LayerZeroV2 delegate address.
  Usage:
    setDelegate(address delegate_) external override onlyProtocolAdmin
```

--------------------------------

### startCrossChainRebalanceMulti Solidity Function

Source: https://docs.superform.xyz/periphery-contracts/superformrouter/superformrouterplus

Initiates the cross-chain rebalance of multiple positions. Handles cross-chain transfers, interim assets, and rebalancing logic across multiple positions.

```APIDOC
startCrossChainRebalanceMulti(InitiateXChainRebalanceMultiArgs memory args) external payable
  - Starts the cross-chain rebalance of multiple positions.
  - Parameters:
    - args: Structure containing rebalance arguments.
      - ids: An array of position IDs to rebalance.
      - sharesToRedeem: The number of shares to redeem for each position.
      - receiverAddressSP: The address to receive the rebalanced positions.
      - interimAsset: The interim asset used during the cross-chain rebalance.
      - finalizeSlippage: The slippage tolerance for finalization.
      - expectedAmountInterimAsset: The expected amount of interim asset to receive.
      - rebalanceToSelector: The selector of the rebalance function to call on the destination chain.
      - callData: The call data to pass for the rebalance.
      - rebalanceToAmbIds: The array of AMB (Asynchronous Message Bus) IDs.
      - rebalanceToDstChainIds: The destination chain IDs.
      - rebalanceToSfData: Additional data for Superform-specific rebalances.
  - Returns: None (external payable function).
```

--------------------------------

### Get Superform Count (SuperformFactory)

Source: https://docs.superform.xyz/periphery-contracts/superformfactory

Returns the total number of Superforms that have been created on the current chain. This count reflects the number of vault-form associations established.

```solidity
function getSuperformCount() 
    external view override returns (
        uint256 superforms_)

```

--------------------------------

### Get Form Count (SuperformFactory)

Source: https://docs.superform.xyz/periphery-contracts/superformfactory

Retrieves the total number of Form implementations that have been registered on the current chain. This view function provides a count of available yield adapters.

```solidity
function getFormCount() 
    external view override returns (
        uint256 forms_)

```

--------------------------------

### LiqRequest Parameters

Source: https://docs.superform.xyz/periphery-contracts/superformrouter

Details the parameters for the LiqRequest structure, explaining their purpose, data types, and usage in liquidity operations.

```APIDOC
LiqRequest:
  txData: bytes
    Description: bytes txData to move funds, obtained via starting routes through the appropriate bridgeId API below. Optional to implement on withdrawals, Keeper will update.

  token: address
    Description: address of the token the user is using or requesting. On deposits this is the user's starting token, and on withdrawals this is the token the user wants to receive on the appropriate liqDstChainId.

  interimToken: address
    Description: address of the token that is allowed to be used as an interim token on the destination chain on deposits by DstSwapper to be swapped into the vault token. Will be set to 0 on withdrawals.

  bridgeId: uint8
    Description: uint8 representing the bridge being used. 1 = LiFi, 2 = Socket, 3 = SocketOneInch.
    References: [LiFi API](https://apidocs.li.fi/reference/welcome-to-the-lifinance-api), [Socket API](https://docs.socket.tech/socket-overview/what-is-socket)

  liqDstChainId: uint64
    Description: uint64 representing the final destination chain for the liquidity in the bridgeRequest. On deposits it is the same as the chain of the Superform, but on withdrawals it can be any supported chain id by the bridge.

  nativeAmount: uint256
    Description: uint256 amount of native tokens that will be passed in the liquidity request (0 if native tokens are not being swapped or bridged).
```

--------------------------------

### Hyperlane Configuration Setters

Source: https://docs.superform.xyz/core-contracts/amb-implementations/hyperlaneimplementation

API documentation for configuration setters within the HyperlaneImplementation contract, managed by the PROTOCOL_ADMIN.

```APIDOC
setChainId:
  Signature: function setChainId(
    uint64 superChainId_,
    uint16 ambChainId_
  ) external onlyProtocolAdmin
  Description: Maps a Hyperlane chain ID to Superform's internal chain ID (EVM ID).
  Parameters:
    - superChainId_ (uint64): The internal chain ID used by the Superform protocol, derived from block.chainid.
    - ambChainId_ (uint16): The chain ID allocated to the chain by Hyperlane.

setReceiver:
  Signature: function setReceiver(
    uint32 domain_,
    address authorizedImpl_
  ) external onlyProtocolAdmin
  Description: Sets receiver implementations for a new chain ID, authorizing a Hyperlane message bridge.
  Parameters:
    - domain_ (uint32): Hyperlane's chain ID.
    - authorizedImpl_ (address): The address of the Hyperlane message bridge on the respective chain.
```

--------------------------------

### LiqRequest Parameters

Source: https://docs.superform.xyz/periphery-contracts

Details the parameters for the LiqRequest structure, explaining their purpose, data types, and usage in liquidity operations.

```APIDOC
LiqRequest:
  txData: bytes
    Description: bytes txData to move funds, obtained via starting routes through the appropriate bridgeId API below. Optional to implement on withdrawals, Keeper will update.

  token: address
    Description: address of the token the user is using or requesting. On deposits this is the user's starting token, and on withdrawals this is the token the user wants to receive on the appropriate liqDstChainId.

  interimToken: address
    Description: address of the token that is allowed to be used as an interim token on the destination chain on deposits by DstSwapper to be swapped into the vault token. Will be set to 0 on withdrawals.

  bridgeId: uint8
    Description: uint8 representing the bridge being used. 1 = LiFi, 2 = Socket, 3 = SocketOneInch.
    References: [LiFi API](https://apidocs.li.fi/reference/welcome-to-the-lifinance-api), [Socket API](https://docs.socket.tech/socket-overview/what-is-socket)

  liqDstChainId: uint64
    Description: uint64 representing the final destination chain for the liquidity in the bridgeRequest. On deposits it is the same as the chain of the Superform, but on withdrawals it can be any supported chain id by the bridge.

  nativeAmount: uint256
    Description: uint256 amount of native tokens that will be passed in the liquidity request (0 if native tokens are not being swapped or bridged).
```

--------------------------------

### Get Form Implementation Address (SuperformFactory)

Source: https://docs.superform.xyz/periphery-contracts/superformfactory

Returns the contract address of a specific Form implementation, identified by its uint32 ID. This allows querying which implementation is associated with a given ID.

```solidity
function getFormImplementation(uint32 formImplementationId_) 
    external view override returns (address)

```

--------------------------------

### ERC20 to ERC1155A Transmutation API Reference

Source: https://docs.superform.xyz/periphery-contracts/superpositions/erc1155a

Detailed API documentation for the transmutation functions, outlining parameters, their types, and descriptions. This section provides a structured view of the function signatures and their expected inputs.

```APIDOC
Transmutation Functions:

1. transmuteToERC1155A
   - Converts a specified amount of an ERC20 token to its corresponding ERC1155A tokenId.
   - Signature: transmuteToERC1155A(address owner, uint256 id, uint256 amount, address receiver) external override
   - Parameters:
     - owner (address): The address of the user initiating the transmutation.
     - id (uint256): The ERC1155A ID corresponding to the token being transmuted.
     - amount (uint256): The quantity of the ERC20 token to transmute.
     - receiver (address): The address where the resulting ERC1155A tokenId will be sent.
   - Returns: None (external function).
   - Notes: This is a single token transmutation.

2. transmuteBatchToERC1155A
   - Converts specified amounts of multiple ERC20 tokens to their corresponding ERC1155A tokenIds in a single transaction.
   - Signature: transmuteBatchToERC1155A(address owner, uint256[] memory ids, uint256[] memory amounts, address receiver) external override
   - Parameters:
     - owner (address): The address of the user initiating the transmutation.
     - ids (uint256[] memory): An array of ERC1155A IDs corresponding to the tokens being transmuted.
     - amounts (uint256[] memory): An array of quantities, where each element corresponds to the amount of the ERC20 token for the respective ID in the 'ids' array.
     - receiver (address): The address where the resulting ERC1155A tokenIds will be sent.
   - Returns: None (external function).
   - Notes: The 'ids' and 'amounts' arrays must have the same length. This function is optimized for batch operations.
```

--------------------------------

### Get Superform Details (SuperformFactory)

Source: https://docs.superform.xyz/periphery-contracts/superformfactory

Decodes a given superformId to retrieve the associated Superform address, the form ID it was added to, and the chain ID on which it was created. This function works across different chains.

```solidity
function getSuperform(uint256 superformId)
    external pure override returns (
        address superform_,
        uint32 formBeaconId_,
        uint64 chainId_)

```

--------------------------------

### Minting SuperPositions

Source: https://docs.superform.xyz/periphery-contracts/superpositions

Functions for minting SuperPositions. `mintSingle` and `mintBatch` are for same-chain deposits, while `stateMultiSync` and `stateSync` handle cross-chain deposit callbacks. These are restricted to specific callers like SuperformRouter or CoreStateRegistry.

```APIDOC
function mintBatch(
    address receiverAddressSP_,
    uint256[] memory ids_,
    uint256[] amounts_
)
    external
    virtual
    override;

Parameters:
  receiverAddressSP_: address of the receiver of the `SuperPositions`
  ids_: uint256 ids of `Superforms`
  amounts_: uint256 amounts of the `SuperPositions` being minted
```

```APIDOC
function mintSingle(address receiverAddressSP_, uint256 id_, uint256 amount_) external virtual override;

Parameters:
  receiverAddressSP_: address of the receiver of the `SuperPositions`
  id_: uint256 id of a `Superform`
  amount_: uint256 amount of the `SuperPositions` being minted
```

```APIDOC
function stateMultiSync(AMBMessage memory data_) external virtual override returns (uint64 srcChainId_);
function stateSync(AMBMessage memory data_) external virtual override returns (uint64 srcChainId_);

Parameters:
  data_: `AMBMessage` struct containing cross-chain data.

Note: It is the responsibility of each implementation contract to support these functions and make them perform according to the intended specification.
```

--------------------------------

### Get Sync Withdraw Tx Data Payload Counter

Source: https://docs.superform.xyz/core-contracts/state-registries/asyncstateregistry

Returns the number of sync withdraw payloads received by the async state registry. This is a view function, meaning it does not modify the blockchain state.

```Solidity
function syncWithdrawTxDataPayloadCounter() external view returns (uint256);
```

--------------------------------

### Query CrossChain Initiated Transactions (GraphQL)

Source: https://docs.superform.xyz/resources/subgraphs/deposits-and-withdrawals

Tracks cross-chain withdrawals or deposits initiated from a specific chain. This query provides the transaction hash and payload IDs, useful for monitoring the start of cross-chain flows. Note that these transactions may not be completed on destination chains.

```graphql
{
  crossChainInitiatedTransactions(first:5){
    id
    transactionHash
    srcPayloadId
    blockNumber
    blockTimestamp
  }
}
```

--------------------------------

### PaymentHelperConfig Data Structure

Source: https://docs.superform.xyz/periphery-contracts/paymenthelper

Defines the configuration parameters for the PaymentHelper contract, including oracle addresses, gas estimations, and fallback prices for native tokens and gas.

```APIDOC
struct PaymentHelperConfig {
        address nativeFeedOracle;
        address gasPriceOracle;
        uint256 swapGasUsed;
        uint256 updateGasUsed;
        uint256 depositGasUsed;
        uint256 withdrawGasUsed;
        uint256 defaultNativePrice;
        uint256 defaultGasPrice;
        uint256 dstGasPerByte;
        uint256 ackGasCost;
        uint256 timelockCost;
        uint256 emergencyCost;
}

Parameters:
  nativeFeedOracle: address of the Chainlink native token / USD price feed (i.e. AVAX/USD)
  gasPriceOracle: address of the Chainlink gas price feed
  swapGasUsed: uint256 estimated gas consumed to make a swap on the specified chain
  updateGasUsed: uint256 estimated gas consumed in updating a payload on the chain
  depositGasUsed: uint256 estimated gas consumed in calling `vault.deposit()` on that chain via Superform
  withdrawGasUsed: uint256 estimated gas consumed in calling `vault.redeem()` on that chain via Superform
  defaultNativePrice: uint256 price of the native token to use as fallback if Chainlink price feed not available
  defaultGasPrice: uint256 average gas price to use as fallback if Chainlink gas feed not available
  dstGasPerByte: uint256 gas per size of data
  ackGasCost: uint256 gas cost for processing ack on the source chain
  timelockCost: unit256 cost for processing time-locked payloads
  emergencyCost: uint256 cost for processing withdrawals sent to the emergency queue if Forms are paused
```

--------------------------------

### AddressLib: Address Utility Functions

Source: https://docs.superform.xyz/core-contracts/bridge-validators/oneinchvalidator

Provides utility functions for manipulating and extracting data from an address type, which is represented as a uint256. It includes methods to get the address, check flags, and retrieve uint32/uint64 values at specific bit offsets.

```Solidity
// SPDX-License-Identifier: MIT\npragma solidity ^0.8.23;\n\ntype Address is uint256;\n\nuint256 constant _CURVE_TO_COINS_ARG_MASK = 0xff;\nuint256 constant _CURVE_TO_COINS_ARG_OFFSET = 216;\nuint256 constant _PARTIAL_FILL = 1 << 0;\nuint256 constant _REQUIRES_EXTRA_ETH = 1 << 1;\nuint256 constant _USE_PERMIT2 = 1 << 2;\n\nlibrary AddressLib {\n    uint256 private constant _LOW_160_BIT_MASK = (1 << 160) - 1;\n\n    /**\n     * @notice Returns the address representation of a uint256.\n     * @param a The uint256 value to convert to an address.\n     * @return The address representation of the provided uint256 value.\n     */\n    function get(Address a) internal pure returns (address) {\n        return address(uint160(Address.unwrap(a) & _LOW_160_BIT_MASK));\n    }\n\n    /**\n     * @notice Checks if a given flag is set for the provided address.\n     * @param a The address to check for the flag.\n     * @param flag The flag to check for in the provided address.\n     * @return True if the provided flag is set in the address, false otherwise.\n     */\n    function getFlag(Address a, uint256 flag) internal pure returns (bool) {\n        return (Address.unwrap(a) & flag) != 0;\n    }\n\n    /**\n     * @notice Returns a uint32 value stored at a specific bit offset in the provided address.\n     * @param a The address containing the uint32 value.\n     * @param offset The bit offset at which the uint32 value is stored.\n     * @return The uint32 value stored in the address at the specified bit offset.\n     */\n    function getUint32(Address a, uint256 offset) internal pure returns (uint32) {\n        return uint32(Address.unwrap(a) >> offset);\n    }\n\n    /**\n     * @notice Returns a uint64 value stored at a specific bit offset in the provided address.\n     * @param a The address containing the uint64 value.\n     * @param offset The bit offset at which the uint64 value is stored.\n     * @return The uint64 value stored in the address at the specified bit offset.\n     */\n    function getUint64(Address a, uint256 offset) internal pure returns (uint64) {\n        return uint64(Address.unwrap(a) >> offset);\n    }\n}\n
```

--------------------------------

### SuperformRouterPlus: startCrossChainRebalance

Source: https://docs.superform.xyz/periphery-contracts/superformrouter/superformrouterplus

Initiates the cross-chain rebalance of a single position. This function manages the transfer of interim assets across chains and handles slippage tolerances and message passing for the rebalance.

```APIDOC
function startCrossChainRebalance(InitiateXChainRebalanceArgs calldata args) external payable;

Parameters:
  args: Structure containing cross-chain rebalance initiation arguments.
    id (uint256): The ID of the position undergoing cross-chain rebalance.
    sharesToRedeem (uint256): The number of shares to redeem for the rebalance.
    receiverAddressSP (address): The address that will receive the rebalanced position on the destination chain.
    interimAsset (address): The interim asset used during the cross-chain rebalance process.
    finalizeSlippage (uint256): The slippage tolerance during the finalization step of the cross-chain rebalance.
    expectedAmountInterimAsset (uint256): The expected amount of interim asset to receive on the destination chain.
    rebalanceToSelector (bytes4): The function selector of the rebalance function to call on the destination chain.
    callData (bytes): The call data to pass along for the rebalance operation.
    rebalanceToAmbIds (uint32[]): An array of AMB (Asynchronous Message Bus) IDs for the cross-chain rebalance.
    rebalanceToDstChainIds (uint32[]): An array of destination chain IDs for the cross-chain rebalances.
    rebalanceToSfData (bytes): Additional data required for Superform functionality during the cross-chain rebalance.

Description:
  This function is responsible for initiating a cross-chain rebalance for a single SuperPosition. It orchestrates the process by specifying interim assets, slippage, and the necessary data for execution and finalization on the destination chain.
```

--------------------------------

### CoreStateRegistry: Dispatch and Process Payload

Source: https://docs.superform.xyz/e2e-flows/cross-chain-deposit

Manages the cross-chain communication of data and proofs. `dispatchPayload` sends instructions and proofs to other chains, while `processPayload` on the destination chain executes these instructions, such as depositing tokens or minting assets.

```Solidity
function dispatchPayload(
    address _amb,
    bytes calldata _payload,
    bytes calldata _proof
) external;

// _amb: Address of the Arbitrary Message Bridge.
// _payload: Encoded data and instructions for the destination chain.
// _proof: Proof verifying the integrity of the payload.

function processPayload(
    bytes calldata _payload,
    bytes calldata _proof
) external;

// _payload: Data received from the source chain.
// _proof: Proof verifying the received payload.
```

--------------------------------

### ERC7540Form Contract Methods

Source: https://docs.superform.xyz/periphery-contracts/forms/erc7540form

API documentation for the ERC7540Form contract, detailing methods for processing two-step deposits and redeems via the AsyncStateRegistry. These functions manage the state transitions and asset handling for asynchronous vault operations.

```solidity
function claimDeposit(
 address user_,
 uint256 superformId_,
 uint256 amountToClaim_,
 bool retain4626_
) external onlyAsyncStateRegistry returns (uint256 shares);

  Parameters:
    user_: The address of the user who made the deposit request.
    superformId_: The unique id of the superform to deposit to.
    amountToClaim_: Amount of assets that are made available to be deposited by the vault.
    retain4626_: Flag to represent if the user wants to mint superpositions post the deposit action.
  Returns:
    shares: The number of shares minted for the user.
```

```solidity
function claimRedeem(
  address user_,
  uint256 superformId_,
  uint256 amountToClaim_,
  uint256 maxSlippage_,
  uint8 isXChain_,
  uint64 srcChainId_,
  LiqRequest calldata liqData_
) external onlyAsyncStateRegistry returns (uint256 assets);

  Parameters:
    user_: The address of the user who made the redeem request.
    superformId_: The unique id of the superform to deposit to.
    amountToClaim_: Amount of shares that are made available to be redeemed by the vault.
    maxSlippage_: The slippage that can be allowed post redeem.
    isXChain_: Flag to indicate if the redeem request made is same-chain (or) cross-chain.
    srcChainId_: The chainId from which the request is made.
    liqData_: The liquidity data to process the collateral bridging /swapping post-redeem.
  Returns:
    assets: The amount of assets redeemed by the user.
```

```solidity
function syncWithdrawTxData(SyncWithdrawTxDataPayload memory p_)
  external
  onlyAsyncStateRegistry
  returns (uint256 assets);

  Parameters:
    p_: The sync withdraw payload to redeem.
  Returns:
    assets: The amount of assets redeemed by the user.
```

--------------------------------

### SuperRegistry GraphQL API

Source: https://docs.superform.xyz/resources/subgraphs/protocol-level-entities

API documentation for querying the SuperRegistry contract. This entry details the fields available when querying the 'protocolDeployedAddress' entity, providing addresses for core protocol contracts and related entities like state registries, bridges, and routers.

```APIDOC
SuperRegistry Query:
  Query the SuperRegistry contract to get deployment addresses.
  Use id: "protocolDeployedAddress" to fetch the main registry information.

  Fields:
    - chainID: The Chain ID on which the SuperRegistry is deployed.
    - superRouterAddress: Address of the SuperRouter Smart Contract.
    - superformFactoryAddress: Address of the Superform Factory Smart Contract.
    - superRBACAddress: Address of the SuperRBAC Smart Contract.
    - superPositionsAddress: Address of the SuperPositions Smart Contract.
    - payMasterAddress: Address of the PayMaster Smart Contract.
    - coreStateRegistryAddress: Address of the Core State Registry Smart Contract.
    - paymentAdminAddress: Address of the Payment Admin Smart Contract.
    - paymentHelperAddress: Address of the Payment Helper Smart Contract.
    - payloadHelperAddress: Address of the Payload Helper Smart Contract.
    - twoStepsRegistryProcessor: Address of the Two Steps Registry Smart Contract.
    - coreRegistryUpdaterAddress: Address of the Core Registry Updater Smart Contract.
    - coreRegistryProcessorAddress: Address of the Core Registry Processor Smart Contract.
    - superTransmuterAddress: Address of the SuperTransmuter Smart Contract.
    - timelockStateRegistryAddress: Address of the Timelock State Registry Smart Contract.
    - broadcastRegistryAddress: Address of the Broadcasting Registry Smart Contract.
    - broadcastRegistryProcessorAddress: Address of the Broadcast Registry Processor Smart Contract.
    - permit2Address: Address of the Permit2 Smart Contract.

  Related Entities (Paginated):
    - stateRegistries(first: Int): List of State Registries.
      - chainId: Chain ID.
      - address: Address of the State Registry.
    - bridgeValidatorAddress(first: Int): List of Bridge Validator Smart Contracts.
      - bridgeValidatorId: ID of the Bridge Validator.
      - bridgeValidatorAddress: Address of the Bridge Validator contract.
    - bridgeAddress(first: Int): List of Bridge Smart Contracts.
      - bridgeId: ID of the Bridge.
      - bridgeAddress: Address of the Bridge contract.
    - ambAddress(first: Int): List of Arbitrary Message Bridge (AMB) addresses.
      - ambId: ID of the AMB.
      - ambAddress: Address of the AMB contract.
    - quorumsRequired(first: Int): List of quorums required for messages from different source chains.
      - srcChainId: Chain ID of the source chain.
      - quorumRequired: Quorum required for messages from the source chain.
    - routers(first: Int): List of SuperFormRouters deployed in the protocol.
      - superFormRouterId: ID of the SuperFormRouter.
      - stateSyncerAddress: Address of the state syncer contract.
      - routerAddress: Address of the SuperFormRouter contract on the specific chain.
```

--------------------------------

### Superform Same-chain Deposit API and Contract Flow

Source: https://docs.superform.xyz/e2e-flows/same-chain-deposit

This entry describes the sequence of API requests and contract calls involved in a same-chain deposit. It covers route generation, initiating the deposit via the SuperformRouter, and the internal vault deposit mechanism.

```APIDOC
Superform API & Contract Deposit Flow:

1.  **Route Generation and Selection**
    *   **Action**: User selects vault, funding token, and amount.
    *   **API Request**: User requests routes from the Superform API.
        *   **Endpoint**: `/api/v1/routes` (Hypothetical, based on description)
        *   **Method**: POST
        *   **Request Body**: {
            "fromToken": "0x...",
            "toVault": "0x...",
            "amount": "1000000"
          }
        *   **Response**: List of available swap and deposit routes.
    *   **Action**: User selects a route.

2.  **Token Approval (if needed)**
    *   **Action**: User approves `permit2` contract for the funding token.
    *   **Contract**: `Permit2` (e.g., Uniswap's Permit2)
    *   **Method**: `approve` or `permitTransferFrom` (depending on implementation)
    *   **Parameters**: Token address, spender (SuperformRouter), allowance amount.

3.  **Initiate Deposit via SuperformRouter**
    *   **Action**: User calls `singleDirectSingleVaultDeposit` on the `SuperformRouter` contract.
    *   **Contract**: `SuperformRouter`
    *   **Method**: `singleDirectSingleVaultDeposit(
        address _fundingToken,
        uint256 _amount,
        address _vault,
        bytes _swapAndDepositData
    )`
    *   **Parameters**: 
        *   `_fundingToken`: Address of the token the user is depositing.
        *   `_amount`: The amount of funding tokens to deposit.
        *   `_vault`: The address of the target vault.
        *   `_swapAndDepositData`: Encoded data containing the desired swap route and deposit instructions. This data is typically generated by the Superform API.
    *   **Functionality**: This function handles the atomic execution of swapping (if necessary) and depositing into the specified vault.

4.  **Vault Deposit and Share Minting**
    *   **Internal Call**: `directDepositIntoVault` is called within the `SuperformRouter` or directly by the vault's `Superform` contract.
    *   **Contract**: Vault's `Superform` contract
    *   **Method**: `directDepositIntoVault(
        address _fundingToken,
        uint256 _amount,
        bytes _swapData
    )` (Hypothetical signature)
    *   **Functionality**: 
        *   Performs the actual deposit of tokens into the vault.
        *   If the `_fundingToken` differs from the vault's underlying token, it executes the swap using the provided `_swapData`.
        *   Mints vault shares to the user.

5.  **SuperPositions Minting**
    *   **Action**: `SuperPositions` NFTs are minted to the user.
    *   **Contract**: `SuperPositions`
    *   **Functionality**: Represents the user's position in the vault.
```

--------------------------------

### Solidity: strictlySwapAndCall Function

Source: https://docs.superform.xyz/core-contracts/bridge-validators/debridgevalidator-and-forwarder

Executes a token swap using a specified router and then calls a target contract with provided data. It includes parameters for input/output tokens, amounts, swap details, refund recipient, and target contract information.

```APIDOC
strictlySwapAndCall:
  signature: strictlySwapAndCall(
    address _srcTokenIn,
    uint256 _srcAmountIn,
    bytes memory _srcTokenInPermitEnvelope,
    address _srcSwapRouter,
    bytes calldata _srcSwapCalldata,
    address _srcTokenOut,
    uint256 _srcTokenExpectedAmountOut,
    address _srcTokenRefundRecipient,
    address _target,
    bytes calldata _targetData
  )
  visibility: external
  payable: true
  parameters:
    - name: _srcTokenIn
      type: address
      description: The input token address for the swap.
    - name: _srcAmountIn
      type: uint256
      description: The amount of input tokens to use for the swap.
    - name: _srcTokenInPermitEnvelope
      type: bytes memory
      description: Permit data envelope for the input token.
    - name: _srcSwapRouter
      type: address
      description: The address of the swap router contract.
    - name: _srcSwapCalldata
      type: bytes calldata
      description: Calldata for the swap operation against _srcSwapRouter.
    - name: _srcTokenOut
      type: address
      description: The output token address expected from the swap.
    - name: _srcTokenExpectedAmountOut
      type: uint256
      description: Minimum acceptable amount of output tokens from the swap.
    - name: _srcTokenRefundRecipient
      type: address
      description: Address to send any excess output tokens to.
    - name: _target
      type: address
      description: The contract address to call after a successful swap.
    - name: _targetData
      type: bytes calldata
      description: Calldata to execute against the _target contract.
  returns:
    - None (external payable function)
```

--------------------------------

### InitSingleVaultData Struct Definition

Source: https://docs.superform.xyz/periphery-contracts/forms

Defines the structure used to encapsulate data for single vault deposit and withdrawal actions. It includes parameters for payload identification, amounts, slippage, liquidity data, swap indicators, receiver addresses, and future use.

```Solidity
struct InitSingleVaultData {
    uint256 payloadId;
    uint256 superformId;
    uint256 amount;
    uint256 outputAmount;
    uint256 maxSlippage;
    LiqRequest liqData;
    bool hasDstSwap;
    bool retain4626;
    address receiverAddress;
    address receiverAddressSP;
    bytes extraFormData;
}

// Description of fields:
// payloadId: id of the payload from the source chain (generated in SuperformRouter)
// superformId: id of the Superform to perform the action on
// amount: expected amount of token or vault (deposits = expected token received, withdrawal = SuperPositions burned)
// outputAmount: expected amount of outputs from the deposit/redeem action (deposits = vault shares received, withdrawal = tokens received)
// maxSlippage: acceptable slippage in bps (0-10000)
// liqData: liquidity information for swapping/bridging (see SuperformRouter#liquidity-request)
// hasDstSwap: indicates if the route has a swap on the destination chain
// retain4626: if true, user receives ERC4626 shares instead of SuperPositions
// receiverAddress: address to refund the user on the destination chain if tokens are stuck
// receiverAddressSP: address to mint SuperPositions on the source chain
// extraFormData: reserved for future use
```

--------------------------------

### ERC1155A: Approval Management Functions

Source: https://docs.superform.xyz/periphery-contracts/superpositions/erc1155a

Provides detailed API documentation for managing approvals on ERC1155A tokens. This includes setting approvals for single IDs, multiple IDs, and all IDs, along with their respective parameters and descriptions.

```APIDOC
ERC1155A Approval Functions:

setApprovalForOne(address operator, uint256 id, uint256 amount)
  - Sets an approval for a specific ERC1155A token ID.
  - Parameters:
    - operator (address): The address to grant approval to.
    - id (uint256): The specific token ID to approve.
    - amount (uint256): The amount of tokens approved for the operator.
  - Usage: Allows granular control over token spending for individual IDs.

setApprovalForMany(address operator, uint256[] memory ids, uint256[] memory amounts)
  - Sets approvals for multiple ERC1155A token IDs simultaneously.
  - Parameters:
    - operator (address): The address to grant approval to.
    - ids (uint256[]): An array of token IDs to approve.
    - amounts (uint256[]): An array of amounts corresponding to each ID for approval.
  - Usage: Efficiently manages approvals for a batch of token IDs.

setApprovalForAll(address operator, bool approved)
  - Inherited from ERC1155, this function grants or revokes approval for all token IDs.
  - Parameters:
    - operator (address): The address to grant or revoke approval for.
    - approved (bool): True to approve all IDs, false to revoke.
  - Usage: Provides broad control over an operator's ability to spend tokens across all IDs.
```

--------------------------------

### AsyncStateRegistry Contract API

Source: https://docs.superform.xyz/core-contracts/state-registries/asyncstateregistry

Provides the interface for interacting with the AsyncStateRegistry smart contract. This contract handles the logic for two-step cross-chain actions, managing deposit and withdrawal requests, and updating state configurations.

```APIDOC
AsyncStateRegistry Contract Functions:

updateRequestConfig(uint8 type_, uint64 srcChainId_, bool isDeposit_, uint256 requestId_, InitSingleVaultData memory data_) external
  - Updates the request configuration for a user and superform. This function sets various parameters like srcChainId, requestId, and form-specific data, with the latest configuration being considered final for previous actions.
  - Parameters:
    - type_: The type of request, indicating if the action is same-chain or cross-chain.
    - srcChainId_: The origin chain ID of the request.
    - isDeposit_: A boolean flag indicating if the request is a deposit or a redeem.
    - requestId_: The unique identifier for the request.
    - data_: Request-specific data passed from the form.

claimAvailableDeposits(address user_, uint256 superformId_) external
  - Claims deposits that have been made available for a user to claim from a vault.
  - Parameters:
    - user_: The address of the user whose deposits are available.
    - superformId_: The identifier of the superform from which to claim deposits.

claimAvailableRedeem(address user_, uint256 superformId_, bytes memory updatedTxData_) external
  - Redeems shares that are available after a redemption request has been made. It also handles bridging collateral post-redeem.
  - Parameters:
    - user_: The address of the user whose redeem requests are available.
    - superformId_: The identifier of the superform from which to redeem.
    - updatedTxData_: The transaction data required to bridge collateral after redemption.

receiveSyncWithdrawTxDataPayload(uint64 srcChainId_, InitSingleVaultData calldata data_) external
  - Processes synchronous withdrawal requests for DEPOSIT_ASYNC forms that require a txData update. This function allows the processor to generate txData on-demand to prevent slippage issues when the user only specifies withdrawal intent.
  - Parameters:
    - srcChainId_: The chain ID from which the cross-chain redeem call is invoked.
    - data_: The cross-chain withdrawal data passed from the ERC7540 Form.

processSyncWithdrawWithUpdatedTxData(uint256 payloadId_, bytes calldata txData_) external
  - Completes payloads received via receiveSyncWithdrawTxDataPayload with an updated txData. This function is used by the async state registry processor to finalize user collateral after the redemption process.
  - Parameters:
    - payloadId_: The unique identifier assigned to every payload upon its delivery.
    - txData_: The transaction data to process user collateral after redemption.

getRequestConfig(address user_, uint256 superformId_) external view returns (RequestConfig memory requestConfig)
  - Retrieves the latest request configuration for a user for a specific superform. This is useful for querying the current state of a user's request.
  - Parameters:
    - user_: The wallet address of the user.
    - superformId_: The unique identifier of the superform to query.
  - Returns:
    - requestConfig: A memory struct containing the request configuration details.

getSyncWithdrawTxDataPayload(uint256 payloadId_) external view returns (SyncWithdrawTxDataPayload memory syncWithdrawTxDataPayload_)
  - Retrieves the withdraw tx data payload for DEPOSIT_ASYNC 7540Forms. This function allows querying the specific payload details associated with a given payload ID.
  - Parameters:
    - payloadId_: The unique identifier assigned to every payload upon its delivery.
  - Returns:
    - syncWithdrawTxDataPayload_: A memory struct containing the synchronous withdraw transaction data payload.

Related Functions:
  - Inherits from BaseStateRegistry.
  - Interacts with ERC7540 Forms.
```

--------------------------------

### Create Superform (SuperformFactory)

Source: https://docs.superform.xyz/periphery-contracts/superformfactory

Creates a Superform by associating a vault with a specific Form implementation. It returns the unique superformId and the address of the newly created Superform. Requires the form implementation ID and the vault address.

```solidity
function createSuperform(
    uint32 formImplementationId_,
    address vault_
) external override returns (uint256 superformId_, address superform_)
```

--------------------------------

### LiqRequest Struct Definition

Source: https://docs.superform.xyz/periphery-contracts/superformrouter

Defines the structure for liquidity requests used by SuperformRouter, specifying parameters for bridging and token handling.

```Solidity
struct LiqRequest {
    bytes txData;
    address token;
    address interimToken;
    uint8 bridgeId;
    uint64 liqDstChainId;
    uint256 nativeAmount;
}
```

--------------------------------

### ProtocolLib: Protocol and WETH Handling

Source: https://docs.superform.xyz/core-contracts/bridge-validators/oneinchvalidator

This library extends the Address type to determine the associated protocol (UniswapV2, UniswapV3, Curve) and flags related to WETH handling (unwrap/wrap) and Permit2 usage. It provides methods to query these properties and determine the correct address for pre-transfer operations.

```Solidity
library ProtocolLib {\n    using AddressLib for Address;\n\n    enum Protocol {\n        UniswapV2,\n        UniswapV3,\n        Curve\n    }\n\n    uint256 private constant _PROTOCOL_OFFSET = 253;\n    uint256 private constant _WETH_UNWRAP_FLAG = 1 << 252;\n    uint256 private constant _WETH_NOT_WRAP_FLAG = 1 << 251;\n    uint256 private constant _USE_PERMIT2_FLAG = 1 << 250;\n\n    function protocol(Address self) internal pure returns (Protocol) {\n        // there is no need to mask because protocol is stored in the highest 3 bits\n        return Protocol((Address.unwrap(self) >> _PROTOCOL_OFFSET));\n    }\n\n    function shouldUnwrapWeth(Address self) internal pure returns (bool) {\n        return self.getFlag(_WETH_UNWRAP_FLAG);\n    }\n\n    function shouldWrapWeth(Address self) internal pure returns (bool) {\n        return !self.getFlag(_WETH_NOT_WRAP_FLAG);\n    }\n\n    function usePermit2(Address self) internal pure returns (bool) {\n        return self.getFlag(_USE_PERMIT2_FLAG);\n    }\n\n    function addressForPreTransfer(Address self) internal view returns (address) {\n        if (protocol(self) == Protocol.UniswapV2) {\n            return self.get();\n        }\n        return address(this);\n    }\n}\n
```

--------------------------------

### Set Optimistic Delay Window

Source: https://docs.superform.xyz/core-contracts/settings/superregistry

Configures the optimistic time window for users to dispute proposed rescue amounts. The delay must be between 1 and 24 hours (3600 to 86400 seconds).

```solidity
function setDelay(
    uint256 delay_
) external override onlyProtocolAdmin
```

--------------------------------

### Query ProofReceived GraphQL

Source: https://docs.superform.xyz/resources/subgraphs/deposits-and-withdrawals

Fetches data related to proofs received on the destination chain via data bridges. This query allows inspection of proof IDs, the proof data itself (in bytes), and the block number where the proof was processed. It's essential for verifying cross-chain data integrity.

```graphql
{
  proofReceiveds(first:5){
    id
    proof
    blockNumber
  }
}
```

--------------------------------

### Deposit and Withdrawal Preview Functions

Source: https://docs.superform.xyz/periphery-contracts/forms

Functions that allow users to preview the outcome of deposit or withdrawal operations without executing them. These use the vault's internal conversion logic.

```APIDOC
function previewDepositTo(uint256 assets_)
  public view virtual override returns (uint256)
  - Previews the number of vault shares that would be received for a given amount of assets.
  - Internally calls the vault's `convertToShares` function.

function previewWithdrawFrom(uint256 assets_)
  public view virtual override returns (uint256)
  - Previews the amount of assets that would be withdrawn for a given amount of assets.
  - Internally calls the vault's `previewWithdraw` function.

function previewRedeemFrom(uint256 shares_)
  public view virtual override returns (uint256)
  - Previews the amount of assets that would be received for a given number of vault shares.
  - Internally calls the vault's `previewRedeem` function.
```