@agoric/fast-usdc 0.1.1-other-dev-3eb1a1d.0 → 0.1.1-other-dev-fbe72e7.0.fbe72e7

package/src/clientSupport.js

@@ -0,0 +1,98 @@
+// @ts-check
+import { assertAllDefined } from '@agoric/internal';
+
+/**
+ * @import {USDCProposalShapes} from './pool-share-math.js';
+ */
+
+/**
+ * @param {Pick<
+ *   import('@agoric/vats/tools/board-utils.js').AgoricNamesRemotes,
+ *   'brand'
+ * >} agoricNames
+ * @param {object} opts
+ * @param {string} opts.offerId
+ * @param {bigint} opts.fastLPAmount
+ * @param {bigint} opts.usdcAmount
+ * @returns {import('@agoric/smart-wallet/src/offers.js').OfferSpec & {proposal: USDCProposalShapes['deposit']}}
+ */
+const makeDepositOffer = ({ brand }, { offerId, fastLPAmount, usdcAmount }) => {
+  assertAllDefined({ offerId, fastLPAmount, usdcAmount });
+
+  return {
+    id: offerId,
+    invitationSpec: {
+      source: 'agoricContract',
+      instancePath: ['fastUsdc'],
+      callPipe: [['makeDepositInvitation']],
+    },
+    /** @type {USDCProposalShapes['deposit']} */
+    // @ts-expect-error https://github.com/Agoric/agoric-sdk/issues/10491
+    proposal: {
+      give: {
+        USDC: {
+          brand: brand.USDC,
+          value: usdcAmount,
+        },
+      },
+      want: {
+        PoolShare: {
+          brand: brand.FastLP,
+          value: fastLPAmount,
+        },
+      },
+    },
+  };
+};
+
+/**
+ * @param {Pick<
+ *   import('@agoric/vats/tools/board-utils.js').AgoricNamesRemotes,
+ *   'brand'
+ * >} agoricNames
+ * @param {object} opts
+ * @param {string} opts.offerId
+ * @param {bigint} opts.fastLPAmount
+ * @param {bigint} opts.usdcAmount
+ * @returns {import('@agoric/smart-wallet/src/offers.js').OfferSpec}
+ */
+const makeWithdrawOffer = (
+  { brand },
+  { offerId, fastLPAmount, usdcAmount },
+) => ({
+  id: offerId,
+  invitationSpec: {
+    source: 'agoricContract',
+    instancePath: ['fastUsdc'],
+    callPipe: [['makeWithdrawInvitation']],
+  },
+  proposal: {
+    give: {
+      PoolShare: {
+        // @ts-expect-error https://github.com/Agoric/agoric-sdk/issues/10491
+        brand: brand.FastLP,
+        value: fastLPAmount,
+      },
+    },
+    want: {
+      USDC: {
+        // @ts-expect-error https://github.com/Agoric/agoric-sdk/issues/10491
+        brand: brand.USDC,
+        value: usdcAmount,
+      },
+    },
+  },
+});
+
+/**
+ * @satisfies {Record<
+ *   string,
+ *   Record<string, import('@agoric/smart-wallet/src/types.js').OfferMaker>
+ * >}
+ */
+export const Offers = {
+  fastUsdc: {
+    Deposit: makeDepositOffer,
+    Withdraw: makeWithdrawOffer,
+  },
+};

package/src/constants.js

@@ -1,5 +1,5 @@
 /**
- * Status values for FastUSDC.
+ * Status values for FastUSDC. Includes states for advancing and settling.
  *
  * @enum {(typeof TxStatus)[keyof typeof TxStatus]}
  */
