orchestration typedoc: portfolio holder

packages/orchestration/src/exos/combine-invitation-makers.js

@@ -13,6 +13,11 @@ import { getMethodNames } from '@agoric/internal';
 // TODO use a helper from Endo https://github.com/endojs/endo/issues/2448
 /**
  * Takes two or more InvitationMaker exos and combines them into a new one.
+ * Combine with `publicTopics` to form a {@link ContinuingOfferResult} that can
+ * be returned to a smart-wallet client.
+ *
+ * Useful for writing your own invitationMakers while preserving
+ * platform-provided ones like `Delegate`, `Transfer`, `Send`.
  *
  * @param {Zone} zone
  * @param {import('@endo/patterns').InterfaceGuard[]} interfaceGuards
@@ -51,3 +56,4 @@ export const prepareCombineInvitationMakers = (zone, ...interfaceGuards) => {
 };
 
 /** @typedef {ReturnType<typeof prepareCombineInvitationMakers>} MakeCombineInvitationMakers */
+/** @typedef {ReturnType<MakeCombineInvitationMakers>} CombinedInvitationMakers */

packages/orchestration/src/exos/portfolio-holder-kit.js

@@ -13,7 +13,7 @@ const { fromEntries } = Object;
  * @import {VowTools} from '@agoric/vow';
  * @import {ResolvedPublicTopic} from '@agoric/zoe/src/contractSupport/topics.js';
  * @import {Zone} from '@agoric/zone';
- * @import {OrchestrationAccount, OrchestrationAccountI} from '@agoric/orchestration';
+ * @import {OrchestrationAccount, OrchestrationAccountI, MakeCombineInvitationMakers} from '@agoric/orchestration';
  */
 
 /**
@@ -156,8 +156,65 @@ const preparePortfolioHolderKit = (zone, { asVow, when }) => {
  * A portfolio holder stores two or more OrchestrationAccounts and combines
  * ContinuingOfferResult's from each into a single result.
  *
- * XXX consider an interface for extending the exo maker with additional
- * invitation makers.
+ * The invitationMakers can be accessed via the `Proxy` invitationMaker, which
+ * calls out to other invitationMakers.
+ *
+ * See {@link MakeCombineInvitationMakers} for an exo that allows a developer to
+ * define extra invitationMakers to combine with platform-provided ones.
+ *
+ * @example
+ *
+ * ```js
+ * // in contract start/prepare
+ * const makePortfolioHolder = preparePortfolioHolder(
+ *   rootZone.subZone('portfolio'),
+ *   vowTools,
+ * );
+ *
+ * // in a flow
+ * const accounts = {
+ *   cosmoshub: await cosmosChain.makeAccount(),
+ *   agoric: await agoricChain.makeAccount(),
+ * };
+ * const accountEntries = harden(Object.entries(accounts));
+ * const publicTopicEntries = harden(
+ *   await Promise.all(
+ *     Object.entries(accounts).map(async ([chainName, holder]) => {
+ *       const { account } = await E(holder).getPublicTopics();
+ *       return [chainName, account];
+ *     }),
+ *   ),
+ * );
+ * const holder = makePortfolioHolder(accountEntries, publicTopicEntries);
+ *
+ * // return ContinuingOfferResult to client
+ * return E(holder).asContinuingOffer();
+ *
+ * const { invitationMakers } = await E(holder).asContinuingOffer();
+ *
+ * // with invitationArgs
+ * const delegateInv = await E(invitationMakers).Proxying(
+ *   'cosmoshub',
+ *   'Delegate',
+ *   [
+ *     {
+ *       value: 'cosmos1valoper',
+ *       chainId: 'cosmoshub-99',
+ *       encoding: 'bech32',
+ *     },
+ *     {
+ *       denom: 'uatom',
+ *       value: 10n,
+ *     },
+ *   ],
+ * );
+ *
+ * // without invitationArgs
+ * const transferInv = await E(invitationMakers).Proxying(
+ *   'cosmoshub',
+ *   'Transfer',
+ * );
+ * ```
  *
  * @param {Zone} zone
  * @param {VowTools} vowTools

packages/orchestration/src/types.ts

@@ -3,13 +3,15 @@
 export type * from './chain-info.js';
 export type * from './cosmos-api.js';
 export type * from './ethereum-api.js';
+export type * from './exos/chain-hub.js';
+export type * from './exos/combine-invitation-makers.js';
+export type * from './exos/cosmos-interchain-service.js';
+export type * from './exos/exo-interfaces.js';
 export type * from './exos/ica-account-kit.js';
-export type * from './exos/local-chain-facade.js';
 export type * from './exos/icq-connection-kit.js';
-export type * from './exos/exo-interfaces.js';
+export type * from './exos/local-chain-facade.js';
+export type * from './exos/portfolio-holder-kit.js';
 export type * from './orchestration-api.js';
-export type * from './exos/cosmos-interchain-service.js';
-export type * from './exos/chain-hub.js';
 export type * from './vat-orchestration.js';
 
 /**