@agoric/orchestration 0.1.1-dev-a477bee.0 → 0.1.1-dev-2b7439e.0

package/index.js

@@ -1,2 +1,4 @@
 // eslint-disable-next-line import/export
 export * from './src/types.js';
+export * from './src/utils/address.js';
+export * from './src/orchestration.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/orchestration",
-  "version": "0.1.1-dev-a477bee.0+a477bee",
+  "version": "0.1.1-dev-2b7439e.0+2b7439e",
   "description": "Chain abstraction for Agoric's orchestration clients",
   "type": "module",
   "main": "index.js",
@@ -29,13 +29,16 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
-    "@agoric/ertp": "0.16.3-dev-a477bee.0+a477bee",
-    "@agoric/internal": "0.3.3-dev-a477bee.0+a477bee",
-    "@agoric/notifier": "0.6.3-dev-a477bee.0+a477bee",
-    "@agoric/vat-data": "0.5.3-dev-a477bee.0+a477bee",
-    "@agoric/vats": "0.15.2-dev-a477bee.0+a477bee",
-    "@agoric/zoe": "0.26.3-dev-a477bee.0+a477bee",
-    "@agoric/zone": "0.2.3-dev-a477bee.0+a477bee",
+    "@agoric/assert": "0.6.1-dev-2b7439e.0+2b7439e",
+    "@agoric/ertp": "0.16.3-dev-2b7439e.0+2b7439e",
+    "@agoric/internal": "0.3.3-dev-2b7439e.0+2b7439e",
+    "@agoric/network": "0.1.1-dev-2b7439e.0+2b7439e",
+    "@agoric/notifier": "0.6.3-dev-2b7439e.0+2b7439e",
+    "@agoric/store": "0.9.3-dev-2b7439e.0+2b7439e",
+    "@agoric/vat-data": "0.5.3-dev-2b7439e.0+2b7439e",
+    "@agoric/vats": "0.15.2-dev-2b7439e.0+2b7439e",
+    "@agoric/zoe": "0.26.3-dev-2b7439e.0+2b7439e",
+    "@agoric/zone": "0.2.3-dev-2b7439e.0+2b7439e",
     "@endo/far": "^1.1.0",
     "@endo/marshal": "^1.4.0",
     "@endo/patterns": "^1.3.0"
@@ -43,7 +46,8 @@
   "devDependencies": {
     "@cosmjs/amino": "^0.32.3",
     "@cosmjs/proto-signing": "^0.32.3",
-    "ava": "^5.3.0",
+    "@endo/ses-ava": "^1.2.0",
+    "ava": "^5.3.1",
     "cosmjs-types": "^0.9.0"
   },
   "ava": {
@@ -76,5 +80,5 @@
   "typeCoverage": {
     "atLeast": 96.96
   },
-  "gitHead": "a477bee3be6e0e98b9346c0640380e276cf8423e"
+  "gitHead": "2b7439e3ad174ead924c942b105a4ad348d2bea9"
 }

package/src/contracts/stakeAtom.contract.js

@@ -0,0 +1,52 @@
+// @ts-check
+/**
+ * @file Example contract that uses orchestration
+ */
+
+import { makeDurableZone } from '@agoric/zone/durable.js';
+import { V as E } from '@agoric/vat-data/vow.js';
+import { M } from '@endo/patterns';
+
+/**
+ * @import * as orchestration from '../types'
+ * @import * as vatData from '@agoric/vat-data'
+ */
+
+/**
+ * @typedef {{
+ *  hostConnectionId: orchestration.ConnectionId;
+ *  controllerConnectionId: orchestration.ConnectionId;
+ * }} StakeAtomTerms
+ */
+
+/**
+ *
+ * @param {ZCF<StakeAtomTerms>} zcf
+ * @param {{
+ *   orchestration: orchestration.Orchestration;
+ * }} privateArgs
+ * @param {vatData.Baggage} baggage
+ */
+export const start = async (zcf, privateArgs, baggage) => {
+  const { hostConnectionId, controllerConnectionId } = zcf.getTerms();
+  const { orchestration } = privateArgs;
+
+  const zone = makeDurableZone(baggage);
+
+  const publicFacet = zone.exo(
+    'StakeAtom',
+    M.interface('StakeAtomI', {
+      createAccount: M.callWhen().returns(M.remotable('ChainAccount')),
+    }),
+    {
+      async createAccount() {
+        return E(orchestration).createAccount(
+          hostConnectionId,
+          controllerConnectionId,
+        );
+      },
+    },
+  );
+
+  return { publicFacet };
+};

