# **05. Liquid Tokens**
###### tags: `Done`, `Functions`, `Smart Contracts`

**Purpose:**
* Understand how Liquid tokens are used on 3.Finance to facilitate the growth of compound token positions.
* Define smart contract requirements for Liquid tokens (in general and when specific liquid tokens are targeted for other uses).

Content:

> Definitions
> References
> Journeys:
>> Liquid **Deposit** Pools
>> Liquid **Emissions**
>> **Targeted** Liquid Emissions
>> Migrating balances

## Definitions

* An **asset-stack** is a standalone product within 3.Finance. Each asset-stack should be clearly differentiated within the construction of 3.Finance. (Only 1 asset-stack will exist for MVP, that shall be the '**Curve Asset-Stack**')
* The **Curve asset-stack** is made of 3 '**Compound tokens**'. These are: CRV, CVX and BENT. (Plus any derivatives mentioned in the Journeys below)
* **Compound tokens** are tokens that are favoured by 3.Finance. These favoured tokens make the foundation for 3.Finance tokens and NFTs. These tokens will be auto-compounded.
* **Liquid tokens** are tokens that are not favoured by 3.Finance. These unfavroued tokens are used to boost the deposit balance of those Compound tokens.
* **Compound Deposit Pools** or **CDPs** are pools where compound tokens are deposited and auto-compounded.
* **Liquid Deposit Pools** or **LDPs** are pools where liquid tokens are deposited.
* **Rewards** are tokens received by other protocols that are not yet in the 3.Finance ecosystem.
* **Emissions** are tokens received as rewards for depositing liquidity. Emissions are received by external protocols and are within the 3.Finance ecosystem.
* **Compound Emissions** are tokens received as rewards and are of the format of '**Compound tokens**'.
* **Liquid Emissions** are tokens received as rewards and are of the format of '**Liquid tokens**'.
* **Flagged tokens** are tokens that, when deposited, have impositions applied that prevent or delay withdrawals of the underlying asset. Each of the curve asset-stack tokens also happen to be flagged tokens.
* The **Streaming** contract referrs to the smart contract that receives rewards from external protocols and streams them to wallets with associated deposits within the 3.Finance eco syste, as Emissions on a pro-rata basis over a 7 calander day period.
* A **Signal** is when a user, during the harvest process; selects a specific direction they wish emissions to be harvested.
* The **Signals** contract referrs to the smart contract that registers how each connected wallet has directed their emissions during their **last** harvest. This **Signal** is then used by other functions when harvesting on behalf of other registered wallets.
* A **Registered Wallet** is a wallet that has once connected to and transacted on or via the 3.Finance protocol and is therefore, for all intents and purposes: registered with the protocol.

## References

*(References will be added here when they are ready and deemed necessary)

## Journeys

### Liquid Deposit Pools

#### (Liquid) Depositing / 1 token / Flagged
This process is not applicable as no liquid tokens are flagged.

#### (Liquid) Depositing / 1 token / Unflagged
(**Note**: all Liquid deposits are unflagged)

1. As a user, I wish to deposit liquidity into a **Liquid Deposit Pool** on 3.Finance to use resulting emissions to boost my Compound positions.
2. I select a Liquid Deposit pool I am interested in and/or wish to deposit into; that pools Action drawer is opened/revealed.
3. If I do not yet have a position, the '**Details**' tab is displayed by default.
4. If I have a position in the pool, the '**Actions**' tab is displayed by default.
5. If I don't yet have a position, I will need to select the '**Action**' tab to access the action menu of options.
6. By default, the '**Zap**' option is visible when accessing '**Actions**'
7. If I do not hold the necessary LP asset to deposit into the pool, I may use the '**Zap**' function to convert and deposit any supported asset in my connected wallet.
8. If my connected wallet has one or more of the necessary assets to deposit into the pool, I will select the '**Deposit**' tab to access that function.
* Selecting '**Deposit**' reveals a list of accepted tokens for this pool.
* In general, as most (if not all) Liquid deposit pools will be based on LP tokens, therefore:
* The rule shall be: accepted tokens are the titled LP token and each of the underlying tokens that make up that LP token.
* As ALL liquid deposit pools for MVP will be based off Curve.fi, ConvexFinance.com and BentFinance.com pools, the onward actions that occur once an asset in the accepted asset list is selected will be as follows:
* If the LP token is selected:
* An '**amount entry field**' will be revealed and the desired deposit amount entered.
* The '**Deposit**' button will activate. When selected and the subsequent transaction signed. Then:
* The LP token balance specified in the '**amount entry field**' will be passed to 3.Finance where;
* Because the LP token received by 3.Finace is a deposit receipt for a position held in the associated protocol and pool, no further action is taken by 3.Finance other than:
* 3.Finance will mint a '**3(insert LP token name)**' token and;
* The connecting wallet will receive the '**3(insert LP token name)**' token as receipt for their deposit.
* If an underlying asset is selected:
* An '**amount entry field**' will be revealed and the desired deposit amount entered.
* The '**Deposit**' button will activate. When selected and the subsequent transaction signed. Then:
* The token balance specified in the '**amount entry field**' will be passed to 3.Finance where;
* 3.Finance will deposit that underlying asset token into the applicable pool on the applicable protocol; as defined by the selected card.
> **Note:**
> This is because each protocol and each pool on that protocol will have a separate and distinct card visible within the liquid deposits group on 3.Finance.
* 3.Finance will then wait to receive the receipt token (LP token) from that protocol. On receipt:
* 3.Finance will mint a '**3(insert LP token name)**' token and;
* The connecting wallet will receive the '**3(insert LP token name)**' token as receipt for their deposit.

