@agoric/orchestration 0.1.1-dev-4c65fc2.0 → 0.1.1-dev-76b8d53.0

package/index.js

@@ -2,4 +2,4 @@
 export * from './src/types.js';
 export * from './src/utils/address.js';
 export * from './src/utils/tx.js';
-export * from './src/orchestration.js';
+export * from './src/service.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/orchestration",
-  "version": "0.1.1-dev-4c65fc2.0+4c65fc2",
+  "version": "0.1.1-dev-76b8d53.0+76b8d53",
   "description": "Chain abstraction for Agoric's orchestration clients",
   "type": "module",
   "main": "index.js",
@@ -29,17 +29,18 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
-    "@agoric/assert": "0.6.1-dev-4c65fc2.0+4c65fc2",
-    "@agoric/cosmic-proto": "0.4.1-dev-4c65fc2.0+4c65fc2",
-    "@agoric/ertp": "0.16.3-dev-4c65fc2.0+4c65fc2",
-    "@agoric/internal": "0.3.3-dev-4c65fc2.0+4c65fc2",
-    "@agoric/network": "0.1.1-dev-4c65fc2.0+4c65fc2",
-    "@agoric/notifier": "0.6.3-dev-4c65fc2.0+4c65fc2",
-    "@agoric/store": "0.9.3-dev-4c65fc2.0+4c65fc2",
-    "@agoric/vat-data": "0.5.3-dev-4c65fc2.0+4c65fc2",
-    "@agoric/vats": "0.15.2-dev-4c65fc2.0+4c65fc2",
-    "@agoric/zoe": "0.26.3-dev-4c65fc2.0+4c65fc2",
-    "@agoric/zone": "0.2.3-dev-4c65fc2.0+4c65fc2",
+    "@agoric/assert": "0.6.1-dev-76b8d53.0+76b8d53",
+    "@agoric/cosmic-proto": "0.4.1-dev-76b8d53.0+76b8d53",
+    "@agoric/ertp": "0.16.3-dev-76b8d53.0+76b8d53",
+    "@agoric/internal": "0.3.3-dev-76b8d53.0+76b8d53",
+    "@agoric/network": "0.1.1-dev-76b8d53.0+76b8d53",
+    "@agoric/notifier": "0.6.3-dev-76b8d53.0+76b8d53",
+    "@agoric/store": "0.9.3-dev-76b8d53.0+76b8d53",
+    "@agoric/time": "0.3.3-dev-76b8d53.0+76b8d53",
+    "@agoric/vat-data": "0.5.3-dev-76b8d53.0+76b8d53",
+    "@agoric/vats": "0.15.2-dev-76b8d53.0+76b8d53",
+    "@agoric/zoe": "0.26.3-dev-76b8d53.0+76b8d53",
+    "@agoric/zone": "0.2.3-dev-76b8d53.0+76b8d53",
     "@endo/base64": "^1.0.4",
     "@endo/far": "^1.1.1",
     "@endo/marshal": "^1.4.1",
@@ -81,5 +82,5 @@
   "typeCoverage": {
     "atLeast": 96.39
   },
-  "gitHead": "4c65fc27a3e151be82ad228d58a7610d51b3c4a2"
+  "gitHead": "76b8d531fd9779664f767297a1a079ac500af731"
 }

package/src/contracts/stakeAtom.contract.js

@@ -11,7 +11,7 @@ import { prepareStakingAccountHolder } from './stakingAccountHolder.js';
 
 const trace = makeTracer('StakeAtom');
 /**
- * @import { Orchestration } from '../types.js';
+ * @import { OrchestrationService } from '../service.js'
  * @import { Baggage } from '@agoric/vat-data';
  * @import { IBCConnectionID } from '@agoric/vats';
  */
@@ -27,7 +27,7 @@ const trace = makeTracer('StakeAtom');
  *
  * @param {ZCF<StakeAtomTerms>} zcf
  * @param {{
- *  orchestration: Orchestration;
+ *  orchestration: OrchestrationService;
  *  storageNode: StorageNode;
  *  marshaller: Marshaller;
  * }} privateArgs

package/src/contracts/stakingAccountHolder.js

