Skip to content

Commit dbdae4d

Browse files
mattstammattstam
authored
docs(contracts): atomic deployment instructions (#201)
1 parent 03535d2 commit dbdae4d

2 files changed

Lines changed: 156 additions & 133 deletions

File tree

‎contracts/DEPLOYMENT.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Deployment
2+
3+
This document contains instructions on deploying the contracts to a specific chain.
4+
5+
## Setup
6+
7+
First make a copy of the [.env.example](./.env.example):
8+
9+
```sh
10+
cp .env.example .env
11+
```
12+
13+
And then fill in your `.env` file with all the variables needed for configuring the contracts.
14+
15+
Also, set these terminal parameters needed to deploy to a specific chain:
16+
17+
```sh
18+
export PRIVATE_KEY=
19+
export ETH_RPC_URL=
20+
export ETHERSCAN_API_KEY=
21+
```
22+
23+
Then add a `{CHAIN_ID}.json` file in the [deployments](./deployments) directory for the chain you are deploying to. This command will automatically create it with an empty JSON `{}` if it doesn't exist:
24+
25+
```sh
26+
CHAIN_ID=$(cast chain-id --rpc-url $ETH_RPC_URL); mkdir -p ./deployments && [ -f "./deployments/${CHAIN_ID}.json" ] || echo '{}' > "./deployments/${CHAIN_ID}.json"
27+
```
28+
29+
Then you should add the `VKEY` and `GENESIS_STATE_ROOT` to the `{CHAIN_ID}.json` file:
30+
31+
```json
32+
{
33+
"VKEY": "0x00379594d327723819f32e812d869de681100f77f766869b8d672072ab73e27c",
34+
"GENESIS_STATE_ROOT": "0x7f1150ec996e291947d4a9a30a49155b5f042042f841f25db4d41da04cef63f4"
35+
}
36+
```
37+
38+
Ensure these match the actual vkey and genesis state root for the Rust vApp program.
39+
40+
Note: the production version of these contracts were deployed using foundry [v1.3.0](https://github.com/foundry-rs/foundry/releases/tag/v1.3.0).
41+
42+
For the below commands, you can append `--verify --verifier etherscan --etherscan-api-key $ETHERSCAN_API_KEY` to the above commands to automatically verify the contracts on Etherscan.
43+
44+
### Pre-deployed contracts
45+
46+
Also fill out `{CHAIN_ID}.json` with any pre-deployed contracts. For example, if there is an existing `PROVE` and `VERIFIER` those keys would be filled:
47+
48+
```json
49+
{
50+
"VKEY": "0x00379594d327723819f32e812d869de681100f77f766869b8d672072ab73e27c",
51+
"GENESIS_STATE_ROOT": "0x7f1150ec996e291947d4a9a30a49155b5f042042f841f25db4d41da04cef63f4",
52+
"PROVE": "0x6BEF15D938d4E72056AC92Ea4bDD0D76B1C4ad29",
53+
"VERIFIER": "0x397A5f7f3dBd538f23DE225B51f532c34448dA9B"
54+
}
55+
```
56+
57+
The scripts and steps below make the assumption that the `PROVE` and `VERIFIER` contracts are already deployed.
58+
59+
## Deploy
60+
61+
### Bulk atomic deployment (Production)
62+
63+
To avoid frontrunning the `initialize` functions, **must** use the `AtomicDeployer` contract to deploy and initialize the contracts atomically.
64+
65+
Deploy all contracts atomically at once:
66+
67+
```sh
68+
FOUNDRY_PROFILE=deploy forge script AllAtomicScript --private-key $PRIVATE_KEY --broadcast --rpc-url $ETH_RPC_URL
69+
```
70+
71+
### Bulk deployment (Testing)
72+
73+
Deploy all contracts at once:
74+
75+
```sh
76+
FOUNDRY_PROFILE=deploy forge script AllScript --private-key $PRIVATE_KEY --broadcast --rpc-url $ETH_RPC_URL
77+
```
78+
79+
### Individual deployment (Testing)
80+
81+
Deploy the SuccinctStaking contract:
82+
83+
```sh
84+
FOUNDRY_PROFILE=deploy forge script SuccinctStakingScript --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL --verify --verifier etherscan --etherscan-api-key $ETHERSCAN_API_KEY
85+
```
86+
87+
This DOES NOT initalize the contract - this will be done in a later step once references to other contracts are available.
88+
89+
Deploy the $iPROVE contract (assumes $PROVE is already deployed):
90+
91+
```sh
92+
FOUNDRY_PROFILE=deploy forge script IntermediateSuccinctScript --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL --verify --verifier etherscan --etherscan-api-key $ETHERSCAN_API_KEY
93+
```
94+
95+
Deploy the SuccinctGovernor contract:
96+
97+
```sh
98+
FOUNDRY_PROFILE=deploy forge script SuccinctGovernorScript --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL --verify --verifier etherscan --etherscan-api-key $ETHERSCAN_API_KEY
99+
```
100+
101+
Deploy the SuccinctVApp implementation and proxy contracts (assumes verifier is already deployed):
102+
103+
```sh
104+
FOUNDRY_PROFILE=deploy forge script SuccinctVAppScript --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL --verify --verifier etherscan --etherscan-api-key $ETHERSCAN_API_KEY
105+
```
106+
107+
If the SP1VerifierGateway is not already deployed, follow steps in [sp1-contracts](https://github.com/succinctlabs/sp1-contracts) to deploy it and fill out the address in your `{CHAIN_ID}.json` file.
108+
109+
Initalize the SuccinctStaking contract:
110+
111+
```sh
112+
FOUNDRY_PROFILE=deploy forge script SuccinctStakingScript --sig "initialize()" --private-key $PRIVATE_KEY --broadcast --rpc-url $ETH_RPC_URL
113+
```
114+
115+
### Post-deployment
116+
117+
At this point, you should have all the predicted addresses in your `{CHAIN_ID}.json` file. You should now re-run these with the `--broadcast` flag to actually deploy the contracts.
118+
119+
Run the integrity check:
120+
121+
```sh
122+
FOUNDRY_PROFILE=deploy forge script PostDeploymentScript --rpc-url $ETH_RPC_URL
123+
```
124+
125+
If that passes without reverting, the contracts have been successfully deployed and initalized. The addresses are in the `{CHAIN_ID}.json` file.
126+
127+
## Verification
128+
129+
If any of the contracts failed to verify on Etherscan, you can manually verify them by copying the the flatten source code and uploading it to Etherscan.
130+
131+
To do this, go to the address on Etherscan and click "Verify Contract". Choose:
132+
133+
* Compiler: "Solidity (Single File)"
134+
* Compiler Version: "0.8.28"
135+
* License: "MIT"
136+
137+
Then flatten the contract you're verifying, for example the SuccinctStaking contract:
138+
139+
```sh
140+
forge flatten src/SuccinctStaking.sol
141+
```
142+
143+
Copy the output into the "Contract Code" field.
144+
145+
Then enter the compiler settings from the [foundry.toml](./foundry.toml) file's `[profile.deploy]` section.
146+
147+
If any constructor arguements were used but not shown in the "Constructor Arguments" field, use `cast abi-encode` with the appropriate signature to encode them, for example:
148+
149+
```sh
150+
cast abi-encode "constructor(address)" 0xbD74E9B0Dcb0317E26505CA93757c29d564B533B
151+
```
152+
153+
strip the `0x` prefix from this output and paste it into the "Constructor Arguments" field.

‎contracts/README.md‎

Lines changed: 3 additions & 133 deletions
Original file line numberDiff line numberDiff line change
@@ -38,138 +38,8 @@ FOUNDRY_PROFILE=deploy forge snapshot --no-match-test "Fuzz"
3838

3939
## Deployment
4040

41-
### Setup
41+
Deployment guide is available in [DEPLOYMENT.md](./DEPLOYMENT.md).
4242

43-
First make a copy of the [.env.example](./.env.example):
43+
## Operations
4444

45-
```sh
46-
cp .env.example .env
47-
```
48-
49-
And then fill in your `.env` file with all the variables needed for configuring the contracts.
50-
51-
Also, set these terminal parameters needed to deploy to a specific chain:
52-
53-
```sh
54-
export PRIVATE_KEY=
55-
export ETH_RPC_URL=
56-
export ETHERSCAN_API_KEY=
57-
```
58-
59-
Then add a `{CHAIN_ID}.json` file in the [deployments](./deployments) directory for the chain you are deploying to. This command will automatically create it with an empty JSON `{}` if it doesn't exist:
60-
61-
```sh
62-
CHAIN_ID=$(cast chain-id --rpc-url $ETH_RPC_URL); mkdir -p ./deployments && [ -f "./deployments/${CHAIN_ID}.json" ] || echo '{}' > "./deployments/${CHAIN_ID}.json"
63-
```
64-
65-
Then you should add the `VKEY` and `GENESIS_STATE_ROOT` to the `{CHAIN_ID}.json` file:
66-
67-
```json
68-
{
69-
"VKEY": "0x00379594d327723819f32e812d869de681100f77f766869b8d672072ab73e27c",
70-
"GENESIS_STATE_ROOT": "0x7f1150ec996e291947d4a9a30a49155b5f042042f841f25db4d41da04cef63f4"
71-
}
72-
```
73-
74-
Ensure these match the actual vkey and genesis state root for the Rust vApp program.
75-
76-
Note: the production version of these contracts were deployed using foundry [v1.3.0](https://github.com/foundry-rs/foundry/releases/tag/v1.3.0).
77-
78-
### Bulk deployment
79-
80-
This should generally only be used for testing.
81-
82-
Deploy all contracts at once:
83-
84-
```sh
85-
FOUNDRY_PROFILE=deploy forge script AllScript --private-key $PRIVATE_KEY --broadcast --rpc-url $ETH_RPC_URL
86-
```
87-
88-
You can append `--verify --verifier etherscan --etherscan-api-key $ETHERSCAN_API_KEY` to the above commands to verify the contracts on Etherscan.
89-
90-
### Individual deployment
91-
92-
Instead of deploying all contracts at once, it's recommended to deploy each contract individually for production deployments.
93-
94-
#### Pre-deployed contracts
95-
96-
Fill out `{CHAIN_ID}.json` with any pre-deployed contracts. For example, if there is an existing `PROVE` and `VERIFIER` those keys would be filled:
97-
98-
```json
99-
{
100-
"VKEY": "0x00379594d327723819f32e812d869de681100f77f766869b8d672072ab73e27c",
101-
"GENESIS_STATE_ROOT": "0x7f1150ec996e291947d4a9a30a49155b5f042042f841f25db4d41da04cef63f4",
102-
"PROVE": "0x6BEF15D938d4E72056AC92Ea4bDD0D76B1C4ad29",
103-
"VERIFIER": "0x397A5f7f3dBd538f23DE225B51f532c34448dA9B"
104-
}
105-
```
106-
107-
#### Deploy each contract
108-
109-
The broadcast flag is intentially removed from these scripts so that the predicted addresses are written to the `{CHAIN_ID}.json` file without actually deploying them. This is so that `initialize` functions can be atomically called to avoid [frontrunning attacks](https://dedaub.com/blog/the-cpimp-attack-an-insanely-far-reaching-vulnerability-successfully-mitigated/) on the `initialize` function.
110-
111-
Deploy the SuccinctStaking contract:
112-
113-
```sh
114-
FOUNDRY_PROFILE=deploy forge script SuccinctStakingScript --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL --verify --verifier etherscan --etherscan-api-key $ETHERSCAN_API_KEY
115-
```
116-
117-
This DOES NOT initalize the contract - this will be done in a later step once references to other contracts are available.
118-
119-
Deploy the $iPROVE contract (assumes $PROVE is already deployed):
120-
121-
```sh
122-
FOUNDRY_PROFILE=deploy forge script IntermediateSuccinctScript --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL --verify --verifier etherscan --etherscan-api-key $ETHERSCAN_API_KEY
123-
```
124-
125-
Deploy the SuccinctGovernor contract:
126-
127-
```sh
128-
FOUNDRY_PROFILE=deploy forge script SuccinctGovernorScript --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL --verify --verifier etherscan --etherscan-api-key $ETHERSCAN_API_KEY
129-
```
130-
131-
Deploy the SuccinctVApp implementation and proxy contracts (assumes verifier is already deployed):
132-
133-
```sh
134-
FOUNDRY_PROFILE=deploy forge script SuccinctVAppScript --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL --verify --verifier etherscan --etherscan-api-key $ETHERSCAN_API_KEY
135-
```
136-
137-
If the SP1VerifierGateway is not already deployed, follow steps in [sp1-contracts](https://github.com/succinctlabs/sp1-contracts) to deploy it and fill out the address in your `{CHAIN_ID}.json` file.
138-
139-
At this point, you should have all the predicted addresses in your `{CHAIN_ID}.json` file. You should now re-run these with the `--broadcast` flag to actually deploy the contracts.
140-
141-
Run the integrity check:
142-
143-
```sh
144-
FOUNDRY_PROFILE=deploy forge script PostDeploymentScript --rpc-url $ETH_RPC_URL
145-
```
146-
147-
If that passes without reverting, the contracts have been successfully deployed and initalized. The addresses are in the `{CHAIN_ID}.json` file.
148-
149-
## Verification
150-
151-
If any of the contracts failed to verify on Etherscan, you can manually verify them by copying the the flatten source code and uploading it to Etherscan.
152-
153-
To do this, go to the address on Etherscan and click "Verify Contract". Choose:
154-
155-
* Compiler: "Solidity (Single File)"
156-
* Compiler Version: "0.8.28"
157-
* License: "MIT"
158-
159-
Then flatten the contract you're verifying, for example the SuccinctStaking contract:
160-
161-
```sh
162-
forge flatten src/SuccinctStaking.sol
163-
```
164-
165-
Copy the output into the "Contract Code" field.
166-
167-
Then enter the compiler settings from the [foundry.toml](./foundry.toml) file's `[profile.deploy]` section.
168-
169-
If any constructor arguements were used but not shown in the "Constructor Arguments" field, use `cast abi-encode` with the appropriate signature to encode them, for example:
170-
171-
```sh
172-
cast abi-encode "constructor(address)" 0xbD74E9B0Dcb0317E26505CA93757c29d564B533B
173-
```
174-
175-
strip the `0x` prefix from this output and paste it into the "Constructor Arguments" field.
45+
Operations guide is available in [OPERATIONS.md](./OPERATIONS.md).

0 commit comments

Comments
 (0)