What are Internal Balances?

Beanstalk uses an Internal Balances system largely inspired by Balancer's Vault. 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. 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.

Relevant Contracts

• LibTransfer.sol

• 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.

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.

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

At any time, a user can transfer, add or remove ERC-20 tokens from their Internal Balance through the transferToken function in the TokenFacet. 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).

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

Sending Internal / External Balances

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.

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

Receiving Internal / External Balances

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.

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, rather than the library itself.

The Beanstalk contract is a Diamond – a multi-facet proxy defined in EIP-2535 that can implement functionality from numerous different Facet contracts.

All the Facets share a common storage through the AppStorage pattern. Functionality is shared between Facets through internal Libraries.

Understanding EIP-2535 really helps to understand Beanstalk. This page serves as a resource hub for EIP-2535.

What is a Diamond?

• EIP-2535

• Understanding Diamonds on Ethereum

• How Diamond Upgrades Work

Implementation Tips for Diamonds (which Beanstalk uses)

• AppStorage Pattern for State Variables in Solidity

• How to Share Functions Between Facets of a Diamond

• Accessing State Variables in Libraries

Why use a Diamond?

• Ethereum's Maximum Contract Size Limit is Solved with the Diamond Standard

• 🌱 Beanstalk 🤝 EIP-2535 💎

• Ethereum Diamonds Solve These Problems

More Information on Diamonds

• Beanstalk on Louper, The Ethereum Diamond Inspector

• EIP-2535 Diamonds Discord

• Nick Mudge <> Publius Podcast

Decentralized blockchains like Ethereum impose extreme computational and storage limitations. While centralized computation solutions allow the execution of advanced statistical models on gigabytes of data, decentralized systems force users to pay for every byte stored and basic arithmetic operation performed on-chain.

Decentralized systems will scale infinitely over time, eventually allowing users to perform large scale machine learning operations on decentralized architectures. However, it's imperative to start building, experimenting with and iterating on the financial primitives that will define the foundations of permissionless ecosystems. Otherwise, it is likely that they will merely mimic those of the centralized world. Beanstalk is an attempt at implementing a permissionless fiat currency designed to become the basis of the rent-free economy that decentralized primitives are ushering in.

“Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.” – Antoine de Saint-Exupéry

No one wants to be limited, but resource scarcity forces innovation. For example, because Ethereum does not lend itself to trading on order books, Automated Market Makers (AMMs) like Uniswap and Bancor created liquidity pools based on a predefined pricing curve to create an efficient exchange format (instead of a high frequency order book).

AMMs are still being iterated and innovated on. Uniswap created an order book/AMM hybrid with Uniswap V3. Curve implemented capital efficient pricing curves. Bancor built an omnipool, providing impermanent loss protection. Basin supports a 0% (customizable) fee AMM.

Open source protocols are a public good. More than 250 protocols have forked Uniswap V2 to try to improve on its model. Some may call it competitive, but it is also collaborative. Each implementation is more advanced than its previous iteration and is made possible through increasingly efficient allocation of EVM resources.

Question everything, be critical, and collaborate.

Because Beanstalk is a single contract, all of the Facets can share a common state through the AppStorage pattern.

Each Facet should define the AppStorage storage variable in the base contract and define no other internal or public state variables.

AppStorage internal s;

The AppStorage struct can be found in the AppStorage.sol file.

When adding new state variables, always add them to the end of the AppStorage struct to ensure consistent mapping of state variables to storage slots. When deprecating an unnecessary state variables, either replace it with a different variable denoting that the state variable is deprecated or leave it as is.

In the EVM, data is accessed 32 bytes at a time (known as a slot). Because of this, in Beanstalk, many state variables are packed within the AppStorage struct to reduce gas costs. For example, say that in function foo, the state of 2 uint256 values is changed. Changing a non-zero value to another non-zero value costs 10000 gas (2 * 5000). If the 2 values could be stored in uint128s instead (meaning the data is in one slot), 2100 gas is shaved off, as the state slot is now warm. (If a slot is touched for the first time in a transaction, it is turned from cold to warm for the rest of that transaction. Warm touches are cheaper than cold touches.)

The Agronomics Handbook is a collection of technical documentation about Beanstalk.

