@agoric/orchestration 0.1.1-dev-2f0f355.0.2f0f355 → 0.1.1-dev-aa6629d.0.aa6629d

package/src/utils/orchestrationAccount.js

@@ -3,6 +3,7 @@ import { Shape as NetworkShape } from '@agoric/network';
 import { VowShape } from '@agoric/vow';
 import { TopicsRecordShape } from '@agoric/zoe/src/contractSupport/topics.js';
 import { M } from '@endo/patterns';
+import { Fail } from '@endo/errors';
 import {
   AccountIdArgShape,
   AmountArgShape,
@@ -13,6 +14,24 @@ import {
 
 const { Vow$ } = NetworkShape; // TODO #9611
 
+/**
+ * @import {TypedPattern} from '@agoric/internal';
+ * @import {IBCEndpoint} from '@agoric/vats/tools/ibc-utils.js';
+ * @import {CaipChainId, IBCConnectionInfo, TrafficEntry} from '../types.js';
+ */
+
+/**
+ * @typedef {object} SliceDescriptor
+ * @property {number} start beginning index of the range (inclusive)
+ * @property {number} end ending index of the range (exclusive)
+ */
+/** @type {TypedPattern<SliceDescriptor>} */
+export const SliceDescriptorShape = M.splitRecord({
+  start: M.number(),
+  end: M.number(),
+});
+harden(SliceDescriptorShape);
+
 /** @see {OrchestrationAccountCommon} */
 export const orchestrationAccountMethods = {
   getAddress: M.call().returns(CosmosChainAddressShape),
@@ -38,4 +57,189 @@ export const orchestrationAccountMethods = {
     }),
   ),
   getPublicTopics: M.call().returns(Vow$(TopicsRecordShape)),
+  makeProgressTracker: M.call().returns(M.remotable('ProgressTracker')),
+};
+
+/**
+ * @param {CaipChainId} srcChain
+ * @param {CaipChainId} dstChain
+ * @param {IBCConnectionInfo['transferChannel']} ibcChannel
+ * @returns {(TrafficEntry<'ibc'> & { incomplete: true })[]}
+ */
+const startIbcTransfer = (srcChain, dstChain, ibcChannel) =>
+  harden([
+    {
+      op: 'transfer',
+      src: [
+        'ibc',
+        ['chain', srcChain],
+        ['port', ibcChannel.portId],
+        ['channel', ibcChannel.channelId],
+      ],
+      dst: [
+        'ibc',
+        ['chain', dstChain],
+        ['port', ibcChannel.counterPartyPortId],
+        ['channel', ibcChannel.counterPartyChannelId],
+      ],
+      seq: { status: 'pending' },
+      incomplete: true,
+    },
+  ]);
+
+/**
+ * @template {TrafficEntry} T
+ * @param {T} entry
+ * @param {TrafficEntry['seq']} sequence
+ * @returns {T}
+ */
+const attachGenericSequence = (entry, sequence) => {
+  const baseSequence = entry.seq;
+  Object(baseSequence)?.status === 'pending' ||
+    Fail`expected entry.seq ${baseSequence} to be pending`;
+  sequence != null || Fail`expected sequence ${sequence} to be non-nullish`;
+
+  return {
+    ...entry,
+    seq: sequence,
+  };
+};
+
+/**
+ * @param {(TrafficEntry<'ibc'> & { incomplete?: any })[]} entries
+ * @param {TrafficEntry<'ibc'>['seq']} sequence
+ * @returns {TrafficEntry<'ibc'>[]}
+ */
+const finishIbcTransfer = (entries, sequence) => {
+  entries.length === 1 || Fail`expected single traffic entry to finish`;
+  const [{ incomplete, ...entry }] = entries;
+  incomplete || Fail`expected incomplete traffic entry`;
+  entry.op === 'transfer' ||
+    Fail`expected transfer traffic entry, got ${entry.op}`;
+  entry.src[0] === 'ibc' || Fail`expected ibc source in transfer traffic entry`;
+  entry.dst[0] === 'ibc' || Fail`expected ibc dest in transfer traffic entry`;
+
+  return harden([attachGenericSequence(entry, sequence)]);
+};
+
+/**
+ * @param {CaipChainId} dstChain
+ * @returns {(TrafficEntry<'ibc'> & { incomplete: true })[]}
+ */
+const startIbcICA = dstChain =>
+  harden([
+    {
+      op: 'ICA',
+      src: ['ibc'],
+      dst: ['ibc', ['chain', dstChain]],
+      // the rest is filled in by ICA processing
+      seq: { status: 'pending' },
+      incomplete: true,
+    },
+  ]);
+
+/**
+ * @param {(TrafficEntry<'ibc'> & { incomplete?: any })[]} entries
+ * @param {CaipChainId} srcChain
+ * @param {Pick<IBCEndpoint, 'portID' | 'channelID'>} srcEndpoint
+ * @param {Pick<IBCEndpoint, 'portID' | 'channelID'>} dstEndpoint
+ * @param {TrafficEntry<'ibc'>['seq']} sequence
+ * @returns {TrafficEntry<'ibc'>[]}
+ */
+const finishIbcICA = (
+  entries,
+  srcChain,
+  srcEndpoint,
+  dstEndpoint,
+  sequence,
+) => {
+  entries.length === 1 || Fail`expected single traffic entry to finish`;
+  const [{ incomplete, ...entry }] = entries;
+  incomplete || Fail`expected incomplete traffic entry`;
+  entry.op === 'ICA' || Fail`expected ICA traffic entry`;
+
+  entry.src.length === 1 || Fail`expected source length 1 in ICA traffic entry`;
+  entry.src[0] === 'ibc' || Fail`expected ibc source in ICA traffic entry`;
+  const src = [
+    ...entry.src,
+    ['chain', srcChain],
+    ['port', srcEndpoint.portID],
+    ['channel', srcEndpoint.channelID],
+  ];
+
+  entry.dst.length === 2 || Fail`expected dest length 2 in ICA traffic entry`;
+  entry.dst[0] === 'ibc' || Fail`expected ibc dest in ICA traffic entry`;
+  const dst = [
+    ...entry.dst,
+    ['port', dstEndpoint.portID],
+    ['channel', dstEndpoint.channelID],
+  ];
+  return [
+    attachGenericSequence(
+      /** @type {TrafficEntry<'ibc'>} */ ({
+        ...entry,
+        src,
+        dst,
+      }),
+      sequence,
+    ),
+  ];
+};
+
+export const trafficTransforms = /** @type {const} */ ({
+  IbcTransfer: {
+    start: startIbcTransfer,
+    finish: finishIbcTransfer,
+  },
+  IbcICA: {
+    start: startIbcICA,
+    finish: finishIbcICA,
+  },
+});
+harden(trafficTransforms);
+
+/**
+ * @param {TrafficEntry[] | undefined} priorTraffic
+ * @param {TrafficEntry[]} newEntries
+ * @returns {{ traffic: TrafficEntry[]; slice: SliceDescriptor }}
+ */
+export const addTrafficEntries = (priorTraffic, newEntries) => {
+  const entries = priorTraffic ?? [];
+  const start = entries.length;
+  const end = start + newEntries.length;
+  return harden({
+    traffic: [...entries, ...newEntries],
+    slice: {
+      start,
+      end,
+    },
+  });
+};
+harden(addTrafficEntries);
+
+/**
+ * @param {TrafficEntry[] | undefined} priorTraffic
+ * @param {SliceDescriptor | undefined} sliceDescriptor
+ * @param {(entries: TrafficEntry[]) => TrafficEntry[]} finisher
+ * @returns {TrafficEntry[]}
+ */
+export const finishTrafficEntries = (
+  priorTraffic,
+  sliceDescriptor,
+  finisher,
+) => {
+  const entries = priorTraffic ?? [];
+  const slice = sliceDescriptor ?? { start: 0, end: entries.length };
+
+  const toTransform = harden(entries.slice(slice.start, slice.end));
+  toTransform.length > 0 || Fail`no traffic entries to finish`;
+
+  const transformed = harden(finisher(toTransform));
+  transformed.length === toTransform.length ||
+    Fail`traffic entry transform must not change length; expected ${toTransform.length}, got ${transformed.length}`;
+
+  const pre = entries.slice(0, slice.start);
+  const post = entries.slice(slice.end);
+  return harden([...pre, ...transformed, ...post]);
 };
