@agoric/vats 0.15.2-dev-c19f1b5.0 → 0.15.2-dev-27cc9b8.0

package/src/transfer.js

@@ -0,0 +1,271 @@
+// @ts-check
+import { E } from '@endo/far';
+import { M } from '@endo/patterns';
+import { VTRANSFER_IBC_EVENT } from '@agoric/internal';
+import { coerceToByteSource, byteSourceToBase64 } from '@agoric/network';
+import {
+  prepareBridgeTargetModule,
+  TargetAppI,
+  AppTransformerI,
+} from './bridge-target.js';
+
+/**
+ * @import {TargetApp, TargetHost} from './bridge-target.js'
+ */
+
+const { Fail, bare } = assert;
+
+/**
+ * The least possibly restrictive guard for a `watch` watcher's `onFulfilled` or
+ * `onRejected` reaction
+ */
+const ReactionGuard = M.call(M.any()).optional(M.any()).returns(M.any());
+
+/**
+ * @param {import('@agoric/base-zone').Zone} zone
+ * @param {import('@agoric/vow').VowTools} vowTools
+ */
+const prepareTransferInterceptor = (zone, vowTools) => {
+  const { watch } = vowTools;
+  const makeTransferInterceptorKit = zone.exoClassKit(
+    'TransferInterceptorKit',
+    {
+      public: TargetAppI,
+      encodeAckWatcher: M.interface('EncodeAckWatcher', {
+        onFulfilled: ReactionGuard,
+      }),
+      sendErrorWatcher: M.interface('SendErrorWatcher', {
+        onRejected: ReactionGuard,
+      }),
+      logErrorWatcher: M.interface('LogErrorWatcher', {
+        onRejected: ReactionGuard,
+      }),
+    },
+    /**
+     * @param {ERef<TargetApp>} tap
+     * @param {ERef<TargetHost>} targetHost
+     * @param {boolean} [isActiveTap] Whether the tap is active (can modify
+     *   acknowledgements), or passive (can't cause delays in the middleware).
+     */
+    (tap, targetHost, isActiveTap = false) => ({
+      isActiveTap,
+      tap,
+      targetHost,
+    }),
+    {
+      public: {
+        async receiveUpcall(obj) {
+          const { isActiveTap, tap, targetHost } = this.state;
+
+          obj.type === VTRANSFER_IBC_EVENT ||
+            Fail`Invalid upcall argument type ${obj.type}; expected ${bare(VTRANSFER_IBC_EVENT)}`;
+
+          // First, call our target contract listener.
+          // A VTransfer active interceptor can return a write acknowledgement
+          /** @type {import('@agoric/vow').Vow<unknown>} */
+          let retP = watch(E(tap).receiveUpcall(obj));
+
+          // See if the upcall result needs special handling.
+          if (obj.event === 'writeAcknowledgement') {
+            const ackMethodData = {
+              type: 'IBC_METHOD',
+              method: 'receiveExecuted',
+              packet: obj.packet,
+            };
+            if (isActiveTap) {
+              retP = watch(retP, this.facets.encodeAckWatcher, {
+                ackMethodData,
+              });
+            } else {
+              // This is a passive tap, so forward the ack without intervention.
+              ackMethodData.ack = obj.acknowledgement;
+              retP = watch(E(targetHost).sendDowncall(ackMethodData));
+            }
+            retP = watch(retP, this.facets.sendErrorWatcher, { ackMethodData });
+          }
+
+          // Log errors in the upcall handling.
+          retP = watch(retP, this.facets.logErrorWatcher, { obj });
+
+          if (isActiveTap) {
+            // If the tap is active, return the promiseVow to the caller.  This
+            // will delay the middleware until fulfilment of the retP chain.
+            return retP;
+          }
+
+          // Otherwise, passively return nothing.
+        },
+      },
+      /**
+       * `watch` callback for encoding the raw `ack` return value from an active
+       * `writeAcknowledgement` tap as base64, then sending down to the
+       * targetHost.
+       */
+      encodeAckWatcher: {
+        onFulfilled(rawAck, { ackMethodData }) {
+          // Encode the tap's ack and write it out.
+          const ack = byteSourceToBase64(coerceToByteSource(rawAck));
+          ackMethodData = { ...ackMethodData, ack };
+          return E(this.state.targetHost).sendDowncall(ackMethodData);
+        },
+      },
+      /**
+       * `watch` callback for handling errors in the sending of an ack and
+       * reifying it as an error acknowledgement.
+       */
+      sendErrorWatcher: {
+        onRejected(error, { ackMethodData }) {
+          console.error(`Error sending ack:`, error);
+          const rawAck = JSON.stringify({ error: error.message });
+          ackMethodData = { ...ackMethodData, ack: byteSourceToBase64(rawAck) };
+          return E(this.state.targetHost).sendDowncall(ackMethodData);
+        },
+      },
+      /** `watch` callback for logging errors in the upcall handling. */
+      logErrorWatcher: {
+        onRejected(error, { obj }) {
+          console.error(`Error in handling of`, obj, error);
+        },
+      },
+    },
+  );
+
+  /**
+   * A TransferInterceptor wraps a TargetApp that is specialized for handling
+   * asynchronous callbacks from the IBC transfer protocol as implemented by
+   * `x/vtransfer`. By using this interceptor, the TargetApp is prevented from
+   * sending messages which may violate the transfer protocol directly to the
+   * `targetHost`.
+   *
+   * @param {Parameters<typeof makeTransferInterceptorKit>} args
+   */
+  const makeTransferInterceptor = (...args) =>
+    makeTransferInterceptorKit(...args).public;
+  return makeTransferInterceptor;
+};
+harden(prepareTransferInterceptor);
+
+const TransferMiddlewareKitFinisherI = M.interface(
+  'TransferMiddlewareKitFinisher',
+  {
+    useRegistry: M.call(M.remotable('TargetRegistry')).returns(),
+  },
+);
+
+const TransferMiddlewareI = M.interface('TransferMiddleware', {
+  registerTap: M.callWhen(
+    M.string(),
+    M.remotable('TransferInterceptor'),
+  ).returns(M.remotable('TargetRegistration')),
+  registerActiveTap: M.callWhen(
+    M.string(),
+    M.remotable('TransferInterceptor'),
+  ).returns(M.remotable('TargetRegistration')),
+  unregisterTap: M.callWhen(M.string()).returns(),
+});
+
+/**
+ * @callback RegisterTap
+ * @param {string} target String identifying the bridge target.
+ * @param {ERef<import('./bridge-target.js').TargetApp>} tap The "application
+ *   tap" to register for the target.
+ */
+
+/**
+ * A TransferMiddlewareKit has a `transferMiddleware` facet with methods for
+ * registering and unregistering active and passive "taps" in a BridgeTargetKit
+ * registry that must use the `interceptorFactory` facet as its appTransfomer to
+ * enforce IBC transfer protocol conformance. Before registering any taps, the
+ * backing BridgeTargetKit must be set with the `finisher` facet (i.e., the
+ * expected setup pattern is to pass in `interceptorFactory` as the
+ * appTransformer argument when making a BridgeTargetKit and then to invoke
+ * `finisher.useRegistry` with the `targetRegistry` of that BridgeTargetKit
+ * before making further use of the TransferMiddlewareKit or connecting the
+ * BridgeTargetKit to a bridge).
+ *
+ * @param {import('@agoric/base-zone').Zone} zone
+ * @param {ReturnType<typeof prepareTransferInterceptor>} makeTransferInterceptor
+ */
+const prepareTransferMiddlewareKit = (zone, makeTransferInterceptor) =>
+  zone.exoClassKit(
+    'TransferMiddlewareKit',
+    {
+      finisher: TransferMiddlewareKitFinisherI,
+      interceptorFactory: AppTransformerI,
+      transferMiddleware: TransferMiddlewareI,
+    },
+    () => ({
+      /** @type {import('./bridge-target').TargetRegistry | undefined} */
+      targetRegistry: undefined,
+    }),
+    {
+      finisher: {
+        /**
+         * @param {import('./bridge-target').TargetRegistry} registry
+         */
+        useRegistry(registry) {
+          this.state.targetRegistry = registry;
+        },
+      },
+      interceptorFactory: {
+        wrapApp: makeTransferInterceptor,
+      },
+      transferMiddleware: {
+        /**
+         * Register a tap to intercept the vtransfer target account address
+         * messages, without granting that tap the ability to delay or interfere
+         * with the underlying IBC transfer protocol.
+         *
+         * @type {RegisterTap}
+         */
+        async registerTap(target, tap) {
+          const { targetRegistry } = this.state;
+          if (!targetRegistry) throw Fail`Registry not initialized`;
+          return E(targetRegistry).register(target, tap, []);
+        },
+        /**
+         * Similar to `registerTap`, but allows the tap to inject async
+         * acknowledgements in the IBC transfer protocol.
+         *
+         * @type {RegisterTap}
+         */
+        async registerActiveTap(target, tap) {
+          const { targetRegistry } = this.state;
+          if (!targetRegistry) throw Fail`Registry not initialized`;
+          return E(targetRegistry).register(target, tap, [true]);
+        },
+        /**
+         * Unregister the target.
+         *
+         * @param {string} target String identifying the bridge target to stop
+         *   tapping.
+         */
+        async unregisterTap(target) {
+          const { targetRegistry } = this.state;
+          if (!targetRegistry) throw Fail`Registry not initialized`;
+          await E(targetRegistry).unregister(target);
+        },
+      },
+    },
+  );
+/** @typedef {ReturnType<ReturnType<typeof prepareTransferMiddlewareKit>>} TransferMiddlewareKit */
+/** @typedef {TransferMiddlewareKit['transferMiddleware']} TransferMiddleware */
+
+/**
+ * @param {import('@agoric/base-zone').Zone} zone
+ * @param {import('@agoric/vow').VowTools} vowTools
+ */
+export const prepareTransferTools = (zone, vowTools) => {
+  const makeTransferInterceptor = prepareTransferInterceptor(zone, vowTools);
+  const { makeBridgeTargetKit } = prepareBridgeTargetModule(
+    zone.subZone('bridge-target'),
+  );
+
+  const makeTransferMiddlewareKit = prepareTransferMiddlewareKit(
+    zone,
+    makeTransferInterceptor,
+  );
+
+  return harden({ makeTransferMiddlewareKit, makeBridgeTargetKit });
+};
+harden(prepareTransferTools);

