Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation for the CoreEval feature #799

Merged
merged 18 commits into from
Jun 20, 2023
Merged

Documentation for the CoreEval feature #799

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
79db198
Adding the new coreeval files
Tyrosine22 May 8, 2023
f5ca122
Adding the new coreeval files
Tyrosine22 May 8, 2023
3076b3a
Modifying the navigation files
Tyrosine22 May 8, 2023
b429cf0
Modifying the navigation files
Tyrosine22 May 8, 2023
41ea905
Updated the navigation files with the new section title
Tyrosine22 May 11, 2023
398d7e6
Responded to PR feedback
Tyrosine22 May 11, 2023
647a07c
Responding to PR feedback
Tyrosine22 May 17, 2023
1d56b80
Responding to PR feedback
Tyrosine22 May 24, 2023
b22d2dd
Responding to PR feedback
Tyrosine22 May 24, 2023
fe3040a
Responded to PR feedback
Tyrosine22 May 30, 2023
c09f748
Moving the setup changes to their own PR
Tyrosine22 May 30, 2023
78aebad
Responding to PR feedback
Tyrosine22 May 30, 2023
e5492db
Responding to PR feedback
Tyrosine22 May 30, 2023
ef84da2
Updating the console command
Tyrosine22 Jun 19, 2023
ca2b873
Responded to PR feedback
Tyrosine22 Jun 20, 2023
0a94fdd
Responded to PR feedback
Tyrosine22 Jun 20, 2023
0dbc077
Made a minor improvement to the instructions
Tyrosine22 Jun 20, 2023
eb90ae7
Merge branch 'main' into newcoreeval
Tyrosine22 Jun 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 28 additions & 10 deletions main/guides/coreeval/local-testnet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,44 @@

To create, start, and deploy an Agoric governance proposal to a local Agoric Testnet, do the following:

1. Navigate to `<agoric-sdk>/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 <The name of your project>
```
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 <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
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 `<agoric-sdk>/bin` and submit the governance proposal.

5. Wait for the first block to be produced.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"How can I tell?" I can imagine our audience asking. I suggest providing an example log entry showing a block being produced.

(suggestion; not critical / important)

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.

```
./agd --chain-id=agoriclocal --title=<Insert your own title> --description=<Insert your description> --home=../packages/cosmic-swingset/t1/bootstrap --keyring-backend=test --from=bootstrap tx gov submit-proposal swingset-core-eval <PATH to permissions> <PATH to proposal> -bblock --gas=auto --deposit=1000000ubld
./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 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=<Insert your own title> --description=<Insert your 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=<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
```
6 changes: 4 additions & 2 deletions main/guides/coreeval/permissions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
8 changes: 2 additions & 6 deletions main/guides/coreeval/proposal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 */
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The startPSM global was provided in the pismo boot configuration but isn't provided in vaults.

The global environment for CoreEval scripts is another thing we should document:

https://github.com/Agoric/agoric-sdk/blob/bf164a05f425460ad357841b537b8dbc044357a2/packages/vats/src/core/chain-behaviors.js#L78-L83

where farExports comes from import * as farExports from '@endo/far'; and hence includes E and Far.
endowments comes from a few lines previous:

https://github.com/Agoric/agoric-sdk/blob/bf164a05f425460ad357841b537b8dbc044357a2/packages/vats/src/core/chain-behaviors.js#L40-L45

Documenting VatData is a whole other thing; maybe we can leave that out of scope for now.

And allPowers.modules comes from:

https://github.com/Agoric/agoric-sdk/blob/bf164a05f425460ad357841b537b8dbc044357a2/packages/vats/src/core/boot-chain.js#L17-L20

startPSM was part of allPowers.modules in the pismo bootstrap. But in vaults, it's not there.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It sounds like you're saying that startPSM isn't a part of CoreEval's global environment anymore. But gov-add-psm.js is checked-in code, it appears to assume that startPSM is part of its global environment, and the code works when I run it. So it seems like startPSM is still in global?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

gov-add-psm.js is checked-in code

yes, but there are no automated tests for it

the code works when I run it.

That surprises me. There are no errors in the agd logs? And you can see a new PSM contract started with agd query vstorage children published.psm.IST?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@michaelfig , @Tyrosine22 says you were there when it worked for him. Any idea how the global reference to startPSM worked? I'm confused.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: just say "The script executes in an environment with globals such as E and Far provided." and leave enumeration of the whole list of globals to a later PR.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@michaelfig , @Tyrosine22 says you were there when it worked for him.

We verified that the vote passed and that something happened on the chain.

Any idea how the global reference to startPSM worked? I'm confused.

I don't know if the proposal contents were viable or completed successfully, only that they were initiated.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The following text was added to the top blurb on proposal.md:

"The script executes in an environment with globals such as E and Far provided."

// @ts-nocheck
Expand Down Expand Up @@ -51,9 +52,4 @@ const main = async permittedPowers => {
main;

```

Bundle your contract by navigating to `<agoric-sdk>/packages/vats` and running

```
yarn bundle-source --cache-json bundles/ <PATH_TO_CONTRACT> <CONTRACT_NAME>
```
:::