9757 Orchestration docs timebox (#10050)

refs: #9757 ## Description A bunch of docs improvements to get into the u17 release. This doesn't do all the things specified in the ticket so leaves open: - #9757 ### Security Considerations n/a ### Scaling Considerations n/a ### Documentation Considerations We'll need tutorial docs. I think some of the `@example` suggestions make more sense there. ### Testing Considerations CI ### Upgrade Considerations not yet deployed
Agoric · Sep 9, 2024 · 2e66067 · 2e66067
2 parents 67275c2 + 220d4b2
commit 2e66067
Show file tree

Hide file tree

Showing 50 changed files with 339 additions and 184 deletions.
diff --git a/package.json b/package.json
@@ -32,7 +32,7 @@
  "prettier-plugin-jsdoc": "^1.3.0",
  "prettier-plugin-sh": "^0.14.0",
  "type-coverage": "^2.27.1",
- "typedoc": "^0.26.4",
+ "typedoc": "^0.26.7",
  "typedoc-plugin-markdown": "^4.2.1",
  "typescript": "^5.5.3",
  "typescript-eslint": "^7.15.0"

diff --git a/packages/SwingSet/package.json b/packages/SwingSet/package.json
@@ -101,6 +101,6 @@
  "access": "public"
  },
  "typeCoverage": {
- "atLeast": 75.1
+ "atLeast": 75.7
  }
 }
diff --git a/packages/agoric-cli/package.json b/packages/agoric-cli/package.json
@@ -99,6 +99,6 @@
  "workerThreads": false
  },
  "typeCoverage": {
- "atLeast": 77.36
+ "atLeast": 77.44
  }
 }
diff --git a/packages/boot/package.json b/packages/boot/package.json
@@ -90,6 +90,6 @@
  "workerThreads": false
  },
  "typeCoverage": {
- "atLeast": 86.64
+ "atLeast": 90.03
  }
 }
diff --git a/packages/builders/package.json b/packages/builders/package.json
@@ -79,6 +79,6 @@
  "workerThreads": false
  },
  "typeCoverage": {
- "atLeast": 76.03
+ "atLeast": 81.8
  }
 }
diff --git a/packages/cosmic-swingset/package.json b/packages/cosmic-swingset/package.json
@@ -69,6 +69,6 @@
  "timeout": "20m"
  },
  "typeCoverage": {
- "atLeast": 80.6
+ "atLeast": 80.53
  }
 }
diff --git a/packages/deploy-script-support/package.json b/packages/deploy-script-support/package.json
@@ -72,6 +72,6 @@
  "access": "public"
  },
  "typeCoverage": {
- "atLeast": 82.44
+ "atLeast": 82.6
  }
 }
diff --git a/packages/inter-protocol/package.json b/packages/inter-protocol/package.json
@@ -82,6 +82,6 @@
  "access": "public"
  },
  "typeCoverage": {
- "atLeast": 95.81
+ "atLeast": 95.8
  }
 }
diff --git a/packages/internal/package.json b/packages/internal/package.json
@@ -57,6 +57,6 @@
  "access": "public"
  },
  "typeCoverage": {
- "atLeast": 93.82
+ "atLeast": 93.32
  }
 }
diff --git a/packages/network/package.json b/packages/network/package.json
@@ -66,6 +66,6 @@
  "workerThreads": false
  },
  "typeCoverage": {
- "atLeast": 90.69
+ "atLeast": 91.15
  }
 }
diff --git a/packages/orchestration/index.js b/packages/orchestration/index.js
@@ -4,4 +4,7 @@
 
 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';
diff --git a/packages/orchestration/package.json b/packages/orchestration/package.json
@@ -92,6 +92,6 @@
  "access": "public"
  },
  "typeCoverage": {
- "atLeast": 98.1
+ "atLeast": 97.57
  }
 }