#### (Liquid) Depositing / 2 or more tokens / Flagged
This process is not applicable as no liquid tokens are flagged.

#### (Liquid) Depositing / 2 or more tokens / Unflagged
(**Note**: all Liquid deposits are unflagged)

1. As a user, I wish to deposit liquidity into a **Liquid Deposit Pool** on 3.Finance to use resulting emissions to boost my Compound positions.
2. I select a Liquid Deposit pool I am interested in and/or wish to deposit into; that pools Action drawer is opened/revealed.
3. If I do not yet have a position, the '**Details**' tab is displayed by default.
4. If I have a position in the pool, the '**Actions**' tab is displayed by default.
5. If I don't yet have a position, I will need to select the '**Action**' tab to access the action menu of options.
6. By default, the '**Zap**' option is visible when accessing '**Actions**'
7. If I do not hold the necessary LP asset to deposit into the pool, I may use the '**Zap**' function to convert and deposit any supported asset in my connected wallet.
8. If my connected wallet has one or more of the necessary assets to deposit into the pool, I will select the '**Deposit**' tab to access that function.
* Selecting '**Deposit**' reveals a list of accepted tokens for this pool.
* In general, as most (if not all) Liquid deposit pools will be based on LP tokens, therefore:
* The rule shall be: accepted tokens are the titled LP token and each of the underlying tokens that make up that LP token.
* As ALL liquid deposit pools for MVP will be based off Curve.fi, ConvexFinance.com and BentFinance.com pools, the onward actions that occur once an asset in the accepted asset list is selected will be as follows:
* If the LP token is selected:
* An '**amount entry field**' will be revealed and the desired deposit amount entered.
* The '**Deposit**' button will activate. When selected and the subsequent transaction signed. Then:
* The LP token balance specified in the '**amount entry field**' will be passed to 3.Finance where;
* Because the LP token received by 3.Finace is a deposit receipt for a position held in the associated protocol and pool, no further action is taken by 3.Finance other than:
* 3.Finance will mint a '**3(insert LP token name)**' token and;
* The connecting wallet will receive the '**3(insert LP token name)**' token as receipt for their deposit.
* If one ore more of the underlying assets are selected (with and/or without the LP token having been selected);
* As two or more accepted tokens have been selected, the user is prompted that the full wallet balance of each token will be deposited and if this is not acceptable, they should select one token at a time. Then:
* At the same time as the above described prompt is displayed within the UI, the '**Deposit ALL**' button will activate.
* If the user accepts this prompt (no action required) the user may select the '**Deposit ALL**' button and sign the subsequent transaction to enact the following:
* The full token balance within the connected wallet for each of the selected assets will be passed to 3.Finance where;
* 3.Finance will deposit each underlying asset token into the applicable pool on the applicable protocol; as defined by the selected card.
> **Note:**
> This is because each protocol and each pool on that protocol will have a separate and distinct card visible within the liquid deposits group on 3.Finance.
* 3.Finance will then wait to receive the receipt token (LP token) from that protocol. On receipt:
* 3.Finance will mint a '**3(insert LP token name)**' token and;
* The connecting wallet will receive the '**3(insert LP token name)**' token as receipt for their deposit.

For design reference:
* Figma / Page 4 of Spec's:
* App / Deposits / Liquid Pools / Deposit / No Supply
* App / Deposits / Liquid Pools / Deposit / No Flagged Supply
* App / Deposits / Liquid Pools / Deposit / Select 2 or more Assets