package/src/orchestration.js

@@ -0,0 +1,240 @@
+// @ts-check
+/** @file Orchestration service */
+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 { makeICAConnectionAddress, parseAddress } from './utils/address.js';
+import '@agoric/network/exported.js';
+
+/**
+ * @import { ConnectionId } from './types';
+ * @import { Zone } from '@agoric/base-zone';
+ */
+
+const { Fail, bare } = assert;
+const trace = makeTracer('Orchestration');
+
+// TODO improve me
+/** @typedef {string} ChainAddress */
+
+/**
+ * @typedef {object} OrchestrationPowers
+ * @property {ERef<
+ *   import('@agoric/orchestration/src/types').AttenuatedNetwork
+ * >} network
+ */
+
+/**
+ * PowerStore is used so additional powers can be added on upgrade. See
+ * [#7337](https://github.com/Agoric/agoric-sdk/issues/7337) for tracking on Exo
+ * state migrations.
+ *
+ * @typedef {MapStore<
+ *   keyof OrchestrationPowers,
+ *   OrchestrationPowers[keyof OrchestrationPowers]
+ * >} PowerStore
+ */
+
+/**
+ * @template {keyof OrchestrationPowers} K
+ * @param {PowerStore} powers
+ * @param {K} name
+ */
+const getPower = (powers, name) => {
+  powers.has(name) || Fail`need powers.${bare(name)} for this method`;
+  return /** @type {OrchestrationPowers[K]} */ (powers.get(name));
+};
+
+export const ChainAccountI = M.interface('ChainAccount', {
+  getAccountAddress: M.call().returns(M.string()),
+  getLocalAddress: M.call().returns(M.string()),
+  getRemoteAddress: M.call().returns(M.string()),
+  getPort: M.call().returns(M.remotable('Port')),
+  close: M.callWhen().returns(M.string()),
+});
+
+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()),
+});
+
+/** @param {Zone} zone */
+const prepareChainAccount = zone =>
+  zone.exoClassKit(
+    'ChainAccount',
+    { account: ChainAccountI, connectionHandler: ConnectionHandlerI },
+    /**
+     * @param {Port} port
+     * @param {string} requestedRemoteAddress
+     */
+    (port, requestedRemoteAddress) =>
+      /**
+       * @type {{
+       *   port: Port;
+       *   connection: Connection | undefined;
+       *   localAddress: string | undefined;
+       *   requestedRemoteAddress: string;
+       *   remoteAddress: string | undefined;
+       *   accountAddress: ChainAddress | undefined;
+       * }}
+       */ (
+        harden({
+          port,
+          connection: undefined,
+          requestedRemoteAddress,
+          remoteAddress: undefined,
+          accountAddress: undefined,
+          localAddress: undefined,
+        })
+      ),
+    {
+      account: {
+        getAccountAddress() {
+          return NonNullish(
+            this.state.accountAddress,
+            'Error parsing account address from remote address',
+          );
+        },
+        getLocalAddress() {
+          return NonNullish(
+            this.state.localAddress,
+            'local address not available',
+          );
+        },
+        getRemoteAddress() {
+          return NonNullish(
+            this.state.remoteAddress,
+            'remote address not available',
+          );
+        },
+        getPort() {
+          return this.state.port;
+        },
+        async close() {
+          /// XXX what should the behavior be here? and `onClose`?
+          // - retrieve assets?
+          // - revoke the port?
+          const { connection } = this.state;
+          if (!connection) throw Fail`connection not available`;
+          await null;
+          try {
+            await E(connection).close();
+          } catch (e) {
+            throw Fail`Failed to close connection: ${e}`;
+          }
+          return 'Connection closed';
+        },
+      },
+      connectionHandler: {
+        /**
+         * @param {Connection} connection
+         * @param {string} localAddr
+         * @param {string} remoteAddr
+         */
+        async onOpen(connection, localAddr, remoteAddr) {
+          trace(`ICA Channel Opened for ${localAddr} at ${remoteAddr}`);
+          this.state.connection = connection;
+          this.state.remoteAddress = remoteAddr;
+          this.state.localAddress = localAddr;
+          // XXX parseAddress currently throws, should it return '' instead?
+          this.state.accountAddress = parseAddress(remoteAddr);
+        },
+        async onClose(_connection, reason) {
+          trace(`ICA Channel closed. Reason: ${reason}`);
+          // XXX handle connection closing
+          // XXX is there a scenario where a connection will unexpectedly close? _I think yes_
+        },
+        async onReceive(connection, bytes) {
+          trace(`ICA Channel onReceive`, connection, bytes);
+          return '';
+        },
+      },
+    },
+  );
+
+export const OrchestrationI = M.interface('Orchestration', {
+  createAccount: M.callWhen(M.string(), M.string()).returns(
+    M.remotable('ChainAccount'),
+  ),
+});
+
+/**
+ * @param {Zone} zone
+ * @param {ReturnType<typeof prepareChainAccount>} createChainAccount
+ */
+const prepareOrchestration = (zone, createChainAccount) =>
+  zone.exoClassKit(
+    'Orchestration',
+    {
+      self: M.interface('OrchestrationSelf', {
+        bindPort: M.callWhen().returns(M.remotable()),
+      }),
+      public: OrchestrationI,
+    },
+    /** @param {Partial<OrchestrationPowers>} [initialPowers] */
+    initialPowers => {
+      /** @type {PowerStore} */
+      const powers = zone.detached().mapStore('PowerStore');
+      if (initialPowers) {
+        for (const [name, power] of Object.entries(initialPowers)) {
+          powers.init(/** @type {keyof OrchestrationPowers} */ (name), power);
+        }
+      }
+      return { powers, icaControllerNonce: 0 };
+    },
+    {
+      self: {
+        async bindPort() {
+          const network = getPower(this.state.powers, 'network');
+          const port = await E(network)
+            .bind(`/ibc-port/icacontroller-${this.state.icaControllerNonce}`)
+            .catch(e => Fail`Failed to bind port: ${e}`);
+          this.state.icaControllerNonce += 1;
+          return port;
+        },
+      },
+      public: {
+        /**
+         * @param {ConnectionId} hostConnectionId
+         *   the counterparty connection_id
+         * @param {ConnectionId} controllerConnectionId
+         *   self connection_id
+         * @returns {Promise<ChainAccount>}
+         */
+        async createAccount(hostConnectionId, controllerConnectionId) {
+          const port = await this.facets.self.bindPort();
+
+          const remoteConnAddr = makeICAConnectionAddress(
+            hostConnectionId,
+            controllerConnectionId,
+          );
+          const chainAccount = createChainAccount(port, remoteConnAddr);
+
+          // await so we do not return a ChainAccount before it successfully instantiates
+          await E(port)
+            .connect(remoteConnAddr, chainAccount.connectionHandler)
+            // XXX if we fail, should we close the port (if it was created in this flow)?
+            .catch(e => Fail`Failed to create ICA connection: ${bare(e)}`);
+
+          return chainAccount.account;
+        },
+      },
+    },
+  );
+
+/** @param {Zone} zone */
+export const prepareOrchestrationTools = zone => {
+  const createChainAccount = prepareChainAccount(zone);
+  const makeOrchestration = prepareOrchestration(zone, createChainAccount);
+
+  return harden({ makeOrchestration });
+};
+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 */