+harden(finishTrafficEntries);

package/src/utils/progress.d.ts

@@ -0,0 +1,41 @@
+export namespace progressTrackerAsyncFlowUtils {
+    function promiseFromVow<T>(specimen: T): Promise<Fulfilled<T>>;
+    function reduceProgressReports<A = unknown>(tracker: ProgressTracker, reducer: PublicationReducer<ProgressReport, A>, initialAccum: A): Promise<A>;
+}
+export function prepareProgressTracker(zone: Zone, { vowTools: { makeVowKit } }: {
+    vowTools: Pick<VowTools, "makeVowKit">;
+}): () => import("@endo/exo").Guarded<{
+    getCurrentProgressReport(): ProgressReport;
+    /**
+     * @param {ProgressReport} progressReport
+     */
+    update(progressReport: ProgressReport): ProgressReport;
+    finish(): ProgressReport;
+    /**
+     * CAVEAT: Intended for use only by `progress.js` utilities.
+     *
+     * @returns {PublicationInternals<ProgressReport>}
+     * @internal
+     */
+    exposePublicationInternals(): PublicationInternals<ProgressReport>;
+}>;
+export type ProgressReport = Record<string, any>;
+export type PublicationInternals<T> = {
+    value: T;
+    tail: EVow<PublicationInternals<T>>;
+};
+/**
+ * Called on the value of each linked T. This
+ *   function should perform any side-effects it can when it receives a new
+ *   value, since there is no guarantee that the ProgressRecord tail will be
+ *   prompt (it may take a long time with cross-chain communication) or ever
+ *   fulfill (it may result in a rejection).
+ */
+export type PublicationReducer<T, A = unknown> = (value: T | undefined | null, accum: A) => EVow<A | null>;
+export type MakeProgressTracker = ReturnType<typeof prepareProgressTracker>;
+export type ProgressTracker = ReturnType<MakeProgressTracker>;
+import type { Fulfilled } from '@agoric/vow';
+import type { Zone } from '@agoric/base-zone';
+import type { VowTools } from '@agoric/vow';
+import type { EVow } from '@agoric/vow';
+//# sourceMappingURL=progress.d.ts.map

