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 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 Diamond module contains various functions that require ownership of Beanstalk to execute in Beanstalk. This includes Pausing and Unpausing Beanstalk and upgrading Beanstalk via Diamond Cuts.

See EIP-2535 Diamond to read more about Beanstalk's upgradable proxy implementation.

The Diamond consists of 4 facets:

• Diamond Cut Facet

• Diamond Loupe Facet

• Ownership Facet

• Pause Facet

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

All the Facets share a common storage through the 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?

Implementation Tips for Diamonds (which Beanstalk uses)

Why use a Diamond?

More Information on Diamonds

The Diamond Cut Facet is used by the owner to upgrade Beanstalk.

Call Functions

Add, replace, and/or remove any number of functions and optionally execute a function with delegatecall. Can only be called by the owner of Beanstalk.

View Functions

None.

Events

None.

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 several subcontracts:

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

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

• Sun.sol -> 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 Barn);

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

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

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.

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

The Farm also provides composable Beanstalk-native interfaces for other DeFi protocols. This allows Farmers to call supported external protocols through the farm function and leverage Internal Balances. The current protocols that the Farm supports are:

• WETH -> wrapping and unwrapping; and

• Curve -> swapping and adding/removing liquidity.

• Pipeline -> performing an arbitrary series of actions in the EVM in a single transaction.

The Farm creates an interface to transfer ERC-20 tokens between Internal and External Balances, as well as between Farmers through the transferToken function.

The Farm consists of 5 facets:

• Farm Facet

• Depot Facet

• Token Facet

• Token Support Facet

• Curve Facet

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.

The Metadata Facet provides metadata for the ERC-1155 Silo Deposits. Deposit IDs are a uint256 that is the concatenation of the token address and the Stem.

Call Functions

None.

View Functions

URI

function uri(uint256 depositId) external view returns (string memory);

Returns the URI for a given Deposit ID.

Name

function name() external pure returns (string memory);

Returns the name of the collection for OpenSea compatibility.

Symbol

function symbol() external pure returns (string memory);

Returns the ticker of the collection for OpenSea compatibility.

Image URI

function imageURI(uint256 depositId) public view returns (string memory);

Returns the image URI for a given Deposit ID.

Events

URI

event URI(string _uri, uint256 indexed _id);

Not currently emitted.

The Field is Beanstalk's credit facility. Beanstalk relies on a decentralized set of creditors to maintain Bean price stability.

Anytime Beanstalk is willing to issue debt, there is Soil in the Field. Soil represents the number of Beans that Beanstalk is currently willing to borrow.

Anytime there is Soil in the Field, Farmers can Sow Beans in exchange for Pods. Pods are stored in Plots and placed at the end of the Pod Line.

Pods become Harvestable on a First In, First Out (FIFO) basis when deltaB > 0 over the course of a Season. Assuming there are Unharvestable Pods and Unfertilized Beans, 1/3 of Bean mints turn Pods into Harvestable Pods, which can be Harvested (redeemed) for Beans via the harvest() function. When a Plot is Harvested, it is deleted from storage.

Pods are implemented using 3 indices:

• podIndex -> The total number of Pods ever created.

• harvestableIndex -> The total number of Pods that ever became Harvestable.

• harvestedIndex -> The total number of Pods ever Harvested.

When Beans are Sown, a Plot is created at the current podIndex with beans * (1 + weather). Pods and podIndex are incremented by the number of Pods.

When Pods become Harvestable, harvestableIndex is incremented by the number of newly Harvestable Pods. Plots are Harvestable if the index of a Plot is less than harvestableIndex. Plots can be partially Harvested, in which case Beanstalk deletes the first part of the Plot and creates a new Plot at the harvestableIndex. When a Plot is Harvested, the harvestedIndex increases by the number of Harvested Pods.

Fundraiser

Fundraisers allow Beanstalk to raise non-Bean stablecoins to pay for services on behalf of the protocol, such as audits. Fundraisers can be created through the createFundraiser() function by Beanstalk or the owner of the contract.

Each Fundraiser requires:

1. The token address of the non-Bean token being raised;

2. The amount of tokens being raised; and

3. The address to send the tokens to upon completion of the Fundraiser.

Farmers fund() Fundraisers by transferring the non-Bean stablecoin to Beanstalk and in exchange receive Pods at the current Weather at the end of the Pod Line. Funding is akin to Sowing, but instead of burning Beans, Beanstalk is raising a non-Bean stable coin.