diff --git a/packages/orchestration/src/chain-info.js b/packages/orchestration/src/chain-info.js
@@ -9,10 +9,15 @@ 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 - channel, connection, and denom
+ * info.
+ *
+ * @typedef {CosmosChainInfo | EthChainInfo} ChainInfo
+ */
 
 const knownChains = /** @satisfies {Record<string, ChainInfo>} */ (
  harden({
@@ -69,14 +74,19 @@ const knownChains = /** @satisfies {Record<string, ChainInfo>} */ (
  })
 );
 
-/** @typedef {typeof knownChains} KnownChains */
+/**
+ * @typedef {typeof knownChains} KnownChains
+ * @internal
+ */
 
+// TODO(#9572): include this in registerChain
 /**
- * TODO(#9572): include this in registerChain
+ * Register chain assets into agoricNames
  *
  * @param {ERef<NameAdmin>} agoricNamesAdmin
  * @param {string} name
  * @param {CosmosAssetInfo[]} assets
+ * @alpha
  */
 export const registerChainAssets = async (agoricNamesAdmin, name, assets) => {
  mustMatch(assets, M.arrayOf(CosmosAssetInfoShape));
@@ -86,6 +96,8 @@ export const registerChainAssets = async (agoricNamesAdmin, name, assets) => {
 };
 
 /**
+ * Register a chain into agoricNames
+ *
  * @param {ERef<NameAdmin>} agoricNamesAdmin
  * @param {string} name
  * @param {CosmosChainInfo} chainInfo

diff --git a/packages/orchestration/src/cosmos-api.ts b/packages/orchestration/src/cosmos-api.ts
@@ -36,7 +36,7 @@ export type CosmosValidatorAddress = ChainAddress & {
 };
 
 /** Represents an IBC Connection between two chains, which can contain multiple Channels. */
-export type IBCConnectionInfo = {
+export interface IBCConnectionInfo {
  id: IBCConnectionID; // e.g. connection-0
  client_id: string; // '07-tendermint-0'
  state: IBCConnectionState;
@@ -56,12 +56,12 @@ export type IBCConnectionInfo = {
  state: IBCChannelState;
  version: string; // e.eg. 'ics20-1'
  };
-};
+}
 
 /**
  * https:/cosmos/chain-registry/blob/master/assetlist.schema.json
  */
-export type CosmosAssetInfo = {
+export interface CosmosAssetInfo extends Record<string, unknown> {
  base: Denom;
  name: string;
  display: string;
@@ -79,7 +79,7 @@ export type CosmosAssetInfo = {
  path: string;
  };
  }>;
-} & Record<string, unknown>;
+}
 
 /**
  * Info for a Cosmos-based chain.
@@ -97,6 +97,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)
@@ -141,6 +147,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} and
+ * {@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.
@@ -241,11 +254,13 @@ export interface IcaAccount {
  getPort: () => Port;
 }
 
-export type LiquidStakingMethods = {
+/** Methods on chains that support Liquid Staking */
+export interface LiquidStakingMethods {
  liquidStake: (amount: AmountArg) => Promise<void>;
-};
+}
 