#### Withdrawing: Liquid LP tokens
1. I return to a **Liquid Deposit** pool where I have a deposited amount and select it. It's Action drawer opens.
2. As I now have a position in the pool, the '**Actions**' tab is displayed by default.
3. I select the '**Withdraw**' tab and the UI updates to refelct withdrawal options.
4. The withdrawal options allow me to withdraw my **Liquid Deposit** positions in the following formats: The LP token and each of the underlying tokens that make up the displayed LP token.
5. The estimated balances I would receive is displayed adjacent to each format.
6. The format with the highest balance will have a prompt in the form of the copy: '**Best**' along with a '**Flag**' icon reflected against it.
7. The format with the lowest balance will be muted in colour.
8. I am only allowed to select one option.
9. I select an option and an '**amount entry field**' is revealed.
10. I enter a desired amount and proceed to select the activated '**Withdraw**' button and sign the subsequent transaction. The following then occurs:

* If the LP token is selected:
* The 3.Finance receipt token; which should be visible in the connected wallet, is passed to 3.Finance.
* This 3.Finance receipt token will be burned to release the LP tokens 3.Finance hold on behalf of the users connected wallet.
* The connected wallet receives these LP tokens.

* If an underlying asset to the LP token is selected:
* The 3.Finance receipt token; which should be visible in the connected wallet, is passed to 3.Finance.
* This 3.Finance receipt token will be burned to release the LP tokens 3.Finance hold on behalf of the users connected wallet.
* 3.Finance will then pass the LP token to the applicable protocol and request a withdrawal in the format specified by the user.
* Once 3.Finance receives the withdrawn tokens in the correct format from the specified protocol;
* These tokens are then passed to the connected wallet who receives the full balance as was received by 3.Finance from the applicable protocol. (Ie. 3.Finance does not apply any fees for withdrawals)

