feat(portfolio-contract): include FlowDetail (esp. type) in StatusFor['flow'] (#12178)

refs:
 - https://github.com/Agoric/agoric-private/issues/507

## Description

once a flow is done or failed, there was no way to see in vstorage whether it was a ‘withdraw’, ‘deposit’, or ‘rebalance’ (without tracing history)

### Scaling Considerations

a small increase in vstorage IAVL usage

### Documentation / Testing Considerations

types, snapshots as usual

### Upgrade / Security Considerations

no exo state changes. `ymaxControl.upgrade(...)` compatible.

Only optional fields are added to shapes. This adds a gap when used as `TypedPattern<T>`: runtime validation might pass without satisfying the static type.

Author: mergify[bot]

packages/portfolio-api/src/types.ts

@@ -144,7 +144,7 @@ export type StatusFor = {
     totalIn: NatAmount;
     totalOut: NatAmount;
   };
-  flow: FlowStatus;
+  flow: FlowStatus & FlowDetail;
   flowSteps: FlowStep[];
   flowOrder: FundsFlowPlan['order'];
 };

packages/portfolio-api/test/types.test-d.ts

@@ -147,7 +147,7 @@ const status: StatusFor = {
     totalIn: natAmount,
     totalOut: natAmount,
   },
-  flow: { state: 'done' },
+  flow: { state: 'done', type: 'rebalance' },
   flowSteps,
   flowOrder: [
     [4, [2, 3]],

packages/portfolio-contract/src/portfolio.flows.ts

@@ -183,6 +183,7 @@ const trackFlow = async (
   traceFlow: TraceLogger,
   accounts: AccountsByChain,
   order: Job['order'],
+  detail: FlowDetail,
 ) => {
   const runTask = async (ix: number, running: number[]) => {
     // steps are 1-based. the scheduler is 0-based
@@ -195,6 +196,7 @@ const trackFlow = async (
       steps,
       step: min(...steps),
       how: moves[min(...running)].how,
+      ...detail,
     });
     await null;
     try {
@@ -235,11 +237,15 @@ const trackFlow = async (
       return errs;
     }, undefined);
     assert(reasons); // guaranteed by results.some(...) above
-    reporter.publishFlowStatus(flowId, { state: 'fail', ...reasons });
+    reporter.publishFlowStatus(flowId, {
+      state: 'fail',
+      ...reasons,
+      ...detail,
+    });
     throw results;
   }
 
-  reporter.publishFlowStatus(flowId, { state: 'done' });
+  reporter.publishFlowStatus(flowId, { state: 'done', ...detail });
 };
 
 export const provideCosmosAccount = async <C extends 'agoric' | 'noble'>(
@@ -437,6 +443,7 @@ const stepFlow = async (
   kit: GuestInterface<PortfolioKit>,
   traceP: TraceLogger,
   flowId: number,
+  flowDetail: FlowDetail,
 ) => {
   const todo: AssetMovement[] = [];
 
@@ -711,6 +718,7 @@ const stepFlow = async (
     state: 'run',
     step: 0,
     how: `makeAccounts(${acctsToDo.join(', ')})`,
+    ...flowDetail,
   });
   reporter.publishFlowSteps(
     flowId,
@@ -736,6 +744,7 @@ const stepFlow = async (
         step: 0,
         how: `makeAccount: ${chain}`,
         error: err && typeof err === 'object' ? err.message : `${err}`,
+        ...flowDetail,
       });
       throw err;
     }
@@ -787,7 +796,15 @@ const stepFlow = async (
   };
   traceFlow('accounts for trackFlow', keys(accounts));
 
-  await trackFlow(reporter, todo, flowId, traceFlow, accounts, order);
+  await trackFlow(
+    reporter,
+    todo,
+    flowId,
+    traceFlow,
+    accounts,
+    order,
+    flowDetail,
+  );
   traceFlow('stepFlow done');
 };
 
