What's Really Going on When Processing Liquidity in a Uniswap Pool?
Unraveling the Intricacies of Liquidity Provision on Uniswap: The Role of Internal Accounting and EigenPhi's Transaction Analyzer
When liquidity providers add or remove liquidity in a Uniswap pool, the protocol uses internal accounting to save gas fees, among other reasons. This approach hides many details that retail users do not care about. However, if you want to become a sleuth of DeFi, it's critical to find out what's really going on behind the curtain. EigenPhi's EigenTx transaction analyzer offers a comprehensive toolset to unravel the complexities of the internal accounting procedures associated with adding and removing liquidity to a Uniswap pool. Consider yourself as a liquidity provider now. Basically, you can regard yourself as a shareholder of a bank branch. Adding your liquidity to a Uniswap pool is like adding your asset to the asset of the bank branch.
Now, follow my lead.
Pretend You Are One of the Shareholders of a Bank Branch.
First, take a look at the table below, which contains the information that concerns your interests when you become one of the shareholders of the branch.
You put USD and CAD(Canadian dollars) into the branch. In return, you receive shares of the branch.
The bank's database has internal data to store how many USD and CAD this branch owns, marked as "Internal USD" and "Internal CAD."
Meanwhile, to keep your record right, the bank's database also shows how much USD and CAD you have put into the bank, marked as "External USD" and "External CAD."
The bank branch has the data of the total shares of this branch, marked as "Entire Liquidity Share."
Your shares of the branch are recorded as "Shareholder's Share."
Now, when you put your USD and CAD assets into the bank branch as your contribution to the liquidity share of the branch, the amount of your contribution will be reflected as follows:
The amount of Internal USD will increase, adding your USD contribution.
The amount of Internal CAD will increase, adding your CAD contribution.
The amount of External USD is your USD contribution.
The amount of External CAD is your CAD contribution.
The number of Entire Liquidity Shares will increase, adding your shares based on your USD and CAD contribution.
The number of the Shareholder's Shares will increase, adding your shares based on your USD and CAD contributions.
All the operations above will generate an "adding" record of the internal bookkeeping for each operation.
Let's consider what happens when you remove your USD and CAD assets from the bank branch's overall shares. The amount of your removal will be reflected as follows:
The amount of Internal USD will decrease, removing your USD contribution.
The amount of Internal CAD will decrease, removing your CAD contribution.
The amount of External USD is your USD removal.
The amount of External CAD is your CAD removal.
The number of Entire Liquidity Shares will decrease, removing your shares based on your USD and CAD removals.
The number of Shareholder's Shares will be your shares based on your USD and CAD removals.
All the operations above will generate a "removing" record of the internal bookkeeping for each operation.
Let's Match the Bank Branch to a Uniswap Pool.
A Uniswap Pool is like a bank branch. We have a table like this showing an Unsiwap V3 pool trading WBTC and USDC.
In this table:
The number 350101 is the liquidity provider's identification number.
"UNI-V3-POS" is the NFT contract used by Uniswap. When a liquidity provider adds WBTC and USDC to the pool, the contract will mint an NFT and send it to the liquidity provider. This is an actual contract that was deployed by the Uniswap team. EigenTx uses this contract to represent the internal records of liquidity providers' contributions.
"UNI-V3-POS-350101" is the actual NFT issued by the aforementioned NFT contract. EigenTx uses it to represent the external records of the liquidity providers' contributions.
Besides the two above, the left contracts are virtual contracts introduced by EigenTx to demonstrate the internal accounting procedure, following the double-entre bookkeeping rules.
EigenTx also uses virtual assets for internal accounting, which can be found in the following example.
You can put on the Liquidity Provider hat now.
"virtualOwed0WBTC" and "virtualOwed1USDC" are virtual contracts storing your WBTC and USDC contribution to the pool for internal uses.
"virtualOwed0WBTC-350101" and "virtualOwed1USDC--350101" are virtual contracts storing your WBTC and USDC contribution to the pool for your use.
The pool has the data of the total shares of this pool, marked as "virtualLiquidity."
Your exclusive shares of the pool are recorded in "virtualLiquidity-350101."
EigenTx uses "mint" to show a record of adding one kind of asset or shares, which could be actual or virtual, to a contract.
EigenTx uses "burn" to show a record of removing one kind of asset or shares, which could be actual or virtual, from a contract.
We can also match the assets and shares between the bank branch analogy and the pool.
Adding Liquidity.
Let's look at this add liquidity transaction shown in EigenTx to understand what's happening.
The full token flow chart is here.
Dive into the details.
Steps 0, 1: You added USDC and WBTC to the pool.
Step 2: The "virtualLiquidity," the virtual contract recording the total shares of the pool, minted a certain amount of "virtualLiquidity," to record your adding USDC & WBTC liquidity operation. Here, EigenTx uses "virtualLiquidity" as a voucher.
Step 3: The double-entry bookkeeping demands that once a record is added, another record must be added to balance the balance sheet. After step 2, another virtual asset as a voucher, "virtualLiquidity-350101", has to be "minted" to record the shares owned by you now, and it is transferred to your "UNI-V3-POS-350101" NFT contract.
Step 4: The actual NFT, UNI-V3-POS-350101, is minted and transferred to you, the liquidity provider, indicating your position/shares in the pool.
All the dashed lines in the chart show the connections between these actual and virtual contracts.
In comparison with adding liquidity, removing liquidity is more complex.
Removing Liquidity.
When removing liquidity from a pool, several things will happen in this transaction. Remember, you are still the liquidity provider here. Let's use the above tables again for easier understanding.
MOVE 1: Your exclusive shares of the pool in "virtualLiquidity-350101" will be burned to reflect your liquidity removal. This is a virtual shares "burn" operation added by EigenTx to indicate the internal accounting operation. Remember that we've added "minted," 2 virtual shares in the Adding Liquidity transaction.
MOVE 2: The total shares of the pool will remove your shares from the total share "virtualLiquidity." This is also a virtual shares "burn" operation added by EigenTx to indicate the internal accounting operation.
MOVE 3: The internal assets position data will remove your assets. Since we did not mint any virtual assets in the Adding Liquidity transaction, here we need to "mint" the virtual assets first. These are also "virtual" operations.
The internal accounting processes of Uniswap and Bank are generally similar, with the difference being that, on Uniswap, after a user deposits money, their assets are mixed with others and follow the changes in currency holdings according to the AMM curve. Therefore, when depositing money, it is not necessary to record how much of each token has been deposited. When the liquidity is removed, Uniswap calculates the specific amount of tokens that can be taken out based on the provider's liquidity shares.
MOVE 4: The removed virtual assets from the pool's internal assets positions will be added to your external position data, which are "mint" operations. These are also "virtual" operations.
MOVE 5: Now, the pool's internal accounting operations have done the removal process. Then, the pool transfers the actual assets to you, including the liquidity fees you earn.
MOVE 6: To keep the sheet balance, the internal and external position data need to "burn" the virtual assets. These are also "virtual" related operations.
MOVE 7: In the end, the Position NFT will be burned to reflect the liquidity removal.
Now, let's look at this actual liquidity removal transaction step by step.
Here is the whole token flow chart.
It is time to thoroughly break down the steps involved and match the abovementioned moves.
Steps 0-1: The two virtual internal assets positions minted virtualOwed0WBTC and virtualOwed1USDC and sent to the actual total internal position contract. MOVE 3. These 2 steps are overlapped in the chart. But you can find the details in the transfer list shown below.
Go to the next step.
Step 2: The virtual total shares burned your shares. MOVE 2.
Step 3: Your exclusive external virtual shares were burned. MOVE 1.
Steps 4-5: The two virtual external assets positions minted virtualOwed0WBTC-350101 and virtualOwed1USDC-350101 and sent to the actual total internal position contract. MOVE 4.
Steps 6-7: The pool transferred your liquidity and fees you earned back to you. MOVE 5.
Steps 8-11: Now that both the internal and external representation of the liquidity provider account should have no balance. UNI-V3-POS and UNI-V3-POS-350101 burned the corresponding balances of virtual assets. MOVE 6.
Step 12: This matches the MOVE 7 that burned the position NFT to reflect the liquidity removal.
Step 13: The builder was paid.
Conclusion
EigenTx creates these virtual contracts and assets to demonstrate how Uniswap deals with liquidity operations, helping users understand one of the most significant DeFi protocols' mechanisms. With the release of Uniswap V4, EigentTx will keep improving to mirror the latest developments of the incumbent project.
Follow us via these to dig more hidden wisdom of DeFi:
EigenTx | Website | Discord | Twitter | YouTube | Substack | Medium | Telegram