Once all of the Funds have been raised, the tokens are transferred to the payee address stored in the Fundraiser.

You can find links to past BIPs that created Fundraisers here.

What are Internal Balances?

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

To / From

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

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

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

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.

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.

For protocols that are building on top of Beanstalk and want to interact with Internal Balances, they can utilize the functions given in , rather than the library itself.

The Beanstalk codebase currently uses several terms that are out of date with the whitepaper, the Beanstalk UI, the Farmers' Almanac, etc. The following is a list of outdated terminology used in the Beanstalk codebase and the associated proper terms.

The following discrepancies are in the .

The Ownership Facet handles the ownership of Beanstalk.

Call Functions

Transfer Ownership

function transferOwnership(address _newOwner) external;

Transfers ownership of Beanstalk to a new address. Can only be called by the owner of Beanstalk.

Claim Ownership

function claimOwnership() external;

Callable by candidate for ownership after a successful transferOwnership function call.

View Functions

Owner

function owner() external view returns (address owner_);

Returns the address of the owner of Beanstalk.

Owner Candidate

function ownerCandidate() external view returns (address ownerCandidate_);

Returns the owner candidate of Beanstalk.

Events

Ownership Transferred

event OwnershipTransferred(
    address indexed previousOwner, 
    address indexed newOwner
);

Emitted when ownership of Beanstalk is transferred.

The Farm Facet allows Farmers to perform multiple Beanstalk functions calls in a single transaction using farm calls.

Call Functions

Farm

function farm(bytes[] calldata data)
    external
    payable
    withEth
    returns (bytes[] memory results);

Loops through the list of encoded selectors in data and performs a delegateCall on each of them.

Advanced Farm

function advancedFarm(AdvancedFarmCall[] calldata data)
    external
    payable
    withEth
    returns (bytes[] memory results);

Execute multiple AdvancedFarmCalls.

View Functions

None.

Events

None.

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

Call Functions

None.

View Functions

Curve to BDV

function curveToBDV(uint256 amount) public view returns (uint256);

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

Bean to BDV

function beanToBDV(uint256 amount) public pure returns (uint256);

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

Unripe LP to BDV

function unripeLPToBDV(uint256 amount) public view returns (uint256);

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

Unripe Bean to BDV

function unripeBeanToBDV(uint256 amount) public view returns (uint256);

Returns the total BDV of a number of Unripe Beans.

Well BDV

function wellBdv(address token, uint256 amount)
    external
    view
    returns (uint256);

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

Events

None.

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.

The Diamond Loupe Facet allows anyone to see the available functions within Beanstalk.

Call Functions

None.

View Functions

Facets

function facets() external view override returns (Facet[] memory facets_);

Returns facet info for all facets of Beanstalk

Facet Function Selectors

function facetFunctionSelectors(address _facet)
    external
    view
    override
    returns (bytes4[] memory facetFunctionSelectors_);

Returns all the function selectors provided by a facet.

Facet Addresses

function facetAddresses() 
    external 
    view 
    override 
    returns (address[] memory facetAddresses_);

Get all the facet addresses used by the Beanstalk Diamond.

Facet Address

function facetAddress(bytes4 _functionSelector)
    external
    view
    override
    returns (address facetAddress_);

Gets the facet that supports the given selector.

Supports Interface

function supportsInterface(bytes4 _interfaceId) 
    external 
    view 
    override 
    returns (bool);

Returns if a contract implements an interface. Implements ERC-165.

Events

None.

On April 17, 2022, Beanstalk was exploited via a governance attack. The attacker used a flash loan to exploit the protocol’s then on-chain governance mechanism and transferred all of the Deposited assets in the Silo to an address they controlled, resulting in a theft of ~$77M in non-Bean assets.

Upon exploit, Beanstalk was Paused and the on-chain governance mechanism was removed. Stalkholders voted via Snapshot on how Beanstalk should proceed.

The Barn is the Beanstalk recapitalization facility used to Replant Beanstalk. The Barn Raise started on June 6, 2022 while the protocol was offline and continues until the recapitalization target has been reached.

The Barn is consists of 2 Facets:

• Fertilizer Facet

• Unripe Facet

Fertilizer

Fertilizer is a semi-fungible limited debt issuance to recapitalize $77M in stolen liquidity.

