chore: implement parseInboundTransfer

anilhelvaci · anilhelvaci · commit 347fd7621c6c · 2025-05-14T15:03:06.000+03:00
Refs: #11374
diff --git a/packages/orchestration/src/cosmos-api.ts b/packages/orchestration/src/cosmos-api.ts
@@ -357,6 +357,15 @@ export interface LocalAccountMethods extends StakingAccountActions {
    * @param tap
    */
   monitorTransfers: (tap: TargetApp) => Promise<TargetRegistration>;
+  /**
+   * Parse an incoming transfer message and return its details.
+   */
+  parseInboundTransfer: (packet: Record<string, any>) => Promise<{
+    amount: DenomAmount;
+    fromAccount: AccountId;
+    toAccount: AccountId;
+    extra: Record<string, any>;
+  }>;
 }
 
 /**
diff --git a/packages/orchestration/src/exos/local-orchestration-account.js b/packages/orchestration/src/exos/local-orchestration-account.js
@@ -28,8 +28,11 @@ import { TransferRouteShape } from './chain-hub.js';
 /**
  * @import {HostOf} from '@agoric/async-flow';
  * @import {LocalChain, LocalChainAccount} from '@agoric/vats/src/localchain.js';
- * @import {AmountArg, CosmosChainAddress, DenomAmount, IBCMsgTransferOptions, IBCConnectionInfo, OrchestrationAccountCommon, LocalAccountMethods, TransferRoute, AccountId, AccountIdArg} from '@agoric/orchestration';
- * @import {ContractMeta, Invitation, OfferHandler, ZCF, ZCFSeat} from '@agoric/zoe';
+ * @import {AmountArg, CosmosChainAddress, DenomAmount, IBCMsgTransferOptions, OrchestrationAccountCommon, LocalAccountMethods, TransferRoute, AccountIdArg, Denom, Bech32Address} from '@agoric/orchestration';
+ * @import {OfferHandler, ZCF, ZCFSeat} from '@agoric/zoe';
+ * @import {IBCEvent} from '@agoric/vats';
+ * @import {QueryDenomHashResponse} from '@agoric/cosmic-proto/ibc/applications/transfer/v1/query.js';
+ * @import {FungibleTokenPacketData} from '@agoric/cosmic-proto/ibc/applications/transfer/v2/packet.js';
  * @import {RecorderKit, MakeRecorderKit} from '@agoric/zoe/src/contractSupport/recorder.js'.
  * @import {Zone} from '@agoric/zone';
  * @import {Remote} from '@agoric/internal';
@@ -78,6 +81,14 @@ const HolderI = M.interface('holder', {
     .returns(EVow$(M.string())),
   matchFirstPacket: M.call(M.any()).returns(EVow$(M.any())),
   monitorTransfers: M.call(M.remotable('TargetApp')).returns(EVow$(M.any())),
+  parseInboundTransfer: M.call(M.recordOf(M.string(), M.any())).returns(
+    Vow$({
+      amount: DenomAmountShape,
+      fromAccount: M.string(),
+      toAccount: M.string(),
+      extra: M.recordOf(M.string(), M.any()),
+    }),
+  ),
 });
 
 /** @type {{ [name: string]: [description: string, valueShape: Matcher] }} */
@@ -167,6 +178,10 @@ export const prepareLocalOrchestrationAccountKit = (
           M.arrayOf(DenomAmountShape),
         ),
       }),