package/src/utils/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["progress.js"],"names":[],"mappings":";IAgDkB,wBAJH,CAAC,YACH,CAAC,GACC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAQjC;IAcsB,+BATT,CAAC,qBACJ,eAAe,WACf,kBAAkB,CAAC,cAAc,EAAE,CAAC,CAAC,gBACrC,CAAC,GAIC,OAAO,CAAC,CAAC,CAAC,CA0BtB;;AAYI,6CAJI,IAAI,gCAEZ;IAA6C,QAAQ,EAA7C,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC;CACtC;;IA0BO;;OAEG;2BADQ,cAAc;;IAyBzB;;;;;OAKG;kCAFU,oBAAoB,CAAC,cAAc,CAAC;GAYxD;6BA9JY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;iCAInB,CAAC;WAEA,CAAC;UACD,KAAK,oBAAoB,CAAC,CAAC,CAAC,CAAC;;;;;;;;;+BAI9B,CAAC,EACA,CAAC,sBAMJ,CAAC,GAAG,SAAS,GAAG,IAAI,SAEpB,CAAC,KACC,KAAK,CAAC,GAAG,IAAI,CAAC;kCA6Id,UAAU,CAAC,OAAO,sBAAsB,CAAC;8BAIzC,UAAU,CAAC,mBAAmB,CAAC;+BA3KA,aAAa;0BAClC,mBAAmB;8BADE,aAAa;0BAAb,aAAa"}

