How the vault contract works

Documentation Index

Fetch the complete documentation index at: https://eco.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

Architecture

Vault Implementation (deployed once)
    ↓
Proxy (deployed per intent via CREATE2)
    ↓ delegates to
Vault Implementation

• One vault per intent, deployed on-demand
• Deterministic addresses computed from intent hash
• Only the Portal can manage vault operations
• No persistent state between intents (stateless implementation)

​

Deployment

​

CREATE2 Determinism

address vaultAddress = keccak256(
    abi.encodePacked(
        CREATE2_PREFIX,        // 0xff (standard) or 0x41 (TRON)
        portalAddress,         // Deployer
        intentHash,            // Salt
        keccak256(             // Init code hash
            abi.encodePacked(
                type(Proxy).creationCode,
                abi.encode(vaultImplementation)
            )
        )
    )
)

​

On-Demand Deployment

• Intent Publishing: Address is computed but not deployed
• First Funding: Vault deployed if not already exists
• Withdrawal/Refund: Vault deployed if not already exists

​

Chain Compatibility

• Standard EVM Chains: 0xff prefix
• TRON Mainnet (728126428): 0x41 prefix
• TRON Testnet (2494104990): 0x41 prefix

​

Access Control

modifier onlyPortal()

• Only validated intents can withdraw funds
• Refunds require proper deadline checks
• Token recovery follows protocol rules

​

Funding

​

Standard Funding

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

1. Check native token balance against reward.nativeAmount
2. For each ERC20 token:
   • Attempt permit-based transfer first (if permit contract provided)
   • Fall back to standard transferFrom with allowance
3. Return true only if all tokens fully funded

• Funder’s token balance
• Funder’s allowance/permit to vault
• Existing vault balance

​

Permit-Based Funding

function _fundFromPermit(
    address funder,
    IERC20 token,
    uint256 rewardAmount,
    IPermit permit
) internal returns (uint256 remaining)

function _fundFrom(
    address funder,
    IERC20 token,
    uint256 remainingAmount
) internal returns (uint256 remaining)

1. Check current vault balance
2. Try permit transfer if permit contract provided
3. Fall back to standard transfer for any remaining amount
4. Return unfunded amount

​

Withdrawal

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

1. Transfer all reward ERC20 tokens to claimant (up to reward amounts)
2. Transfer native tokens to claimant (up to reward amount)
3. Use actual balance (may be less than reward if partially funded)

• Uses SafeERC20.safeTransfer for token transfers
• Minimum of reward amount and actual balance prevents over-withdrawal
• Native transfers use low-level call with success check
• Reverts on failed native transfer with NativeTransferFailed error

​

Refund

function refund(Reward calldata reward) external onlyPortal

1. Transfer all ERC20 token balances to reward.creator
2. Transfer all native token balance to reward.creator
3. No amount restrictions (returns full vault contents)

• Returns actual balance, not limited to reward amounts
• Always transfers to reward.creator
• Portal validates deadline before calling

​

Token Recovery

function recover(address refundee, address token) external onlyPortal

• User accidentally sent tokens directly to vault address
• Tokens sent to wrong vault
• Extra tokens beyond reward amounts

• Cannot recover zero address (native tokens)
• Cannot recover any token in reward.tokens array
• Intent must have zero native rewards OR already be claimed/refunded

​

Fund Flow

​

Publishing Flow

User → Portal.publishAndFund()
    ↓
Portal → Vault.fundFor()
    ↓
Vault ← User (tokens via transferFrom/permit)

​

Withdrawal Flow

Solver → Portal.withdraw()
    ↓
Portal → Prover (verify proof)
    ↓
Portal → Vault.withdraw()
    ↓
Vault → Solver (claimant address)

​

Refund Flow

Creator → Portal.refund()
    ↓
Portal (validates deadline/proof)
    ↓
Portal → Vault.refund()
    ↓
Vault → Creator

​

Security Model

​

Immutable Portal

address private immutable portal;

• Unauthorized withdrawals
• Fake refunds before expiry
• Bypassing protocol validation

​

Balance-Based Logic

• No accounting variables to manipulate
• Always transfers real tokens held by vault
• Cannot withdraw more than vault contains

​

