Mainnet 2 Deployment Guide

[rowgraus]

Agoric OpCo wants to ensure the health of agoric-3 chain. To that end we assist with CoreEval proposals to the network.

The process is described in the Mainnet CoreEval Proposal runbook.

When you want to propose to the chain, make a copy of that and fill in the roles.

That document supersedes the previous checklist, shown below:

Old MN-2 Reference Partner Checklist

The purpose of this document is to capture a checklist of pre-launch requirements that reference partners launching new contracts should complete prior to deployment on the Agoric chain during Mainnet-2.

The checklist has items owned by Agoric OpCo as well as by the reference partner. It's divided into three sections:

1. Pre-launch preparation
2. OpCo Review
3. Deployment Readiness

Pre-Launch Preparation

Requirement	Description	Owner
Linting Rules	Task: Agoric OpCo has a set of preferred linting rules for partners to run. The partner contract & dapp should be free of linting errors. Purpose: Linting rules can either prevent or help to catch common errors that might impact correctness or robustness. Instructions: #8274	Partner
Full Contract Functionality Coverage in CI Coverage	Task: Ensure that your contract functionality is covered with automated testing and new changes are covered by Continuous Integration. Purpose: To ensure previously reviewed contract continues functioning properly after any changes are made	Partner
Contract level pause button	Task: Add a facility to the contract to allow rapidly disabling the processing of incoming transactions & timer wakeups. Purpose: Allows contract admin to rapidly pause/disable the contract if it is damaging chain availability or correctness. BLD Staker can disable a contract via a 3-day vote but this mechanism allows more rapid response. Instructions: How to add a contract level pause feature? · #8172	Partner
Upgrade test	Task: For contracts planned to be upgradable, add a null-upgrade test. Purpose: Verifies the contract is upgradable and has held enough state durably to continue to function post upgrade. If not performed prior to initial contract deployment, there might be unfixable bugs that prevent upgrade. Instructions: OpCo recommends writing a test of restarting the contract (“null upgrade”).An example of such a test can be found in: test-fluxAggregator-service-upgrade.js	Partner
Deployment Test	Task: Add a deployment test that exercises the core-eval that will be used to install & start the contract on chain. Purpose: This is an end-to-end test that exercises critical deployment functionality not easily tested via unit testing or simpler integration tests. Instructions: OpCo recommends extending the docker-upgrade tests that were used for MN-1b release. See How to do end-to-end test of permissioned deployment? · #8173	Partner
RPC rate limiting	Task: Dapps must make a maximum of 2 RPC calls every 1 second. Purpose: Avoid spamming RPC nodes and reducing their availability. Instructions: Maximum 2 requests per second to the RPC server (per issue)The @agoric/rpc library offers batchQuery and chainStorageWatcher modules. (example)	Partner
Deployment to public testnet	Task: Deploy your completed contract(s) to a public testnet (e.g., DevNet). Purpose: Demonstrate contract can be deployed and operates correctly outside of your local environment	Partner
Perf testing	Perform performance and stress testing on the smart contract deployed on our testnet. Build test tools and scripts to simulate high loads, monitor resource usage, and identify bottlenecks. Document results, including performance metrics, failure points, and recommendations for improvement. See also #9941	Partner
E2E Demo	Task: Demo your completed contract in its expected context to Agoric OpCo product and engineering. Demo should showcase completion of checklist items and include front end if a front end is required for contract use cases. Purpose: Exit criteria for entering OpCo review. Ensure full contract functionality and user flows are ready.	Partner

OpCo Review

Requirement	Description	Owner
Code review of contract code	Task: Code review the contract code which will be deployed to chain. Purpose: Audit to raise confidence that contract implements desired behavior, is upgradable, properly uses durability & virtualization, doesn’t have bugs like infinite loops. Instructions: OpCo engineers to arrange review with partner via direct communication channels.	OpCo
Code review of core-eval	Task: Code review the core-eval which will be used to deploy the contract. Purpose: This allows verification that the permissions asked for in the core-eval are necessary. This allows verification that the bundles being installed on chain are the bundles that have been reviewed. Instructions: OpCo engineers to arrange review with partner via direct communication channels.	OpCo
Security review of new transactions	Task: Collaborative review session where the purpose & shape of each new transaction is audited. Purpose: Ensure user-controlled flows are resilient against unexpected or malicious inputs, look for lack of input validation, particularly in areas where it could propagate and lead to consensus failures. Instructions: OpCo security team to schedule with partner via direct communication channels	Partner & OpCo
Resource measurement on testnet deployment	Task: Deploy with core-eval on a testnet and exercise core functionality in a stress like manner. Measure CPU, memory, & storage utilization. Purpose: Ensure contract will be well behaved before more advanced metering solves come in. Instructions: OpCo engineers to work with Partner to designate a test network & share a monitoring dashboard showing memory, CPU, storage usage, blocktime, etc. on that network. Partner performs a functional stress test and observes metrics with OpCo.	Partner & OpCo

Production Rollout

Requirement	Description	Owner
Community Posts	Task: Post to the Community Forums to give the BLD Staker community an overview of your application and clarity around the work done in above steps. Purpose BLD Stakers must vote to allow contract deployment. They require notice to understand what they are voting for.	Partner
EmeryNet Preparation	Task: Work with Agoric chain Validators in Discord to prepare for a deployment to EmeryNet. Agoric OpCo can help coordination. Purpose: EmeryNet is a production-like testnet and is the last step before Mainnet.	Partner & OpCo
Bundle Install Preparation	Task: Ensure you have prepared sufficient $IST to deploy your bundles to mainnet. Instructions: Use available tooling to estimate your bundle cost. To acquire IST, you can mint from Inter Protocol Vaults or PSMs or you can acquire it on a DEX like Osmosis. See docs for more information	Partner

[dckc]

Meanwhile: Community Engagement in Governance

Mainnet 2 Deployment is ultimately a BLD staker governance decision. Engaging the BLD staker community in preparation for an on-chain proposal is important. By way of example, see https://community.agoric.com/t/add-smart-contract-for-kread-dapp/483