At the beginning of the Barn Raise, there was 77M Available Fertilizer. Available Fertilizer is the number of Fertilizer that can be bought from Beanstalk in exchange for 1 USDC each. Fertilizer becomes Active when it is bought, at which point the ERC-1155 Fertilizer token is minted.

Active Fertilizer entitles holders to a pro rata portion of 1/3 of Bean mints.

Fertilizer is minted with a given % Humidity. Humidity is dependent on the Season during which the Fertilizer is minted. During Season 6074 (the Season Beanstalk was Paused at), the Humidity was 500%. The next Season, Humidity was set to 250% and decreased 0.5% every Season until it reached 20%. The Humidity will remain at 20% until all Fertilizer is sold.

Each Fertilizer entitles its holder up to 1 + humidity Unfertilized Beans. Unfertilized Beans become Fertilized Beans when Beans are distributed to Active Fertilizer holders. When Fertilizer has no more corresponding Unfertilized Beans, it becomes Used and no longer receives Bean mints.

To track Active Fertilizer, Beanstalk has a global variable s.bpf, which is the cumulative Beans Per Fertilizer (BPF) paid back over all Seasons. Fertilizer is indexed by endBpf = s.bpf + 1 + humidity at the time of minting. This indicates that once s.bpf reaches endBpf, the Fertilizer becomes Used. Beanstalk sorts all non-zero Fertilizer ids by endBpf in s.nextFid. This is a linked list where s.fFirst is the start of the list and s.fLast is the end of the list.

Every Season, Beanstalk increments s.bpf by the number of new Bean mints distributed to Fertilizer holders divided by s.activeFertilizer. Note that Beanstalk integrates s.bpf over s.activeFertilizer—every time s.bpf reaches s.fFirst, s.activeFertilizer decreases by the supply of Fertilizer with an id of s.fFirst. The first item is then popped off the linked list and s.fFirst is set to the next item. When s.fFirst == 0, Beanstalk stops paying Beans to Fertilizer as all Fertilizer is either Used or Available (and thus s.activeFertilizer == 0).

Fertilizer can be claimed via the claimFertilizer function (it is also claimed automatically whenever Fertilizer is transferred). The Fertilizer contract stores the lastBpf value for each token id that the Farmer owns. When a Farmer claims Fertilizer, Beanstalk computes how many Beans have been Fertilized since the last time the Farmer Fertilized that id with: min(s.bpf, s.nextFid[id]) – lastBpf. It then gives the Farmer that many Beans for each Fertilizer they have of that id.

Pre-Replant Fertilizer

Before Beanstalk was Replanted, Fertilizer was deployed as FertilizerPreMint.sol, which transferred USDC from the caller to the Beanstalk Community Multisig (BCM) address in exchange for Fertilizer. The Fertilizer was issued at the id 6_000_000 as the Humidity was 500% before Replant.

When Beanstalk was Replanted, the BCM called the addFertilizerOwner function that handled the process of adding liquidity to the BEAN:3CRV pool and minting new Beans for all of the Fertilizer minted prior to Replant.

At the same time, the Fertilizer contract was upgraded to Fertilizer.sol. This moved the mintFertilizer() functionality from the Fertilizer contract to Beanstalk itself. From this point forward, Beanstalk automatically adds new liquidity for Unripe LP holders and new Beans for Unripe Bean holders in the same transaction that Fertilizer is minted in.

Unripe Assets

Upon Replant, Farmers who held Beans in the block prior to the exploit received 1 Unripe Bean for every pre-exploit Bean; Farmers who held whitelisted LP Tokens in the block prior to the exploit received 1 Unripe BEAN:3CRV LP for every 1 BDV of each pre-exploit whitelisted LP Token.

As Fertilizer is sold, Beans are distributed to all Unripe Bean holders pro rata (and BEAN:3CRV LP is distributed to all Unripe LP holders) using the shares and underlying token model that EIP-4626 uses for yield-bearing tokens. The Unripe tokens are the Shares and Beans/LP are the underlying assets. The underlying portion will continue to increase as Fertilizer is minted in exchange for USDC.

Farmers can Chop their Unripe assets at any point for a penalized percent of the corresponding underlying tokens. The penalized percent is equal to the percent of Unfertilized Beans that have been Fertilized. This can be computed as s.fertilizedIndex / s.unfertilizedIndex.

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

• (1 Facet)

• (10 Facets)

• (2 Facets)

• (2 Facets)

• (1 Facet)

• (5 Facets)

• (4 Facets)

Sun

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

The Sun consists of 1 Facet:

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

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

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

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

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

