Merge pull request #799 from Agoric/newcoreeval

Documentation for the CoreEval feature

main/.vuepress/config.js

@@ -149,6 +149,17 @@ module.exports = {
             '/guides/zoe/price-authority',
           ],
         },
+        {
+          title: 'Injecting Code to Agoric Testnet',
+          path: '/guides/coreeval/',
+          collapsible: false,
+          children: [
+            '/guides/coreeval/',
+            '/guides/coreeval/permissions',
+            '/guides/coreeval/proposal',
+            '/guides/coreeval/local-testnet',
+          ],
+        },        
         {
           title: 'Example Zoe Contracts',
           path: '/guides/zoe/contracts/',

main/.vuepress/themeConfig/nav.js

@@ -61,6 +61,11 @@ module.exports = [
       link: '/guides/zoe/'
       },
       {
+      text: 'Injecting Code to Agoric Testnet',
+      ariaLabel: 'Coreeval',
+      link: '/guides/coreeval/'
+      },      
+      {
       text: 'Example Zoe Contracts',
       ariaLabel: 'Example Zoe Contracts',
       link: '/guides/zoe/contracts/'

main/guides/coreeval/README.md

@@ -0,0 +1,12 @@
+# Injecting Code to Agoric Testnet
+
+Agoric facilitates safely injecting code to the Agoric testnet, usually for the purpose of running a contract and modifying it based on the result of a governance vote. To do so, we submit a proposal using cosmos-sdk level API ([swingset.CoreEval](https://community.agoric.com/t/blder-dao-governance-using-arbitrary-code-injection-swingset-coreeval/99)). If the proposal passes its governance vote, its JavaScript code is run with ocaps extracted using the proposal's declared capabilities, which the code can combine to perform privileged tasks.
+
+To do this, do the following:
+
+1. [Declare the capabilities that the proposal will require](./permissions.md).
+2. [Code the proposal itself](./proposal.md).
+3. [Deploy the proposal to a local testnet](./local-testnet.md).
+
+
+

main/guides/coreeval/local-testnet.md

@@ -0,0 +1,45 @@
+# Deploy a Governance Proposal to a Local Testnet
+
+To create, start, and deploy an Agoric governance proposal to a local Agoric Testnet, do the following:
+
+1. If you're using a Mac, ensure that you have [Xcode](https://apps.apple.com/us/app/xcode/id497799835) installed.
+2. Create a project folder that will allow you to run a local blockchain:
+
+	```jsx
+	agoric init <The name of your project>
+	```
+
+    For example, if you wanted to run your local blockchain from a folder named "Demo", you'd run this command:
+
+    ```jsx
+    agoric init Demo
+    ```
+
+	**Note:** Your project folder should *not* be located within your local clone of the agoric SDK.
+
+3. Install additional dependencies by entering your project folder and running the following command.
+
+	```jsx
+    cd <Name of your project (e.g., Demo)>
+    agoric install
+    ```
+
+4.  Start the chain by running the following command. (**Note:** You should still be located within your project folder.)
+
+	```jsx
+	agoric start local-chain --verbose --reset
+	```
+
+5. Wait for the first block to be produced.
+6. Open a second terminal.
+7. Within the second terminal, navigate to `<agoric-sdk>/bin` and submit the governance proposal by running the following command. (Make sure to enter "y" when asked to confirm the transaction.)
+
+	```
+    ./agd --chain-id=agoriclocal --title=<Insert your own title> --description=<Insert your description> --home=<PATH to your project folder>/_agstate/keys --keyring-backend=test --from=provision tx gov submit-proposal swingset-core-eval <PATH to permissions> <PATH to proposal>
+	```
+
+    For example, to deploy the PSM proposal referenced in the previous topics, run the following:
+
+    ```
+	./agd --chain-id=agoriclocal --title=<Insert your own title> --description=<Insert your description> --home=<PATH to your project folder>/_agstate/keys --keyring-backend=test --from=provision tx gov submit-proposal swingset-core-eval ../packages/inter-protocol/test/psm/gov-add-psm-permit.json ../packages/inter-protocol/test/psm/gov-add-psm.js
+    ```

main/guides/coreeval/permissions.md

@@ -0,0 +1,96 @@
+# Declaring Required Capabilities
+
+Write a json file declaring the capabilities that the proposal will need. For example,
+[gov-add-psm-permit.json](https://github.com/Agoric/agoric-sdk/blob/master/packages/inter-protocol/test/psm/gov-add-psm-permit.json) 
+declares capabilities needed to start a new PSM contract. Note that capabilities are declared using
+their name as a property along with any truthy value. For example,`"bankManager": true` and 
+`"bankManager": 'hello'` are equivalent; they both set the `bankManager` capability.
+
+::: details Show example permissions file
+```
+{
+  "consume": {
+    "agoricNamesAdmin": true,
+    "bankManager": true,
+    "board": true,
+    "chainStorage": true,
+    "zoe": "zoe",
+    "feeMintAccess": "zoe",
+    "economicCommitteeCreatorFacet": "economicCommittee",
+    "econCharterKit": true,
+    "provisionPoolStartResult": true,
+    "psmKit": true,
+    "chainTimerService": "timer"
+  },
+  "produce": {
+    "testFirstAnchorKit": true
+  },
+  "installation": {
+    "consume": {
+      "contractGovernor": true,
+      "psm": true,
+      "mintHolder": true
+    }
+  },
+  "instance": {
+    "consume": {
+      "economicCommittee": true
+    }
+  },
+  "issuer": {
+    "produce": {
+      "DAI": true
+    },
+    "consume": {
+      "DAI": true
+    }
+  },
+  "brand": {
+    "consume": {
+      "DAI": true,
+      "IST": true
+    },
+    "produce": {
+      "DAI": true
+    }
+  }
+}
+```
+:::
+
+## Top Level Consume Section
+
+In this section you need to set all the permissions that your contract will need to be able to use
+(i.e., "consume"). Some of the listed permissions in the example PSM permission file above are of
+general interest to most contracts, while others are more specific to the PSM contract.
+
+* **agoricNamesAdmin**: Grants write access to the Agoric name service. This permission is somewhat specific to the PSM contract.
+* **bankManager**: Grants access to bank-related functionality within ERTP, allowing the contract to manipulate nearly all Cosmos assets in the chain. Because this capability is very powerful, this permission should only be granted to contracts that absolutely need it.
+* **board**: Grants write access to the [board name service](/guides/wallet/README.md#the-agoric-board).
+* **chainStorage**: Grants write access to the chain storage node, which is required when running `agd query` commands. Thus, most contracts will need access to this.
+* **zoe**: When this permission is set, it grants access to the Zoe framework. All contracts will need access to this.
+* **feeMintAccess**: When this permission is set, the contract will be able to create digital assets. Only contracts that mint privileged Agoric digital assets (i.e., not the unprivileged **[zcf.makeZCFMint()](/reference/zoe-api/zoe-contract-facet.md#zcf-makezcfmint-keyword-assetkind-displayinfo)**) will need access to this.
+* **economicCommitteeCreatorFacet**, **econCharterKit**, **provisionPoolStartResult**: These 3 permissions are required by governed contracts.
+* **chainTimerService**: When this permission is set, it grants access to the *chainTimerService*. All governed contracts need access to this so they know when a vote is complete.
+
+## Top Level Produce Section
+
+Specifies what, if anything, the contract produces. For example, the example PSM contract 
+produces *testFirstAnchorKit* which is used for testing purposes.
+
+## Installation Section 
+
+Specifies what well-known installations the contract requires. At a minimum, the contract itself should
+be listed as an installation. Governed contracts should include a *contractGovernor* installation.
+
+## Instance Section
+
+Specifies what instances, if any, the contract produces or consumes.
+
+## Issuer Section
+
+Specifies what **[Issuers](/reference/ertp-api/issuer.md)**, if any, the contract produces or consumes.
+
+## Brand Section
+
+Specifies what **[Brands](/reference/ertp-api/brand.md)**, if any, the contract produces or consumes.

main/guides/coreeval/proposal.md

@@ -0,0 +1,59 @@
+# Code the Proposal
+
+You will need to write a proposal script that runs the contract, and possibly does additional things
+depending on your needs. (Usually these additional things will be dependent on a governance vote.) For
+example, [gov-add-psm.js](https://github.com/Agoric/agoric-sdk/blob/master/packages/inter-protocol/test/psm/gov-add-psm.js) 
+is a proposal Agoric created for the PSM contract. It executes in an environment with globals such as
+**[E](../js-programming/eventual-send.md)** and **[Far](../js-programming/far.md#far-api)** provided.
+
+::: details Show example proposal
+```jsx
+/* global startPSM */
+// @ts-nocheck
+
+/**
+ * @typedef {{
+ *   denom: string,
+ *   keyword?: string,
+ *   proposedName?: string,
+ *   decimalPlaces?: number
+ * }} AnchorOptions
+ */
+
+/** @type {AnchorOptions} */
+const DAI = {
+  keyword: 'DAI',
+  decimalPlaces: 18,
+  denom: 'ibc/toydai',
+  proposedName: 'Maker DAI',
+};
+
+const config = {
+  options: { anchorOptions: DAI },
+  WantMintedFeeBP: 1n,
+  GiveMintedFeeBP: 3n,
+  MINT_LIMIT: 0n,
+};
+
+/** @param {unknown} permittedPowers see gov-add-psm-permit.json */
+const main = async permittedPowers => {
+  console.log('starting PSM:', DAI);
+  const {
+    consume: { feeMintAccess: _, ...restC },
+    ...restP
+  } = permittedPowers;
+  const noMinting = { consume: restC, ...restP };
+  await Promise.all([
+    startPSM.makeAnchorAsset(noMinting, {
+      options: { anchorOptions: DAI },
+    }),
+    startPSM.startPSM(permittedPowers, config),
+  ]);
+  console.log('started PSM:', config);
+};
+
+// "export" from script
+main;
+
+```
+:::