package/src/proposals/orchestration-proposal.js

@@ -0,0 +1,99 @@
+// @ts-check
+import { V as E } from '@agoric/vat-data/vow.js';
+import { Far } from '@endo/far';
+
+/** @import { AttenuatedNetwork, Orchestration, OrchestrationVat } from '../types' */
+
+/**
+ * @param {BootstrapPowers & {
+ *   consume: {
+ *     loadCriticalVat: VatLoader<any>;
+ *     networkVat: NetworkVat;
+ *   };
+ *   produce: {
+ *     orchestration: Producer<any>;
+ *     orchestrationKit: Producer<any>;
+ *     orchestrationVat: Producer<any>;
+ *   };
+ * }} powers
+ * @param {object} options
+ * @param {{ orchestrationRef: VatSourceRef }} options.options
+ *
+ * @typedef {{
+ *   orchestration: ERef<OrchestrationVat>;
+ * }} OrchestrationVats
+ */
+export const setupOrchestrationVat = async (
+  {
+    consume: { loadCriticalVat, networkVat },
+    produce: {
+      orchestrationVat,
+      orchestration,
+      orchestrationKit: orchestrationKitP,
+    },
+  },
+  options,
+) => {
+  const { orchestrationRef } = options.options;
+  /** @type {OrchestrationVats} */
+  const vats = {
+    orchestration: E(loadCriticalVat)('orchestration', orchestrationRef),
+  };
+  // don't proceed if loadCriticalVat fails
+  await Promise.all(Object.values(vats));
+
+  orchestrationVat.reset();
+  orchestrationVat.resolve(vats.orchestration);
+
+  await networkVat;
+  /** @type {AttenuatedNetwork} */
+  const network = Far('Attenuated Network', {
+    /** @param {string} localAddr */
+    async bind(localAddr) {
+      return E(networkVat).bind(localAddr);
+    },
+  });
+
+  const newOrchestrationKit = await E(vats.orchestration).makeOrchestration({
+    network,
+  });
+
+  orchestration.reset();
+  orchestration.resolve(newOrchestrationKit.public);
+  orchestrationKitP.reset();
+  orchestrationKitP.resolve(newOrchestrationKit);
+};
+
+/**
+ * @param {BootstrapPowers & {
+ *   consume: {
+ *     orchestration: Orchestration;
+ *   };
+ * }} powers
+ * @param {object} _options
+ */
+export const addOrchestrationToClient = async (
+  { consume: { client, orchestration } },
+  _options,
+) => {
+  return E(client).assignBundle([_a => ({ orchestration })]);
+};
+
+export const getManifestForOrchestration = (_powers, { orchestrationRef }) => ({
+  manifest: {
+    [setupOrchestrationVat.name]: {
+      consume: {
+        loadCriticalVat: true,
+        networkVat: true,
+      },
+      produce: {
+        orchestration: 'orchestration',
+        orchestrationKit: 'orchestration',
+        orchestrationVat: 'orchestration',
+      },
+    },
+  },
+  options: {
+    orchestrationRef,
+  },
+});

