Skip to content

Commit

Permalink
docs(smart wallet): elaborate InvitationSpec including continuing
Browse files Browse the repository at this point in the history
 - add glossary entry for Continuing Invitation Pattern
  • Loading branch information
dckc committed Mar 15, 2024
1 parent 6e7689d commit 5292aa8
Show file tree
Hide file tree
Showing 2 changed files with 41 additions and 2 deletions.
6 changes: 6 additions & 0 deletions main/glossary/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,12 @@ unavailable for later use. See

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

## Continuing Invitation Pattern

A continuing invitation presumes a previous offer
whose result includes capabilities to make further
invitations. See [`source: 'continuing'`](/guides/getting-started/contract-rpc#source-continuing) in [Specifying Offers](/guides/getting-started/contract-rpc#specifying-offers) for details.

## Contract Installation and Contract Instance

In Agoric documentation, _contract_ usually refers to a contract's source code that
Expand Down
37 changes: 35 additions & 2 deletions main/guides/getting-started/contract-rpc.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,8 +130,41 @@ public facet.

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

::: tip InvitationSpec Patterns
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
::: tip InvitationSpec Usage

Supposing `spec` is an `InvitationSpec`, its `.source` is one of:

- `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.

- `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)`

- `agoricContract` - for example, from [dapp-inter](https://github.com/Agoric/dapp-inter):

```js
{
source: 'agoricContract',
instancePath: ['VaultFactory'],
callPipe: [
['getCollateralManager', [toLock.brand]],
['makeVaultInvitation'],
],
}
```

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.

- <a name="source-continuing"></a>`continuing` - For example, `dapp-inter` uses the following `InvitationSpec` to adjust a vault:

```js
{
source: 'continuing',
previousOffer: vaultOfferId,
invitationMakerName: 'AdjustBalances',
}
```

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.

:::

The client fills in the proposal, which instructs the `SmartWallet`
Expand Down

0 comments on commit 5292aa8

Please sign in to comment.