@agoric/fast-usdc 0.2.0-upgrade-20-dev-ef71cfd.0 → 0.2.0-upgrade-19-devnet-dev-5428c4d.0

package/README.md

@@ -1,27 +1,101 @@
 # Fast USDC
 
-Development package for the Fast USDC product. Here in agoric-sdk as a
-convenience for integration testing and iterating on the SDK affordances
-required for the product.
+Development package for the Fast USDC product.
+Here in agoric-sdk as a convenience for integration testing and iterating on the SDK affordances required for the product.
 
 # Factoring
 
-This package is meant to contain all the code for the Fast USDC product.
-However, there are some constraints:
+This package is meant to contain all the code for the Fast USDC product. However there are some constraints:
 
-- a3p integration tests are in the `a3p-integration` top-level package, separate
-    from this workspace
-- the proposal builders are in `@agoric/builders` to work with the
-    a3p-integration `build:submissions` script
-- the RunUtils tests are in `@aglocal/boot` to test running them atop a fresh
-    bootstrapped environment
+- a3p integration tests are in the `a3p-integration` top-level package, separate from this workspace
+- the proposal builders are in `@agoric/builders` to work with the a3p-integration `build:submissions` script
+- the RunUtils tests are in `@agoric/boot` to test running them atop a fresh bootstrapped environment
 
 Over time we can update our tooling to decouple this more from the `packages` directory.
 
-1. Make a3p-integration `build:submissions` script work with arbitrary builder
-    paths, allowing this to be above `@agoric/builders` in the package graph
-2. Export bootstrap testing utilities from `@aglocal/boot`, allowing this to be
-    above `@aglocal/boot` in the package graph
-3. Update CI to support packages that aren't under `packages/`, eg. a top-level
-   `dapps` directory
+1. Make a3p-integration `build:submissions` script work with arbitrary builder paths, allowing this to be above `@agoric/builders` in the package graph
+2. Export bootstrap testing utilities from `@agoric/boot`, allowing this to be above `@agoric/boot` in the package graph
+3. Update CI to support packages that aren't under `packages/`, eg. a top-level `dapps` directory
 4. Move this package out of agoric-sdk
+
+# Transaction feed
+
+## Oracles interface
+
+Oracles run off-chain and interact with the contract via an Agoric smart wallet bridge.
+```mermaid
+sequenceDiagram
+    title Becoming an oracle operator
+    participant OW as Operator N<br/>Smart Wallet
+    participant FUC as Fast USDC<br/>Contract Exo
+    participant CE as Core Eval
+
+    CE->>FUC: makeOperatorInvitation()
+    FUC-->>CE: operatorInvitation
+    CE->>+OW: deposit(operatorInvitation)
+
+    Note left of FUC: Off-chain wallet accepts the operator invitation
+
+    OW->>+FUC: offer(operatorInvitation)
+    FUC-->>OW: operator invitationMakers: {SubmitEvidence}
+
+    Note left of FUC: Off-chain watcher detects evidence
+    OW->>+FUC: offer(SubmitEvidence, evidence)
+```
+
+```mermaid
+sequenceDiagram
+    title Receiving evidence
+    participant W as Operator N<br/>Smart Wallet
+    participant A as Operator N<br/>Admin Oexo
+    participant TF as Transaction<br/>Feed
+
+    W->>A: offer(SubmitEvidence, evidence)
+
+    Note left of A: Once 3 operators push the same…
+
+    A->>TF: notify(evidence)
+```
+
+# Status Manager
+
+### Pending Advance State Diagram
+
+*Transactions are qualified by the OCW and EventFeed before arriving to the Advancer.*
+
+```mermaid
+stateDiagram-v2
+  [*] --> Observed: observe()
+  [*] --> Advancing: advancing()
+
+  Advancing --> Advanced: advanceOutcome(...true)
+  Advancing --> AdvanceFailed: advanceOutcome(...false)
+
+  Observed --> [*]: dequeueStatus()
+  Advanced --> [*]: dequeueStatus()
+  AdvanceFailed --> [*]: dequeueStatus()
+
+  note right of [*]
+    After dequeueStatus():
+    Transaction is removed 
+    from pendingTxs store.
+    Settler will .disburse()
+    or .forward()
+  end note
+```
+
+### Complete state diagram (starting from Transaction Feed into Advancer)
+
+```mermaid
+stateDiagram-v2
+  Observed --> AdvanceSkipped : Risks identified
+  Observed --> Advancing : No risks, can advance
+  Observed --> Forwarding : No risks, Mint deposited before advance
+  Forwarding --> Forwarded
+  Advancing --> Advanced
+  Advanced --> Disbursed
+  AdvanceSkipped --> Forwarding : Mint deposited
+  AdvanceFailed --> Forwarding : Mint deposited
+  Advancing --> AdvanceFailed
+  Forwarding --> ForwardFailed
+```

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@agoric/fast-usdc",
-  "version": "0.2.0-upgrade-20-dev-ef71cfd.0+ef71cfd",
+  "version": "0.2.0-upgrade-19-devnet-dev-5428c4d.0+5428c4d",
   "description": "CLI and library for Fast USDC product",
   "type": "module",
   "files": [
+    "contract",
     "src",
     "tools"
   ],
