@agoric/orchestration 0.1.1-dev-286302a.0 → 0.1.1-dev-24f7f32.0

package/index.js

@@ -1,5 +1,4 @@
 // eslint-disable-next-line import/export
 export * from './src/types.js';
-export * from './src/utils/address.js';
-export * from './src/utils/tx.js';
 export * from './src/service.js';
+export * from './src/typeGuards.js';

package/package.json

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

package/src/examples/stakeAtom.contract.js

@@ -11,15 +11,16 @@ import { prepareStakingAccountKit } from '../exos/stakingAccountKit.js';
 
 const trace = makeTracer('StakeAtom');
 /**
- * @import { OrchestrationService } from '../service.js'
  * @import { Baggage } from '@agoric/vat-data';
  * @import { IBCConnectionID } from '@agoric/vats';
+ * @import { ICQConnection, OrchestrationService } from '../types.js';
  */
 
 /**
  * @typedef {{
  *  hostConnectionId: IBCConnectionID;
  *  controllerConnectionId: IBCConnectionID;
+ *  bondDenom: string;
  * }} StakeAtomTerms
  */
 
@@ -34,7 +35,9 @@ const trace = makeTracer('StakeAtom');
  * @param {Baggage} baggage
  */
 export const start = async (zcf, privateArgs, baggage) => {
-  const { hostConnectionId, controllerConnectionId } = zcf.getTerms();
+  // TODO #9063 this roughly matches what we'll get from Chain<C>.getChainInfo()
+  const { hostConnectionId, controllerConnectionId, bondDenom } =
+    zcf.getTerms();
   const { orchestration, marshaller, storageNode } = privateArgs;
 
   const zone = makeDurableZone(baggage);
@@ -52,12 +55,19 @@ export const start = async (zcf, privateArgs, baggage) => {
       hostConnectionId,
       controllerConnectionId,
     );
-    const address = await E(account).getAddress();
-    trace('chain address', address);
+    // #9212 TODO do not fail if host does not have `async-icq` module;
+    // communicate to OrchestrationAccount that it can't send queries
+    const icqConnection = await E(orchestration).provideICQConnection(
+      controllerConnectionId,
+    );
+    const accountAddress = await E(account).getAddress();
+    trace('account address', accountAddress);
     const { holder, invitationMakers } = makeStakingAccountKit(
       account,
       storageNode,
-      address,
+      accountAddress,
+      icqConnection,
+      bondDenom,
     );
     return {
       publicSubscribers: holder.getPublicTopics(),

package/src/exos/chainAccountKit.js

@@ -1,22 +1,27 @@
 // @ts-check
-/** @file Orchestration service */
-import { NonNullish } from '@agoric/assert';
-import { makeTracer } from '@agoric/internal';
+/** @file ChainAccount exo */
 
 // XXX ambient types runtime imports until https://github.com/Agoric/agoric-sdk/issues/6512
 import '@agoric/network/exported.js';
 
+import { NonNullish } from '@agoric/assert';
+import { makeTracer } from '@agoric/internal';
 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 { parseAddress } from '../utils/address.js';
-import { makeTxPacket, parsePacketAck } from '../utils/tx.js';
+import { findAddressField } from '../utils/address.js';
+import {
+  ConnectionHandlerI,
+  ChainAddressShape,
+  Proto3Shape,
+} from '../typeGuards.js';
+import { makeTxPacket, parseTxPacket } from '../utils/packet.js';
 
 /**
+ * @import { Zone } from '@agoric/base-zone';
  * @import { Connection, Port } from '@agoric/network';
  * @import { Remote } from '@agoric/vow';
- * @import { Zone } from '@agoric/base-zone';
  * @import { AnyJson } from '@agoric/cosmic-proto';
  * @import { TxBody } from '@agoric/cosmic-proto/cosmos/tx/v1beta1/tx.js';
  * @import { LocalIbcAddress, RemoteIbcAddress } from '@agoric/vats/tools/ibc-utils.js';
@@ -24,18 +29,7 @@ import { makeTxPacket, parsePacketAck } from '../utils/tx.js';
  */
 
 const { Fail } = assert;
-const trace = makeTracer('ChainAccount');
-
-export const Proto3Shape = {
-  typeUrl: M.string(),
-  value: M.string(),
-};
-
-export const ChainAddressShape = {
-  address: M.string(),
-  chainId: M.string(),
-  addressEncoding: M.string(),
-};
+const trace = makeTracer('ChainAccountKit');
 
 /** @typedef {'UNPARSABLE_CHAIN_ADDRESS'}  UnparsableChainAddress */
 const UNPARSABLE_CHAIN_ADDRESS = 'UNPARSABLE_CHAIN_ADDRESS';
@@ -55,32 +49,28 @@ export const ChainAccountI = M.interface('ChainAccount', {
   prepareTransfer: M.callWhen().returns(InvitationShape),
 });
 
-export const ConnectionHandlerI = M.interface('ConnectionHandler', {
-  onOpen: M.callWhen(M.any(), M.string(), M.string(), M.any()).returns(M.any()),
-  onClose: M.callWhen(M.any(), M.any(), M.any()).returns(M.any()),
-  onReceive: M.callWhen(M.any(), M.string()).returns(M.any()),
-});
+/**
+ * @typedef {{
+ *   port: Port;
+ *   connection: Remote<Connection> | undefined;
+ *   localAddress: LocalIbcAddress | undefined;
+ *   requestedRemoteAddress: string;
+ *   remoteAddress: RemoteIbcAddress | undefined;
+ *   chainAddress: ChainAddress | undefined;
+ * }} State
+ */
 
 /** @param {Zone} zone */
 export const prepareChainAccountKit = zone =>
   zone.exoClassKit(
-    'ChainAccount',
+    'ChainAccountKit',
     { account: ChainAccountI, connectionHandler: ConnectionHandlerI },
     /**
      * @param {Port} port
      * @param {string} requestedRemoteAddress
      */
     (port, requestedRemoteAddress) =>
-      /**
-       * @type {{
-       *   port: Port;
-       *   connection: Remote<Connection> | undefined;
-       *   localAddress: LocalIbcAddress | undefined;
-       *   requestedRemoteAddress: string;
-       *   remoteAddress: RemoteIbcAddress | undefined;
-       *   chainAddress: ChainAddress | undefined;
-       * }}
-       */ (
+      /** @type {State} */ (
         harden({
           port,
           connection: undefined,
@@ -131,8 +121,8 @@ export const prepareChainAccountKit = zone =>
           if (!connection) throw Fail`connection not available`;
           return E.when(
             E(connection).send(makeTxPacket(msgs, opts)),
-            // if parsePacketAck cannot find a `result` key, it throws
-            ack => parsePacketAck(ack),
+            // if parseTxPacket cannot find a `result` key, it throws
+            ack => parseTxPacket(ack),
           );
         },
         /**
@@ -175,9 +165,8 @@ export const prepareChainAccountKit = zone =>
           this.state.connection = connection;
           this.state.remoteAddress = remoteAddr;
           this.state.localAddress = localAddr;
-          // XXX parseAddress currently throws, should it return '' instead?
           this.state.chainAddress = harden({
-            address: parseAddress(remoteAddr) || UNPARSABLE_CHAIN_ADDRESS,
+            address: findAddressField(remoteAddr) || UNPARSABLE_CHAIN_ADDRESS,
             // TODO get this from `Chain` object #9063
             // XXX how do we get a chainId for an unknown chain? seems it may need to be a user supplied arg
             chainId: 'FIXME',

package/src/exos/icqConnectionKit.js

@@ -0,0 +1,125 @@
+// @ts-check
+/** @file ICQConnection Exo */
+import { NonNullish } from '@agoric/assert';
+import { makeTracer } from '@agoric/internal';
+import { V as E } from '@agoric/vat-data/vow.js';
+import { M } from '@endo/patterns';
+import { makeQueryPacket, parseQueryPacket } from '../utils/packet.js';
+import { ConnectionHandlerI } from '../typeGuards.js';
+
+/**
+ * @import {Zone} from '@agoric/base-zone';
+ * @import {Connection, Port} from '@agoric/network';
+ * @import {Remote} from '@agoric/vow';
+ * @import {Base64Any, RequestQueryJson} from '@agoric/cosmic-proto';
+ * @import {ResponseQuery} from '@agoric/cosmic-proto/tendermint/abci/types.js';
+ * @import {LocalIbcAddress, RemoteIbcAddress} from '@agoric/vats/tools/ibc-utils.js';
+ */
+
+const { Fail } = assert;
+const trace = makeTracer('Orchestration:ICQConnection');
+
+export const ICQMsgShape = M.splitRecord(
+  { path: M.string(), data: M.string() },
+  { height: M.string(), prove: M.boolean() },
+);
+
+export const ICQConnectionI = M.interface('ICQConnection', {
+  getLocalAddress: M.call().returns(M.string()),
+  getRemoteAddress: M.call().returns(M.string()),
+  query: M.call(M.arrayOf(ICQMsgShape)).returns(M.promise()),
+});
+
+/**
+ * @typedef {{
+ *   port: Port;
+ *   connection: Remote<Connection> | undefined;
+ *   localAddress: LocalIbcAddress | undefined;
+ *   remoteAddress: RemoteIbcAddress | undefined;
+ * }} ICQConnectionKitState
+ */
+
+/**
+ * Prepares an ICQ Connection Kit based on the {@link https://github.com/cosmos/ibc-apps/blob/e9b46e4bf0ad0a66cf6bc53b5e5496f6e2b4b02b/modules/async-icq/README.md | `icq/v1` IBC application protocol}.
+ *
+ * `icq/v1`, also referred to as `async-icq`, is a protocol for asynchronous queries
+ * between IBC-enabled chains. It allows a chain to send queries to another chain
+ * and receive responses asynchronously.
+ *
+ * The ICQ connection kit provides the necessary functionality to establish and manage
+ * an ICQ connection between two chains. It includes methods for retrieving the local
+ * and remote addresses of the connection, as well as sending queries and handling
+ * connection events.
+ *
+ * @param {Zone} zone
+ */
+export const prepareICQConnectionKit = zone =>
+  zone.exoClassKit(
+    'ICQConnectionKit',
+    { connection: ICQConnectionI, connectionHandler: ConnectionHandlerI },
+    /**
+     * @param {Port} port
+     */
+    port =>
+      /** @type {ICQConnectionKitState} */ (
+        harden({
+          port,
+          connection: undefined,
+          remoteAddress: undefined,
+          localAddress: undefined,
+        })
+      ),
+    {
+      connection: {
+        getLocalAddress() {
+          return NonNullish(
+            this.state.localAddress,
+            'local address not available',
+          );
+        },
+        getRemoteAddress() {
+          return NonNullish(
+            this.state.remoteAddress,
+            'remote address not available',
+          );
+        },
+        /**
+         * @param {RequestQueryJson[]} msgs
+         * @returns {Promise<Base64Any<ResponseQuery>[]>}
+         * @throws {Error} if packet fails to send or an error is returned
+         */
+        query(msgs) {
+          const { connection } = this.state;
+          if (!connection) throw Fail`connection not available`;
+          return E.when(
+            E(connection).send(makeQueryPacket(msgs)),
+            // if parseTxPacket cannot find a `result` key, it throws
+            ack => parseQueryPacket(ack),
+          );
+        },
+      },
+      connectionHandler: {
+        /**
+         * @param {Remote<Connection>} connection
+         * @param {LocalIbcAddress} localAddr
+         * @param {RemoteIbcAddress} remoteAddr
+         */
+        async onOpen(connection, localAddr, remoteAddr) {
+          trace(`ICQ Channel Opened for ${localAddr} at ${remoteAddr}`);
+          this.state.connection = connection;
+          this.state.remoteAddress = remoteAddr;
+          this.state.localAddress = localAddr;
+        },
+        async onClose(_connection, reason) {
+          trace(`ICQ Channel closed. Reason: ${reason}`);
+        },
+        async onReceive(connection, bytes) {
+          trace(`ICQ Channel onReceive`, connection, bytes);
+          return '';
+        },
+      },
+    },
+  );
+
+/** @typedef {ReturnType<ReturnType<typeof prepareICQConnectionKit>>} ICQConnectionKit */
+/** @typedef {ICQConnectionKit['connection']} ICQConnection */

package/src/exos/stakingAccountKit.js

@@ -8,6 +8,10 @@ import {
   MsgDelegate,
   MsgDelegateResponse,
 } from '@agoric/cosmic-proto/cosmos/staking/v1beta1/tx.js';
+import {
+  QueryBalanceRequest,
+  QueryBalanceResponse,
+} from '@agoric/cosmic-proto/cosmos/bank/v1beta1/query.js';
 import { Any } from '@agoric/cosmic-proto/google/protobuf/any.js';
 import { AmountShape } from '@agoric/ertp';
 import { makeTracer } from '@agoric/internal';
@@ -16,11 +20,13 @@ import { M, prepareExoClassKit } from '@agoric/vat-data';
 import { TopicsRecordShape } from '@agoric/zoe/src/contractSupport/index.js';
 import { decodeBase64 } from '@endo/base64';
 import { E } from '@endo/far';
+import { toRequestQueryJson } from '@agoric/cosmic-proto';
+import { ChainAddressShape, CoinShape } from '../typeGuards.js';
 
 /**
- * @import { ChainAccount, ChainAddress, ChainAmount, CosmosValidatorAddress } from '../types.js';
- * @import { RecorderKit, MakeRecorderKit } from '@agoric/zoe/src/contractSupport/recorder.js';
- * @import { Baggage } from '@agoric/swingset-liveslots';
+ * @import {ChainAccount, ChainAddress, ChainAmount, CosmosValidatorAddress, ICQConnection} 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';
  */
 
@@ -37,13 +43,17 @@ const { Fail } = assert;
  *  topicKit: RecorderKit<StakingAccountNotification>;
  *  account: ChainAccount;
  *  chainAddress: ChainAddress;
+ *  icqConnection: ICQConnection;
+ *  bondDenom: string;
  * }} State
  */
 
-const HolderI = M.interface('holder', {
+export const ChainAccountHolderI = M.interface('ChainAccountHolder', {
   getPublicTopics: M.call().returns(TopicsRecordShape),
-  delegate: M.callWhen(M.string(), AmountShape).returns(M.record()),
-  withdrawReward: M.callWhen(M.string()).returns(M.array()),
+  getAddress: M.call().returns(ChainAddressShape),
+  getBalance: M.callWhen().optional(M.string()).returns(CoinShape),
+  delegate: M.callWhen(ChainAddressShape, AmountShape).returns(M.record()),
+  withdrawReward: M.callWhen(ChainAddressShape).returns(M.arrayOf(CoinShape)),
 });
 
 /** @type {{ [name: string]: [description: string, valueShape: Pattern] }} */
@@ -89,10 +99,10 @@ export const prepareStakingAccountKit = (baggage, makeRecorderKit, zcf) => {
     'Staking Account Holder',
     {
       helper: UnguardedHelperI,
-      holder: HolderI,
+      holder: ChainAccountHolderI,
       invitationMakers: M.interface('invitationMakers', {
-        Delegate: M.call(M.string(), AmountShape).returns(M.promise()),
-        WithdrawReward: M.call(M.string()).returns(M.promise()),
+        Delegate: M.call(ChainAddressShape, AmountShape).returns(M.promise()),
+        WithdrawReward: M.call(ChainAddressShape).returns(M.promise()),
         CloseAccount: M.call().returns(M.promise()),
         TransferAccount: M.call().returns(M.promise()),
       }),
@@ -101,13 +111,15 @@ export const prepareStakingAccountKit = (baggage, makeRecorderKit, zcf) => {
      * @param {ChainAccount} account
      * @param {StorageNode} storageNode
      * @param {ChainAddress} chainAddress
+     * @param {ICQConnection} icqConnection
+     * @param {string} bondDenom e.g. 'uatom'
      * @returns {State}
      */
-    (account, storageNode, chainAddress) => {
+    (account, storageNode, chainAddress, icqConnection, bondDenom) => {
       // must be the fully synchronous maker because the kit is held in durable state
       const topicKit = makeRecorderKit(storageNode, PUBLIC_TOPICS.account[1]);
 
-      return { account, chainAddress, topicKit };
+      return { account, chainAddress, topicKit, icqConnection, bondDenom };
     },
     {
       helper: {
@@ -126,24 +138,24 @@ export const prepareStakingAccountKit = (baggage, makeRecorderKit, zcf) => {
       invitationMakers: {
         /**
          *
-         * @param {string} validatorAddress
+         * @param {CosmosValidatorAddress} validator
          * @param {Amount<'nat'>} amount
          */
-        Delegate(validatorAddress, amount) {
-          trace('Delegate', validatorAddress, amount);
+        Delegate(validator, amount) {
+          trace('Delegate', validator, amount);
 
           return zcf.makeInvitation(async seat => {
             seat.exit();
-            return this.facets.holder.delegate(validatorAddress, amount);
+            return this.facets.holder.delegate(validator, amount);
           }, 'Delegate');
         },
-        /** @param {string} validatorAddress */
-        WithdrawReward(validatorAddress) {
-          trace('WithdrawReward', validatorAddress);
+        /** @param {CosmosValidatorAddress} validator */
+        WithdrawReward(validator) {
+          trace('WithdrawReward', validator);
 
           return zcf.makeInvitation(async seat => {
             seat.exit();
-            return this.facets.holder.withdrawReward(validatorAddress);
+            return this.facets.holder.withdrawReward(validator);
           }, 'WithdrawReward');
         },
         CloseAccount() {
@@ -170,20 +182,23 @@ export const prepareStakingAccountKit = (baggage, makeRecorderKit, zcf) => {
         },
         // TODO move this beneath the Orchestration abstraction,
         // to the OrchestrationAccount provided by makeAccount()
+        /** @returns {ChainAddress} */
+        getAddress() {
+          return this.state.chainAddress;
+        },
         /**
          * _Assumes users has already sent funds to their ICA, until #9193
-         * @param {string} validatorAddress
+         * @param {CosmosValidatorAddress} validator
          * @param {Amount<'nat'>} ertpAmount
          */
-        async delegate(validatorAddress, ertpAmount) {
-          trace('delegate', validatorAddress, ertpAmount);
+        async delegate(validator, ertpAmount) {
+          trace('delegate', validator, ertpAmount);
 
-          // FIXME get values from proposal or args
-          // FIXME brand handling and amount scaling
+          // FIXME brand handling and amount scaling #9211
           trace('TODO: handle brand', ertpAmount);
           const amount = {
             amount: String(ertpAmount.value),
-            denom: 'uatom',
+            denom: this.state.bondDenom,
           };
 
           const account = this.facets.helper.owned();
@@ -193,7 +208,7 @@ export const prepareStakingAccountKit = (baggage, makeRecorderKit, zcf) => {
             toAnyJSON(
               MsgDelegate.toProtoMsg({
                 delegatorAddress,
-                validatorAddress,
+                validatorAddress: validator.address,
                 amount,
               }),
             ),
@@ -204,15 +219,15 @@ export const prepareStakingAccountKit = (baggage, makeRecorderKit, zcf) => {
         },
 
         /**
-         * @param {string} validatorAddress
+         * @param {CosmosValidatorAddress} validator
          * @returns {Promise<ChainAmount[]>}
          */
-        async withdrawReward(validatorAddress) {
+        async withdrawReward(validator) {
           const { chainAddress } = this.state;
-          assert.typeof(validatorAddress, 'string');
+          assert.typeof(validator.address, 'string');
           const msg = MsgWithdrawDelegatorReward.toProtoMsg({
             delegatorAddress: chainAddress.address,
-            validatorAddress,
+            validatorAddress: validator.address,
           });
           const account = this.facets.helper.owned();
           const result = await E(account).executeEncodedTx([toAnyJSON(msg)]);
@@ -222,9 +237,35 @@ export const prepareStakingAccountKit = (baggage, makeRecorderKit, zcf) => {
           );
           return harden(coins.map(toChainAmount));
         },
+        /**
+         * @param {ChainAmount['denom']} [denom] - defaults to bondDenom
+         * @returns {Promise<ChainAmount>}
+         */
+        async getBalance(denom) {
+          const { chainAddress, icqConnection, bondDenom } = this.state;
+          denom ||= bondDenom;
+          assert.typeof(denom, 'string');
+
+          const [result] = await E(icqConnection).query([
+            toRequestQueryJson(
+              QueryBalanceRequest.toProtoMsg({
+                address: chainAddress.address,
+                denom,
+              }),
+            ),
+          ]);
+          if (!result?.key) throw Fail`Error parsing result ${result}`;
+          const { balance } = QueryBalanceResponse.decode(
+            decodeBase64(result.key),
+          );
+          if (!balance) throw Fail`Result lacked balance key: ${result}`;
+          return harden(toChainAmount(balance));
+        },
       },
     },
   );
   return makeStakingAccountKit;
 };
+
 /** @typedef {ReturnType<ReturnType<typeof prepareStakingAccountKit>>} StakingAccountKit */
+/** @typedef {StakingAccountKit['holder']} StakingAccounHolder */

package/src/proposals/orchestration-proposal.js

@@ -2,9 +2,9 @@
 import { V as E } from '@agoric/vat-data/vow.js';
 
 /**
- * @import {Connection, Port, PortAllocator} from '@agoric/network';
- * @import { OrchestrationService } from '../service.js'
- * @import { OrchestrationVat } from '../vat-orchestration.js'
+ * @import {PortAllocator} from '@agoric/network';
+ * @import {OrchestrationService} from '../service.js'
+ * @import {OrchestrationVat} from '../vat-orchestration.js'
  */
 
 /**
@@ -19,8 +19,7 @@ import { V as E } from '@agoric/vat-data/vow.js';
  *     orchestrationVat: Producer<any>;
  *   };
  * }} powers
- * @param {object} options
- * @param {{ orchestrationRef: VatSourceRef }} options.options
+ * @param {{ options: { orchestrationRef: VatSourceRef }}} options
  *
  * @typedef {{
  *   orchestration: ERef<OrchestrationVat>;
@@ -50,7 +49,7 @@ export const setupOrchestrationVat = async (
 
   const portAllocator = await portAllocatorP;
 
-  const newOrchestrationKit = await E(vats.orchestration).makeOrchestration({
+  const newOrchestrationKit = await E(vats.orchestration).makeOrchestrationKit({
     portAllocator,
   });
 
@@ -84,8 +83,8 @@ export const getManifestForOrchestration = (_powers, { orchestrationRef }) => ({
       },
       produce: {
         orchestration: 'orchestration',
-        orchestrationKit: 'orchestration',
-        orchestrationVat: 'orchestration',
+        orchestrationKit: 'orchestrationKit',
+        orchestrationVat: 'orchestrationVat',
       },
     },
   },

package/src/proposals/start-stakeAtom.js

@@ -27,10 +27,14 @@ export const startStakeAtom = async (
       produce: { stakeAtom: produceInstance },
     },
   },
-  { options: { hostConnectionId, controllerConnectionId } },
+  { options: { hostConnectionId, controllerConnectionId, bondDenom } },
 ) => {
   const VSTORAGE_PATH = 'stakeAtom';
-  trace('startStakeAtom', { hostConnectionId, controllerConnectionId });
+  trace('startStakeAtom', {
+    hostConnectionId,
+    controllerConnectionId,
+    bondDenom,
+  });
   await null;
 
   const storageNode = await makeStorageNodeChild(chainStorage, VSTORAGE_PATH);
@@ -46,6 +50,7 @@ export const startStakeAtom = async (
     terms: {
       hostConnectionId,
       controllerConnectionId,
+      bondDenom,
     },
     privateArgs: {
       orchestration: await orchestration,

package/src/service.js

@@ -6,14 +6,19 @@ import '@agoric/network/exported.js';
 
 import { V as E } from '@agoric/vat-data/vow.js';
 import { M } from '@endo/patterns';
+import { Shape as NetworkShape } from '@agoric/network';
 import { prepareChainAccountKit } from './exos/chainAccountKit.js';
-import { makeICAConnectionAddress } from './utils/address.js';
+import { prepareICQConnectionKit } from './exos/icqConnectionKit.js';
+import {
+  makeICAChannelAddress,
+  makeICQChannelAddress,
+} from './utils/address.js';
 
 /**
- * @import { PortAllocator} from '@agoric/network';
- * @import { IBCConnectionID } from '@agoric/vats';
  * @import { Zone } from '@agoric/base-zone';
- * @import { ChainAccount } from './types.js';
+ * @import { Port, PortAllocator } from '@agoric/network';
+ * @import { IBCConnectionID } from '@agoric/vats';
+ * @import { ICQConnection, ChainAccount, ICQConnectionKit } from './types.js';
  */
 
 const { Fail, bare } = assert;
@@ -34,6 +39,10 @@ const { Fail, bare } = assert;
  * >} PowerStore
  */
 
+/**
+ * @typedef {MapStore<IBCConnectionID,ICQConnectionKit>} ICQConnectionStore
+ */
+
 /**
  * @template {keyof OrchestrationPowers} K
  * @param {PowerStore} powers
@@ -48,18 +57,33 @@ export const OrchestrationI = M.interface('Orchestration', {
   makeAccount: M.callWhen(M.string(), M.string()).returns(
     M.remotable('ChainAccount'),
   ),
+  provideICQConnection: M.callWhen(M.string()).returns(
+    M.remotable('Connection'),
+  ),
 });
 
+/** @typedef {{ powers: PowerStore; icqConnections: ICQConnectionStore } } OrchestrationState */
+
 /**
  * @param {Zone} zone
  * @param {ReturnType<typeof prepareChainAccountKit>} makeChainAccountKit
+ * @param {ReturnType<typeof prepareICQConnectionKit>} makeICQConnectionKit
  */
-const prepareOrchestration = (zone, makeChainAccountKit) =>
+const prepareOrchestrationKit = (
+  zone,
+  makeChainAccountKit,
+  makeICQConnectionKit,
+) =>
   zone.exoClassKit(
     'Orchestration',
     {
       self: M.interface('OrchestrationSelf', {
-        bindPort: M.callWhen().returns(M.remotable()),
+        allocateICAControllerPort: M.callWhen().returns(
+          NetworkShape.Vow$(NetworkShape.Port),
+        ),
+        allocateICQControllerPort: M.callWhen().returns(
+          NetworkShape.Vow$(NetworkShape.Port),
+        ),
       }),
       public: OrchestrationI,
     },
@@ -72,11 +96,16 @@ const prepareOrchestration = (zone, makeChainAccountKit) =>
           powers.init(/** @type {keyof OrchestrationPowers} */ (name), power);
         }
       }
-      return { powers };
+      const icqConnections = zone.detached().mapStore('ICQConnections');
+      return /** @type {OrchestrationState} */ ({ powers, icqConnections });
     },
     {
       self: {
-        async bindPort() {
+        async allocateICAControllerPort() {
+          const portAllocator = getPower(this.state.powers, 'portAllocator');
+          return E(portAllocator).allocateICAControllerPort();
+        },
+        async allocateICQControllerPort() {
           const portAllocator = getPower(this.state.powers, 'portAllocator');
           return E(portAllocator).allocateICAControllerPort();
         },
@@ -90,9 +119,9 @@ const prepareOrchestration = (zone, makeChainAccountKit) =>
          * @returns {Promise<ChainAccount>}
          */
         async makeAccount(hostConnectionId, controllerConnectionId) {
-          const port = await this.facets.self.bindPort();
+          const port = await this.facets.self.allocateICAControllerPort();
 
-          const remoteConnAddr = makeICAConnectionAddress(
+          const remoteConnAddr = makeICAChannelAddress(
             hostConnectionId,
             controllerConnectionId,
           );
@@ -104,9 +133,36 @@ const prepareOrchestration = (zone, makeChainAccountKit) =>
             chainAccountKit.connectionHandler,
           );
           // XXX if we fail, should we close the port (if it was created in this flow)?
-
           return chainAccountKit.account;
         },
+        /**
+         * @param {IBCConnectionID} controllerConnectionId
+         * @returns {Promise<ICQConnection>}
+         */
+        async provideICQConnection(controllerConnectionId) {
+          if (this.state.icqConnections.has(controllerConnectionId)) {
+            return this.state.icqConnections.get(controllerConnectionId)
+              .connection;
+          }
+          // allocate a new Port for every Connection
+          // TODO #9317 optimize ICQ port allocation
+          const port = await this.facets.self.allocateICQControllerPort();
+          const remoteConnAddr = makeICQChannelAddress(controllerConnectionId);
+          const icqConnectionKit = makeICQConnectionKit(port);
+
+          // await so we do not return/save a ICQConnection before it successfully instantiates
+          await E(port).connect(
+            remoteConnAddr,
+            icqConnectionKit.connectionHandler,
+          );
+
+          this.state.icqConnections.init(
+            controllerConnectionId,
+            icqConnectionKit,
+          );
+
+          return icqConnectionKit.connection;
+        },
       },
     },
   );
@@ -114,12 +170,17 @@ const prepareOrchestration = (zone, makeChainAccountKit) =>
 /** @param {Zone} zone */
 export const prepareOrchestrationTools = zone => {
   const makeChainAccountKit = prepareChainAccountKit(zone);
-  const makeOrchestration = prepareOrchestration(zone, makeChainAccountKit);
+  const makeICQConnectionKit = prepareICQConnectionKit(zone);
+  const makeOrchestrationKit = prepareOrchestrationKit(
+    zone,
+    makeChainAccountKit,
+    makeICQConnectionKit,
+  );
 
-  return harden({ makeOrchestration });
+  return harden({ makeOrchestrationKit });
 };
 harden(prepareOrchestrationTools);
 
 /** @typedef {ReturnType<typeof prepareOrchestrationTools>} OrchestrationTools */
-/** @typedef {ReturnType<OrchestrationTools['makeOrchestration']>} OrchestrationKit */
+/** @typedef {ReturnType<OrchestrationTools['makeOrchestrationKit']>} OrchestrationKit */
 /** @typedef {OrchestrationKit['public']} OrchestrationService */

package/src/typeGuards.js

@@ -0,0 +1,20 @@
+import { M } from '@endo/patterns';
+
+export const ConnectionHandlerI = M.interface('ConnectionHandler', {
+  onOpen: M.callWhen(M.any(), M.string(), M.string(), M.any()).returns(M.any()),
+  onClose: M.callWhen(M.any(), M.any(), M.any()).returns(M.any()),
+  onReceive: M.callWhen(M.any(), M.string()).returns(M.any()),
+});
+
+export const ChainAddressShape = {
+  address: M.string(),
+  chainId: M.string(),
+  addressEncoding: M.string(),
+};
+
+export const Proto3Shape = {
+  typeUrl: M.string(),
+  value: M.string(),
+};
+
+export const CoinShape = { value: M.bigint(), denom: M.string() };

package/src/types.d.ts

@@ -19,6 +19,13 @@ import type {
 } 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 { 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';
 
 /**
  * static declaration of known chain types will allow type support for
@@ -114,6 +121,10 @@ 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

package/src/utils/address.js

@@ -3,7 +3,8 @@ import { Fail } from '@agoric/assert';
 
 /**
  * @import { IBCConnectionID } from '@agoric/vats';
- * @import { ChainAddress, CosmosValidatorAddress } from '../types.js';
+ * @import { ChainAddress } from '../types.js';
+ * @import { RemoteIbcAddress } from '@agoric/vats/tools/ibc-utils.js';
  */
 
 /**
@@ -14,8 +15,9 @@ import { Fail } from '@agoric/assert';
  * @param {'ordered' | 'unordered'} [opts.ordering] - channel ordering. currently only `ordered` is supported for ics27-1
  * @param {string} [opts.txType] - default is `sdk_multi_msg`
  * @param {string} [opts.version] - default is `ics27-1`
+ * @returns {RemoteIbcAddress}
  */
-export const makeICAConnectionAddress = (
+export const makeICAChannelAddress = (
   hostConnectionId,
   controllerConnectionId,
   {
@@ -37,15 +39,30 @@ export const makeICAConnectionAddress = (
   });
   return `/ibc-hop/${controllerConnectionId}/ibc-port/icahost/${ordering}/${connString}`;
 };
+harden(makeICAChannelAddress);
+
+/**
+ * @param {IBCConnectionID}  controllerConnectionId
+ * @param {{ version?: string }} [opts]
+ * @returns {RemoteIbcAddress}
+ */
+export const makeICQChannelAddress = (
+  controllerConnectionId,
+  { version = 'icq-1' } = {},
+) => {
+  controllerConnectionId || Fail`controllerConnectionId is required`;
+  return `/ibc-hop/${controllerConnectionId}/ibc-port/icqhost/unordered/${version}`;
+};
+harden(makeICQChannelAddress);
 
 /**
  * Parse a chain address from a remote address string.
  * Assumes the address string is in a JSON format and contains an "address" field.
  * This function is designed to be safe against malformed inputs and unexpected data types, and will return `undefined` in those cases.
- * @param {string} remoteAddressString - remote address string, including version
- * @returns {string | undefined} returns undefined on error
+ * @param {RemoteIbcAddress} remoteAddressString - remote address string, including version
+ * @returns {ChainAddress['address'] | undefined} returns undefined on error
  */
-export const parseAddress = remoteAddressString => {
+export const findAddressField = remoteAddressString => {
   try {
     // Extract JSON version string assuming it's always surrounded by {}
     const jsonStr = remoteAddressString?.match(/{.*?}/)?.[0];
@@ -55,4 +72,4 @@ export const parseAddress = remoteAddressString => {
     return undefined;
   }
 };
-harden(parseAddress);
+harden(findAddressField);

package/src/utils/packet.js

@@ -0,0 +1,110 @@
+// @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';
+import { atob, decodeBase64, encodeBase64 } from '@endo/base64';
+import {
+  CosmosQuery,
+  CosmosResponse,
+} from '@agoric/cosmic-proto/icq/v1/packet.js';
+import { Type as PacketType } from '@agoric/cosmic-proto/ibc/applications/interchain_accounts/v1/packet.js';
+
+/**
+ * @import {AnyJson, RequestQueryJson, Base64Any} from '@agoric/cosmic-proto';
+ * @import {ResponseQuery} from '@agoric/cosmic-proto/tendermint/abci/types.js';
+ * @import {InterchainAccountPacketData} from '@agoric/cosmic-proto/ibc/applications/interchain_accounts/v1/packet.js';
+ * @import {InterchainQueryPacketData} from '@agoric/cosmic-proto/icq/v1/packet.js';
+ */
+
+/**
+ * Makes an IBC transaction packet from an array of messages. Expects the `value` of each message
+ * to be base64 encoded bytes.
+ * Skips checks for malformed messages in favor of interface guards.
+ * @param {AnyJson[]} msgs
+ * @param {Partial<Omit<TxBody, 'messages'>>} [opts]
+ * @returns {string} stringified InterchainAccountPacketData
+ * @throws {Error} if malformed messages are provided
+ */
+export function makeTxPacket(msgs, opts) {
+  const messages = msgs.map(Any.fromJSON);
+  const bytes = TxBody.encode(
+    TxBody.fromPartial({
+      messages,
+      ...opts,
+    }),
+  ).finish();
+
+  return JSON.stringify(
+    /** @type {Base64Any<InterchainAccountPacketData>} */ ({
+      type: PacketType.TYPE_EXECUTE_TX,
+      data: encodeBase64(bytes),
+      memo: '',
+    }),
+  );
+}
+harden(makeTxPacket);
+
+/**
+ * Makes an IBC query packet from an array of query messages. Expects the `data` of each message
+ * to be base64 encoded bytes.
+ * Skips checks for malformed messages in favor of interface guards.
+ * @param {RequestQueryJson[]} msgs
+ * @returns {string} stringified InterchainQueryPacketData
+ * @throws {Error} if malformed messages are provided
+ */
+export function makeQueryPacket(msgs) {
+  const bytes = CosmosQuery.encode(
+    CosmosQuery.fromPartial({
+      requests: msgs.map(RequestQuery.fromJSON),
+    }),
+  ).finish();
+
+  return JSON.stringify(
+    /** @type {Base64Any<InterchainQueryPacketData>} */ ({
+      data: encodeBase64(bytes),
+      memo: '',
+    }),
+  );
+}
+harden(makeQueryPacket);
+
+/**
+ * Looks for a result or error key in the response string, and returns
+ * a Base64Bytes string. This string can be decoded using the corresponding
+ * Msg*Response object.
+ * Error strings seem to be plain text and do not need decoding.
+ * @param {string} response
+ * @returns {string} - base64 encoded bytes string
+ * @throws {Error} if error key is detected in response string, or result key is not found
+ */
+export function parseTxPacket(response) {
+  const { result, error } = JSON.parse(response);
+  if (result) return result;
+  else if (error) throw Error(error);
+  else throw Error(response);
+}
+harden(parseTxPacket);
+
+/**
+ * Looks for a result or error key in the response string. If a result is found,
+ * `responses` is decoded via `CosmosResponse`. The `key` and `value` fields on the
+ * resulting entries are base64 encoded for inter-vat communication. These can be
+ * decoded using the corresponding Query*Response objects.
+ * Error strings seem to be plain text and do not need decoding.
+ * @param {string} response
+ * @returns {Base64Any<ResponseQuery>[]}
+ * @throws {Error} if error key is detected in response string, or result key is not found
+ */
+export function parseQueryPacket(response) {
+  const result = parseTxPacket(response);
+  const { data } = JSON.parse(atob(result));
+  const { responses = [] } = CosmosResponse.decode(decodeBase64(data));
+  return harden(
+    responses.map(resp => ({
+      ...resp,
+      key: encodeBase64(resp.key),
+      value: encodeBase64(resp.value),
+    })),
+  );
+}
+harden(parseQueryPacket);

package/src/vat-orchestration.js

@@ -7,14 +7,14 @@ import { prepareOrchestrationTools } from './service.js';
 
 export const buildRootObject = (_vatPowers, _args, baggage) => {
   const zone = makeDurableZone(baggage);
-  const { makeOrchestration } = prepareOrchestrationTools(
+  const { makeOrchestrationKit } = prepareOrchestrationTools(
     zone.subZone('orchestration'),
   );
 
   return Far('OrchestrationVat', {
     /** @param {Partial<OrchestrationPowers>} [initialPowers] */
-    makeOrchestration(initialPowers = {}) {
-      return makeOrchestration(initialPowers);
+    makeOrchestrationKit(initialPowers = {}) {
+      return makeOrchestrationKit(initialPowers);
     },
   });
 };

package/src/utils/tx.js

@@ -1,48 +0,0 @@
-// @ts-check
-import { TxBody } from '@agoric/cosmic-proto/cosmos/tx/v1beta1/tx.js';
-import { encodeBase64 } from '@endo/base64';
-import { Any } from '@agoric/cosmic-proto/google/protobuf/any.js';
-
-/**
- * Makes an IBC packet from an array of messages. Expects the `value` of each message
- * to be base64 encoded bytes.
- * Skips checks for malformed messages in favor of interface guards.
- * @param {import('@agoric/cosmic-proto').AnyJson[]} msgs
- * // XXX intellisense does not seem to infer well here
- * @param {Omit<TxBody, 'messages'>} [opts]
- * @returns {string} - IBC TX packet
- * @throws {Error} if malformed messages are provided
- */
-export function makeTxPacket(msgs, opts) {
-  const messages = msgs.map(Any.fromJSON);
-  const bytes = TxBody.encode(
-    TxBody.fromPartial({
-      messages,
-      ...opts,
-    }),
-  ).finish();
-
-  return JSON.stringify({
-    type: 1,
-    data: encodeBase64(bytes),
-    memo: '',
-  });
-}
-harden(makeTxPacket);
-
-/**
- * Looks for a result or error key in the response string, and returns
- * a Base64Bytes string. This string can be decoded using the corresponding
- * Msg*Response object.
- * Error strings seem to be plain text and do not need decoding.
- * @param {string} response
- * @returns {string} - base64 encoded bytes string
- * @throws {Error} if error key is detected in response string, or result key is not found
- */
-export function parsePacketAck(response) {
-  const { result, error } = JSON.parse(response);
-  if (result) return result;
-  else if (error) throw Error(error);
-  else throw Error(response);
-}
-harden(parsePacketAck);