TokenZapV1

Facilitates atomic token operations known as "Zaps", allowing the execution of predefined actions on behalf of users, such as deposits or swaps. Supports ERC20 tokens and native gas tokens (e.g., ETH).

Tokens must be transferred to the contract before execution, native tokens could be provided as msg.value. This contract is stateless and does not hold assets between Zaps; leftover tokens can be claimed by anyone. Ensure that Zaps fully utilize tokens or revert to prevent the loss of funds.

State Variables

NATIVE_GAS_TOKEN

address public constant NATIVE_GAS_TOKEN = 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE;

Functions

receive

Allows the contract to receive ETH.

Leftover ETH can be claimed by anyone. Ensure the full balance is spent during Zaps.

receive() external payable;

zap

Performs a Zap action using the specified token and amount. This amount must have previously been transferred to this contract (could also be supplied as msg.value if the token is a native gas token). Zap action will be performed forwarding full msg.value for ERC20s or amount for native gas tokens. Note: all funds remaining after the Zap action is performed can be claimed by anyone. Make sure to spend the full balance during the Zaps and avoid sending extra funds if a single Zap is performed.

The provided ZapData contains the target address and calldata for the Zap action, and must be encoded using the encodeZapData function. Native gas token transfers could be done by using empty payload, this is the only case where target could be an EOA.

function zap(address token, uint256 amount, bytes calldata zapData) external payable returns (bytes4);

Parameters

Name	Type	Description
`token`	`address`	Address of the token to be used for the Zap action.
`amount`	`uint256`	Amount of the token to be used for the Zap action.
`zapData`	`bytes`	Encoded Zap Data containing the target address and calldata for the Zap action.

Returns

Name	Type	Description
`<none>`	`bytes4`	selector Selector of this function to signal the caller about the success of the Zap action.

encodeZapData

Encodes the ZapData for a Zap action.

At the time of encoding, we don't know the exact amount of tokens that will be used for the Zap, as we don't have a quote for performing a Zap. Therefore, a placeholder value for the amount must be used when ABI-encoding the payload. A reference index where the actual amount is encoded within the payload must be provided in order to replace the placeholder with the actual amount when the Zap is performed.

function encodeZapData(
    address target,
    bytes memory payload,
    uint256 amountPosition,
    address finalToken,
    address forwardTo
)
    external
    pure
    returns (bytes memory);

Parameters

Name	Type	Description
`target`	`address`	Address of the target contract.
`payload`	`bytes`	ABI-encoded calldata to be used for the `target` contract call. If the target function has the token amount as an argument, any placeholder amount value can be used for the original ABI encoding of `payload`. The placeholder amount will be replaced with the actual amount when the Zap Data is decoded.
`amountPosition`	`uint256`	Position (start index) where the token amount is encoded within `payload`. This will usually be `4 + 32 * n`, where `n` is the position of the token amount in the list of parameters of the target function (starting from 0). Any value greater than or equal to `payload.length` can be used if the token amount is not an argument of the target function.
`finalToken`	`address`	The token produced as a result of the Zap action (ERC20 or native gas token). A zero address value signals that the Zap action doesn't result in any asset per se, like bridging or depositing into a vault without an LP token. Note: this parameter must be set to a non-zero value if the `forwardTo` parameter is set to a non-zero value.
`forwardTo`	`address`	The address to which `finalToken` should be forwarded. This parameter is required only if the Zap action does not automatically transfer the token to the intended recipient. Otherwise, it must be set to address(0).

decodeZapData

Decodes the ZapData for a Zap action. Replaces the placeholder amount with the actual amount, if it was present in the original payload. Otherwise, returns the original payload as is.

function decodeZapData(
    bytes calldata zapData,
    uint256 amount
)
    public
    pure
    returns (address target, bytes memory payload);

Parameters

Name	Type	Description
`zapData`	`bytes`	Encoded Zap Data containing the target address and calldata for the Zap action.
`amount`	`uint256`	Actual amount of the token to be used for the Zap action.

_forwardToken

Forwards the proceeds of the Zap action to the specified non-zero recipient.

function _forwardToken(address token, address forwardTo) internal;

Errors

TokenZapV1__FinalTokenBalanceZero

error TokenZapV1__FinalTokenBalanceZero();

TokenZapV1__PayloadLengthAboveMax

error TokenZapV1__PayloadLengthAboveMax();

TokenZapV1__TargetZeroAddress

error TokenZapV1__TargetZeroAddress();

TokenZapV1__TokenZeroAddress

error TokenZapV1__TokenZeroAddress();