@@ -22,33 +23,39 @@
     "lint:eslint": "eslint ."
   },
   "devDependencies": {
+    "@agoric/swingset-liveslots": "0.10.3-upgrade-19-devnet-dev-5428c4d.0+5428c4d",
+    "@agoric/vats": "0.16.0-upgrade-19-devnet-dev-5428c4d.0+5428c4d",
+    "@agoric/zone": "0.3.0-upgrade-19-devnet-dev-5428c4d.0+5428c4d",
     "@fast-check/ava": "^2.0.1",
     "ava": "^5.3.0",
     "c8": "^10.1.2",
-    "nano-spawn": "^0.2.0",
+    "execa": "9.1.0",
     "ts-blank-space": "^0.4.4"
   },
   "dependencies": {
-    "@agoric/client-utils": "0.2.0-upgrade-20-dev-ef71cfd.0+ef71cfd",
-    "@agoric/cosmic-proto": "0.5.0-upgrade-20-dev-ef71cfd.0+ef71cfd",
-    "@agoric/ertp": "0.16.3-upgrade-20-dev-ef71cfd.0+ef71cfd",
-    "@agoric/internal": "0.4.0-upgrade-20-dev-ef71cfd.0+ef71cfd",
-    "@agoric/notifier": "0.7.0-upgrade-20-dev-ef71cfd.0+ef71cfd",
-    "@agoric/orchestration": "0.2.0-upgrade-20-dev-ef71cfd.0+ef71cfd",
-    "@agoric/zoe": "0.27.0-upgrade-20-dev-ef71cfd.0+ef71cfd",
-    "@cosmjs/proto-signing": "^0.33.0",
-    "@cosmjs/stargate": "^0.33.0",
+    "@agoric/client-utils": "0.2.0-upgrade-19-devnet-dev-5428c4d.0+5428c4d",
+    "@agoric/cosmic-proto": "0.5.0-upgrade-19-devnet-dev-5428c4d.0+5428c4d",
+    "@agoric/ertp": "0.16.3-upgrade-19-devnet-dev-5428c4d.0+5428c4d",
+    "@agoric/internal": "0.4.0-upgrade-19-devnet-dev-5428c4d.0+5428c4d",
+    "@agoric/notifier": "0.7.0-upgrade-19-devnet-dev-5428c4d.0+5428c4d",
+    "@agoric/orchestration": "0.2.0-upgrade-19-devnet-dev-5428c4d.0+5428c4d",
+    "@agoric/store": "0.9.3-upgrade-19-devnet-dev-5428c4d.0+5428c4d",
+    "@agoric/vat-data": "0.5.3-upgrade-19-devnet-dev-5428c4d.0+5428c4d",
+    "@agoric/vow": "0.2.0-upgrade-19-devnet-dev-5428c4d.0+5428c4d",
+    "@agoric/zoe": "0.27.0-upgrade-19-devnet-dev-5428c4d.0+5428c4d",
+    "@cosmjs/proto-signing": "^0.32.4",
+    "@cosmjs/stargate": "^0.32.4",
     "@endo/base64": "^1.0.9",
-    "@endo/common": "^1.2.10",
-    "@endo/errors": "^1.2.10",
-    "@endo/eventual-send": "^1.3.1",
-    "@endo/far": "^1.1.11",
-    "@endo/init": "^1.1.9",
-    "@endo/marshal": "^1.6.4",
-    "@endo/nat": "^5.1.0",
-    "@endo/pass-style": "^1.5.0",
-    "@endo/patterns": "^1.5.0",
-    "@endo/promise-kit": "^1.1.10",
+    "@endo/common": "^1.2.9",
+    "@endo/errors": "^1.2.9",
+    "@endo/eventual-send": "^1.3.0",
+    "@endo/far": "^1.1.10",
+    "@endo/init": "^1.1.8",
+    "@endo/marshal": "^1.6.3",
+    "@endo/nat": "^5.0.14",
+    "@endo/pass-style": "^1.4.8",
+    "@endo/patterns": "^1.4.8",
+    "@endo/promise-kit": "^1.1.9",
     "@nick134-bit/noblejs": "0.0.2",
     "bech32": "^2.0.0",
     "commander": "^12.1.0",
@@ -75,5 +82,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "ef71cfdc9e62572cab9a3d2821dc446ce0d700c3"
+  "gitHead": "5428c4da67b53cef7ff53ba7b2a28cf6ec8f643a"
 }