package/src/types.d.ts

@@ -1,6 +1,5 @@
 import type { BridgeIdValue, Remote } from '@agoric/internal';
 import type { Bytes } from '@agoric/network';
-import type { PromiseVow } from '@agoric/vow';
 import type { Guarded } from '@endo/exo';
 
 export type Board = ReturnType<
@@ -92,7 +91,7 @@ export type NamesByAddressAdmin = NameAdmin & {
 /** An object that can receive messages from the bridge device */
 export type BridgeHandler = {
   /** Handle an inbound message */
-  fromBridge: (obj: any) => PromiseVow<void>;
+  fromBridge: (obj: any) => Promise<unknown>;
 };
 
 /** An object which handles messages for a specific bridge */
@@ -103,8 +102,10 @@ export type ScopedBridgeManager<BridgeId extends BridgeIdValue> = Guarded<{
    * system to hang the bridgeId
    */
   getBridgeId?: () => BridgeId;
+  /** Downcall from the VM into Golang */
   toBridge: (obj: any) => Promise<any>;
-  fromBridge: (obj: any) => PromiseVow<void>;
+  /** Upcall from Golang into the VM */
+  fromBridge: (obj: any) => Promise<unknown>;
   initHandler: (handler: Remote<BridgeHandler>) => void;
   setHandler: (handler: Remote<BridgeHandler>) => void;
 }>;

package/src/vat-ibc.d.ts

@@ -2,20 +2,6 @@ export function buildRootObject(_vatPowers: any, _args: any, baggage: any): {
     createHandlers: (callbacks: any) => {
         protocolHandler: import("@agoric/network").ProtocolHandler;
         bridgeHandler: import("./types.js").BridgeHandler;
-    } | {
-        protocolHandler: import("@endo/exo").Guarded<{
-            onCreate(protocol: import("@agoric/internal").Remote<import("@agoric/network").ProtocolImpl>, p: import("@agoric/internal").Remote<import("@agoric/network").ProtocolHandler>): import("@agoric/vow").PromiseVow<void>;
-            onInstantiate(port: import("@agoric/internal").Remote<import("@agoric/network").Port>, localAddr: Endpoint, remote: Endpoint, p: import("@agoric/internal").Remote<import("@agoric/network").ProtocolHandler>): import("@agoric/vow").PromiseVow<string>;
-            generatePortID(localAddr: Endpoint, p: import("@agoric/internal").Remote<import("@agoric/network").ProtocolHandler>): import("@agoric/vow").PromiseVow<string>;
-            onBind(port: import("@agoric/internal").Remote<import("@agoric/network").Port>, localAddr: Endpoint, p: import("@agoric/internal").Remote<import("@agoric/network").ProtocolHandler>): import("@agoric/vow").PromiseVow<void>;
-            onConnect(port: import("@agoric/internal").Remote<import("@agoric/network").Port>, localAddr: Endpoint, remote: Endpoint, c: import("@agoric/internal").Remote<import("@agoric/network").ConnectionHandler>, p: import("@agoric/internal").Remote<import("@agoric/network").ProtocolHandler>): import("@agoric/vow").PromiseVow<import("@agoric/network").AttemptDescription>;
-            onListen(port: import("@agoric/internal").Remote<import("@agoric/network").Port>, localAddr: Endpoint, listenHandler: import("@agoric/internal").Remote<import("@agoric/network").ListenHandler>, p: import("@agoric/internal").Remote<import("@agoric/network").ProtocolHandler>): import("@agoric/vow").PromiseVow<void>;
-            onListenRemove(port: import("@agoric/internal").Remote<import("@agoric/network").Port>, localAddr: Endpoint, listenHandler: import("@agoric/internal").Remote<import("@agoric/network").ListenHandler>, p: import("@agoric/internal").Remote<import("@agoric/network").ProtocolHandler>): import("@agoric/vow").PromiseVow<void>;
-            onRevoke(port: import("@agoric/internal").Remote<import("@agoric/network").Port>, localAddr: Endpoint, p: import("@agoric/internal").Remote<import("@agoric/network").ProtocolHandler>): import("@agoric/vow").PromiseVow<void>;
-        }>;
-        bridgeHandler: import("@endo/exo").Guarded<{
-            fromBridge(obj: import("./types.js").IBCEvent<import("./types.js").IBCBridgeEvent>): Promise<import("@agoric/vow").Vow<any> | undefined>;
-        }>;
     };
     makeCallbacks: (dibcBridgeManager: import("./types.js").ScopedBridgeManager<"dibc">) => import("@endo/exo").Guarded<{
         downcall(method: string, obj: any): Promise<any>;
@@ -24,20 +10,6 @@ export function buildRootObject(_vatPowers: any, _args: any, baggage: any): {
     createHandlers: (callbacks: any) => {
         protocolHandler: import("@agoric/network").ProtocolHandler;
         bridgeHandler: import("./types.js").BridgeHandler;
-    } | {
-        protocolHandler: import("@endo/exo").Guarded<{
-            onCreate(protocol: import("@agoric/internal").Remote<import("@agoric/network").ProtocolImpl>, p: import("@agoric/internal").Remote<import("@agoric/network").ProtocolHandler>): import("@agoric/vow").PromiseVow<void>;
-            onInstantiate(port: import("@agoric/internal").Remote<import("@agoric/network").Port>, localAddr: Endpoint, remote: Endpoint, p: import("@agoric/internal").Remote<import("@agoric/network").ProtocolHandler>): import("@agoric/vow").PromiseVow<string>;
-            generatePortID(localAddr: Endpoint, p: import("@agoric/internal").Remote<import("@agoric/network").ProtocolHandler>): import("@agoric/vow").PromiseVow<string>;
-            onBind(port: import("@agoric/internal").Remote<import("@agoric/network").Port>, localAddr: Endpoint, p: import("@agoric/internal").Remote<import("@agoric/network").ProtocolHandler>): import("@agoric/vow").PromiseVow<void>;
-            onConnect(port: import("@agoric/internal").Remote<import("@agoric/network").Port>, localAddr: Endpoint, remote: Endpoint, c: import("@agoric/internal").Remote<import("@agoric/network").ConnectionHandler>, p: import("@agoric/internal").Remote<import("@agoric/network").ProtocolHandler>): import("@agoric/vow").PromiseVow<import("@agoric/network").AttemptDescription>;
-            onListen(port: import("@agoric/internal").Remote<import("@agoric/network").Port>, localAddr: Endpoint, listenHandler: import("@agoric/internal").Remote<import("@agoric/network").ListenHandler>, p: import("@agoric/internal").Remote<import("@agoric/network").ProtocolHandler>): import("@agoric/vow").PromiseVow<void>;
-            onListenRemove(port: import("@agoric/internal").Remote<import("@agoric/network").Port>, localAddr: Endpoint, listenHandler: import("@agoric/internal").Remote<import("@agoric/network").ListenHandler>, p: import("@agoric/internal").Remote<import("@agoric/network").ProtocolHandler>): import("@agoric/vow").PromiseVow<void>;
-            onRevoke(port: import("@agoric/internal").Remote<import("@agoric/network").Port>, localAddr: Endpoint, p: import("@agoric/internal").Remote<import("@agoric/network").ProtocolHandler>): import("@agoric/vow").PromiseVow<void>;
-        }>;
-        bridgeHandler: import("@endo/exo").Guarded<{
-            fromBridge(obj: import("./types.js").IBCEvent<import("./types.js").IBCBridgeEvent>): Promise<import("@agoric/vow").Vow<any> | undefined>;
-        }>;
     };
     makeCallbacks: (dibcBridgeManager: import("./types.js").ScopedBridgeManager<"dibc">) => import("@endo/exo").Guarded<{
         downcall(method: string, obj: any): Promise<any>;

package/src/vat-ibc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vat-ibc.d.ts","sourceRoot":"","sources":["vat-ibc.js"],"names":[],"mappings":"AAKA;;;;;;;8GAoB84I,QAAS,UAAc,QAAS;sCAAlyB,QAAS;uGAAkL,QAAS;0GAAmxB,QAAS,UAAc,QAAS;yGAA7pB,QAAS;+GAAmM,QAAS;yGAAqqB,QAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GADx2J"}
+{"version":3,"file":"vat-ibc.d.ts","sourceRoot":"","sources":["vat-ibc.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;GAmBC"}

package/src/vat-localchain.d.ts

@@ -14,6 +14,7 @@ export function buildRootObject(_vatPowers: any, _args: any, baggage: any): {
             executeTx<MT extends {
                 '@type': string;
             }[]>(messages: MT): Promise<{ [K in keyof MT]: import("@agoric/cosmic-proto").JsonSafe<import("@agoric/cosmic-proto").ResponseTo<MT[K]>>; }>;
+            monitorTransfers(tap: any): Promise<any>;
         }>>;
         query(request: import("@agoric/cosmic-proto").TypedJson): Promise<{
             '@type': string;
@@ -41,6 +42,7 @@ export function buildRootObject(_vatPowers: any, _args: any, baggage: any): {
             executeTx<MT extends {
                 '@type': string;
             }[]>(messages: MT): Promise<{ [K in keyof MT]: import("@agoric/cosmic-proto").JsonSafe<import("@agoric/cosmic-proto").ResponseTo<MT[K]>>; }>;
+            monitorTransfers(tap: any): Promise<any>;
         }>>;
         query(request: import("@agoric/cosmic-proto").TypedJson): Promise<{
             '@type': string;

package/src/vat-localchain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vat-localchain.d.ts","sourceRoot":"","sources":["vat-localchain.js"],"names":[],"mappings":"AAMO;IAKH;;;;;OAKG;2BADQ,OAAO,iBAAiB,EAAE,gBAAgB;;;8BASgnB,MAAM,KAAK,CAAC;6BAA8b,QAAQ,KAAK,CAAC,mBAA2B,OAAO;6BAAwhB,OAAO,KAAK,CAAC;;;2BAAgiB,EAAE;;uBAAupE,OAAO,sBAAsB,EAAE,SAAS;;;4BAAyqB,OAAO,sBAAsB,EAAE,SAAS,EAAE;;;;;;;;IAbxnK;;;;;OAKG;2BADQ,OAAO,iBAAiB,EAAE,gBAAgB;;;;;;;;;;sDASu2I,SAAS;;;2DAAwsB,SAAS;;;;;;;GAHznK;4BAEa,UAAU,CAAC,OAAO,eAAe,CAAC"}
+{"version":3,"file":"vat-localchain.d.ts","sourceRoot":"","sources":["vat-localchain.js"],"names":[],"mappings":"AAMO;IAKH;;;;;OAKG;2BADQ,OAAO,iBAAiB,EAAE,gBAAgB;;;8BASs1B,MAAM,KAAK,CAAC;6BAA8b,QAAQ,KAAK,CAAC,mBAA2B,OAAO;6BAAwhB,OAAO,KAAK,CAAC;;;2BAAgiB,EAAE;;;uBAAg0E,OAAO,sBAAsB,EAAE,SAAS;;;4BAAyqB,OAAO,sBAAsB,EAAE,SAAS,EAAE;;;;;;;;IAbvgL;;;;;OAKG;2BADQ,OAAO,iBAAiB,EAAE,gBAAgB;;;;;;;;;;;sDASsvJ,SAAS;;;2DAAwsB,SAAS;;;;;;;GAHxgL;4BAEa,UAAU,CAAC,OAAO,eAAe,CAAC"}

package/src/vat-transfer.d.ts

@@ -0,0 +1,81 @@
+export function buildRootObject(_vatPowers: any, _args: any, baggage: any): {
+    /**
+     * @template {import('@agoric/internal').BridgeIdValue} T
+     * @param {import('./types').ScopedBridgeManager<T>} manager
+     * @param {string} [inboundType]
+     * @param {import('./bridge-target').AppTransformer} [appTransformer]
+     */
+    provideBridgeTargetKit<T extends import("@agoric/internal").BridgeIdValue>(manager: import("./types").ScopedBridgeManager<T>, inboundType?: string | undefined, appTransformer?: import("./bridge-target.js").AppTransformer | undefined): import("@endo/exo").GuardedKit<{
+        bridgeHandler: {
+            fromBridge(obj: any): Promise<any>;
+        };
+        targetHost: {
+            sendDowncall(obj: any): Promise<any>;
+        };
+        targetRegistry: {
+            register(target: string, app: TargetApp, args?: unknown[] | undefined): Promise<import("./bridge-target.js").TargetRegistration>;
+            reregister(target: string, app: TargetApp, args?: unknown[] | undefined): Promise<void>;
+            unregister(target: string): Promise<void>;
+        };
+    }>;
+    /**
+     * Create middleware for exposing IBC messages to and from the underlying
+     * vtransfer port as data with embedded `action` ocaps where safe.
+     */
+    makeTransferMiddlewareKit: () => import("@endo/exo").GuardedKit<{
+        finisher: {
+            useRegistry(registry: import("./bridge-target.js").TargetRegistry): void;
+        };
+        interceptorFactory: {
+            wrapApp: (tap: globalThis.ERef<import("./bridge-target.js").TargetApp>, targetHost: globalThis.ERef<import("./bridge-target.js").TargetHost>, isActiveTap?: boolean | undefined) => import("@endo/exo").Guarded<{
+                receiveUpcall(obj: any): Promise<import("@agoric/vow").Vow<unknown> | undefined>;
+            }>;
+        };
+        transferMiddleware: {
+            registerTap(target: string, tap: ERef<import("./bridge-target.js").TargetApp>): any;
+            registerActiveTap(target: string, tap: ERef<import("./bridge-target.js").TargetApp>): any;
+            unregisterTap(target: string): Promise<void>;
+        };
+    }>;
+} & import("@endo/pass-style").RemotableObject<`Alleged: ${string}`> & import("@endo/eventual-send").RemotableBrand<{}, {
+    /**
+     * @template {import('@agoric/internal').BridgeIdValue} T
+     * @param {import('./types').ScopedBridgeManager<T>} manager
+     * @param {string} [inboundType]
+     * @param {import('./bridge-target').AppTransformer} [appTransformer]
+     */
+    provideBridgeTargetKit<T extends import("@agoric/internal").BridgeIdValue>(manager: import("./types").ScopedBridgeManager<T>, inboundType?: string | undefined, appTransformer?: import("./bridge-target.js").AppTransformer | undefined): import("@endo/exo").GuardedKit<{
+        bridgeHandler: {
+            fromBridge(obj: any): Promise<any>;
+        };
+        targetHost: {
+            sendDowncall(obj: any): Promise<any>;
+        };
+        targetRegistry: {
+            register(target: string, app: TargetApp, args?: unknown[] | undefined): Promise<import("./bridge-target.js").TargetRegistration>;
+            reregister(target: string, app: TargetApp, args?: unknown[] | undefined): Promise<void>;
+            unregister(target: string): Promise<void>;
+        };
+    }>;
+    /**
+     * Create middleware for exposing IBC messages to and from the underlying
+     * vtransfer port as data with embedded `action` ocaps where safe.
+     */
+    makeTransferMiddlewareKit: () => import("@endo/exo").GuardedKit<{
+        finisher: {
+            useRegistry(registry: import("./bridge-target.js").TargetRegistry): void;
+        };
+        interceptorFactory: {
+            wrapApp: (tap: globalThis.ERef<import("./bridge-target.js").TargetApp>, targetHost: globalThis.ERef<import("./bridge-target.js").TargetHost>, isActiveTap?: boolean | undefined) => import("@endo/exo").Guarded<{
+                receiveUpcall(obj: any): Promise<import("@agoric/vow").Vow<unknown> | undefined>;
+            }>;
+        };
+        transferMiddleware: {
+            registerTap(target: string, tap: ERef<import("./bridge-target.js").TargetApp>): any;
+            registerActiveTap(target: string, tap: ERef<import("./bridge-target.js").TargetApp>): any;
+            unregisterTap(target: string): Promise<void>;
+        };
+    }>;
+}>;
+export type TransferVat = ReturnType<typeof buildRootObject>;
+//# sourceMappingURL=vat-transfer.d.ts.map

package/src/vat-transfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vat-transfer.d.ts","sourceRoot":"","sources":["vat-transfer.js"],"names":[],"mappings":"AASO;IAyBH;;;;;OAKG;2BAH8C,CAAC,4DAAvC,OAAO,SAAS,EAAE,mBAAmB,CAAC,CAAC,CAAC;;;;;;;;0CA2B05K,SAAS;4CAA66C,SAAS;;;;IAT54N;;;OAGG;;;kCAMq+J,OAAO,oBAAiB,EAAE,cAAc;;;;;;;;6CAA97C,KAAK,OAAO,oBAAoB,EAAE,SAAS,CAAC;mDAA5C,KAAK,OAAO,oBAAoB,EAAE,SAAS,CAAC;;;;;IA7B9nH;;;;;OAKG;2BAH8C,CAAC,4DAAvC,OAAO,SAAS,EAAE,mBAAmB,CAAC,CAAC,CAAC;;;;;;;;;;;;;IAkBnD;;;OAGG;;;+DAM+/J,cAAc;;;;;;;;+EAA55C,SAAS;qFAAT,SAAS;;;;GAHhoH;0BAEa,UAAU,CAAC,OAAO,eAAe,CAAC"}

package/src/vat-transfer.js

@@ -0,0 +1,63 @@
+// @ts-check
+import { Far } from '@endo/far';
+import { makeDurableZone } from '@agoric/zone/durable.js';
+
+import { provideLazy } from '@agoric/store';
+import { prepareVowTools } from '@agoric/vat-data/vow.js';
+import { prepareBridgeTargetModule } from './bridge-target.js';
+import { prepareTransferTools } from './transfer.js';
+
+export const buildRootObject = (_vatPowers, _args, baggage) => {
+  const zone = makeDurableZone(baggage);
+
+  const { makeBridgeTargetKit } = prepareBridgeTargetModule(
+    zone.subZone('bridge'),
+  );
+
+  const vowTools = prepareVowTools(zone.subZone('vow'));
+
+  const { makeTransferMiddlewareKit } = prepareTransferTools(
+    zone.subZone('transfer'),
+    vowTools,
+  );
+
+  /**
+   * This 2-level structure is to avoid holding the bridge managers strongly, as
+   * well as accommodate the lack of complex keys.
+   *
+   * @type {WeakMapStore<
+   *   import('./types').ScopedBridgeManager<any>,
+   *   MapStore<string, ReturnType<typeof makeBridgeTargetKit>>
+   * >}
+   */
+  const managerToKits = zone.weakMapStore('managerToHandler');
+  return Far('TransferVat', {
+    /**
+     * @template {import('@agoric/internal').BridgeIdValue} T
+     * @param {import('./types').ScopedBridgeManager<T>} manager
+     * @param {string} [inboundType]
+     * @param {import('./bridge-target').AppTransformer} [appTransformer]
+     */
+    provideBridgeTargetKit(
+      manager,
+      inboundType = 'IBC_EVENT',
+      appTransformer = undefined,
+    ) {
+      /** @type {MapStore<string, ReturnType<typeof makeBridgeTargetKit>>} */
+      const inboundTypeToKit = provideLazy(managerToKits, manager, () =>
+        zone.detached().mapStore('inboundTypeToKit'),
+      );
+      const kit = provideLazy(inboundTypeToKit, inboundType, () =>
+        makeBridgeTargetKit(manager, inboundType, appTransformer),
+      );
+      return kit;
+    },
+    /**
+     * Create middleware for exposing IBC messages to and from the underlying
+     * vtransfer port as data with embedded `action` ocaps where safe.
+     */
+    makeTransferMiddlewareKit,
+  });
+};
+
+/** @typedef {ReturnType<typeof buildRootObject>} TransferVat */

package/tools/fake-bridge.d.ts

@@ -6,6 +6,7 @@ export function makeFakeBankBridge(zone: import("@agoric/zone").Zone, opts?: {
 export function makeFakeIbcBridge(zone: import("@agoric/zone").Zone, onToBridge: (obj: any) => void): ScopedBridgeManager<"dibc">;
 export const LOCALCHAIN_DEFAULT_ADDRESS: "agoric1fakeLCAAddress";
 export function makeFakeLocalchainBridge(zone: import("@agoric/zone").Zone, onToBridge?: ((obj: any) => void) | undefined): ScopedBridgeManager<"vlocalchain">;
+export function makeFakeTransferBridge(zone: import("@agoric/zone").Zone, onToBridge?: ((obj: any) => void) | undefined): ScopedBridgeManager<"vtransfer">;
 export type Balances = {
     [address: string]: {
         [denom: string]: bigint;

package/tools/fake-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fake-bridge.d.ts","sourceRoot":"","sources":["fake-bridge.js"],"names":[],"mappings":"AAgBA,6EAA6E;AAE7E,sCAAuC;AAchC,yCANI,OAAO,cAAc,EAAE,IAAI;IAEZ,QAAQ,EAAvB,QAAQ;gCAyFlB;AAOM,wCAJI,OAAO,cAAc,EAAE,IAAI,cAC3B,CAAC,GAAG,KAAA,KAAK,IAAI,+BA+BvB;AAED,iEAAkE;AAO3D,+CAJI,OAAO,cAAc,EAAE,IAAI,8BAClB,IAAI,mDAiEvB;uBA/Ma;IAAE,CAAC,OAAO,EAAE,MAAM,GAAG;QAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAA;CAAE;yCAPX,iBAAiB"}
+{"version":3,"file":"fake-bridge.d.ts","sourceRoot":"","sources":["fake-bridge.js"],"names":[],"mappings":"AAiBA,6EAA6E;AAE7E,sCAAuC;AAchC,yCANI,OAAO,cAAc,EAAE,IAAI;IAEZ,QAAQ,EAAvB,QAAQ;gCAyFlB;AAOM,wCAJI,OAAO,cAAc,EAAE,IAAI,cAC3B,CAAC,GAAG,KAAA,KAAK,IAAI,+BA+BvB;AAED,iEAAkE;AAO3D,+CAJI,OAAO,cAAc,EAAE,IAAI,8BAClB,IAAI,mDAiEvB;AAOM,6CAJI,OAAO,cAAc,EAAE,IAAI,8BAClB,IAAI,iDAwCvB;uBA3Pa;IAAE,CAAC,OAAO,EAAE,MAAM,GAAG;QAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAA;CAAE;yCAPX,iBAAiB"}

package/tools/fake-bridge.js

@@ -1,3 +1,4 @@
+// @ts-check
 import { assert, Fail } from '@agoric/assert';
 import { makeTracer, VBankAccount } from '@agoric/internal';
 import { E } from '@endo/far';
@@ -222,3 +223,47 @@ export const makeFakeLocalchainBridge = (zone, onToBridge = () => {}) => {
     },
   });
 };
+
+/**
+ * @param {import('@agoric/zone').Zone} zone
+ * @param {(obj) => void} [onToBridge]
+ * @returns {ScopedBridgeManager<'vtransfer'>}
+ */
+export const makeFakeTransferBridge = (zone, onToBridge = () => {}) => {
+  /** @type {Remote<BridgeHandler>} */
+  let hndlr;
+  const registered = zone.setStore('registered');
+  return zone.exo('Fake Transfer Bridge Manager', undefined, {
+    getBridgeId: () => 'vtransfer',
+    toBridge: async obj => {
+      onToBridge(obj);
+      const { type, ...params } = obj;
+      trace('toBridge', type, params);
+      switch (type) {
+        case 'BRIDGE_TARGET_REGISTER': {
+          registered.add(params.target);
+          return undefined;
+        }
+        case 'BRIDGE_TARGET_UNREGISTER': {
+          registered.delete(params.target);
+          return undefined;
+        }
+        default:
+          Fail`unknown type ${type}`;
+      }
+      return undefined;
+    },
+    fromBridge: async obj => {
+      if (!hndlr) throw Error('no handler!');
+      return when(E(hndlr).fromBridge(obj));
+    },
+    initHandler: h => {
+      if (hndlr) throw Error('already init');
+      hndlr = h;
+    },
+    setHandler: h => {
+      if (!hndlr) throw Error('must init first');
+      hndlr = h;
+    },
+  });
+};