9757 Orchestration docs timebox

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"

packages/SwingSet/package.json

@@ -101,6 +101,6 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 75.1
+    "atLeast": 75.7
   }
 }

packages/agoric-cli/package.json

@@ -99,6 +99,6 @@
     "workerThreads": false
   },
   "typeCoverage": {
-    "atLeast": 77.36
+    "atLeast": 77.44
   }
 }

packages/boot/package.json

@@ -90,6 +90,6 @@
     "workerThreads": false
   },
   "typeCoverage": {
-    "atLeast": 86.64
+    "atLeast": 90.03
   }
 }

packages/builders/package.json

@@ -79,6 +79,6 @@
     "workerThreads": false
   },
   "typeCoverage": {
-    "atLeast": 76.03
+    "atLeast": 81.8
   }
 }

packages/cosmic-swingset/package.json

@@ -69,6 +69,6 @@
     "timeout": "20m"
   },
   "typeCoverage": {
-    "atLeast": 80.6
+    "atLeast": 80.53
   }
 }

packages/deploy-script-support/package.json

@@ -72,6 +72,6 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 82.44
+    "atLeast": 82.6
   }
 }

packages/inter-protocol/package.json

@@ -82,6 +82,6 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 95.81
+    "atLeast": 95.8
   }
 }

packages/internal/package.json

@@ -57,6 +57,6 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 93.82
+    "atLeast": 93.32
   }
 }

packages/network/package.json

@@ -66,6 +66,6 @@
     "workerThreads": false
   },
   "typeCoverage": {
-    "atLeast": 90.69
+    "atLeast": 91.15
   }
 }

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';

packages/orchestration/package.json

@@ -92,6 +92,6 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 98.1
+    "atLeast": 97.57
   }
 }

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

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://github.com/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://github.com/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;

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';
  */
 
 /**

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';
  */
 
 /**

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(

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';
  */

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';

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';
  */
 

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';
  */
 

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