package/src/proposals/start-stakeAtom.js

@@ -0,0 +1,68 @@
+// @ts-check
+import { makeTracer } from '@agoric/internal';
+import { E } from '@endo/far';
+
+const trace = makeTracer('StartStakeAtom', true);
+
+/**
+ * @param {BootstrapPowers & { installation: {consume: {stakeAtom: Installation<import('../contracts/stakeAtom.contract.js').start>}}}} powers
+ * @param {{options: import('../contracts/stakeAtom.contract.js').StakeAtomTerms}} options
+ */
+export const startStakeAtom = async (
+  {
+    consume: { orchestration, startUpgradable },
+    installation: {
+      consume: { stakeAtom },
+    },
+    instance: {
+      produce: { stakeAtom: produceInstance },
+    },
+  },
+  { options: { hostConnectionId, controllerConnectionId } },
+) => {
+  trace('startStakeAtom', { hostConnectionId, controllerConnectionId });
+  await null;
+
+  /** @type {StartUpgradableOpts<import('../contracts/stakeAtom.contract.js').start>} */
+  const startOpts = {
+    label: 'stakeAtom',
+    installation: stakeAtom,
+    terms: {
+      hostConnectionId,
+      controllerConnectionId,
+    },
+    privateArgs: {
+      orchestration: await orchestration,
+    },
+  };
+
+  const { instance } = await E(startUpgradable)(startOpts);
+  produceInstance.resolve(instance);
+};
+harden(startStakeAtom);
+
+export const getManifestForStakeAtom = (
+  { restoreRef },
+  { installKeys, ...options },
+) => {
+  return {
+    manifest: {
+      [startStakeAtom.name]: {
+        consume: {
+          orchestration: true,
+          startUpgradable: true,
+        },
+        installation: {
+          consume: { stakeAtom: true },
+        },
+        instance: {
+          produce: { stakeAtom: true },
+        },
+      },
+    },
+    installations: {
+      stakeAtom: restoreRef(installKeys.stakeAtom),
+    },
+    options,
+  };
+};

