From 302d9f8bec77fea9a1fd45db6534b7b6be662847 Mon Sep 17 00:00:00 2001 From: Richard Gibson Date: Tue, 28 Apr 2026 09:47:03 -0400 Subject: [PATCH 1/2] fix: Avoid unintentional breaks in the Markdown list documenting InvitationSpec --- main/guides/getting-started/contract-rpc.md | 42 ++++++++++----------- 1 file changed, 19 insertions(+), 23 deletions(-) diff --git a/main/guides/getting-started/contract-rpc.md b/main/guides/getting-started/contract-rpc.md index 6406d21e2..cd51da7e0 100644 --- a/main/guides/getting-started/contract-rpc.md +++ b/main/guides/getting-started/contract-rpc.md @@ -157,31 +157,27 @@ Supposing `spec` is an `InvitationSpec`, its `.source` is one of: - `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. + ```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. - `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. + ```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. ::: From d990642f72095caabe01f8c70e2a0ad3242a6526 Mon Sep 17 00:00:00 2001 From: Richard Gibson Date: Tue, 28 Apr 2026 09:50:28 -0400 Subject: [PATCH 2/2] chore: Make the text documenting InvitationSpec more uniform --- main/guides/getting-started/contract-rpc.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/main/guides/getting-started/contract-rpc.md b/main/guides/getting-started/contract-rpc.md index cd51da7e0..a5c50c574 100644 --- a/main/guides/getting-started/contract-rpc.md +++ b/main/guides/getting-started/contract-rpc.md @@ -150,13 +150,17 @@ public facet. ::: tip InvitationSpec Usage -Supposing `spec` is an `InvitationSpec`, its `.source` is one of: +`InvitationSpec` is a +[discriminated union](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions:~:text=discriminated%20union) +whose `source` property indicates a specific type defining how to get the +invitation. 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. +- `purse` - to use an invitation that is already in the Invitation purse of the smart wallet. `spec` includes properties `.instance` and `.description` properties that must correspond with the same properties of that matching Invitation. 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)` +- `contract` - to have the smart wallet make an invitation using the public facet of a contract referenced by property `.instance`. Property `.publicInvitationMaker` specifies the method name, and optional property `.invitationArgs` specifies arguments for the invocation: `E(E(zoe).getPublicFacet(spec.instance)[spec.publicInvitationMaker](...spec.invitationArgs)` + +- `agoricContract` - to have the smart wallet make an invitation using a chain of calls starting from an instance in [agoricNames](/guides/integration/name-services.html#agoricnames-agoricnamesadmin-well-known-names). Property `.instancePath` is an array of strings used to look up the starting point, and property `.callPipe` is an array of `[methodName: string, args?: unknown[]]` entries, each specifying a method call to invoke on the preceding result. The end of the pipe is expected to return an Invitation. For example, this `InvitationSpec` from [dapp-inter](https://github.com/Agoric/dapp-inter) corresponds with something like `E(E(E(agoricNames).lookup('instance', 'VaultFactory')).getCollateralManager(toLock.brand)).makeVaultInvitation()`: -- `agoricContract` - for example, from [dapp-inter](https://github.com/Agoric/dapp-inter): ```js { source: 'agoricContract', @@ -167,9 +171,8 @@ Supposing `spec` is an `InvitationSpec`, its `.source` is one of: ], } ``` - 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. -- `continuing` - For example, `dapp-inter` uses the following `InvitationSpec` to adjust a vault: +- `continuing` - to have the smart wallet make an invitation by invoking a method on the result of a previous `executeOffer` action. Property `.previousOffer` specifies the `id` associated with that past action, property `.invitationMakerName` specifies the method name, and optional property `.invitationArgs` specifies arguments for the invocation. For example, this `InvitationSpec` from [dapp-inter](https://github.com/Agoric/dapp-inter) for adjusting a vault corresponds with something like `E(offerResults.get(vaultOfferId)).AdjustBalances()`: ```js { source: 'continuing', @@ -177,7 +180,6 @@ Supposing `spec` is an `InvitationSpec`, its `.source` is one of: 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. :::