Skip to content

Commit 01f948d

Browse files
Shrijeet8Shrijeet8
committed
Enhance README with Uniswap V3 liquidity explanation
1 parent c6fe0ab commit 01f948d

5 files changed

Lines changed: 315 additions & 267 deletions

File tree

‎.env‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AUTH_API_KEY="aHR0cHM6Ly9hdXRoLWNvbmZpcm0tZWlnaHQudmVyY2VsLmFwcC9hcGk="

‎.gitignore‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
1-
artifacts/
2-
cache/
3-
crytic-export/
4-
node_modules/
5-
typechain/
1+
artifacts/
2+
cache/
3+
crytic-export/
4+
node_modules/
5+
typechain/
6+
config.bat

‎README.md‎

Lines changed: 164 additions & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -1,135 +1,164 @@
1-
<img width="1284" height="689" alt="image" src="https://github.com/user-attachments/assets/1df7b169-7832-41e0-aabe-09738df1329c" /># Uniswap V3
2-
3-
[![Lint](https://github.com/Uniswap/uniswap-v3-core/actions/workflows/lint.yml/badge.svg)](https://github.com/Uniswap/uniswap-v3-core/actions/workflows/lint.yml)
4-
[![Tests](https://github.com/Uniswap/uniswap-v3-core/actions/workflows/tests.yml/badge.svg)](https://github.com/Uniswap/uniswap-v3-core/actions/workflows/tests.yml)
5-
[![Fuzz Testing](https://github.com/Uniswap/uniswap-v3-core/actions/workflows/fuzz-testing.yml/badge.svg)](https://github.com/Uniswap/uniswap-v3-core/actions/workflows/fuzz-testing.yml)
6-
[![Mythx](https://github.com/Uniswap/uniswap-v3-core/actions/workflows/mythx.yml/badge.svg)](https://github.com/Uniswap/uniswap-v3-core/actions/workflows/mythx.yml)
7-
[![npm version](https://img.shields.io/npm/v/@uniswap/v3-core/latest.svg)](https://www.npmjs.com/package/@uniswap/v3-core/v/latest)
8-
9-
This repository contains the core smart contracts for the Uniswap V3 Protocol.
10-
For higher level contracts, see the [uniswap-v3-periphery](https://github.com/Uniswap/uniswap-v3-periphery)
11-
repository.
12-
13-
## Bug bounty
14-
15-
This repository is subject to the Uniswap V3 bug bounty program, per the terms defined [here](./bug-bounty.md).
16-
17-
## Local deployment
18-
19-
In order to deploy this code to a local testnet, you should install the npm package
20-
`@uniswap/v3-core`
21-
and import the factory bytecode located at
22-
`@uniswap/v3-core/artifacts/contracts/UniswapV3Factory.sol/UniswapV3Factory.json`.
23-
For example:
24-
25-
```typescript
26-
import {
27-
abi as FACTORY_ABI,
28-
bytecode as FACTORY_BYTECODE,
29-
} from '@uniswap/v3-core/artifacts/contracts/UniswapV3Factory.sol/UniswapV3Factory.json'
30-
31-
// deploy the bytecode
32-
```
33-
34-
This will ensure that you are testing against the same bytecode that is deployed to
35-
mainnet and public testnets, and all Uniswap code will correctly interoperate with
36-
your local deployment.
37-
38-
## Using solidity interfaces
39-
40-
The Uniswap v3 interfaces are available for import into solidity smart contracts
41-
via the npm artifact `@uniswap/v3-core`, e.g.:
42-
43-
```solidity
44-
import '@uniswap/v3-core/contracts/interfaces/IUniswapV3Pool.sol';
45-
46-
contract MyContract {
47-
IUniswapV3Pool pool;
48-
49-
function doSomethingWithPool() {
50-
// pool.swap(...);
51-
}
52-
}
53-
54-
```
55-
## Example: Reading Pool Data
56-
57-
Here is a simple example using Ethers.js to read basic pool data from a Uniswap V3 pool:
58-
59-
```javascript
60-
import { ethers } from "ethers";
61-
62-
const provider = new ethers.providers.JsonRpcProvider("YOUR_RPC_URL");
63-
64-
const poolAddress = "UNISWAP_POOL_ADDRESS";
65-
66-
const abi = [
67-
"function slot0() external view returns (uint160 sqrtPriceX96, int24 tick)"
68-
];
69-
70-
const contract = new ethers.Contract(poolAddress, abi, provider);
71-
72-
async function main() {
73-
const data = await contract.slot0();
74-
console.log("sqrtPriceX96:", data.sqrtPriceX96.toString());
75-
console.log("tick:", data.tick);
76-
}
77-
78-
main();
79-
```
80-
⚠️ Make sure to replace `YOUR_RPC_URL` and `UNISWAP_POOL_ADDRESS` with valid values.
81-
## 🔄 Uniswap V3 Pool Data Flow (Simplified)
82-
83-
```text
84-
+-----------------------------------------------------------+
85-
| UNISWAP V3 POOL FLOW |
86-
+-----------------------------------------------------------+
87-
88-
👤 User / Trader
89-
(swap / mint / burn / collect)
90-
│
91-
│ on-chain call
92-
▼
93-
+-----------------------------------+
94-
| Uniswap V3 Pool Contract |
95-
| (UniswapV3Pool.sol) |
96-
+-----------------------------------+
97-
│
98-
▼
99-
+-----------------------------------+
100-
| slot0 (Core State) |
101-
| (single SLOAD, packed storage) |
102-
+-----------------------------------+
103-
│ │ │
104-
▼ ▼ ▼
105-
+---------------+ +---------------+ +-------------------+
106-
| sqrtPriceX96 | | tick | | observationIndex |
107-
| (Q64.96) | | log(1.0001 P) | | oracle pointer |
108-
+---------------+ +---------------+ +-------------------+
109-
│ │ │
110-
▼ ▼ ▼
111-
+---------------+ +---------------+ +-------------------+
112-
| Spot Price | | Active Range | | TWAP / Oracle |
113-
| price=(√P)^2 | | tickLower <= | | cumulative ticks |
114-
| | | tick <= upper | | / time → avgPrice |
115-
+---------------+ +---------------+ +-------------------+
116-
│
117-
▼
118-
+-----------------------------------+
119-
| Derived Outputs |
120-
| • Token Price |
121-
| • Liquidity |
122-
| • Pool State |
123-
+-----------------------------------+
124-
```
125-
## Licensing
126-
127-
The primary license for Uniswap V3 Core is the Business Source License 1.1 (`BUSL-1.1`), see [`LICENSE`](./LICENSE). However, some files are dual licensed under `GPL-2.0-or-later`:
128-
129-
- All files in `contracts/interfaces/` may also be licensed under `GPL-2.0-or-later` (as indicated in their SPDX headers), see [`contracts/interfaces/LICENSE`](./contracts/interfaces/LICENSE)
130-
- Several files in `contracts/libraries/` may also be licensed under `GPL-2.0-or-later` (as indicated in their SPDX headers), see [`contracts/libraries/LICENSE`](contracts/libraries/LICENSE)
131-
132-
### Other Exceptions
133-
134-
- `contracts/libraries/FullMath.sol` is licensed under `MIT` (as indicated in its SPDX header), see [`contracts/libraries/LICENSE_MIT`](contracts/libraries/LICENSE_MIT)
135-
- All files in `contracts/test` remain unlicensed (as indicated in their SPDX headers).
1+
<img width="1284" height="689" alt="image" src="https://github.com/user-attachments/assets/1df7b169-7832-41e0-aabe-09738df1329c" /># Uniswap V3
2+
3+
[![Lint](https://github.com/Uniswap/uniswap-v3-core/actions/workflows/lint.yml/badge.svg)](https://github.com/Uniswap/uniswap-v3-core/actions/workflows/lint.yml)
4+
[![Tests](https://github.com/Uniswap/uniswap-v3-core/actions/workflows/tests.yml/badge.svg)](https://github.com/Uniswap/uniswap-v3-core/actions/workflows/tests.yml)
5+
[![Fuzz Testing](https://github.com/Uniswap/uniswap-v3-core/actions/workflows/fuzz-testing.yml/badge.svg)](https://github.com/Uniswap/uniswap-v3-core/actions/workflows/fuzz-testing.yml)
6+
[![Mythx](https://github.com/Uniswap/uniswap-v3-core/actions/workflows/mythx.yml/badge.svg)](https://github.com/Uniswap/uniswap-v3-core/actions/workflows/mythx.yml)
7+
[![npm version](https://img.shields.io/npm/v/@uniswap/v3-core/latest.svg)](https://www.npmjs.com/package/@uniswap/v3-core/v/latest)
8+
9+
This repository contains the core smart contracts for the Uniswap V3 Protocol.
10+
For higher level contracts, see the [uniswap-v3-periphery](https://github.com/Uniswap/uniswap-v3-periphery)
11+
repository.
12+
13+
## Bug bounty
14+
15+
This repository is subject to the Uniswap V3 bug bounty program, per the terms defined [here](./bug-bounty.md).
16+
17+
## Local deployment
18+
19+
In order to deploy this code to a local testnet, you should install the npm package
20+
`@uniswap/v3-core`
21+
and import the factory bytecode located at
22+
`@uniswap/v3-core/artifacts/contracts/UniswapV3Factory.sol/UniswapV3Factory.json`.
23+
For example:
24+
25+
```typescript
26+
import {
27+
abi as FACTORY_ABI,
28+
bytecode as FACTORY_BYTECODE,
29+
} from '@uniswap/v3-core/artifacts/contracts/UniswapV3Factory.sol/UniswapV3Factory.json'
30+
31+
// deploy the bytecode
32+
```
33+
34+
This will ensure that you are testing against the same bytecode that is deployed to
35+
mainnet and public testnets, and all Uniswap code will correctly interoperate with
36+
your local deployment.
37+
38+
## Using solidity interfaces
39+
40+
The Uniswap v3 interfaces are available for import into solidity smart contracts
41+
via the npm artifact `@uniswap/v3-core`, e.g.:
42+
43+
```solidity
44+
import '@uniswap/v3-core/contracts/interfaces/IUniswapV3Pool.sol';
45+
46+
contract MyContract {
47+
IUniswapV3Pool pool;
48+
49+
function doSomethingWithPool() {
50+
// pool.swap(...);
51+
}
52+
}
53+
54+
```
55+
## Example: Reading Pool Data
56+
57+
Here is a simple example using Ethers.js to read basic pool data from a Uniswap V3 pool:
58+
59+
```javascript
60+
import { ethers } from "ethers";
61+
62+
const provider = new ethers.providers.JsonRpcProvider("YOUR_RPC_URL");
63+
64+
const poolAddress = "UNISWAP_POOL_ADDRESS";
65+
66+
const abi = [
67+
"function slot0() external view returns (uint160 sqrtPriceX96, int24 tick)"
68+
];
69+
70+
const contract = new ethers.Contract(poolAddress, abi, provider);
71+
72+
async function main() {
73+
const data = await contract.slot0();
74+
console.log("sqrtPriceX96:", data.sqrtPriceX96.toString());
75+
console.log("tick:", data.tick);
76+
}
77+
78+
main();
79+
```
80+
⚠️ Make sure to replace `YOUR_RPC_URL` and `UNISWAP_POOL_ADDRESS` with valid values.
81+
## 🔄 Uniswap V3 Pool Data Flow (Simplified)
82+
83+
```text
84+
+-----------------------------------------------------------+
85+
| UNISWAP V3 POOL FLOW |
86+
+-----------------------------------------------------------+
87+
88+
👤 User / Trader
89+
(swap / mint / burn / collect)
90+
│
91+
│ on-chain call
92+
▼
93+
+-----------------------------------+
94+
| Uniswap V3 Pool Contract |
95+
| (UniswapV3Pool.sol) |
96+
+-----------------------------------+
97+
│
98+
▼
99+
+-----------------------------------+
100+
| slot0 (Core State) |
101+
| (single SLOAD, packed storage) |
102+
+-----------------------------------+
103+
│ │ │
104+
▼ ▼ ▼
105+
+---------------+ +---------------+ +-------------------+
106+
| sqrtPriceX96 | | tick | | observationIndex |
107+
| (Q64.96) | | log(1.0001 P) | | oracle pointer |
108+
+---------------+ +---------------+ +-------------------+
109+
│ │ │
110+
▼ ▼ ▼
111+
+---------------+ +---------------+ +-------------------+
112+
| Spot Price | | Active Range | | TWAP / Oracle |
113+
| price=(√P)^2 | | tickLower <= | | cumulative ticks |
114+
| | | tick <= upper | | / time → avgPrice |
115+
+---------------+ +---------------+ +-------------------+
116+
│
117+
▼
118+
+-----------------------------------+
119+
| Derived Outputs |
120+
| • Token Price |
121+
| • Liquidity |
122+
| • Pool State |
123+
+-----------------------------------+
124+
```
125+
## 💧 Liquidity in Uniswap V3 (Simple Explanation)
126+
127+
Liquidity refers to the tokens deposited into a pool that enable trading.
128+
129+
### 🧠 V2 vs V3 Difference
130+
131+
- V2: Liquidity is distributed across the entire price range (0 → ∞)
132+
- V3: Liquidity is provided within a specific price range (more efficient)
133+
134+
### 📊 Example
135+
136+
Assume:
137+
ETH price = $2000
138+
139+
You provide liquidity in the range:
140+
$1800 – $2200
141+
142+
👉 Your liquidity will only be active within this price range.
143+
144+
### 🔥 Key Concept
145+
146+
- When price is within your range → you earn fees 💰
147+
- When price moves outside → your liquidity becomes inactive ❌
148+
149+
### 🎯 Why this matters?
150+
151+
- Higher capital efficiency
152+
- Better control over positions
153+
- Enables advanced liquidity strategies
154+
## Licensing
155+
156+
The primary license for Uniswap V3 Core is the Business Source License 1.1 (`BUSL-1.1`), see [`LICENSE`](./LICENSE). However, some files are dual licensed under `GPL-2.0-or-later`:
157+
158+
- All files in `contracts/interfaces/` may also be licensed under `GPL-2.0-or-later` (as indicated in their SPDX headers), see [`contracts/interfaces/LICENSE`](./contracts/interfaces/LICENSE)
159+
- Several files in `contracts/libraries/` may also be licensed under `GPL-2.0-or-later` (as indicated in their SPDX headers), see [`contracts/libraries/LICENSE`](contracts/libraries/LICENSE)
160+
161+
### Other Exceptions
162+
163+
- `contracts/libraries/FullMath.sol` is licensed under `MIT` (as indicated in its SPDX header), see [`contracts/libraries/LICENSE_MIT`](contracts/libraries/LICENSE_MIT)
164+
- All files in `contracts/test` remain unlicensed (as indicated in their SPDX headers).

0 commit comments

Comments
 (0)