package/src/utils/progress.js

@@ -0,0 +1,180 @@
+/**
+ * @file Utilities for working with ResultMeta<T>.
+ */
+
+import { isVow } from '@agoric/vow/src/vow-utils.js';
+
+/**
+ * @import {EVow, VowTools, Fulfilled} from '@agoric/vow';
+ * @import {Zone} from '@agoric/base-zone';
+ */
+
+/**
+ * @typedef {Record<string, any>} ProgressReport
+ */
+
+/**
+ * @template T
+ * @typedef {object} PublicationInternals
+ * @property {T} value
+ * @property {EVow<PublicationInternals<T>>} tail
+ */
+
+/**
+ * @template T
+ * @template [A=unknown]
+ * @callback PublicationReducer Called on the value of each linked T. This
+ *   function should perform any side-effects it can when it receives a new
+ *   value, since there is no guarantee that the ProgressRecord tail will be
+ *   prompt (it may take a long time with cross-chain communication) or ever
+ *   fulfill (it may result in a rejection).
+ * @param {T | undefined | null} value `value == null` is a sentinel for the
+ *   final reducer call.
+ * @param {A} accum previous reduction value
+ * @returns {EVow<A | null>} Returning `null` exits the reduction
+ */
+
+/**
+ * Utilities for working with ResultMeta within an async flow.
+ */
+export const progressTrackerAsyncFlowUtils = {
+  /**
+   * Converts a specimen to a Promise. Since the use of Vows is only needed
+   * outside of async-flows, we currently reject if we encounter one.
+   *
+   * @template T
+   * @param {T} specimen
+   * @returns {Promise<Fulfilled<T>>}
+   */
+  promiseFromVow: async specimen => {
+    const maybeVow = await specimen;
+    !isVow(maybeVow) ||
+      assert.Fail`Unexpected Vow ${maybeVow}; only use progress utilities within async flows (withOrchestration)`;
+
+    return /** @type {Fulfilled<T>} */ (maybeVow);
+  },
+
+  /**
+   * Extracts reports from a tracker, calling `reducer` on each.
+   *
+   * @template [A=unknown]
+   * @param {ProgressTracker} tracker
+   * @param {PublicationReducer<ProgressReport, A>} reducer
+   * @param {A} initialAccum accumulator to pass to the reducer on the first
+   *   call. Providing the initial accumulator avoids having to deal with
+   *   `undefined` values in the reducer or explicitly specify the desired
+   *   type.
+   * @returns {Promise<A>} the accumulated result
+   */
+  reduceProgressReports: async (tracker, reducer, initialAccum) => {
+    const { promiseFromVow } = progressTrackerAsyncFlowUtils;
+
+    /** @type {PublicationInternals<ProgressReport> | null} */
+    let nextReport = await promiseFromVow(tracker.exposePublicationInternals());
+    let accum = harden(initialAccum);
+
+    while (true) {
+      const reduction = await promiseFromVow(
+        reducer(nextReport?.value ?? null, accum),
+      );
+      harden(reduction);
+
+      if (reduction == null) {
+        nextReport = null;
+      } else {
+        accum = /** @type {A} */ (reduction);
+      }
+      if (nextReport == null) {
+        return accum;
+      }
+
+      nextReport = (await promiseFromVow(nextReport?.tail)) ?? null;
+    }
+  },
+};
+
+harden(progressTrackerAsyncFlowUtils);
+
+/**
+ * A helper for ProgressPublication operations via VowTools.
+ *
+ * @param {Zone} zone
+ * @param {object} powers
+ * @param {Pick<VowTools, 'makeVowKit'>} powers.vowTools
+ */
+export const prepareProgressTracker = (zone, { vowTools: { makeVowKit } }) => {
+  const makeProgressTrackerKit = zone.exoClassKit(
+    'ProgressTrackerKit',
+    undefined,
+    () => {
+      const { vow: nextReport, resolver: tailResolver } = makeVowKit();
+
+      /** @type {PublicationInternals<ProgressReport>} */
+      const currentPublication = harden({
+        value: {},
+        tail: nextReport,
+      });
+      return {
+        currentPublication,
+        done: false,
+        tailResolver,
+      };
+    },
+    {
+      helper: {},
+      public: {
+        getCurrentProgressReport() {
+          const { currentPublication } = this.state;
+          return currentPublication.value;
+        },
+        /**
+         * @param {ProgressReport} progressReport
+         */
+        update(progressReport) {
+          const { currentPublication, tailResolver, done } = this.state;
+          if (done) {
+            return currentPublication.value;
+          }
+
+          const { vow: nextTail, resolver: nextTailResolver } = makeVowKit();
+
+          const tail = harden({ value: progressReport, tail: nextTail });
+          this.state.currentPublication = tail;
+          tailResolver.resolve(tail);
+          this.state.tailResolver = nextTailResolver;
+          return progressReport;
+        },
+        finish() {
+          const { currentPublication, tailResolver, done } = this.state;
+          if (!done) {
+            tailResolver.resolve(null);
+            this.state.done = true;
+          }
+
+          return currentPublication.value;
+        },
+        /**
+         * CAVEAT: Intended for use only by `progress.js` utilities.
+         *
+         * @returns {PublicationInternals<ProgressReport>}
+         * @internal
+         */
+        exposePublicationInternals() {
+          return this.state.currentPublication;
+        },
+      },
+    },
+  );
+
+  const makeProgressTracker = () => makeProgressTrackerKit().public;
+  return harden(makeProgressTracker);
+};
+harden(prepareProgressTracker);
+
+/**
+ * @typedef {ReturnType<typeof prepareProgressTracker>} MakeProgressTracker
+ */
+
+/**
+ * @typedef {ReturnType<MakeProgressTracker>} ProgressTracker
+ */

