feat(fast-usdc): core-eval, builder script (#10477)

closes: #10301

## Description

 - feat(fast-usdc): .start.js core-eval w/oracle invitations
    - the pool share brand is called `FastLP` , at least **UNTIL #10432**
    - needed contract tweak: STUB! makeOracleInvitation , so perhaps this should wait for #10478
 - feat(builders): fast-usdc builder w/CLI config for fees, oracle addresses

Also, rather than yet another ad-hoc way of passing terms containing amounts from builders to core-eval, this includes `LegibleCapData`, an approach for...

   -  #7309

### Security Considerations

Oracle invitations are sent do parties identified by addresses, so the usual key management issues apply. In order to reduce "which address is for which operator?" hassle, configuration uses a record, like we do for `voterAddresses`, rather than a plain array as in price feed core-eval code.

The core eval produces a `fastUSDCKit` including `privateArgs`; this was prompted by testing difficulties: `instancePrivateArgs` is a heap map, not a remotable, so `EV(instancePrivateArgs).get(instance)` is a no-go. But it also usefully avoids handing out all of `instancePrivateArgs` to any core-eval for upgrading this contract.

### Scaling Considerations

The core-eval is O(1), I think. It's O(n) in the number of oracle operators, but that number is fixed by proposal time.

### Documentation Considerations

The builder CLI args are lightly documented, in the source:

```js
/** @type {ParseArgsConfig['options']} */
const optionsConfig = {
  contractFee: { type: 'string', default: '0.01' },
  poolFee: { type: 'string', default: '0.01' },
  oracle: { type: 'string', multiple: true },
};
const oraclesRequiredUsage = 'use --oracle name:address ...';
```


### Testing Considerations

 - [x] test(boot): fast-usdc core eval
   - needed chore: include noble USDC in orch integration test config
 - [x] test(boot): restart fastUSDC
 - [x] unit tests for config marshal 

### Upgrade Considerations

Restart is a pre-requisite for upgrade, so this is progress on testing upgrade of fastUSDC.

Author: mergify[bot]

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

@@ -0,0 +1,108 @@
+import { test as anyTest } from '@agoric/zoe/tools/prepare-test-env-ava.js';
+
+import type { TestFn } from 'ava';
+import type { FastUSDCKit } from '@agoric/fast-usdc/src/fast-usdc.start.js';
+import { Fail } from '@endo/errors';
+import { unmarshalFromVstorage } from '@agoric/internal/src/marshal.js';
+import { makeMarshal } from '@endo/marshal';
+import {
+  makeWalletFactoryContext,
+  type WalletFactoryTestContext,
+} from '../bootstrapTests/walletFactory.js';
+
+const test: TestFn<WalletFactoryTestContext> = anyTest;
+
+test.before('bootstrap', async t => {
+  const config = '@agoric/vm-config/decentral-itest-orchestration-config.json';
+  t.context = await makeWalletFactoryContext(t, config);
+});
+test.after.always(t => t.context.shutdown?.());
+
+test.serial('oracles provision before contract deployment', async t => {
+  const { walletFactoryDriver: wd } = t.context;
+  const watcherWallet = await wd.provideSmartWallet('agoric1watcher1');
+  t.truthy(watcherWallet);
+});
+
+test.serial(
+  'contract starts; adds to agoricNames; sends invitation',
+  async t => {
+    const {
+      agoricNamesRemotes,
+      evalProposal,
+      buildProposal,
+      refreshAgoricNamesRemotes,
+      storage,
+      walletFactoryDriver: wd,
+    } = t.context;
+
+    const watcherWallet = await wd.provideSmartWallet('agoric1watcher1');
+
+    const materials = buildProposal(
+      '@agoric/builders/scripts/fast-usdc/init-fast-usdc.js',
+      ['--oracle', 'a:agoric1watcher1'],
+    );
+    await evalProposal(materials);
+
+    // update now that fastUsdc is instantiated
+    refreshAgoricNamesRemotes();
+    t.truthy(agoricNamesRemotes.instance.fastUsdc);
+    t.truthy(agoricNamesRemotes.brand.FastLP);
+
+    const { EV } = t.context.runUtils;
+    const agoricNames = await EV.vat('bootstrap').consumeItem('agoricNames');
+    const board = await EV.vat('bootstrap').consumeItem('board');
+    const getBoardAux = async name => {
+      const brand = await EV(agoricNames).lookup('brand', name);
+      const id = await EV(board).getId(brand);
+      t.truthy(storage.data.get(`published.boardAux.${id}`));
+      return unmarshalFromVstorage(
+        storage.data,
+        `published.boardAux.${id}`,
+        makeMarshal().fromCapData,
+        -1,
+      );
+    };
+    t.like(
+      await getBoardAux('FastLP'),
+      {
+        allegedName: 'PoolShares', // misnomer, in some contexts
+        displayInfo: {
+          assetKind: 'nat',
+          decimalPlaces: 6,
+        },
+      },
+      'brand displayInfo available in boardAux',
+    );
+
+    const current = watcherWallet.getCurrentWalletRecord();
+
+    // XXX We should be able to compare objects by identity like this:
+    //
+    // const invitationPurse = current.purses.find(
+    //   p => p.brand === agoricNamesRemotes.brand.Invitation,
+    // );
+    //
+    // But agoricNamesRemotes and walletFactoryDriver
+    // don't share a marshal context.
+    // We should be able to map between them using
+    // const walletStuff = w.fromCapData(a.toCapData(aStuff))
+    // but the marshallers don't even preserve identity within themselves.
+
+    current.purses.length === 1 || Fail`test limited to 1 purse`;
+    const [thePurse] = current.purses;
+    const details = thePurse.balance.value as Array<any>;
+    Array.isArray(details) || Fail`expected SET value`;
+    t.is(details.length, 1, 'oracle wallet has 1 invitation');
+    t.is(details[0].description, 'oracle operator invitation');
+    // XXX t.is(details.instance, agoricNames.instance.fastUsdc) should work
+  },
+);
+
+test.serial('restart contract', async t => {
+  const { EV } = t.context.runUtils;
+  await null;
+  const kit = await EV.vat('bootstrap').consumeItem('fastUsdcKit');
+  const actual = await EV(kit.adminFacet).restartContract(kit.privateArgs);
+  t.deepEqual(actual, { incarnationNumber: 1 });
+});

packages/boot/test/orchestration/contract-upgrade.test.ts

@@ -82,7 +82,7 @@ test('resume', async t => {
 
   t.deepEqual(getLogged(), [
     'sending {0} from cosmoshub to cosmos1whatever',
-    'got info for denoms: ibc/toyatom, ibc/toyusdc, ubld, uist',
+    'got info for denoms: ibc/FE98AAD68F02F03565E9FA39A5E627946699B2B07115889ED812D8BA639576A9, ibc/toyatom, ibc/toyusdc, ubld, uist',
     'got info for chain: cosmoshub cosmoshub-4',
     'completed transfer to localAccount',
   ]);
@@ -99,7 +99,7 @@ test('resume', async t => {
 
   t.deepEqual(getLogged(), [
     'sending {0} from cosmoshub to cosmos1whatever',
-    'got info for denoms: ibc/toyatom, ibc/toyusdc, ubld, uist',
+    'got info for denoms: ibc/FE98AAD68F02F03565E9FA39A5E627946699B2B07115889ED812D8BA639576A9, ibc/toyatom, ibc/toyusdc, ubld, uist',
     'got info for chain: cosmoshub cosmoshub-4',
     'completed transfer to localAccount',
     'completed transfer to cosmos1whatever',

packages/boot/tools/supports.ts

@@ -46,15 +46,18 @@ import type { SwingsetController } from '@agoric/swingset-vat/src/controller/con
 import type { BridgeHandler, IBCMethod } from '@agoric/vats';
 import type { BootstrapRootObject } from '@agoric/vats/src/core/lib-boot.js';
 import type { EProxy } from '@endo/eventual-send';
+import type { FastUSDCCorePowers } from '@agoric/fast-usdc/src/fast-usdc.start.js';
 import { icaMocks, protoMsgMockMap, protoMsgMocks } from './ibc/mocks.js';
 
 const trace = makeTracer('BSTSupport', false);
 
 type ConsumeBootrapItem = <N extends string>(
   name: N,
-) => N extends keyof EconomyBootstrapPowers['consume']
-  ? EconomyBootstrapPowers['consume'][N]
-  : unknown;
+) => N extends keyof FastUSDCCorePowers['consume']
+  ? FastUSDCCorePowers['consume'][N]
+  : N extends keyof EconomyBootstrapPowers['consume']
+    ? EconomyBootstrapPowers['consume'][N]
+    : unknown;
 
 // XXX should satisfy EVProxy from run-utils.js but that's failing to import
 /**

packages/builders/package.json

@@ -24,6 +24,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@agoric/ertp": "^0.16.2",
+    "@agoric/fast-usdc": "0.1.0",
     "@agoric/internal": "^0.3.2",
     "@agoric/notifier": "^0.6.2",
     "@agoric/smart-wallet": "^0.5.3",
@@ -36,6 +37,7 @@
     "@endo/far": "^1.1.8",
     "@endo/init": "^1.1.6",
     "@endo/marshal": "^1.6.1",
+    "@endo/patterns": "^1.4.6",
     "@endo/promise-kit": "^1.1.7",
     "@endo/stream": "^1.2.7",
     "import-meta-resolve": "^2.2.1"

packages/builders/scripts/fast-usdc/init-fast-usdc.js

@@ -0,0 +1,105 @@
+// @ts-check
+import { makeHelpers } from '@agoric/deploy-script-support';
+import { AmountMath } from '@agoric/ertp';
+import {
+  FastUSDCConfigShape,
+  getManifestForFastUSDC,
+} from '@agoric/fast-usdc/src/fast-usdc.start.js';
+import { toExternalConfig } from '@agoric/fast-usdc/src/utils/config-marshal.js';
+import { objectMap } from '@agoric/internal';
+import {
+  multiplyBy,
+  parseRatio,
+} from '@agoric/zoe/src/contractSupport/ratio.js';
+import { Far } from '@endo/far';
+import { parseArgs } from 'node:util';
+
+/**
+ * @import {CoreEvalBuilder, DeployScriptFunction} from '@agoric/deploy-script-support/src/externalTypes.js'
+ * @import {ParseArgsConfig} from 'node:util'
+ * @import {FastUSDCConfig} from '@agoric/fast-usdc/src/fast-usdc.start.js'
+ */
+
+/** @type {ParseArgsConfig['options']} */
+const options = {
+  contractFee: { type: 'string', default: '0.01' },
+  poolFee: { type: 'string', default: '0.01' },
+  oracle: { type: 'string', multiple: true },
+};
+const oraclesRequiredUsage = 'use --oracle name:address ...';
+/**
+ * @typedef {{
+ *   contractFee: string;
+ *   poolFee: string;
+ *   oracle?: string[];
+ * }} FastUSDCOpts
+ */
+
+const crossVatContext = /** @type {const} */ ({
+  /** @type {Brand<'nat'>} */
+  USDC: Far('USDC Brand'),
+});
+const { USDC } = crossVatContext;
+const USDC_DECIMALS = 6;
+const unit = AmountMath.make(USDC, 10n ** BigInt(USDC_DECIMALS));
+
+/** @type {CoreEvalBuilder} */
+export const defaultProposalBuilder = async (
+  { publishRef, install },
+  /** @type {FastUSDCConfig} */ config,
+) => {
+  return harden({
+    sourceSpec: '@agoric/fast-usdc/src/fast-usdc.start.js',
+    /** @type {[string, Parameters<typeof getManifestForFastUSDC>[1]]} */
+    getManifestCall: [
+      getManifestForFastUSDC.name,
+      {
+        options: toExternalConfig(config, crossVatContext, FastUSDCConfigShape),
+        installKeys: {
+          fastUsdc: publishRef(
+            install('@agoric/fast-usdc/src/fast-usdc.contract.js'),
+          ),
+        },
+      },
+    ],
+  });
+};
+
+/** @type {DeployScriptFunction} */
+export default async (homeP, endowments) => {
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
+  const { scriptArgs } = endowments;
+
+  /** @type {{ values: FastUSDCOpts }} */
+  // @ts-expect-error ensured by options
+  const {
+    values: { oracle: oracleArgs, ...fees },
+  } = parseArgs({ args: scriptArgs, options });
+
+  const parseOracleArgs = () => {
+    if (!oracleArgs) throw Error(oraclesRequiredUsage);
+    return Object.fromEntries(
+      oracleArgs.map(arg => {
+        const result = arg.match(/(?<name>[^:]+):(?<address>.+)/);
+        if (!(result && result.groups)) throw Error(oraclesRequiredUsage);
+        const { name, address } = result.groups;
+        return [name, address];
+      }),
+    );
+  };
+
+  /** @type {FastUSDCConfig} */
+  const config = harden({
+    oracles: parseOracleArgs(),
+    terms: {
+      ...objectMap(fees, numeral =>
+        multiplyBy(unit, parseRatio(numeral, USDC)),
+      ),
+      usdcDenom: 'ibc/usdconagoric',
+    },
+  });
+
+  await writeCoreEval('start-fast-usdc', utils =>
+    defaultProposalBuilder(utils, config),
+  );
+};

packages/fast-usdc/package.json

@@ -54,7 +54,6 @@
     "@endo/patterns": "^1.4.6",
     "@endo/promise-kit": "^1.1.7",
     "@nick134-bit/noblejs": "0.0.2",
-    "agoric": "^0.21.1",
     "bech32": "^2.0.0",
     "commander": "^12.1.0",
     "ethers": "^6.13.4"

packages/fast-usdc/src/fast-usdc.contract.js

@@ -1,17 +1,16 @@
 import { AssetKind } from '@agoric/ertp';
-import { BrandShape } from '@agoric/ertp/src/typeGuards.js';
 import { assertAllDefined, makeTracer } from '@agoric/internal';
 import { observeIteration, subscribeEach } from '@agoric/notifier';
 import { withOrchestration } from '@agoric/orchestration';
 import { provideSingleton } from '@agoric/zoe/src/contractSupport/durability.js';
 import { prepareRecorderKitMakers } from '@agoric/zoe/src/contractSupport/recorder.js';
-import { M } from '@endo/patterns';
 import { prepareAdvancer } from './exos/advancer.js';
 import { prepareLiquidityPoolKit } from './exos/liquidity-pool.js';
 import { prepareSettler } from './exos/settler.js';
 import { prepareStatusManager } from './exos/status-manager.js';
 import { prepareTransactionFeedKit } from './exos/transaction-feed.js';
 import { defineInertInvitation } from './utils/zoe.js';
+import { FastUSDCTermsShape } from './type-guards.js';
 
 const trace = makeTracer('FastUsdc');
 
@@ -30,13 +29,8 @@ const trace = makeTracer('FastUsdc');
  *   usdcDenom: Denom;
  * }} FastUsdcTerms
  */
-const NatAmountShape = { brand: BrandShape, value: M.nat() };
 export const meta = {
-  customTermsShape: {
-    contractFee: NatAmountShape,
-    poolFee: NatAmountShape,
-    usdcDenom: M.string(),
-  },
+  customTermsShape: FastUSDCTermsShape,
 };
 harden(meta);