Skip to content

Commit 5292aa8

Browse files
committed
docs(smart wallet): elaborate InvitationSpec including continuing
- add glossary entry for Continuing Invitation Pattern
1 parent 6e7689d commit 5292aa8

File tree

2 files changed

+41
-2
lines changed

2 files changed

+41
-2
lines changed

main/glossary/index.md

+6
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,12 @@ unavailable for later use. See
163163

164164
Comparable is a deprecated synonym of [Key](#key).
165165

166+
## Continuing Invitation Pattern
167+
168+
A continuing invitation presumes a previous offer
169+
whose result includes capabilities to make further
170+
invitations. See [`source: 'continuing'`](/guides/getting-started/contract-rpc#source-continuing) in [Specifying Offers](/guides/getting-started/contract-rpc#specifying-offers) for details.
171+
166172
## Contract Installation and Contract Instance
167173

168174
In Agoric documentation, _contract_ usually refers to a contract's source code that

main/guides/getting-started/contract-rpc.md

+35-2
Original file line numberDiff line numberDiff line change
@@ -130,8 +130,41 @@ public facet.
130130

131131
<!-- TODO: SVG diagram in /assets/ -->
132132

133-
::: tip InvitationSpec Patterns
134-
For more `InvitationSpec` examples, see [How to make an offer from a dapp via the smart wallet? \(InvitationSpec Patterns\) · #8082](https://github.com/Agoric/agoric-sdk/discussions/8082) July 2023
133+
::: tip InvitationSpec Usage
134+
135+
Supposing `spec` is an `InvitationSpec`, its `.source` is one of:
136+
137+
- `purse` - to make an offer with an invitation that is already in the Invitation purse of the smart wallet and agrees with `spec` on `.instance` and `.description` properties. For example, in [dapp-econ-gov](https://github.com/Agoric/dapp-econ-gov), committee members use invitations sent to them when the committee was created.
138+
139+
- `contract` - the smart wallet makes an invitation by calling a method on the public facet of a specified instance: `E(E(zoe).getPublicFacet(spec.instance)[spec.publicInvitationMaker](...spec.invitationArgs)`
140+
141+
- `agoricContract` - for example, from [dapp-inter](https://github.com/Agoric/dapp-inter):
142+
143+
```js
144+
{
145+
source: 'agoricContract',
146+
instancePath: ['VaultFactory'],
147+
callPipe: [
148+
['getCollateralManager', [toLock.brand]],
149+
['makeVaultInvitation'],
150+
],
151+
}
152+
```
153+
154+
The smart wallet finds the instance using `E(agoricNames).lookup('instance', ...spec.instancePath)` and makes a chain of calls specified by `spec.callPipe`. Each entry in the callPipe is a `[methodName, args?]` pair used to execute a call on the preceding result. The end of the pipe is expected to return an Invitation.
155+
156+
- <a name="source-continuing"></a>`continuing` - For example, `dapp-inter` uses the following `InvitationSpec` to adjust a vault:
157+
158+
```js
159+
{
160+
source: 'continuing',
161+
previousOffer: vaultOfferId,
162+
invitationMakerName: 'AdjustBalances',
163+
}
164+
```
165+
166+
In this continuing offer, the smart wallet uses the `spec.previousOffer` id to look up the `.invitationMakers` property of the result of the previous offer. It uses `E(invitationMakers)[spec.invitationMakerName](...spec.invitationArgs)` to make an invitation.
167+
135168
:::
136169

137170
The client fills in the proposal, which instructs the `SmartWallet`

0 commit comments

Comments
 (0)