# Internal Balances

### What are Internal Balances? <a href="#what-are-internal-balances" id="what-are-internal-balances"></a>

Beanstalk uses an Internal Balances system largely inspired by [Balancer's Vault](https://docs.balancer.fi/getting-started/faqs/the-vault#what-are-internal-user-balances). With Internal Balances, Beanstalk is able to store an any ERC-20 token on behalf of a user. Beanstalk stores that the user has that ERC-20 token in [`AppStorage`](/developers/overview/app-storage.md). All functions within Beanstalk that either use a user's ERC-20 tokens or send ERC-20 tokens to a user can send/receive the ERC-20 tokens from the user's Internal Balance and/or External Balance (the user's wallet).

Internal Balances can significantly reduce transaction costs for using tokens that remain in Beanstalk. As more protocols utilize Internal Balances, the gas savings can compound.

{% hint style="warning" %}
In the Beanstalk ecosystem, **Internal Balances** are referred to as **Farm Balances**. Similarly, **External Balances** (balances in the user's wallet) are referred to as **Circulating Balances**. See [Terminology Discrepancies](/developers/misc/terminology-discrepancies.md).
{% endhint %}

### Relevant Contracts <a href="#associated-contracts" id="associated-contracts"></a>

* [`LibTransfer.sol`](https://github.com/BeanstalkFarms/Beanstalk/blob/master/protocol/contracts/libraries/Token/LibTransfer.sol)
* [`LibBalance.sol`](https://github.com/BeanstalkFarms/Beanstalk/blob/master/protocol/contracts/libraries/Token/LibBalance.sol)

### To / From

`LibTransfer` uses the following structs in order to denote the location(s) from which tokens will be used in a function.

```solidity
enum From {
    EXTERNAL,
    INTERNAL,
    EXTERNAL_INTERNAL,
    INTERNAL_TOLERANT
}
```

* `EXTERNAL`: Beanstalk will receive tokens from the user's External Balance;
* `INTERNAL`: Beanstalk will receive tokens from the user's Internal Balance;
* `EXTERNAL_INTERNAL`: Beanstalk will receive tokens from the user's Internal Balance and will receive from their External Balance if there is not enough in the Internal Balance; and
* `INTERNAL_TOLERANT`: Beanstalk will receive tokens from the user's Internal Balance and will not fail if there is not enough in their Internal Balance.

```solidity
enum To {
    EXTERNAL,
    INTERNAL
}
```

* `EXTERNAL` Beanstalk will send tokens to the user's External Balance; and
* `INTERNAL` Beanstalk will send tokens to the user's Internal Balance.

### Transferring Internal / External Balances <a href="#transferring-internal-external-balances" id="transferring-internal-external-balances"></a>

At any time, a user can transfer, add or remove ERC-20 tokens from their Internal Balance through the `transferToken` function in the [`TokenFacet`](/developers/protocol/depot/token-facet.md). `transferToken` is a general transfer method that allows full control of the tokens start/end location (i.e internal to internal, internal to external, external to internal, external to external).

```solidity
function transferToken(
    IERC20 token,
    address recipient,
    uint256 amount,
    LibTransfer.From fromMode,
    LibTransfer.To toMode
) external payable;
```

### Sending Internal / External Balances <a href="#sending-internal-external-balances" id="sending-internal-external-balances"></a>

A function that sends ERC-20 tokens to users can implement Internal Balances by adding the `To` enum in `LibTransfer` to a function's signature.

Then call `sendToken` in `LibTransfer` instead of directly calling the ERC-20 function `transferFrom`.

```solidity
function sendToken(
    IERC20 token,
    uint256 amount,
    address recipient,
    To mode
) internal;
```

### Receiving Internal / External Balances <a href="#receiving-internal-external-balances" id="receiving-internal-external-balances"></a>

A function that receives ERC-20 tokens from users can implement Internal Balances by adding the `From` enum in `LibTransfer` to a function's signature.

Then call `receiveToken` in `LibTransfer` instead of directly calling the ERC-20 function `transfer`.

```solidity
function receiveToken(
    IERC20 token,
    uint256 amount,
    address recipient,
    To mode
) internal;
```

For protocols that are building on top of Beanstalk and want to interact with Internal Balances, they can utilize the functions given in [`TokenFacet`](/developers/protocol/depot/token-facet.md), rather than the library itself.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bean.money/developers/overview/internal-balances.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.