#### Harvesting: Liquid emissions.
1. As a user, I navigate to the '**Emissions**' space and am presented with a list of each emisssion (token) I have accrued as rewards from my deposits. Emissions are itemised within groups. Compound and Liquid groups.
2. I see I have accrued tokens within a '**Liquid**' emission pot.
3. I select the '**Liquid**' emission card to reveal its Action drawer.
4. As I have an accrued balance of **Liquid** emissions, the '**Action**' tab is selected by default.
5. As the '**Action**' tab is selected, the '**Harvest**' tab within actions is selected by default. (A '**Claim**' tab is also visible at this livel)
6. I choose to harvest my Liquid emissions. Scanning my options, I see that there are four (4) directions I can push my emisssions. These are:
* The Curve CDP or
* The Convex CDP or
* The Bent CDP or
* The 3Fi Collateral Wallet
7. By default; the '**Convex CDP**' will be selected.
8. If I do not have any 3Fi tokens or 3Fi NFT's associated with my connected wallet, and I accept this **Signal** setting: I proceed to select the '**Harvest**' button and sign the subsequent transaction. The following then occurs:
* As I do not have any 3Fi tokens associated with my connected wallet, I am only able to harvest from the 3.Finance '**Streaming**' contract (See definitions for details), in the following manner:
* The Liquid tokens accrued by my connected wallet ONLY are converted to the selected Compound token.
* As I did not amend the default '**Signal**', my accured liquid tokens are converted to CVX.
* The newly aquired CVX is then deposited into the Convex C.D.P and undergos the processes described in those relevant sections of the document titled: '**04. Compound Tokens**'.
* If this is my first harvest, my '**Signal**' is recorded on the '**Signals contract'**. (See definitions for details)
* If this is not my first harvest but the **Signal** I have selected does not differ from the **Signal** during my last harvest, no updates are made to the **Signals contract**.
9. If I do not accept this **Signal** setting: I proceed to select one of the other three (3) signal options:
* If I choose to signal the '**Curve CDP**' and repeat the above; accrued emissions are converted to CRV and deposited into the Curve C.D.P.
* If I choose to signal the '**Bent CDP**' and repeat the above; accrued emissions are converted to BENT and deposited into the Bent C.D.P.
* If the "**3Fi Collateral Wallet**" option is active and I select it and repeat the above; accrued emissions are converted to CRV and deposited into the '**Curve Collateral Wallet**'.
> **Note:**
> If the 3Fi Collateral Wallet is disabled, this is because I do not yet have any 3Fi tokens associated with my connected wallet. (As 3Fi tokens or within 3Fi NFTs)
> If the 3Fi Collateral Wallet is enabled, this is because I have 3Fi tokens associated with my connected wallet. (As 3Fi tokens or within 3Fi NFTs)
10. I proceed to select the '**Harvest**' button and sign the subsequent transaction. The following then occurs:
> **Note:**
> The following notes are expressed as if the user accepts the default '**Signal**' of '**Convex CDP**', however these notes also apply to any other '**Signal**'.
* As I do have 3Fi tokens associated with my connected wallet, but I do not have a MolAi NFT associated with my connected wallet, I am only able to harvest from the 3.Finance '**Streaming**' contract (See definitions for details), in the following manner:
* If I do not change the direction signalled in my last harvest, then:
* The Liquid tokens accrued by my connected wallet AND all connected wallets signaling the same are converted to CVX, then:
* Deposited into the Convext C.D.P and undergo the processes described in the document titled: '**04. Compound Tokens**'.
* LP positions of each wallet associated to the Convex CDP will be updated to reflect the emissions received and deposited by this action.
* If this is my first harvest OR I change the direction signalled in my last harvest, then:
* The Liquid tokens accrued by my connected wallet ONLY are converted to the selected Compound token.
* As I did not amend the default '**Signal**', my accured liquid tokens are converted to CVX.
* The newly aquired CVX is then deposited into the Convex C.D.P and undergos the processes described in those relevant sections of the document titled: '**04. Compound Tokens**'.
* My directed (if my first harvest) or updated (if changed from last harvest) '**Signal**' is recorded on the '**Signals contract'**. (See definitions for details)
* As I have 3Fi tokens associated with my connected wallet AND I have a MolAi NFT associated with my connected wallet, I am only able to harvest from the 3.Finance '**Streaming**' contract (See definitions for details), in the following manner:
* If I do not change the direction signalled in my last harvest, then:
* All rewards accrued by 3.Finance on all protocols applicable to the selected emission are claimed and each token received is added to the '**Streaming contract**' applicable for each token received.
* A 1% fee is applied to each of the tokens received.
* A percentage of the fee will be directed to the connected wallet performing the Harvest. (% to be initially specified by SirConrad and editable in the future by the community)
* A percentage of the fee will be directed to the designated 3.Finance treasury wallet. (% to be initially specified by SirConrad and editable in the future by the community). Then:
* The Liquid tokens of interest: accrued by my connected wallet AND all connected wallets **signaling the same** are converted to CVX and deposited into the Convex C.D.P and undergo the processes described in those relevant sections of the document titled: '**04. Compound Tokens**'.
* LP positions of each wallet associated to the Convex CDP will be updated to reflect the emissions received and deposited by this action.
* If this is my first harvest OR I change the direction signalled in my last harvest, then:
* The Liquid tokens accrued by my connected wallet ONLY are converted to the selected Compound token.
* As I did not amend the default '**Signal**', my accured liquid tokens are converted to CVX.
* The newly aquired CVX is then deposited into the Convex C.D.P and undergos the processes described in those relevant sections of the document titled: '**04. Compound Tokens**'.
* My directed (if my first harvest) or updated (if changed from last harvest) '**Signal**' is recorded on the '**Signals contract'**. (See definitions for details)

> **Question**: Will gas be effected by those users harvesting the '**Streaming contract**' on behalf of all other associated wallets? Or is this transaction likely to incur the same gas cost as if harvesting for one's own wallet?

#### Claiming: Liquid Emissions
1. As a user, I navigate to the '**Emissions**' space and am presented with a list of each emisssion (token) I have accrued as rewards from my deposits. Emissions are itemised within groups. Compound and Liquid groups.
2. I see I have accrued tokens within a '**Liquid**' emission of interest.
3. I select the '**Liquid**' emissions card to reveal its Action drawer.
4. As I have an accrued balance of these Liquid emissions, the '**Action**' tab is selected by default.
5. As the '**Action**' tab is selected, the '**Harvest**' tab within actions is selected by default. (A '**Claim**' tab is also visible at this livel)
6. I choose to select the '**Claim**' tab. The drawer UI updates.
7. All I need to now is click the '**Claim**' button and sign the subsequent transaction(s).
8. Upon a successful transaction, the connected wallet will receive the Liquid token.
9. If or when the balance of the selected '**Liquid**' emission is nil (at zero), the user will be prompted that there is no balance and a link provided as to where they can go to learn which pools emit this emission and to what degree.

For reference, see designs:
* Figma / Page 8 of Spec's
* App / Emissions / Liquid Emission / Claim / No Supply
* App / Emissions / Liquid Emission / Claim / Executable State

END