@@ -32,7 +32,7 @@ const { Fail } = assert;
  * @typedef {{
  *  topicKit: RecorderKit<StakingAccountNotification>;
  *  account: ChainAccount;
- *  chainAddress: ChainAddress;
+ *  chainAddress: string;
  * }} State
  */
 
@@ -71,7 +71,7 @@ export const prepareStakingAccountHolder = (baggage, makeRecorderKit, zcf) => {
     /**
      * @param {ChainAccount} account
      * @param {StorageNode} storageNode
-     * @param {ChainAddress} chainAddress
+     * @param {string} chainAddress
      * @returns {State}
      */
     (account, storageNode, chainAddress) => {
@@ -93,6 +93,8 @@ export const prepareStakingAccountHolder = (baggage, makeRecorderKit, zcf) => {
         getUpdater() {
           return this.state.topicKit.recorder;
         },
+        // TODO move this beneath the Orchestration abstraction,
+        // to the OrchestrationAccount provided by createAccount()
         /**
          * _Assumes users has already sent funds to their ICA, until #9193
          * @param {string} validatorAddress

package/src/contracts/swapExample.contract.js

@@ -0,0 +1,102 @@
+// @ts-check
+import { Fail } from '@agoric/assert';
+import { AmountMath, AmountShape } from '@agoric/ertp';
+import { E, Far } from '@endo/far';
+import { M } from '@endo/patterns';
+import { makeOrchestrationFacade } from '../facade.js';
+import { orcUtils } from '../utils/orc.js';
+
+/**
+ * @import {Orchestrator, ChainAccount, CosmosValidatorAddress} from '../types.js'
+ * @import {TimerService} from '@agoric/time';
+ * @import {ERef} from '@endo/far'
+ * @import {OrchestrationService} from '../service.js';
+ * @import {Zone} from '@agoric/zone';
+ */
+
+/**
+ * @param {ZCF} zcf
+ * @param {{
+ * orchestrationService: ERef<OrchestrationService>;
+ * storageNode: ERef<StorageNode>;
+ * timerService: ERef<TimerService>;
+ * zone: Zone;
+ * }} privateArgs
+ */
+export const start = async (zcf, privateArgs) => {
+  const { orchestrationService, storageNode, timerService, zone } = privateArgs;
+
+  const { orchestrate } = makeOrchestrationFacade({
+    zone,
+    timerService,
+    zcf,
+    storageNode,
+    orchestrationService,
+  });
+
+  /** deprecated historical example */
+  /** @type {OfferHandler} */
+  const swapAndStakeHandler = orchestrate(
+    'LSTTia',
+    { zcf },
+    // eslint-disable-next-line no-shadow -- this `zcf` is enclosed in a membrane
+    async (/** @type {Orchestrator} */ orch, { zcf }, seat, offerArgs) => {
+      const { give } = seat.getProposal();
+      !AmountMath.isEmpty(give.USDC.value) || Fail`Must provide USDC.`;
+
+      const celestia = await orch.getChain('celestia');
+      const agoric = await orch.getChain('agoric');
+
+      const [celestiaAccount, localAccount] = await Promise.all([
+        celestia.createAccount(),
+        agoric.createAccount(),
+      ]);
+
+      const tiaAddress = await celestiaAccount.getChainAddress();
+
+      // deposit funds from user seat to LocalChainAccount
+      const seatKit = zcf.makeEmptySeatKit();
+      zcf.atomicRearrange(harden([[seat, seatKit.zcfSeat, give]]));
+      // seat.exit() // exit user seat now, or later?
+      const payment = await E(seatKit.userSeat).getPayout('USDC');
+      await localAccount.deposit(payment);
+
+      // build swap instructions with orcUtils library
+      const transferMsg = orcUtils.makeOsmosisSwap({
+        destChain: 'celestia',
+        destAddress: tiaAddress,
+        amountIn: give.USDC,
+        brandOut: offerArgs.staked.brand,
+        slippage: 0.03,
+      });
+
+      await localAccount
+        .transferSteps(give.USDC, transferMsg)
+        .then(_txResult =>
+          celestiaAccount.delegate(offerArgs.validator, offerArgs.staked),
+        )
+        .catch(e => console.error(e));
+
+      // XXX close localAccount?
+      return celestiaAccount; // should be continuing inv since this is an offer?
+    },
+  );
+
+  const makeSwapAndStakeInvitation = () =>
+    zcf.makeInvitation(
+      swapAndStakeHandler,
+      'Swap for TIA and stake',
+      undefined,
+      harden({
+        give: { USDC: AmountShape },
+        want: {}, // XXX ChainAccount Ownable?
+        exit: M.any(),
+      }),
+    );
+
+  const publicFacet = Far('SwapAndStake Public Facet', {
+    makeSwapAndStakeInvitation,
+  });
+
+  return harden({ publicFacet });
+};

package/src/contracts/unbondExample.contract.js

@@ -0,0 +1,87 @@
+// @ts-check
+import { Fail } from '@agoric/assert';
+import { AmountMath, AmountShape } from '@agoric/ertp';
+import { Far } from '@endo/far';
+import { M } from '@endo/patterns';
+import { makeOrchestrationFacade } from '../facade.js';
+
+/**
+ * @import {Orchestrator, ChainAccount, CosmosValidatorAddress} from '../types.js'
+ * @import {TimerService} from '@agoric/time';
+ * @import {ERef} from '@endo/far'
+ * @import {OrchestrationService} from '../service.js';
+ * @import {Zone} from '@agoric/zone';
+ */
+
+/**
+ * @param {ZCF} zcf
+ * @param {{
+ * orchestrationService: ERef<OrchestrationService>;
+ * storageNode: ERef<StorageNode>;
+ * timerService: ERef<TimerService>;
+ * zone: Zone;
+ * }} privateArgs
+ */
+export const start = async (zcf, privateArgs) => {
+  const { orchestrationService, storageNode, timerService, zone } = privateArgs;
+
+  const { orchestrate } = makeOrchestrationFacade({
+    zone,
+    timerService,
+    zcf,
+    storageNode,
+    orchestrationService,
+  });
+
+  /** @type {OfferHandler} */
+  const unbondAndLiquidStake = orchestrate(
+    'LSTTia',
+    { zcf },
+    // eslint-disable-next-line no-shadow -- this `zcf` is enclosed in a membrane
+    async (/** @type {Orchestrator} */ orch, { zcf }, seat, _offerArgs) => {
+      console.log('zcf within the membrane', zcf);
+      const { give } = seat.getProposal();
+      !AmountMath.isEmpty(give.USDC.value) || Fail`Must provide USDC.`;
+
+      // We would actually alreaady have the account from the orchestrator
+      // ??? could these be passed in? It would reduce the size of this handler,
+      // keeping it focused on long-running operations.
+      const celestia = await orch.getChain('celestia');
+      const celestiaAccount = await celestia.createAccount();
+
+      const delegations = await celestiaAccount.getDelegations();
+      const [undelegation] = await celestiaAccount.undelegate(delegations);
+
+      // wait for the undelegations to be complete (may take weeks)
+      await undelegation.completion;
+
+      // ??? should this be synchronous? depends on how names are resolved.
+      const stride = await orch.getChain('stride');
+      const strideAccount = await stride.createAccount();
+
+      // TODO the `TIA` string actually needs to be the Brand from AgoricNames
+      const tiaAmt = await celestiaAccount.getBalance('TIA');
+      await celestiaAccount.transfer(tiaAmt, strideAccount.getChainAddress());
+
+      await strideAccount.liquidStake(tiaAmt);
+    },
+  );
+
+  const makeUnbondAndLiquidStakeInvitation = () =>
+    zcf.makeInvitation(
+      unbondAndLiquidStake,
+      'Unbond and liquid stake',
+      undefined,
+      harden({
+        give: { USDC: AmountShape },
+        want: {}, // XXX ChainAccount Ownable?
+        exit: M.any(),
+      }),
+    );
+
+  const publicFacet = Far('SwapAndStake Public Facet', {
+    makeUnbondAndLiquidStakeInvitation,
+  });
+
+  return harden({ publicFacet });
+};

package/src/facade.js

@@ -0,0 +1,47 @@
+// @ts-check
+/** @file Orchestration service */
+
+/**
+ * @import {Zone} from '@agoric/zone';
+ * @import {TimerService} from '@agoric/time';
+ * @import {OrchestrationService} from './service.js';
+ * @import {OrchestrationHandlerMaker} from './types.js';
+ */
+
+/**
+ *
+ * @param {{
+ *   zone: Zone;
+ *   timerService: ERef<TimerService>;
+ *   zcf: ERef<ZCF>;
+ *   storageNode: ERef<StorageNode>;
+ *   orchestrationService: ERef<OrchestrationService>;
+ * }} powers
+ */
+export const makeOrchestrationFacade = ({
+  zone,
+  timerService,
+  zcf,
+  storageNode,
+  orchestrationService,
+}) => {
+  console.log('makeOrchestrationFacade got', {
+    zone,
+    timerService,
+    zcf,
+    storageNode,
+    orchestrationService,
+  });
+
+  return {
+    /**
+     * @type {OrchestrationHandlerMaker}
+     */
+    orchestrate(durableName, ctx, fn) {
+      console.log('orchestrate got', durableName, ctx, fn);
+      throw new Error('Not yet implemented');
+    },
+  };
+};
+harden(makeOrchestrationFacade);
+/** @typedef {ReturnType<typeof makeOrchestrationFacade>} OrchestrationFacade */

package/src/proposals/orchestration-proposal.js

@@ -2,7 +2,11 @@
 import { V as E } from '@agoric/vat-data/vow.js';
 import { Far } from '@endo/far';
 
-/** @import { AttenuatedNetwork, Orchestration, OrchestrationVat } from '../types' */
+/**
+ * @import { AttenuatedNetwork } from '../types'
+ * @import { OrchestrationService } from '../service.js'
+ * @import { OrchestrationVat } from '../vat-orchestration.js'
+ */
 
 /**
  * @param {BootstrapPowers & {
@@ -67,7 +71,7 @@ export const setupOrchestrationVat = async (
 /**
  * @param {BootstrapPowers & {
  *   consume: {
- *     orchestration: Orchestration;
+ *     orchestration: OrchestrationService;
  *   };
  * }} powers
  * @param {object} _options

package/src/{orchestration.js → service.js}

@@ -2,14 +2,16 @@
 /** @file Orchestration service */
 import { NonNullish } from '@agoric/assert';
 import { makeTracer } from '@agoric/internal';
+import '@agoric/network/exported.js';
 import { V as E } from '@agoric/vat-data/vow.js';
 import { M } from '@endo/patterns';
+import { PaymentShape, PurseShape } from '@agoric/ertp';
+import { InvitationShape } from '@agoric/zoe/src/typeGuards.js';
 import { makeICAConnectionAddress, parseAddress } from './utils/address.js';
 import { makeTxPacket, parsePacketAck } from './utils/tx.js';
-import '@agoric/network/exported.js';
 
 /**
- * @import { AttenuatedNetwork } from './types.js';
+ * @import { AttenuatedNetwork, ChainAccount, ChainAddress } from './types.js';
  * @import { IBCConnectionID } from '@agoric/vats';
  * @import { Zone } from '@agoric/base-zone';
  * @import { TxBody } from '@agoric/cosmic-proto/cosmos/tx/v1beta1/tx.js';
@@ -20,9 +22,6 @@ const trace = makeTracer('Orchestration');
 
 /** @import {AnyJson} from '@agoric/cosmic-proto'; */
 
-// TODO improve me
-/** @typedef {string} ChainAddress */
-
 /**
  * @typedef {object} OrchestrationPowers
  * @property {ERef<AttenuatedNetwork>} network
@@ -59,10 +58,14 @@ export const ChainAccountI = M.interface('ChainAccount', {
   getLocalAddress: M.call().returns(M.string()),
   getRemoteAddress: M.call().returns(M.string()),
   getPort: M.call().returns(M.remotable('Port')),
+  executeTx: M.call(M.arrayOf(M.record())).returns(M.promise()),
   executeEncodedTx: M.call(M.arrayOf(Proto3Shape))
     .optional(M.record())
     .returns(M.promise()),
-  close: M.callWhen().returns(M.string()),
+  close: M.callWhen().returns(M.undefined()),
+  deposit: M.callWhen(PaymentShape).returns(M.undefined()),
+  getPurse: M.callWhen().returns(PurseShape),
+  prepareTransfer: M.callWhen().returns(InvitationShape),
 });
 
 export const ConnectionHandlerI = M.interface('ConnectionHandler', {
@@ -88,7 +91,7 @@ const prepareChainAccount = zone =>
        *   localAddress: string | undefined;
        *   requestedRemoteAddress: string;
        *   remoteAddress: string | undefined;
-       *   accountAddress: ChainAddress | undefined;
+       *   accountAddress: string | undefined;
        * }}
        */ (
         harden({
@@ -102,6 +105,9 @@ const prepareChainAccount = zone =>
       ),
     {
       account: {
+        /**
+         * @returns {string} the address of the account on the chain
+         */
         getAccountAddress() {
           return NonNullish(
             this.state.accountAddress,
@@ -123,7 +129,11 @@ const prepareChainAccount = zone =>
         getPort() {
           return this.state.port;
         },
+        executeTx() {
+          throw new Error('not yet implemented');
+        },
         /**
+         * Submit a transaction on behalf of the remote account for execution on the remote chain.
          * @param {AnyJson[]} msgs
          * @param {Omit<TxBody, 'messages'>} [opts]
          * @returns {Promise<string>} - base64 encoded bytes string. Can be decoded using the corresponding `Msg*Response` object.
@@ -138,6 +148,9 @@ const prepareChainAccount = zone =>
             ack => parsePacketAck(ack),
           );
         },
+        /**
+         * Close the remote account
+         */
         async close() {
           /// XXX what should the behavior be here? and `onClose`?
           // - retrieve assets?
@@ -145,7 +158,23 @@ const prepareChainAccount = zone =>
           const { connection } = this.state;
           if (!connection) throw Fail`connection not available`;
           await E(connection).close();
-          return 'Connection closed';
+        },
+        async deposit(payment) {
+          console.log('deposit got', payment);
+          throw new Error('not yet implemented');
+        },
+        /**
+         * get Purse for a brand to .withdraw() a Payment from the account
+         * @param {Brand} brand
+         */
+        async getPurse(brand) {
+          console.log('getPurse got', brand);
+          throw new Error('not yet implemented');
+        },
+
+        /* transfer account to new holder */
+        async prepareTransfer() {
+          throw new Error('not yet implemented');
         },
       },
       connectionHandler: {
@@ -253,7 +282,6 @@ export const prepareOrchestrationTools = zone => {
 harden(prepareOrchestrationTools);
 
 /** @typedef {ReturnType<ReturnType<typeof prepareChainAccount>>} ChainAccountKit */
-/** @typedef {ChainAccountKit['account']} ChainAccount */
 /** @typedef {ReturnType<typeof prepareOrchestrationTools>} OrchestrationTools */
 /** @typedef {ReturnType<OrchestrationTools['makeOrchestration']>} OrchestrationKit */
-/** @typedef {OrchestrationKit['public']} Orchestration */
+/** @typedef {OrchestrationKit['public']} OrchestrationService */

package/src/types.d.ts

@@ -1,7 +1,457 @@
-import type { RouterProtocol } from '@agoric/network/src/router';
+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 { AnyJson } from '@agoric/cosmic-proto';
+import type { MsgUndelegateResponse } from '@agoric/cosmic-proto/cosmos/staking/v1beta1/tx.js';
+import type {
+  Delegation,
+  Redelegation,
+  UnbondingDelegation,
+} from '@agoric/cosmic-proto/cosmos/staking/v1beta1/staking.js';
 
 export type AttenuatedNetwork = Pick<RouterProtocol, 'bindPort'>;
 
-export type * from './orchestration.js';
-export type * from './vat-orchestration.js';
-export type * from './utils/tx.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: {
+      liquidStake: (amount: AmountArg) => Promise<void>;
+    };
+  };
+  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: {} };
+};
+
+/** A helper type for type extensions. */
+export type TypeUrl = string;
+
+/**
+ * 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;
+
+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 */
+  chainId: string;
+  address: string;
+  // TODO what's the right way to scope the address? it's not chainId
+  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: (
+    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>;
+
+  /**
+   * 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;
+
+/**
+ * Info for an Ethereum-based chain.
+ */
+export type EthChainInfo = {
+  chainId: string;
+  allegedName: string;
+};
+
+/**
+ * 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
+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
+   */
+  createAccount: () => 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>;
+}
+
+/**
+ * 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
+   */
+  getAccountAddress: () => string;
+  /**
+   * 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 msgs - records for the transaction
+   * @returns acknowledge string
+   */
+  executeEncodedTx: (msgs: AnyJson[]) => 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>;
+}
+
+export interface Undelegation {
+  // TODO return MsgCancelUnbondingDelegationResponse when that type is available
+  cancel: () => Promise<void>;
+  response: MsgUndelegateResponse;
+  /**
+   * Resolves when the undelegation is complete and the tokens are no longer bonded.
+   * Note it may take weeks.
+   */
+  completion: Promise<void>;
+}
+
+/**
+ * An object that supports high-level operations for an account on a remote chain.
+ */
+export interface BaseOrchestrationAccount {
+  /** @returns the underlying low-level operation object. */
+  getChainAcccount: () => Promise<ChainAccount>;
+
+  /**
+   * @returns the address of the account on the remote chain
+   */
+  getChainAddress: () => 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 }>;
+
+  /**
+   * @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[]>;
+
+  /**
+   * 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>;
+
+  /**
+   * 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 teh 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.
+   * @param delegations - the delegation to undelegate
+   */
+  undelegate: (delegations: Delegation[]) => Promise<Undelegation[]>;
+
+  /**
+   * 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[]>;
+
+  /**
+   * 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>;
+}
+
+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;
+};
+
+// Example
+// await icaNoble.transferSteps(usdcAmt,
+//   osmosisSwap(tiaBrand, { pool: 1224, slippage: 0.05 }, icaCel.getAddress()));
+
+/**
+ * @param pool - Required. Pool number
+ */
+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;
+
+type AfterAction = { destChain: string; destAddress: ChainAddress };
+type SwapExact = { amountIn: Amount; amountOut: Amount };
+type SwapMaxSlippage = { amountIn: Amount; brandOut: Brand; slippage: number };

package/src/utils/address.js

@@ -1,7 +1,10 @@
 // @ts-check
 import { Fail } from '@agoric/assert';
 
-/** @import { IBCConnectionID } from '@agoric/vats'; */
+/**
+ * @import { IBCConnectionID } from '@agoric/vats';
+ * @import { ChainAddress, CosmosValidatorAddress } from '../types.js';
+ */
 
 /**
  * @param {IBCConnectionID} hostConnectionId Counterpart Connection ID
@@ -52,3 +55,4 @@ export const parseAddress = remoteAddressString => {
     return undefined;
   }
 };
+harden(parseAddress);

package/src/utils/orc.js

@@ -0,0 +1,37 @@
+// @ts-check
+/** @import {AfterAction, SwapMaxSlippage, TransferMsg} from '../types.js' */
+
+export const orcUtils = {
+  /**
+   * unwinds denom with PFM, if necessary
+   *
+   * @param {Omit<TransferMsg, 'memo'>} _args
+   * @returns {TransferMsg}
+   */
+  makeTransferMsg: _args => {
+    // XXX mocked, so typescript is happy
+    return {
+      toAccount: {
+        chainId: 'osmosis-test',
+        address: 'osmo1234',
+        addressEncoding: 'bech32',
+      },
+    };
+  },
+  /**
+   * SwapExact or SwapMaxSlippage, with optional AfterAction
+   * @param { (SwapExact | SwapMaxSlippage) &
+  (AfterAction | Record<string, never>)} _args
+   * @returns {TransferMsg}
+   */
+  makeOsmosisSwap(_args) {
+    // XXX mocked, so typescript is happy
+    return {
+      toAccount: {
+        chainId: 'osmosis-test',
+        address: 'osmo1234',
+        addressEncoding: 'bech32',
+      },
+    };
+  },
+};

package/src/vat-orchestration.js

@@ -1,9 +1,9 @@
 // @ts-check
 import { Far } from '@endo/far';
 import { makeDurableZone } from '@agoric/zone/durable.js';
-import { prepareOrchestrationTools } from './orchestration.js';
+import { prepareOrchestrationTools } from './service.js';
 
-/** @import { OrchestrationPowers } from './types.js' */
+/** @import { OrchestrationPowers } from './service.js' */
 
 export const buildRootObject = (_vatPowers, _args, baggage) => {
   const zone = makeDurableZone(baggage);