• -> Contains view functions for Convert data.

• -> Where Farmers Enroot their Unripe Deposits.

• -> Contains logic for Deposit approvals and permits.

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

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

• -> Facilitates backwards compatibility for Farmers with unclaimed Withdrawals before the .

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:

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

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

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

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

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

The Farm consists of 5 Facets:

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

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

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

• -> Handles token permits.

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

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

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

• -> Manages which address owns Beanstalk.

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

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 Migration Facet contains functions related to . Farmers are required to migrate to the new accounting system created by the Silo V3 upgrade.

Call Functions

Migrates a Farmer's Deposits from the old (Seasons based) to the new Silo (Stems based) accounting system.

When migrating an account, a user must submit all of the account's Deposits or the migration will not pass because the Seed check will fail. The Seed check adds up the BDV of all submitted Deposits, multiplies by the corresponding Seed amount for each token type, then compares that to the total Seeds stored for that user. If everything matches, the migration is valid.

Migrate an account to Silo V3 that has no Deposits.

View Functions

Gets balance of Seeds for a Farmer that hasn't migrated.

Gets a Farmer's balance of Grown Stalk at the time of Stems deployment (Silo V3 upgrade).

Locate the token amount and BDV for a Farmer's Deposit in legacy storage.

Events

None.

The Depot Facet wraps Pipeline's pipe functions to facilitate the loading of non-Ether assets in .

Call Functions

Pipe a PipeCall through Pipeline.

Pipe multiple PipeCalls through Pipeline. Does not support sending Ether in the call.

Pipe multiple AdvancedPipeCalls through Pipeline.

Pipe a PipeCall through Pipeline with an Ether value.

View Functions

Return the return value of a PipeCall without executing it.

Events

None.

Who calls the gm function?

In theory, anyone is able to call the gm function. In practice, MEV bots will front run your transaction by calling the function themselves as they can determine that they will get the Beans instead of you. As there are a number of bots playing the Sunrise game, the chances of getting a successful gm call from clicking the Sunrise button on the UI are essentially zero.

Where can I call functions directly on Beanstalk?

Louper allows users to directly call functions in a contract that implements EIP-2535, as Etherscan does not yet support this. The Beanstalk contract on Louper can be found here.

Why do Beans only have 6 decimals?

Solidity has a limit of 2^256 - 1 ~= 1e77 for integers. Beanstalk is a complex protocol that does a lot of multiplication of big numbers which could potentially bring that upper integer limit into play, especially in the Flood functionality. Given that Bean is a stablecoin and the the value peg is $1, there is no need for an excessive amount of decimals. By reducing decimals to increase protocol security in the long run, Beanstalk is better set up for success. Note that USDC and Tether both have 6 decimals.

A lot of tokens have 18 decimals. Non-stable tokens have to be functional at any possible price at any point in the future.

Let's take the example of ETH and say that the ETH price is $4300. $0.01 is about 0.0000023 ETH. Thus, for ETH to be tradable at the cent level, it needs to have at least 7 decimals. Now fast forward 100 years and let's say (hypothetically) that ETH is worth $1,000,000,000. This would require ETH to have 11 decimals to be transacted at a cent level. Thus, it makes sense for ETH to have 18 decimals.

In terms of gas cost, there is no difference between 6 and 18 decimals.

How are proxy contracts used to upgrade Beanstalk?

Delegate calls in Solidity allow a smart contract to use functionality stored in another contract’s bytecode and apply it to its own memory.

Traditionally, an upgradeable contract is a proxy address with an implementation contract. All calls to the proxy use the logic stored in the implementation contract, but update the state of the proxy. Thus, by changing a proxy’s implementation address, one can change the functionality in a contract while maintaining the same state and address. You can read about it more on the OpenZeppelin docs here and here. Beanstalk is actually a multi-facet proxy implementation called a Diamond. This implementation is defined by EIP-2535. EIP-2535 allows a single proxy to implement multiple smart contracts at the same time. You can read more about the reasoning behind EIP-2535 usage with Beanstalk here.

What are Roots?

Roots were implemented in BIP-0. Roots are an underlying accounting variable for Stalk in order to track how many Earned Beans a Farmer has earned. When a Farmer Deposits assets or Mows Grown Stalk, they are given Roots proportional to the Stalk they receive: newStalk * totalRoots / totalStalk.

