feat: advancer with fees

0xpatrickdev · 0xpatrickdev · commit 06ca4dd1570e · 2024-11-15T12:25:28.000-05:00
diff --git a/packages/fast-usdc/src/exos/advancer.js b/packages/fast-usdc/src/exos/advancer.js
@@ -8,6 +8,7 @@ import { E } from '@endo/far';
 import { M } from '@endo/patterns';
 import { CctpTxEvidenceShape, EudParamShape } from '../typeGuards.js';
 import { addressTools } from '../utils/address.js';
+import { makeFeeTools } from '../utils/fees.js';
 
 const { isGTE } = AmountMath;
 
@@ -17,7 +18,7 @@ const { isGTE } = AmountMath;
  * @import {ChainAddress, ChainHub, Denom, DenomAmount, OrchestrationAccount} from '@agoric/orchestration';
  * @import {VowTools} from '@agoric/vow';
  * @import {Zone} from '@agoric/zone';
- * @import {CctpTxEvidence, LogFn} from '../types.js';
+ * @import {CctpTxEvidence, FeeConfig, LogFn} from '../types.js';
  * @import {StatusManager} from './status-manager.js';
  */
 
@@ -34,6 +35,7 @@ const { isGTE } = AmountMath;
 /**
  * @typedef {{
  *  chainHub: ChainHub;
+ *  feeConfig: FeeConfig;
  *  log: LogFn;
  *  statusManager: StatusManager;
  *  usdc: { brand: Brand<'nat'>; denom: Denom; };
@@ -75,15 +77,16 @@ const AdvancerKitI = harden({
  */
 export const prepareAdvancerKit = (
   zone,
-  { chainHub, log, statusManager, usdc, vowTools: { watch, when } },
+  { chainHub, feeConfig, log, statusManager, usdc, vowTools: { watch, when } },
 ) => {
   assertAllDefined({
     chainHub,
+    feeConfig,
     statusManager,
     watch,
     when,
   });
-
+  const feeTools = makeFeeTools(usdc.brand, feeConfig);
   /** @param {bigint} value */
   const toAmount = value => AmountMath.make(usdc.brand, value);
 
@@ -123,14 +126,17 @@ export const prepareAdvancerKit = (
             // this will throw if the bech32 prefix is not found, but is handled by the catch
             const destination = chainHub.makeChainAddress(EUD);
             const requestedAmount = toAmount(evidence.tx.amount);
+            const advanceAmount = feeTools.calculateAdvance(requestedAmount);
 
             // TODO: consider skipping and using `borrow()`s internal balance check
             const poolBalance = assetManagerFacet.lookupBalance();
             if (!isGTE(poolBalance, requestedAmount)) {
               log(
                 `Insufficient pool funds`,
-                `Requested ${q(requestedAmount)} but only have ${q(poolBalance)}`,
+                `Requested ${q(advanceAmount)} but only have ${q(poolBalance)}`,
               );
+              // report `requestedAmount`, not `advancedAmount`... do we need to
+              // communicate net to `StatusManger` in case fees change in between?
               statusManager.observe(evidence);
               return;
             }
@@ -147,7 +153,7 @@ export const prepareAdvancerKit = (
             }
 
             try {
-              const payment = await assetManagerFacet.borrow(requestedAmount);
+              const payment = await assetManagerFacet.borrow(advanceAmount);
               const depositV = E(poolAccount).deposit(payment);
               void watch(depositV, this.facets.depositHandler, {
                 destination,
diff --git a/packages/fast-usdc/src/fast-usdc.contract.js b/packages/fast-usdc/src/fast-usdc.contract.js
@@ -1,17 +1,17 @@
 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 { M, mustMatch } 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 { FeeConfigShape } from './typeGuards.js';
 
 const trace = makeTracer('FastUsdc');
 
@@ -20,21 +20,17 @@ const trace = makeTracer('FastUsdc');
  * @import {OrchestrationPowers, OrchestrationTools} from '@agoric/orchestration/src/utils/start-helper.js';
  * @import {Zone} from '@agoric/zone';
  * @import {OperatorKit} from './exos/operator-kit.js';
- * @import {CctpTxEvidence} from './types.js';
+ * @import {CctpTxEvidence, FeeConfig} from './types.js';
  */
 
 /**
  * @typedef {{
- *   poolFee: Amount<'nat'>;
- *   contractFee: Amount<'nat'>;
  *   usdcDenom: Denom;
  * }} FastUsdcTerms
  */
-const NatAmountShape = { brand: BrandShape, value: M.nat() };
+
 export const meta = {
   customTermsShape: {
-    contractFee: NatAmountShape,
-    poolFee: NatAmountShape,
     usdcDenom: M.string(),
   },
 };
@@ -44,6 +40,7 @@ harden(meta);
  * @param {ZCF<FastUsdcTerms>} zcf
  * @param {OrchestrationPowers & {
  *   marshaller: Marshaller;
+ *   feeConfig: FeeConfig;
  * }} privateArgs
  * @param {Zone} zone
  * @param {OrchestrationTools} tools
@@ -53,6 +50,7 @@ export const contract = async (zcf, privateArgs, zone, tools) => {
   const terms = zcf.getTerms();
   assert('USDC' in terms.brands, 'no USDC brand');
   assert('usdcDenom' in terms, 'no usdcDenom');
+  mustMatch(privateArgs.feeConfig, FeeConfigShape, 'must provide feeConfig');
 
   const { makeRecorderKit } = prepareRecorderKitMakers(
     zone.mapStore('vstorage'),
@@ -64,6 +62,7 @@ export const contract = async (zcf, privateArgs, zone, tools) => {
   const { chainHub, vowTools } = tools;
   const makeAdvancer = prepareAdvancer(zone, {
     chainHub,
+    feeConfig: privateArgs.feeConfig,
     log: trace,
     usdc: harden({
       brand: terms.brands.USDC,
diff --git a/packages/fast-usdc/src/typeGuards.js b/packages/fast-usdc/src/typeGuards.js
@@ -1,9 +1,10 @@
 import { M } from '@endo/patterns';
+import { BrandShape, RatioShape } from '@agoric/ertp';
 import { PendingTxStatus } from './constants.js';
 
 /**
  * @import {TypedPattern} from '@agoric/internal';
- * @import {CctpTxEvidence, PendingTx} from './types.js';
+ * @import {CctpTxEvidence, FeeConfig, PendingTx} from './types.js';
  */
 
 /** @type {TypedPattern<string>} */
@@ -42,3 +43,13 @@ export const EudParamShape = {
   EUD: M.string(),
 };
 harden(EudParamShape);
+
+const NatAmountShape = { brand: BrandShape, value: M.nat() };
+/** @type {TypedPattern<FeeConfig>} */
+export const FeeConfigShape = {
+  flat: NatAmountShape,
+  variableRate: RatioShape,
+  maxVariable: NatAmountShape,
+  contractRate: RatioShape,
+};
+harden(FeeConfigShape);
diff --git a/packages/fast-usdc/src/types.ts b/packages/fast-usdc/src/types.ts
@@ -35,4 +35,11 @@ export type PendingTxKey = `pendingTx:${string}`;
 /** internal key for `StatusManager` exo */
 export type SeenTxKey = `seenTx:${string}`;
 
+export type FeeConfig = {
+  flat: Amount<'nat'>;
+  variableRate: Ratio;
+  maxVariable: Amount<'nat'>;
+  contractRate: Ratio;
+};
+
 export type * from './constants.js';
diff --git a/packages/fast-usdc/src/utils/fees.js b/packages/fast-usdc/src/utils/fees.js
@@ -0,0 +1,61 @@
+import { AmountMath } from '@agoric/ertp';
+import { multiplyBy } from '@agoric/zoe/src/contractSupport/ratio.js';
+import { Fail } from '@endo/errors';
+import { mustMatch } from '@endo/patterns';
+import { FeeConfigShape } from '../typeGuards.js';
+
+const { add, subtract, isEqual, isGTE } = AmountMath;
+
+/**
+ * @import {Amount, Brand} from '@agoric/ertp';
+ * @import {FeeConfig} from '../types.js';
+ */
+
+/**
+ * @param {Brand} brand
+ * @param {FeeConfig} feeConfig
+ */
+export const makeFeeTools = (brand, feeConfig) => {
+  mustMatch(feeConfig, FeeConfigShape, 'Must provide feeConfig');
+  const { flat, variableRate, maxVariable } = feeConfig;
+  const emptyAmount = AmountMath.makeEmpty(brand);
+  return harden({
+    /**
+     * Calculate the net amount to advance after withholding fees.
+     *
+     * @param {Amount<'nat'>} requested
+     */
+    calculateAdvance(requested) {
+      const fee = this.calculateAdvanceFee(requested);
+      return subtract(requested, fee);
+    },
+    /**
+     * Calculate the total fee to charge for the advance.
+     *
+     * @param {Amount<'nat'>} requested must be greater than 0
+     */
+    calculateAdvanceFee(requested) {
+      !isEqual(requested, emptyAmount) || Fail`Fee exceeds requested.`;
+      const potentialVariable = multiplyBy(requested, variableRate);
+      const variable = isGTE(potentialVariable, maxVariable)
+        ? maxVariable
+        : potentialVariable;
+      const fee = add(variable, flat);
+      !isGTE(fee, requested) || Fail`Fee exceeds requested.`;
+      return fee;
+    },
+    /**
+     * Calculate the split of fees between pool and contract.
+     *
+     * @param {Amount<'nat'>} requested
+     * @returns {{ Principal: Amount<'nat'>, PoolFee: Amount<'nat'>, ContractFee: Amount<'nat'> }} AmountKeywordRecord
+     */
+    calculateSplit(requested) {
+      const fee = this.calculateAdvanceFee(requested);
+      const Principal = subtract(requested, fee);
+      const ContractFee = multiplyBy(fee, feeConfig.contractRate);
+      const PoolFee = subtract(fee, ContractFee);
+      return harden({ Principal, PoolFee, ContractFee });
+    },
+  });
+};
diff --git a/packages/fast-usdc/test/exos/advancer.test.ts b/packages/fast-usdc/test/exos/advancer.test.ts
@@ -13,7 +13,11 @@ import { prepareStatusManager } from '../../src/exos/status-manager.js';
 
 import { commonSetup } from '../supports.js';
 import { MockCctpTxEvidences } from '../fixtures.js';
-import { makeTestLogger, prepareMockOrchAccounts } from '../mocks.js';
+import {
+  makeTestFeeConfig,
+  makeTestLogger,
+  prepareMockOrchAccounts,
+} from '../mocks.js';
 
 const LOCAL_DENOM = `ibc/${denomHash({
   denom: 'uusdc',
@@ -46,8 +50,10 @@ const createTestExtensions = (t, common: CommonSetup) => {
     usdc,
   });
 
+  const feeConfig = makeTestFeeConfig(usdc);
   const makeAdvancer = prepareAdvancer(rootZone.subZone('advancer'), {
     chainHub,
+    feeConfig,
     log,
     statusManager,
     usdc: harden({
@@ -90,6 +96,7 @@ const createTestExtensions = (t, common: CommonSetup) => {
   return {
     constants: {
       localDenom: LOCAL_DENOM,
+      feeConfig,
     },
     helpers: {
       inspectLogs,
@@ -187,7 +194,7 @@ test('updates status to OBSERVED on insufficient pool funds', async t => {
 
   t.deepEqual(inspectLogs(0), [
     'Insufficient pool funds',
-    'Requested {"brand":"[Alleged: USDC brand]","value":"[200000000n]"} but only have {"brand":"[Alleged: USDC brand]","value":"[1n]"}',
+    'Requested {"brand":"[Alleged: USDC brand]","value":"[195000000n]"} but only have {"brand":"[Alleged: USDC brand]","value":"[1n]"}',
   ]);
 });
 
diff --git a/packages/fast-usdc/test/fast-usdc.contract.test.ts b/packages/fast-usdc/test/fast-usdc.contract.test.ts
@@ -51,8 +51,6 @@ const startContract = async (
     installation,
     { USDC: usdc.issuer },
     {
-      poolFee: usdc.make(1n),
-      contractFee: usdc.make(1n),
       usdcDenom: 'ibc/usdconagoric',
     },
     commonPrivateArgs,
@@ -243,8 +241,6 @@ test('baggage', async t => {
     installation,
     { USDC: usdc.issuer },
     {
-      poolFee: usdc.make(1n),
-      contractFee: usdc.make(1n),
       usdcDenom: 'ibc/usdconagoric',
     },
     commonPrivateArgs,
diff --git a/packages/fast-usdc/test/mocks.ts b/packages/fast-usdc/test/mocks.ts
@@ -6,7 +6,12 @@ import type {
 } from '@agoric/orchestration';
 import type { Zone } from '@agoric/zone';
 import type { VowTools } from '@agoric/vow';
-import type { LogFn } from '../src/types.js';
+import { makeRatio } from '@agoric/zoe/src/contractSupport/ratio.js';
+import type {
+  AmountUtils,
+  withAmountUtils,
+} from '@agoric/zoe/tools/test-utils.js';
+import type { FeeConfig, LogFn } from '../src/types.js';
 
 export const prepareMockOrchAccounts = (
   zone: Zone,
@@ -59,3 +64,11 @@ export const makeTestLogger = (logger: LogFn) => {
 };
 
 export type TestLogger = ReturnType<typeof makeTestLogger>;
+
+export const makeTestFeeConfig = (usdc: Omit<AmountUtils, 'mint'>): FeeConfig =>
+  harden({
+    flat: usdc.units(1),
+    variableRate: makeRatio(2n, usdc.brand, 100n, usdc.brand),
+    maxVariable: usdc.units(100),
+    contractRate: makeRatio(2n, usdc.brand, 10n, usdc.brand),
+  });
diff --git a/packages/fast-usdc/test/supports.ts b/packages/fast-usdc/test/supports.ts
@@ -28,6 +28,7 @@ import { makeHeapZone, type Zone } from '@agoric/zone';
 import { makeDurableZone } from '@agoric/zone/durable.js';
 import { E } from '@endo/far';
 import type { ExecutionContext } from 'ava';
+import { makeTestFeeConfig } from './mocks.js';
 
 export {
   makeFakeLocalchainBridge,
@@ -184,6 +185,7 @@ export const commonSetup = async (t: ExecutionContext<any>) => {
       storageNode: storage.rootNode,
       marshaller,
       timerService: timer,
+      feeConfig: makeTestFeeConfig(usdc),
     },
     facadeServices: {
       agoricNames,
diff --git a/packages/fast-usdc/test/utils/fees.test.ts b/packages/fast-usdc/test/utils/fees.test.ts