@@ -840,7 +857,9 @@ export const rebalance = (async (
     if (flow) {
       ({ flowId } =
         startedFlow ?? kit.manager.startFlow({ type: 'rebalance' }, flow));
-      await stepFlow(orch, ctx, seat, flow, kit, traceP, flowId);
+      await stepFlow(orch, ctx, seat, flow, kit, traceP, flowId, {
+        type: 'rebalance',
+      });
     }
 
     if (!seat.hasExited()) {
@@ -1153,7 +1172,7 @@ export const executePlan = (async (
     MovementDesc[] | FundsFlowPlan
   >); // XXX Guest/Host types UNTIL #9822
   try {
-    await stepFlow(orch, ctx, seat, plan, pKit, traceP, flowId);
+    await stepFlow(orch, ctx, seat, plan, pKit, traceP, flowId, flowDetail);
     return `flow${flowId}`;
   } finally {
     // The seat must be exited no matter what to avoid leaks

packages/portfolio-contract/src/type-guards.ts

@@ -307,16 +307,25 @@ export const makeFlowStepsPath = (
   prop: 'steps' | 'order' = 'steps',
 ) => [`portfolio${parent}`, 'flows', `flow${id}`, prop];
 
+const FlowDetailsProps = {
+  type: M.string(),
+  amount: AnyNatAmountShape,
+};
+
 export const FlowStatusShape: TypedPattern<StatusFor['flow']> = M.or(
   M.splitRecord(
     { state: 'run', step: M.number(), how: M.string() },
-    { steps: M.arrayOf(M.number()) },
+    { steps: M.arrayOf(M.number()), ...FlowDetailsProps },
   ),
   { state: 'undo', step: M.number(), how: M.string() }, // XXX Not currently used
-  { state: 'done' },
+  M.splitRecord({ state: 'done' }, FlowDetailsProps),
   M.splitRecord(
     { state: 'fail', step: M.number(), how: M.string(), error: M.string() },
-    { next: M.record(), where: AnyString<AssetPlaceRef>() },
+    {
+      next: M.record(), // XXX recursive pattern
+      where: AnyString<AssetPlaceRef>(), // XXX obsolete
+      ...FlowDetailsProps,
+    },
     {},
   ),
 );

packages/portfolio-contract/test/offer-shapes.test.ts

@@ -150,27 +150,36 @@ test('numeric position references are rejected', t => {
 });
 
 test('vstorage flow type matches shape', t => {
+  const amount = usdc(200n);
   const passCases: Record<string, StatusFor['flow']> = harden({
     runningFlow: {
       state: 'run',
       step: 1,
       how: 'deposit',
+      type: 'deposit',
+      amount,
     },
     completedFlow: {
       state: 'done',
+      type: 'deposit',
+      amount,
     },
     failedFlow: {
       state: 'fail',
       step: 0,
       how: 'transfer',
       error: 'Insufficient funds',
+      type: 'deposit',
+      amount,
     },
     failedFlowWithLocation: {
       state: 'fail',
       step: 1,
       how: 'deposit',
       error: 'Network timeout',
       where: '@Arbitrum',
+      type: 'deposit',
+      amount,
     },
   });
 

packages/portfolio-contract/test/portfolio.exo.test.ts

@@ -79,7 +79,12 @@ test('portfolio exo caches storage nodes', async t => {
   t.is(nodeQty, 2, 'root + portfolio');
 
   manager.startFlow({ type: 'rebalance' });
-  const flowStatus: StatusFor['flow'] = { state: 'run', step: 1, how: 'USDN' };
+  const flowStatus: StatusFor['flow'] = {
+    state: 'run',
+    step: 1,
+    how: 'USDN',
+    type: 'rebalance',
+  };
   reporter.publishFlowStatus(1, flowStatus);
   reporter.publishFlowStatus(1, { ...flowStatus, step: 2 });
   await eventLoopIteration();

packages/portfolio-contract/test/portfolio.flows.test.ts

@@ -1246,6 +1246,7 @@ test('handle failure in provideEVMAccount sendMakeAccountCall', async t => {
     const fs = await getFlowStatus(1, 1);
     t.log(fs);
     t.deepEqual(fs, {
+      type: 'rebalance',
       state: 'fail',
       step: 0,
       how: 'makeAccount: Arbitrum',