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

kriskowal commented 2 years ago

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 commented 1 year ago

a 1-off attempt: game1-bundles.mk

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

dckc commented 1 year ago

Case studies:

2023-09-23 #49 Upgrade Smart Wallet to support NFTs
- Based on agoric-upgrade-11wf e669bb12f560d84f7fc017abda49d3dd6d5cee17
- 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

Agoric / agoric-sdk