@@ -7,21 +7,44 @@ export const TxStatus = /** @type {const} */ ({
   /** tx was observed but not advanced */
   Observed: 'OBSERVED',
   /** IBC transfer is initiated */
+  Advancing: 'ADVANCING',
+  /** IBC transfer is complete */
   Advanced: 'ADVANCED',
-  /** settlement for matching advance received and funds dispersed */
-  Settled: 'SETTLED',
+  /** IBC transfer failed (timed out) */
+  AdvanceFailed: 'ADVANCE_FAILED',
+  /** Advance skipped and waiting for forward */
+  AdvanceSkipped: 'ADVANCE_SKIPPED',
+  /** settlement for matching advance received and funds disbursed */
+  Disbursed: 'DISBURSED',
+  /** No route, forward not attempted */
+  ForwardedSkipped: 'FORWARD_SKIPPED',
+  /** fallback: do not collect fees */
+  Forwarded: 'FORWARDED',
+  /** failed to forward to EUD */
+  ForwardFailed: 'FORWARD_FAILED',
 });
 harden(TxStatus);
 
+// According to the state diagram
+export const TerminalTxStatus = {
+  [TxStatus.Forwarded]: true,
+  [TxStatus.ForwardFailed]: true,
+  [TxStatus.Disbursed]: true,
+};
+
 /**
- * Status values for the StatusManager.
+ * Status values for the StatusManager while an advance is being processed.
  *
  * @enum {(typeof PendingTxStatus)[keyof typeof PendingTxStatus]}
  */
 export const PendingTxStatus = /** @type {const} */ ({
-  /** tx was observed but not advanced */
-  Observed: 'OBSERVED',
   /** IBC transfer is initiated */
+  Advancing: 'ADVANCING',
+  /** IBC transfer failed (timed out) */
+  AdvanceFailed: 'ADVANCE_FAILED',
+  /** IBC transfer is complete */
   Advanced: 'ADVANCED',
+  /** Advance skipped and waiting for forward */
+  AdvanceSkipped: 'ADVANCE_SKIPPED',
 });
 harden(PendingTxStatus);

package/src/main.js

@@ -0,0 +1 @@
+export * from './types.js';

package/src/operator-kit-interface.js

@@ -0,0 +1,29 @@
+import { M } from '@endo/patterns';
+import { CctpTxEvidenceShape, RiskAssessmentShape } from './type-guards.js';
+
+/**
+ * @import {Zone} from '@agoric/zone';
+ * @import {CctpTxEvidence, RiskAssessment} from '@agoric/fast-usdc/src/types.js';
+ */
+
+/** Name in the invitation purse (keyed also by this contract instance) */
+export const INVITATION_MAKERS_DESC = 'oracle operator invitation';
+
+export const OperatorKitI = {
+  admin: M.interface('Admin', {
+    disable: M.call().returns(),
+  }),
+
+  invitationMakers: M.interface('InvitationMakers', {
+    SubmitEvidence: M.call(CctpTxEvidenceShape)
+      .optional(RiskAssessmentShape)
+      .returns(M.promise()),
+  }),
+
+  operator: M.interface('Operator', {
+    submitEvidence: M.call(CctpTxEvidenceShape)
+      .optional(RiskAssessmentShape)
+      .returns(),
+    getStatus: M.call().returns(M.record()),
+  }),
+};

package/src/pool-share-math.js

@@ -4,21 +4,23 @@ import {
   makeRatio,
   makeRatioFromAmounts,
   multiplyBy,
-} from '@agoric/zoe/src/contractSupport/ratio.js';
+} from '@agoric/ertp/src/ratio.js';
 import { Fail, q } from '@endo/errors';
 
-const { getValue, add, isEmpty, isEqual, isGTE, subtract } = AmountMath;
+const { keys } = Object;
+const { add, isEmpty, isEqual, isGTE, make, makeEmpty, subtract } = AmountMath;
 
 /**
- * @import {PoolStats} from './types';
- * @import {RepayAmountKWR} from './exos/liquidity-pool';
+ * @import {Amount, Brand, DepositFacet, NatValue, Payment, Ratio} from '@agoric/ertp';
+ * @import {Allocation} from '@agoric/zoe';
+ * @import {PoolStats} from './types.js';
+ * @import {RepayAmountKWR} from './utils/fees.js';
  */
 
 /**
  * Invariant: shareWorth is the pool balance divided by shares outstanding.
  *
- * Use `makeParity(make(USDC, epsilon), PoolShares)` for an initial
- * value, for some negligible `epsilon` such as 1n.
+ * Use `makeParity(USDC, PoolShares)` for an initial value.
  *
  * @typedef {Ratio} ShareWorth
  */
