-
Notifications
You must be signed in to change notification settings - Fork 210
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Document process for creating proposals and submissions in a3p-integr…
…ation. (#9093) refs: #8740 ## Description Improved description of creating proposals and submissions in a3p-integration ### Security Considerations None ### Scaling Considerations None ### Documentation Considerations That's it. ### Testing Considerations None ### Upgrade Considerations None --------- Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
- Loading branch information
1 parent
b5bea48
commit 6578834
Showing
2 changed files
with
158 additions
and
16 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,87 @@ | ||
| # Deploy Script Support | ||
|
|
||
| Import this code in your dapp deploy scripts to more easily install and | ||
| interact with Zoe contracts. | ||
| To install code on chain or in the a3p-integration environment, you'll have to | ||
| generate a proposal, and write a script to build the core proposal. The | ||
| proposals have limited access to bootstrap powers, described by their manifests. | ||
|
|
||
|
|
||
| ### Proposal | ||
|
|
||
| The proposal is called with `(powers, options)` available. The manifest | ||
| detailing the powers that will be used is usually in the same file, and | ||
| conventionally provided by a function named `getManifestForFoo`. The manifest | ||
| needs to have a unique name, since it will be referenced by name from the script. | ||
| The usual format is | ||
| ```js | ||
| export const foo = async ( | ||
| { | ||
| consume: { | ||
| ... | ||
| }, | ||
| brands: { | ||
| ... | ||
| } | ||
| }, | ||
| options, | ||
| ) => { | ||
| // do the things using powers and options | ||
| }; | ||
|
|
||
| export const getManifestForFoo = (powers, options) => { | ||
| manifest: { | ||
| [foo.name]: { | ||
| consume: { | ||
| ... | ||
| }, | ||
| options, | ||
| )}; | ||
| ``` | ||
| `manifest` contains descriptions of powers to be provided to the proposals. | ||
| **TODO** what happens with the `installations` in [`startPsm.js`](https://github.com/Agoric/agoric-sdk/blob/b13743a2cccf0cb63a412b54384435596d4e81ea/packages/inter-protocol/src/proposals/startPSM.js#L496)? | ||
| `options` allows the proposal to be provided with arbitray other powerful | ||
| objects. | ||
| ### Script | ||
| The script describes how to build the core proposal. For | ||
| `agoric-3-proposals` and uploading to the chain, the script must be named in the | ||
| `CoreProposalSteps` section in | ||
| [`app.go`](https://github.com/Agoric/agoric-sdk/blob/b13743a2cccf0cb63a412b54384435596d4e81ea/golang/cosmos/app/app.go#L881), | ||
| and its `defaultProposalBuilder` will be invoked | ||
| directly. | ||
| Script files should export `defaultProposalBuilder` and a `default` function | ||
| that invokes `writeCoreProposal` one or more times to generate sets of files | ||
| describing the proposal. | ||
| ```js | ||
| export const defaultProposalBuilder = ({ publishRef, install }) => { | ||
| return harden({ | ||
| sourceSpec: '@agoric/vats/src/proposals/foo.js', | ||
| getManifestCall: [ | ||
| 'getManifestForFoo', | ||
| { | ||
| fooRef: publishRef(install('@agoric/...')), | ||
| ...otherParams, | ||
| }, | ||
| ], | ||
| }); | ||
| }; | ||
| ` | ||
| export default async (homeP, endowments) => { | ||
| const { writeCoreProposal } = await makeHelpers(homeP, endowments); | ||
| await writeCoreProposal('proposalName', defaultProposalBuilder); | ||
| }; | ||
| ``` | ||
|
|
||
| The first element of `getManifestCall` is interpreted as the name of a proposal. | ||
| The second element of `getManifestCall` produces the `options` argument passed | ||
| to the proposal. (`foo` in the example above). A common thing to want to pass in | ||
| options is a reference to code to be installed on-chain. The `fooRef` example | ||
| above shows how. `publishRef(install(<path>))` is built from sources in the | ||
| sdk, and passed as a `bundleRef`, which contains a `bundleID` suitable for | ||
| passing to Zoe (for contracts) or `vatAdminService` (for non-contract vat code). | ||
|
|