package/src/utils/start-helper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"start-helper.d.ts","sourceRoot":"","sources":["start-helper.js"],"names":[],"mappings":"AA+DO,0CARI,GAAG,WACH,OAAO,gBACP,mBAAmB,oBACnB,OAAO,UAAU,CAAC,SAE1B;IAA4D,mBAAmB,GAAvE,qBAAqB,CAAC,qBAAqB,CAAC;CACpD;+BAwGU,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBA1Ed,CAAC;;;;;;;;;;;;;;;;;;;;;sBAgKu9V,CAAC;;;;;;;;;;;;;;;;;;;;;;;;EApD39V;AA+BM,kCAfgC,EAAE,SAA3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAE,EAGhC,EAAE,SAFM,mBAAmB,GAAG;IAC/B,UAAU,EAAE,OAAO,UAAU,CAAC,CAAC;CAC/B,EACQ,CAAC,cACH,CACN,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,EACZ,WAAW,EAAE,EAAE,EACf,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,kBAAkB,KACtB,OAAO,CAAC,CAAC,CAAC,SACP,qBAAqB,GACnB,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,CAsBzE;kCA3NU;IACR,UAAU,EAAE,OAAO,UAAU,CAAC,CAAC;IAC/B,oBAAoB,EAAE,OAAO,uBAAuB,CAAC,CAAC;IACtD,WAAW,CAAC,EAAE,OAAO,WAAW,CAAC,CAAC;IAClC,YAAY,EAAE,OAAO,YAAY,CAAC,CAAC;IACnC,WAAW,EAAE,OAAO,OAAO,CAAC,CAAC;CAC9B;;;;;;;;;;;;;0BAQU,OAAO;;iCA8JP,IAAI,CAAC,UAAU,CAAC,OAAO,oBAAoB,CAAC,EAAE,MAAM,CAAC;6BArLzC,kBAAkB;4BAEnB,aAAa;0BACf,cAAc;6BACX,gBAAgB;gCANb,gCAAgC;6CAOnB,2BAA2B;iCATvC,0CAA0C;kCAGzC,cAAc;6BAEnB,cAAc"}
+{"version":3,"file":"start-helper.d.ts","sourceRoot":"","sources":["start-helper.js"],"names":[],"mappings":"AAgEO,0CARI,GAAG,WACH,OAAO,gBACP,mBAAmB,oBACnB,OAAO,UAAU,CAAC,SAE1B;IAA4D,mBAAmB,GAAvE,qBAAqB,CAAC,qBAAqB,CAAC;CACpD;+BA6GU,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAnF8C,CAAC;;;;;;;;;;;;;;;;;;;;;sBAyK6sV,CAAC;;;;;;;;;;;;;;;;;;;;;;;;EApD7wV;AA+BM,kCAfgC,EAAE,SAA3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAE,EAGhC,EAAE,SAFM,mBAAmB,GAAG;IAC/B,UAAU,EAAE,OAAO,UAAU,CAAC,CAAC;CAC/B,EACQ,CAAC,cACH,CACN,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,EACZ,WAAW,EAAE,EAAE,EACf,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,kBAAkB,KACtB,OAAO,CAAC,CAAC,CAAC,SACP,qBAAqB,GACnB,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,CAsBzE;kCAhOU;IACR,UAAU,EAAE,OAAO,UAAU,CAAC,CAAC;IAC/B,oBAAoB,EAAE,OAAO,uBAAuB,CAAC,CAAC;IACtD,WAAW,CAAC,EAAE,OAAO,WAAW,CAAC,CAAC;IAClC,YAAY,EAAE,OAAO,YAAY,CAAC,CAAC;IACnC,WAAW,EAAE,OAAO,OAAO,CAAC,CAAC;CAC9B;;;;;;;;;;;;;0BAQU,OAAO;;iCAmKP,IAAI,CAAC,UAAU,CAAC,OAAO,oBAAoB,CAAC,EAAE,MAAM,CAAC;6BA1LzC,kBAAkB;4BAEnB,aAAa;0BACf,cAAc;6BACX,gBAAgB;gCANb,gCAAgC;6CAOnB,2BAA2B;iCATvC,0CAA0C;kCAGzC,cAAc;6BAEnB,cAAc"}

