@agoric/orchestration 0.2.0-upgrade-18-dev-aaebae4.0 → 0.2.0-upgrade-18-dev-bd8fd54.0

package/src/examples/staking-combinations.flows.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staking-combinations.flows.d.ts","sourceRoot":"","sources":["staking-combinations.flows.js"],"names":[],"mappings":"AA4BO,kCATI,YAAY,OACZ;IACN,2BAA2B,EAAE,2BAA2B,CAAC;IACzD,wBAAwB,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,gBAAgB,CAAC;CAC9D,SACO,OAAO,iBACP;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GACnB,OAAO,CAAC,6BAA6B,CAAC,CAiBlD;AAcM,yCATI,YAAY,qCAEpB;IAA6E,mBAAmB,EAAxF,OAAO,CAAC,eAAe,4BAA4B,CAAC,QAAQ,CAAC,CAAC,CAAC;IACjC,QAAQ,EAAtC,eAAe,QAAQ,CAAC;CAChC,WAAQ,eAAe,0BAA0B,CAAC,QAC1C,OAAO,aACP,sBAAsB,GACpB,OAAO,CAAC,IAAI,CAAC,CAgCzB;AAcM,4CATI,YAAY,OACZ,MAAM,WACN,eAAe,0BAA0B,CAAC,gCAC1C;IACN,WAAW,EAAE;QAAE,MAAM,EAAE,SAAS,CAAC;QAAC,SAAS,EAAE,sBAAsB,CAAA;KAAE,EAAE,CAAC;IACxE,WAAW,EAAE,YAAY,CAAC;CAC3B,GACS,OAAO,CAAC,IAAI,CAAC,CAYzB;kCA7G8I,aAAa;iDAG9G,sCAAsC;sCAF1B,mCAAmC;mDAInC,uBAAuB;kDAHlC,wCAAwC;oCAHtD,oBAAoB;8BAMK,uBAAuB;gDADpC,yCAAyC;4CAJyD,aAAa;+BAAb,aAAa;kCAAb,aAAa"}
+{"version":3,"file":"staking-combinations.flows.d.ts","sourceRoot":"","sources":["staking-combinations.flows.js"],"names":[],"mappings":"AA4BO,kCATI,YAAY,OACZ;IACN,2BAA2B,EAAE,2BAA2B,CAAC;IACzD,wBAAwB,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,gBAAgB,CAAC;CAC9D,SACO,OAAO,iBACP;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GACnB,OAAO,CAAC,6BAA6B,CAAC,CAiBlD;AAeM,yCAVI,YAAY,+CAEpB;IAAsC,QAAQ,EAAtC,eAAe,QAAQ,CAAC;IAC6C,mBAAmB,EAAxF,OAAO,CAAC,eAAe,4BAA4B,CAAC,QAAQ,CAAC,CAAC,CAAC;IACjC,QAAQ,EAAtC,eAAe,QAAQ,CAAC;CAChC,WAAQ,eAAe,0BAA0B,CAAC,QAC1C,OAAO,aACP,sBAAsB,GACpB,OAAO,CAAC,IAAI,CAAC,CAoCzB;AAcM,4CATI,YAAY,OACZ,MAAM,WACN,eAAe,0BAA0B,CAAC,gCAC1C;IACN,WAAW,EAAE;QAAE,MAAM,EAAE,SAAS,CAAC;QAAC,SAAS,EAAE,sBAAsB,CAAA;KAAE,EAAE,CAAC;IACxE,WAAW,EAAE,YAAY,CAAC;CAC3B,GACS,OAAO,CAAC,IAAI,CAAC,CAYzB;kCAlH6J,aAAa;iDAG7H,sCAAsC;sCAF1B,mCAAmC;mDAInC,uBAAuB;8BAL6E,aAAa;oCAD1I,oBAAoB;kDAGN,wCAAwC;8BAG7B,uBAAuB;gDADpC,yCAAyC;4CAJwE,aAAa;+BAAb,aAAa;kCAAb,aAAa"}

package/src/examples/staking-combinations.flows.js

@@ -1,6 +1,6 @@
 /**
  * @import {GuestInterface} from '@agoric/async-flow';
- * @import {Orchestrator, OrchestrationFlow, AmountArg, CosmosValidatorAddress, ChainAddress, LocalAccountMethods, OrchestrationAccountI} from '../types.js'
+ * @import {Orchestrator, OrchestrationFlow, AmountArg, CosmosValidatorAddress, ChainAddress, LocalAccountMethods, OrchestrationAccountCommon, ChainHub} from '../types.js'
  * @import {ContinuingOfferResult, InvitationMakers} from '@agoric/smart-wallet/src/types.js';
  * @import {LocalOrchestrationAccountKit} from '../exos/local-orchestration-account.js';
  * @import {MakeCombineInvitationMakers} from '../exos/combine-invitation-makers.js';
@@ -9,7 +9,7 @@
  */
 
 import { mustMatch } from '@endo/patterns';
-import { makeError, q } from '@endo/errors';
+import { Fail, makeError, q } from '@endo/errors';
 import { makeTracer } from '@agoric/internal';
 import { ChainAddressShape } from '../typeGuards.js';
 
@@ -48,6 +48,7 @@ harden(makeAccount);
  * @satisfies {OrchestrationFlow}
  * @param {Orchestrator} orch
  * @param {object} ctx