When Beanstalk mints Beans, it increases totalStalk but not totalRoots, which in effect, increases stalk / root. When a Farmer Mows their Grown Stalk, the ratio: farmerStalk / farmerRoots = totalStalk / totalRoots is restored. (In this formula farmerStalk is equal to the Stalk they have after Mowing.)

earnedStalk = farmerStalk - totalStalk / totalRoots * farmerRoots (In this formula farmerStalk is equal to the Stalk they have before the Mow.) 1 Stalk = 1 Bean, so earnedBeans = earnedStalk.

Why build a zero fee AMM?

From an engineering perspective, building a zero fee AMM is simpler than building an AMM with fees—you can simply skip the code that implements the fee when a swap occurs.

From an economic perspective, the concept is that Silo yield is a sufficient enough incentive to attract and retain liquidity providers such that there is no need to charge a fee on swaps.

Why is having zero fees important? Given that whether deltaB < 0 or deltaB > 0 is a defining data point in how Beanstalk's peg maintenance operates, any fee on swaps creates a serious inefficiency in Farmers' ability to arbitrage the peg. The BEAN:3CRV pool charges a 0.04% on swaps (including Convert). This means that buying or Converting above the price of $0.9996 means you are paying more than $1 per Bean and selling or Converting below $1.0004 means you are getting less than $1 per Bean. Any Farmer who is constantly arbitraging the price within this range is losing money overtime instead of making a profit (which they should be). For reference, the BEAN:ETH pool previously had a 0.3% fee, which created an even more extreme inefficiency in peg maintenance.

In addition, Beanstalk can overtime become the primary liquidity provider for all of DeFi by providing the cheapest on-chain swaps between two non-Bean assets.

Why aren't Pods / Plots implemented with an ERC standard?

Plots function completely differently than both ERC-721 and ERC-1155. ERC-1155 doesn't work for Plots/Pods as Pods require ordinality for FIFO Harvesting. ERC-721 could work for Pods, but its hard to see how this would add value. ERC-721 tokens are non-divisible, so it would only allow entire Plots to be bought and sold on NFT marketplaces, which is far less efficient that the current Pod Market. Implementing Pods as ERC-721 would increase the cost of Sowing, Harvesting, Transferring, buying and selling.

Why doesn't Fertilizer.sol have an initialize function?

When Fertilizer was originally deployed. It was deployed as the FertilizerPreMint.sol contract, which has an initialize function that calls __Internallize_init here. The initialize function was run on deployment. When Beanstalk was Replanted, The Fertilizer proxy contract was upgraded to the Fertilizer contract found here. This is the current implementation contract you see on Etherscan. There was no additional initialization needed as __Internallize_init was already executed. Thus, the Fertilizer contract has no need to have an external initialize function.

Why is the BDV of urBEAN3CRV lower than the BDV of urBEAN?

On October 25, 2022, two values could be found on the Beanstalk Data Dashboard:

• Underlying per urBEAN3CRV: 0.219823021543684162

• Underlying per urBEAN: 0.222227

• Dividing the two numbers: 0.219823021543684162/0.222227 = 0.9891823

This implies that 1 urBEAN3CRV will only ripen into 0.9891823 BEAN3CRV (i.e., not 1 BEAN3CRV) when Beanstalk is full recapitalized, assuming there are no Chops, no fees, deltaB = 0 and 1 BEAN3CRV = 1 BEAN. 1 urBEAN will ripen into 1 BEAN.

There are numerous reasons for this discrepancy, but the most significant is that deltaB > 0 when the exploit occurred, so the BDV of LP tokens at the time was less than 1.

Why are Beans minted for a Fundraiser just to later burn them?

See FundraiserFacet.sol.

Fundraisers are meant to mimic an OTC swap where the buyer trades some stablecoin for a Bean and then automatically Sows the bought Beans for Pods, similar to how the credit mechanism to sustain the peg works. As defined in the whitepaper, Sowing requires a Bean to be burned in exchanged for the Pods. At the start of the Fundraiser, Beans are minted. These Beans represent (1) expected "sell pressure" for Beans as they can be sold at anytime for 1 stablecoin (normally USDC) and (2) expected Pod issuance given that the Beans will be Sown into Pods.

Algorithm Explanations

remainingRecapitalization

totalDollars is the total dollar value required to be raised in the Barn Raise. It is equal to dollarPerUnripeLP() * unripeLP().totalSupply(). If no Farmer has forfeited Unripe LP, then totalDollars is 77 million, but given that Farmer's can chop their Unripe LP and forfeit the funds they have not yet been paid back, we need totalDollars to decrease with the total supply of Unripe LP.