package/src/utils/start-helper.js

@@ -7,6 +7,7 @@ import { makeChainHub } from '../exos/chain-hub.js';
 import { prepareCosmosOrchestrationAccount } from '../exos/cosmos-orchestration-account.js';
 import { prepareLocalChainFacade } from '../exos/local-chain-facade.js';
 import { prepareLocalOrchestrationAccountKit } from '../exos/local-orchestration-account.js';
+import { prepareProgressTracker } from './progress.js';
 import { prepareOrchestrator } from '../exos/orchestrator.js';
 import { prepareRemoteChainFacade } from '../exos/remote-chain-facade.js';
 import { makeOrchestrationFacade } from '../facade.js';
@@ -103,9 +104,13 @@ export const provideOrchestration = (
     baggage,
     cachingMarshaller,
   );
+  const makeProgressTracker = prepareProgressTracker(zones.orchestration, {
+    vowTools,
+  });
   const makeLocalOrchestrationAccountKit = prepareLocalOrchestrationAccountKit(
     zones.orchestration,
     {
+      makeProgressTracker,
       makeRecorderKit,
       zcf,
       timerService,
@@ -124,6 +129,7 @@ export const provideOrchestration = (
     zones.orchestration,
     {
       chainHub,
+      makeProgressTracker,
       makeRecorderKit,
       timerService,
       vowTools,