+      parseInboundTransferWatcher: M.interface('parseInboundTransferWatcher', {
+        onFulfilled: M.call(M.record(), M.record()).returns(M.record()),
+        onRejected: M.call(M.any(), M.record()).returns(M.record()),
+      }),
       invitationMakers: M.interface('invitationMakers', {
         CloseAccount: M.call().returns(M.promise()),
         Delegate: M.call(M.string(), AmountShape).returns(M.promise()),
@@ -481,6 +496,40 @@ export const prepareLocalOrchestrationAccountKit = (
           return harden(balances.map(toDenomAmount));
         },
       },
+      parseInboundTransferWatcher: {
+        /**
+         * @param {QueryDenomHashResponse} localDenomHash
+         * @param {Awaited<
+         *   ReturnType<LocalAccountMethods['parseInboundTransfer']>
+         * >} naiveResult
+         */
+        onFulfilled(localDenomHash, naiveResult) {
+          const localDenom = `ibc/${localDenomHash.hash}`;
+          const { amount, ...rest } = naiveResult;
+          const { denom: _, ...amountRest } = amount;
+          return harden({
+            ...rest,
+            amount: { ...amountRest, denom: localDenom },
+          });
+        },
+        /**
+         * @param {unknown} reason
+         * @param {Awaited<
+         *   ReturnType<LocalAccountMethods['parseInboundTransfer']>
+         * >} naiveResult
+         */
+        onRejected(reason, naiveResult) {
+          if (
+            reason instanceof Error &&
+            String(reason.message).includes('denomination trace not found')
+          ) {
+            // Looks like the trace was not found; The naive result is good enough.
+            return naiveResult;
+          }
+          // Propagate other errors upwards.
+          throw reason;
+        },
+      },
       holder: {
         /** @type {HostOf<OrchestrationAccountCommon['asContinuingOffer']>} */
         asContinuingOffer() {
@@ -716,6 +765,76 @@ export const prepareLocalOrchestrationAccountKit = (
             return resultV;
           });
         },
+        /**
+         * @type {HostOf<LocalAccountMethods['parseInboundTransfer']>}
+         */
+        parseInboundTransfer(record) {
+          trace('parseInboundTransfer', record);
+          return asVow(() => {
+            const packet =
+              /** @type {IBCEvent<'writeAcknowledgement'>['packet']} */ (
+                record
+              );
+
+            /** @type {FungibleTokenPacketData} */
+            const ftPacketData = JSON.parse(atob(packet.data));
+            const {
+              denom: transferDenom,
+              sender,
+              receiver,
+              amount,
+            } = ftPacketData;
+
+            /**
+             * @param {string} address
+             */
+            const resolveBech32Address = address =>
+              chainHub.resolveAccountId(/** @type {Bech32Address} */ (address));
+
+            /**
+             * @param {Denom} localDenom
+             */
+            const buildReturnValue = localDenom =>
+              harden({
+                amount: /** @type {DenomAmount} */ ({
+                  value: BigInt(amount),
+                  denom: localDenom,
+                }),
+                fromAccount: resolveBech32Address(sender),
+                toAccount: resolveBech32Address(receiver),
+                extra: {
+                  ...ftPacketData,
+                },
+              });
+
+            /**
+             * @type {Denom}
+             */
+            let denomOrTrace;
+
+            const prefix = `${packet.source_port}/${packet.source_channel}/`;
+            trace({ transferDenom, prefix });
+            if (transferDenom.startsWith(prefix)) {
+              // Unwind, which may end up as a local denom.
+              denomOrTrace = transferDenom.slice(prefix.length);
+            } else {
+              // If the denom is not local, attach its source.
+              denomOrTrace = `${packet.destination_port}/${packet.destination_channel}/${transferDenom}`;
+            }
+
+            // Find the local denom hash for the transferDenom, if there is one.
+            return watch(
+              E(localchain).query(
+                typedJson(
+                  '/ibc.applications.transfer.v1.QueryDenomHashRequest',
+                  { trace: denomOrTrace },
+                ),
+              ),
+              this.facets.parseInboundTransferWatcher,
+              buildReturnValue(denomOrTrace),
+            );
+          });
+        },
         /** @type {HostOf<OrchestrationAccountCommon['transferSteps']>} */
         transferSteps(amount, msg) {
           return asVow(() => {
diff --git a/packages/orchestration/test/exos/local-orchestration-account-kit.test.ts b/packages/orchestration/test/exos/local-orchestration-account-kit.test.ts
@@ -5,6 +5,7 @@ import { eventLoopIteration } from '@agoric/internal/src/testing-utils.js';
 import type { TargetApp } from '@agoric/vats/src/bridge-target.js';
 import {
   LOCALCHAIN_QUERY_ALL_BALANCES_RESPONSE,
+  LOCALCHAIN_QUERY_DENOM_HASH_DEFAULT_VALUE,
   SIMULATED_ERRORS,
 } from '@agoric/vats/tools/fake-bridge.js';
 import { heapVowE as VE } from '@agoric/vow/vat.js';
@@ -524,3 +525,82 @@ test('getBalances', async t => {
   );
   t.is(queryMessages.length, 1, 'getBalances sends query to cosmos golang');
 });
+
+test('parseInboundTransfer', async t => {
+  const common = await commonSetup(t);
+  common.utils.populateChainHub();
+  const makeTestLOAKit = prepareMakeTestLOAKit(t, common);
+  const account = await makeTestLOAKit();
+
+  const { value: target } = await VE(account).getAddress();
+
+  /**
+   * Here we assume an account on CosmosHub that has BLD (funded by an Agoric account)
+   * sends some 'ibc/hash('transfer/channel-1/' + ubld)' back to Agoric. Where "transfer"
+   * is source port and "channel-1" is source channel for CosmosHub.
+   *
+   * parseInboundTransfer should be able to handle incoming denom 'transfer/channel-1/ubld'
+   * as a local denom.
+   *
+   * Here's an example IBC packet we scraped from multichain:
+   * @example
+   *   { event: 'writeAcknowledgement',
+   *      packet: { data: 'eyJhbW91bnQiOiIxMjUiLCJkZW5vbSI6InRyYW5zZmVyL2NoYW5uZWwtMS91YmxkIiwicmVjZWl2ZXIiOiJhZ29yaWMxMHJjaHBjNmFyZjVlNHhmMDYzODh5M21kdzc2M2pnZTZobng0Y3hxcWptend3dzRmMmQ4cnBxZjk4YW54N21lYXZmc2h5cXBxNHo2c2VhIiwic2VuZGVyIjoiY29zbW9zMXJzamR2aHpydDl0NnQwZnl5cnVseGpneHFlcHNtdnJmeXltNWh6In0=', destination_channel: 'channel-1', destination_port: 'transfer', sequence: '1', source_channel: 'channel-1', source_port: 'transfer', timeout_height: { revision_height: '0', revision_number: '0' }, timeout_timestamp: '14933241973593604096' }, relayer: '', target: 'agoric1udw356v6nyhagnnjgakh0dgeyvaten2urqqfd3888254xn3ssyjsmlny72', type: 'VTRANSFER_IBC_EVENT' }
+   *   And packet.data decodes to: '{"amount":"125","denom":"transfer/channel-1/ubld","receiver":"agoric10rchpc6arf5e4xf06388y3mdw763jge6hnx4cxqqjmzwww4f2d8rpqf98anx7meavfshyqpq4z6sea","sender":"cosmos1rsjdvhzrt9t6t0fyyrulxjgxqepsmvrfyym5hz"}'
+   */
+  const bldResult = await VE(account).parseInboundTransfer(
+    buildVTransferEvent({
+      receiver: target,
+      denom: 'transfer/channel-1/ubld',
+      amount: 33n,
+      destinationChannel: 'channel-0',
+      sequence: '6',
+      sourceChannel: 'channel-1',
+    }).packet,
+  );
+
+  t.log(bldResult);
+  t.like(bldResult, {
+    amount: {
+      denom: 'ubld',
+      value: 33n,
+    },
+    extra: {
+      denom: 'transfer/channel-1/ubld',
+      amount: '33',
+    },
+  });
+
+  /**
+   * And here we send uatom from CosmosHub to Agoric. The expectation is that parseInboundTransfer returns
+   * a hash as amount.denom instead of 'transfer/channel-0/uatom'.
+   *
+   * Here's an example IBC packet we scraped from multichain:
+   * @example
+   *  { event: 'writeAcknowledgement',
+   *     packet: { data: 'eyJhbW91bnQiOiI5OSIsImRlbm9tIjoidWF0b20iLCJyZWNlaXZlciI6ImFnb3JpYzEwcmNocDJreHhxMmVlcThrc2RjeDQ3bjI0bHZteWQ5am1zeXRmZGY2NWxncG5qN2dnbDd0cTZrbThhbng3bWVhdmZzaHlxcHEycmZ1YWQiLCJzZW5kZXIiOiJjb3Ntb3Mxbnhsd3h2OXN3NG55ejVkM2E0c2d0NTNlMHNxOHFzeGNsbHB1NmsifQ==', destination_channel: 'channel-0', destination_port: 'transfer', sequence: '1', source_channel: 'channel-1', source_port: 'transfer', timeout_height: { revision_height: '0', revision_number: '0' }, timeout_timestamp: '14933241973593604096' }, relayer: '', target: 'agoric14trrq9vusrmgxur2lf42lkdjxjedcz95k5a205qee0yy0l9sdtdstw3zja', type: 'VTRANSFER_IBC_EVENT' }
+   *   And packet.data decodes to: '{"amount":"99","denom":"uatom","receiver":"agoric10rchp2kxxq2eeq8ksdcx47n24lvmyd9jmsytfdf65lgpnj7ggl7tq6km8anx7meavfshyqpq2rfuad","sender":"cosmos1nxlwxv9sw4nyz5d3a4sgt53e0sq8qsxcllpu6k"}'
+   */
+  const atomResult = await VE(account).parseInboundTransfer(
+    buildVTransferEvent({
+      receiver: target,
+      denom: 'uatom',
+      amount: 35n,
+      destinationChannel: 'channel-0',
+      sequence: '6',
+      sourceChannel: 'channel-1',
+    }).packet,
+  );
+
+  t.log(atomResult);
+  t.like(atomResult, {
+    amount: {
+      denom: `ibc/${LOCALCHAIN_QUERY_DENOM_HASH_DEFAULT_VALUE}`,
+      value: 35n,
+    },
+    extra: {
+      denom: 'uatom',
+      amount: '35',
+    },
+  });
+});
diff --git a/packages/vats/tools/fake-bridge.js b/packages/vats/tools/fake-bridge.js
@@ -251,6 +251,8 @@ export const LOCALCHAIN_QUERY_ALL_BALANCES_RESPONSE = [
   },
 ];
 
+export const LOCALCHAIN_QUERY_DENOM_HASH_DEFAULT_VALUE = 'fakeDenomHash';
+
 /**
  * Used to mock responses from Cosmos Golang back to SwingSet for for
  * E(lca).query() and E(lca).queryMany().
@@ -292,6 +294,21 @@ export const fakeLocalChainBridgeQueryHandler = message => {
         },
       };
     }
+    case '/ibc.applications.transfer.v1.QueryDenomHashRequest': {
+      // native agoric assets cause this query throw
+      if (message.trace === 'ubld') {
+        throw new Error('ubld denomination trace not found');
+      }
+
+      return {
+        error: '',
+        height: '1',
+        reply: {
+          '@type': '/ibc.applications.transfer.v1.QueryDenomHashResponse',
+          hash: LOCALCHAIN_QUERY_DENOM_HASH_DEFAULT_VALUE,
+        },
+      };
+    }
     // returns one empty object per message unless specified
     default:
       return {};