if (s.recapitalized >= totalDollars) return 0; —

A safe guard in case Beanstalk ends up in a situation where too much is raised. This is also possible if someone uses the chop function at a penalty even after the full amount has been raised.

return totalDollars.sub(s.recapitalized); —

s.recapitalized is incremented every time USDC is exchanged for Fertilizer (or Unripe LP is generated through Convert), but it is equal to the dollar value that has been recapitalized. Thus, the difference between the two is the amount remaining.

checkForMaxDeltaB

See EBIP-2.

It is assumed that if |deltaB| > beanSupply / 100, then manipulation occurred. This isn't always true, but the ramifications if |deltaB| > beanSupply / 100 naturally are minimal as Beanstalk will simply mint fewer Beans/less Soil this Season.

Theoretically, a multi-block MEV attack could manipulate deltaB to be any value. Multi-block MEV can only be executed on some time cadence dependent on % ownership of Ethereal stake. Therefore, the greatest vulnerability to Beanstalk is a massive one-time Bean/Soil issuance. By adding this supply cap, the maximum effect of potential manipulation can be at most 1% of supply.

Whitelist Facet handles the whitelisting/dewhitelisting of assets on the Deposit Whitelist.

Call Functions

Dewhitelist Token

function dewhitelistToken(address token) external payable;

Dewhitelists tokens on the Deposit Whitelist. A token can no longer be Deposited in the Silo after dewhitelisting. Can only be called by the owner of Beanstalk.

Whitelist Token

function whitelistToken(
    address token,
    bytes4 selector,
    uint32 stalkIssuedPerBdv,
    uint32 stalkEarnedPerSeason
) external payable;

Adds a token to the Deposit Whitelist. Can only be called by the owner of Beanstalk.

Whitelist Token with Encode Type

function whitelistTokenWithEncodeType(
    address token,
    bytes4 selector,
    uint32 stalkIssuedPerBdv,
    uint32 stalkEarnedPerSeason,
    bytes1 encodeType
) external payable;

Adds a token to the Deposit Whitelist with an encodeType. Can only be called by the owner of Beanstalk.

Update Stalk per BDV per Season for Token

function updateStalkPerBdvPerSeasonForToken(
    address token,
    uint32 stalkEarnedPerSeason
) external payable;

Changes the Grown Stalk per BDV per Season for a token on the Deposit Whitelist. Can only be called by the owner of Beanstalk.

View Functions

None.

Events

Whitelist Token

event WhitelistToken(
    address indexed token,
    bytes4 selector,
    uint32 stalkEarnedPerSeason,
    uint256 stalkIssuedPerBdv
);

Emitted when a token is added to the Deposit Whitelist.

Update Stalk per BDV per Season

event UpdatedStalkPerBdvPerSeason(
    address indexed token,
    uint32 stalkEarnedPerSeason,
    uint32 season
);

Emitted when the Grown Stalk per BDV per Season for a token on the Deposit Whitelist is changed.

Dewhitelist Token

event DewhitelistToken(address indexed token);

Emitted when a token is removed from the Deposit Whitelist.

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.

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

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

The AppStorage struct can be found in the 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 Pause Facet handles the Pausing and Unpausing of Beanstalk.

Call Functions

Pause

function pause() external payable;

Pause Beanstalk, which makes it such that the gm function cannot be successfully called. Only callable by the owner of Beanstalk.

Unpause

function unpause() external payable;

Unpause Beanstalk, which allows the gm function to be successfully called at the top of the 2nd hour. The TWAP oracle and Season timer are reset as well.

View Functions

None.

Events

Pause

event Pause(uint256 timestamp);

Emitted when Beanstalk is Paused.

Unpause

event Unpause(uint256 timestamp, uint256 timePassed);

Emitted when Beanstalk is Unpaused.

The Fundraiser Facet dandles the creation, funding, and completion of Fundraisers.

Call Functions

Fund

function fund(
    uint32 id,
    uint256 amount,
    LibTransfer.From mode
) external payable nonReentrant returns (uint256);

Fund a Fundraiser in exchange for Pods.

Create Fundraiser

function createFundraiser(
    address payee,
    address token,
    uint256 amount
) external payable;

Creates a Fundraiser. Can only be called by the owner of Beanstalk.

View Functions

Remaining Funding