package/src/add-operators.core.js

@@ -0,0 +1,63 @@
+import { makeTracer } from '@agoric/internal';
+import { inviteOracles } from './utils/core-eval.js';
+
+/**
+ * @import {ManifestBundleRef} from '@agoric/deploy-script-support/src/externalTypes.js'
+ * @import {BootstrapManifest} from '@agoric/vats/src/core/lib-boot.js'
+ * @import {LegibleCapData} from './utils/config-marshal.js'
+ * @import {FastUSDCConfig} from './types.js'
+ * @import {FastUSDCCorePowers, FastUSDCKit} from './start-fast-usdc.core.js';
+ */
+
+const trace = makeTracer('FUSD-AddOperators', true);
+
+/**
+ * @throws if oracle smart wallets are not yet provisioned
+ *
+ * @param {BootstrapPowers & FastUSDCCorePowers } powers
+ * @param {{ options: LegibleCapData<FastUSDCConfig> }} config
+ */
+export const addOperators = async (
+  { consume: { namesByAddress, fastUsdcKit } },
+  config,
+) => {
+  trace(addOperators.name);
+
+  const kit = await fastUsdcKit;
+
+  const { creatorFacet } = kit;
+
+  trace(config);
+
+  // @ts-expect-error XXX LegibleCapData typedef
+  const { oracles } = config.options.structure;
+
+  await inviteOracles({ creatorFacet, namesByAddress }, oracles);
+};
+harden(addOperators);
+
+/**
+ * @param {{
+ *   restoreRef: (b: ERef<ManifestBundleRef>) => Promise<Installation>;
+ * }} utils
+ * @param {{
+ *   options: LegibleCapData<FastUSDCConfig>;
+ * }} param1
+ */
+export const getManifestForAddOperators = ({ restoreRef: _ }, { options }) => {
+  return {
+    /** @type {BootstrapManifest} */
+    manifest: {
+      [addOperators.name]: {
+        consume: {
+          fastUsdcKit: true,
+
+          // widely shared: name services
+          agoricNames: true,
+          namesByAddress: true,
+        },
+      },
+    },
+    options,
+  };
+};