+ * @param {GuestInterface<ChainHub>} ctx.chainHub
  * @param {Promise<GuestInterface<LocalOrchestrationAccountKit['holder']>>} ctx.sharedLocalAccountP
  * @param {GuestInterface<ZoeTools>} ctx.zoeTools
  * @param {GuestInterface<CosmosOrchestrationAccount>} account
@@ -57,7 +58,7 @@ harden(makeAccount);
  */
 export const depositAndDelegate = async (
   orch,
-  { sharedLocalAccountP, zoeTools },
+  { chainHub, sharedLocalAccountP, zoeTools },
   account,
   seat,
   validator,
@@ -84,7 +85,11 @@ export const depositAndDelegate = async (
     throw errMsg;
   }
   seat.exit();
-  await account.delegate(validator, give.Stake);
+  const denom = chainHub.getDenom(give.Stake.brand);
+  if (!denom) throw Fail`unknown brand ${q(give.Stake.brand)}`;
+  // TODO #10449 amountToCoin accepts brands
+  const denomAmount = harden({ denom, value: give.Stake.value });
+  await account.delegate(validator, denomAmount);
 };
 harden(depositAndDelegate);
 

package/src/examples/swap.contract.d.ts

@@ -6,10 +6,11 @@
  * @import {NameHub} from '@agoric/vats';
  * @import {Zone} from '@agoric/zone';
  * @import {OrchestrationTools} from '../utils/start-helper.js';
+ * @import {CosmosChainInfo, Denom, DenomDetail} from '@agoric/orchestration';
  */
 /** @type {ContractMeta<typeof start>} */
 export const meta: ContractMeta<typeof start>;