function remainingFunding(uint32 id) public view returns (uint256);

Returns the remaining number of tokens to raise.

Total Funding

function totalFunding(uint32 id) public view returns (uint256);

Returns the total amount of tokens raised so far.

Funding Token

function fundingToken(uint32 id) public view returns (address);

Returns the address of the token that can be sent to the Fundraiser.

Fundraiser

function fundraiser(uint32 id)
    public
    view
    returns (Storage.Fundraiser memory);

Returns the Fundraiser struct.

Number Of Fundraisers

function numberOfFundraisers() public view returns (uint32);

Returns the number of Fundraisers.

Events

Create Fundraiser

event CreateFundraiser(
    uint32 indexed id,
    address fundraiser,
    address token,
    uint256 amount
);

Emitted when a Fundraiser is created.

Fund Fundraiser

event FundFundraiser(
    address indexed account,
    uint32 indexed id,
    uint256 amount
);

Emitted when a Farmer calls fund.

Complete Fundraiser

event CompleteFundraiser(uint32 indexed id);

Emitted when a Fundraiser is fully funded.

The Market will house various DEXs for zero fee trading. For now, there is only the Pod Market, but in the future there may be a zero fee AMM, a zero fee NFT marketplace, etc.

The Pod Market allows Farmers to create, Fill and Cancel Pod Listings and Pod Orders.

Pod Listings

Farmers with Pods can create Pod Listings, which allow other Farmers to buy part or all of their Plots at a given price.

Pod Listings are contained in the following struct:

struct PodListing {
    address account;
    uint256 index;
    uint256 start;
    uint256 amount;
    uint24 pricePerPod;
    uint256 maxHarvestableIndex;
    LibTransfer.To mode;
}

Pod Listings are created with the createPodListing function. Pod Listings can only be created by the owner of the Plot being listed.

When a Pod Listing is created, The PodListing struct with the exception of account and index is encoded and hashed. Beanstalk stores the hash of the listing on-chain in the s.podListings state mapping. Pod Listing hashes are stored by index of the corresponding Plot. The Pod Listing struct is emitted in an event upon creation.

Pod Listings are Filled with the fillPodListing function. The Pod buyer is required to input the PodListing struct associated with the Plot being transferred. Beanstalk hashes the PodListing data and verifies that the hash is the same as the hash in storage at the corresponding index. If the original Plot owner no longer owns the Plot, then the transaction will fail. If the Fill is successful, Beanstalk then transfers the corresponding part of the Plot to the buyer in exchange for Beans. If the Listing is not empty, the updated Listing is then hashed and stored on-chain.

Pod Listings can be Cancelled at any time with the cancelPodListing function. Pod Listings are automatically Cancelled on Harvest, Transfer or if a new Pod Listing is created with the same plot.

Pod Orders

Pod Orders allow Farmer with Beans to create Orders to buy Plots. An Order specifies a max Place in Line that the Farmer is will to buy Pods at, the price they are willing to by Pods at and the amount they are willing to buy. All Orders are denominated in Beans. Pod Orders are contained in the following struct:

struct PodOrder {
    address account;
    uint24 pricePerPod;
    uint256 maxPlaceInLine;
}

Pod Orders are created with the createPodOrder function. Pod Orders can be created by any Farmer.

When a Pod Order is created, The PodOrder struct is encoded and hashed. Beanstalk stores the hash of the Order on-chain in the s.podOrders state mapping. The hash is the key in the mapping and the amount in the Order is stored in the hash. When a Pod Order is created, Beans are transferred from the Farmer to Beanstalk equal to the amount of Pods being bought times the Price per Pod in the Order. These Beans are locked in Beanstalk until either the Pod Order creator Cancels the Order or the Order is Filled.

Farmers with Pods can sell Pods to open Pod Orders with the fillPodOrder function. The Pod seller is required to input what part of which Plot is being sold and the PodOrder struct associated with Order they are filling. Beanstalk hashes the PodOrder data and verifies that the hash maps to a non-zero value in s.podOrders. The seller is also required to input the Plot being sold as a part of the calldata. If the Fill is successful, the value at the hash key is updated to equal the new amount remaining in the Pod Order.

Pod Orders can be Cancelled at anytime with the cancelPodOrder function. When an Order is Cancelled, Beanstalk returns the remaining Beans in the Pod Order to the Farmer.

The Field Facet is where Beans are Sown.

Call Functions

Sow

