Developers
Search…
Internal User Balances

Overview

Similar to how the Vault keeps track of what tokens are in a pool, the Vault can also maintain balances for users or any other smart contract. Balances can be deposited to, withdrawn from, and transferred. When utilizing internal balances in Balancer transactions (swap/join/trade), gas costs are reduced since there are fewer (or no) ERC20 tokens transferred and everything is handled by the Vault's bookkeeping.

API

1
// Vault function
2
manageUserBalance(
3
UserBalanceOp[] ops
4
)
5
6
// Struct Definition
7
UserBalanceOp{
8
uint8 kind,
9
address asset,
10
uint256 amount,
11
address sender,
12
address recipient
13
}
14
15
// Relevant Enum definition for "kind"
16
enum UserBalanceOpKind {
17
DEPOSIT_INTERNAL,
18
WITHDRAW_INTERNAL,
19
TRANSFER_INTERNAL,
20
TRANSFER_EXTERNAL
21
}
Copied!

Arguments Explained

  • ops - An array of UserBalanceOps, explained below
    • kind - Enum of type UserBalanceOpKind
    • asset - The token you are moving
    • sender - Address sending tokens or internal balance
    • recipient - Address receiving tokens or internal balance

Enums Explained

This explanation is copied for convenience from the original UserBalanceOpKind definition in IVault.sol.
  • DEPOSIT_INTERNAL
    • Increases the Internal Balance of the recipient account by transferring tokens from the correspondingsender. The sender must have allowed the Vault to use their tokens via IERC20.approve(). ETH can be used by passing the ETH sentinel value (the zero address) as the asset and forwarding ETH in the call: it will be wrapped and deposited as WETH. Any ETH amount remaining will be sent back to the caller (not the sender, which is relevant for relayers). Emits an InternalBalanceChanged event.
  • WITHDRAW_INTERNAL
    • Decreases the Internal Balance of the sender account by transferring tokens to the recipient. ETH can be used by passing the ETH sentinel value (the zero address) as the asset. This will deduct WETH instead, unwrap it and send
      it to the recipient as ETH. Emits an InternalBalanceChanged event.
  • TRANSFER_INTERNAL
    • Transfers tokens from the Internal Balance of the sender account to the Internal Balance of recipient. Reverts if the ETH sentinel value (the zero address) is passed. Emits an InternalBalanceChanged event.
  • TRANSFER_EXTERNAL
    • Transfers tokens from sender to recipient, using the Vault's ERC20 allowance. This is typically used by relayers, as it lets them reuse a user's Vault allowance. Reverts if the ETH sentinel value (the zero address) is passed. Emits an ExternalBalanceTransfer event.
Last modified 3mo ago