How to make an offer from a dapp via the smart wallet? (InvitationSpec Patterns)

[samsiegart]

In the #dev channel in Agoric Discord @0xpatrickdev , asked...

... Is it called proposalTempalte (instead of proposal) due to logic in packages/wallet/api/lib-wallet.js?

I am trying to figure out two things right now -

1. how to call a public facet, that does not require an offer/proposal
2. how to pass in offer args. I was trying on an offerArgs key, but seems like it may just be args
3. how does dapp-inter know my vault is mine?

we are not blocked by this lack of capability (1) at the current moment. Was more so getting a lay of the land
ag-solo/mailbox access

How does the smart-wallet app discover that a wallet has pending invitations active seats/facets? Or put another way, how does dapp-inter know my vault is mine? This is something I'm not quite able to figure out yet

I guess I can also include invitations in the question bc that's the way it seems the econ commitee is started. Are these available in a purse for the Invitation issuer?
I see makeOfferToAcceptInvitation which is a cool pattern: https://github.com/Agoric/dapp-econ-gov/blob/38bc952e0ef255288298a790cda3feea9734c918/src/lib/wallet.ts#L83-L99

[dckc]

Calling a public facet without an offer is not yet supported

To call a public facet without an offer would need ag-solo/mailbox access. no can do (yet) #5965

@0xpatrickdev wrote:

Thank you ... we are not blocked by this lack of capability at the current moment. Was more so getting a lay of the land
ag-solo/mailbox access

[dckc]

How to compose an OfferSpec - forms of InvitationSpec

@samsiegart wrote:

lib-wallet is for ag-solo which might be a red herring.

packages/smart-wallet handles the offer messages. But yes I think that's right, Proposal is a specific zoe construct, and proposalTemplate is used to construct the proposal.

The smart wallet contract can handle an empty proposal if you just want to invoke a method with some args. We do this in dapp-econ-gov https://github.com/Agoric/dapp-econ-gov/blob/main/src/lib/wallet.ts#L137-L149C22

However, dapp-econ-gov doesn't go through the wallet UI like other dapps. It seems like the wallet UI is ignoring offerArgs sent from dapps, so it would require an update here
https://github.com/Agoric/wallet-app/blob/456716c42c2044d51427e1c7806072a9266d4a7f/wallet/src/service/Offers.ts#L163-L170

Another point on (1), yea it still requires an offer, we don't have a smart wallet capability for arbitrary method invocations, so it might require some extra dance in your contract to do things through an invitation

@samsiegart writes:

There are different types invitation specs that a dapp can use to make an offer to the smart wallet:

agoric-sdk/packages/smart-wallet/src/invitations.js

Lines 15 to 54 in fb922d3

	/**
	* @typedef {AgoricContractInvitationSpec | ContractInvitationSpec | PurseInvitationSpec | ContinuingInvitationSpec} InvitationSpec
	* Specify how to produce an invitation. See each type in the union for details.
	*/
	/**
	* @typedef {{
	* source: 'agoricContract',
	* instancePath: string[],
	* callPipe: Array<[methodName: string, methodArgs?: any[]]>,
	* }} AgoricContractInvitationSpec
	* source of invitation is a chain of calls starting with an agoricName
	* - the start of the pipe is a lookup of instancePath within agoricNames
	* - each entry in the callPipe executes a call on the preceding result
	* - the end of the pipe is expected to return an Invitation
	*
	* @typedef {{
	* source: 'contract',
	* instance: Instance,
	* publicInvitationMaker: string,
	* invitationArgs?: any[],
	* }} ContractInvitationSpec
	* source is a contract (in which case this takes an Instance to look up in zoe)
	*
	* @typedef {{
	* source: 'purse',
	* instance: Instance,
	* description: string,
	* }} PurseInvitationSpec
	* the invitation is already in your Zoe "invitation" purse so we need to query it
	* - use the find/query invitation by kvs thing
	*
	* @typedef {{
	* source: 'continuing',
	* previousOffer: import('./offers.js').OfferId,
	* invitationMakerName: string,
	* invitationArgs?: any[],
	* }} ContinuingInvitationSpec
	* continuing invitation in which the offer result from a previous invitation had an `invitationMakers` property
	*/

PurseInvitationSpec as used in dapp-econ-gov

dapp-econ-gov uses PurseInvitationSpec to make an offer with an invitation that is already in the purse. This is used for econ-committee invitations granted by BLD governance.

AgoricContractInvitationSpec as used in dapp-inter

dapp-inter uses AgoricContractInvitationSpec to create vaults https://github.com/Agoric/dapp-inter/blob/main/src/service/vaults.ts#L419-L426. When you sign the offer message, the smart wallet will look up 'VaultFactory" in agoricNames, call getCollateralManager(brand).makeVaultInvitation() on its public facet, and use the resulting invitation to make an offer. In this case the invitation is used immediately, it's never deposited in your invitation purse.

ContinuingInvitationSpec: e.g. adjust vault

In both cases, the smart wallet will store the offer result. The offer result itself has publicSubscribers which are vstorage paths of interest (e.g. for watching vault balances), and invitationMakers, which are functions for getting new invitations (e.g. "adjust vault"). We then use ContinuingInvitationSpec to specify which offer id, and which invitation maker, to get the invitation from. In the case of "adjust vault", we specify the id of the offer used to create the vault, and the "AdjustBalances" invitation maker: https://github.com/Agoric/dapp-inter/blob/main/src/service/vaults.ts#L488-L492.

publicSubscribers

You can see how dapp-inter uses makeAgoricWalletConnection to read offer ids and publicSubscribers from offer results in the form of offerIdsToPublicSubscribers https://github.com/Agoric/dapp-inter/blob/main/src/service/wallet.ts