How do I add a PSM for a new stable token?

[dckc]

Proposal #17 to add DAI in Dec, 2022 used a startPSM short-cut that was in the global scope of core-eval proposals in mainnet-1A. But in mainnet-1B, it's no longer there.

So how do we add a PSM for a new stable token?

[dckc]

Run the proposal builder with agoric run

The PSM contracts in mainnet-1B are there by way of core-proposals in the swingset bootstrap config; for example:

agoric-sdk/packages/vm-config/decentral-main-vaults-config.json

Lines 37 to 49 in a9d113a

	"module": "@agoric/builders/scripts/inter-protocol/add-collateral-core.js",
	"entrypoint": "psmProposalBuilder",
	"args": [
	{
	"anchorOptions": {
	"denom": "ibc/295548A78785A1007F232DE286149A6FF512F180AF5657780FC89C009E2C348F",
	"decimalPlaces": 6,
	"keyword": "USDC_axl",
	"proposedName": "USD Coin"
	}
	}
	]
	},

That add-collateral-core.js is a proposal builder. We can run proposal builders from the cli with agoric run.

This one has moved to the builders package. So let's run it from there, supplying ANCHOR_DENOM, to get gov-start-psm-permit.json gov-start-psm.js and an auxiliary bundle:
We have to supply some value for INTERCHAIN_DENOM too, because it's going to generate a proposal to add a collateral too. We can ignore that.

~/projects/agoric-sdk/packages/builders$ ANCHOR_DENOM=ibc/must-be-right INTERCHAIN_DENOM=irrelevant agoric run scripts/inter-protocol/add-collateral-core.js 
...
creating gov-add-collateral.js
...

bundle-source --to /home/connolly/projects/agoric-sdk/packages/inter-protocol/bundles /home/connolly/projects/agoric-sdk/packages/inter-protocol/src/psm/psm.js psm
bundle-source --to /home/connolly/projects/agoric-sdk/packages/vats/bundles /home/connolly/projects/agoric-sdk/packages/vats/src/mintHolder.js mintHolder
creating gov-start-psm-permit.json
creating gov-start-psm.js
You can now run a governance submission command like:
  agd tx gov submit-proposal swingset-core-eval gov-start-psm-permit.json gov-start-psm.js \
    --title="Enable <something>" --description="Evaluate gov-start-psm.js" --deposit=1000000ubld \
    --gas=auto --gas-adjustment=1.2
Remember to install bundles before submitting the proposal:
  agd tx swingset install-bundle @/home/connolly/.agoric/cache/b1-40e51bc62b956be719b3809e424744030cf8a94ea8849d6625b3f5486ca216ed577d5f80fe86f4888861dc752aecbe39a98e8a1d5dbc85689d00b455a13f5ab7.json
  agd tx swingset install-bundle @/home/connolly/.agoric/cache/b1-820164f689d730163488efe6911b89f4f4dfb9b11b33b711c24340416c7ea90ec6a311ceb8c26cc2d1c6624e8d5b714c73eab1a08d99bb81c22d815acefd94fd.json
  agd tx swingset install-bundle @/home/connolly/.agoric/cache/b1-a0ab34f33db19e3e46ed976f7a42d9d6e42649087019fdf4dbf608e2fa4c2d0cfc99e9706ee3844dd8c6ec8a56522999f6ab1e23ed68eb9033e7003cd9f72ee8.json

All but one of those bundles should already be on chain.

• Stay tuned for more about that.

Also, running this builder from the CLI has bit-rotted a little. It seems to need a tweak:

add-collateral-core.js patch

