# Generator ## 1. Overview The Generator contract distributes token rewards (ASTRO) based on locked LP token amounts for each eligible Astroport pool. The Generator also supports proxy staking via 3rd party contracts so that stakers can receive [dual rewards](https://miro.medium.com/max/1400/0*8hn2NSnZJZTa9YGV). The Generator contract code can be found [here](https://github.com/astroport-fi/astroport-core/blob/main/contracts/tokenomics/generator/src/contract.rs). ## 2. Variables & Functions ### Constants
NameDescription
CONFIGStores the contract configuration
POOL_INFOContains information about all generators
TMP_USER_ACTIONUsed to temporarily store data about a user action
USER_INFOStores information about all stakers in every generator
MAX_LIMITThe maximum amount of users that can be read at once from USER_INFO
DEFAULT_LIMITThe default amount of users to read from USER_INFO
OWNERSHIP_PROPOSALContains the proposal to change contract ownership
CONTRACT_NAMEContract name
CONTRACT_VERSIONContract version
### Structs | Name | Description | Contains | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `InstantiateMsg` | This struct holds parameters used to instantiate the Generator contract | | | `PoolLengthResponse` | This structure holds the response returned when querying the total length of the array that keeps track of instantiated generators | | | `PendingTokenResponse` | This structure holds the response returned when querying the amount of pending rewards that can be withdrawn from a 3rd party rewards contract | | | `RewardInfoResponse` | This structure holds the response returned when querying for the token addresses used to reward a specific generator | | | `PoolInfoResponse` | This structure holds the response returned when querying for a pool's information | | | `ConfigResponse` | This structure holds the response returned when querying the contract for general parameters | | | `StakerResponse` | This structure holdes the parameters used to return information about a staked in a specific generator | | | `UserInfo` | This structure provides information for an address staked in a specific generator | | | `PoolInfo` | This structure provides information for a pool | | | `Config` | This structure returns the main configuration for the Generator contract | | ### Functions | Function | Params | Description | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `instantiate` | `(deps: DepsMut`, `_env: Env`, `_info: MessageInfo`, `msg: InstantiateMsg)` `-> ` | Initializes the generator contract using provided parameters | | `execute` | `(deps: DepsMut`, `env: Env`, `info: MessageInfo`, `msg: ExecuteMsg)` `->` `Result` | Exposes execute functions available in the contract | | `execute_update_config` | `execute_update_config(deps: DepsMut`, `info: MessageInfo`, `vesting_contract: Option)` `->` `Result` | Sets a new Generator vesting contract address | | `add` | `add(mut deps: DepsMut`, `env: Env`, `lp_token: Addr`, `alloc_point: Uint64`, `has_asset_rewards: bool`, `reward_proxy: Option)` `->` `Result` | Creates a new generator and adds it to `POOL_INFO` (if it does not exist yet) and updates total allocation points (in `Config`) | | `set` | `set(mut deps: DepsMut`, `env: Env`, `lp_token: Addr`, `alloc_point: Uint64`, `has_asset_rewards: bool)` `->` `Result` | Updates the given generator's ASTRO allocation points | | `reply` | `reply(deps: DepsMut`, `env: Env`, `_msg: Reply)` `->` `Result` | The entry point to the contract for processing replies from submessages | | `mass_update_pools` | `mass_update_pools(mut deps: DepsMut`, `env: Env)` `->` `Result` | Updates the amount of accrued rewards for all generators | | `update_pool` | `update_pool(mut deps: DepsMut`, `env: Env`, `lp_token: Addr)` `->` `Result` | Updates the amount of accrued rewards for a specific generator | | `accumulate_rewards_per_share` | `accumulate_rewards_per_share(deps: DepsMut`, `env: &Env`, `lp_token: &Addr`, `pool: &mut PoolInfo`, `cfg: &Config`, `deposited: Option)` `->` `StdResult<()>` | Accrues the amount of rewards distributed for each staked LP token in a specific generator. Update reward variables for the given generator | | `receive_cw20` | `(deps: DepsMut`, `env: Env`, `info: MessageInfo`, `cw20_msg: Cw20ReceiveMsg)` `->` `Result` | Receives a message of type \[`Cw20ReceiveMsg`] and processes it depending on the received template | | `send_pending_rewards` | `send_pending_rewards(cfg: &Config`, `pool: &PoolInfo`, `user: &UserInfo`, `to: &Addr)` `->` `Result` | Distributes pending proxy rewards for a specific staker | | `deposit` | `deposit(mut deps: DepsMut`, `env: Env`, `lp_token: Addr`, `beneficiary: Addr`, `amount: Uint128)` `->` Result\ | Deposit LP tokens in a generator to receive token emissions | | `withdraw` | `withdraw(mut deps: DepsMut`, `env: Env`, `lp_token: Addr`, `account: Addr`, `amount: Uint128)` `->` `Result` | Withdraw LP tokens from a generator | | `emergency_withdraw` | `emergency_withdraw(deps: DepsMut`, `_env: Env`, `info: MessageInfo`, `lp_token: String)` `->` `Result` | Withdraw LP tokens without caring about rewards. **To be used in emergency cases only** | | `set_allowed_reward_proxies` | `set_allowed_reward_proxies(deps: DepsMut`, `info: MessageInfo`, `proxies: Vec)` `->` `Result` | Sets the allowed reward proxies that can interact with the Generator contract | | `send_orphan_proxy_rewards` | `send_orphan_proxy_rewards(deps: DepsMut`, `info: MessageInfo`, `recipient: String`, `lp_token: String)` `->` `Result` | Sends orphaned proxy rewards (which are left behind by emergency withdrawals) to another address. Can only be called by the `owner` | | `migrate` | `migrate(deps: DepsMut`, `_env: Env`, `_msg: MigrateMsg)` `->` `Result` | Used for contract migration | | `query` | `query(deps: Deps`, `env: Env`, `msg: QueryMsg)` `->` `Result` | Exposes all the queries available in the contract | | `pool_length` | `pool_length(deps: Deps)` `->` `Result` | Returns the amount of instantiated generators | | `query_deposit` | `query_deposit(deps: Deps`, `lp_token: String`, `user: String)` `->` `Result` | Returns the amount of LP tokens a user staked in a specific generator | | `pending_token` | `pending_token(deps: Deps`, `env: Env`, `lp_token: String`, `user: String)` `->` `Result` | Calculates and returns pending token rewards for a specific user | | `query_config` | `query_config(deps: Deps)` `->` `Result` | Returns information about a generator's configuration | | `query_reward_info` | `query_reward_info(deps: Deps`, `lp_token: String)` `->` `Result` | Returns reward information for a specific generator | | `query_orphan_proxy_rewards` | `query_orphan_proxy_rewards(deps: Deps`, `lp_token: String)` `->` `Result` | Returns the amount of orphaned proxy rewards for a specific generator | | `query_pool_info` | `query_pool_info(deps: Deps`, `env: Env`, `lp_token: String)` `->` `Result` | Returns a generator's configuration | | `query_simulate_future_reward` | `query_simulate_future_reward(deps: Deps`, `env: Env`, `lp_token: String`, `future_block: u64)` `->` `Result` | Returns the total amount of ASTRO tokens distributed for a specific generator up to a certain block in the future | | `query_list_of_stakers` | `query_list_of_stakers(deps: Deps`, `lp_token: String`, `start_after: Option`, `limit: Option)` `->` `Result`, `ContractError>` | Returns a list of stakers that currently have funds in a specific generator | | `calculate_rewards` | `calculate_rewards(env: &Env`, `pool: &PoolInfo`, `cfg: &Config)` `->` `StdResult` | Calculates and returns the amount of accrued rewards since the last reward checkpoint for a specific generator | ## 3. Reward Distribution The Generator reward distribution is controlled by several variables: | Variable | Description | | ------------------- | -------------------------------------------------------------------------------------------------- | | `tokens_per_block` | The total amount of ASTRO rewards that will be distributed every block among all active generators | | `alloc_point` | A distribution ratio set per individual generator | | `total_alloc_point` | The sum of **`alloc_point`** for each active generator | The formula for reward distribution (for every generator) is the following: `astro_to_distribute = blocks_since_last_reward * tokens_per_block * alloc_point / total_alloc_point` For example, if there are three active generators, and the **`alloc_point`** for each generator is **1000,** the **`total_alloc_point`** would equal **3000** (1000 \* 3). All three pools will get an equal amount of rewards. But what happens if we want to add another pool? Let's add one more pool and set its **`alloc_point`** to **3000**. *Note, that doing this will change the distribution for all existing pools, as it will affect the **`total_alloc_point`** variable.* After adding the new pool, the **`total_alloc_point`** would be **6000**. This new pool will now receive 50% of rewards (**3000** is 50% of **6000**) and the other 50% will be evenly distributed between the initial three pools (because each of their **alloc\_points** is **1000**). In order to maintain the same reward allocations for existing pools, it is required to update each of their **`alloc_point`**s. ## 4. Walkthrough {% hint style="info" %} The following are examples and descriptions of core functions that can be called by anyone to interact with the Generator contract. {% endhint %} ### **Execute Functions** **`deposit`** Stakes LP tokens in a specific generator (inside the Generator contract). In order to stake in the Generator contract, you should execute this message inside the contract of the LP token you want to stake. ``` { "send": { "contract": , "amount": 999, "msg": "base64-encodedStringOfWithdrawMsg" } } ``` Inside `send.msg`, you may encode this JSON string into base64 encoding: ``` { "Deposit": {} } ``` #### **`depositFor`** Stakes LP tokens in the Generator on behalf of another address. In order to stake in the Generator contract, you should execute this message inside the LP token you want to stake. ``` { "send": { "contract": , "amount": 999, "msg": "base64-encodedStringOfWithdrawMsg" } } ``` In `send.msg`, you may encode this JSON string into base64 encoding: ``` { "DepositFor": "terra..." } ``` **`withdraw`** Unstakes LP tokens from the Generator contract and claims outstanding token emissions. An address can also claim rewards without unstaking from a generator: call the withdraw function and specify **`amount`** as 0 (you don’t withdraw any LP tokens, only claim rewards). ``` "withdraw": { "lp_token": "terra...", "amount": "123" } } ``` #### **`emergency_withdraw`** Unstakes LP tokens without caring about rewards. To be used only in emergencies such as a critical bug found in the Generator contract. ``` { "emergency_withdraw": { "lp_token": "terra..." } } ``` **`auto_stake`** An address can provide liquidity and stake in the Generator in one transaction using the Swap Pairs contracts. Calling the `provide_liquidity` operation with `auto_stake` as`true` allows LP tokens to automatically be staked in the Generator contract (if the LP tokens currently get ASTRO or 3rd party emissions). If `auto_stake` is not specified, LP tokens will just be minted for the recipient. {% tabs %} {% tab title="ANC-UST" %} ``` { "provide_liquidity": { "assets": [ { "info": { "token": { "contract_addr": "terra14z56l0fp2lsf86zy3hty2z47ezkhnthtr9yq76" } }, "amount": "1000000" }, { "info": { "native_token": { "denom": "uusd" } }, "amount": "1000000" } ], "slippage_tolerance": "0.01", "auto_stake": true, "receiver": "terra..." } } ``` {% endtab %} {% tab title="bLUNA-LUNA" %} ``` { "provide_liquidity": { "assets": [ { "info": { "token": { "contract_addr": "terra1kc87mu460fwkqte29rquh4hc20m54fxwtsx7gp" } }, "amount": "1000000" }, { "info": { "native_token": { "denom": "uluna" } }, "amount": "1000000" } ], "slippage_tolerance": "0.01", "auto_stake": true, "receiver": "terra..." } } ``` {% endtab %} {% endtabs %} ### Query Functions #### `deposit` Returns the amount of a specific LP token that a user currently has staked in the Generator. {% tabs %} {% tab title="Query" %} ``` { "deposit": { "lp_token": "terra...", "user": "terra..." } } ``` {% endtab %} {% tab title="Ex. Response" %} ``` "123" ``` {% endtab %} {% endtabs %} #### `pending_token` Returns the amount of pending ASTRO and 3rd party token rewards that can be claimed by a user that staked a specific LP token. {% tabs %} {% tab title="Query" %} ``` { "pending_token": { "lp_token": "terra...", "user": "terra..." } } ``` {% endtab %} {% tab title="Ex. Response" %} ``` { "pending": "123", "pending_on_proxy": null } ``` {% endtab %} {% endtabs %} #### `reward_info` {% tabs %} {% tab title="Query" %} ``` { "reward_info": { "lp_token": "terra..." } } ``` {% endtab %} {% tab title="ANC-UST Ex. Response" %} ``` { "base_reward_token": "terra1xj49zyqrwpv5k928jwfpfy2ha668nwdgkwlrg3", "proxy_reward_token": "terra14z56l0fp2lsf86zy3hty2z47ezkhnthtr9yq76" } ``` {% endtab %} {% endtabs %} #### `orphan_proxy_rewards` {% tabs %} {% tab title="Query" %} ``` { "orphan_proxy_rewards": { "lp_token": "terra..." } } ``` {% endtab %} {% tab title="ANC-UST Ex. Response" %} ``` "0" ``` {% endtab %} {% endtabs %} #### `simulate_future_reward` Returns the amount of ASTRO that will be distributed up to a future block and for a specific LP token. {% tabs %} {% tab title="Query" %} ``` { "simulate_future_reward": { "lp_token": "terra...", "future_block": "999" } } ``` {% endtab %} {% tab title="Ex. Response" %} ``` "123" ``` {% endtab %} {% endtabs %} #### `list_of_stakers` Returns a list of stakers that currently have funds in a specific generator. {% tabs %} {% tab title="Query" %} ``` { "list_of_stakers": { "lp_token": "terra...", "start_after": "terra...", "limit": 5 } } ``` {% endtab %} {% endtabs %} ## 5. Risks 1. **`alloc_point`** miscalculation can lead to specific pools not getting the initially intended ASTRO emissions. 2. If **`owner`** is compromised, it can drain the Generator of all staked LP tokens. 3. Dual rewards proxy misconfiguration can block addresses from staking in specific generators. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://astroport.gitbook.io/astroport/smart-contracts/tokenomics/generator.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.