refactorings to support AccountId pervasively (#11223)

_incidental_

## Description

The move from `CosmosChainAddress` to CAIP-10 `AccountId` has been incremental. This smooths out one of the common cases where a function needs to pass along a `CosmosChainAddress` but expanding the `makeChainAddress` function to coerce its AccountIdArg into a CosmosChainAddress. It renames it to `coerceCosmosAddress` to make clear its a coercer and that it's only for Cosmos accounts.

It also does a bunch of type narrowing to make the distinctions clearer.

### Security Considerations
none

### Scaling Considerations
none

### Documentation Considerations
none

### Testing Considerations
CI

### Upgrade Considerations
This renames a method on ChainHub. That's safe because there's a new one made in each incarnation.

Author: mergify[bot]

multichain-testing/test/fast-usdc/noble-forwarding.test.ts

@@ -2,7 +2,7 @@ import anyTest from '@endo/ses-ava/prepare-endo.js';
 import type { TestFn } from 'ava';
 import { commonSetup, type SetupContext } from '../support.js';
 import { createWallet } from '../../tools/wallet.js';
-import type { IBCConnectionInfo } from '@agoric/orchestration';
+import type { Bech32Address, IBCConnectionInfo } from '@agoric/orchestration';
 import { makeQueryClient } from '../../tools/query.js';
 
 const test = anyTest as TestFn<SetupContext>;
@@ -12,7 +12,8 @@ test('noble forwarding', async t => {
     await commonSetup(t, { config: '../config.fusdc.yaml' });
 
   const agoricWallet = await createWallet('agoric');
-  const agoricAddr = (await agoricWallet.getAccounts())[0].address;
+  const agoricAddr = (await agoricWallet.getAccounts())[0]
+    .address as Bech32Address;
   t.log('Made agoric wallet:', agoricAddr);
 
   const agoricChainId = useChain('agoric').chain.chain_id;

packages/boot/tools/drivers.ts

@@ -1,4 +1,3 @@
-/* eslint-disable jsdoc/require-param */
 import { Fail } from '@endo/errors';
 import { type Amount } from '@agoric/ertp';
 import { NonNullish } from '@agoric/internal';

packages/cosmic-proto/src/address-hooks.js

@@ -31,6 +31,14 @@
 import { bech32 } from 'bech32';
 import queryString from 'query-string';
 
+/**
+ * @typedef {`${string}1${string}`} Bech32Address
+ * @example
+ *
+ *    agoric1megzytg65cyrgzs6fvzxgrcqvwwl7ugpt62346
+ *    cosmosvaloper1npm9gvss52mlmk
+ */
+
 /* global globalThis */
 /** @type {<T>(x: T) => T} */
 const harden = globalThis.harden || Object.freeze;
@@ -94,15 +102,17 @@ harden(decodeBech32);
  * @param {string} humanReadablePart
  * @param {ArrayLike<number>} bytes
  * @param {number} [charLimit]
- * @returns {string}
+ * @returns {Bech32Address}
  */
 export const encodeBech32 = (
   humanReadablePart,
   bytes,
   charLimit = DEFAULT_HOOKED_ADDRESS_CHAR_LIMIT,
 ) => {
   const words = bech32.toWords(bytes);
-  return bech32.encode(humanReadablePart, words, charLimit);
+  return /** @type {Bech32Address} */ (
+    bech32.encode(humanReadablePart, words, charLimit)
+  );
 };
 harden(encodeBech32);
 
@@ -126,7 +136,7 @@ harden(encodeBech32);
  * @param {string} baseAddress
  * @param {ArrayLike<number>} hookData
  * @param {number} [charLimit]
- * @returns {string}
+ * @returns {Bech32Address}
  */
 export const joinHookedAddress = (
   baseAddress,
@@ -178,6 +188,7 @@ harden(joinHookedAddress);
  * @param {string} baseAddress
  * @param {HookQuery} query
  * @param {number} [charLimit]
+ * @returns {Bech32Address}
  */
 export const encodeAddressHook = (baseAddress, query, charLimit) => {
   const queryStr = queryString.stringify(query);

packages/cosmic-proto/test/address-hooks.test.js

@@ -228,7 +228,7 @@ const lengthCheckMacro = test.macro({
  *   [
  *     baseAddress: string,
  *     query: import('../src/address-hooks.js').HookQuery,
- *     expected: string,
+ *     expected: import('../src/address-hooks.js').Bech32Address,
  *   ]
  * >}
  */

packages/fast-usdc-contract/src/exos/advancer.ts

@@ -45,7 +45,7 @@ import type { ZCF, ZCFSeat } from '@agoric/zoe/src/zoeService/zoe.js';
 import type { Zone } from '@agoric/zone';
 import { Fail, q } from '@endo/errors';
 import { E } from '@endo/far';
-import { M, mustMatch } from '@endo/patterns';
+import { M, mustMatch } from '@agoric/store';
 import type { LiquidityPoolKit } from './liquidity-pool.js';
 import type { SettlerKit } from './settler.js';
 import type { StatusManager } from './status-manager.js';
@@ -200,7 +200,6 @@ export const prepareAdvancerKit = (
             }
             const { EUD } = decoded.query;
             log(`decoded EUD: ${EUD}`);
-            assert.typeof(EUD, 'string');
             // throws if the bech32 prefix is not found
             const destination = chainHub.resolveAccountId(EUD);
 

packages/fast-usdc-contract/src/exos/settler.ts

@@ -17,6 +17,7 @@ import { M } from '@endo/patterns';
 import { decodeAddressHook } from '@agoric/cosmic-proto/address-hooks.js';
 import { PendingTxStatus } from '@agoric/fast-usdc/src/constants.js';
 import {
+  AddressHookShape,
   CctpTxEvidenceShape,
   EvmHashShape,
   makeNatAmountShape,
@@ -36,14 +37,16 @@ import type {
 } from '@agoric/fast-usdc/src/types.js';
 import type {
   AccountId,
+  AccountIdArg,
+  Bech32Address,
   ChainHub,
   CosmosChainAddress,
   Denom,
   OrchestrationAccount,
 } from '@agoric/orchestration';
 import { parseAccountId } from '@agoric/orchestration/src/utils/address.js';
 import type { WithdrawToSeat } from '@agoric/orchestration/src/utils/zoe-tools.js';
-import type { MapStore } from '@agoric/store';
+import { mustMatch, type MapStore } from '@agoric/store';
 import type { IBCChannelID, IBCPacket, VTransferIBCEvent } from '@agoric/vats';
 import type { TargetRegistration } from '@agoric/vats/src/bridge-target.js';
 import type { VowTools } from '@agoric/vow';
@@ -58,7 +61,7 @@ const decodeEventPacket = (
   { data }: IBCPacket,
   remoteDenom: string,
 ):
-  | { nfa: NobleAddress; amount: bigint; EUD: string }
+  | { nfa: NobleAddress; amount: bigint; EUD: AccountId | Bech32Address }
   | { error: unknown[] } => {
   // NB: may not be a FungibleTokenPacketData or even JSON
   let tx: FungibleTokenPacketData;
@@ -76,15 +79,12 @@ const decodeEventPacket = (
     return { error: ['unexpected denom', { actual, expected: remoteDenom }] };
   }
 
-  let EUD;
+  let EUD: Bech32Address;
   try {
-    ({ EUD } = decodeAddressHook(tx.receiver).query);
-    if (!EUD) {
-      return { error: ['no EUD parameter', tx.receiver] };
-    }
-    if (typeof EUD !== 'string') {
-      return { error: ['EUD is not a string', EUD] };
-    }
+    const decoded = decodeAddressHook(tx.receiver);
+    mustMatch(decoded, AddressHookShape);
+
+    ({ EUD } = decoded.query);
   } catch (e) {
     return { error: ['no query params', tx.receiver] };
   }
@@ -362,15 +362,11 @@ export const prepareSettler = (
         /**
          * The intended payee received an advance from the pool. When the funds
          * are minted, disburse them to the pool and fee seats.
-         *
-         * @param {EvmHash} txHash
-         * @param {NatValue} fullValue
-         * @param {AccountId | CosmosChainAddress['value']} EUD
          */
         async disburse(
           txHash: EvmHash,
           fullValue: NatValue,
-          EUD: AccountId | CosmosChainAddress['value'],
+          EUD: AccountId | Bech32Address,
         ) {
           const { repayer, settlementAccount } = this.state;
           const received = AmountMath.make(USDC, fullValue);
@@ -407,7 +403,11 @@ export const prepareSettler = (
          * @param {NatValue} fullValue
          * @param {string} EUD
          */
-        forward(txHash: EvmHash, fullValue: NatValue, EUD: string) {
+        forward(
+          txHash: EvmHash,
+          fullValue: NatValue,
+          EUD: AccountId | Bech32Address,
+        ) {
           const { settlementAccount } = this.state;
           log('forwarding', fullValue, 'to', EUD, 'for', txHash);
 

packages/fast-usdc-contract/test/exos/advancer.test.ts

@@ -330,7 +330,7 @@ test('updates status to ADVANCE_SKIPPED on insufficient pool funds', async t =>
   ]);
 });
 
-test('updates status to ADVANCE_SKIPPED if makeChainAddress fails', async t => {
+test('updates status to ADVANCE_SKIPPED if coerceCosmosAddress fails', async t => {
   const {
     bootstrap: { storage },
     extensions: {
@@ -352,7 +352,7 @@ test('updates status to ADVANCE_SKIPPED if makeChainAddress fails', async t => {
         status: 'ADVANCE_SKIPPED',
       },
     ],
-    'ADVANCE_SKIPPED status on makeChainAddress failure',
+    'ADVANCE_SKIPPED status on coerceCosmosAddress failure',
   );
 
   t.deepEqual(inspectLogs(), [

packages/fast-usdc-contract/test/exos/settler.test.ts

@@ -5,22 +5,23 @@ import {
   decodeAddressHook,
   encodeAddressHook,
 } from '@agoric/cosmic-proto/address-hooks.js';
+import { PendingTxStatus, TxStatus } from '@agoric/fast-usdc/src/constants.js';
+import { AddressHookShape } from '@agoric/fast-usdc/src/type-guards.js';
+import type { CctpTxEvidence } from '@agoric/fast-usdc/src/types.js';
+import { makeFeeTools } from '@agoric/fast-usdc/src/utils/fees.js';
 import { defaultMarshaller } from '@agoric/internal/src/storage-test-utils.js';
 import { eventLoopIteration } from '@agoric/internal/src/testing-utils.js';
+import cctpChainInfo from '@agoric/orchestration/src/cctp-chain-info.js';
 import fetchedChainInfo from '@agoric/orchestration/src/fetched-chain-info.js';
 import { buildVTransferEvent } from '@agoric/orchestration/tools/ibc-mocks.js';
-import type { Zone } from '@agoric/zone';
-import type { EReturn } from '@endo/far';
+import { mustMatch } from '@agoric/store';
 import type {
   AmountKeywordRecord,
   TransferPart,
   ZcfSeatKit,
 } from '@agoric/zoe';
-import { PendingTxStatus, TxStatus } from '@agoric/fast-usdc/src/constants.js';
-import type { CctpTxEvidence } from '@agoric/fast-usdc/src/types.js';
-import { makeFeeTools } from '@agoric/fast-usdc/src/utils/fees.js';
-import type { Baggage } from '@agoric/vat-data';
-import cctpChainInfo from '@agoric/orchestration/src/cctp-chain-info.js';
+import type { Zone } from '@agoric/zone';
+import type { EReturn } from '@endo/far';
 import {
   prepareSettler,
   type SettlerKit,
@@ -133,10 +134,9 @@ const makeTestContext = async t => {
       const { txHash } = evidence;
       const { forwardingAddress, amount } = evidence.tx;
       const { recipientAddress } = evidence.aux;
-      const { EUD } = decodeAddressHook(recipientAddress).query;
-      if (typeof EUD !== 'string') {
-        throw Error(`EUD not found in ${recipientAddress}`);
-      }
+      const decoded = decodeAddressHook(recipientAddress);
+      mustMatch(decoded, AddressHookShape);
+      const { EUD } = decoded.query;
       return harden({
         txHash,
         forwardingAddress,
@@ -875,7 +875,7 @@ test('bad packet data', async t => {
   t.deepEqual(inspectLogs().at(-1), [
     'invalid event packet',
     [
-      'no EUD parameter',
+      'no query params',
       'agoric10rchps2sfet5lleu7xhs6ztgeehkm5lz5rpkz0cqzs95zdge',
     ],
   ]);

packages/fast-usdc-contract/test/fast-usdc.contract.test.ts

@@ -28,7 +28,11 @@ import {
   type Publisher,
   type Subscriber,
 } from '@agoric/notifier';
-import type { ChainHub, CosmosChainInfo } from '@agoric/orchestration';
+import type {
+  Bech32Address,
+  ChainHub,
+  CosmosChainInfo,
+} from '@agoric/orchestration';
 import fetchedChainInfo from '@agoric/orchestration/src/fetched-chain-info.js';
 import { buildVTransferEvent } from '@agoric/orchestration/tools/ibc-mocks.js';
 import { makeTestAddress } from '@agoric/orchestration/tools/make-test-address.js';
@@ -399,7 +403,7 @@ const makeEVM = (template = MockCctpTxEvidences.AGORIC_PLUS_OSMO()) => {
 
   const makeTx = (
     amount: bigint,
-    recipientAddress: string,
+    recipientAddress: Bech32Address,
     nonceOverride?: number,
   ): CctpTxEvidence => {
     nonce += 1;

packages/fast-usdc-contract/test/fixtures.ts

@@ -1,6 +1,6 @@
 import { buildVTransferEvent } from '@agoric/orchestration/tools/ibc-mocks.js';
 import fetchedChainInfo from '@agoric/orchestration/src/fetched-chain-info.js';
-import type { CosmosChainAddress } from '@agoric/orchestration';
+import type { Bech32Address, CosmosChainAddress } from '@agoric/orchestration';
 import type { VTransferIBCEvent } from '@agoric/vats';
 import {
   MockCctpTxEvidences,
@@ -21,9 +21,9 @@ const nobleDefaultVTransferParams = {
 
 export const MockVTransferEvents: Record<
   MockScenario,
-  (receiverAddress?: string) => VTransferIBCEvent
+  (receiverAddress?: Bech32Address) => VTransferIBCEvent
 > = {
-  AGORIC_PLUS_OSMO: (receiverAddress?: string) =>
+  AGORIC_PLUS_OSMO: (receiverAddress?: Bech32Address) =>
     buildVTransferEvent({
       ...nobleDefaultVTransferParams,
       amount: MockCctpTxEvidences.AGORIC_PLUS_OSMO().tx.amount,
@@ -32,7 +32,7 @@ export const MockVTransferEvents: Record<
         receiverAddress ||
         MockCctpTxEvidences.AGORIC_PLUS_OSMO().aux.recipientAddress,
     }),
-  AGORIC_PLUS_DYDX: (receiverAddress?: string) =>
+  AGORIC_PLUS_DYDX: (receiverAddress?: Bech32Address) =>
     buildVTransferEvent({
       ...nobleDefaultVTransferParams,
       amount: MockCctpTxEvidences.AGORIC_PLUS_DYDX().tx.amount,
@@ -41,7 +41,7 @@ export const MockVTransferEvents: Record<
         receiverAddress ||
         MockCctpTxEvidences.AGORIC_PLUS_DYDX().aux.recipientAddress,
     }),
-  AGORIC_PLUS_AGORIC: (receiverAddress?: string) =>
+  AGORIC_PLUS_AGORIC: (receiverAddress?: Bech32Address) =>
     buildVTransferEvent({
       ...nobleDefaultVTransferParams,
       amount: MockCctpTxEvidences.AGORIC_PLUS_AGORIC().tx.amount,
@@ -50,7 +50,7 @@ export const MockVTransferEvents: Record<
         receiverAddress ||
         MockCctpTxEvidences.AGORIC_PLUS_AGORIC().aux.recipientAddress,
     }),
-  AGORIC_NO_PARAMS: (receiverAddress?: string) =>
+  AGORIC_NO_PARAMS: (receiverAddress?: Bech32Address) =>
     buildVTransferEvent({
       ...nobleDefaultVTransferParams,
       amount: MockCctpTxEvidences.AGORIC_NO_PARAMS().tx.amount,
@@ -59,7 +59,7 @@ export const MockVTransferEvents: Record<
         receiverAddress ||
         MockCctpTxEvidences.AGORIC_NO_PARAMS().aux.recipientAddress,
     }),
-  AGORIC_UNKNOWN_EUD: (receiverAddress?: string) =>
+  AGORIC_UNKNOWN_EUD: (receiverAddress?: Bech32Address) =>
     buildVTransferEvent({
       ...nobleDefaultVTransferParams,
       amount: MockCctpTxEvidences.AGORIC_UNKNOWN_EUD().tx.amount,
@@ -69,7 +69,7 @@ export const MockVTransferEvents: Record<
         MockCctpTxEvidences.AGORIC_UNKNOWN_EUD().aux.recipientAddress,
     }),
 
-  AGORIC_PLUS_ETHEREUM: (receiverAddress?: string) =>
+  AGORIC_PLUS_ETHEREUM: (receiverAddress?: Bech32Address) =>
     buildVTransferEvent({
       ...nobleDefaultVTransferParams,
       amount: MockCctpTxEvidences.AGORIC_PLUS_ETHEREUM().tx.amount,