Skip to content

Commit a6ad291

Browse files
author
Ryan
committed
added readme
1 parent dc6e961 commit a6ad291

1 file changed

Lines changed: 122 additions & 38 deletions

File tree

‎README.md‎

Lines changed: 122 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,150 @@
1-
## Foundry
1+
# Proxy Forge
22

3-
**Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.**
3+
**ProxyForge** is a lightweight, gas-optimized framework for deploying and managing upgradeable proxies on the Ethereum Virtual Machine (EVM). It maintains compatibility with OpenZeppelin's proxy architecture while introducing low-level optimizations and slot-based metadata tracking.
44

5-
Foundry consists of:
5+
---
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+
## Features
118

12-
## Documentation
9+
- **Transparent Proxy** — Transparent proxy pattern (`ERC1967` compatible)
10+
- **Proxy Admin** — Upgrade proxies securely using minimal admin logic
11+
- **Factory Deployment** — Deploy proxies via `CREATE` and `CREATE2`
12+
- **Slot-Based Tracking** — No mappings, storage traced via keccak256 seeds
13+
- **Modular Design** — Components can be used independently or via the factory
1314

14-
https://book.getfoundry.sh/
15+
---
1516

16-
## Usage
17+
## Contracts Overview
1718

18-
### Build
19+
| Contract | Description |
20+
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
21+
| **ForgeProxy** | The core proxy contract that delegates calls to implementation contracts. Features assembly-optimized routing and automatic admin deployment. |
22+
| **ForgeProxyAdmin** | Ultra-lightweight admin contract for managing proxy upgrades. Automatically deployed per proxy with minimal overhead, enabling isolated upgrade control. |
23+
| **ProxyForge** | The central hub for proxy deployment and management. Provides multiple deployment strategies via factory methods, including deterministic and non-deterministic paths. |
1924

20-
```shell
21-
$ forge build
22-
```
25+
---
2326

24-
### Test
27+
## API Reference
2528

26-
```shell
27-
$ forge test
28-
```
29+
### Deployment Flow
30+
31+
1. Call `deploy()` or `deployAndCall()` on `ProxyForge`.
32+
2. A `ForgeProxy` is deployed with the specified implementation and (optionally) initialized via delegatecall.
33+
3. A `ForgeProxyAdmin` is auto-deployed and linked to the proxy.
34+
4. Proxy ownership, admin, and implementation are tracked via factory-local slot logic.
35+
36+
### Usage Snippet
37+
38+
```solidity
39+
// Deploy via CREATE without initialization
40+
address proxy = proxyForge.deploy(implementation, owner);
41+
42+
// Deploy via CREATE and initialize in one tx
43+
address proxy = proxyForge.deployAndCall(implementation, owner, data);
44+
45+
// Deploy deterministically via CREATE2 without initialization
46+
address proxy = proxyForge.deployDeterministic(implementation, owner, salt);
2947
30-
### Format
48+
// Deploy deterministically via CREATE2 and initialize in one tx
49+
address proxy = proxyForge.deployDeterministicAndCall(implementation, owner, salt, data);
3150
32-
```shell
33-
$ forge fmt
51+
// Upgrade existing proxy
52+
proxyForge.upgrade(proxy, implementation);
53+
54+
// Upgrade existing proxy with initialization
55+
proxyForge.upgradeAndCall(proxy, implementation, data);
3456
```
3557

36-
### Gas Snapshots
58+
### Deployment Functions
3759

38-
```shell
39-
$ forge snapshot
60+
```solidity
61+
function deploy(address implementation, address owner) external payable returns (address proxy);
62+
function deployAndCall(address implementation, address owner, bytes calldata data) external payable returns (address proxy);
63+
function deployDeterministic(address implementation, address owner, bytes32 salt) external payable returns (address proxy);
64+
function deployDeterministicAndCall(address implementation, address owner, bytes32 salt, bytes calldata data) external payable returns (address proxy);
4065
```
4166