```diff diff --git a/packages/builders/scripts/inter-protocol/add-collateral-core.js b/packages/builders/scripts/inter-protocol/add-collateral-core.js index d15497ba0..ee84fb0d1 100644 --- a/packages/builders/scripts/inter-protocol/add-collateral-core.js +++ b/packages/builders/scripts/inter-protocol/add-collateral-core.js @@ -86,13 +86,13 @@ export const psmProposalBuilder = async ( psm: publishRef( install( '@agoric/inter-protocol/src/psm/psm.js', - '../bundles/bundle-psm.js', + '@agoric/inter-protocol/bundles/bundle-psm.js', ), ), mintHolder: publishRef( install( '@agoric/vats/src/mintHolder.js', - '../../vats/bundles/bundle-mintHolder.js', + '@agoric/vats/bundles/bundle-mintHolder.js', ), ), }, ```

We should fill in keyword and proposedName in the anchorOptions of gov-start-psm.js.

Then we're ready to install a bundle and then make the proposal as above.

[0xpatrickdev]

Context

Following directions here, using latest master (740eacc), I am getting 3 bundles that are not currently on chain (expected, due to rolling changes on master):

bundleId	contents
b1-820164...fd94fd	{"compartment":"@agoric/vats-v0.15.1","module":"./src/mintHolder.js"}
b1-d6bf14...0fdeda	{"compartment":"@agoric/inter-protocol-v0.16.1","module":"./src/psm/psm.js"}
b1-eb7db3...e3df83	{"compartment":"@agoric/inter-protocol-v0.16.1","module":"./src/proposals/startPSM.js"}

When I checkout the latest emerynet tag, and run the proposal builder, I get 3 bundles that are already on mainnet-1b.

cd ~/agoric-sdk
git fetch --tags && git checkout -b mainnet1B-rc3 tags/mainnet1B-rc3
yarn install && yarn build
cd packages/inter-protocol
ANCHOR_DENOM=ibc/FE98AAD68F02F03565E9FA39A5E627946699B2B07115889ED812D8BA639576A9 INTERCHAIN_DENOM=irrelevant agoric run scripts/add-collateral-core.js

agoric run scripts/add-collateral-core.js output

yarn run v1.22.19
$ ANCHOR_DENOM=ibc/FE98AAD68F02F03565E9FA39A5E627946699B2B07115889ED812D8BA639576A9 INTERCHAIN_DENOM=irrelevant agoric run scripts/add-collateral-core.js
agoric: run: running /Users/0xpatrick/agoric-sdk/packages/inter-protocol/scripts/add-collateral-core.js
agoric: run: Deploy script will run with Node.js ESM
bundle-source --to /Users/0xpatrick/agoric-sdk/packages/inter-protocol/bundles /Users/0xpatrick/agoric-sdk/packages/zoe/src/contracts/scaledPriceAuthority.js scaledPriceAuthority
/Users/0xpatrick/agoric-sdk/packages/inter-protocol/bundles bundle-scaledPriceAuthority.js valid: 133 files bundled at 2023-10-24T17:48:50.743Z
creating gov-add-collateral-permit.json
creating gov-add-collateral.js
You can now run a governance submission command like:
  agd tx gov submit-proposal swingset-core-eval gov-add-collateral-permit.json gov-add-collateral.js \
    --title="Enable <something>" --description="Evaluate gov-add-collateral.js" --deposit=1000000ubld \
    --gas=auto --gas-adjustment=1.2
Remember to install bundles before submitting the proposal:
  agd tx swingset install-bundle @/Users/0xpatrick/.agoric/cache/b1-0b2177975e88c7221b2fe635fdc75f518916ee42d959e9772dc77ef9775995f36cef50578a070708606e2c2431e66ee51d01147b10821aa5f1983e564697cccd.json
  agd tx swingset install-bundle @/Users/0xpatrick/.agoric/cache/b1-1bedaaafbc7ecb292a4ae481bcee4cce924a21309945e3c95ffcfe1897eb77fa27f132991da666e47cdae9024f4d3d288cce6d9c839a43ad2d8d97510b375203.json

