From 79db198037c6909db645ad8365e39fa6cb1675b9 Mon Sep 17 00:00:00 2001 From: Mark Molina Date: Mon, 8 May 2023 11:59:54 -0700 Subject: [PATCH 01/17] Adding the new coreeval files --- main/guides/coreeval/local-testnet.md | 34 ++++++++++ main/guides/coreeval/permissions.md | 89 +++++++++++++++++++++++++++ main/guides/coreeval/proposal.md | 59 ++++++++++++++++++ 3 files changed, 182 insertions(+) create mode 100644 main/guides/coreeval/local-testnet.md create mode 100644 main/guides/coreeval/permissions.md create mode 100644 main/guides/coreeval/proposal.md diff --git a/main/guides/coreeval/local-testnet.md b/main/guides/coreeval/local-testnet.md new file mode 100644 index 000000000..c42754fd7 --- /dev/null +++ b/main/guides/coreeval/local-testnet.md @@ -0,0 +1,34 @@ +# Create a Local Testnet + +To create, start, and deploy an Agoric contract to a local Agoric Testnet, do the following: + + +1. Install *Go* if needed. + + ``` + brew install go + ``` +2. Navigate to `/packages/cosmic-swingset` and run `make`. +3. Prepare the chain and solo nodes. + + ```jsx + make scenario2-setup BASE_PORT=8000 NUM_SOLOS=0 + ``` +4. Start the chain. + + ```jsx + make scenario2-run-chain + ``` +5. Switch to another terminal and wait for the first block to be produced. +6. Navigate to `/bin` and start the client. + + ``` + agd --chain-id=agoricdev-17 tx gov submit-proposal swingset-core-eval + ``` + + For example, to deploy the PSM contract referenced in the previous topics, run the following: + + ``` + agd --chain-id=agoricdev-17 tx gov submit-proposal swingset-core-eval test/psm/gov-add-psm-permit.json test/psm/gov-add-psm.js + ``` +7. Adjust variables in `/packages/cosmic-swingset/Makefile` to point to the proposal and permissions you created earlier. diff --git a/main/guides/coreeval/permissions.md b/main/guides/coreeval/permissions.md new file mode 100644 index 000000000..25115c2a3 --- /dev/null +++ b/main/guides/coreeval/permissions.md @@ -0,0 +1,89 @@ +# Coding Permissions + +Write a json file with the permissions that the proposal will need. For example, [here](https://github.com/Agoric/agoric-sdk/blob/master/packages/inter-protocol/test/psm/gov-add-psm-permit.json) is the proposal Agoric created for the PSM contract: + + +::: 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 + } + } +} +``` +::: + +## 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 and Zoe. Most contracts will need access. +* **board**: Grants write access to the board name service. This permission is somewhat specific to the PSM contract. +* **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 to "zoe", it grqnts access to the Zoe framework. All contracts will need access to this. +* **feeMintAccess**: When this permission is set to "zoe", the contract will be able to print money. Any contract that mints a currency will need access to this. +* **economicCommitteeCreatorFacet**, **econCharterKit**, **provisionPoolStartResult**: These 3 permissions are required by governed contracts. +* **chainTimerService**: When this permission is set to "timer", it grants access to the *chainTimerService*. All governed contracts need access to this so they know when the vote is complete. + +## 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 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 tokens, if any, the contract issuer can produce or consume. + +## Brand Section + +Specifies what brands, if any, the contract can produce or consume. \ No newline at end of file diff --git a/main/guides/coreeval/proposal.md b/main/guides/coreeval/proposal.md new file mode 100644 index 000000000..32e163a5d --- /dev/null +++ b/main/guides/coreeval/proposal.md @@ -0,0 +1,59 @@ +# Code the Proposal + +You will need to write a proposal script that requests storageNode powers and passes them to the contract via privateArgs. For example, [here](https://github.com/Agoric/agoric-sdk/blob/master/packages/inter-protocol/test/psm/gov-add-psm.js) is the proposal we created for the PSM contract: + +```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; + +``` + +Bundle your contract by navigating to `/packages/vats` and running + +``` +yarn bundle-source --cache-json bundles/ +``` \ No newline at end of file From f5ca1227a0405fab6f65f4a3903623e0a2a5251a Mon Sep 17 00:00:00 2001 From: Mark Molina Date: Mon, 8 May 2023 12:00:36 -0700 Subject: [PATCH 02/17] Adding the new coreeval files --- main/guides/coreeval/README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 main/guides/coreeval/README.md diff --git a/main/guides/coreeval/README.md b/main/guides/coreeval/README.md new file mode 100644 index 000000000..8924725b5 --- /dev/null +++ b/main/guides/coreeval/README.md @@ -0,0 +1,12 @@ +# Deploying to Agoric Testnet + +In order for an Agoric contract to publish data without having the user pay fees, the use of a chain storage node is required. A chain storage node is an object that can be passed to a contract by submitting a proposal using cosmos-sdk level API ([swingset.CoreEval](https://community.agoric.com/t/blder-dao-governance-using-arbitrary-code-injection-swingset-coreeval/99)). The proposal runs a script that gets access to the chain storage node and starts an instance of the contract, passing the storage node as a privateArg to the contract. + +To deploy a contract, you need to do the following: + +1. [Code the permissions that the proposal will require](./permissions.md). +2. [Code the proposal itself](./proposal.md). +3. [Create a local testnet](./local-testnet.md). + + + From 3076b3ad498a270660d0c2df76fb2150ba55076b Mon Sep 17 00:00:00 2001 From: Mark Molina Date: Mon, 8 May 2023 12:02:58 -0700 Subject: [PATCH 03/17] Modifying the navigation files --- main/.vuepress/config.js | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/main/.vuepress/config.js b/main/.vuepress/config.js index 80ad544f5..aea2f7160 100644 --- a/main/.vuepress/config.js +++ b/main/.vuepress/config.js @@ -149,6 +149,17 @@ module.exports = { '/guides/zoe/price-authority', ], }, + { + title: 'Deploying 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/', From b429cf06d3c4eca8323b0cbb70618adcb3694847 Mon Sep 17 00:00:00 2001 From: Mark Molina Date: Mon, 8 May 2023 12:03:11 -0700 Subject: [PATCH 04/17] Modifying the navigation files --- main/.vuepress/themeConfig/nav.js | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/main/.vuepress/themeConfig/nav.js b/main/.vuepress/themeConfig/nav.js index 1f0657481..9c8c1fbcd 100644 --- a/main/.vuepress/themeConfig/nav.js +++ b/main/.vuepress/themeConfig/nav.js @@ -61,6 +61,11 @@ module.exports = [ link: '/guides/zoe/' }, { + text: 'Deploying to Agoric Testnet', + ariaLabel: 'Coreeval', + link: '/guides/coreeval/' + }, + { text: 'Example Zoe Contracts', ariaLabel: 'Example Zoe Contracts', link: '/guides/zoe/contracts/' From 41ea905dbdadb0886d19decfa5a4bd09d90d5fae Mon Sep 17 00:00:00 2001 From: Mark Molina Date: Thu, 11 May 2023 13:47:01 -0700 Subject: [PATCH 05/17] Updated the navigation files with the new section title --- main/.vuepress/config.js | 2 +- main/.vuepress/themeConfig/nav.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/main/.vuepress/config.js b/main/.vuepress/config.js index aea2f7160..0e5b07f64 100644 --- a/main/.vuepress/config.js +++ b/main/.vuepress/config.js @@ -150,7 +150,7 @@ module.exports = { ], }, { - title: 'Deploying to Agoric Testnet', + title: 'Injecting Code to Agoric Testnet', path: '/guides/coreeval/', collapsible: false, children: [ diff --git a/main/.vuepress/themeConfig/nav.js b/main/.vuepress/themeConfig/nav.js index 9c8c1fbcd..e1ee360c9 100644 --- a/main/.vuepress/themeConfig/nav.js +++ b/main/.vuepress/themeConfig/nav.js @@ -61,7 +61,7 @@ module.exports = [ link: '/guides/zoe/' }, { - text: 'Deploying to Agoric Testnet', + text: 'Injecting Code to Agoric Testnet', ariaLabel: 'Coreeval', link: '/guides/coreeval/' }, From 398d7e6ee9fe4c17bb63914e7d78356ed354790d Mon Sep 17 00:00:00 2001 From: Mark Molina Date: Thu, 11 May 2023 13:47:41 -0700 Subject: [PATCH 06/17] Responded to PR feedback --- main/guides/coreeval/README.md | 6 +++--- main/guides/coreeval/permissions.md | 8 ++++---- main/guides/coreeval/proposal.md | 2 +- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/main/guides/coreeval/README.md b/main/guides/coreeval/README.md index 8924725b5..19bc3c5e3 100644 --- a/main/guides/coreeval/README.md +++ b/main/guides/coreeval/README.md @@ -1,8 +1,8 @@ -# Deploying to Agoric Testnet +# Injecting Code to Agoric Testnet -In order for an Agoric contract to publish data without having the user pay fees, the use of a chain storage node is required. A chain storage node is an object that can be passed to a contract by submitting a proposal using cosmos-sdk level API ([swingset.CoreEval](https://community.agoric.com/t/blder-dao-governance-using-arbitrary-code-injection-swingset-coreeval/99)). The proposal runs a script that gets access to the chain storage node and starts an instance of the contract, passing the storage node as a privateArg to the contract. +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)). The proposal runs a script that runs the contract, and possibly runs an additional script, depending on the result of a governance vote. -To deploy a contract, you need to do the following: +To do this, do the following: 1. [Code the permissions that the proposal will require](./permissions.md). 2. [Code the proposal itself](./proposal.md). diff --git a/main/guides/coreeval/permissions.md b/main/guides/coreeval/permissions.md index 25115c2a3..ee14eead9 100644 --- a/main/guides/coreeval/permissions.md +++ b/main/guides/coreeval/permissions.md @@ -63,10 +63,10 @@ In this section you need to set all the permissions that your contract will need * **bankManager**: Grants access to bank-related functionality within ERTP and Zoe. Most contracts will need access. * **board**: Grants write access to the board name service. This permission is somewhat specific to the PSM contract. * **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 to "zoe", it grqnts access to the Zoe framework. All contracts will need access to this. -* **feeMintAccess**: When this permission is set to "zoe", the contract will be able to print money. Any contract that mints a currency will need access to this. +* **zoe**: When this permission is set to "zoe", it grants access to the Zoe framework. All contracts will need access to this. +* **feeMintAccess**: When this permission is set to "zoe", the contract will be able to create digital assets. Any contract that mints digital assets will need access to this. * **economicCommitteeCreatorFacet**, **econCharterKit**, **provisionPoolStartResult**: These 3 permissions are required by governed contracts. -* **chainTimerService**: When this permission is set to "timer", it grants access to the *chainTimerService*. All governed contracts need access to this so they know when the vote is complete. +* **chainTimerService**: When this permission is set to "timer", it grants access to the *chainTimerService*. All governed contracts need access to this so they know when a vote is complete. ## Produce Section @@ -86,4 +86,4 @@ Specifies what tokens, if any, the contract issuer can produce or consume. ## Brand Section -Specifies what brands, if any, the contract can produce or consume. \ No newline at end of file +Specifies what brands, if any, the contract can produce or consume. Note that any brands that the contract may mint are not included in this section, unless they're also produced or consumed in some other capacity. \ No newline at end of file diff --git a/main/guides/coreeval/proposal.md b/main/guides/coreeval/proposal.md index 32e163a5d..c3b2b7cc4 100644 --- a/main/guides/coreeval/proposal.md +++ b/main/guides/coreeval/proposal.md @@ -1,6 +1,6 @@ # Code the Proposal -You will need to write a proposal script that requests storageNode powers and passes them to the contract via privateArgs. For example, [here](https://github.com/Agoric/agoric-sdk/blob/master/packages/inter-protocol/test/psm/gov-add-psm.js) is the proposal we created for the PSM contract: +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, [here](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: ```jsx /* global startPSM */ From 647a07c592c0b1f719176890c9addede1aab679c Mon Sep 17 00:00:00 2001 From: Mark Molina Date: Wed, 17 May 2023 09:41:59 -0700 Subject: [PATCH 07/17] Responding to PR feedback --- main/guides/coreeval/README.md | 4 ++-- main/guides/coreeval/permissions.md | 27 +++++++++++++++++---------- main/guides/coreeval/proposal.md | 2 +- 3 files changed, 20 insertions(+), 13 deletions(-) diff --git a/main/guides/coreeval/README.md b/main/guides/coreeval/README.md index 19bc3c5e3..b4cc7cc52 100644 --- a/main/guides/coreeval/README.md +++ b/main/guides/coreeval/README.md @@ -1,10 +1,10 @@ # 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)). The proposal runs a script that runs the contract, and possibly runs an additional script, depending on the result of a governance vote. +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 permit list, which the code can combine to perform privileged tasks. To do this, do the following: -1. [Code the permissions that the proposal will require](./permissions.md). +1. [Code the permit list that the proposal will require](./permissions.md). 2. [Code the proposal itself](./proposal.md). 3. [Create a local testnet](./local-testnet.md). diff --git a/main/guides/coreeval/permissions.md b/main/guides/coreeval/permissions.md index ee14eead9..15296753a 100644 --- a/main/guides/coreeval/permissions.md +++ b/main/guides/coreeval/permissions.md @@ -1,7 +1,10 @@ # Coding Permissions -Write a json file with the permissions that the proposal will need. For example, [here](https://github.com/Agoric/agoric-sdk/blob/master/packages/inter-protocol/test/psm/gov-add-psm-permit.json) is the proposal Agoric created for the PSM contract: - +Write a json file with the permissions 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) +is the proposal Agoric created for the PSM contract. Note that permissions are set by listing the +permission and setting it to any String. Thus,`"bankManager": true` and `"bankManager": false` are +equivalent; they both set the `bankManager` permission. ::: details Show example permissions file ``` @@ -57,16 +60,18 @@ Write a json file with the permissions that the proposal will need. For example, ## 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. +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 and Zoe. Most contracts will need access. +* **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. This permission is somewhat specific to the PSM contract. * **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 to "zoe", it grants access to the Zoe framework. All contracts will need access to this. -* **feeMintAccess**: When this permission is set to "zoe", the contract will be able to create digital assets. Any contract that mints digital assets 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.makeZDFMint()](/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 to "timer", it grants access to the *chainTimerService*. All governed contracts need access to this so they know when a vote is complete. +* **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. ## Produce Section @@ -74,7 +79,7 @@ Specifies what, if anything, the contract produces. For example, the example PSM ## Installation Section -Specifies what installations the contract requires. At a minimum, the contract itself should be listed as an installation. Governed contracts should include a *contractGovernor* installation. +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 @@ -82,8 +87,10 @@ Specifies what instances, if any, the contract produces or consumes. ## Issuer Section -Specifies what tokens, if any, the contract issuer can produce or consume. +Specifies what digital assets, if any, the contract issuer can produce or consume. ## Brand Section -Specifies what brands, if any, the contract can produce or consume. Note that any brands that the contract may mint are not included in this section, unless they're also produced or consumed in some other capacity. \ No newline at end of file +Specifies what **[Brands](/reference/ertp-api/brand.md)**, if any, the contract can produce or consume. +Note that any **Brands** associated with digital assets that the contract mints +are not included in this section, unless they're also produced or consumed in some other capacity. \ No newline at end of file diff --git a/main/guides/coreeval/proposal.md b/main/guides/coreeval/proposal.md index c3b2b7cc4..7ed177e68 100644 --- a/main/guides/coreeval/proposal.md +++ b/main/guides/coreeval/proposal.md @@ -1,6 +1,6 @@ # 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, [here](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: +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: ```jsx /* global startPSM */ From 1d56b8017af4326a9ad350098b62397f44e0a91d Mon Sep 17 00:00:00 2001 From: Mark Molina Date: Wed, 24 May 2023 16:17:37 -0700 Subject: [PATCH 08/17] Responding to PR feedback --- main/guides/coreeval/local-testnet.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/main/guides/coreeval/local-testnet.md b/main/guides/coreeval/local-testnet.md index c42754fd7..bae33e38e 100644 --- a/main/guides/coreeval/local-testnet.md +++ b/main/guides/coreeval/local-testnet.md @@ -23,12 +23,11 @@ To create, start, and deploy an Agoric contract to a local Agoric Testnet, do th 6. Navigate to `/bin` and start the client. ``` - agd --chain-id=agoricdev-17 tx gov submit-proposal swingset-core-eval + ./agd --chain-id=agoriclocal --title= --description= --home=../packages/cosmic-swingset/t1/bootstrap --keyring-backend=test --from=bootstrap tx gov submit-proposal swingset-core-eval -bblock --gas=auto --deposit=1000000ubld ``` - + For example, to deploy the PSM contract referenced in the previous topics, run the following: - + ``` - agd --chain-id=agoricdev-17 tx gov submit-proposal swingset-core-eval test/psm/gov-add-psm-permit.json test/psm/gov-add-psm.js + ./agd --chain-id=agoriclocal --title= --description= --home=../packages/cosmic-swingset/t1/bootstrap --keyring-backend=test --from=bootstrap 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 -bblock --gas=auto --deposit=1000000ubld ``` -7. Adjust variables in `/packages/cosmic-swingset/Makefile` to point to the proposal and permissions you created earlier. From b22d2dd8d02b7b8b3bf6210d1d763eb4565687f8 Mon Sep 17 00:00:00 2001 From: Mark Molina Date: Wed, 24 May 2023 16:18:05 -0700 Subject: [PATCH 09/17] Responding to PR feedback --- main/guides/getting-started/README.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/main/guides/getting-started/README.md b/main/guides/getting-started/README.md index cdd51a737..b7985f3ed 100644 --- a/main/guides/getting-started/README.md +++ b/main/guides/getting-started/README.md @@ -9,7 +9,8 @@ After installing the Agoric SDK, you can proceed to [starting a project](./start If you're familar with JavaScript development tools such as `node`, `yarn`, and `git`: ```shell -node --version # 16.19.1 or higher +brew install jq # Install jQuery +node --version # 18.16.0 or higher npm install --global yarn # Install yarn for package management git clone --branch community-dev https://github.com/Agoric/agoric-sdk # Clone the "community-dev" branch cd agoric-sdk @@ -27,7 +28,7 @@ If `agoric` is not found, then you may need to add the parent directory of where This presentation is a good overview of the Agoric SDK setup process, though a few details are out of date: -- node version: 12.x is too old; use 16.19.1 or higher +- node version: 12.x is too old; use 18.16.0 or higher - skip `git checkout hackathon-2020-11`; use the `community-dev` branch @@ -43,12 +44,20 @@ The Agoric SDK is supported on Lin - To launch a terminal on Linux, use the **Terminal** application. - To access WSL from Windows, visit the [WSL documentation](https://docs.microsoft.com/en-us/windows/wsl/). -## Install Node.js 16.19.1 or Higher +## Install jQuery -Download Node.js from [Node.js](https://nodejs.org/) and follow the instructions for your platform. We recommend installing the LTS version of node 16. +Install jQuery by running the following command. ```shell -node --version # 16.19.1 or higher +brew install jq +``` + +## Install Node.js 18.16.0 or Higher + +Download Node.js from [Node.js](https://nodejs.org/) and follow the instructions for your platform. We recommend installing the LTS version of node 18. + +```shell +node --version # 18.16.0 or higher ``` ## Install the Yarn Package Manager From fe3040ad5c99845760fe807c9dcc8e63493e100c Mon Sep 17 00:00:00 2001 From: Mark Molina Date: Tue, 30 May 2023 06:41:04 -0700 Subject: [PATCH 10/17] Responded to PR feedback --- main/guides/coreeval/README.md | 2 +- main/guides/coreeval/local-testnet.md | 20 +++++++------------- main/guides/coreeval/permissions.md | 2 +- 3 files changed, 9 insertions(+), 15 deletions(-) diff --git a/main/guides/coreeval/README.md b/main/guides/coreeval/README.md index b4cc7cc52..5cc6e5487 100644 --- a/main/guides/coreeval/README.md +++ b/main/guides/coreeval/README.md @@ -6,7 +6,7 @@ To do this, do the following: 1. [Code the permit list that the proposal will require](./permissions.md). 2. [Code the proposal itself](./proposal.md). -3. [Create a local testnet](./local-testnet.md). +3. [Deploy the proposal to a local testnet](./local-testnet.md). diff --git a/main/guides/coreeval/local-testnet.md b/main/guides/coreeval/local-testnet.md index bae33e38e..8124e0e6a 100644 --- a/main/guides/coreeval/local-testnet.md +++ b/main/guides/coreeval/local-testnet.md @@ -1,26 +1,20 @@ -# Create a Local Testnet +# Deploy a Governance Proposal to a Local Testnet -To create, start, and deploy an Agoric contract to a local Agoric Testnet, do the following: +To create, start, and deploy an Agoric governance proposal to a local Agoric Testnet, do the following: - -1. Install *Go* if needed. - - ``` - brew install go - ``` -2. Navigate to `/packages/cosmic-swingset` and run `make`. -3. Prepare the chain and solo nodes. +1. Navigate to `/packages/cosmic-swingset` and run `make`. +2. Prepare the chain and solo nodes. ```jsx make scenario2-setup BASE_PORT=8000 NUM_SOLOS=0 ``` -4. Start the chain. +3. Start the chain. ```jsx make scenario2-run-chain ``` -5. Switch to another terminal and wait for the first block to be produced. -6. Navigate to `/bin` and start the client. +4. Switch to another terminal and wait for the first block to be produced. +5. Navigate to `/bin` and submit the governance proposal. ``` ./agd --chain-id=agoriclocal --title= --description= --home=../packages/cosmic-swingset/t1/bootstrap --keyring-backend=test --from=bootstrap tx gov submit-proposal swingset-core-eval -bblock --gas=auto --deposit=1000000ubld diff --git a/main/guides/coreeval/permissions.md b/main/guides/coreeval/permissions.md index 15296753a..a7c18dabb 100644 --- a/main/guides/coreeval/permissions.md +++ b/main/guides/coreeval/permissions.md @@ -66,7 +66,7 @@ general interest to most contracts, while others are more specific to the PSM co * **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. This permission is somewhat specific to the PSM contract. +* **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.makeZDFMint()](/reference/zoe-api/zoe-contract-facet.md#zcf-makezcfmint-keyword-assetkind-displayinfo)**) will need access to this. From c09f7483190470141c46cf2ad5e9dec2a7317bf8 Mon Sep 17 00:00:00 2001 From: Mark Molina Date: Tue, 30 May 2023 06:41:45 -0700 Subject: [PATCH 11/17] Moving the setup changes to their own PR --- main/guides/getting-started/README.md | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) diff --git a/main/guides/getting-started/README.md b/main/guides/getting-started/README.md index b7985f3ed..cdd51a737 100644 --- a/main/guides/getting-started/README.md +++ b/main/guides/getting-started/README.md @@ -9,8 +9,7 @@ After installing the Agoric SDK, you can proceed to [starting a project](./start If you're familar with JavaScript development tools such as `node`, `yarn`, and `git`: ```shell -brew install jq # Install jQuery -node --version # 18.16.0 or higher +node --version # 16.19.1 or higher npm install --global yarn # Install yarn for package management git clone --branch community-dev https://github.com/Agoric/agoric-sdk # Clone the "community-dev" branch cd agoric-sdk @@ -28,7 +27,7 @@ If `agoric` is not found, then you may need to add the parent directory of where This presentation is a good overview of the Agoric SDK setup process, though a few details are out of date: -- node version: 12.x is too old; use 18.16.0 or higher +- node version: 12.x is too old; use 16.19.1 or higher - skip `git checkout hackathon-2020-11`; use the `community-dev` branch @@ -44,20 +43,12 @@ The Agoric SDK is supported on Lin - To launch a terminal on Linux, use the **Terminal** application. - To access WSL from Windows, visit the [WSL documentation](https://docs.microsoft.com/en-us/windows/wsl/). -## Install jQuery +## Install Node.js 16.19.1 or Higher -Install jQuery by running the following command. +Download Node.js from [Node.js](https://nodejs.org/) and follow the instructions for your platform. We recommend installing the LTS version of node 16. ```shell -brew install jq -``` - -## Install Node.js 18.16.0 or Higher - -Download Node.js from [Node.js](https://nodejs.org/) and follow the instructions for your platform. We recommend installing the LTS version of node 18. - -```shell -node --version # 18.16.0 or higher +node --version # 16.19.1 or higher ``` ## Install the Yarn Package Manager From 78aebad2a012ccd2ed80d44d795199342b9c746c Mon Sep 17 00:00:00 2001 From: Mark Molina Date: Tue, 30 May 2023 12:59:39 -0700 Subject: [PATCH 12/17] Responding to PR feedback --- main/guides/coreeval/permissions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/main/guides/coreeval/permissions.md b/main/guides/coreeval/permissions.md index a7c18dabb..2db9b0f6a 100644 --- a/main/guides/coreeval/permissions.md +++ b/main/guides/coreeval/permissions.md @@ -3,7 +3,7 @@ Write a json file with the permissions 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) is the proposal Agoric created for the PSM contract. Note that permissions are set by listing the -permission and setting it to any String. Thus,`"bankManager": true` and `"bankManager": false` are +permission and setting it to any truthy value. Thus,`"bankManager": true` and `"bankManager": 'hello'` are equivalent; they both set the `bankManager` permission. ::: details Show example permissions file @@ -87,10 +87,10 @@ Specifies what instances, if any, the contract produces or consumes. ## Issuer Section -Specifies what digital assets, if any, the contract issuer can produce or consume. +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 can produce or consume. +Specifies what **[Brands](/reference/ertp-api/brand.md)**, if any, the contract produces or consumes. Note that any **Brands** associated with digital assets that the contract mints are not included in this section, unless they're also produced or consumed in some other capacity. \ No newline at end of file From e5492db1beccc903ae6270446ee71ba8e58ea60b Mon Sep 17 00:00:00 2001 From: Mark Molina Date: Tue, 30 May 2023 15:35:17 -0700 Subject: [PATCH 13/17] Responding to PR feedback --- main/guides/coreeval/README.md | 4 ++-- main/guides/coreeval/permissions.md | 18 +++++++++--------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/main/guides/coreeval/README.md b/main/guides/coreeval/README.md index 5cc6e5487..f9349c2c0 100644 --- a/main/guides/coreeval/README.md +++ b/main/guides/coreeval/README.md @@ -1,10 +1,10 @@ # 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 permit list, which the code can combine to perform privileged tasks. +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. [Code the permit list that the proposal will require](./permissions.md). +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). diff --git a/main/guides/coreeval/permissions.md b/main/guides/coreeval/permissions.md index 2db9b0f6a..5a344878b 100644 --- a/main/guides/coreeval/permissions.md +++ b/main/guides/coreeval/permissions.md @@ -1,10 +1,10 @@ -# Coding Permissions +# Declaring Required Capabilities -Write a json file with the permissions that the proposal will need. For example, +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) -is the proposal Agoric created for the PSM contract. Note that permissions are set by listing the -permission and setting it to any truthy value. Thus,`"bankManager": true` and `"bankManager": 'hello'` are -equivalent; they both set the `bankManager` permission. +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 ``` @@ -58,7 +58,7 @@ equivalent; they both set the `bankManager` permission. ``` ::: -## Consume Section +## 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 @@ -69,11 +69,11 @@ general interest to most contracts, while others are more specific to the PSM co * **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.makeZDFMint()](/reference/zoe-api/zoe-contract-facet.md#zcf-makezcfmint-keyword-assetkind-displayinfo)**) 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. -## Produce Section +## 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. @@ -87,7 +87,7 @@ 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. +Specifies what **[Issuers](/reference/ertp-api/issuer.md)**, if any, the contract produces or consumes. ## Brand Section From ef84da200e9c2c9068158db6d85890a210eae73d Mon Sep 17 00:00:00 2001 From: Mark Molina Date: Mon, 19 Jun 2023 09:42:13 -0700 Subject: [PATCH 14/17] Updating the console command --- main/guides/coreeval/local-testnet.md | 38 ++++++++++++++++++++------- main/guides/coreeval/permissions.md | 6 +++-- main/guides/coreeval/proposal.md | 8 ++---- 3 files changed, 34 insertions(+), 18 deletions(-) diff --git a/main/guides/coreeval/local-testnet.md b/main/guides/coreeval/local-testnet.md index 8124e0e6a..14f245711 100644 --- a/main/guides/coreeval/local-testnet.md +++ b/main/guides/coreeval/local-testnet.md @@ -2,26 +2,44 @@ To create, start, and deploy an Agoric governance proposal to a local Agoric Testnet, do the following: -1. Navigate to `/packages/cosmic-swingset` and run `make`. -2. Prepare the chain and solo nodes. +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 - make scenario2-setup BASE_PORT=8000 NUM_SOLOS=0 + agoric init ``` -3. Start the chain. + + 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 + agoric install + ``` + +4. Start the chain by running the following command. (**Note:** You should still be located within your project folder.) ```jsx - make scenario2-run-chain + agoric start local-chain --verbose --reset ``` -4. Switch to another terminal and wait for the first block to be produced. -5. Navigate to `/bin` and submit the governance proposal. + +5. Wait for the first block to be produced. +6. Open a second terminal. +7. Within the second terminal, navigate to `/bin` and submit the governance proposal by running the following command. ``` - ./agd --chain-id=agoriclocal --title= --description= --home=../packages/cosmic-swingset/t1/bootstrap --keyring-backend=test --from=bootstrap tx gov submit-proposal swingset-core-eval -bblock --gas=auto --deposit=1000000ubld + ./agd --chain-id=agoriclocal --title= --description= --home=/_agstate/keys --keyring-backend=test --from=provision tx gov submit-proposal swingset-core-eval ``` - For example, to deploy the PSM contract referenced in the previous topics, run the following: + For example, to deploy the PSM proposal referenced in the previous topics, run the following: ``` - ./agd --chain-id=agoriclocal --title= --description= --home=../packages/cosmic-swingset/t1/bootstrap --keyring-backend=test --from=bootstrap 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 -bblock --gas=auto --deposit=1000000ubld + ./agd --chain-id=agoriclocal --title= --description= --home=/_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 ``` diff --git a/main/guides/coreeval/permissions.md b/main/guides/coreeval/permissions.md index 5a344878b..b0d42e987 100644 --- a/main/guides/coreeval/permissions.md +++ b/main/guides/coreeval/permissions.md @@ -75,11 +75,13 @@ general interest to most contracts, while others are more specific to the PSM co ## 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. +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. +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 diff --git a/main/guides/coreeval/proposal.md b/main/guides/coreeval/proposal.md index 7ed177e68..81b2b3a84 100644 --- a/main/guides/coreeval/proposal.md +++ b/main/guides/coreeval/proposal.md @@ -2,6 +2,7 @@ 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: +::: details Show example proposal ```jsx /* global startPSM */ // @ts-nocheck @@ -51,9 +52,4 @@ const main = async permittedPowers => { main; ``` - -Bundle your contract by navigating to `/packages/vats` and running - -``` -yarn bundle-source --cache-json bundles/ -``` \ No newline at end of file +::: From ca2b8739248446de1179701af812c708b96558db Mon Sep 17 00:00:00 2001 From: Mark Molina Date: Mon, 19 Jun 2023 20:17:44 -0700 Subject: [PATCH 15/17] Responded to PR feedback --- main/guides/coreeval/proposal.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/main/guides/coreeval/proposal.md b/main/guides/coreeval/proposal.md index 81b2b3a84..059363b30 100644 --- a/main/guides/coreeval/proposal.md +++ b/main/guides/coreeval/proposal.md @@ -1,6 +1,10 @@ # 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: +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 From 0a94fddeb1f3cb4f98be490dd31c08146874a139 Mon Sep 17 00:00:00 2001 From: Mark Molina Date: Mon, 19 Jun 2023 20:46:57 -0700 Subject: [PATCH 16/17] Responded to PR feedback --- main/guides/coreeval/permissions.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/main/guides/coreeval/permissions.md b/main/guides/coreeval/permissions.md index b0d42e987..bc80e4593 100644 --- a/main/guides/coreeval/permissions.md +++ b/main/guides/coreeval/permissions.md @@ -93,6 +93,4 @@ Specifies what **[Issuers](/reference/ertp-api/issuer.md)**, if any, the contrac ## Brand Section -Specifies what **[Brands](/reference/ertp-api/brand.md)**, if any, the contract produces or consumes. -Note that any **Brands** associated with digital assets that the contract mints -are not included in this section, unless they're also produced or consumed in some other capacity. \ No newline at end of file +Specifies what **[Brands](/reference/ertp-api/brand.md)**, if any, the contract produces or consumes. \ No newline at end of file From 0dbc077be192ccc5b48c8cbdded0d0108178da6c Mon Sep 17 00:00:00 2001 From: Mark Molina Date: Tue, 20 Jun 2023 06:41:40 -0700 Subject: [PATCH 17/17] Made a minor improvement to the instructions --- main/guides/coreeval/local-testnet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/main/guides/coreeval/local-testnet.md b/main/guides/coreeval/local-testnet.md index 14f245711..da4909b4b 100644 --- a/main/guides/coreeval/local-testnet.md +++ b/main/guides/coreeval/local-testnet.md @@ -32,7 +32,7 @@ To create, start, and deploy an Agoric governance proposal to a local Agoric Tes 5. Wait for the first block to be produced. 6. Open a second terminal. -7. Within the second terminal, navigate to `/bin` and submit the governance proposal by running the following command. +7. Within the second terminal, navigate to `/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= --description= --home=/_agstate/keys --keyring-backend=test --from=provision tx gov submit-proposal swingset-core-eval