package/src/cli/config.js

@@ -23,7 +23,7 @@ import { stdin as input, stdout as output } from 'node:process';
   }} ConfigOpts
  */
 
-/** @import { File } from './util/file.js' */
+/** @import { File } from './util/file' */
 
 export const init = async (
   /** @type {File} */ configFile,

package/src/cli/lp-commands.js

@@ -18,7 +18,7 @@ import {
   floorDivideBy,
   multiplyBy,
   parseRatio,
-} from '@agoric/ertp/src/ratio.js';
+} from '@agoric/zoe/src/contractSupport/ratio.js';
 import { InvalidArgumentError } from 'commander';
 import { outputActionAndHint } from './bridge-action.js';
 import { Offers } from '../clientSupport.js';
@@ -38,7 +38,7 @@ const parseDecimal = arg => {
 
 /**
  * @param {string} amountString
- * @param {Brand<'nat'>} usdc
+ * @param {Brand} usdc
  */
 const parseUSDCAmount = (amountString, usdc) => {
   const USDC_DECIMALS = 6;

package/src/cli/operator-commands.js

@@ -3,6 +3,7 @@
  * @import {Command} from 'commander';
  * @import {OfferSpec} from '@agoric/smart-wallet/src/offers.js';
  * @import {ExecuteOfferAction} from '@agoric/smart-wallet/src/smartWallet.js';
+ * @import {OperatorKit} from '../exos/operator-kit.js';
  */
 
 import {
@@ -12,7 +13,7 @@ import {
 import { mustMatch } from '@agoric/internal';
 import { Nat } from '@endo/nat';
 import { InvalidArgumentError } from 'commander';
-import { INVITATION_MAKERS_DESC } from '../operator-kit-interface.js';
+import { INVITATION_MAKERS_DESC } from '../exos/transaction-feed.js';
 import { CctpTxEvidenceShape } from '../type-guards.js';
 import { outputActionAndHint } from './bridge-action.js';
 
@@ -127,7 +128,9 @@ export const addOperatorCommands = (
         invitationSpec: {
           source: 'continuing',
           previousOffer: previousOfferId,
+          /** @type {string & keyof OperatorKit['invitationMakers'] } */
           invitationMakerName: 'SubmitEvidence',
+          /** @type {Parameters<OperatorKit['invitationMakers']['SubmitEvidence']> } */
           invitationArgs: [evidence],
         },
         proposal: {},

package/src/cli/transfer.js

@@ -16,7 +16,7 @@ import {
 } from './util/noble.js';
 import { queryUSDCBalance } from './util/bank.js';
 
-/** @import { File } from './util/file.js' */
+/** @import { File } from './util/file' */
 /** @import { VStorage } from '@agoric/client-utils' */
 /** @import { SigningStargateClient } from '@cosmjs/stargate' */
 /** @import { JsonRpcProvider as ethProvider } from 'ethers' */
@@ -34,7 +34,7 @@ const transfer = async (
   setTimeout = globalThis.setTimeout,
 ) => {
   const execute = async (
-    /** @type {import('./config.js').ConfigOpts} */ config,
+    /** @type {import('./config').ConfigOpts} */ config,
   ) => {
     const netConfig = await fetchEnvNetworkConfig({ env, fetch });
     vstorage ||= makeVStorage(

package/src/constants.js

@@ -1,5 +1,5 @@
 /**
- * Status values for FastUSDC. Includes states for advancing and settling.
+ * Status values for FastUSDC.
  *
  * @enum {(typeof TxStatus)[keyof typeof TxStatus]}
  */
@@ -31,7 +31,7 @@ export const TerminalTxStatus = {
 };
 
 /**
- * Status values for the StatusManager while an advance is being processed.
+ * Status values for the StatusManager.
  *
  * @enum {(typeof PendingTxStatus)[keyof typeof PendingTxStatus]}
  */

package/src/distribute-fees.core.js

@@ -0,0 +1,93 @@
+/** @file core eval module to collect fees. */
+import { AmountMath } from '@agoric/ertp';
+import { floorMultiplyBy } from '@agoric/zoe/src/contractSupport/index.js';
+import { E } from '@endo/far';
+import { makeTracer } from '@agoric/internal';
+import { fromExternalConfig } from './utils/config-marshal.js';
+
+/**
+ * @import {DepositFacet} from '@agoric/ertp';
+ * @import {FastUSDCCorePowers} from '@agoric/fast-usdc/src/start-fast-usdc.core.js';
+ * @import {CopyRecord} from '@endo/pass-style'
+ * @import {BootstrapManifestPermit} from '@agoric/vats/src/core/lib-boot.js'
+ * @import {LegibleCapData} from './utils/config-marshal.js'
+ */
+
+/**
+ * @typedef {{ destinationAddress: string } &
+ *  ({ feePortion: Ratio} | {fixedFees: Amount<'nat'>}) &
+ *  CopyRecord
+ * } FeeDistributionTerms
+ */
+
+const kwUSDC = 'USDC'; // keyword in AmountKeywordRecord
+const issUSDC = 'USDC'; // issuer name
+
+const trace = makeTracer('FUCF', true);
+
+/**
+ * @param {BootstrapPowers & FastUSDCCorePowers } permittedPowers
+ * @param {{ options: LegibleCapData<{ feeTerms: FeeDistributionTerms}> }} config
+ */
+export const distributeFees = async (permittedPowers, config) => {
+  trace('distributeFees...', config.options);
+
+  const { agoricNames, namesByAddress, zoe } = permittedPowers.consume;
+  /** @type {Brand<'nat'>} */
+  const usdcBrand = await E(agoricNames).lookup('brand', issUSDC);
+  /** @type {{ feeTerms: FeeDistributionTerms}} */
+  const { feeTerms: terms } = fromExternalConfig(config.options, {
+    USDC: usdcBrand,
+  });
+
+  const { creatorFacet } = await permittedPowers.consume.fastUsdcKit;
+  const want = {
+    [kwUSDC]: await ('fixedFees' in terms
+      ? terms.fixedFees
+      : E(creatorFacet)
+          .getContractFeeBalance()
+          .then(balance => floorMultiplyBy(balance, terms.feePortion))),
+  };
+  const proposal = harden({ want });
+
+  /** @type {DepositFacet} */
+  const depositFacet = await E(namesByAddress).lookup(
+    terms.destinationAddress,
+    'depositFacet',
+  );
+  trace('to:', terms.destinationAddress, depositFacet);
+
+  const toWithdraw = await E(creatorFacet).makeWithdrawFeesInvitation();
+  trace('invitation:', toWithdraw, 'proposal:', proposal);
+  const seat = E(zoe).offer(toWithdraw, proposal);
+  const result = await E(seat).getOfferResult();
+  trace('offer result', result);
+  const payout = await E(seat).getPayout(kwUSDC);
+  /** @type {Amount<'nat'>} */
+  // @ts-expect-error USDC is a nat brand
+  const rxd = await E(depositFacet).receive(payout);
+  trace('received', rxd);
+  if (!AmountMath.isGTE(rxd, proposal.want[kwUSDC])) {
+    trace('🚨 expected', proposal.want[kwUSDC], 'got', rxd);
+  }
+  trace('done');
+};
+harden(distributeFees);
+
+/** @satisfies {BootstrapManifestPermit} */
+const permit = {
+  consume: {
+    fastUsdcKit: true,
+    agoricNames: true,
+    namesByAddress: true,
+    zoe: true,
+  },
+};
+
+/**
+ * @param {unknown} _utils
+ * @param {Parameters<typeof distributeFees>[1]} config
+ */
+export const getManifestForDistributeFees = (_utils, { options }) => {
+  return { manifest: { [distributeFees.name]: permit }, options };
+};