Document how voters can currently safely validate a governance proposal to instantiate a contract

[kriskowal]

What is the Problem Being Solved?

We currently lack documentation for the workflow for proposing and validating governance proposals that would, for example, upgrade a contract.

Description of the Design

By way of a preliminary sketch:

To propose a new contract installation, one would need to

• construct a bundle using @endo/bundle-source’s bundle-source command
• use agd swingset install-bundle to send the source to the chain.
• The bundle contains a hash, which can be extracted via jq -r .endoZipBase64Sha512 bundle.json.
• The governance proposal must contain a bootstrap script that arranges for E(zoe).install({ endoZipBase64Sha512 })` to be called and instructions for how to find the sources for that hash and safely verify the integrity of the sources and its third-party dependencies and reproducing the bundle with the same hash.

To verify a governance proposal that includes a E(zoe).install({ endoZipBase64Sha512 }) command in a bootstrap script:

• Skeptically follow the instructions in the governance proposal, which should be of the form:
• In a bomb-proof Docker container from which there is no escape,
• Download the bundle from the location specified in the governance proposal,
• Use a yet-to-be-written bundle auditing tool, which would produce the hash and verify the internal integrity of the bundle, then extract the original sources into the file system for manual inspection. The extracted bundle is not executable.

and/or verify the bundle is consistent with the sources of the contract from a repository and hash:

• Download the sources and their dependencies. These should be captured somewhere in a zip file and auditors should not be instructed to use yarn or npm, since these provide an opportunity for the attacker to run arbitrary code.
• Install the Agoric SDK
• Use @endo/bundle-source’s bundle-source CLI to generate a bundle.
• Extract and compare the hashes of the generated bundle.
• Proceed to review the sources only if the hashes match.

Security Considerations

Validating a contract currently requires obtaining the sources at a particular hash, installing their dependencies, reconstructing the bundle, matching the generated hash, then inspecting the contract proper for malfeasance. Improperly installing the dependencies of an arbitrary application can empower an attacker to run arbitrary code with the authority of the user.

Test Plan

[dckc]

a 1-off attempt: game1-bundles.mk

https://devnet.agoric.explorers.guru/proposal/9 on agoricdev-20

[dckc]

Case studies:

• 2023-09-23 #49 Upgrade Smart Wallet to support NFTs
  • Based on agoric-upgrade-11wf e669bb1
  • See also Upgrade Smart Wallet to support NFTs discussion.
• 2023-10-01 #53 KREAd-rc1 to Mainnet
  • discussion: #53 Add smart-contract for KREAd dapp - Governance / CoreEval - Agoric Community Forum
  • release: https://github.com/Kryha/KREAd/releases/tag/KREAd-rc1
• 2024-09-04 #76 Replace Auctioneer and Upgrade Vaults
  • based on agoric-upgrade-16av-rc4

See also a web-based prototype tool:

• Bundle Explorer (prototype) shows modules, sizes from InstallBundle tx #8416

[dckc]

Testnet case studies:

• 2024-09-30 emerynet #75 Start orca.contract v0.1.0-beta.2 w/chainDetails
  • 2024-09-30 v0.1.0-beta.2 of dapp-orchestration-basics
• (only deployed to chains that are now defunct)
  • 2023-11-16 v0.1.1-alpha2 of gimix