-export type LocalAccountMethods = {
+/** Methods supported only on Agoric chain accounts */
+export interface LocalAccountMethods {
  /** deposit payment (from zoe, for example) to the account */
  deposit: (payment: Payment<'nat'>) => Promise<void>;
  /** withdraw a Payment from the account */
@@ -261,14 +276,28 @@ export type LocalAccountMethods = {
  * @param tap
  */
  monitorTransfers: (tap: TargetApp) => Promise<TargetRegistration>;
-};
+}
 
-export type IBCMsgTransferOptions = {
+/**
+ * Options for {@link OrchestrationAccountI} `transfer` method.
+ *
+ * @see {@link https:/cosmos/ibc/tree/master/spec/app/ics-020-fungible-token-transfer#data-structures ICS 20 Data Structures}
+ */
+export interface 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, {@link StakingAccountActions}
+ * are available.
+ *
+ * @see {OrchestrationAccountI}
+ */
 export type CosmosChainAccountMethods<CCI extends CosmosChainInfo> =
  (CCI extends {
  icaEnabled: true;

diff --git a/packages/orchestration/src/examples/auto-stake-it.contract.js b/packages/orchestration/src/examples/auto-stake-it.contract.js
@@ -10,23 +10,8 @@ import { prepareStakingTap } from './auto-stake-it-tap-kit.js';
 import * as flows from './auto-stake-it.flows.js';
 
 /**
- * @import {TimerService} from '@agoric/time';
- * @import {LocalChain} from '@agoric/vats/src/localchain.js';
- * @import {NameHub} from '@agoric/vats';
- * @import {Remote} from '@agoric/vow';
  * @import {Zone} from '@agoric/zone';
- * @import {CosmosInterchainService} from '@agoric/orchestration';
- * @import {OrchestrationTools} from '../utils/start-helper.js';
- */
-
-/**
- * @typedef {{
- * localchain: Remote<LocalChain>;
- * orchestrationService: Remote<CosmosInterchainService>;
- * storageNode: Remote<StorageNode>;
- * timerService: Remote<TimerService>;
- * agoricNames: Remote<NameHub>;
- * }} OrchestrationPowers
+ * @import {OrchestrationPowers, OrchestrationTools} from '../utils/start-helper.js';
  */
 
 /**

diff --git a/packages/orchestration/src/examples/basic-flows.contract.js b/packages/orchestration/src/examples/basic-flows.contract.js
@@ -10,8 +10,7 @@ import * as flows from './basic-flows.flows.js';
 
 /**
  * @import {Zone} from '@agoric/zone';
- * @import {OrchestrationPowers} from '../utils/start-helper.js';
- * @import {OrchestrationTools} from '../utils/start-helper.js';
+ * @import {OrchestrationPowers, OrchestrationTools} from '../utils/start-helper.js';
  */
 
 /**

diff --git a/packages/orchestration/src/examples/send-anywhere.contract.js b/packages/orchestration/src/examples/send-anywhere.contract.js
@@ -7,24 +7,8 @@ import * as flows from './send-anywhere.flows.js';
 import { prepareChainHubAdmin } from '../exos/chain-hub-admin.js';
 
 /**
- * @import {TimerService} from '@agoric/time';
- * @import {LocalChain} from '@agoric/vats/src/localchain.js';
- * @import {NameHub} from '@agoric/vats';
- * @import {Remote, Vow} from '@agoric/vow';
  * @import {Zone} from '@agoric/zone';
- * @import {VBankAssetDetail} from '@agoric/vats/tools/board-utils.js';
- * @import {CosmosInterchainService} from '../exos/cosmos-interchain-service.js';
- * @import {OrchestrationTools} from '../utils/start-helper.js';
- */
-
-/**
- * @typedef {{
- * localchain: Remote<LocalChain>;
- * orchestrationService: Remote<CosmosInterchainService>;
- * storageNode: Remote<StorageNode>;
- * timerService: Remote<TimerService>;
- * agoricNames: Remote<NameHub>;
- * }} OrchestrationPowers
+ * @import {OrchestrationPowers, OrchestrationTools} from '../utils/start-helper.js';
  */
 
 export const SingleAmountRecord = M.and(

diff --git a/packages/orchestration/src/examples/staking-combinations.contract.js b/packages/orchestration/src/examples/staking-combinations.contract.js
@@ -22,7 +22,7 @@ import * as flows from './staking-combinations.flows.js';
  * @import {Vow} from '@agoric/vow';
  * @import {Remote} from '@agoric/internal';
  * @import {Zone} from '@agoric/zone';
- * @import {CosmosInterchainService} from '../exos/cosmos-interchain-service.js';
+ * @import {CosmosInterchainService} from '../exos/exo-interfaces.js';
  * @import {OrchestrationTools} from '../utils/start-helper.js';
  * @import {CosmosOrchestrationAccount} from '../exos/cosmos-orchestration-account.js';
  */

diff --git a/packages/orchestration/src/examples/swap.contract.js b/packages/orchestration/src/examples/swap.contract.js
@@ -8,7 +8,7 @@ import * as flows from './swap.flows.js';
  * @import {TimerService} from '@agoric/time';
  * @import {LocalChain} from '@agoric/vats/src/localchain.js';
  * @import {Remote} from '@agoric/internal';
- * @import {CosmosInterchainService} from '../exos/cosmos-interchain-service.js';
+ * @import {CosmosInterchainService} from '../exos/exo-interfaces.js';
  * @import {NameHub} from '@agoric/vats';
  * @import {Zone} from '@agoric/zone';
  * @import {OrchestrationTools} from '../utils/start-helper.js';

diff --git a/packages/orchestration/src/examples/unbond.contract.js b/packages/orchestration/src/examples/unbond.contract.js
@@ -8,7 +8,7 @@ import * as flows from './unbond.flows.js';
  * @import {NameHub} from '@agoric/vats';
  * @import {Remote} from '@agoric/internal';
  * @import {Zone} from '@agoric/zone';
- * @import {CosmosInterchainService} from '../exos/cosmos-interchain-service.js';
+ * @import {CosmosInterchainService} from '../exos/exo-interfaces.js';
  * @import {OrchestrationTools} from '../utils/start-helper.js';
  */
 

diff --git a/packages/orchestration/src/examples/unbond.flows.js b/packages/orchestration/src/examples/unbond.flows.js
@@ -5,7 +5,7 @@
  * @import {NameHub} from '@agoric/vats';
  * @import {Remote} from '@agoric/internal';
  * @import {Zone} from '@agoric/zone';
- * @import {CosmosInterchainService} from '../exos/cosmos-interchain-service.js';
+ * @import {CosmosInterchainService} from '../exos/exo-interfaces.js';
  * @import {OrchestrationTools} from '../utils/start-helper.js';
  */
 

diff --git a/packages/orchestration/src/exos/chain-hub-admin.js b/packages/orchestration/src/exos/chain-hub-admin.js
@@ -16,6 +16,17 @@ import { DenomDetailShape } from './chain-hub.js';
  * developers to add new chain configurations to a local chainHub, in the event
  * the information is not available widely in `agoricNames`.
  *
+ * @example
+ *
+ * ```js
+ * const chainHubAdmin = prepareChainHubAdmin(zone, chainHub);
+ * chainHubAdmin.initChain(
+ * 'hotNewChain',
+ * hotNewChainInfo,
+ * agoricTohotNewChainConnectionInfo,
+ * );
+ * ```
+ *
  * @param {Zone} zone
  * @param {ChainHub} chainHub
  */
@@ -33,9 +44,11 @@ export const prepareChainHubAdmin = (zone, chainHub) => {
  }),
  {
  /**
- * @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