@@ -26,23 +28,26 @@ const { getValue, add, isEmpty, isEqual, isGTE, subtract } = AmountMath;
 /**
  * Make a 1-to-1 ratio between amounts of 2 brands.
  *
- * @param {Amount<'nat'>} numerator
+ * @param {Brand<'nat'>} numeratorBrand
  * @param {Brand<'nat'>} denominatorBrand
  */
-export const makeParity = (numerator, denominatorBrand) => {
-  const value = getValue(numerator.brand, numerator);
-  return makeRatio(value, numerator.brand, value, denominatorBrand);
+export const makeParity = (numeratorBrand, denominatorBrand) => {
+  const dust = 1n;
+  return makeRatio(dust, numeratorBrand, dust, denominatorBrand);
 };
 
 /**
  * @typedef {{
  *   deposit: {
  *     give: { USDC: Amount<'nat'> },
- *     want?: { PoolShare: Amount<'nat'> }
+ *     want: { PoolShare: Amount<'nat'> }
  *   },
  *   withdraw: {
  *     give: { PoolShare: Amount<'nat'> }
  *     want: { USDC: Amount<'nat'> },
+ *   },
+ *   withdrawFees: {
+ *     want: { USDC: Amount<'nat'> }
  *   }
  * }} USDCProposalShapes
  */
@@ -91,14 +96,54 @@ export const depositCalc = (shareWorth, { give, want }) => {
   });
 };
 
+/**
+ * Verifies that the total pool balance (unencumbered + encumbered) matches the
+ * shareWorth numerator. The total pool balance consists of:
+ * 1. unencumbered balance - USDC available in the pool for borrowing
+ * 2. encumbered balance - USDC currently lent out
+ *
+ * A negligible `dust` amount is used to initialize shareWorth with a non-zero
+ * denominator. It must remain in the pool at all times.
+ *
+ * @param {Allocation} poolAlloc
+ * @param {ShareWorth} shareWorth
+ * @param {Amount<'nat'>} encumberedBalance
+ */
+export const checkPoolBalance = (poolAlloc, shareWorth, encumberedBalance) => {
+  const { brand: usdcBrand } = encumberedBalance;
+  const unencumberedBalance = poolAlloc.USDC || makeEmpty(usdcBrand);
+  const kwds = keys(poolAlloc);
+  kwds.length === 0 ||
+    (kwds.length === 1 && kwds[0] === 'USDC') ||
+    Fail`unexpected pool allocations: ${poolAlloc}`;
+  const dust = make(usdcBrand, 1n);
+  const grossBalance = add(add(unencumberedBalance, dust), encumberedBalance);
+  isEqual(grossBalance, shareWorth.numerator) ||
+    Fail`🚨 pool balance ${q(unencumberedBalance)} and encumbered balance ${q(encumberedBalance)} inconsistent with shareWorth ${q(shareWorth)}`;
+  return harden({ unencumberedBalance, grossBalance });
+};
+
 /**
  * Compute payout from a withdraw proposal, along with updated shareWorth
  *
  * @param {ShareWorth} shareWorth
  * @param {USDCProposalShapes['withdraw']} proposal
+ * @param {Allocation} poolAlloc
+ * @param {Amount<'nat'>} [encumberedBalance]
  * @returns {{ shareWorth: ShareWorth, payouts: { USDC: Amount<'nat'> }}}
  */
