orch ref docs fixes (WIP)

packages/orchestration/index.js

@@ -4,4 +4,6 @@
 
 export * from './src/types.js';
 export * from './src/exos/cosmos-interchain-service.js';
+export * from './src/exos/chain-hub-admin.js';
 export * from './src/typeGuards.js';
+export { withOrchestration } from './src/utils/start-helper.js';

packages/orchestration/src/chain-info.js

@@ -9,10 +9,14 @@ import {
 import fetchedChainInfo from './fetched-chain-info.js'; // Refresh with scripts/refresh-chain-info.ts
 import { CosmosAssetInfoShape, CosmosChainInfoShape } from './typeGuards.js';
 
-/** @import {CosmosAssetInfo, CosmosChainInfo, EthChainInfo, IBCConnectionInfo} from './types.js'; */
+/** @import {Chain, CosmosAssetInfo, CosmosChainInfo, EthChainInfo, IBCConnectionInfo} from './types.js'; */
 /** @import {NameAdmin} from '@agoric/vats'; */
 
-/** @typedef {CosmosChainInfo | EthChainInfo} ChainInfo */
+/**
+ * Info used to build a {@link Chain} object - naming, connections, etc.
+ *
+ * @typedef {CosmosChainInfo | EthChainInfo} ChainInfo
+ */
 
 const knownChains = /** @satisfies {Record<string, ChainInfo>} */ (
   harden({

packages/orchestration/src/cosmos-api.ts

@@ -93,6 +93,12 @@ export type CosmosChainInfo = Readonly<{
   stakingTokens?: Readonly<Array<{ denom: string }>>;
 }>;
 
+/**
+ * Queries for the staking properties of an account.
+ *
+ * @see {@link https://docs.cosmos.network/main/build/modules/staking#messages x/staking messages}
+ * {@link https://cosmos.github.io/cosmjs/latest/stargate/interfaces/StakingExtension.html StakingExtension} in cosmjs
+ */
 export interface StakingAccountQueries {
   /**
    * @returns all active delegations from the account to any validator (or [] if none)
@@ -137,6 +143,13 @@ export interface StakingAccountQueries {
    */
   getReward: (validator: CosmosValidatorAddress) => Promise<DenomAmount[]>;
 }
+
+/**
+ * Transactions for doing staking operations on an individual account.
+ *
+ * @see {@link https://docs.cosmos.network/main/build/modules/staking#messages x/staking messages}
+ * {@link https://cosmos.github.io/cosmjs/latest/stargate/interfaces/StakingExtension.html StakingExtension} in cosmjs
+ */
 export interface StakingAccountActions {
   /**
    * Delegate an amount to a validator. The promise settles when the delegation is complete.
@@ -248,12 +261,26 @@ export type LocalAccountMethods = {
   monitorTransfers: (tap: TargetApp) => Promise<TargetRegistration>;
 };
 
+/**
+ * Options for {@link OrchestrationAccountI} `transfer` method.
+ *
+ * @see {@link https://github.com/cosmos/ibc/tree/master/spec/app/ics-020-fungible-token-transfer#data-structures ICS 20 Data Structures}
+ */
 export type IBCMsgTransferOptions = {
   timeoutHeight?: MsgTransfer['timeoutHeight'];
   timeoutTimestamp?: MsgTransfer['timeoutTimestamp'];
   memo?: string;
 };
 
+/**
+ * Cosmos-specific methods to extend `OrchestrationAccountI`, parameterized
+ * by `CosmosChainInfo`.
+ *
+ * In particular, if the chain info includes a staking token, `StakingAccountActions`
+ * are available.
+ *
+ * @see {OrchestrationAccountI}
+ */
 export type CosmosChainAccountMethods<CCI extends CosmosChainInfo> =
   (CCI extends {
     icaEnabled: true;

packages/orchestration/src/exos/chain-hub-admin.js

@@ -11,10 +11,15 @@
  */
 
 /**
+ * 
  * For use with async-flow contracts: can be used as a creator facet that allows
  * developers to add new chain configurations to a local chainHub, in the event
  * the information is not available widely in `agoricNames`.
  *
+ * @example 
+ * const chainHubAdmin = prepareChainHubAdmin(zone, chainHub);
+ * chainHubAdmin.initChain('hotNewChain', hotNewChainInfo, agoricTohotNewChainConnectionInfo);
+ * 
  * @param {Zone} zone
  * @param {ChainHub} chainHub
  */
@@ -31,9 +36,11 @@
     }),
     {
       /**
-       * @param {string} chainName
+       * Register information for a chain
+       *
+       * @param {string} chainName - must not exist in chainHub
        * @param {CosmosChainInfo} chainInfo
-       * @param {IBCConnectionInfo} connectionInfo
+       * @param {IBCConnectionInfo} connectionInfo - from Agoric chain
        */
       async initChain(chainName, chainInfo, connectionInfo) {
         // when() because chainHub methods return vows. If this were inside
@@ -52,5 +59,3 @@
   );
   return makeCreatorFacet;
 };
-
-/** @typedef {ReturnType<prepareChainHubAdmin>} ChainHubAdmin */

packages/orchestration/src/exos/chain-hub.js

@@ -171,15 +171,16 @@
 });
 
 /**
- * Make a new ChainHub in the zone (or in the heap if no zone is provided).
+ * Make a new ChainHub in the heap zone.
  *
- * The resulting object is an Exo singleton. It has no precious state. It's only
+ * The resulting object is an Exo singleton. It has no precious state. Its only
  * state is a cache of queries to agoricNames and whatever info was provided in
- * registration calls. When you need a newer version you can simply make a hub
- * hub and repeat the registrations.
+ * registration calls. When you need a newer version you can simply make a ChainHub
+ * and repeat the registrations.
  *
  * @param {Remote<NameHub>} agoricNames
  * @param {VowTools} vowTools
+ * @internal @see {withOrchestration}
  */
 export const makeChainHub = (agoricNames, vowTools) => {
   const zone = makeHeapZone();

packages/orchestration/src/exos/cosmos-interchain-service.js

@@ -24,6 +24,10 @@ import {
 
 const { Vow$ } = NetworkShape; // TODO #9611
 /**
+ * This is the greatest thing since sliced bread.
+ *
+ * TODO: private
+ *
  * @typedef {object} OrchestrationPowers
  * @property {Remote<PortAllocator>} portAllocator
  * @property {undefined} reserved reserve a state key for future use. can hold
@@ -270,4 +274,11 @@ export const prepareCosmosInterchainService = (zone, vowTools) => {
 harden(prepareCosmosInterchainService);
 
 /** @typedef {ReturnType<typeof prepareCosmosInterchainService>} MakeCosmosInterchainService */
-/** @typedef {ReturnType<MakeCosmosInterchainService>} CosmosInterchainService */
+/**
+ * Authority to make an interchain account or an interchain query connection.
+ *
+ * - UNTIL #9765
+ * - UNTIL #9766
+ *
+ * @typedef {ReturnType<MakeCosmosInterchainService>} CosmosInterchainService
+ */

packages/orchestration/src/orchestration-api.ts

@@ -210,8 +210,21 @@ export type TransferMsg = {
   data?: object;
 };
 
+/**
+ * TODO: document how Osmosis ibc hooks work
+ */
 export type AfterAction = { destChain: string; destAddress: ChainAddress };
+/**
+ * Detail for an exact swap on Osmosis.
+ *
+ * @see {@link https://docs.osmosis.zone/osmosis-core/modules/pool-manager/ Osmosis pool-manager module}
+ */
 export type SwapExact = { amountIn: Amount; amountOut: Amount };
+/**
+ * Detail for a max-slippage swap on Osmosis.
+ *
+ * @see {@link https://docs.osmosis.zone/osmosis-core/modules/pool-manager/ Osmosis pool-manager module}
+ */
 export type SwapMaxSlippage = {
   amountIn: Amount;
   brandOut: Brand;

packages/orchestration/src/typeGuards.js

@@ -3,11 +3,21 @@ import { VowShape } from '@agoric/vow';
 import { M } from '@endo/patterns';
 
 /**
- * @import {TypedPattern} from '@agoric/internal';
+ * @import {TypedPattern as TPInternal} from '@agoric/internal';
  * @import {ChainAddress, CosmosAssetInfo, ChainInfo, CosmosChainInfo, DenomAmount, DenomDetail} from './types.js';
  * @import {Delegation} from '@agoric/cosmic-proto/cosmos/staking/v1beta1/staking.js';
  */
 
+/**
+ * @template T
+ * @typedef {TPInternal<T>} TypedPattern a pattern that recognizes an object
+ *   with the static type T
+ * @see {M}
+ *
+ * TODO: caveat about static types that express more than patterns can.
+ * TODO: push TypedPattern down into @endo/patterns
+ */
+
 /**
  * Used for IBC Channel Connections that only send outgoing transactions. If
  * your channel expects incoming transactions, please extend this interface to

packages/orchestration/src/types.ts

@@ -1,5 +1,7 @@
 /** @file Rollup of all type definitions in the package, for local import and external export */
 
+import { prepareChainHubAdmin } from './exos/chain-hub-admin.js';
+
 export type * from './chain-info.js';
 export type * from './cosmos-api.js';
 export type * from './ethereum-api.js';
@@ -9,3 +11,6 @@ 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';
+
+/** @interface */
+export type ChainHubAdmin = ReturnType<typeof prepareChainHubAdmin>;

packages/orchestration/src/utils/start-helper.js

@@ -175,6 +175,13 @@ harden(provideOrchestration);
  * Simplifies contract functions for Orchestration by wrapping a simpler
  * function with all the tools it needs in order to use Orchestration.
  *
+ * @example
+ *
+ * ```js
+ * const contract = (zcf, privateArgs, zone, tools) => { ... };
+ * export const start = withOrchestration(contract);
+ * ```
+ *
  * @template {Record<string, unknown>} CT
  * @template {OrchestrationPowers & {
  *   marshaller: Marshaller;