function sow(
    uint256 beans,
    uint256 minTemperature,
    LibTransfer.From mode
)
    external
    payable
    returns (uint256 pods);

Sow Beans in exchange for Pods.

Sow With Min

function sowWithMin(
    uint256 beans,
    uint256 minTemperature,
    uint256 minSoil,
    LibTransfer.From mode
) public payable returns (uint256 pods);

Sow Beans in exchange for Pods. Use at least minSoil.

Harvest

function harvest(uint256[] calldata plots, LibTransfer.To mode)
    external
    payable;

Harvest Pods from the Field.

View Functions

Pod Index

function podIndex() public view returns (uint256);

Returns the total number of Pods ever minted.

Harvestable Index

function harvestableIndex() public view returns (uint256);

Returns the index below which Pods are Harvestable.

Total Pods

function totalPods() public view returns (uint256);

Returns the number of outstanding Pods. Includes Pods that are currently Harvestable but have not yet been Harvested.

Total Harvested

function totalHarvested() public view returns (uint256);

Returns the number of Pods that have ever been Harvested.

Total Harvestable

function totalHarvestable() public view returns (uint256);

Returns the number of Pods that are currently Harvestable but have not yet been Harvested.

Total Unharvestable

function totalUnharvestable() public view returns (uint256);

Returns the number of Pods that are not yet Harvestable.

Plot

function plot(address account, uint256 index)
    public
    view
    returns (uint256);

Returns the number of Pods remaining in a Plot.

Total Soil

function totalSoil() external view returns (uint256);

Returns the total available Soil.

Yield

function yield() external view returns (uint32);

Returns the current yield (aka "Temperature") offered by Beanstalk when burning Beans in exchange for Pods.

Temperature

function temperature() external view returns (uint256);

Returns the current Temperature, the interest rate offered by Beanstalk in exchange for Sowing Beans.

Max Temperature

function maxTemperature() external view returns (uint256);

Returns the Maximum Temperature that Beanstalk is willing to offer this Season.

Remaining Pods

function remainingPods() external view returns (uint256);

Returns the remaining Pods that could be issued this Season.

Events

Sow

event Sow(
    address indexed account,
    uint256 index,
    uint256 beans,
    uint256 pods
);

Emitted from LibDibbler.sowNoSoil when an account creates a Plot. A Plot is a set of Pods created in from a single sow or fund call.

Harvest

event Harvest(address indexed account, uint256[] plots, uint256 beans);

Emitted when account claims the Beans associated with Harvestable Pods.

Pod Listing Cancelled

event PodListingCancelled(address indexed account, uint256 index);

Emitted when a Pod Listing is Cancelled.

The Legacy Claim Withdrawal Facet allows anyone to Claim and read Withdrawals. Silo V3 removed the Withdrawal Freeze from the Silo. Withdrawing now directly sends ERC-20 tokens to the Farmer's Farm or Circulating balances instead of creating a Withdrawal.

Although new Withdrawals cannot be created, the claim Withdrawal functionality has been preserved in this facet to allow pre-existing unclaimed Withdrawals to still be claimed.

Call Functions

Claim Withdrawal

function claimWithdrawal(
    address token,
    uint32 season,
    LibTransfer.To mode
) external payable nonReentrant;

Claims tokens from a Withdrawal.

Claim Withdrawals

function claimWithdrawals(
    address token,
    uint32[] calldata seasons,
    LibTransfer.To mode
) external payable nonReentrant;

Claims tokens from multiple Withdrawals.

View Functions

Get Withdrawal

function getWithdrawal(
    address account,
    address token,
    uint32 season
) external view returns (uint256);

Get the amount of token in the Withdrawal season for account.

Get Total Withdrawn

function getTotalWithdrawn(address token) external view returns (uint256);

Get the total amount of token currently Withdrawn from the Silo across all Farmers.

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

All Deposited assets are valued based on the Bean Denominated Value (BDV) at the time Deposit. Each asset on the Deposit Whitelist has a unique BDV function in the to calculate the BDV of a given amount of the asset.

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 Token Support Facet handles permits for ERC-20 and ERC-721 tokens and transfers for ERC-721 and ERC-1155 tokens.

Call Functions

Permit ERC-20

function permitERC20(
    IERC20Permit token,
    address owner,
    address spender,
    uint256 value,
    uint256 deadline,
    uint8 v,
    bytes32 r,
    bytes32 s
) public payable;

permitERC20 is a wrapper function for permit of ERC20Permit token.