-export const withdrawCalc = (shareWorth, { give, want }) => {
+export const withdrawCalc = (
+  shareWorth,
+  { give, want },
+  poolAlloc,
+  encumberedBalance = makeEmpty(shareWorth.numerator.brand),
+) => {
+  const { unencumberedBalance } = checkPoolBalance(
+    poolAlloc,
+    shareWorth,
+    encumberedBalance,
+  );
+
   assert(!isEmpty(give.PoolShare));
   assert(!isEmpty(want.USDC));
 
@@ -108,6 +153,8 @@ export const withdrawCalc = (shareWorth, { give, want }) => {
   const { denominator: sharesOutstanding, numerator: poolBalance } = shareWorth;
   !isGTE(want.USDC, poolBalance) ||
     Fail`cannot withdraw ${q(want.USDC)}; only ${q(poolBalance)} in pool`;
+  isGTE(unencumberedBalance, want.USDC) ||
+    Fail`cannot withdraw ${q(want.USDC)}; ${q(encumberedBalance)} is in use; stand by for pool to return to ${q(poolBalance)}`;
   const balancePost = subtract(poolBalance, payout);
   // giving more shares than are outstanding is impossible,
   // so it's not worth a custom diagnostic. subtract will fail
@@ -155,35 +202,26 @@ export const borrowCalc = (
 
 /**
  * @param {ShareWorth} shareWorth
- * @param {Allocation} fromSeatAllocation
- * @param {RepayAmountKWR} amounts
+ * @param {RepayAmountKWR} split
  * @param {Amount<'nat'>} encumberedBalance aka 'outstanding borrows'
  * @param {PoolStats} poolStats
- * @throws {Error} if allocations do not match amounts or Principal exceeds encumberedBalance
+ * @throws {Error} if Principal exceeds encumberedBalance
  */
-export const repayCalc = (
-  shareWorth,
-  fromSeatAllocation,
-  amounts,
-  encumberedBalance,
-  poolStats,
-) => {
-  (isEqual(fromSeatAllocation.Principal, amounts.Principal) &&
-    isEqual(fromSeatAllocation.PoolFee, amounts.PoolFee) &&
-    isEqual(fromSeatAllocation.ContractFee, amounts.ContractFee)) ||
-    Fail`Cannot repay. From seat allocation ${q(fromSeatAllocation)} does not equal amounts ${q(amounts)}.`;
-
-  isGTE(encumberedBalance, amounts.Principal) ||
-    Fail`Cannot repay. Principal ${q(amounts.Principal)} exceeds encumberedBalance ${q(encumberedBalance)}.`;
+export const repayCalc = (shareWorth, split, encumberedBalance, poolStats) => {
+  isGTE(encumberedBalance, split.Principal) ||
+    Fail`Cannot repay. Principal ${q(split.Principal)} exceeds encumberedBalance ${q(encumberedBalance)}.`;
 
   return harden({
-    shareWorth: withFees(shareWorth, amounts.PoolFee),
-    encumberedBalance: subtract(encumberedBalance, amounts.Principal),
+    shareWorth: withFees(shareWorth, split.PoolFee),
+    encumberedBalance: subtract(encumberedBalance, split.Principal),
     poolStats: {
       ...poolStats,
-      totalRepays: add(poolStats.totalRepays, amounts.Principal),
-      totalPoolFees: add(poolStats.totalPoolFees, amounts.PoolFee),
-      totalContractFees: add(poolStats.totalContractFees, amounts.ContractFee),
+      totalRepays: add(poolStats.totalRepays, split.Principal),
+      totalPoolFees: add(poolStats.totalPoolFees, split.PoolFee),
+      totalContractFees: add(
+        add(poolStats.totalContractFees, split.ContractFee),
+        split.RelayFee,
+      ),
     },
   });
 };

package/src/type-guards.js

@@ -1,16 +1,21 @@
 import { AmountShape, BrandShape, RatioShape } from '@agoric/ertp';
 import { M } from '@endo/patterns';
+import {
+  DenomDetailShape,
+  DenomShape,
+} from '@agoric/orchestration/src/typeGuards.js';
 import { PendingTxStatus } from './constants.js';
 
 /**
+ * @import {Amount, Brand, NatValue, Payment} from '@agoric/ertp';
  * @import {TypedPattern} from '@agoric/internal';
- * @import {FastUsdcTerms} from './fast-usdc.contract.js';
+ * @import {CosmosChainInfo, Denom, DenomDetail, OrchestrationAccount, IBCConnectionInfo, CaipChainId} from '@agoric/orchestration';
  * @import {USDCProposalShapes} from './pool-share-math.js';
- * @import {CctpTxEvidence, FeeConfig, PendingTx, PoolMetrics, ChainPolicy, FeedPolicy} from './types.js';
+ * @import {CctpTxEvidence, FastUSDCConfig, FastUsdcTerms, FeeConfig, PendingTx, PoolMetrics, ChainPolicy, FeedPolicy, AddressHook, EvmAddress, EvmHash, RiskAssessment, EvidenceWithRisk} from './types.js';
  */
 
 /**
- * @param {Brand} brand must be a 'nat' brand, not checked
+ * @param {Brand<'nat'>} brand must be a 'nat' brand, not checked
  * @param {NatValue} [min]
  */
 export const makeNatAmountShape = (brand, min) =>
@@ -19,16 +24,20 @@ export const makeNatAmountShape = (brand, min) =>
 /** @param {Record<'PoolShares' | 'USDC', Brand<'nat'>>} brands */
 export const makeProposalShapes = ({ PoolShares, USDC }) => {
   /** @type {TypedPattern<USDCProposalShapes['deposit']>} */
-  const deposit = M.splitRecord(
-    { give: { USDC: makeNatAmountShape(USDC, 1n) } },
-    { want: { PoolShare: makeNatAmountShape(PoolShares) } },
-  );
+  const deposit = M.splitRecord({
+    give: { USDC: makeNatAmountShape(USDC, 1n) },
+    want: { PoolShare: makeNatAmountShape(PoolShares) },
+  });
   /** @type {TypedPattern<USDCProposalShapes['withdraw']>} */
   const withdraw = M.splitRecord({
     give: { PoolShare: makeNatAmountShape(PoolShares, 1n) },
     want: { USDC: makeNatAmountShape(USDC, 1n) },
   });
-  return harden({ deposit, withdraw });
+  /** @type {TypedPattern<USDCProposalShapes['withdrawFees']>} */
+  const withdrawFees = M.splitRecord({
+    want: { USDC: makeNatAmountShape(USDC, 1n) },
+  });
+  return harden({ deposit, withdraw, withdrawFees });
 };
 
 /** @type {TypedPattern<FastUsdcTerms>} */
@@ -36,12 +45,28 @@ export const FastUSDCTermsShape = harden({
   usdcDenom: M.string(),
 });
 
-/** @type {TypedPattern<string>} */
+/** @type {TypedPattern<EvmAddress>} */
+export const EvmAddressShape = M.string({
+  // 0x + 40 hex digits
+  stringLengthLimit: 42,
+});
+harden(EvmAddressShape);
+
+/** @type {TypedPattern<EvmHash>} */
 export const EvmHashShape = M.string({
   stringLengthLimit: 66,
 });
 harden(EvmHashShape);
 
+/** @type {TypedPattern<RiskAssessment>} */
+export const RiskAssessmentShape = M.splitRecord(
+  {},
+  {
+    risksIdentified: M.arrayOf(M.string()),
+  },
+);
+harden(RiskAssessmentShape);
+
 /** @type {TypedPattern<CctpTxEvidence>} */
 export const CctpTxEvidenceShape = {
   aux: {
@@ -49,17 +74,25 @@ export const CctpTxEvidenceShape = {
     recipientAddress: M.string(),
   },
   blockHash: EvmHashShape,
-  blockNumber: M.bigint(),
-  blockTimestamp: M.bigint(),
+  blockNumber: M.nat(),
+  blockTimestamp: M.nat(),
   chainId: M.number(),
   tx: {
-    amount: M.bigint(),
+    amount: M.nat(),
     forwardingAddress: M.string(),
+    sender: EvmAddressShape,
   },
   txHash: EvmHashShape,
 };
 harden(CctpTxEvidenceShape);
 
+/** @type {TypedPattern<EvidenceWithRisk>} */
+export const EvidenceWithRiskShape = {
+  evidence: CctpTxEvidenceShape,
+  risk: RiskAssessmentShape,
+};
+harden(EvidenceWithRiskShape);
+
 /** @type {TypedPattern<PendingTx>} */
 // @ts-expect-error TypedPattern not recognized as record
 export const PendingTxShape = {
@@ -68,20 +101,42 @@ export const PendingTxShape = {
 };
 harden(PendingTxShape);
 
-export const EudParamShape = {
-  EUD: M.string(),
+/** @type {TypedPattern<AddressHook>} */
+export const AddressHookShape = {
+  baseAddress: M.string(),
+  query: { EUD: M.string() },
 };
-harden(EudParamShape);
+harden(AddressHookShape);
 
 const NatAmountShape = { brand: BrandShape, value: M.nat() };
+
+/** @type {TypedPattern<FeeConfig['destinationOverrides']>} */
+export const DestinationOverridesShape = M.recordOf(
+  M.string(),
+  M.splitRecord(
+    {},
+    {
+      flat: NatAmountShape,
+      variableRate: RatioShape,
+      contractRate: RatioShape,
+      relay: NatAmountShape,
+    },
+  ),
+);
+
 /** @type {TypedPattern<FeeConfig>} */
-export const FeeConfigShape = {
-  flat: NatAmountShape,
-  variableRate: RatioShape,
-  maxVariable: NatAmountShape,
-  contractRate: RatioShape,
-};
-harden(FeeConfigShape);
+export const FeeConfigShape = M.splitRecord(
+  {
+    flat: NatAmountShape,
+    variableRate: RatioShape,
+    contractRate: RatioShape,
+  },
+  {
+    relay: NatAmountShape,
+    destinationOverrides: DestinationOverridesShape,
+  },
+  {},
+);
 
 /** @type {TypedPattern<PoolMetrics>} */
 export const PoolMetricsShape = {
@@ -95,29 +150,62 @@ export const PoolMetricsShape = {
 harden(PoolMetricsShape);
 
 /** @type {TypedPattern<ChainPolicy>} */
-export const ChainPoliciesShape = M.splitRecord(
-  {
-    nobleContractAddress: EvmHashShape,
-    cctpTokenMessengerAddress: EvmHashShape,
-    confirmations: M.number(),
-    chainId: M.number(),
+export const ChainPolicyShape = {
+  attenuatedCttpBridgeAddresses: M.splitArray(
+    [EvmHashShape],
+    undefined,
+    M.arrayOf(EvmHashShape),
+  ),
+  cctpTokenMessengerAddress: EvmHashShape,
+  confirmations: M.number(),
+  chainId: M.number(),
+  rateLimits: {
+    tx: M.bigint(),
+    blockWindow: M.bigint(),
+    blockWindowSize: M.number(),
   },
-  { chainType: M.number() },
-);
-harden(ChainPoliciesShape);
+};
+harden(ChainPolicyShape);
 
 /**
  * @type {TypedPattern<FeedPolicy>}
  *
- * Should be JSON serializable so CLI can specify policy. E.g. no bigint,
- * undefined, remotable, etc.
+ * must be CopyData; no Brands or other Remotables
  */
 export const FeedPolicyShape = M.splitRecord(
   {
     nobleDomainId: M.number(),
     nobleAgoricChannelId: M.string(),
-    chainPolicies: M.recordOf(M.string(), ChainPoliciesShape),
+    chainPolicies: M.recordOf(M.string(), ChainPolicyShape),
   },
   { eventFilter: M.string() },
 );
 harden(FeedPolicyShape);
+
+/**
+ * The version of CosmosChainInfoShape that matches the `valueShape` used in FUSDC's ChainHub's `chainInfos` mapStore.
+ * @type {TypedPattern<CosmosChainInfo>}
+ */
+export const CosmosChainInfoShapeV1 = M.splitRecord(
+  {
+    chainId: M.string(),
+  },
+  {
+    bech32Prefix: M.string(),
+    connections: M.record(),
+    stakingTokens: M.arrayOf({ denom: M.string() }),
+    // UNTIL https://github.com/Agoric/agoric-sdk/issues/9326
+    icqEnabled: M.boolean(),
+    pfmEnabled: M.boolean(),
+  },
+);
+
+/** @type {TypedPattern<FastUSDCConfig>} */
+export const FastUSDCConfigShape = M.splitRecord({
+  terms: FastUSDCTermsShape,
+  oracles: M.recordOf(M.string(), M.string()),
+  feeConfig: FeeConfigShape,
+  feedPolicy: FeedPolicyShape,
+  chainInfo: M.recordOf(M.string(), CosmosChainInfoShapeV1),
+  assetInfo: M.arrayOf([DenomShape, DenomDetailShape]),
+});