Vault

Escrow contract for managing cross-chain reward payments

Overview

The Vault contract is an escrow contract for managing cross-chain reward payments. It implements a lifecycle-based vault that can be funded, withdrawn from, or refunded.

Contract Location: contracts/vault/Vault.sol

Implements: IVault

Vault contracts are created deterministically using CREATE2 by the IntentSource contract. Each intent gets its own dedicated vault for holding rewards.

State Variables

portal

address private immutable portal

Address of the portal contract that can call this vault. Only the portal can call fund, withdraw, refund, and recover functions.

Constructor

Vault()

constructor()

Creates a new vault instance. Sets the deployer (IntentSource) as the authorized portal contract.

The constructor automatically sets msg.sender as the portal, ensuring only the deploying contract can manage vault operations.

State-Changing Functions

fundFor

function fundFor(
    Reward calldata reward,
    address funder,
    IPermit permit
) external payable onlyPortal returns (bool fullyFunded)

Funds the vault with tokens and native currency from the reward.

reward · Reward

The reward structure containing token addresses, amounts, and native value

funder · address

Address that will provide the funding

permit · IPermit

Optional permit contract for gasless token approvals

fullyFunded · bool

True if the vault was fully funded, false otherwise

This function is payable to accept native tokens (ETH). It first attempts to use the permit contract for gasless approvals, then falls back to standard ERC20 transfers if needed.

---

withdraw

function withdraw(
    Reward calldata reward,
    address claimant
) external onlyPortal

Withdraws rewards from the vault to the specified claimant.

reward · Reward

The reward structure defining what to withdraw

claimant · address

Address that will receive the withdrawn rewards

The function withdraws the minimum of the reward amount and the vault’s actual balance for each token. This allows partial withdrawals if the vault is not fully funded.

---

refund

function refund(
    Reward calldata reward,
    address refundee
) external onlyPortal

Refunds all vault contents to a specified address.

reward · Reward

The reward structure containing token information

refundee · address

Address to receive the refunded rewards

Unlike withdraw, this function refunds the entire balance of each token and all native currency in the vault, not just the reward amounts.

---

recover

function recover(
    address refundee,
    address token
) external onlyPortal

Recovers tokens that are not part of the reward to the creator.

refundee · address

Address to receive the recovered tokens

token · address

Address of the token to recover (must not be a reward token)

This function is used to recover tokens that were sent to the vault by mistake. The token must not be among the reward tokens, and the vault must have a non-zero balance of the token.

Errors

NotPortalCaller

error NotPortalCaller(address caller)

Thrown when a non-portal address attempts to call a restricted function.

NativeTransferFailed

error NativeTransferFailed(address recipient, uint256 amount)

Thrown when a native token transfer fails.

ZeroRecoverTokenBalance

error ZeroRecoverTokenBalance(address token)

Thrown when attempting to recover a token with zero balance.

Access Control

All state-changing functions use the onlyPortal modifier, which ensures that only the portal contract can:

• Fund the vault
• Withdraw rewards to claimants
• Refund rewards to creators
• Recover mistakenly sent tokens

This design ensures that vault operations are properly authorized and follow the intent lifecycle managed by the portal.

Usage Example

// Vault is created deterministically by IntentSource
address vaultAddress = intentSource.intentVaultAddress(intent);

// Fund vault (called internally by IntentSource)
vault.fundFor{value: 1 ether}(reward, funder, permitContract);

// Withdraw to claimant (after intent is proven)
vault.withdraw(reward, claimantAddress);

// Refund if intent expires
vault.refund(reward, creatorAddress);