Common Deployment Pitfalls
When working with Zeus deployments, there are several common pitfalls that teams can encounter. This guide helps you identify and avoid these issues.
Forge Version Mismatches
One of the most common issues in multi-developer teams is using different Forge versions.
Problem
Different Forge versions can produce slightly different bytecode for the same source code, leading to verification failures when team members get different results.
Solution
Always ensure your entire team is using the same version of Forge:
# Check your current Forge version
forge --version
# If needed, install a specific version
foundryup -v 0.2.0 # Replace with your team's agreed version
Add the Forge version to your project documentation and consider adding a check in your CI/CD pipeline to verify the correct version is being used.
Working on Different Git Commits
Problem
When team members work from different commits, they may end up with different contract code, leading to discrepancies in bytecode and deployment behavior.
Solution
Always ensure everyone is working from the same commit when performing deployments:
# Pull the latest changes and checkout the agreed-upon commit
git fetch
git checkout <specific-commit-hash>
# Verify the current commit
git rev-parse HEAD
For critical deployments, it's good practice to tag the specific commit you're deploying from:
git tag -a deployment-v1.0.0 -m "Production deployment v1.0.0"
git push origin deployment-v1.0.0
Inconsistent Build Environment
Problem
Stale build artifacts or outdated dependencies can lead to unexpected behavior.
Solution
Always start with a clean build environment before any deployment:
# Update submodules
git submodule update --init --recursive
# Clean build artifacts
forge clean
# Rebuild contracts
forge build
Adding this as a pre-deployment checklist item helps ensure everyone has a consistent build environment.
Overlooking Dependency Changes
Problem
Changes in dependencies (like OpenZeppelin contracts) can affect your deployment.
Solution
Lock your dependencies to specific versions and commits in your Foundry configuration:
# foundry.toml or remappings.txt
@openzeppelin/contracts=lib/openzeppelin-contracts/contracts
And specify exact commit hashes in your .gitmodules
file:
[submodule "lib/openzeppelin-contracts"]
path = lib/openzeppelin-contracts
url = https://github.com/OpenZeppelin/openzeppelin-contracts
branch = v4.8.0
Zeus Environment Configuration Issues
Problem
Using incorrect or inconsistent environment configurations across team members.
Solution
Before starting a deployment, verify the environment configuration:
# View the current environment configuration
zeus env show <env-name>
# If needed, update environment parameters
zeus deploy run --upgrade your-setup-script --env <env-name>
Document all environment parameters and their expected values in your project documentation.
Multisig Coordination Failures
Problem
Inadequate coordination among multisig signers can delay deployments or lead to incomplete transactions.
Solution
- Schedule deployment windows when all required signers are available
- Use Zeus to prepare transactions in advance:
zeus deploy run --upgrade <deployment> --env <env>
- Share the deployment plan with all signers before execution
- Establish clear communication channels during the deployment process
Pre-Deployment Checklist
Before any important deployment, run through this checklist:
# Zeus Deployment Pre-Flight Checklist
## Environment
- [ ] Forge version matches team standard: `forge --version` = v0.x.y
- [ ] All team members on same commit: `git rev-parse HEAD` = 0xabcdef...
- [ ] Clean build environment: `git submodule update --recursive && forge clean && forge build`
## Configuration
- [ ] Environment parameters verified: `zeus env show <env>`
- [ ] Required signers confirmed and available
- [ ] Network configuration verified (RPC URLs, chain IDs)
## Contracts
- [ ] All contract tests passing: `forge test`
- [ ] Contract verification process documented
- [ ] Deployment sequence documented and understood by team
## Recovery
- [ ] Rollback procedure defined
- [ ] Emergency contacts list prepared
- [ ] Test environment validated with identical deployment steps
Following these practices will help your team avoid common pitfalls and ensure smoother deployments with Zeus.