Skip to content

Commit 327d079

Browse files
angel10xangel10x
authored
Merge pull request #6 from angel10x/dev
feat: readme
2 parents c29fb52 + b37a2f7 commit 327d079

File tree

2 files changed

+537
-39
lines changed

2 files changed

+537
-39
lines changed

‎README.md‎

Lines changed: 243 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,270 @@
1-
## Foundry
1+
[简体中文](./README_CN.md)
22

3-
**Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.**
3+
# GNad.Fun Smart Contract
44

5-
Foundry consists of:
5+
## Table of Contents
66

7-
- **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools).
8-
- **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data.
9-
- **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network.
10-
- **Chisel**: Fast, utilitarian, and verbose solidity REPL.
7+
- [System Overview](#system-overview)
8+
- [Contract Architecture](#contract-architecture)
9+
- [Key Components](#key-components)
10+
- [Main Functions](#main-functions)
11+
- [Events](#events)
12+
- [Usage Notes](#usage-notes)
13+
- [Testing](#testing)
14+
- [Development Information](#development-information)
1115

12-
## Documentation
16+
## System Overview
1317

14-
https://book.getfoundry.sh/
18+
gnad.fun is a smart contract system for creating and managing bonding curve-based tokens on the Monad blockchain. It enables creators to mint new tokens with associated bonding curves and allows traders to buy and sell these tokens through a centralized endpoint. The system uses a combination of bonding curves and automated market makers to provide liquidity and price discovery for newly created tokens.
1519

16-
## Usage
20+
## Contract Architecture
1721

18-
### Build
22+
### Core Contracts
1923

20-
```shell
21-
$ forge build
22-
```
24+
1. **GNad.sol**
2325

24-
### Test
26+
- Central contract that coordinates all system operations
27+
- Handles token creation, buying, and selling operations
28+
- Manages interactions with WMon (Wrapped Monad) and fee collection
29+
- Implements various safety checks and slippage protection
30+
- Supports EIP-2612 permit functionality for gasless approvals
2531

26-
```shell
27-
$ forge test
28-
```
32+
2. **BondingCurve.sol**
2933

30-
### Format
34+
- Implements the bonding curve logic using constant product formula
35+
- Calculates token prices based on virtual and real reserves
36+
- Manages token reserves and liquidity
37+
- Handles buy/sell operations with locked token mechanism
38+
- Supports DEX listing when target is reached
3139

32-
```shell
33-
$ forge fmt
34-
```
40+
3. **BondingCurveFactory.sol**
41+
42+
- Deploys new bonding curve contracts
43+
- Maintains registry of created curves
44+
- Ensures standardization of curve parameters
45+
- Manages configuration (fees, virtual reserves, target tokens)
46+
47+
4. **WMon.sol**
48+
- Wrapped Monad token implementation
49+
- Provides ERC20 interface for native Monad tokens
50+
- Enables deposit/withdraw functionality
51+
- Supports EIP-2612 permit
52+
53+
### Supporting Contracts
54+
55+
5. **FeeVault.sol**
56+
57+
- Collects and manages trading fees
58+
- Implements multisig withdrawal mechanism
59+
- Requires multiple signatures for withdrawals
60+
- Provides secure fee management
61+
62+
6. **Token.sol**
63+
64+
- Standard ERC20 implementation for created tokens
65+
- Includes ERC20Permit for gasless approvals
66+
- Single mint restriction (can only mint once)
67+
- Burn functionality for token holders
68+
69+
### Libraries
70+
71+
- **lib/BCLib.sol**
72+
- Bonding curve calculation functions
73+
- Amount in/out calculations
74+
- Fee calculation utilities
75+
76+
- **lib/Transfer.sol**
77+
- Safe native token transfer utilities
78+
- Handles transfer failures gracefully
79+
80+
### Interfaces
81+
82+
- Defines contract interfaces for all major contracts
83+
- Ensures proper contract interaction
84+
- Facilitates type safety and integration
85+
86+
### Errors
87+
88+
- Centralizes error definitions as string constants
89+
- Provides clear error messages
90+
- Improves debugging experience
91+
92+
## Key Components
93+
94+
| Component | Description |
95+
| ------------------- | ------------------------------------------------------------------------------------------ |
96+
| Creator | Initiates the creation of new tokens and bonding curves |
97+
| Trader | Interacts with the system to buy and sell tokens |
98+
| GNad | Main contract handling bonding curve creation, buying, and selling |
99+
| WMon | Wrapped Monad token used for transactions |
100+
| BondingCurveFactory | Deploys new bonding curve contracts |
101+
| BondingCurve | Manages token supply and price calculations using constant product formula |
102+
| Token | Standard ERC20 token contract deployed for each new coin |
103+
| DEX | External decentralized exchange (Uniswap V2 compatible) for token trading after listing |
104+
| FeeVault | Repository for accumulated trading fees; multisig-controlled withdrawals |
105+
106+
## Main Functions
107+
108+
### Create Functions
109+
110+
- `createBc`: Creates a new token and its associated bonding curve
111+
- Can optionally perform an initial buy during creation
112+
- Returns bonding curve address, token address, and initial reserves
113+
114+
### Buy Functions
115+
116+
| Function | Description |
117+
| ------------- | ----------------------------------------------------- |
118+
| `buy` | Market buy tokens at the current bonding curve price |
119+
| `protectBuy` | Buys tokens with slippage protection |
120+
| `exactOutBuy` | Buys an exact amount of tokens from a bonding curve |
35121

36-
### Gas Snapshots
122+
### Sell Functions
37123

38-
```shell
39-
$ forge snapshot
124+
| Function | Description |
125+
| ------------------- | ------------------------------------------------------------------------ |
126+
| `sell` | Market sells tokens at the current bonding curve price |
127+
| `sellPermit` | Market sells tokens at the current bonding curve price with permit |
128+
| `protectSell` | Sells tokens with slippage protection |
129+
| `protectSellPermit` | Sells tokens with slippage protection with permit |
130+
| `exactOutSell` | Sells tokens for an exact amount of native on the bonding curve |
131+
| `exactOutSellPermit`| Sells tokens for an exact amount of native on the bonding curve with permit |
132+
133+
### Utility Functions
134+
135+
- `getBcData`: Retrieves data about a specific bonding curve (address, virtual reserves, k)
136+
- `getAmountOut`: Calculates the output amount for a given input
137+
- `getAmountIn`: Calculates the input amount required for a desired output
138+
- `getFeeVault`: Returns the address of the fee vault
139+
140+
## Events
141+
142+
### GNad Events
143+
144+
```solidity
145+
event GNadCreate();
146+
event GNadBuy();
147+
event GNadSell();
40148
```
41149

42-
### Anvil
150+
### BondingCurve Events
151+
152+
```solidity
153+
event Buy(
154+
address indexed sender,
155+
address indexed token,
156+
uint256 amountIn,
157+
uint256 amountOut
158+
);
43159
44-
```shell
45-
$ anvil
160+
event Sell(
161+
address indexed sender,
162+
address indexed token,
163+
uint256 amountIn,
164+
uint256 amountOut
165+
);
166+
167+
event Lock(address indexed token);
168+
event Sync(
169+
address indexed token,
170+
uint256 reserveWNative,
171+
uint256 reserveToken,
172+
uint256 virtualWNative,
173+
uint256 virtualToken
174+
);
175+
176+
event Listing(
177+
address indexed curve,
178+
address indexed token,
179+
address indexed pair,
180+
uint256 listingWNativeAmount,
181+
uint256 listingTokenAmount,
182+
uint256 burnLiquidity
183+
);
46184
```
47185

48-
### Deploy
186+
### Factory Events
49187

50-
```shell
51-
$ forge script script/Counter.s.sol:CounterScript --rpc-url <your_rpc_url> --private-key <your_private_key>
188+
```solidity
189+
event Create(
190+
address indexed creator,
191+
address indexed bc,
192+
address indexed token,
193+
string tokenURI,
194+
string name,
195+
string symbol,
196+
uint256 virtualNative,
197+
uint256 virtualToken
198+
);
52199
```
53200

54-
### Cast
201+
## Usage Notes
202+
203+
- ⏰ **Deadline parameter**: Ensures transaction freshness in all trading functions
204+
- 🔐 **Token approvals**: Some functions require pre-approval of token spending
205+
- 💱 **WMon**: All transactions use WMon (Wrapped Monad) tokens
206+
- 📝 **EIP-2612 permit**: Gasless approvals available for buy/sell operations
207+
- 🛡️ **Slippage protection**: Implemented in `protectBuy` and `protectSell` functions
208+
- 🔒 **Locked tokens**: Bonding curves lock when target token amount is reached
209+
- 📊 **Virtual reserves**: Used for price calculation, separate from real reserves
210+
- 🏭 **DEX listing**: Automatic listing on DEX when locked token target is reached
211+
212+
## Testing
213+
214+
The project includes comprehensive test coverage using Foundry. To run tests:
215+
216+
```bash
217+
# Run all tests
218+
forge test
55219

56-
```shell
57-
$ cast <subcommand>
220+
# Run with verbose output (shows console.log)
221+
forge test -vv
222+
223+
# Run specific test file
224+
forge test --match-path test/WMon.t.sol
225+
226+
# Run with gas reporting
227+
forge test --gas-report
58228
```
59229

60-
### Help
230+
See [test/README.md](test/README.md) for more testing information.
231+
232+
## Development Information
233+
234+
This smart contract system is designed to create and manage bonding curve-based tokens on the Monad blockchain. The system uses:
235+
236+
- **Solidity**: ^0.8.13
237+
- **Foundry**: For development and testing
238+
- **OpenZeppelin**: For ERC20 and ERC20Permit implementations
239+
- **Uniswap V2**: For DEX integration after listing
240+
241+
### Key Features
242+
243+
- Constant product bonding curve formula
244+
- Virtual and real reserve management
245+
- Multisig fee vault
246+
- Gasless approvals via EIP-2612
247+
- Automatic DEX listing mechanism
248+
- Comprehensive test coverage
249+
250+
### Project Structure
61251

62-
```shell
63-
$ forge --help
64-
$ anvil --help
65-
$ cast --help
66252
```
253+
src/
254+
├── GNad.sol # Main contract
255+
├── BondingCurve.sol # Bonding curve implementation
256+
├── BondingCurveFactory.sol # Factory for creating curves
257+
├── WMon.sol # Wrapped Monad token
258+
├── Token.sol # ERC20 token implementation
259+
├── FeeVault.sol # Multisig fee vault
260+
├── lib/ # Utility libraries
261+
│ ├── BCLib.sol # Bonding curve calculations
262+
│ └── Transfer.sol # Safe transfer utilities
263+
├── interfaces/ # Contract interfaces
264+
└── errors/ # Error definitions
265+
266+
test/
267+
└── *.t.sol # Test files
268+
```
269+
270+
📌 For questions or support, please open an issue in the GitHub repository.

0 commit comments

Comments
 (0)