-export function makeNatAmountShape(brand: Brand, min?: bigint | undefined): {
+export function makeNatAmountShape(brand: Brand, min?: NatValue): {
     brand: globalThis.Brand;
     value: import("@endo/patterns").Matcher;
 };
@@ -20,11 +21,24 @@ export const start: (zcf: ZCF<Record<string, unknown>>, privateArgs: {
     storageNode: Remote<StorageNode>;
     timerService: Remote<TimerService>;
     marshaller: Marshaller;
+    chainInfo: Record<string, Readonly<{
+        bech32Prefix?: string;
+        chainId: string;
+        connections?: Record<string, import("@agoric/orchestration").IBCConnectionInfo>;
+        icqEnabled?: boolean;
+        pfmEnabled?: boolean;
+        stakingTokens?: Readonly<Array<{
+            denom: string;
+        }>>;
+    }>>;
+    assetInfo: [Denom, DenomDetail & {
+        brandKey?: string;
+    }][];
 }, baggage: import("@agoric/vat-data").Baggage) => Promise<{
     publicFacet: import("@endo/exo").Guarded<{
         makeSwapAndStakeInvitation(): Promise<Invitation<import("@agoric/vow").Vow<void>, {
             staked: Amount<"nat">;
-            validator: import("../cosmos-api.js").CosmosValidatorAddress;
+            validator: import("@agoric/orchestration").CosmosValidatorAddress;
         }>>;
     }>;
 }>;
@@ -33,4 +47,6 @@ import type { Remote } from '@agoric/internal';
 import type { LocalChain } from '@agoric/vats/src/localchain.js';
 import type { CosmosInterchainService } from '../exos/exo-interfaces.js';
 import type { TimerService } from '@agoric/time';
+import type { Denom } from '@agoric/orchestration';
+import type { DenomDetail } from '@agoric/orchestration';
 //# sourceMappingURL=swap.contract.d.ts.map

package/src/examples/swap.contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"swap.contract.d.ts","sourceRoot":"","sources":["swap.contract.js"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AAEH,yCAAyC;AACzC,mBADW,YAAY,CAAC,OAAO,KAAK,CAAC,CAWnC;AASK,0CAHI,KAAK;;;EAIsC;AAgDtD;iBAxCkB,OAAO,OAAO,CAAC;gBAChB,OAAO,UAAU,CAAC;0BACR,OAAO,uBAAuB,CAAC;iBACxC,OAAO,WAAW,CAAC;kBAClB,OAAO,YAAY,CAAC;gBACtB,UAAU;;;;;;;;GAmCsB;6BA1EvB,cAAc;4BAFf,kBAAkB;gCADd,gCAAgC;6CAEnB,2BAA2B;kCAHtC,cAAc"}
+{"version":3,"file":"swap.contract.d.ts","sourceRoot":"","sources":["swap.contract.js"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AAEH,yCAAyC;AACzC,mBADW,YAAY,CAAC,OAAO,KAAK,CAAC,CAanC;AASK,0CAHI,KAAK,QACL,QAAQ;;;EAGmC;AAkDtD;iBA1CkB,OAAO,OAAO,CAAC;gBAChB,OAAO,UAAU,CAAC;0BACR,OAAO,uBAAuB,CAAC;iBACxC,OAAO,WAAW,CAAC;kBAClB,OAAO,YAAY,CAAC;gBACtB,UAAU;;;;;;;;;;;eAEX,CAAC,KAAK,EAAE,WAAW,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE;;;;;;;;GAmCb;6BA/EvB,cAAc;4BAFf,kBAAkB;gCADd,gCAAgC;6CAEnB,2BAA2B;kCAHtC,cAAc;2BAOS,uBAAuB;iCAAvB,uBAAuB"}

package/src/examples/swap.contract.js

@@ -3,6 +3,7 @@ import { TimerServiceShape } from '@agoric/time';
 import { M } from '@endo/patterns';
 import { withOrchestration } from '../utils/start-helper.js';
 import * as flows from './swap.flows.js';
+import { CosmosChainInfoShape, DenomDetailShape } from '../typeGuards.js';
 
 /**
  * @import {TimerService} from '@agoric/time';
@@ -12,6 +13,7 @@ import * as flows from './swap.flows.js';
  * @import {NameHub} from '@agoric/vats';
  * @import {Zone} from '@agoric/zone';
  * @import {OrchestrationTools} from '../utils/start-helper.js';
+ * @import {CosmosChainInfo, Denom, DenomDetail} from '@agoric/orchestration';
  */
 
 /** @type {ContractMeta<typeof start>} */
@@ -23,6 +25,8 @@ export const meta = {
     storageNode: StorageNodeShape,
     marshaller: M.remotable('marshaller'),
     timerService: M.or(TimerServiceShape, null),
+    chainInfo: M.recordOf(M.string(), CosmosChainInfoShape),
+    assetInfo: M.arrayOf([M.string(), DenomDetailShape]),
   },
   upgradability: 'canUpgrade',
 };
@@ -49,6 +53,8 @@ harden(makeNatAmountShape);
  *   storageNode: Remote<StorageNode>;
  *   timerService: Remote<TimerService>;
  *   marshaller: Marshaller;
+ *   chainInfo: Record<string, CosmosChainInfo>;
+ *   assetInfo: [Denom, DenomDetail & { brandKey?: string }][];
  * }} privateArgs
  * @param {Zone} zone
  * @param {OrchestrationTools} tools

package/src/exos/README.md

@@ -1,6 +1,6 @@
 # Exo structure
 
-Last verified 2024-09-06
+Last verified 2024-10-30
 
 ```mermaid
 classDiagram
@@ -52,9 +52,9 @@ classDiagram
 
 %% In other vats
     class Port {
-      getLocalAddress()
       addListener()
       connect()
+      getLocalAddress()
       removeListener()
       revoke()
     }
@@ -76,9 +76,8 @@ classDiagram
       deposit()
       executeTx()
       getBalance()
-      withdraw()
-      executeTx()
       monitorTransfers()
+      withdraw()
     }
 
 %% In api consumer vats
@@ -113,12 +112,14 @@ classDiagram
       timer: Timer
       topicKit: RecorderKit<OrchestrationAccountNotification>
       asContinuingOffer()
+      deactivate()
       delegate()
       executeEncodedTx()
       getAddress()
       getBalance()
       getBalances()
       getPublicTopics()
+      reactivate()
       redelegate()
       send()
       sendAll()

package/src/exos/chain-hub-admin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chain-hub-admin.d.ts","sourceRoot":"","sources":["chain-hub-admin.js"],"names":[],"mappings":"AAgCO,2CAHI,IAAI,YACJ,QAAQ;IAeb;;;;;;OAMG;6BAHQ,MAAM,aACN,eAAe,kBACf,iBAAiB;IAe5B;;;;;;;OAOG;yBAHQ,KAAK,UAEL,WAAW;GAU3B;4BAEa,UAAU,QAtDb,IAAI,YACJ,QAAQ;IAeb;;;;;;OAMG;6BAHQ,MAAM,aACN,eAAe,kBACf,iBAAiB;IAe5B;;;;;;;OAOG;yBAHQ,KAAK,UAEL,WAAW;GAYkB;0BA3EvB,cAAc;8BAEG,gBAAgB;qCADI,uBAAuB;uCAAvB,uBAAuB;2BAAvB,uBAAuB;iCAC3C,gBAAgB"}
+{"version":3,"file":"chain-hub-admin.d.ts","sourceRoot":"","sources":["chain-hub-admin.js"],"names":[],"mappings":"AA+BO,2CAHI,IAAI,YACJ,QAAQ;IAeb;;;;;;OAMG;6BAHQ,MAAM,aACN,eAAe,kBACf,iBAAiB;IAe5B;;;;;;;OAOG;yBAHQ,KAAK,UAEL,WAAW;GAU3B;4BAEa,UAAU,QAtDb,IAAI,YACJ,QAAQ;IAeb;;;;;;OAMG;6BAHQ,MAAM,aACN,eAAe,kBACf,iBAAiB;IAe5B;;;;;;;OAOG;yBAHQ,KAAK,UAEL,WAAW;GAYkB;0BA3EvB,cAAc;8BAEG,gBAAgB;qCADI,uBAAuB;uCAAvB,uBAAuB;2BAAvB,uBAAuB;iCAC3C,gBAAgB"}

package/src/exos/chain-hub-admin.js

@@ -2,8 +2,7 @@
 /* eslint-disable no-restricted-syntax */
 import { heapVowE } from '@agoric/vow/vat.js';
 import { M } from '@endo/patterns';
-import { CosmosChainInfoShape } from '../typeGuards.js';
-import { DenomDetailShape } from './chain-hub.js';
+import { CosmosChainInfoShape, DenomDetailShape } from '../typeGuards.js';
 
 /**
  * @import {Zone} from '@agoric/zone';

package/src/exos/chain-hub.d.ts

@@ -2,31 +2,13 @@
  * @import {NameHub} from '@agoric/vats';
  * @import {Vow, VowTools} from '@agoric/vow';
  * @import {Zone} from '@agoric/zone';
- * @import {CosmosAssetInfo, CosmosChainInfo, IBCConnectionInfo} from '../cosmos-api.js';
+ * @import {CosmosAssetInfo, CosmosChainInfo, ForwardInfo, IBCConnectionInfo, IBCMsgTransferOptions, TransferRoute, GoDuration} from '../cosmos-api.js';
  * @import {ChainInfo, KnownChains} from '../chain-info.js';
- * @import {Denom} from '../orchestration-api.js';
- * @import {Remote} from '@agoric/internal';
- * @import {TypedPattern} from '@agoric/internal';
+ * @import {ChainAddress, Denom, DenomAmount} from '../orchestration-api.js';
+ * @import {Remote, TypedPattern} from '@agoric/internal';
  */
-/**
- * If K matches a known chain, narrow the type from generic ChainInfo
- *
- * @template {string} K
- * @typedef {K extends keyof KnownChains
- *   ? ChainInfo & Omit<KnownChains[K], 'connections'>
- *   : ChainInfo} ActualChainInfo
- * @internal
- */
-/**
- * @typedef {object} DenomDetail
- * @property {string} baseName - name of issuing chain; e.g. cosmoshub
- * @property {Denom} baseDenom - e.g. uatom
- * @property {string} chainName - name of holding chain; e.g. agoric
- * @property {Brand<'nat'>} [brand] - vbank brand, if registered
- * @see {ChainHub} `registerAsset` method
- */
-/** @type {TypedPattern<DenomDetail>} */
-export const DenomDetailShape: TypedPattern<DenomDetail>;
+/** receiver address value for ibc transfers that involve PFM */
+export const PFM_RECEIVER: "pfm";
 export type HubName = (typeof HubName)[keyof typeof HubName];
 export namespace HubName {
     let Chain: "chain";
@@ -41,6 +23,8 @@ export const CONNECTIONS_KEY: "chainConnection";
 export const ASSETS_KEY: "chainAssets";
 export function connectionKey(chainId1: string, chainId2: string): string;
 export function normalizeConnectionInfo(primaryChainId: string, counterChainId: string, directed: IBCConnectionInfo): [string, IBCConnectionInfo];
+/** @type {TypedPattern<TransferRoute>} */
+export const TransferRouteShape: TypedPattern<TransferRoute>;
 export function makeChainHub(zone: Zone, agoricNames: Remote<NameHub>, vowTools: VowTools): import("@endo/exo").Guarded<{
     /**
      * Register a new chain. The name will override a name in well known chain
@@ -100,9 +84,10 @@ export function makeChainHub(zone: Zone, agoricNames: Remote<NameHub>, vowTools:
      * Retrieve holding, issuing chain names etc. for a denom.
      *
      * @param {Denom} denom
+     * @param {string} srcChainName - the chainName the denom is held on
      * @returns {DenomDetail | undefined}
      */
-    getAsset(denom: Denom): DenomDetail | undefined;
+    getAsset(denom: Denom, srcChainName: string): DenomDetail | undefined;
     /**
      * Retrieve denom (string) for a Brand.
      *
@@ -110,6 +95,29 @@ export function makeChainHub(zone: Zone, agoricNames: Remote<NameHub>, vowTools:
      * @returns {Denom | undefined}
      */
     getDenom(brand: Brand): Denom | undefined;
+    /**
+     * @param {string} address bech32 address
+     * @returns {ChainAddress}
+     * @throws {Error} if chain info not found for bech32Prefix
+     */
+    makeChainAddress(address: string): ChainAddress;
+    /**
+     * Determine the transfer route for a destination and amount given the
+     * current holding chain.
+     *
+     * Does not account for routes with more than 1 intermediary hop - that is,
+     * it can't unwrap denoms that were incorrectly routed.
+     *
+     * XXX consider accepting AmountArg #10449
+     *
+     * @param {ChainAddress} destination
+     * @param {DenomAmount} denomAmount
+     * @param {string} srcChainName
+     * @param {IBCMsgTransferOptions['forwardOpts']} [forwardOpts]
+     * @returns {TransferRoute} single hop, multi hop
+     * @throws {Error} if unable to determine route
+     */
+    makeTransferRoute(destination: ChainAddress, denomAmount: DenomAmount, srcChainName: string, forwardOpts?: IBCMsgTransferOptions["forwardOpts"]): TransferRoute;
 }>;
 export function registerAssets(chainHub: ChainHub, name: string, assets: CosmosAssetInfo[]): void;
 /**
@@ -135,8 +143,9 @@ export type DenomDetail = {
     brand?: globalThis.Brand<"nat"> | undefined;
 };
 export type ChainHub = ReturnType<typeof makeChainHub>;
-import type { TypedPattern } from '@agoric/internal';
 import type { IBCConnectionInfo } from '../cosmos-api.js';
+import type { TransferRoute } from '../cosmos-api.js';
+import type { TypedPattern } from '@agoric/internal';
 import type { Zone } from '@agoric/zone';
 import type { NameHub } from '@agoric/vats';
 import type { Remote } from '@agoric/internal';
@@ -144,6 +153,9 @@ import type { VowTools } from '@agoric/vow';
 import type { CosmosChainInfo } from '../cosmos-api.js';
 import type { Vow } from '@agoric/vow';
 import type { Denom } from '../orchestration-api.js';
+import type { ChainAddress } from '../orchestration-api.js';
+import type { DenomAmount } from '../orchestration-api.js';
+import type { IBCMsgTransferOptions } from '../cosmos-api.js';
 import type { CosmosAssetInfo } from '../cosmos-api.js';
 import type { KnownChains } from '../chain-info.js';
 import type { ChainInfo } from '../chain-info.js';

package/src/exos/chain-hub.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chain-hub.d.ts","sourceRoot":"","sources":["chain-hub.js"],"names":[],"mappings":"AAQA;;;;;;;;;GASG;AAEH;;;;;;;;GAQG;AAEH;;;;;;;GAOG;AACH,wCAAwC;AACxC,+BADW,aAAa,WAAW,CAAC,CAIlC;sBAGQ,CAAC,OAAO,OAAO,EAAE,MAAM,OAAO,OAAO,CAAC;;;;;;AAYhD,oCAAoC;AACpC,gCAAuC;AACvC,8CAA8C;AAC9C,gDAAuD;AACvD,0CAA0C;AAC1C,uCAA8C;AAqBvC,wCAHI,MAAM,YACN,MAAM,UAUhB;AAoCM,wDALI,MAAM,kBACN,MAAM,YACN,iBAAiB,GACf,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAavC;AA2DM,mCAJI,IAAI,eACJ,OAAO,OAAO,CAAC,YACf,QAAQ;IA8Gf;;;;;;;;;;;OAWG;wBAFQ,MAAM,aACN,eAAe;IAK1B;;;;OAIG;iBAHmB,CAAC,SAAV,MAAQ,aACV,CAAC,GACC,IAAI,eAAe,CAAC,CAAC,CAAC,CAAC;IAYpC;;;;OAIG;uCAHQ,MAAM,uBACN,MAAM,kBACN,iBAAiB;IAW5B;;;;OAIG;+BAHQ,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,WAC5B,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAC1B,IAAI,iBAAiB,CAAC;IAmBnC;;;;;;;;OAQG;2BAPmB,EAAE,SAAX,MAAQ,EACC,EAAE,SAAX,MAAQ,eACV,EAAE,eACF,EAAE,GACA,IACZ,CAAK,eAAe,CAAC,EAAE,CAAC,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,iBAAiB,CAAC,CAC9D;IAOJ;;;;;;;OAOG;yBAHQ,KAAK,UAEL,WAAW;IAatB;;;;;OAKG;oBAFQ,KAAK,GACH,WAAW,GAAG,SAAS;IAQpC;;;;;OAKG;oBAFQ,KAAK,GACH,KAAK,GAAG,SAAS;GAWjC;AAUM,yCAJI,QAAQ,QACR,MAAM,UACN,eAAe,EAAE,QAe3B;;;;4BA/aqB,CAAC,SAAV,MAAQ,IACR,CAAC,SAAS,MAAM,WAAW,GACjC,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC,GAC/C,SAAS;;;;;cAMF,MAAM;;;;eACN,KAAK;;;;eACL,MAAM;;;;;;uBA8YN,UAAU,CAAC,OAAO,YAAY,CAAC;kCA/Zd,kBAAkB;uCAJqB,kBAAkB;0BADjE,cAAc;6BAFX,cAAc;4BAMf,kBAAkB;8BALX,aAAa;qCAEyB,kBAAkB;yBAFxD,aAAa;2BAIrB,yBAAyB;qCAFqB,kBAAkB;iCAC/C,kBAAkB;+BAAlB,kBAAkB"}
+{"version":3,"file":"chain-hub.d.ts","sourceRoot":"","sources":["chain-hub.js"],"names":[],"mappings":"AAmBA;;;;;;;;GAQG;AAEH,gEAAgE;AAChE,2BAAkD,KAAK,CAAE;sBAsB/C,CAAC,OAAO,OAAO,EAAE,MAAM,OAAO,OAAO,CAAC;;;;;;AAYhD,oCAAoC;AACpC,gCAAuC;AACvC,8CAA8C;AAC9C,gDAAuD;AACvD,0CAA0C;AAC1C,uCAA8C;AAqBvC,wCAHI,MAAM,YACN,MAAM,UAUhB;AAoCM,wDALI,MAAM,kBACN,MAAM,YACN,iBAAiB,GACf,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAavC;AAwCD,0CAA0C;AAC1C,iCADW,aAAa,aAAa,CAAC,CAUpC;AAmCK,mCAJI,IAAI,eACJ,OAAO,OAAO,CAAC,YACf,QAAQ;IA2Hf;;;;;;;;;;;OAWG;wBAFQ,MAAM,aACN,eAAe;IAQ1B;;;;OAIG;iBAHmB,CAAC,SAAV,MAAQ,aACV,CAAC,GACC,IAAI,eAAe,CAAC,CAAC,CAAC,CAAC;IAYpC;;;;OAIG;uCAHQ,MAAM,uBACN,MAAM,kBACN,iBAAiB;IAW5B;;;;OAIG;+BAHQ,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,WAC5B,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAC1B,IAAI,iBAAiB,CAAC;IAmBnC;;;;;;;;OAQG;2BAPmB,EAAE,SAAX,MAAQ,EACC,EAAE,SAAX,MAAQ,eACV,EAAE,eACF,EAAE,GACA,IACZ,CAAK,eAAe,CAAC,EAAE,CAAC,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,iBAAiB,CAAC,CAC9D;IAOJ;;;;;;;OAOG;yBAHQ,KAAK,UAEL,WAAW;IAmBtB;;;;;;OAMG;oBAHQ,KAAK,gBACL,MAAM,GACJ,WAAW,GAAG,SAAS;IASpC;;;;;OAKG;oBAFQ,KAAK,GACH,KAAK,GAAG,SAAS;IAQ9B;;;;OAIG;8BAHQ,MAAM,GACJ,YAAY;IAgBzB;;;;;;;;;;;;;;;OAeG;mCANQ,YAAY,eACZ,WAAW,gBACX,MAAM,gBACN,qBAAqB,CAAC,aAAa,CAAC,GAClC,aAAa;GAmG7B;AAUM,yCAJI,QAAQ,QACR,MAAM,UACN,eAAe,EAAE,QAe3B;;;;4BA3lBqB,CAAC,SAAV,MAAQ,IACR,CAAC,SAAS,MAAM,WAAW,GACjC,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC,GAC/C,SAAS;;;;;cAMF,MAAM;;;;eACN,KAAK;;;;eACL,MAAM;;;;;;uBA0jBN,UAAU,CAAC,OAAO,YAAY,CAAC;uCAjlBwF,kBAAkB;mCAAlB,kBAAkB;kCAGhH,kBAAkB;0BAJlC,cAAc;6BAFX,cAAc;4BAMD,kBAAkB;8BALzB,aAAa;qCAEwF,kBAAkB;yBAFvH,aAAa;2BAIM,yBAAyB;kCAAzB,yBAAyB;iCAAzB,yBAAyB;2CAFyD,kBAAkB;qCAAlB,kBAAkB;iCAC9G,kBAAkB;+BAAlB,kBAAkB"}

package/src/exos/chain-hub.js

@@ -4,19 +4,32 @@ import { M } from '@endo/patterns';
 import { BrandShape } from '@agoric/ertp/src/typeGuards.js';
 
 import { VowShape } from '@agoric/vow';
-import { CosmosChainInfoShape, IBCConnectionInfoShape } from '../typeGuards.js';
+import {
+  ChainAddressShape,
+  CoinShape,
+  CosmosChainInfoShape,
+  DenomAmountShape,
+  DenomDetailShape,
+  ForwardInfoShape,
+  ForwardOptsShape,
+  IBCChannelIDShape,
+  IBCConnectionInfoShape,
+} from '../typeGuards.js';
+import { getBech32Prefix } from '../utils/address.js';
 
 /**
  * @import {NameHub} from '@agoric/vats';
  * @import {Vow, VowTools} from '@agoric/vow';
  * @import {Zone} from '@agoric/zone';
- * @import {CosmosAssetInfo, CosmosChainInfo, IBCConnectionInfo} from '../cosmos-api.js';
+ * @import {CosmosAssetInfo, CosmosChainInfo, ForwardInfo, IBCConnectionInfo, IBCMsgTransferOptions, TransferRoute, GoDuration} from '../cosmos-api.js';
  * @import {ChainInfo, KnownChains} from '../chain-info.js';
- * @import {Denom} from '../orchestration-api.js';
- * @import {Remote} from '@agoric/internal';
- * @import {TypedPattern} from '@agoric/internal';
+ * @import {ChainAddress, Denom, DenomAmount} from '../orchestration-api.js';
+ * @import {Remote, TypedPattern} from '@agoric/internal';
  */
 
+/** receiver address value for ibc transfers that involve PFM */
+export const PFM_RECEIVER = /** @type {const} */ ('pfm');
+
 /**
  * If K matches a known chain, narrow the type from generic ChainInfo
  *
@@ -35,11 +48,6 @@ import { CosmosChainInfoShape, IBCConnectionInfoShape } from '../typeGuards.js';
  * @property {Brand<'nat'>} [brand] - vbank brand, if registered
  * @see {ChainHub} `registerAsset` method
  */
-/** @type {TypedPattern<DenomDetail>} */
-export const DenomDetailShape = M.splitRecord(
-  { chainName: M.string(), baseName: M.string(), baseDenom: M.string() },
-  { brand: BrandShape },
-);
 
 /**
  * @enum {(typeof HubName)[keyof typeof HubName]}
@@ -98,7 +106,7 @@ export const connectionKey = (chainId1, chainId2) => {
  */
 const reverseConnInfo = connInfo => {
   const { transferChannel } = connInfo;
-  return {
+  return harden({
     id: connInfo.counterparty.connection_id,
     client_id: connInfo.counterparty.client_id,
     counterparty: {
@@ -113,7 +121,7 @@ const reverseConnInfo = connInfo => {
       portId: transferChannel.counterPartyPortId,
       counterPartyPortId: transferChannel.portId,
     },
-  };
+  });
 };
 
 /**
@@ -167,6 +175,26 @@ const ChainIdArgShape = M.or(
   ),
 );
 
+// TODO #9324 determine timeout defaults
+const DefaultPfmTimeoutOpts = harden(
+  /** @type {const} */ ({
+    retries: 3,
+    timeout: /** @type {const} */ ('10m'),
+  }),
+);
+
+/** @type {TypedPattern<TransferRoute>} */
+export const TransferRouteShape = M.splitRecord(
+  {
+    sourcePort: M.string(),
+    sourceChannel: IBCChannelIDShape,
+    token: CoinShape,
+    receiver: M.string(),
+  },
+  { forwardInfo: ForwardInfoShape },
+  {},
+);
+
 const ChainHubI = M.interface('ChainHub', {
   registerChain: M.call(M.string(), CosmosChainInfoShape).returns(),
   getChainInfo: M.call(M.string()).returns(VowShape),
@@ -178,8 +206,14 @@ const ChainHubI = M.interface('ChainHub', {
   getConnectionInfo: M.call(ChainIdArgShape, ChainIdArgShape).returns(VowShape),
   getChainsAndConnection: M.call(M.string(), M.string()).returns(VowShape),
   registerAsset: M.call(M.string(), DenomDetailShape).returns(),
-  getAsset: M.call(M.string()).returns(M.or(DenomDetailShape, M.undefined())),
+  getAsset: M.call(M.string(), M.string()).returns(
+    M.or(DenomDetailShape, M.undefined()),
+  ),
   getDenom: M.call(BrandShape).returns(M.or(M.string(), M.undefined())),
+  makeChainAddress: M.call(M.string()).returns(ChainAddressShape),
+  makeTransferRoute: M.call(ChainAddressShape, DenomAmountShape, M.string())
+    .optional(ForwardOptsShape)
+    .returns(M.or(M.undefined(), TransferRouteShape)),
 });
 
 /**
@@ -216,6 +250,17 @@ export const makeChainHub = (zone, agoricNames, vowTools) => {
     keyShape: BrandShape,
     valueShape: M.string(),
   });
+  /** @type {MapStore<string, string>} */
+  const bech32PrefixToChainName = zone.mapStore('bech32PrefixToChainName', {
+    keyShape: M.string(),
+    valueShape: M.string(),
+  });
+
+  /**
+   * @param {Denom} denom - from perspective of the src/holding chain
+   * @param {DenomDetail['chainName']} srcChainName
+   */
+  const makeDenomKey = (denom, srcChainName) => `${srcChainName}:${denom}`;
 
   const lookupChainInfo = vowTools.retryable(
     zone,
@@ -230,6 +275,9 @@ export const makeChainHub = (zone, agoricNames, vowTools) => {
         // TODO consider makeAtomicProvider for vows
         if (!chainInfos.has(chainName)) {
           chainInfos.init(chainName, chainInfo);
+          if (chainInfo.bech32Prefix) {
+            bech32PrefixToChainName.init(chainInfo.bech32Prefix, chainName);
+          }
         }
         return chainInfo;
       } catch (e) {
@@ -269,7 +317,6 @@ export const makeChainHub = (zone, agoricNames, vowTools) => {
     },
   );
 
-  /* eslint-disable no-use-before-define -- chainHub defined below */
   const lookupChainsAndConnection = vowTools.retryable(
     zone,
     'lookupChainsAndConnection',
@@ -316,6 +363,9 @@ export const makeChainHub = (zone, agoricNames, vowTools) => {
      */
     registerChain(name, chainInfo) {
       chainInfos.init(name, chainInfo);
+      if (chainInfo.bech32Prefix) {
+        bech32PrefixToChainName.init(chainInfo.bech32Prefix, name);
+      }
     },
     /**
      * @template {string} K
@@ -396,8 +446,14 @@ export const makeChainHub = (zone, agoricNames, vowTools) => {
         Fail`must register chain ${q(chainName)} first`;
       chainInfos.has(baseName) ||
         Fail`must register chain ${q(baseName)} first`;
-      denomDetails.init(denom, detail);
+
+      const denomKey = makeDenomKey(denom, detail.chainName);
+      denomDetails.has(denomKey) &&
+        Fail`already registered ${q(denom)} on ${q(chainName)}`;
+      denomDetails.init(denomKey, detail);
       if (detail.brand) {
+        chainName === 'agoric' ||
+          Fail`brands only registerable for agoric-held assets`;
         brandDenoms.init(detail.brand, denom);
       }
     },
@@ -405,11 +461,13 @@ export const makeChainHub = (zone, agoricNames, vowTools) => {
      * Retrieve holding, issuing chain names etc. for a denom.
      *
      * @param {Denom} denom
+     * @param {string} srcChainName - the chainName the denom is held on
      * @returns {DenomDetail | undefined}
      */
-    getAsset(denom) {
-      if (denomDetails.has(denom)) {
-        return denomDetails.get(denom);
+    getAsset(denom, srcChainName) {
+      const denomKey = makeDenomKey(denom, srcChainName);
+      if (denomDetails.has(denomKey)) {
+        return denomDetails.get(denomKey);
       }
       return undefined;
     },
@@ -425,6 +483,133 @@ export const makeChainHub = (zone, agoricNames, vowTools) => {
       }
       return undefined;
     },
+    /**
+     * @param {string} address bech32 address
+     * @returns {ChainAddress}
+     * @throws {Error} if chain info not found for bech32Prefix
+     */
+    makeChainAddress(address) {
+      const prefix = getBech32Prefix(address);
+      if (!bech32PrefixToChainName.has(prefix)) {
+        throw makeError(`Chain info not found for bech32Prefix ${q(prefix)}`);
+      }
+      const chainName = bech32PrefixToChainName.get(prefix);
+      const { chainId } = chainInfos.get(chainName);
+      return harden({
+        chainId,
+        value: address,
+        encoding: /** @type {const} */ ('bech32'),
+      });
+    },
+    /**
+     * Determine the transfer route for a destination and amount given the
+     * current holding chain.
+     *
+     * Does not account for routes with more than 1 intermediary hop - that is,
+     * it can't unwrap denoms that were incorrectly routed.
+     *
+     * XXX consider accepting AmountArg #10449
+     *
+     * @param {ChainAddress} destination
+     * @param {DenomAmount} denomAmount
+     * @param {string} srcChainName
+     * @param {IBCMsgTransferOptions['forwardOpts']} [forwardOpts]
+     * @returns {TransferRoute} single hop, multi hop
+     * @throws {Error} if unable to determine route
+     */
+    makeTransferRoute(destination, denomAmount, srcChainName, forwardOpts) {
+      chainInfos.has(srcChainName) ||
+        Fail`chain info not found for holding chain: ${q(srcChainName)}`;
+
+      const denomDetail = chainHub.getAsset(denomAmount.denom, srcChainName);
+      denomDetail ||
+        Fail`no denom detail for: ${q(denomAmount.denom)} on ${q(srcChainName)}. ensure it is registered in chainHub.`;
+
+      const { baseName, chainName } = /** @type {DenomDetail} */ (denomDetail);
+
+      // currently unreachable since assets are registered with holdingChainName
+      chainName === srcChainName ||
+        Fail`cannot transfer asset ${q(denomAmount.denom)}. held on ${q(chainName)} not ${q(srcChainName)}.`;
+
+      // currently unreachable since we can't register an asset before a chain
+      chainInfos.has(baseName) ||
+        Fail`chain info not found for issuing chain: ${q(baseName)}`;
+
+      const { chainId: baseChainId, pfmEnabled } = chainInfos.get(baseName);
+
+      const holdingChainId = chainInfos.get(srcChainName).chainId;
+
+      // asset is transferring to or from the issuing chain, return direct route
+      if (baseChainId === destination.chainId || baseName === srcChainName) {
+        // TODO use getConnectionInfo once its sync
+        const connKey = connectionKey(holdingChainId, destination.chainId);
+        connectionInfos.has(connKey) ||
+          Fail`no connection info found for ${holdingChainId}<->${destination.chainId}`;
+
+        const { transferChannel } = denormalizeConnectionInfo(
+          holdingChainId, // from chain (primary)
+          destination.chainId, // to chain (counterparty)
+          connectionInfos.get(connKey),
+        );
+        return harden({
+          sourcePort: transferChannel.portId,
+          sourceChannel: transferChannel.channelId,
+          token: {
+            amount: String(denomAmount.value),
+            denom: denomAmount.denom,
+          },
+          receiver: destination.value,
+        });
+      }
+
+      // asset is issued on a 3rd chain, attempt pfm route
+      pfmEnabled || Fail`pfm not enabled on issuing chain: ${q(baseName)}`;
+
+      // TODO use getConnectionInfo once its sync
+      const currToIssuerKey = connectionKey(holdingChainId, baseChainId);
+      connectionInfos.has(currToIssuerKey) ||
+        Fail`no connection info found for ${holdingChainId}<->${baseChainId}`;
+
+      const issuerToDestKey = connectionKey(baseChainId, destination.chainId);
+      connectionInfos.has(issuerToDestKey) ||
+        Fail`no connection info found for ${baseChainId}<->${destination.chainId}`;
+
+      const currToIssuer = denormalizeConnectionInfo(
+        holdingChainId,
+        baseChainId,
+        connectionInfos.get(currToIssuerKey),
+      );
+      const issuerToDest = denormalizeConnectionInfo(
+        baseChainId,
+        destination.chainId,
+        connectionInfos.get(issuerToDestKey),
+      );
+
+      /** @type {ForwardInfo} */
+      const forwardInfo = harden({
+        forward: {
+          receiver: destination.value,
+          port: issuerToDest.transferChannel.portId,
+          channel: issuerToDest.transferChannel.channelId,
+          ...DefaultPfmTimeoutOpts,
+          ...forwardOpts,
+        },
+      });
+      return harden({
+        sourcePort: currToIssuer.transferChannel.portId,
+        sourceChannel: currToIssuer.transferChannel.channelId,
+        token: {
+          amount: String(denomAmount.value),
+          denom: denomAmount.denom,
+        },
+        /**
+         * purposely using invalid bech32
+         * {@link https://github.com/cosmos/ibc-apps/blob/26f3ad8f58e4ffc7769c6766cb42b954181dc100/middleware/packet-forward-middleware/README.md#minimal-example---chain-forward-a-b-c}
+         */
+        receiver: forwardOpts?.intermediateRecipient?.value || PFM_RECEIVER,
+        forwardInfo,
+      });
+    },
   });
 
   return chainHub;