SafeERC20 Integration

• Handles non-standard ERC20 returns
• Prevents silent transfer failures
• Reverts on insufficient balance

​

Minimal Proxy Pattern

• Gas Efficiency: ~2,500 gas to deploy vs ~200,000 for full contract
• Security: Implementation cannot be changed after proxy deployment
• Predictability: Deterministic addresses enable pre-funding

​

Integration Examples

​

Computing Vault Address

// From Portal
Intent memory intent = /* ... */;
address vault = portal.intentVaultAddress(intent);

// Or with components
bytes32 intentHash = portal.getIntentHash(
    destination,
    route,
    reward
);
address vault = portal.intentVaultAddress(
    destination,
    abi.encode(route),
    reward
);

​

Pre-Funding Vault

// Compute vault address
address vault = portal.intentVaultAddress(intent);

// Send tokens to vault
IERC20(tokenAddress).transfer(vault, amount);

// Publish without funding (vault already has tokens)
portal.publish(intent);

​

Partial Funding

// User has limited balance
uint256 userBalance = token.balanceOf(user);
uint256 rewardAmount = 1000e18;

// Approve partial amount
token.approve(address(portal), userBalance);

// Publish with partial funding allowed
portal.publishAndFund{value: nativeAmount}(intent, true);
// allowPartial = true

// Check funding status
bool funded = portal.isIntentFunded(intent);
// Returns false if partially funded

​

Using Permit for Gasless Funding

// User signs permit off-chain
IPermit permit = IPermit(permitContract);

// Relayer calls publishAndFundFor
portal.publishAndFundFor(
    intent,
    true,              // allowPartial
    user,              // funder
    address(permit)    // permit contract
);

// Vault uses permit.transferFrom instead of token.transferFrom

​

Error Handling

• NotPortalCaller(address): Caller is not the authorized Portal contract
• NativeTransferFailed(address, uint256): Failed to send native tokens to recipient
• ZeroRecoverTokenBalance(address): Attempted to recover token with zero balance

​

Gas Considerations

​

Deployment Costs

• Full Vault Contract: ~200,000 gas
• Minimal Proxy: ~2,500 gas (98.75% savings)
• Implementation: One-time cost, shared across all vaults

​

Operation Costs

• Native transfer: ~21,000 gas
• ERC20 transfer: ~50,000 gas per token
• Permit transfer: ~70,000 gas per token (includes permit verification)

• Per token: ~50,000 gas
• Native transfer: ~21,000 gas

• Similar to withdrawal costs
• No amount validation overhead

​

Optimization Strategies

1. Batch Operations: Use Portal.batchWithdraw() to amortize vault deployment costs
2. Pre-Funding: Send tokens to vault address before publishing to skip funding transaction
3. Single Token Rewards: Minimize token array length in rewards
4. Standard Transfers: Use regular approvals instead of permits when possible (lower gas)

​

Cross-Chain Considerations

​

Address Consistency

• Portal deployment address
• Intent parameters (destination, route, reward)
• CREATE2 prefix (chain-specific)

Ethereum: 0x1234...5678 (0xff prefix)
TRON:     0x4321...8765 (0x41 prefix, different address)

​

Native Token Handling

• Ethereum: ETH
• Polygon: MATIC
• Arbitrum: ETH
• TRON: TRX

​

Best Practices

​

For Intent Creators

1. Verify Funding: Call portal.isIntentFunded() before expecting fulfillment
2. Adequate Approvals: Ensure sufficient allowance for all reward tokens
3. Gas Budgeting: Include native amount for destination chain execution
4. Deadline Buffer: Set reward.deadline with buffer for proof verification time

​

For Solvers

1. Check Vault Balance: Verify vault is fully funded before fulfilling
2. Gas Estimation: Account for withdrawal transaction costs in profitability calculations
3. Claimant Address: Ensure claimant address is correct and can receive tokens
4. Token Compatibility: Verify all reward tokens are standard ERC20

​

For Integrators

1. Address Prediction: Compute vault addresses off-chain to display to users
2. Event Monitoring: Watch IntentFunded events to track funding progress
3. Error Handling: Handle partial funding scenarios gracefully
4. Permit Integration: Support gasless approvals for better UX