From c413d10c41b0d59bddad8b59f12011b698e4e73a Mon Sep 17 00:00:00 2001
From: Turadg Aleahmad <turadg@agoric.com>
Date: Fri, 10 May 2024 10:27:44 -0700
Subject: [PATCH 01/14] build: .ts

---
 packages/orchestration/package.json                 | 1 +
 packages/orchestration/src/types.js                 | 6 ------
 packages/orchestration/src/{types.d.ts => types.ts} | 6 ++++--
 3 files changed, 5 insertions(+), 8 deletions(-)
 delete mode 100644 packages/orchestration/src/types.js
 rename packages/orchestration/src/{types.d.ts => types.ts} (99%)

diff --git a/packages/orchestration/package.json b/packages/orchestration/package.json
index e38cce30d5e..7873105c800 100644
--- a/packages/orchestration/package.json
+++ b/packages/orchestration/package.json
@@ -10,6 +10,7 @@
   },
   "scripts": {
     "build": "exit 0",
+    "prepack": "tsc --build tsconfig.build.json",
     "test": "ava",
     "test:xs": "exit 0",
     "lint": "run-s --continue-on-error lint:*",
diff --git a/packages/orchestration/src/types.js b/packages/orchestration/src/types.js
deleted file mode 100644
index 0ef9dda392a..00000000000
--- a/packages/orchestration/src/types.js
+++ /dev/null
@@ -1,6 +0,0 @@
-// @ts-check
-import '@agoric/network/exported.js';
-import '@agoric/vats/exported.js';
-import '@agoric/zoe/exported.js';
-
-export {};
diff --git a/packages/orchestration/src/types.d.ts b/packages/orchestration/src/types.ts
similarity index 99%
rename from packages/orchestration/src/types.d.ts
rename to packages/orchestration/src/types.ts
index 910404ae18c..52641418aec 100644
--- a/packages/orchestration/src/types.d.ts
+++ b/packages/orchestration/src/types.ts
@@ -1,7 +1,9 @@
+// Ambients
+import '@agoric/zoe/exported.js';
+
 import type { Amount, Brand, Payment, Purse } from '@agoric/ertp/exported.js';
 import type { Timestamp } from '@agoric/time';
-import type { Invitation } from '@agoric/zoe/exported.js';
-import type { Any } from '@agoric/cosmic-proto/google/protobuf/any';
+import type { Any } from '@agoric/cosmic-proto/google/protobuf/any.js';
 import type { AnyJson } from '@agoric/cosmic-proto';
 import type {
   Delegation,

From ea4352d688a5ef4d4eacdbc1932bee8e9b046cd7 Mon Sep 17 00:00:00 2001
From: Turadg Aleahmad <turadg@agoric.com>
Date: Tue, 14 May 2024 06:32:18 -0700
Subject: [PATCH 02/14] chore(types): checkJs

---
 packages/orchestration/src/examples/stakeAtom.contract.js     | 1 -
 packages/orchestration/src/examples/stakeBld.contract.js      | 1 -
 packages/orchestration/src/examples/swapExample.contract.js   | 1 -
 packages/orchestration/src/examples/unbondExample.contract.js | 1 -
 packages/orchestration/src/exos/chainAccountKit.js            | 1 -
 packages/orchestration/src/exos/icqConnectionKit.js           | 1 -
 packages/orchestration/src/exos/localchainAccountKit.js       | 1 -
 packages/orchestration/src/exos/stakingAccountKit.js          | 1 -
 packages/orchestration/src/facade.js                          | 1 -
 .../orchestration/src/proposals/orchestration-proposal.js     | 1 -
 packages/orchestration/src/proposals/start-stakeAtom.js       | 1 -
 packages/orchestration/src/proposals/start-stakeBld.js        | 4 ++--
 packages/orchestration/src/service.js                         | 1 -
 packages/orchestration/src/utils/address.js                   | 1 -
 packages/orchestration/src/utils/orc.js                       | 1 -
 packages/orchestration/src/utils/packet.js                    | 1 -
 packages/orchestration/src/vat-orchestration.js               | 1 -
 packages/orchestration/test/tx-encoding.test.js               | 1 -
 packages/orchestration/test/utils/address.test.js             | 2 --
 packages/orchestration/test/utils/packet.test.js              | 2 --
 packages/orchestration/tsconfig.json                          | 3 ---
 21 files changed, 2 insertions(+), 26 deletions(-)

diff --git a/packages/orchestration/src/examples/stakeAtom.contract.js b/packages/orchestration/src/examples/stakeAtom.contract.js
index 0c6f59b3e78..d2e879b84b7 100644
--- a/packages/orchestration/src/examples/stakeAtom.contract.js
+++ b/packages/orchestration/src/examples/stakeAtom.contract.js
@@ -1,4 +1,3 @@
-// @ts-check
 /**
  * @file Example contract that uses orchestration
  */
diff --git a/packages/orchestration/src/examples/stakeBld.contract.js b/packages/orchestration/src/examples/stakeBld.contract.js
index 8b0a165f901..93dc23fd080 100644
--- a/packages/orchestration/src/examples/stakeBld.contract.js
+++ b/packages/orchestration/src/examples/stakeBld.contract.js
@@ -1,4 +1,3 @@
-// @ts-check
 /**
  * @file Stake BLD contract
  *
diff --git a/packages/orchestration/src/examples/swapExample.contract.js b/packages/orchestration/src/examples/swapExample.contract.js
index 0b29715757d..75f18930222 100644
--- a/packages/orchestration/src/examples/swapExample.contract.js
+++ b/packages/orchestration/src/examples/swapExample.contract.js
@@ -1,4 +1,3 @@
-// @ts-check
 import { Fail } from '@agoric/assert';
 import { AmountMath, AmountShape } from '@agoric/ertp';
 import { E, Far } from '@endo/far';
diff --git a/packages/orchestration/src/examples/unbondExample.contract.js b/packages/orchestration/src/examples/unbondExample.contract.js
index 949d3c3bc90..f688645288a 100644
--- a/packages/orchestration/src/examples/unbondExample.contract.js
+++ b/packages/orchestration/src/examples/unbondExample.contract.js
@@ -1,4 +1,3 @@
-// @ts-check
 import { Fail } from '@agoric/assert';
 import { AmountMath, AmountShape } from '@agoric/ertp';
 import { Far } from '@endo/far';
diff --git a/packages/orchestration/src/exos/chainAccountKit.js b/packages/orchestration/src/exos/chainAccountKit.js
index 6d3f4acb305..4af29428257 100644
--- a/packages/orchestration/src/exos/chainAccountKit.js
+++ b/packages/orchestration/src/exos/chainAccountKit.js
@@ -1,4 +1,3 @@
-// @ts-check
 /** @file ChainAccount exo */
 
 // XXX ambient types runtime imports until https://github.com/Agoric/agoric-sdk/issues/6512
diff --git a/packages/orchestration/src/exos/icqConnectionKit.js b/packages/orchestration/src/exos/icqConnectionKit.js
index 6e3a3cf8b47..e8289d9b16a 100644
--- a/packages/orchestration/src/exos/icqConnectionKit.js
+++ b/packages/orchestration/src/exos/icqConnectionKit.js
@@ -1,4 +1,3 @@
-// @ts-check
 /** @file ICQConnection Exo */
 import { NonNullish } from '@agoric/assert';
 import { makeTracer } from '@agoric/internal';
diff --git a/packages/orchestration/src/exos/localchainAccountKit.js b/packages/orchestration/src/exos/localchainAccountKit.js
index 37c71421b7e..77e90704091 100644
--- a/packages/orchestration/src/exos/localchainAccountKit.js
+++ b/packages/orchestration/src/exos/localchainAccountKit.js
@@ -1,4 +1,3 @@
-// @ts-check
 /** @file Use-object for the owner of a localchain account */
 import { typedJson } from '@agoric/cosmic-proto/vatsafe';
 import { AmountShape } from '@agoric/ertp';
diff --git a/packages/orchestration/src/exos/stakingAccountKit.js b/packages/orchestration/src/exos/stakingAccountKit.js
index 703109fb040..96a78228147 100644
--- a/packages/orchestration/src/exos/stakingAccountKit.js
+++ b/packages/orchestration/src/exos/stakingAccountKit.js
@@ -1,4 +1,3 @@
-// @ts-check
 /** @file Use-object for the owner of a staking account */
 import {
   MsgWithdrawDelegatorReward,
diff --git a/packages/orchestration/src/facade.js b/packages/orchestration/src/facade.js
index 2a5d6fa3636..7d870db87cd 100644
--- a/packages/orchestration/src/facade.js
+++ b/packages/orchestration/src/facade.js
@@ -1,4 +1,3 @@
-// @ts-check
 /** @file Orchestration service */
 
 /**
diff --git a/packages/orchestration/src/proposals/orchestration-proposal.js b/packages/orchestration/src/proposals/orchestration-proposal.js
index f7e71e9b77c..a4f8851d326 100644
--- a/packages/orchestration/src/proposals/orchestration-proposal.js
+++ b/packages/orchestration/src/proposals/orchestration-proposal.js
@@ -1,4 +1,3 @@
-// @ts-check
 import { V as E } from '@agoric/vow/vat.js';
 
 /**
diff --git a/packages/orchestration/src/proposals/start-stakeAtom.js b/packages/orchestration/src/proposals/start-stakeAtom.js
index d5147f1e4e3..fdeb562270c 100644
--- a/packages/orchestration/src/proposals/start-stakeAtom.js
+++ b/packages/orchestration/src/proposals/start-stakeAtom.js
@@ -1,4 +1,3 @@
-// @ts-check
 import { makeTracer } from '@agoric/internal';
 import { makeStorageNodeChild } from '@agoric/internal/src/lib-chainStorage.js';
 import { E } from '@endo/far';
diff --git a/packages/orchestration/src/proposals/start-stakeBld.js b/packages/orchestration/src/proposals/start-stakeBld.js
index f70a4b12a35..3168886a88b 100644
--- a/packages/orchestration/src/proposals/start-stakeBld.js
+++ b/packages/orchestration/src/proposals/start-stakeBld.js
@@ -6,7 +6,7 @@ import { E } from '@endo/far';
 const trace = makeTracer('StartStakeBld', true);
 
 /**
- * @param {BootstrapPowers & {installation: {consume: {stakeBld: Installation<import('../../test/examples/stakeBld.contract.js').start>}}}} powers
+ * @param {BootstrapPowers & {installation: {consume: {stakeBld: Installation<import('../../src/examples/stakeBld.contract.js').start>}}}} powers
  */
 export const startStakeBld = async ({
   consume: { board, chainStorage, localchain, startUpgradable },
@@ -29,7 +29,7 @@ export const startStakeBld = async ({
   const marshaller = await E(board).getPublishingMarshaller();
 
   // FIXME this isn't detecting missing privateArgs
-  /** @type {StartUpgradableOpts<import('../../test/examples/stakeBld.contract.js').start>} */
+  /** @type {StartUpgradableOpts<import('../../src/examples/stakeBld.contract.js').start>} */
   const startOpts = {
     label: 'stakeBld',
     installation: stakeBld,
diff --git a/packages/orchestration/src/service.js b/packages/orchestration/src/service.js
index a541c2e691a..ea8742dd669 100644
--- a/packages/orchestration/src/service.js
+++ b/packages/orchestration/src/service.js
@@ -1,4 +1,3 @@
-// @ts-check
 /** @file Orchestration service */
 
 // XXX ambient types runtime imports until https://github.com/Agoric/agoric-sdk/issues/6512
diff --git a/packages/orchestration/src/utils/address.js b/packages/orchestration/src/utils/address.js
index aecb650d85d..68741bda81b 100644
--- a/packages/orchestration/src/utils/address.js
+++ b/packages/orchestration/src/utils/address.js
@@ -1,4 +1,3 @@
-// @ts-check
 import { Fail } from '@agoric/assert';
 
 /**
diff --git a/packages/orchestration/src/utils/orc.js b/packages/orchestration/src/utils/orc.js
index edc3aa85711..29a4d1f36c8 100644
--- a/packages/orchestration/src/utils/orc.js
+++ b/packages/orchestration/src/utils/orc.js
@@ -1,4 +1,3 @@
-// @ts-check
 /** @import {AfterAction, SwapMaxSlippage, TransferMsg} from '../types.js' */
 
 export const orcUtils = {
diff --git a/packages/orchestration/src/utils/packet.js b/packages/orchestration/src/utils/packet.js
index 3b6bde1d016..944073d7e34 100644
--- a/packages/orchestration/src/utils/packet.js
+++ b/packages/orchestration/src/utils/packet.js
@@ -1,4 +1,3 @@
-// @ts-check
 import { TxBody } from '@agoric/cosmic-proto/cosmos/tx/v1beta1/tx.js';
 import { Any } from '@agoric/cosmic-proto/google/protobuf/any.js';
 import { RequestQuery } from '@agoric/cosmic-proto/tendermint/abci/types.js';
diff --git a/packages/orchestration/src/vat-orchestration.js b/packages/orchestration/src/vat-orchestration.js
index 1f50b7d23a9..8a8e3367739 100644
--- a/packages/orchestration/src/vat-orchestration.js
+++ b/packages/orchestration/src/vat-orchestration.js
@@ -1,4 +1,3 @@
-// @ts-check
 import { Far } from '@endo/far';
 import { makeDurableZone } from '@agoric/zone/durable.js';
 import { prepareOrchestrationTools } from './service.js';
diff --git a/packages/orchestration/test/tx-encoding.test.js b/packages/orchestration/test/tx-encoding.test.js
index d25dede87f2..387e1eb981a 100644
--- a/packages/orchestration/test/tx-encoding.test.js
+++ b/packages/orchestration/test/tx-encoding.test.js
@@ -1,4 +1,3 @@
-// @ts-check
 import { test as anyTest } from '@agoric/zoe/tools/prepare-test-env-ava.js';
 
 import {
diff --git a/packages/orchestration/test/utils/address.test.js b/packages/orchestration/test/utils/address.test.js
index 22b186dc632..b637687d5b9 100644
--- a/packages/orchestration/test/utils/address.test.js
+++ b/packages/orchestration/test/utils/address.test.js
@@ -1,5 +1,3 @@
-// @ts-check
-
 import test from '@endo/ses-ava/prepare-endo.js';
 import { validateRemoteIbcAddress } from '@agoric/vats/tools/ibc-utils.js';
 import {
diff --git a/packages/orchestration/test/utils/packet.test.js b/packages/orchestration/test/utils/packet.test.js
index e58626308f4..f5202de6c39 100644
--- a/packages/orchestration/test/utils/packet.test.js
+++ b/packages/orchestration/test/utils/packet.test.js
@@ -1,5 +1,3 @@
-// @ts-check
-
 import test from '@endo/ses-ava/prepare-endo.js';
 import { Any } from '@agoric/cosmic-proto/google/protobuf/any.js';
 import {
diff --git a/packages/orchestration/tsconfig.json b/packages/orchestration/tsconfig.json
index 4ee11675557..9dc3939bb9d 100644
--- a/packages/orchestration/tsconfig.json
+++ b/packages/orchestration/tsconfig.json
@@ -1,8 +1,5 @@
 {
   "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "checkJs": false,
-  },
   "include": [
     "build",
     "index.js",

From 90b30020273cdd940b01e2de9e7ab11538f0b8a5 Mon Sep 17 00:00:00 2001
From: Turadg Aleahmad <turadg@agoric.com>
Date: Thu, 9 May 2024 15:54:47 -0700
Subject: [PATCH 03/14] chore(types): drop ambients

---
 packages/orchestration/src/types.ts | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/packages/orchestration/src/types.ts b/packages/orchestration/src/types.ts
index 52641418aec..ac9e9379d6e 100644
--- a/packages/orchestration/src/types.ts
+++ b/packages/orchestration/src/types.ts
@@ -1,29 +1,33 @@
 // Ambients
 import '@agoric/zoe/exported.js';
 
-import type { Amount, Brand, Payment, Purse } from '@agoric/ertp/exported.js';
-import type { Timestamp } from '@agoric/time';
-import type { Any } from '@agoric/cosmic-proto/google/protobuf/any.js';
 import type { AnyJson } from '@agoric/cosmic-proto';
 import type {
   Delegation,
   Redelegation,
   UnbondingDelegation,
 } from '@agoric/cosmic-proto/cosmos/staking/v1beta1/staking.js';
+import type {
+  MsgBeginRedelegateResponse,
+  MsgUndelegateResponse,
+} from '@agoric/cosmic-proto/cosmos/staking/v1beta1/tx.js';
 import type { TxBody } from '@agoric/cosmic-proto/cosmos/tx/v1beta1/tx.js';
+import { MsgTransferResponse } from '@agoric/cosmic-proto/ibc/applications/transfer/v1/tx.js';
+import type { Amount, Brand, Payment, Purse } from '@agoric/ertp/exported.js';
+import type { Port } from '@agoric/network';
+import type { Timestamp } from '@agoric/time';
+import type { IBCConnectionID } from '@agoric/vats';
 import type {
   LocalIbcAddress,
   RemoteIbcAddress,
 } from '@agoric/vats/tools/ibc-utils.js';
-import type { Port } from '@agoric/network';
-import { MsgTransferResponse } from '@agoric/cosmic-proto/ibc/applications/transfer/v1/tx.js';
-import type { IBCConnectionID } from '@agoric/vats';
+import type { LocalChainAccount } from '@agoric/vats/src/localchain.js';
 import type { ICQConnection } from './exos/icqConnectionKit.js';
 
-export type * from './service.js';
-export type * from './vat-orchestration.js';
 export type * from './exos/chainAccountKit.js';
 export type * from './exos/icqConnectionKit.js';
+export type * from './service.js';
+export type * from './vat-orchestration.js';
 
 /**
  * static declaration of known chain types will allow type support for

From 8c9a62bd254a6fb30885a229a6198240d29b5da6 Mon Sep 17 00:00:00 2001
From: Turadg Aleahmad <turadg@agoric.com>
Date: Tue, 14 May 2024 11:32:53 -0700
Subject: [PATCH 04/14] refactor(types): extract ethereum-api

refactor(types): extract ethereum-api
---
 packages/orchestration/src/ethereum-api.ts |  7 +++++++
 packages/orchestration/src/types.ts        | 16 +++-------------
 2 files changed, 10 insertions(+), 13 deletions(-)
 create mode 100644 packages/orchestration/src/ethereum-api.ts

diff --git a/packages/orchestration/src/ethereum-api.ts b/packages/orchestration/src/ethereum-api.ts
new file mode 100644
index 00000000000..9d0f7dc2ea5
--- /dev/null
+++ b/packages/orchestration/src/ethereum-api.ts
@@ -0,0 +1,7 @@
+/**
+ * Info for an Ethereum-based chain.
+ */
+export type EthChainInfo = {
+  chainId: string;
+  allegedName: string;
+};
diff --git a/packages/orchestration/src/types.ts b/packages/orchestration/src/types.ts
index ac9e9379d6e..a8c45c5d8ad 100644
--- a/packages/orchestration/src/types.ts
+++ b/packages/orchestration/src/types.ts
@@ -7,23 +7,21 @@ import type {
   Redelegation,
   UnbondingDelegation,
 } from '@agoric/cosmic-proto/cosmos/staking/v1beta1/staking.js';
-import type {
-  MsgBeginRedelegateResponse,
-  MsgUndelegateResponse,
-} from '@agoric/cosmic-proto/cosmos/staking/v1beta1/tx.js';
 import type { TxBody } from '@agoric/cosmic-proto/cosmos/tx/v1beta1/tx.js';
 import { MsgTransferResponse } from '@agoric/cosmic-proto/ibc/applications/transfer/v1/tx.js';
 import type { Amount, Brand, Payment, Purse } from '@agoric/ertp/exported.js';
 import type { Port } from '@agoric/network';
 import type { Timestamp } from '@agoric/time';
 import type { IBCConnectionID } from '@agoric/vats';
+import type { LocalChainAccount } from '@agoric/vats/src/localchain.js';
 import type {
   LocalIbcAddress,
   RemoteIbcAddress,
 } from '@agoric/vats/tools/ibc-utils.js';
-import type { LocalChainAccount } from '@agoric/vats/src/localchain.js';
+import type { EthChainInfo } from './ethereum-api.js';
 import type { ICQConnection } from './exos/icqConnectionKit.js';
 
+export type * from './ethereum-api.js';
 export type * from './exos/chainAccountKit.js';
 export type * from './exos/icqConnectionKit.js';
 export type * from './service.js';
@@ -166,14 +164,6 @@ export type OrchestrationHandlerMaker = <C extends object>(
   fn: (orc: Orchestrator, ctx2: C, ...args) => object,
 ) => (...args) => object;
 
-/**
- * Info for an Ethereum-based chain.
- */
-export type EthChainInfo = {
-  chainId: string;
-  allegedName: string;
-};
-
 /**
  * Info for a Cosmos-based chain.
  */

From a211e880725ad50f8a9c4938e565d55ad2b28c94 Mon Sep 17 00:00:00 2001
From: Turadg Aleahmad <turadg@agoric.com>
Date: Tue, 14 May 2024 11:28:30 -0700
Subject: [PATCH 05/14] refactor(types): extract cosmos-api

---
 packages/orchestration/src/cosmos-api.ts      | 203 +++++++++++++++++
 .../src/exos/stakingAccountKit.js             |   6 +-
 packages/orchestration/src/service.js         |   4 +-
 packages/orchestration/src/types.ts           | 209 ++----------------
 .../orchestration/test/staking-ops.test.js    |   4 +-
 5 files changed, 223 insertions(+), 203 deletions(-)
 create mode 100644 packages/orchestration/src/cosmos-api.ts

diff --git a/packages/orchestration/src/cosmos-api.ts b/packages/orchestration/src/cosmos-api.ts
new file mode 100644
index 00000000000..db1a55d30bf
--- /dev/null
+++ b/packages/orchestration/src/cosmos-api.ts
@@ -0,0 +1,203 @@
+import type { AnyJson } from '@agoric/cosmic-proto';
+import type {
+  Delegation,
+  Redelegation,
+  UnbondingDelegation,
+} from '@agoric/cosmic-proto/cosmos/staking/v1beta1/staking.js';
+import type { TxBody } from '@agoric/cosmic-proto/cosmos/tx/v1beta1/tx.js';
+import type { Brand, Payment, Purse } from '@agoric/ertp/exported.js';
+import type { Port } from '@agoric/network';
+import type {
+  LocalIbcAddress,
+  RemoteIbcAddress,
+} from '@agoric/vats/tools/ibc-utils.js';
+import type { AmountArg, ChainAddress, ChainAmount } from './types.js';
+import type {
+  MsgBeginRedelegateResponse,
+  MsgUndelegateResponse,
+} from '@agoric/cosmic-proto/cosmos/staking/v1beta1/tx.js';
+
+/** A helper type for type extensions. */
+export type TypeUrl = string;
+
+// TODO move into cosmic-proto
+export type Proto3JSONMsg = {
+  '@type': TypeUrl;
+  value: Record<string, unknown>;
+};
+
+/** An address for a validator on some blockchain, e.g., cosmos, eth, etc. */
+export type CosmosValidatorAddress = ChainAddress & {
+  // TODO document why this is the format
+  address: `${string}valoper${string}`;
+  addressEncoding: 'bech32';
+};
+
+/**
+ * Info for a Cosmos-based chain.
+ */
+export type CosmosChainInfo = {
+  chainId: string;
+  ibcConnectionInfo: {
+    id: string; // e.g. connection-0
+    client_id: string; // '07-tendermint-0'
+    state: 'OPEN' | 'TRYOPEN' | 'INIT' | 'CLOSED';
+    counterparty: {
+      client_id: string;
+      connection_id: string;
+      prefix: {
+        key_prefix: string;
+      };
+    };
+    versions: { identifier: string; features: string[] }[];
+    delay_period: bigint;
+  };
+  icaEnabled: boolean;
+  icqEnabled: boolean;
+  pfmEnabled: boolean;
+  ibcHooksEnabled: boolean;
+  /**
+   *
+   */
+  allowedMessages: TypeUrl[];
+  allowedQueries: TypeUrl[];
+};
+
+export interface StakingAccountQueries {
+  /**
+   * @returns all active delegations from the account to any validator (or [] if none)
+   */
+  getDelegations: () => Promise<Delegation[]>;
+
+  /**
+   * @returns the active delegation from the account to a specific validator. Return an
+   * empty Delegation if there is no delegation.
+   */
+  getDelegation: (validator: CosmosValidatorAddress) => Promise<Delegation>;
+
+  /**
+   * @returns the unbonding delegations from the account to any validator (or [] if none)
+   */
+  getUnbondingDelegations: () => Promise<UnbondingDelegation[]>;
+
+  /**
+   * @returns the unbonding delegations from the account to a specific validator (or [] if none)
+   */
+  getUnbondingDelegation: (
+    validator: CosmosValidatorAddress,
+  ) => Promise<UnbondingDelegation>;
+
+  getRedelegations: () => Promise<Redelegation[]>;
+
+  getRedelegation: (
+    srcValidator: CosmosValidatorAddress,
+    dstValidator?: CosmosValidatorAddress,
+  ) => Promise<Redelegation>;
+
+  /**
+   * Get the pending rewards for the account.
+   * @returns the amounts of the account's rewards pending from all validators
+   */
+  getRewards: () => Promise<ChainAmount[]>;
+
+  /**
+   * Get the rewards pending with a specific validator.
+   * @param validator - the validator address to query for
+   * @returns the amount of the account's rewards pending from a specific validator
+   */
+  getReward: (validator: CosmosValidatorAddress) => Promise<ChainAmount[]>;
+}
+export interface StakingAccountActions {
+  /**
+   * Delegate an amount to a validator. The promise settles when the delegation is complete.
+   * @param validator - the validator to delegate to
+   * @param amount  - the amount to delegate
+   * @returns void
+   */
+  delegate: (
+    validator: CosmosValidatorAddress,
+    amount: AmountArg,
+  ) => Promise<void>;
+
+  /**
+   * Redelegate from one delegator to another.
+   * Settles when the redelegation is established, not 21 days later.
+   * @param srcValidator - the current validator for the delegation.
+   * @param dstValidator - the validator that will receive the delegation.
+   * @param amount - how much to redelegate.
+   * @returns
+   */
+  redelegate: (
+    srcValidator: CosmosValidatorAddress,
+    dstValidator: CosmosValidatorAddress,
+    amount: AmountArg,
+  ) => Promise<void>;
+
+  /**
+   * Undelegate multiple delegations (concurrently). To delegate independently, pass an array with one item.
+   * Resolves when the undelegation is complete and the tokens are no longer bonded. Note it may take weeks.
+   * The unbonding time is padded by 10 minutes to account for clock skew.
+   * @param {Delegation[]} delegations - the delegation to undelegate
+   */
+  undelegate: (delegations: Delegation[]) => Promise<void>;
+
+  /**
+   * Withdraw rewards from all validators. The promise settles when the rewards are withdrawn.
+   * @returns The total amounts of rewards withdrawn
+   */
+  withdrawRewards: () => Promise<ChainAmount[]>;
+
+  /**
+   * Withdraw rewards from a specific validator. The promise settles when the rewards are withdrawn.
+   * @param validator - the validator to withdraw rewards from
+   * @returns
+   */
+  withdrawReward: (validator: CosmosValidatorAddress) => Promise<ChainAmount[]>;
+}
+
+/**
+ * Low level object that supports queries and operations for an account on a remote chain.
+ */
+export interface IcaAccount {
+  /**
+   * @returns the address of the account on the remote chain
+   */
+  getAddress: () => ChainAddress;
+
+  /**
+   * Submit a transaction on behalf of the remote account for execution on the remote chain.
+   * @param msgs - records for the transaction
+   * @returns acknowledgement string
+   */
+  executeTx: (msgs: Proto3JSONMsg[]) => Promise<string>;
+  /**
+   * Submit a transaction on behalf of the remote account for execution on the remote chain.
+   * @param {AnyJson[]} msgs - records for the transaction
+   * @param {Partial<Omit<TxBody, 'messages'>>} [opts] - optional parameters for the Tx, like `timeoutHeight` and `memo`
+   * @returns acknowledgement string
+   */
+  executeEncodedTx: (
+    msgs: AnyJson[],
+    opts?: Partial<Omit<TxBody, 'messages'>>,
+  ) => Promise<string>;
+  /** deposit payment from zoe to the account*/
+  deposit: (payment: Payment) => Promise<void>;
+  /** get Purse for a brand to .withdraw() a Payment from the account */
+  getPurse: (brand: Brand) => Promise<Purse>;
+  /**
+   * Close the remote account
+   */
+  close: () => Promise<void>;
+  /* transfer account to new holder */
+  prepareTransfer: () => Promise<Invitation>;
+  /** @returns the address of the remote channel */
+  getRemoteAddress: () => RemoteIbcAddress;
+  /** @returns the address of the local channel */
+  getLocalAddress: () => LocalIbcAddress;
+  /** @returns the port the ICA channel is bound to */
+  getPort: () => Port;
+}
+
+export type LiquidStakingMethods = {
+  liquidStake: (amount: AmountArg) => Promise<void>;
+};
diff --git a/packages/orchestration/src/exos/stakingAccountKit.js b/packages/orchestration/src/exos/stakingAccountKit.js
index 96a78228147..c1a3e2bae69 100644
--- a/packages/orchestration/src/exos/stakingAccountKit.js
+++ b/packages/orchestration/src/exos/stakingAccountKit.js
@@ -35,7 +35,7 @@ import {
 export const maxClockSkew = 10n * 60n;
 
 /**
- * @import {AmountArg, ChainAccount, ChainAddress, ChainAmount, CosmosValidatorAddress, ICQConnection, StakingAccountActions} from '../types.js';
+ * @import {AmountArg, IcaAccount, ChainAddress, ChainAmount, CosmosValidatorAddress, ICQConnection, StakingAccountActions} from '../types.js';
  * @import {RecorderKit, MakeRecorderKit} from '@agoric/zoe/src/contractSupport/recorder.js';
  * @import {Baggage} from '@agoric/swingset-liveslots';
  * @import {AnyJson} from '@agoric/cosmic-proto';
@@ -55,7 +55,7 @@ const { Fail } = assert;
 /**
  * @typedef {{
  *  topicKit: RecorderKit<StakingAccountNotification>;
- *  account: ChainAccount;
+ *  account: IcaAccount;
  *  chainAddress: ChainAddress;
  *  icqConnection: ICQConnection;
  *  bondDenom: string;
@@ -168,7 +168,7 @@ export const prepareStakingAccountKit = (baggage, makeRecorderKit, zcf) => {
      * @param {ChainAddress} chainAddress
      * @param {string} bondDenom e.g. 'uatom'
      * @param {object} io
-     * @param {ChainAccount} io.account
+     * @param {IcaAccount} io.account
      * @param {StorageNode} io.storageNode
      * @param {ICQConnection} io.icqConnection
      * @param {TimerService} io.timer
diff --git a/packages/orchestration/src/service.js b/packages/orchestration/src/service.js
index ea8742dd669..ae38835da58 100644
--- a/packages/orchestration/src/service.js
+++ b/packages/orchestration/src/service.js
@@ -17,7 +17,7 @@ import {
  * @import { Zone } from '@agoric/base-zone';
  * @import { Port, PortAllocator } from '@agoric/network';
  * @import { IBCConnectionID } from '@agoric/vats';
- * @import { ICQConnection, ChainAccount, ICQConnectionKit } from './types.js';
+ * @import { ICQConnection, IcaAccount, ICQConnectionKit } from './types.js';
  */
 
 const { Fail, bare } = assert;
@@ -115,7 +115,7 @@ const prepareOrchestrationKit = (
          *   the counterparty connection_id
          * @param {IBCConnectionID} controllerConnectionId
          *   self connection_id
-         * @returns {Promise<ChainAccount>}
+         * @returns {Promise<IcaAccount>}
          */
         async makeAccount(hostConnectionId, controllerConnectionId) {
           const port = await this.facets.self.allocateICAControllerPort();
diff --git a/packages/orchestration/src/types.ts b/packages/orchestration/src/types.ts
index a8c45c5d8ad..aa7e5fb694e 100644
--- a/packages/orchestration/src/types.ts
+++ b/packages/orchestration/src/types.ts
@@ -1,26 +1,23 @@
 // Ambients
 import '@agoric/zoe/exported.js';
 
-import type { AnyJson } from '@agoric/cosmic-proto';
-import type {
-  Delegation,
-  Redelegation,
-  UnbondingDelegation,
-} from '@agoric/cosmic-proto/cosmos/staking/v1beta1/staking.js';
-import type { TxBody } from '@agoric/cosmic-proto/cosmos/tx/v1beta1/tx.js';
 import { MsgTransferResponse } from '@agoric/cosmic-proto/ibc/applications/transfer/v1/tx.js';
-import type { Amount, Brand, Payment, Purse } from '@agoric/ertp/exported.js';
-import type { Port } from '@agoric/network';
+import type { Amount, Brand, Payment } from '@agoric/ertp/exported.js';
 import type { Timestamp } from '@agoric/time';
 import type { IBCConnectionID } from '@agoric/vats';
 import type { LocalChainAccount } from '@agoric/vats/src/localchain.js';
-import type {
-  LocalIbcAddress,
-  RemoteIbcAddress,
-} from '@agoric/vats/tools/ibc-utils.js';
 import type { EthChainInfo } from './ethereum-api.js';
 import type { ICQConnection } from './exos/icqConnectionKit.js';
-
+import type {
+  CosmosChainInfo,
+  Proto3JSONMsg,
+  StakingAccountQueries,
+  StakingAccountActions,
+  IcaAccount,
+  LiquidStakingMethods,
+} from './cosmos-api.js';
+
+export type * from './cosmos-api.js';
 export type * from './ethereum-api.js';
 export type * from './exos/chainAccountKit.js';
 export type * from './exos/icqConnectionKit.js';
@@ -34,9 +31,7 @@ export type * from './vat-orchestration.js';
 export type KnownChains = {
   stride: {
     info: CosmosChainInfo;
-    methods: {
-      liquidStake: (amount: AmountArg) => Promise<void>;
-    };
+    methods: LiquidStakingMethods;
   };
   cosmos: { info: CosmosChainInfo; methods: {} };
   agoric: {
@@ -56,9 +51,6 @@ export type KnownChains = {
   osmosis: { info: CosmosChainInfo; methods: {} };
 };
 
-/** A helper type for type extensions. */
-export type TypeUrl = string;
-
 /**
  * A denom that designates a token type on some blockchain.
  *
@@ -78,10 +70,6 @@ export type Denom = string; // ibc/... or uist
  */
 export type DenomArg = Brand | Denom;
 
-export type Proto3JSONMsg = {
-  '@type': TypeUrl;
-  value: Record<string, unknown>;
-};
 /** An address on some blockchain, e.g., cosmos, eth, etc. */
 export type ChainAddress = {
   /** e.g. 1 for Ethereum, agoric-3 for Agoric, cosmoshub-4 for Cosmos */
@@ -91,13 +79,6 @@ export type ChainAddress = {
   addressEncoding: 'bech32' | 'ethereum';
 };
 
-/** An address for a validator on some blockchain, e.g., cosmos, eth, etc. */
-export type CosmosValidatorAddress = ChainAddress & {
-  // TODO document why this is the format
-  address: `${string}valoper${string}`;
-  addressEncoding: 'bech32';
-};
-
 /** Details for setup will be determined in the implementation. */
 export interface OrchestrationGovernor {
   registerChain: (
@@ -164,36 +145,6 @@ export type OrchestrationHandlerMaker = <C extends object>(
   fn: (orc: Orchestrator, ctx2: C, ...args) => object,
 ) => (...args) => object;
 
-/**
- * Info for a Cosmos-based chain.
- */
-export type CosmosChainInfo = {
-  chainId: string;
-  ibcConnectionInfo: {
-    id: string; // e.g. connection-0
-    client_id: string; // '07-tendermint-0'
-    state: 'OPEN' | 'TRYOPEN' | 'INIT' | 'CLOSED';
-    counterparty: {
-      client_id: string;
-      connection_id: string;
-      prefix: {
-        key_prefix: string;
-      };
-    };
-    versions: { identifier: string; features: string[] }[];
-    delay_period: bigint;
-  };
-  icaEnabled: boolean;
-  icqEnabled: boolean;
-  pfmEnabled: boolean;
-  ibcHooksEnabled: boolean;
-  /**
-   *
-   */
-  allowedMessages: TypeUrl[];
-  allowedQueries: TypeUrl[];
-};
-
 export type ChainInfo = CosmosChainInfo | EthChainInfo;
 
 // marker interface
@@ -233,140 +184,6 @@ export interface Chain<C extends keyof KnownChains> {
   getLocalDenom: (denom: DenomArg) => Promise<Denom>;
 }
 
-/**
- * Low level object that supports queries and operations for an account on a remote chain.
- */
-export interface ChainAccount {
-  /**
-   * @returns the address of the account on the remote chain
-   */
-  getAddress: () => ChainAddress;
-  /**
-   * Submit a transaction on behalf of the remote account for execution on the remote chain.
-   * @param msgs - records for the transaction
-   * @returns acknowledgement string
-   */
-  executeTx: (msgs: Proto3JSONMsg[]) => Promise<string>;
-  /**
-   * Submit a transaction on behalf of the remote account for execution on the remote chain.
-   * @param {AnyJson[]} msgs - records for the transaction
-   * @param {Partial<Omit<TxBody, 'messages'>>} [opts] - optional parameters for the Tx, like `timeoutHeight` and `memo`
-   * @returns acknowledgement string
-   */
-  executeEncodedTx: (
-    msgs: AnyJson[],
-    opts?: Partial<Omit<TxBody, 'messages'>>,
-  ) => Promise<string>;
-  /** deposit payment from zoe to the account*/
-  deposit: (payment: Payment) => Promise<void>;
-  /** get Purse for a brand to .withdraw() a Payment from the account */
-  getPurse: (brand: Brand) => Promise<Purse>;
-  /**
-   * Close the remote account
-   */
-  close: () => Promise<void>;
-  /* transfer account to new holder */
-  prepareTransfer: () => Promise<Invitation>;
-  /** @returns the address of the remote channel */
-  getRemoteAddress: () => RemoteIbcAddress;
-  /** @returns the address of the local channel */
-  getLocalAddress: () => LocalIbcAddress;
-  /** @returns the port the ICA channel is bound to */
-  getPort: () => Port;
-}
-
-export interface StakingAccountQueries {
-  /**
-   * @returns all active delegations from the account to any validator (or [] if none)
-   */
-  getDelegations: () => Promise<Delegation[]>;
-
-  /**
-   * @returns the active delegation from the account to a specific validator. Return an
-   * empty Delegation if there is no delegation.
-   */
-  getDelegation: (validator: CosmosValidatorAddress) => Promise<Delegation>;
-
-  /**
-   * @returns the unbonding delegations from the account to any validator (or [] if none)
-   */
-  getUnbondingDelegations: () => Promise<UnbondingDelegation[]>;
-
-  /**
-   * @returns the unbonding delegations from the account to a specific validator (or [] if none)
-   */
-  getUnbondingDelegation: (
-    validator: CosmosValidatorAddress,
-  ) => Promise<UnbondingDelegation>;
-
-  getRedelegations: () => Promise<Redelegation[]>;
-
-  getRedelegation: (
-    srcValidator: CosmosValidatorAddress,
-    dstValidator?: CosmosValidatorAddress,
-  ) => Promise<Redelegation>;
-
-  /**
-   * Get the pending rewards for the account.
-   * @returns the amounts of the account's rewards pending from all validators
-   */
-  getRewards: () => Promise<ChainAmount[]>;
-
-  /**
-   * Get the rewards pending with a specific validator.
-   * @param validator - the validator address to query for
-   * @returns the amount of the account's rewards pending from a specific validator
-   */
-  getReward: (validator: CosmosValidatorAddress) => Promise<ChainAmount[]>;
-}
-export interface StakingAccountActions {
-  /**
-   * Delegate an amount to a validator. The promise settles when the delegation is complete.
-   * @param validator - the validator to delegate to
-   * @param amount  - the amount to delegate
-   * @returns void
-   */
-  delegate: (
-    validator: CosmosValidatorAddress,
-    amount: AmountArg,
-  ) => Promise<void>;
-
-  /**
-   * Redelegate from one delegator to another.
-   * Settles when the redelegation is established, not 21 days later.
-   * @param srcValidator - the current validator for the delegation.
-   * @param dstValidator - the validator that will receive the delegation.
-   * @param amount - how much to redelegate.
-   * @returns
-   */
-  redelegate: (
-    srcValidator: CosmosValidatorAddress,
-    dstValidator: CosmosValidatorAddress,
-    amount: AmountArg,
-  ) => Promise<void>;
-
-  /**
-   * Undelegate multiple delegations (concurrently). To delegate independently, pass an array with one item.
-   * Resolves when the undelegation is complete and the tokens are no longer bonded. Note it may take weeks.
-   * The unbonding time is padded by 10 minutes to account for clock skew.
-   * @param {Delegation[]} delegations - the delegation to undelegate
-   */
-  undelegate: (delegations: Delegation[]) => Promise<void>;
-
-  /**
-   * Withdraw rewards from all validators. The promise settles when the rewards are withdrawn.
-   * @returns The total amounts of rewards withdrawn
-   */
-  withdrawRewards: () => Promise<ChainAmount[]>;
-
-  /**
-   * Withdraw rewards from a specific validator. The promise settles when the rewards are withdrawn.
-   * @param validator - the validator to withdraw rewards from
-   * @returns
-   */
-  withdrawReward: (validator: CosmosValidatorAddress) => Promise<ChainAmount[]>;
-}
-
 /**
  * An object that supports high-level operations for an account on a remote chain.
  */
@@ -374,7 +191,7 @@ export interface BaseOrchestrationAccount
   extends StakingAccountQueries,
     StakingAccountActions {
   /** @returns the underlying low-level operation object. */
-  getChainAcccount: () => Promise<ChainAccount>;
+  getChainAcccount: () => Promise<IcaAccount>;
 
   /**
    * @returns the address of the account on the remote chain
diff --git a/packages/orchestration/test/staking-ops.test.js b/packages/orchestration/test/staking-ops.test.js
index a178d008ca8..cfaab0d36c6 100644
--- a/packages/orchestration/test/staking-ops.test.js
+++ b/packages/orchestration/test/staking-ops.test.js
@@ -20,7 +20,7 @@ import {
 } from '../src/exos/stakingAccountKit.js';
 
 /**
- * @import {ChainAccount, ChainAddress, ICQConnection} from '../src/types.js';
+ * @import {IcaAccount, ChainAddress, ICQConnection} from '../src/types.js';
  * @import { Coin } from '@agoric/cosmic-proto/cosmos/base/v1beta1/coin.js';
  */
 
@@ -130,7 +130,7 @@ const makeScenario = () => {
       chainId: 'FIXME',
     });
 
-    /** @type {ChainAccount} */
+    /** @type {IcaAccount} */
     const account = Far('MockAccount', {
       getAddress: () => chainAddress,
       executeEncodedTx: async msgs => {

From 8fd74d08247fb976d9a376cf084368592cc52dc4 Mon Sep 17 00:00:00 2001
From: Turadg Aleahmad <turadg@agoric.com>
Date: Thu, 9 May 2024 16:02:46 -0700
Subject: [PATCH 06/14] feat(types): orchestrate() generic

refactor(types): Chain, OrchestrationAccount
---
 .../src/examples/swapExample.contract.js      |   4 +-
 .../src/examples/unbondExample.contract.js    |   2 +-
 .../src/exos/stakingAccountKit.js             |   4 +-
 packages/orchestration/src/facade.js          |   9 +-
 .../orchestration/src/orchestration-api.ts    | 188 ++++++++++++++
 packages/orchestration/src/types.ts           | 235 +-----------------
 6 files changed, 204 insertions(+), 238 deletions(-)
 create mode 100644 packages/orchestration/src/orchestration-api.ts

diff --git a/packages/orchestration/src/examples/swapExample.contract.js b/packages/orchestration/src/examples/swapExample.contract.js
index 75f18930222..7b4280890b6 100644
--- a/packages/orchestration/src/examples/swapExample.contract.js
+++ b/packages/orchestration/src/examples/swapExample.contract.js
@@ -6,7 +6,7 @@ import { makeOrchestrationFacade } from '../facade.js';
 import { orcUtils } from '../utils/orc.js';
 
 /**
- * @import {Orchestrator, ChainAccount, CosmosValidatorAddress} from '../types.js'
+ * @import {Orchestrator, IcaAccount, CosmosValidatorAddress} from '../types.js'
  * @import {TimerService} from '@agoric/time';
  * @import {ERef} from '@endo/far'
  * @import {OrchestrationService} from '../service.js';
@@ -34,7 +34,7 @@ export const start = async (zcf, privateArgs) => {
   });
 
   /** deprecated historical example */
-  /** @type {OfferHandler} */
+  /** @type {OfferHandler<unknown, {staked: Amount<'nat'>, validator: CosmosValidatorAddress}>} */
   const swapAndStakeHandler = orchestrate(
     'LSTTia',
     { zcf },
diff --git a/packages/orchestration/src/examples/unbondExample.contract.js b/packages/orchestration/src/examples/unbondExample.contract.js
index f688645288a..2e419149b01 100644
--- a/packages/orchestration/src/examples/unbondExample.contract.js
+++ b/packages/orchestration/src/examples/unbondExample.contract.js
@@ -5,7 +5,7 @@ import { M } from '@endo/patterns';
 import { makeOrchestrationFacade } from '../facade.js';
 
 /**
- * @import {Orchestrator, ChainAccount, CosmosValidatorAddress} from '../types.js'
+ * @import {Orchestrator, IcaAccount, CosmosValidatorAddress} from '../types.js'
  * @import {TimerService} from '@agoric/time';
  * @import {ERef} from '@endo/far'
  * @import {OrchestrationService} from '../service.js';
diff --git a/packages/orchestration/src/exos/stakingAccountKit.js b/packages/orchestration/src/exos/stakingAccountKit.js
index c1a3e2bae69..128c7034033 100644
--- a/packages/orchestration/src/exos/stakingAccountKit.js
+++ b/packages/orchestration/src/exos/stakingAccountKit.js
@@ -63,7 +63,7 @@ const { Fail } = assert;
  * }} State
  */
 
-export const ChainAccountHolderI = M.interface('ChainAccountHolder', {
+export const IcaAccountHolderI = M.interface('IcaAccountHolder', {
   getPublicTopics: M.call().returns(TopicsRecordShape),
   getAddress: M.call().returns(ChainAddressShape),
   getBalance: M.callWhen().optional(M.string()).returns(CoinShape),
@@ -146,7 +146,7 @@ export const prepareStakingAccountKit = (baggage, makeRecorderKit, zcf) => {
         getUpdater: M.call().returns(M.remotable()),
         amountToCoin: M.call(AmountShape).returns(M.record()),
       }),
-      holder: ChainAccountHolderI,
+      holder: IcaAccountHolderI,
       invitationMakers: M.interface('invitationMakers', {
         Delegate: M.callWhen(ChainAddressShape, AmountShape).returns(
           InvitationShape,
diff --git a/packages/orchestration/src/facade.js b/packages/orchestration/src/facade.js
index 7d870db87cd..b2284f5c5be 100644
--- a/packages/orchestration/src/facade.js
+++ b/packages/orchestration/src/facade.js
@@ -4,7 +4,7 @@
  * @import {Zone} from '@agoric/zone';
  * @import {TimerService} from '@agoric/time';
  * @import {OrchestrationService} from './service.js';
- * @import {OrchestrationHandlerMaker} from './types.js';
+ * @import {Orchestrator} from './types.js';
  */
 
 /**
@@ -34,7 +34,12 @@ export const makeOrchestrationFacade = ({
 
   return {
     /**
-     * @type {OrchestrationHandlerMaker}
+     * @template Context
+     * @template {any[]} Args
+     * @param {string} durableName
+     * @param {Context} ctx
+     * @param {(orc: Orchestrator, ctx2: Context, ...args: Args) => object} fn
+     * @returns {(...args: Args) => Promise<unknown>}
      */
     orchestrate(durableName, ctx, fn) {
       console.log('orchestrate got', durableName, ctx, fn);
diff --git a/packages/orchestration/src/orchestration-api.ts b/packages/orchestration/src/orchestration-api.ts
new file mode 100644
index 00000000000..5d7909f058a
--- /dev/null
+++ b/packages/orchestration/src/orchestration-api.ts
@@ -0,0 +1,188 @@
+/* eslint-disable no-use-before-define */
+/**
+ * @file General API of orchestration
+ * - must not have chain-specific types without runtime narrowing by chain id
+ * - should remain relatively stable.
+ */
+import type { Amount, Brand } from '@agoric/ertp/exported.js';
+import type { LocalChainAccount } from '@agoric/vats/src/localchain.js';
+import type { Timestamp } from '@agoric/time';
+import type { KnownChains } from './types.js';
+
+/**
+ * A denom that designates a token type on some blockchain.
+ *
+ * Multiple denoms may designate the same underlying base denom (e.g., `uist`,
+ * `uatom`) on different Chains or on the same Chain via different paths. On
+ * Cosmos chains, all but the base denom are IBC style denoms, but that may vary
+ * across other chains. All the denoms that designate the same underlying base
+ * denom form an equivalence class, along with the unique Brand on the local
+ * Chain. Some operations accept any member of the equivalence class to
+ * effectively designate the corresponding token type on the target chain.
+ */
+export type Denom = string; // ibc/... or uist
+
+/**
+ * In many cases, either a denom string or a local Brand can be used to
+ * designate a remote token type.
+ */
+export type DenomArg = Denom | Brand;
+
+/**
+ * Count of some fungible token on some blockchain.
+ *
+ * NB: this is not an instance of the `Amount` type from ERTP but can be
+ * converted to one surjectively
+ */
+export type ChainAmount = {
+  denom: Denom;
+  value: bigint; // Nat
+};
+
+/** Amounts can be provided as pure data using denoms or as native Amounts */
+export type AmountArg = ChainAmount | Amount;
+
+/** An address on some blockchain, e.g., cosmos, eth, etc. */
+export type ChainAddress = {
+  /** e.g. 1 for Ethereum, agoric-3 for Agoric, cosmoshub-4 for Cosmos */
+  chainId: string;
+  address: string;
+  // TODO what's the right way to scope the address? it's not chainId
+  addressEncoding: 'bech32' | 'ethereum';
+};
+
+export type OrchestrationAccount<C extends keyof KnownChains> =
+  OrchestrationAccountI & KnownChains[C]['methods'];
+
+/**
+ * An object for access the core functions of a remote chain.
+ *
+ * Note that "remote" can mean the local chain; it's just that
+ * accounts are treated as remote/arms length for consistency.
+ */
+export interface Chain<C extends keyof KnownChains> {
+  getChainInfo: () => Promise<KnownChains[C]['info']>;
+
+  // "makeAccount" suggests an operation within a vat
+  /**
+   * Creates a new account on the remote chain.
+   * @returns an object that controls a new remote account on Chain
+   */
+  makeAccount: () => Promise<OrchestrationAccount<C>>;
+  // FUTURE supply optional port object; also fetch port object
+
+  // TODO provide a way to get the local denom/brand/whatever for this chain
+}
+
+/**
+ * Provided in the callback to `orchestrate()`.
+ */
+export interface Orchestrator {
+  // TODO we need a way to work with a chain its native way vs generic way
+  // E.g. an Osmosis delegate that looks Cosmos-y or no different from an Ethereum delegate
+  getChain: <C extends keyof KnownChains>(chainName: C) => Promise<Chain<C>>;
+
+  makeLocalAccount: () => Promise<LocalChainAccount>;
+  /**
+   * For a denom, return information about a denom including the equivalent
+   * local Brand, the Chain on which the denom is held, and the Chain that
+   * issues the corresponding asset.
+   * @param denom
+   */
+  getBrandInfo: <
+    HoldingChain extends keyof KnownChains,
+    IssuingChain extends keyof KnownChains,
+  >(
+    denom: Denom,
+  ) => {
+    /** The well-known Brand on Agoric for the direct asset */
+    brand?: Brand;
+    /** The Chain at which the argument `denom` exists (where the asset is currently held) */
+    chain: Chain<HoldingChain>;
+    /** The Chain that is the issuer of the underlying asset */
+    base: Chain<IssuingChain>;
+    /** the Denom for the underlying asset on its issuer chain */
+    baseDenom: Denom;
+  };
+  /**
+   * Convert an amount described in native data to a local, structured Amount.
+   * @param amount - the described amount
+   * @returns the Amount in local structuerd format
+   */
+  asAmount: (amount: ChainAmount) => Amount;
+}
+
+/**
+ * An object that supports high-level operations for an account on a remote chain.
+ */
+export interface OrchestrationAccountI {
+  /**
+   * @returns the address of the account on the remote chain
+   */
+  getAddress: () => ChainAddress;
+
+  /** @returns an array of amounts for every balance in the account. */
+  getBalances: () => Promise<ChainAmount[]>;
+
+  /** @returns the balance of a specific denom for the account. */
+  getBalance: (denom: DenomArg) => Promise<ChainAmount>;
+
+  /**
+   * Transfer amount to another account on the same chain. The promise settles when the transfer is complete.
+   * @param toAccount - the account to send the amount to. MUST be on the same chain
+   * @param amount - the amount to send
+   * @returns void
+   */
+  send: (toAccount: ChainAddress, amount: AmountArg) => Promise<void>;
+
+  /**
+   * Transfer an amount to another account, typically on another chain.
+   * The promise settles when the transfer is complete.
+   * @param amount - the amount to transfer.
+   * @param destination - the account to transfer the amount to.
+   * @param memo - an optional memo to include with the transfer, which could drive custom PFM behavior
+   * @returns void
+   *
+   * TODO document the mapping from the address to the destination chain.
+   */
+  transfer: (
+    amount: AmountArg,
+    destination: ChainAddress,
+    memo?: string,
+  ) => Promise<void>;
+
+  /**
+   * Transfer an amount to another account in multiple steps. The promise settles when
+   * the entire path of the transfer is complete.
+   * @param amount - the amount to transfer
+   * @param msg - the transfer message, including follow-up steps
+   * @returns void
+   */
+  transferSteps: (amount: AmountArg, msg: TransferMsg) => Promise<void>;
+  /**
+   * deposit payment from zoe to the account. For remote accounts,
+   * an IBC Transfer will be executed to transfer funds there.
+   */
+  deposit: (payment: Payment) => Promise<void>;
+}
+
+/**
+ * Internal structure for TransferMsgs.
+ * The type must be able to express transfers across different chains and transports.
+ *
+ * NOTE Expected to change, so consider an opaque structure.
+ */
+export type TransferMsg = {
+  toAccount: ChainAddress;
+  timeout?: Timestamp;
+  next?: TransferMsg;
+  data?: object;
+};
+
+export type AfterAction = { destChain: string; destAddress: ChainAddress };
+export type SwapExact = { amountIn: Amount; amountOut: Amount };
+export type SwapMaxSlippage = {
+  amountIn: Amount;
+  brandOut: Brand;
+  slippage: number;
+};
diff --git a/packages/orchestration/src/types.ts b/packages/orchestration/src/types.ts
index aa7e5fb694e..15915dab853 100644
--- a/packages/orchestration/src/types.ts
+++ b/packages/orchestration/src/types.ts
@@ -1,26 +1,16 @@
+/* eslint-disable no-use-before-define -- fine for types */
 // Ambients
 import '@agoric/zoe/exported.js';
 
-import { MsgTransferResponse } from '@agoric/cosmic-proto/ibc/applications/transfer/v1/tx.js';
-import type { Amount, Brand, Payment } from '@agoric/ertp/exported.js';
-import type { Timestamp } from '@agoric/time';
-import type { IBCConnectionID } from '@agoric/vats';
-import type { LocalChainAccount } from '@agoric/vats/src/localchain.js';
+import type { CosmosChainInfo, LiquidStakingMethods } from './cosmos-api.js';
 import type { EthChainInfo } from './ethereum-api.js';
-import type { ICQConnection } from './exos/icqConnectionKit.js';
-import type {
-  CosmosChainInfo,
-  Proto3JSONMsg,
-  StakingAccountQueries,
-  StakingAccountActions,
-  IcaAccount,
-  LiquidStakingMethods,
-} from './cosmos-api.js';
+import { ChainAddress, DenomArg, TransferMsg } from './orchestration-api.js';
 
 export type * from './cosmos-api.js';
 export type * from './ethereum-api.js';
 export type * from './exos/chainAccountKit.js';
 export type * from './exos/icqConnectionKit.js';
+export type * from './orchestration-api.js';
 export type * from './service.js';
 export type * from './vat-orchestration.js';
 
@@ -51,220 +41,11 @@ export type KnownChains = {
   osmosis: { info: CosmosChainInfo; methods: {} };
 };
 
-/**
- * A denom that designates a token type on some blockchain.
- *
- * Multiple denoms may designate the same underlying base denom (e.g., `uist`,
- * `uatom`) on different Chains or on the same Chain via different paths. On
- * Cosmos chains, all but the base denom are IBC style denoms, but that may vary
- * across other chains. All the denoms that designate the same underlying base
- * denom form an equivalence class, along with the unique Brand on the local
- * Chain. Some operations accept any member of the equivalence class to
- * effectively designate the corresponding token type on the target chain.
- */
-export type Denom = string; // ibc/... or uist
-
-/**
- * In many cases, either a denom string or a local Brand can be used to
- * designate a remote token type.
- */
-export type DenomArg = Brand | Denom;
-
-/** An address on some blockchain, e.g., cosmos, eth, etc. */
-export type ChainAddress = {
-  /** e.g. 1 for Ethereum, agoric-3 for Agoric, cosmoshub-4 for Cosmos */
-  chainId: string;
-  address: string;
-  // TODO what's the right way to scope the address? it's not chainId
-  addressEncoding: 'bech32' | 'ethereum';
-};
-
-/** Details for setup will be determined in the implementation. */
-export interface OrchestrationGovernor {
-  registerChain: (
-    chainName: string,
-    info: ChainInfo,
-    methods?: Record<string, any>,
-  ) => Promise<void>;
-}
-
-/** Description for an amount of some fungible currency */
-export type ChainAmount = {
-  denom: Denom;
-  value: bigint; // Nat
-};
-
-/** Amounts can be provided as pure data using denoms or as native Amounts */
-export type AmountArg = ChainAmount | Amount;
-
-// chainName: managed like agoricNames. API consumers can make/provide their own
-export interface Orchestrator {
-  getChain: <C extends keyof KnownChains>(chainName: C) => Promise<Chain<C>>;
-
-  makeLocalAccount: () => Promise<LocalChainAccount>;
-  /** Send queries to ibc chains unknown to KnownChains */
-  provideICQConnection: (
-    controllerConnectionId: IBCConnectionID,
-  ) => ICQConnection;
-
-  /**
-   * For a denom, return information about a denom including the equivalent
-   * local Brand, the Chain on which the denom is held, and the Chain that
-   * issues the corresponding asset.
-   * @param denom
-   */
-  getBrandInfo: <
-    HoldingChain extends keyof KnownChains,
-    IssuingChain extends keyof KnownChains,
-  >(
-    denom: Denom,
-  ) => {
-    /** The well-known Brand on Agoric for the direct asset */
-    brand?: Brand;
-    /** The Chain at which the argument `denom` exists (where the asset is currently held) */
-    chain: Chain<HoldingChain>;
-    /** The Chain that is the issuer of the underlying asset */
-    base: Chain<IssuingChain>;
-    /** the Denom for the underlying asset on its issuer chain */
-    baseDenom: Denom;
-  };
-  /**
-   * Convert an amount described in native data to a local, structured Amount.
-   * @param amount - the described amount
-   * @returns the Amount in local structuerd format
-   */
-  asAmount: (amount: ChainAmount) => Amount;
-}
-
-// orchestrate('LSTTia', { zcf }, async (orch, { zcf }, seat, offerArgs) => {...})
-// export type OrchestrationHandlerMaker<Context> =
-// TODO @turadg add typed so that the ctx object and args are consistently typed
-export type OrchestrationHandlerMaker = <C extends object>(
-  durableName: string,
-  ctx: C,
-  fn: (orc: Orchestrator, ctx2: C, ...args) => object,
-) => (...args) => object;
-
 export type ChainInfo = CosmosChainInfo | EthChainInfo;
 
 // marker interface
 interface QueryResult {}
 
-/**
- * An object for access the core functions of a remote chain.
- *
- * Note that "remote" can mean the local chain; it's just that
- * accounts are treated as remote/arms length for consistency.
- */
-export interface Chain<C extends keyof KnownChains> {
-  getChainInfo: () => Promise<KnownChains[C]['info']>;
-
-  // "makeAccount" suggests an operation within a vat
-  /**
-   * Creates a new account on the remote chain.
-   * @returns an object that controls a new remote account on Chain
-   */
-  makeAccount: () => Promise<OrchestrationAccount<C>>;
-  // FUTURE supply optional port object; also fetch port object
-
-  /**
-   * Low level operation to query external chain state (e.g., governance params)
-   * @param queries
-   * @returns
-   *
-   */
-  query: (queries: Proto3JSONMsg[]) => Promise<Iterable<QueryResult>>;
-
-  /**
-   * Get the Denom on this Chain corresponding to the denom or Brand on
-   * this or another Chain.
-   * @param denom
-   * @returns
-   */
-  getLocalDenom: (denom: DenomArg) => Promise<Denom>;
-}
-
-/**
- * An object that supports high-level operations for an account on a remote chain.
- */
-export interface BaseOrchestrationAccount
-  extends StakingAccountQueries,
-    StakingAccountActions {
-  /** @returns the underlying low-level operation object. */
-  getChainAcccount: () => Promise<IcaAccount>;
-
-  /**
-   * @returns the address of the account on the remote chain
-   */
-  getAddress: () => ChainAddress;
-
-  /** @returns an array of amounts for every balance in the account. */
-  getBalances: () => Promise<ChainAmount[]>;
-
-  /** @returns the balance of a specific denom for the account. */
-  getBalance: (denom: DenomArg) => Promise<ChainAmount>;
-
-  getDenomTrace: (
-    denom: string,
-  ) => Promise<{ path: string; base_denom: string }>;
-
-  /**
-   * Transfer amount to another account on the same chain. The promise settles when the transfer is complete.
-   * @param toAccount - the account to send the amount to. MUST be on the same chain
-   * @param amount - the amount to send
-   * @returns void
-   */
-  send: (toAccount: ChainAddress, amount: AmountArg) => Promise<void>;
-
-  /**
-   * Transfer an amount to another account, typically on another chain.
-   * The promise settles when the transfer is complete.
-   * @param amount - the amount to transfer.
-   * @param destination - the account to transfer the amount to.
-   * @param memo - an optional memo to include with the transfer, which could drive custom PFM behavior
-   * @returns void
-   *
-   * TODO document the mapping from the address to the destination chain.
-   */
-  transfer: (
-    amount: AmountArg,
-    destination: ChainAddress,
-    memo?: string,
-  ) => Promise<MsgTransferResponse>;
-
-  /**
-   * Transfer an amount to another account in multiple steps. The promise settles when
-   * the entire path of the transfer is complete.
-   * @param amount - the amount to transfer
-   * @param msg - the transfer message, including follow-up steps
-   * @returns void
-   */
-  transferSteps: (
-    amount: AmountArg,
-    msg: TransferMsg,
-  ) => Promise<MsgTransferResponse>;
-  /**
-   * deposit payment from zoe to the account. For remote accounts,
-   * an IBC Transfer will be executed to transfer funds there.
-   */
-  deposit: (payment: Payment) => Promise<void>;
-}
-
-export type OrchestrationAccount<C extends keyof KnownChains> =
-  BaseOrchestrationAccount & KnownChains[C]['methods'];
-
-/**
- * Internal structure for TransferMsgs.
- *
- * NOTE Expected to change, so consider an opaque structure.
- */
-export type TransferMsg = {
-  toAccount: ChainAddress;
-  timeout?: Timestamp;
-  next?: TransferMsg;
-  data?: object;
-};
-
 /**
  * @param pool - Required. Pool number
  * @example
@@ -287,11 +68,3 @@ export type OsmoSwapFn = (
   options: Partial<OsmoSwapOptions>,
   next: TransferMsg | ChainAddress,
 ) => TransferMsg;
-
-export type AfterAction = { destChain: string; destAddress: ChainAddress };
-export type SwapExact = { amountIn: Amount; amountOut: Amount };
-export type SwapMaxSlippage = {
-  amountIn: Amount;
-  brandOut: Brand;
-  slippage: number;
-};

From fef4f2d696ef17a30023e2a19844b424b4c861dc Mon Sep 17 00:00:00 2001
From: Turadg Aleahmad <turadg@agoric.com>
Date: Tue, 14 May 2024 06:59:25 -0700
Subject: [PATCH 07/14] refactor(types): extract chain-info module

---
 packages/orchestration/src/chain-info.ts | 64 ++++++++++++++++++++++++
 packages/orchestration/src/cosmos-api.ts |  4 --
 packages/orchestration/src/types.ts      | 32 +-----------
 3 files changed, 65 insertions(+), 35 deletions(-)
 create mode 100644 packages/orchestration/src/chain-info.ts

diff --git a/packages/orchestration/src/chain-info.ts b/packages/orchestration/src/chain-info.ts
new file mode 100644
index 00000000000..bb729352588
--- /dev/null
+++ b/packages/orchestration/src/chain-info.ts
@@ -0,0 +1,64 @@
+/**
+ * @file static declaration of known chain types will allow type support for
+ * additional chain-specific operations like `liquidStake`
+ */
+
+import type {
+  CosmosChainInfo,
+  EthChainInfo,
+  IcaAccount,
+  ICQConnection,
+  LiquidStakingMethods,
+  StakingAccountActions,
+  StakingAccountQueries,
+} from './types.js';
+
+// TODO generate this automatically with a build script drawing on data sources such as https://github.com/cosmos/chain-registry
+
+// XXX methods ad-hoc and not fully accurate
+export type KnownChains = {
+  stride: {
+    info: CosmosChainInfo;
+    methods: IcaAccount &
+      ICQConnection &
+      StakingAccountActions &
+      StakingAccountQueries &
+      LiquidStakingMethods;
+  };
+  cosmos: {
+    info: CosmosChainInfo;
+    methods: IcaAccount &
+      ICQConnection &
+      StakingAccountActions &
+      StakingAccountQueries;
+  };
+  agoric: {
+    info: CosmosChainInfo;
+    methods: {
+      // TODO reference type from #8624 `packages/vats/src/localchain.js`
+      /**
+       * Register a hook to intercept an incoming IBC Transfer and handle it.
+       * Calling without arguments will unregister the hook.
+       */
+      interceptTransfer: (tap?: {
+        upcall: (args: any) => Promise<any>;
+      }) => Promise<void>;
+    };
+  };
+  celestia: {
+    info: CosmosChainInfo;
+    methods: IcaAccount &
+      ICQConnection &
+      StakingAccountActions &
+      StakingAccountQueries;
+  };
+  osmosis: {
+    info: CosmosChainInfo;
+    methods: IcaAccount &
+      ICQConnection &
+      StakingAccountActions &
+      StakingAccountQueries;
+  };
+};
+
+export type ChainInfo = CosmosChainInfo | EthChainInfo;
diff --git a/packages/orchestration/src/cosmos-api.ts b/packages/orchestration/src/cosmos-api.ts
index db1a55d30bf..50a685d7483 100644
--- a/packages/orchestration/src/cosmos-api.ts
+++ b/packages/orchestration/src/cosmos-api.ts
@@ -12,10 +12,6 @@ import type {
   RemoteIbcAddress,
 } from '@agoric/vats/tools/ibc-utils.js';
 import type { AmountArg, ChainAddress, ChainAmount } from './types.js';
-import type {
-  MsgBeginRedelegateResponse,
-  MsgUndelegateResponse,
-} from '@agoric/cosmic-proto/cosmos/staking/v1beta1/tx.js';
 
 /** A helper type for type extensions. */
 export type TypeUrl = string;
diff --git a/packages/orchestration/src/types.ts b/packages/orchestration/src/types.ts
index 15915dab853..5703f41f4f7 100644
--- a/packages/orchestration/src/types.ts
+++ b/packages/orchestration/src/types.ts
@@ -2,10 +2,9 @@
 // Ambients
 import '@agoric/zoe/exported.js';
 
-import type { CosmosChainInfo, LiquidStakingMethods } from './cosmos-api.js';
-import type { EthChainInfo } from './ethereum-api.js';
 import { ChainAddress, DenomArg, TransferMsg } from './orchestration-api.js';
 
+export type * from './chain-info.js';
 export type * from './cosmos-api.js';
 export type * from './ethereum-api.js';
 export type * from './exos/chainAccountKit.js';
@@ -14,35 +13,6 @@ export type * from './orchestration-api.js';
 export type * from './service.js';
 export type * from './vat-orchestration.js';
 
-/**
- * static declaration of known chain types will allow type support for
- * additional chain-specific operations like `liquidStake`
- */
-export type KnownChains = {
-  stride: {
-    info: CosmosChainInfo;
-    methods: LiquidStakingMethods;
-  };
-  cosmos: { info: CosmosChainInfo; methods: {} };
-  agoric: {
-    info: Omit<CosmosChainInfo, 'ibcConnectionInfo'>;
-    methods: {
-      // TODO reference type from #8624 `packages/vats/src/localchain.js`
-      /**
-       * Register a hook to intercept an incoming IBC Transfer and handle it.
-       * Calling without arguments will unregister the hook.
-       */
-      interceptTransfer: (tap?: {
-        upcall: (args: any) => Promise<any>;
-      }) => Promise<void>;
-    };
-  };
-  celestia: { info: CosmosChainInfo; methods: {} };
-  osmosis: { info: CosmosChainInfo; methods: {} };
-};
-
-export type ChainInfo = CosmosChainInfo | EthChainInfo;
-
 // marker interface
 interface QueryResult {}
 

From b2546d4d3c2be09776ffe8f257284f9dfdf26ea5 Mon Sep 17 00:00:00 2001
From: Turadg Aleahmad <turadg@agoric.com>
Date: Tue, 14 May 2024 06:52:36 -0700
Subject: [PATCH 08/14] chore(types): asAmount returns Nat

---
 packages/orchestration/src/orchestration-api.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/orchestration/src/orchestration-api.ts b/packages/orchestration/src/orchestration-api.ts
index 5d7909f058a..9eb452d3cea 100644
--- a/packages/orchestration/src/orchestration-api.ts
+++ b/packages/orchestration/src/orchestration-api.ts
@@ -4,7 +4,7 @@
  * - must not have chain-specific types without runtime narrowing by chain id
  * - should remain relatively stable.
  */
-import type { Amount, Brand } from '@agoric/ertp/exported.js';
+import type { Amount, Brand, NatAmount } from '@agoric/ertp/exported.js';
 import type { LocalChainAccount } from '@agoric/vats/src/localchain.js';
 import type { Timestamp } from '@agoric/time';
 import type { KnownChains } from './types.js';
@@ -109,7 +109,7 @@ export interface Orchestrator {
    * @param amount - the described amount
    * @returns the Amount in local structuerd format
    */
-  asAmount: (amount: ChainAmount) => Amount;
+  asAmount: (amount: ChainAmount) => NatAmount;
 }
 
 /**

From a51db10a074064327cebbb9ae1d65a23825e1f74 Mon Sep 17 00:00:00 2001
From: Turadg Aleahmad <turadg@agoric.com>
Date: Tue, 14 May 2024 07:08:59 -0700
Subject: [PATCH 09/14] refactor(types): rollup module

---
 packages/orchestration/index.js     |  1 -
 packages/orchestration/src/types.ts | 32 +----------------------------
 2 files changed, 1 insertion(+), 32 deletions(-)

diff --git a/packages/orchestration/index.js b/packages/orchestration/index.js
index 4db591ddc0b..d5173404ac0 100644
--- a/packages/orchestration/index.js
+++ b/packages/orchestration/index.js
@@ -1,4 +1,3 @@
-// eslint-disable-next-line import/export
 export * from './src/types.js';
 export * from './src/service.js';
 export * from './src/typeGuards.js';
diff --git a/packages/orchestration/src/types.ts b/packages/orchestration/src/types.ts
index 5703f41f4f7..151bf3bb83b 100644
--- a/packages/orchestration/src/types.ts
+++ b/packages/orchestration/src/types.ts
@@ -1,8 +1,4 @@
-/* eslint-disable no-use-before-define -- fine for types */
-// Ambients
-import '@agoric/zoe/exported.js';
-
-import { ChainAddress, DenomArg, TransferMsg } from './orchestration-api.js';
+/** @file Rollup of all type definitions in the package, for local import and external export */
 
 export type * from './chain-info.js';
 export type * from './cosmos-api.js';
@@ -12,29 +8,3 @@ export type * from './exos/icqConnectionKit.js';
 export type * from './orchestration-api.js';
 export type * from './service.js';
 export type * from './vat-orchestration.js';
-
-// marker interface
-interface QueryResult {}
-
-/**
- * @param pool - Required. Pool number
- * @example
- * await icaNoble.transferSteps(usdcAmt,
- *  osmosisSwap(tiaBrand, { pool: 1224, slippage: 0.05 }, icaCel.getAddress()));
- */
-export type OsmoSwapOptions = {
-  pool: string;
-  slippage?: Number;
-};
-
-/**
- * Make a TransferMsg for a swap operation.
- * @param denom - the currency to swap to
- * @param options
- * @param slippage - the maximum acceptable slippage
- */
-export type OsmoSwapFn = (
-  denom: DenomArg,
-  options: Partial<OsmoSwapOptions>,
-  next: TransferMsg | ChainAddress,
-) => TransferMsg;

From 29baf90b5c188cc25b859b9898180a39047eaf2d Mon Sep 17 00:00:00 2001
From: Turadg Aleahmad <turadg@agoric.com>
Date: Tue, 14 May 2024 16:25:39 -0700
Subject: [PATCH 10/14] docs: clarify Denom

---
 packages/orchestration/src/orchestration-api.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/orchestration/src/orchestration-api.ts b/packages/orchestration/src/orchestration-api.ts
index 9eb452d3cea..ccce2aae0b8 100644
--- a/packages/orchestration/src/orchestration-api.ts
+++ b/packages/orchestration/src/orchestration-api.ts
@@ -10,7 +10,7 @@ import type { Timestamp } from '@agoric/time';
 import type { KnownChains } from './types.js';
 
 /**
- * A denom that designates a token type on some blockchain.
+ * A denom that designates a path to a token type on some blockchain.
  *
  * Multiple denoms may designate the same underlying base denom (e.g., `uist`,
  * `uatom`) on different Chains or on the same Chain via different paths. On
@@ -22,6 +22,8 @@ import type { KnownChains } from './types.js';
  */
 export type Denom = string; // ibc/... or uist
 
+// ??? when multiple Denoms provide paths to the same remote token type,
+// should the brand be 1:1 with that equivalence class or each Denom?
 /**
  * In many cases, either a denom string or a local Brand can be used to
  * designate a remote token type.
@@ -104,6 +106,7 @@ export interface Orchestrator {
     /** the Denom for the underlying asset on its issuer chain */
     baseDenom: Denom;
   };
+  // TODO preload the mapping so this can be synchronous
   /**
    * Convert an amount described in native data to a local, structured Amount.
    * @param amount - the described amount

From 95ee056b9b0a3b48c0d33b969bc8794a01e97942 Mon Sep 17 00:00:00 2001
From: Turadg Aleahmad <turadg@agoric.com>
Date: Tue, 14 May 2024 07:14:41 -0700
Subject: [PATCH 11/14] =?UTF-8?q?refactor:=20ChainAmount=20=E2=86=92=20Den?=
 =?UTF-8?q?omAmount?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/orchestration/src/cosmos-api.ts         | 10 +++++-----
 .../orchestration/src/exos/stakingAccountKit.js  | 16 ++++++++--------
 packages/orchestration/src/orchestration-api.ts  | 13 ++++++-------
 3 files changed, 19 insertions(+), 20 deletions(-)

diff --git a/packages/orchestration/src/cosmos-api.ts b/packages/orchestration/src/cosmos-api.ts
index 50a685d7483..b158f41db4b 100644
--- a/packages/orchestration/src/cosmos-api.ts
+++ b/packages/orchestration/src/cosmos-api.ts
@@ -11,7 +11,7 @@ import type {
   LocalIbcAddress,
   RemoteIbcAddress,
 } from '@agoric/vats/tools/ibc-utils.js';
-import type { AmountArg, ChainAddress, ChainAmount } from './types.js';
+import type { AmountArg, ChainAddress, DenomAmount } from './types.js';
 
 /** A helper type for type extensions. */
 export type TypeUrl = string;
@@ -94,14 +94,14 @@ export interface StakingAccountQueries {
    * Get the pending rewards for the account.
    * @returns the amounts of the account's rewards pending from all validators
    */
-  getRewards: () => Promise<ChainAmount[]>;
+  getRewards: () => Promise<DenomAmount[]>;
 
   /**
    * Get the rewards pending with a specific validator.
    * @param validator - the validator address to query for
    * @returns the amount of the account's rewards pending from a specific validator
    */
-  getReward: (validator: CosmosValidatorAddress) => Promise<ChainAmount[]>;
+  getReward: (validator: CosmosValidatorAddress) => Promise<DenomAmount[]>;
 }
 export interface StakingAccountActions {
   /**
@@ -141,14 +141,14 @@ export interface StakingAccountActions {
    * Withdraw rewards from all validators. The promise settles when the rewards are withdrawn.
    * @returns The total amounts of rewards withdrawn
    */
-  withdrawRewards: () => Promise<ChainAmount[]>;
+  withdrawRewards: () => Promise<DenomAmount[]>;
 
   /**
    * Withdraw rewards from a specific validator. The promise settles when the rewards are withdrawn.
    * @param validator - the validator to withdraw rewards from
    * @returns
    */
-  withdrawReward: (validator: CosmosValidatorAddress) => Promise<ChainAmount[]>;
+  withdrawReward: (validator: CosmosValidatorAddress) => Promise<DenomAmount[]>;
 }
 
 /**
diff --git a/packages/orchestration/src/exos/stakingAccountKit.js b/packages/orchestration/src/exos/stakingAccountKit.js
index 128c7034033..c019cda7d5e 100644
--- a/packages/orchestration/src/exos/stakingAccountKit.js
+++ b/packages/orchestration/src/exos/stakingAccountKit.js
@@ -35,7 +35,7 @@ import {
 export const maxClockSkew = 10n * 60n;
 
 /**
- * @import {AmountArg, IcaAccount, ChainAddress, ChainAmount, CosmosValidatorAddress, ICQConnection, StakingAccountActions} from '../types.js';
+ * @import {AmountArg, IcaAccount, ChainAddress, ChainAmount, CosmosValidatorAddress, ICQConnection, StakingAccountActions, DenomAmount} from '../types.js';
  * @import {RecorderKit, MakeRecorderKit} from '@agoric/zoe/src/contractSupport/recorder.js';
  * @import {Baggage} from '@agoric/swingset-liveslots';
  * @import {AnyJson} from '@agoric/cosmic-proto';
@@ -128,8 +128,8 @@ export const tryDecodeResponse = (ackStr, fromProtoMsg) => {
   }
 };
 
-/** @type {(c: { denom: string, amount: string }) => ChainAmount} */
-const toChainAmount = c => ({ denom: c.denom, value: BigInt(c.amount) });
+/** @type {(c: { denom: string, amount: string }) => DenomAmount} */
+const toDenomAmount = c => ({ denom: c.denom, value: BigInt(c.amount) });
 
 /**
  * @param {Baggage} baggage
@@ -341,7 +341,7 @@ export const prepareStakingAccountKit = (baggage, makeRecorderKit, zcf) => {
 
         /**
          * @param {CosmosValidatorAddress} validator
-         * @returns {Promise<ChainAmount[]>}
+         * @returns {Promise<DenomAmount[]>}
          */
         async withdrawReward(validator) {
           trace('withdrawReward', validator);
@@ -359,11 +359,11 @@ export const prepareStakingAccountKit = (baggage, makeRecorderKit, zcf) => {
           );
           trace('withdrawReward response', response);
           const { amount: coins } = response;
-          return harden(coins.map(toChainAmount));
+          return harden(coins.map(toDenomAmount));
         },
         /**
-         * @param {ChainAmount['denom']} [denom] - defaults to bondDenom
-         * @returns {Promise<ChainAmount>}
+         * @param {DenomAmount['denom']} [denom] - defaults to bondDenom
+         * @returns {Promise<DenomAmount>}
          */
         async getBalance(denom) {
           const { chainAddress, icqConnection, bondDenom } = this.state;
@@ -383,7 +383,7 @@ export const prepareStakingAccountKit = (baggage, makeRecorderKit, zcf) => {
             decodeBase64(result.key),
           );
           if (!balance) throw Fail`Result lacked balance key: ${result}`;
-          return harden(toChainAmount(balance));
+          return harden(toDenomAmount(balance));
         },
 
         withdrawRewards() {
diff --git a/packages/orchestration/src/orchestration-api.ts b/packages/orchestration/src/orchestration-api.ts
index ccce2aae0b8..9c37cb3d7ec 100644
--- a/packages/orchestration/src/orchestration-api.ts
+++ b/packages/orchestration/src/orchestration-api.ts
@@ -33,16 +33,15 @@ export type DenomArg = Denom | Brand;
 /**
  * Count of some fungible token on some blockchain.
  *
- * NB: this is not an instance of the `Amount` type from ERTP but can be
- * converted to one surjectively
+ * @see {@link Orchestrator.asAmount} to convert to an Amount surjectively
  */
-export type ChainAmount = {
+export type DenomAmount = {
   denom: Denom;
   value: bigint; // Nat
 };
 
 /** Amounts can be provided as pure data using denoms or as native Amounts */
-export type AmountArg = ChainAmount | Amount;
+export type AmountArg = DenomAmount | Amount;
 
 /** An address on some blockchain, e.g., cosmos, eth, etc. */
 export type ChainAddress = {
@@ -112,7 +111,7 @@ export interface Orchestrator {
    * @param amount - the described amount
    * @returns the Amount in local structuerd format
    */
-  asAmount: (amount: ChainAmount) => NatAmount;
+  asAmount: (amount: DenomAmount) => NatAmount;
 }
 
 /**
@@ -125,10 +124,10 @@ export interface OrchestrationAccountI {
   getAddress: () => ChainAddress;
 
   /** @returns an array of amounts for every balance in the account. */
-  getBalances: () => Promise<ChainAmount[]>;
+  getBalances: () => Promise<DenomAmount[]>;
 
   /** @returns the balance of a specific denom for the account. */
-  getBalance: (denom: DenomArg) => Promise<ChainAmount>;
+  getBalance: (denom: DenomArg) => Promise<DenomAmount>;
 
   /**
    * Transfer amount to another account on the same chain. The promise settles when the transfer is complete.

From df2fed70fa5cb7f5b53124d9c080d10f84663096 Mon Sep 17 00:00:00 2001
From: Turadg Aleahmad <turadg@agoric.com>
Date: Wed, 15 May 2024 09:09:45 -0700
Subject: [PATCH 12/14] build: consistent postpack

---
 packages/inter-protocol/package.json | 2 +-
 packages/notifier/package.json       | 2 +-
 packages/orchestration/package.json  | 1 +
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/inter-protocol/package.json b/packages/inter-protocol/package.json
index 1684b002c87..80a4f529a30 100644
--- a/packages/inter-protocol/package.json
+++ b/packages/inter-protocol/package.json
@@ -11,7 +11,7 @@
     "build": "yarn build:bundles",
     "build:bundles": "node ./scripts/build-bundles.js",
     "prepack": "tsc --build tsconfig.build.json",
-    "postpack": "git clean -f '*.d.ts*' src/types.js",
+    "postpack": "git clean -f '*.d.ts*'",
     "test": "ava",
     "test:c8": "c8 $C8_OPTIONS ava --config=ava-nesm.config.js",
     "test:xs": "exit 0",
diff --git a/packages/notifier/package.json b/packages/notifier/package.json
index 32e6eb33025..0c8133229dd 100644
--- a/packages/notifier/package.json
+++ b/packages/notifier/package.json
@@ -10,7 +10,7 @@
   "scripts": {
     "build": "exit 0",
     "prepack": "tsc --build tsconfig.build.json",
-    "postpack": "git clean -f '*.d.ts*' src/types.js",
+    "postpack": "git clean -f '*.d.ts*'",
     "test": "ava",
     "test:c8": "c8 $C8_OPTIONS ava --config=ava-nesm.config.js",
     "test:xs": "exit 0",
diff --git a/packages/orchestration/package.json b/packages/orchestration/package.json
index 7873105c800..9fae85e4378 100644
--- a/packages/orchestration/package.json
+++ b/packages/orchestration/package.json
@@ -11,6 +11,7 @@
   "scripts": {
     "build": "exit 0",
     "prepack": "tsc --build tsconfig.build.json",
+    "postpack": "git clean -f '*.d.ts*'",
     "test": "ava",
     "test:xs": "exit 0",
     "lint": "run-s --continue-on-error lint:*",

From d1a35d8054beb60538fca459f276aeb5526e094e Mon Sep 17 00:00:00 2001
From: Turadg Aleahmad <turadg@agoric.com>
Date: Wed, 15 May 2024 09:14:16 -0700
Subject: [PATCH 13/14] chore(types): more explicit imports

to fix build order sensitivity
---
 packages/orchestration/src/orchestration-api.ts | 7 ++++++-
 packages/vats/src/core/basic-behaviors.js       | 2 ++
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/packages/orchestration/src/orchestration-api.ts b/packages/orchestration/src/orchestration-api.ts
index 9c37cb3d7ec..0492bf457b5 100644
--- a/packages/orchestration/src/orchestration-api.ts
+++ b/packages/orchestration/src/orchestration-api.ts
@@ -4,7 +4,12 @@
  * - must not have chain-specific types without runtime narrowing by chain id
  * - should remain relatively stable.
  */
-import type { Amount, Brand, NatAmount } from '@agoric/ertp/exported.js';
+import type {
+  Amount,
+  Brand,
+  NatAmount,
+  Payment,
+} from '@agoric/ertp/exported.js';
 import type { LocalChainAccount } from '@agoric/vats/src/localchain.js';
 import type { Timestamp } from '@agoric/time';
 import type { KnownChains } from './types.js';
diff --git a/packages/vats/src/core/basic-behaviors.js b/packages/vats/src/core/basic-behaviors.js
index c5cc5dcee13..947b399bf21 100644
--- a/packages/vats/src/core/basic-behaviors.js
+++ b/packages/vats/src/core/basic-behaviors.js
@@ -17,6 +17,8 @@ import { makeNameHubKit } from '../nameHub.js';
 import { PowerFlags } from '../walletFlags.js';
 import { feeIssuerConfig, makeMyAddressNameAdminKit } from './utils.js';
 
+/** @import {GovernableStartFn, GovernanceFacetKit} from '@agoric/governance/src/types.js'; */
+
 const { details: X } = assert;
 
 /**

From 01e4ac29b9c9d7bda123cb337d71d139a9386db9 Mon Sep 17 00:00:00 2001
From: Turadg Aleahmad <turadg@agoric.com>
Date: Wed, 15 May 2024 09:22:30 -0700
Subject: [PATCH 14/14] ci: pack packages in PR tests

---
 .github/workflows/test-all-packages.yml | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/.github/workflows/test-all-packages.yml b/.github/workflows/test-all-packages.yml
index 51e109e4c7e..29c1b529d3f 100644
--- a/.github/workflows/test-all-packages.yml
+++ b/.github/workflows/test-all-packages.yml
@@ -48,9 +48,23 @@ jobs:
       - name: Install graphviz
         run: sudo apt install -y graphviz
 
+      # This is now redundant with Lerna's --reject-cycles but keep it here so we have
+      # test coverage of this script we use for visualizing the dep graph.
       - name: Check for cycles
         run: scripts/check-dependency-cycles.sh
 
+      # install node_modules
+      - uses: ./.github/actions/restore-node
+
+      # Releasing SDK builds all packages in this order during `lerna publish`.
+      # Due to ambient types, certain build orders (from the dependency graph)
+      # may break the type resolution. Run this in the PR to find out before
+      # attempting to merge to master. This takes about 1min locally and since
+      # this job is about 30s in CI doing it here doesn't add to wall wait
+      # for CI resolution.
+      - name: Pack packages
+        run: yarn lerna exec --reject-cycles --concurrency 1 "npm pack"
+
   ##################
   # Lint tests
   # We run per package bc of https://github.com/typescript-eslint/typescript-eslint/issues/1192