package/src/types.d.ts

@@ -0,0 +1,8 @@
+import type { RouterProtocol } from '@agoric/network/src/router';
+
+export type ConnectionId = `connection-${number}`;
+
+export type AttenuatedNetwork = Pick<RouterProtocol, 'bind'>;
+
+export type * from './orchestration.js';
+export type * from './vat-orchestration.js';

package/src/types.js

@@ -1,4 +1,5 @@
 // @ts-check
+import '@agoric/network/exported.js';
 import '@agoric/vats/exported.js';
 import '@agoric/zoe/exported.js';
 

package/src/utils/address.js

@@ -0,0 +1,54 @@
+// @ts-check
+import { Fail } from '@agoric/assert';
+
+/** @import { ConnectionId } from '../types'; */
+
+/**
+ * @param {ConnectionId} hostConnectionId Counterpart Connection ID
+ * @param {ConnectionId} controllerConnectionId Self Connection ID
+ * @param {object} [opts]
+ * @param {string} [opts.encoding] - message encoding format for the channel. default is `proto3`
+ * @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`
+ */
+export const makeICAConnectionAddress = (
+  hostConnectionId,
+  controllerConnectionId,
+  {
+    version = 'ics27-1',
+    encoding = 'proto3',
+    ordering = 'ordered',
+    txType = 'sdk_multi_msg',
+  } = {},
+) => {
+  hostConnectionId || Fail`hostConnectionId is required`;
+  controllerConnectionId || Fail`controllerConnectionId is required`;
+  const connString = JSON.stringify({
+    version,
+    controllerConnectionId,
+    hostConnectionId,
+    address: '', // will be provided by the counterparty after channelOpenAck
+    encoding,
+    txType,
+  });
+  return `/ibc-hop/${controllerConnectionId}/ibc-port/icahost/${ordering}/${connString}`;
+};
+
+/**
+ * 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
+ */
+export const parseAddress = remoteAddressString => {
+  try {
+    // Extract JSON version string assuming it's always surrounded by {}
+    const jsonStr = remoteAddressString?.match(/{.*?}/)?.[0];
+    const jsonObj = jsonStr ? JSON.parse(jsonStr) : undefined;
+    return jsonObj?.address ?? undefined;
+  } catch (error) {
+    return undefined;
+  }
+};

package/src/vat-orchestration.js

@@ -0,0 +1,22 @@
+// @ts-check
+import { Far } from '@endo/far';
+import { makeDurableZone } from '@agoric/zone/durable.js';
+import { prepareOrchestrationTools } from './orchestration.js';
+
+/** @import { OrchestrationPowers } from './types.js' */
+
+export const buildRootObject = (_vatPowers, _args, baggage) => {
+  const zone = makeDurableZone(baggage);
+  const { makeOrchestration } = prepareOrchestrationTools(
+    zone.subZone('orchestration'),
+  );
+
+  return Far('OrchestrationVat', {
+    /** @param {Partial<OrchestrationPowers>} [initialPowers] */
+    makeOrchestration(initialPowers = {}) {
+      return makeOrchestration(initialPowers);
+    },
+  });
+};
+
+/** @typedef {ReturnType<typeof buildRootObject>} OrchestrationVat */