42-
### Anvil
67+
### Management Functions
4368

44-
```shell
45-
$ anvil
69+
```solidity
70+
function upgrade(address proxy, address implementation) external payable;
71+
function upgradeAndCall(address proxy, address implementation, bytes calldata data) external payable;
72+
function setProxyOwner(address proxy, address owner) external payable;
4673
```
4774

48-
### Deploy
75+
### View Functions
76+
77+
```solidity
78+
function getProxyOwner(address proxy) external view returns (address owner);
79+
function getProxyAdmin(address proxy) external view returns (address admin);
80+
function getProxyImplementation(address proxy) external view returns (address implementation);
4981
50-
```shell
51-
$ forge script script/Counter.s.sol:CounterScript --rpc-url <your_rpc_url> --private-key <your_private_key>
82+
function computeProxyAddress(address implementation, bytes32 salt, bytes calldata data) external view returns (address proxy);
83+
function computeProxyAddress(uint256 nonce) external view returns (address proxy);
84+
function computeProxyAdminAddress(address proxy) external view returns (address admin);
5285
```
5386

54-
### Cast
87+
### Events
5588

56-
```shell
57-
$ cast <subcommand>
89+
```solidity
90+
event ProxyDeployed(address indexed proxy, address indexed owner, bytes32 indexed salt);
91+
event ProxyUpgraded(address indexed proxy, address indexed implementation);
92+
event ProxyAdminChanged(address indexed proxy, address indexed admin);
93+
event ProxyImplementationChanged(address indexed proxy, address indexed implementation);
94+
event ProxyOwnerChanged(address indexed proxy, address indexed owner);
5895
```
5996

60-
### Help
97+
---
98+
99+
## Testing
100+
101+
This project includes a Foundry-based test suite that verifies:
102+
103+
- Deployment paths (`CREATE`, `CREATE2`)
104+
- Admin upgrade controls
105+
- Proxy delegatecall correctness
106+
- Storage slot consistency
107+
- Revert conditions and unauthorized access
108+
109+
Run tests with:
110+
111+
```bash
112+
# Run all tests
113+
forge test
61114

62-
```shell
63-
$ forge --help
64-
$ anvil --help
65-
$ cast --help
115+
# Run with detailed logs
116+
forge test -vvv
117+
118+
# Run with gas reporting
119+
forge test --gas-report
120+
121+
# Run specific test
122+
forge test --match-path test/ProxyForge.fuzz.t.sol
66123
```
124+
125+
---
126+
127+
## Deployment
128+
129+
**ForgeProxy** is deployed on the following chains:
130+
131+
| Network | Chain ID | Address |
132+
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
133+
| Sepolia | 11155111 | [0x5bbbb378546a9b1dB3d6a2FaCa37E3B93dBB03b9](https://sepolia.etherscan.io/address/0x5bbbb378546a9b1dB3d6a2FaCa37E3B93dBB03b9) |
134+
| Arbitrum Sepolia | 421614 | [0x5bbbb378546a9b1dB3d6a2FaCa37E3B93dBB03b9](https://sepolia.arbiscan.io/address/0x5bbbb378546a9b1dB3d6a2FaCa37E3B93dBB03b9) |
135+
| Base Sepolia | 84532 | [0x5bbbb378546a9b1dB3d6a2FaCa37E3B93dBB03b9](https://sepolia.basescan.org/address/0x5bbbb378546a9b1dB3d6a2FaCa37E3B93dBB03b9) |
136+
137+
---
138+
139+
## Acknowledgements
140+
141+
Inspired by:
142+
143+
- [OpenZeppelin TransparentUpgradeableProxy](https://github.com/OpenZeppelin/openzeppelin-contracts)
144+
- [Solady](https://github.com/Vectorized/solady)
145+
146+
---
147+
148+
## Author
149+
150+
- [@fomoweth](https://github.com/fomoweth)

0 commit comments

Comments
 (0)