Beanstalk forms the monetary basis of an Arbitrum-native, rent-free economy facilitated by the seigniorage of its native fiat currency, a stablecoin called Bean.

Beanstalk strives to create product market fit on both a technical and economic level.

Beanstalk pioneers a path forward for devising more efficient and complex systems. Beanstalk is implemented in Solidity v0.8.20 for intended use in the EVM. Beanstalk leverages EIP-2535 to minimize gas costs and complexity.

The contract code can be found below. Beanstalk is deployed at 0xD1A0060ba708BC4BCD3DA6C37EFa8deDF015FB70.

• If you are looking for non-technical documentation about Beanstalk, check out the Farmers' Almanac.

• If you are looking for comprehensive formulas behind Beanstalk's mechanics, check out the Beanstalk whitepaper.

• If you have any other questions while browsing the Agronomics Handbook, join the Beanstalk Discord and ask in the (#🪵・development) channel!

Please share any feedback on the Agronomics Handbook in the (#📜・docs-feedback) channel in Discord and stay tuned for updates in (#📜・docs-updates). You can submit a pull request to the Agronomics Handbook yourself here.

Links

• Technical Introduction

• Development Ethos

• Protocol Overview

• Beanstalk on GitHub

• Contract Addresses

• Glossary

Beanstalk can be broken down into 7 different Modules consisting of 25 Facets:

• Sun (1 Facet)

• Silo (10 Facets)

• Field (2 Facets)

• Barn (2 Facets)

• Market (1 Facet)

• Farm (5 Facets)

• Diamond (4 Facets)

Sun

The Sun handles moving time forward in Beanstalk. It advances Beanstalk to the next Season.

The Sun consists of 1 Facet:

• SeasonFacet -> Contains the gm function.

Silo

The Silo offers a passive yield opportunity in the form of Bean seigniorage to Farmers who Deposit Beans and other whitelisted assets. Upon Deposit in the Silo, Farmers receive Stalk and Seeds based on the Bean Denominated Value (BDV) Deposited and the asset Deposited.

The Silo consists of 10 Facets:

• SiloFacet -> Where Farmers Deposit, Withdraw, Claim and Transfer assets in/from the Silo.

• BDVFacet -> Handles logic for retrieving the BDV of some amount of a whitelisted asset.

• WhitelistFacet -> Handles the addition and removal of tokens from the Deposit Whitelist.

• ConvertFacet -> Where Farmers Convert a Deposit of a whitelisted asset to a Deposit of another whitelisted asset.

• ConvertGettersFacet -> Contains view functions for Convert data.

• EnrootFacet -> Where Farmers Enroot their Unripe Deposits.

• ApprovalFacet -> Contains logic for Deposit approvals and permits.

• MetadataFacet -> Contains on-chain metadata for the Deposit ERC-1155 tokens.

• MigrationFacet -> Where Farmers migrate to the latest Silo accounting system.

• LegacyClaimWithdrawalFacet -> Facilitates backwards compatibility for Farmers with unclaimed Withdrawals before the Silo V3 upgrade.

Field

The Field is Beanstalk's native credit facility. Anytime Beanstalk is willing to borrow Beans from the market, it issues Soil in the Field. Beans are Sown in exchange for Pods, the Beanstalk-native debt asset. Loans to Beanstalk are issued with a fixed interest rate, known as the Temperature, and an unknown maturity date.

Pods become Harvestable Pods that can be Harvested (redeemed) for 1 Bean each on a First In, First Out (FIFO) basis. There is no penalty for waiting to Harvest Pods.

The Field consists of 2 Facets:

• FieldFacet -> Where Farmers Sow Beans into Pods and Harvest Pods into Beans.

• FundraiserFacet -> Where Farmers create and fund Fundraisers through Sowing non-Bean assets into Pods.

Barn

The Barn was built after Beanstalk was exploited on April 17, 2022. The Barn distributes Bean rewards to those who hold Fertilizer tokens from participation in the Barn Raise. It also handles the Chopping of Unripe Beans and Unripe LP into their underlying assets at a potential penalty.

Unfertilized Beans become Fertilized Beans that can be claimed (redeemed) for 1 Bean each on a pari passu basis. There is no penalty for waiting to claim Fertilized Beans.

The Barn consists of 2 Facets:

• FertilizerFacet -> Where Farmers buy Fertilizer with USDC and claim Beans earned from Fertilizer.

• UnripeFacet -> Allows Farmers to Chop Unripe assets into their underlying assets at a potential penalty.

Market

The Market houses various DEXs for zero fee trading. Currently only Pods can be traded on the Market.

Pods can be bought and sold in a decentralized, trustless fashion on the Pod Market. The Pod Market creates liquidity for Pods through an on-chain order book.

Sellers can List Pods or Fill open Pod Orders placed by buyers. Buyers can Order Pods or Fill open Pod Listings placed by sellers.

The Market consists of 1 Facet:

• MarketplaceFacet -> Contains the Pod Market where Farmers create, Fill and Cancel Pod Listings and Orders, as well as transfer Pods.

Farm

The Farm allows Farmers to call multiple functions in a single transaction and use assets between different function in a composable manner, without those assets every leaving Beanstalk (thanks to Internal Balances).

The Farm consists of 5 Facets:

• FarmFacet -> Contains the farm function, which allows Farmers to call a series of functions together within Beanstalk.

• DepotFacet -> Wraps the standalone Pipeline contract, providing access to Pipeline from Beanstalk through the use of the farm function.

• TokenFacet -> Supports transferring assets between Internal and External Balances and between different accounts. Also supports Wrap/Unwrap logic for ETH.

• TokenSupportFacet -> Handles token permits.

• CurveFacet -> Provides an interface to exchange and add/remove liquidity on Curve directly through Beanstalk.

Diamond

The Diamond Module controls and manages the Beanstalk contract by providing functionality to upgrade and view supported functions in Beanstalk. It also controls which address owns the Beanstalk contract.

The Diamond Module consists of 4 Facets:

• DiamondCutFacet -> Provides functionality for the owner to add/remove/replace functions within the Beanstalk contract.

• DiamondLoupeFacet -> Allows anyone to see the available functions within Beanstalk.

• OwnershipFacet -> Manages which address owns Beanstalk.

• PauseFacet -> Allows the owner of Beanstalk to Pause/Unpause Beanstalk.

The Season Facet contains the gm function and handles all logic for Season changes.

Call Functions

Sunrise

function sunrise() external payable returns (uint256);

Advances Beanstalk to the next Season, sending reward Beans to the caller's Circulating balance.

GM

function gm(
    address account,
    LibTransfer.To mode
) public payable returns (uint256);

Advances Beanstalk to the next Season, sending reward Beans to a specified address and balance.

View Functions

Season

function season() public view returns (uint32);

Returns the current Season number.

Paused

function paused() public view returns (bool);

Returns whether Beanstalk is Paused. When Paused, sunrise cannot be called.

Time

function time() external view returns (Storage.Season memory);

Returns the Season struct.

Above Peg

function abovePeg() external view returns (bool);

Returns whether Beanstalk started this Season above or below peg.

Sunrise Block

function sunriseBlock() external view returns (uint32);

Returns the block during which the current Season started.

Season Time

function seasonTime() public view virtual returns (uint32);

Returns the expected Season number given the current block timestamp. The sunrise function can be called when seasonTime() > season().

Weather

function weather() public view returns (Storage.Weather memory);

Returns the Weather struct.

Rain

function rain() public view returns (Storage.Rain memory);

Returns the Rain struct.

Plenty Per Root

function plentyPerRoot(uint32 season) external view returns (uint256);

Returns the Season of Plenty (SOP) rewards per Root for the given Season.

Total deltaB

function totalDeltaB() external view returns (int256 deltaB);

Returns the cumulative deltaB across all pools on the Oracle Whitelist.

Pool deltaB

function poolDeltaB(address pool) external view returns (int256);

Returns the deltaB for a given pool.

Well Oracle Snapshot

function wellOracleSnapshot(address well) external view returns (bytes memory snapshot);

Returns the last Well oracle snapshot for a given Well.

Curve Oracle

function curveOracle() external view returns (Storage.CurveMetapoolOracle memory co);

Returns the last Curve oracle data snapshot for the BEAN:3CRV pool.

Events

Sunrise

event Sunrise(uint256 indexed season);

Emitted when the Season changes.

Incentivization

event Incentivization(address indexed account, uint256 beans);

Emitted when Beanstalk pays Beans to the sunrise caller.

Reward

event Reward(uint32 indexed season, uint256 toField, uint256 toSilo, uint256 toFertilizer);

Emitted during Sunrise when Beans are distributed to the Field, the Silo, and Fertilizer.

Soil

event Soil(uint32 indexed season, uint256 soil);

Emitted during Sunrise when Beanstalk adjusts the amount of available Soil.

Weather Change

event WeatherChange(uint256 indexed season, uint256 caseId, int8 change);

Emitted when the Weather (now Temperature) changes.

Season of Plenty

event SeasonOfPlenty(
    uint256 indexed season,
    uint256 amount,
    uint256 toField
);

Emitted when Beans are minted during the Season of Plenty.

The Convert Getters Facet contains view functions for Convert data.

Call Functions

None.

View Functions

Estimate the maximum number of tokens that can currently be Converted from tokenIn to tokenOut.

Estimate the amount of tokens received from Converting tokenIn to tokenOut given an amount of tokenIn.

Events

None.

Farmers can Deposit assets on the into the Silo in exchange for Stalk and Seeds. The number of Stalk and Seeds received is dependent on the BDV at the time of Deposit, the Stalk per BDV and the Seeds per BDV. Stalk entitles Farmers to a pro-rata portion of Bean seignorage distributed to the Silo and Seeds grown into 0.0001 Stalk each Season.

A Farmer can Withdraw at any time, but must forfeit all Stalk and Seeds associated with the Deposit. All Withdrawals are subject to an unlock period (currently set to the remainder of the current Season). Once a Withdraw is complete, it can be Claimed at any time.

Farmers can also convert a Deposited asset into a different one via the Convert function if the ability to convert between those two assets is on the . Each Convert type must be approved via governance and the Convert functionality must be added to LibConvert.

Adding and Removing Assets on the Deposit Whitelist

Assets can only be Deposited into the Silo if the assets are on the Deposit Whitelist. A token is considered on the Deposit Whitelist if it has a non-zero Silo Settings in Beanstalk’s storage. Silo Settings for each asset on the Deposit Whitelist are stored in the s.ss mapping in defined as:

• The key used in the mapping is the ERC-20 token address.

• selector is a function selector that calculates the BDV of a given amount of the token. selector should be an encoded external view function added to the Beanstalk diamond. BDV is represented with 6 decimal places.

• seeds is the number of Seeds per BDV that a Farmer receives for Depositing this asset. For example, seeds is 2 for Bean and 4 for BEAN:3CRV LP tokens.

• stalk is the number of Stalk per BDV that a Farmer receives for Depositing this asset. Because Stalk has 10 decimals compared to the 6 that BDV has, 10,000 equals 1. stalk is 10,000 for both Bean and BEAN:3CRV LP tokens.

Tokens can be added to the Deposit Whitelist via BIP. In order to Whitelist a token, an address, BDV function selector, Stalk per BDV and Seeds per BDV must be included in the proposal. The BDV function selector must either already be added to Beanstalk or be added as a part of the BIP.

Similarly, tokens can be Dewhitelisted (removed from the Deposit Whitelist) via BIP.

Bean Denominated Value

Stalk and Seeds

Stalk entitles the Farmer to a pro rata portion of at least 1/3 of Bean mints and 1 Stalk is 1 vote in Governance. Beans mints allocated to the Silo are called Earned Beans. Farmers also receive 1 Earned Stalk and 2 Earned Seeds for each Earned Bean.

Each Seed grows 0.0001 Stalk every Season. Stalk grown from Seeds is called Grown Stalk.

There are 3 types of Stalk:

• Stalk -> Stalk stored in a Farmer’s account storage. Stalk is acquired by Depositing, Converting, Updating or Planting.

• Earned Stalk -> A Farmer receives 1 Earned Stalk for each Earned Bean. Earned Stalk automatically compounds and receives a portion of Bean mints. Earned Stalk is claimed as part of the plant function, which turns it into Stalk. Because it is considered active, Earned Stalk has already been minted and it is included in the totalStalk and balanceOfStalk counts. To the Farmer, Earned Stalk is no different from Stalk and just serves as an indicator of how much Stalk has been earned through Bean seignorage since the last plant call.

• Grown Stalk -> 0.0001 Grown Stalk is grown from every Seed each Season. Grown Stalk is not considered active and thus does not receive a pro rata portion of Bean mints. It is claimed via the update function in Beanstalk, which turns it into Stalk. Because Grown Stalk is not active, Stalk isn’t minted until Grown Stalk is updated and thus Grown Stalk is not included in the totalStalk and balanceOfStalk counts.

There are 2 types of Seeds:

• Seeds → Seeds stored in a Farmer’s account storage. Seeds are acquired by Depositing, Planting and in certain cases, Converting.

• Earned Seeds → A Farmer receives 2 Earned Seeds for each Earned Bean. Earned Seeds are not active. Earned Seeds can be claimed via the plant function, which turns them into Seeds. Because Earned Seeds are not active, they are not included in the totalSeeds or balanceOfSeeds function.

Deposit

Farmers can deposit Whitelisted ERC-20 tokens in the Silo in exchange for Stalk and Seeds via the deposit function. deposit first calls the BDV function selector stored in Storage to calculate the BDV of the Deposit. It then distributes Stalk and Seeds to the Farmer based on the Stalk per BDV and Seeds per BDV.

A Deposit is stored in the current Season to record at what Season the Seeds associated with the Deposit started accruing Grown Stalk. The total Seeds and Stalk associated with a Deposit can be calculated as:

Deposits are stored in the Account storage as:

• The mapping is from token address to Season to Deposit.

• amount is the amount of tokens in the Deposit. A Farmer can Withdraw up to amount.

• bdv is the BDV of the amount of tokens at the time of Deposit.

Withdraw

Farmers can Withdraw any Deposit via the withdrawDeposit or withdrawDeposits functions. When a Farmer Withdraws, they specific the token, the Season(s) of the Deposit(s) and the corresponding amount(s) to Withdraw.

In order to Withdraw a Deposit, a Farmer must burn all of the Stalk and Seeds associated with the Deposit.

A Withdraw is locked for a certain number of Seasons. This number is stored in s.season.withdrawSeasons. This number is equal to the # of full Seasons required for Withdraw plus 1. The plus 1 accounts for the partial Season that Farmer Withdraws in.

The Season of a Withdrawal is equal to the Season at which the Withdrawal can be Claimed (Not the Season that the Withdrawal is initiated).

A Withdraw is in the following mapping:

• The mapping is from token address to Season to amount.

Claim Withdrawal

Farmers can Claim Withdrawals that have been unlocked via the claimWithdrawal and claimWithdrawals functions. A Withdrawal is Claimable if the current Season is greater than or equal to the Season of the Withdrawal. A Withdrawal is Claimed by specifying the token and Season(s) of the Withdrawals to Claim. When a Withdrawals is Claimed, the Withdrawal is deleted and the Farmer receives the corresponding amount of the underlying token.

Convert

Farmers can Convert one asset on the Deposit Whitelist (Token A) to another asset on the Deposit Whitelist (Token B) if Converting from Token A to Token B is on the Convert Whitelist. convert takes in a convertData payload that stores the encoded Convert data payload. Convert data is encoded so that different Convert types can have different parameters as necessary. However, each Convert type must specify at least the Convert type and the amount to Convert. Farmers must also specify the Season(s) of Deposits and corresponding amounts to Convert.

Convert does 3 main actions:

1. Converts some amount of Token A to Token B via LibConvert;

2. Removes Deposits of Token A equal to the amount of Token A that was Converted; and

3. Adds a Deposit of Token B equal to the amount received in Convert.

Convert uses the maximum of the BDV of Token A and Token B so that BDV is never lost. Thus, the Farmer won’t lose any Stalk during Convert, but may still gain Stalk depending the BDV of Token B. Seeds can be gained or lost depending on the Seeds per BDV of Token B versus Token A.

Grown Stalk is preserved during Convert and the Season that Converted assets are Deposited into is depending on the number of Grown Stalk:

Converts may have a maximize amount that can be converted from Token A to Token B. For instance, Deposited Beans can only be converted into Deposited BEAN:3CRV LP tokens if the price in the BEAN:3CRV pool is greater than $1 after the Convert. This can be retrieved via the getMaxAmountIn function.

The getAmountOut function returns the expected output amount of a given Convert.

New Converts can be approved via adding new Convert types to LibConvertData and adding the Convert case to LibConvert.

The Enroot Facet handles logic for Enrooting Unripe Deposits.

Call Functions

Claims outstanding Revitalized Stalk and Seeds and updates BDV of a single Unripe Deposit.

Claims outstanding Revitalized Stalk and Seeds and updates BDV of multiple Unripe Deposits.

View Functions

None.

Events

Emitted when account removes a single Deposit from the Silo. Occurs during Withdraw and Convert.

Emitted when account removes multiple Deposits from the Silo. Occurs during Withdraw and Convert.

The Sun advances Beanstalk to the next Season through the sunrise function in the Season Facet. Every time an hour passes, sunrise can be called 1 more time.

The Season Facet has :

• -> Calculates the time weighted average number of Beans that Bean is above/below its value peg in all pools on the .

• -> Changes the Max Temperature (interest rate) depending on the Bean price, debt level and demand for Soil.

• -> Sets the Soil for the next Season and mints new Beans if Oracle returns deltaB > 0 and distributes them as follows:

  • Up to 1/3 to Active Fertilizer holders (see );

  • Up to 1/2 of the remaining amount to Pod holders (see ); and

  • The rest to Stalkholders in the Silo (see ).

sunrise does the following steps:

1. Increments the Season number;

2. Calls Oracle to get deltaB;

3. Calls Weather to adjust the Max Temperature and checks for Rain and Season of Plenty;

4. Calls Sun to set the Soil and mint Beans if deltaB > 0; and

5. Pays msg.sender Beans for paying the transaction fee associated with calling the function.

Beanstalk is a permissionless fiat stablecoin protocol built on Arbitrum.

Beanstalk forms the monetary basis of an Arbitrum-native, rent-free economy facilitated by the seigniorage of its native fiat currency, a stablecoin called Bean.

Beanstalk's primary objective is to incentivize independent market participants to regularly cross the price of 1 Bean across its value peg of $1 in a sustainable fashion. The stability of the Bean price relative to its value peg is a function of the creditworthiness of Beanstalk—Beanstalk attracts lenders when the price of a Bean is below its value peg to remove Beans from the supply and increase their price.

When the Bean price is too high, Beanstalk mints new Beans and distributes them to various ecosystem participants in a deterministic fashion. This inflation is that the Beanstalk economy is based on.

Beanstalk implements several novel mechanisms including a first-in-first-out (FIFO) supplemented by , that increases the opportunity cost of withdrawing the longer an asset stays deposited in the DAO and that allows participants to perform peg maintenance while those assets are staked.

Beanstalk strives to create product market fit on both a technical and economic level. In order to service an entire ecosystem, Beanstalk needs to provide a cheap, composable and interoperable interface. However, as protocols become more sophisticated and blockspace more crowded, smart contract architecture complexity can quickly become overwhelming.

Beanstalk pioneers a path forward for devising more efficient and complex systems. Beanstalk is implemented in for intended use in the . Beanstalk leverages to minimize gas costs and complexity.

Beanstalk consists of 2 main contracts:

• Beanstalk - The protocol responsible for peg maintenance implemented as an multi-facet proxy.

• Bean – The stablecoin implemented as an token.

Contracts

Beanstalk is deployed at .

Bean is deployed at .

All relevant contract addresses can be found on the page of the .

The Silo Facet handles Depositing, Withdrawing, and transferring Deposits (whitelisted assets in the Silo).

Stems keep track of when the Deposit was created. When the Deposit was created determines how much Grown Stalk per BDV the Deposit has.

Call Functions

Deposits ERC20 token into internal Farmer balances.

Withdraws a single Deposit.

Withdraws multiple Deposits.

Transfers single Farmer's Deposit.

Transfers multiple Farmer Deposits.

Transfer a single Deposit, conforming to the ERC1155 standard.

Transfer a single Deposit, conforming to the ERC1155 standard.

Yield Distribution

Claim Grown Stalk for an account for a particular whitelisted asset.

Mow for multiple whitelisted assets for an account.

Claim Earned Beans and their associated Stalk and Plantable Seeds for msg.sender.

Claims rewards from a Flood (Season of Plenty) for msg.sender.

View Functions

Utilities

Get the last Season in which account updated their Silo.

Silo Totals

Returns the total supply of Stalk. Does NOT include Grown Stalk.

Returns the total supply of Roots.

Returns the total supply of Earned Beans.

Silo Account Balances

Returns the balance of Stalk for a particular Farmer. Does NOT include Grown Stalk; does include Earned Stalk.

Returns the balance of Roots for a particular Farmer.

Returns the balance of Grown Stalk for account. Grown Stalk is earned each Season from BDV and must be Mown to add it to a user's Stalk balance.

Returns the balance of Grown Stalk for a single deposit of token in stem for account.

Returns the balance of Earned Beans for a Farmer.

Return the account balance of Earned Stalk, the Stalk associated with Earned Beans.

Return the balance of Deposited BDV of a whitelisted asset for a given Farmer.

Return the Stem at the time that a Farmer last Mowed a particular whitelisted asset.

Return the Mow Status struct of token for a given account.

Season of Plenty (Flood)

Returns the last Season that a Season of Plenty started.

Returns the Farmer's balance of unclaimed 3CRV earned from the Season of Plenty.

Returns the account balance of Roots the last time it was Raining during a Silo update.

Returns the account Season of Plenty related state variables.

Stems

Returns the "stemTip", or cumulative Grown Stalk Per BDV of a given Deposited asset since whitelist, for a given whitelisted token.

Get the Stem associated with a particular Deposit (via its token and Season). Kept for legacy reasons.

Gets the Seeds per token for legacy whitelisted assets. Calling with an non-legacy token will return 0, even after the token is whitelisted. Kept for legacy reasons.

Returns if Earned Beans from the previous gm call are still vesting. Vesting Earned Beans cannot be received via plant until the Vesting Period is over, and will be forfeited if a Farmer Withdraws during the Vesting Period.

Getters

Find the amount and BDV of token that a Farmer has Deposited in a given Stem.

Get the total amount of token currently Deposited in the Silo across all Farmers.

Get the total BDV of token currently Deposited in the Silo across all Farmers.

Get the Storage.SiloSettings for a whitelisted token.

Returns the total BDV of a number of tokens on the Deposit Whitelist.

ERC-1155

Gets the amount of tokens in a Deposit type for a given Farmer.

Gets an array of amounts corresponding to Deposits.

Gets the Deposit ID given an whitelisted token address and Stem.

Events

Emitted when the deposit associated with the Earned Beans of account are Planted.

Emitted when 3CRV paid to account during a Flood is claimed.

Emitted when account gains or loses Stalk.

Emitted when account adds a single Deposit to the Silo. There is no AddDeposits event because there is currently no operation in which Beanstalk creates multiple Deposits in different Stems.

Emitted when account removes a single Deposit from the Silo. Occurs during Withdraw and Convert.

Emitted when account removes multiple Deposits from the Silo. Occurs during Withdraw and Convert.

ERC-1155 event. Emitted when a Deposit is created, removed, or transferred.

ERC-1155 event. Emitted when multiple deposits are withdrawn or transferred.

Legacy event. This event is kept for backwards compatibility in order for the ABI to generate properly.

Legacy event. This event is kept for backwards compatibility in order for the ABI to generate properly.

The Convert Facet handles Conversions between assets in the Silo and Enrooting Unripe Deposits.

Call Functions

Convert allows a user to Convert from one Deposited asset to another, given that the Conversion is on the Convert Whitelist. For example, a Farmer can Convert LP into Bean only when the Bean price is below peg, and vice versa. Read more about .

View Functions

None.

Events

Emitted upon each Conversion.

Emitted when account removes a single Deposit from the Silo. Occurs during Withdraw and Convert.

Emitted when account removes multiple Deposits from the Silo. Occurs during Withdraw and Convert.

The BDV Facet holds functions to get the BDV for each whitelisted Silo asset.

Call Functions

None.

View Functions

Returns the BDV of a number of BEAN:3CRV LP tokens.

Returns the BDV of a number of Beans (1 Bean = 1 BDV).

Returns the total BDV of a number of Unripe BEAN:3CRV LP tokens.

Returns the total BDV of a number of Unripe Beans.

Returns the total BDV of a number of Well LP tokens given a Well LP token.

Events

None.