bundle-source --to /Users/0xpatrick/agoric-sdk/packages/vats/bundles /Users/0xpatrick/agoric-sdk/packages/vats/src/mintHolder.js mintHolder
/Users/0xpatrick/agoric-sdk/packages/vats/bundles bundle-mintHolder.js valid: 107 files bundled at 2023-10-24T17:49:07.386Z
bundle-source --to /Users/0xpatrick/agoric-sdk/packages/inter-protocol/bundles /Users/0xpatrick/agoric-sdk/packages/inter-protocol/src/psm/psm.js psm
`^[/Users/0xpatrick/agoric-sdk/packages/inter-protocol/bundles bundle-psm.js valid: 164 files bundled at 2023-10-24T17:48:52.157Z
^[creating gov-start-psm-permit.json
creating gov-start-psm.js
You can now run a governance submission command like:
  agd tx gov submit-proposal swingset-core-eval gov-start-psm-permit.json gov-start-psm.js \
    --title="Enable <something>" --description="Evaluate gov-start-psm.js" --deposit=1000000ubld \
    --gas=auto --gas-adjustment=1.2
Remember to install bundles before submitting the proposal:
  agd tx swingset install-bundle @/Users/0xpatrick/.agoric/cache/b1-b183edd918de93c0b009b0f662502ff851c8e95177c812f2eabc82cd65c2c53e1cb12c56719d6e7c474a0f3d58d3c3d2839dfbf0c2e62f6ee6758e16c16b38c2.json
  agd tx swingset install-bundle @/Users/0xpatrick/.agoric/cache/b1-c25fbc404ae239a8bf9f3d5f65f3f27d489fb4c8e48de0613b1c59c6fc00718243b2c84a3d7060350cbe4442d340d4826d4d1948b9e9938b31807e64c18adbc4.json
  agd tx swingset install-bundle @/Users/0xpatrick/.agoric/cache/b1-4c34c89b707bc8ece5a41e97e6a354081f7ae8a40391f1462848348613dd1218dcce574b3e30901a9825a966cb85bda6a92ba9f9ce9ba325e4c475f9a678b930.json

bundleId	contents
b1-b183ed...6b38c2	{"compartment":"@agoric/vats-v0.15.1","module":"./src/mintHolder.js"}
b1-c25fbc...8adbc4	{"compartment":"@agoric/inter-protocol-v0.16.1","module":"./src/psm/psm.js"}
b1-4c34c8...78b930	{"compartment":"@agoric/inter-protocol-v0.16.1","module":"./src/proposals/startPSM.js"}

Question

All but one of those bundles should already be on chain.

Can you help me understand what you mean here a bit more? Is there any harm running with the proposal builder from the mainnet1B-rc3 tag?

Edit: here is a git diff of relevant bundle files im analyzing

P.S. the tools in #8416 have been super helpful !

[dckc]

Is there any harm running with the proposal builder from the mainnet1B-rc3 tag?

on the contrary: that's a good way to end up with the contract bundles that are on mainnet.

[dckc]

Stepping back, to add a PSM for a new token, there are 2 main steps:

1. makeAnchorAsset creates a new ERTP issuerKit and associates it with a cosmos denom; typically, an IBC denom such as for USDC_axl or more recently: native USDC from noble.
2. startPSM provides the new issuer when starting a PSM contract. This step also sets up governance.

makeAnchorAsset

sequenceDiagram
title: makeAnchorAsset

  bootstrap ->> bootstrap: makeAnchorAsset(powers)
  note left of mintHolder: make issuerKit<br>in its own contract
  bootstrap ->> zoe: E(zoe).startInstance(powers.installation.mintHolder,<br>'USDC_axl', { decimalPlaces: 6, assetKind: 'nat'})
  zoe ->> mintHolder: start()
  mintHolder ->> mintHolder: makeIssuerKit('USDC_axl',<br>'nat', { decimalPlaces: 6})
  mintHolder -->> zoe: { mint, issuer }
  zoe -->> bootstrap: { mint, issuer }
  bootstrap ->> mintHolder: E(issuer).getBrand()
  mintHolder -->> bootstrap: brand
  note left of agoricNames: share issuer, brand<br>via agoricNames
  bootstrap ->> agoricNames: E(E(agoricNames).lookup('issuer')).update('USDC.axl', issuer)
  bootstrap ->> agoricNames: E(E(agoricNames).lookup('brand')).update('USDC.axl', brand)
  note left of bank: register 'ibc/2955...' denom,<br>with {mint,issuer,brand}<br>in vbank
  bootstrap ->> bank: E(bankManager).addAsset('ibc/2955...', 'USDC.axl', 'USD Coin', { mint, issuer, brand })
  agoricNames -->> bootstrap: 
  agoricNames -->> bootstrap: 
  bank -->> bootstrap: 

Loading

p.s. makeAnchorAsset on mainnet also includes code to do 2 more things for pismo->vaults transition:

1. restore governance parameters and metrics from pismo
2. mint a payment to represent the balance from pismo

startPSM

sequenceDiagram
title: startPSM

  bootstrap ->> bootstrap: startPSM(p,<br>{keyword: 'USDC_axl'})
  note left of agoricNames: look up 'USDC_axl' issuer, brand
  bootstrap ->> agoricNames: E(p.agoricNames).lookup('brand', 'USDC_axl')
  bootstrap ->> agoricNames: E(p.agoricNames).lookup('issuer', 'USDC_axl')
  agoricNames -->> bootstrap: brand
  agoricNames -->> bootstrap: issuer

  note over bridge: 'get vstorage node, board marshaller'
  bootstrap ->> bridge: E(E(p.chainStorage).makeChildNode('psm'))<br>.makeChildNode('USC_axl)
  bridge -->> bootstrap: storageNode

  bootstrap ->> board: E(p.board).getPublishingMarshaller()
  board -->> bootstrap: marshaller

  note over governor: start new PSM under governor
  bootstrap ->> economicCommittee: E(p.economicCommitteeCreatorFacet).getPoserInvitation()
  economicCommittee -->> bootstrap: poserInvitation
  bootstrap ->> zoe: E(E(p.zoe).getInvitationIssuer()).getAmountOf(poserInvitation)
  zoe -->> bootstrap: electorateInvitationAmount

  bootstrap ->> zoe: E(p.zoe).startInstance(p.installation.contractGovernor,<br>{p.timer, p.installation.psm, {'USDC_axl': issuer}},<br>{p.feeMintIssuer,poserInvitation,marshaller,storageNode})
  zoe ->> governor: in installation.contractGovernor: start(zcf, {installation.psm})
  governor ->> zoe: E(zoe).startInstance(installation.psm)
  zoe ->> psm: in installation.psm:<br>start(zcf, {feeMintIssuer,<br> marshaller, storageNode})
  psm -->> zoe: psmFacets
  zoe -->> governor: psmFacets
  governor -->> zoe: governorFacets
  zoe -->> bootstrap: governorFacets

  bootstrap ->> governor: E(governorFacets.creatorFacet).getInstance()
#  bootstrap ->> governor: E(governorFacets.creatorFacet).getCreatorFacet()
#  bootstrap ->> governor: E(governorFacets.creatorFacet).getAdminFacet()
  governor -->> bootstrap: psmInstance
#  governor -->> bootstrap: psmCreatorFacet
#  governor -->> bootstrap: psmAdminFacet

  note over agoricNames: share PSM instance via agoricNames
  bootstrap ->> agoricNames: E(E(p.agoricNames).lookup('instance')).update('psm-IST-USDC_axl', instance)

  note over zoe: introduce new PSM to econCharter, provisionPool
  bootstrap ->> econCharter: E(p.econCharter.creatorFacet).addInstance(psmInstance, psmCreator, 'psm-IST-USDC_axl')
  bootstrap ->> provisionPool: E(p.provisionPool.creatorFacet).initPSM(brand, psmInstance)

Loading

[dckc]

https://github.com/0xpatrickdev/agoric-gov-proposal-hub has potential to be a much more straightforward answer to this question.

cc @0xpatrickdev