fix(portfolio-contract): Start a flow when openPortfolio includes an initial deposit (#12115)

Fixes #12114

## Description
If `openPortfolio` is called with a Deposit, use `executePlan` rather than `rebalance` to coördinate with the planner.

### Security Considerations
None known. This effectively tacks on a "deposit" flow to the existing "open portfolio" flow.

### Scaling Considerations
None; the planner is already expected to respond to deposits.

### Documentation Considerations
n/a

### Testing Considerations
Fixes for existing tests are in progress.

### Upgrade Considerations
The planner is already expecting and prepared to respond to deposit flows. This should follow the usual `ymaxControl.upgrade(...)` pattern.

Author: mergify[bot]

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

@@ -447,13 +447,14 @@ export const preparePortfolioKit = (
             this.facets.reporter.publishStatus();
           }
         },
-        startFlow(detail: FlowDetail) {
-          const { nextFlowId, flowsRunning } = this.state;
-          this.state.nextFlowId = nextFlowId + 1;
+        startFlow(detail: FlowDetail, steps?: MovementDesc[]) {
+          const { nextFlowId: flowId, flowsRunning } = this.state;
+          this.state.nextFlowId = flowId + 1;
           const sync: VowKit<MovementDesc[]> = vowTools.makeVowKit();
-          flowsRunning.init(nextFlowId, harden({ sync, ...detail }));
+          if (steps) sync.resolver.resolve(steps);
+          flowsRunning.init(flowId, harden({ sync, ...detail }));
           this.facets.reporter.publishStatus();
-          return { stepsP: sync.vow, flowId: nextFlowId };
+          return { stepsP: sync.vow, flowId };
         },
         providePosition(
           poolKey: PoolKey,

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

@@ -865,20 +865,21 @@ export const rebalance = (async (
   const traceP = makeTracer('rebalance').sub(`portfolio${id}`);
   const proposal = seat.getProposal() as ProposalType['rebalance'];
   traceP('proposal', proposal.give, proposal.want, offerArgs);
+  const { flow, targetAllocation } = offerArgs;
 
   await null;
   let flowId: number | undefined;
   try {
-    if (offerArgs.targetAllocation) {
-      kit.manager.setTargetAllocation(offerArgs.targetAllocation);
-    } else if ((offerArgs.flow || []).some(step => step.dest === '+agoric')) {
-      // steps include a deposit that the planner should respond to
+    if (targetAllocation) {
+      kit.manager.setTargetAllocation(targetAllocation);
+    } else if (flow?.some(step => step.dest === '+agoric')) {
+      // flow includes a deposit that the planner should respond to
       kit.manager.incrPolicyVersion();
     }
 
-    if (offerArgs.flow) {
-      ({ flowId } = kit.manager.startFlow({ type: 'rebalance' }));
-      await stepFlow(orch, ctx, seat, offerArgs.flow, kit, traceP, flowId);
+    if (flow) {
+      ({ flowId } = kit.manager.startFlow({ type: 'rebalance' }, flow));
+      await stepFlow(orch, ctx, seat, flow, kit, traceP, flowId);
     }
 
     if (!seat.hasExited()) {
@@ -1113,10 +1114,22 @@ export const openPortfolio = (async (
       await registerNobleForwardingAccount(sender, dest, forwarding, traceP);
     }
 
+    const { give } = seat.getProposal() as ProposalType['openPortfolio'];
     try {
-      await rebalance(orch, ctxI, seat, offerArgs, kit);
+      if (offerArgs.flow) {
+        // XXX only for testing recovery?
+        await rebalance(orch, ctxI, seat, offerArgs, kit);
+      } else if (offerArgs.targetAllocation) {
+        kit.manager.setTargetAllocation(offerArgs.targetAllocation);
+        if (give.Deposit) {
+          await executePlan(orch, ctxI, seat, offerArgs, kit, {
+            type: 'deposit',
+            amount: give.Deposit,
+          });
+        }
+      }
     } catch (err) {
-      traceP('⚠️ rebalance failed', err);
+      traceP('⚠️ initial flow failed', err);
       if (!seat.hasExited()) seat.fail(err);
     }
 
@@ -1153,17 +1166,16 @@ export const executePlan = (async (
   orch: Orchestrator,
   ctx: PortfolioInstanceContext,
   seat: ZCFSeat,
-  _offerArgs: unknown,
+  offerArgs: { flow?: MovementDesc[] },
   pKit: GuestInterface<PortfolioKit>,
   flowDetail: FlowDetail,
 ): Promise<`flow${number}`> => {
   const pId = pKit.reader.getPortfolioId();
   const traceP = makeTracer(flowDetail.type).sub(`portfolio${pId}`);
 
-  // XXX enhancement: let caller supply steps
-  const { stepsP, flowId } = pKit.manager.startFlow(flowDetail);
+  const { stepsP, flowId } = pKit.manager.startFlow(flowDetail, offerArgs.flow);
   const traceFlow = traceP.sub(`flow${flowId}`);
-  traceFlow('waiting for steps from planner');
+  if (!offerArgs.flow) traceFlow('waiting for steps from planner');
   // idea: race with seat.getSubscriber()
   const steps = await (stepsP as unknown as Promise<MovementDesc[]>); // XXX Guest/Host types UNTIL #9822
   try {

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

@@ -884,7 +884,7 @@ const setupPlanner = async t => {
   const planner1 = plannerClientMock(walletPlanner, started.instance, () =>
     readPublished(`wallet.agoric1planner`),
   );
-  return { common, zoe, started, trader1, planner1 };
+  return { common, zoe, started, trader1, planner1, readPublished };
 };
 
 test('redeem, use planner invitation', async t => {
@@ -1227,3 +1227,66 @@ test('simple rebalance using planner', async t => {
   ]);
   t.is(833332500n, (3333330000n * 25n) / 100n);
 });
+
+test('create+deposit using planner', async t => {
+  const { common, trader1, planner1, readPublished } = await setupPlanner(t);
+  const { usdc } = common.brands;
+
+  await planner1.redeem();
+
+  const traderP = (async () => {
+    const Deposit = usdc.units(1_000);
+    await Promise.all([
+      trader1.openPortfolio(t, { Deposit }, { targetAllocation: { USDN: 1n } }),
+      ackNFA(common.utils),
+    ]);
+    t.log('trader created with deposit', Deposit);
+  })();
+
+  const plannerP = (async () => {
+    const getStatus = async pId => {
+      // NOTE: readPublished uses eventLoopIteration() to let vstorage writes settle
+      const x = await readPublished(`portfolios.portfolio${pId}`);
+      return x as unknown as StatusFor['portfolio'];
+    };
+
+    const pId = 0;
+    const {
+      flowsRunning = {},
+      policyVersion,
+      rebalanceCount,
+    } = await getStatus(pId);
+    t.is(keys(flowsRunning).length, 1);
+    const [[flowId, detail]] = Object.entries(flowsRunning);
+    const fId = Number(flowId.replace('flow', ''));
+
+    // narrow the type
+    if (detail.type !== 'deposit') throw t.fail(detail.type);
+
+    // XXX brand from vstorage isn't suitable for use in call to kit
+    const amount = AmountMath.make(usdc.brand, detail.amount.value);
+
+    const plan: MovementDesc[] = [
+      { src: '<Deposit>', dest: '@agoric', amount },
+    ];
+    await E(planner1.stub).resolvePlan(
+      pId,
+      fId,
+      plan,
+      policyVersion,
+      rebalanceCount,
+    );
+    t.log('planner resolved plan');
+  })();
+
+  await Promise.all([traderP, plannerP]);
+
+  const bankTraffic = common.utils.inspectBankBridge();
+  const { accountIdByChain } = await trader1.getPortfolioStatus();
+  const [_ns, _ref, addr] = accountIdByChain.agoric!.split(':');
+  const myVBankIO = bankTraffic.filter(obj =>
+    [obj.sender, obj.recipient].includes(addr),
+  );
+  t.log('bankBridge for', addr, myVBankIO);
+  t.like(myVBankIO, [{ type: 'VBANK_GIVE', amount: '1000000000' }]);
+});

packages/portfolio-contract/test/target-allocation.test.ts

@@ -14,18 +14,13 @@ const ackNFA = (utils, ix = 0) =>
 
 test('openPortfolio stores and publishes target allocation', async t => {
   const { trader1, common } = await setupTrader(t);
-  const { usdc } = common.brands;
 
   // target: 60% USDN, 40% Aave on Arbitrum
   const targetAllocation = { USDN: 6000n, Aave_Arbitrum: 4000n };
 
   // Open portfolio with target allocation
   await Promise.all([
-    trader1.openPortfolio(
-      t,
-      { Deposit: usdc.units(1_000) },
-      { targetAllocation },
-    ),
+    trader1.openPortfolio(t, {}, { targetAllocation }),
     ackNFA(common.utils),
   ]);
 
@@ -112,20 +107,12 @@ test('multiple portfolios have independent allocations', async t => {
 
   // Open portfolios with different allocations
   await Promise.all([
-    trader1.openPortfolio(
-      t,
-      { Deposit: usdc.units(5_000) },
-      { targetAllocation: allocation1 },
-    ),
+    trader1.openPortfolio(t, {}, { targetAllocation: allocation1 }),
     ackNFA(common.utils, 0),
   ]);
 
   await Promise.all([
-    trader2.openPortfolio(
-      t,
-      { Deposit: usdc.units(7_000) },
-      { targetAllocation: allocation2 },
-    ),
+    trader2.openPortfolio(t, {}, { targetAllocation: allocation2 }),
     ackNFA(common.utils, -1),
   ]);
 

packages/portfolio-contract/test/ymax-scenario.test.ts

@@ -4,6 +4,7 @@
 // prepare-test-env has to go 1st; use a blank line to separate it
 import { test } from '@agoric/zoe/tools/prepare-test-env-ava.js';
 
+import { inspect } from 'node:util';
 import { eventLoopIteration } from '@agoric/internal/src/testing-utils.js';
 import { AxelarChain } from '@agoric/portfolio-api/src/constants.js';
 import { Fail } from '@endo/errors';
@@ -53,9 +54,9 @@ const rebalanceScenarioMacro = test.macro({
   async exec(t, description: string) {
     const { trader1, common, started, zoe } = await setupTrader(t);
     const scenarios = await scenariosP;
-    const scenario = scenarios[description];
-    if (!scenario) return t.fail(`Scenario "${description}" not found`);
-    t.log('start', description);
+    const rawScenario = scenarios[description];
+    if (!rawScenario) return t.fail(`Scenario "${description}" not found`);
+    t.log('start', description, inspect(rawScenario, { depth: 5 }));
 
     const { ibcBridge } = common.mocks;
     for (const money of [
@@ -70,8 +71,8 @@ const rebalanceScenarioMacro = test.macro({
     }
 
     const { usdc } = common.brands;
-    const sceneB = withBrand(scenario, usdc.brand);
-    const sceneBP = scenario.previous
+    const scenario = withBrand(rawScenario, usdc.brand);
+    const previous = scenario.previous
       ? withBrand(scenarios[scenario.previous], usdc.brand)
       : undefined;
 
@@ -140,21 +141,21 @@ const rebalanceScenarioMacro = test.macro({
       return { result, payouts };
     };
 
-    const openOnly = Object.keys(sceneB.before).length === 0;
-    openOnly || sceneBP || Fail`no previous scenario for ${description}`;
+    const openOnly = Object.keys(scenario.before).length === 0;
+    openOnly || previous || Fail`no previous scenario for ${description}`;
     const openResult = await (openOnly
-      ? openPortfolioAndAck(sceneB.proposal.give, sceneB.offerArgs)
-      : openPortfolioAndAck(sceneBP!.proposal.give, sceneBP!.offerArgs));
+      ? openPortfolioAndAck(scenario.proposal.give, scenario.offerArgs)
+      : openPortfolioAndAck(previous!.proposal.give, previous!.offerArgs));
 
     const { payouts } = await (async () => {
       if (openOnly) return openResult;
 
       const rebalanceP = trader1.rebalance(
         t,
-        sceneB.proposal,
-        sceneB.offerArgs,
+        scenario.proposal,
+        scenario.offerArgs,
       );
-      await ackSteps(sceneB.offerArgs);
+      await ackSteps(scenario.offerArgs);
       const result = await rebalanceP;
       return result;
     })();
@@ -170,11 +171,11 @@ const rebalanceScenarioMacro = test.macro({
 
     const txfrs = await trader1.netTransfersByPosition();
     t.log('net transfers by position', txfrs);
-    t.deepEqual(txfrs, sceneB.after, 'net transfers should match After row');
+    t.deepEqual(txfrs, scenario.after, 'net transfers should match After row');
 
     t.log('payouts', payouts);
     const { Access: _, ...skipAssets } = payouts;
-    t.deepEqual(skipAssets, sceneB.payouts, 'payouts');
+    t.deepEqual(skipAssets, scenario.payouts, 'payouts');
 
     // XXX: inspect bridge for netTransfersByPosition chains?
   },

packages/portfolio-contract/tools/rebalance-grok.ts

@@ -28,17 +28,25 @@ export const numeral = (amt: Dollars) => amt.replace(/[$,]/g, '');
 
 type Empty = Record<never, never>;
 
-export type RebalanceScenario = {
+type MovementDescTemplate<V extends NatAmount | Dollars> = V extends NatAmount
+  ? MovementDesc
+  : V extends Dollars
+    ? Omit<MovementDesc, 'amount'> & { amount: Dollars }
+    : never;
+
+export type RebalanceScenario<V extends NatAmount | Dollars = Dollars> = {
   description: string;
-  before: Partial<Record<YieldProtocol, Dollars>>;
+  before: Partial<Record<YieldProtocol, V>>;
   previous: string;
   proposal:
     | { give: Empty; want: Empty }
-    | { give: { Deposit: Dollars }; want: Empty }
-    | { want: { Cash: Dollars }; give: Empty };
-  offerArgs?: { flow: (Omit<MovementDesc, 'amount'> & { amount: Dollars })[] };
-  after: Partial<Record<YieldProtocol, Dollars>>;
-  payouts: { Deposit?: Dollars; Cash?: Dollars };
+    | { give: { Deposit: V }; want: Empty }
+    | { want: { Cash: V }; give: Empty };
+  offerArgs: V extends NatAmount
+    ? { flow?: MovementDesc[] }
+    : { flow: MovementDescTemplate<V>[] } | undefined;
+  after: Partial<Record<YieldProtocol, V>>;
+  payouts: { Deposit?: V; Cash?: V };
   positionsNet: Dollars;
   offerNet: Dollars;
   operationNet: Dollars;
@@ -169,7 +177,7 @@ export const grokRebalanceScenarios = (data: Array<string[]>) => {
         const dest = asPlaceRef(hd[destCol]);
 
         const amount = T2B as Dollars;
-        assert(amount && amount.startsWith('$'), `bad amount in row ${rownum}`);
+        amount?.startsWith('$') || assert.fail(`bad amount in row ${rownum}`);
 
         flow.push({ src, dest, amount });
         break;
@@ -208,34 +216,34 @@ export const grokRebalanceScenarios = (data: Array<string[]>) => {
 };
 
 export const withBrand = (
-  scenario: RebalanceScenario,
+  scenario: RebalanceScenario<Dollars>,
   brand: Brand<'nat'>,
   feeBrand = brand,
-) => {
+): RebalanceScenario<NatAmount> => {
   const { make } = AmountMath;
   const unit = make(brand, 1_000_000n);
   const $ = (amt: Dollars): NatAmount =>
     multiplyBy(unit, parseRatio(numeral(amt), brand));
   const $$ = <C extends Record<string, Dollars>>(dollarCells: C) =>
     objectMap(dollarCells, a => $(a!));
 
+  const needsFee = m =>
+    m.dest === '@Arbitrum' ||
+    ['Compound', 'Aave'].some(p => m.dest.startsWith(p) || m.src.startsWith(p));
   const withFee = m =>
-    ['Compound', 'Aave'].some(
-      p => m.dest.startsWith(p) || m.src.startsWith(p),
-    ) || m.dest === '@Arbitrum'
-      ? { ...m, fee: { brand: feeBrand, value: 100n } }
-      : m;
-
-  const flow = scenario.offerArgs?.flow;
-  const offerArgs = flow
-    ? harden({ flow: flow.map(m => withFee({ ...m, amount: $(m.amount) })) })
-    : harden({});
+    needsFee(m) ? { ...m, fee: { brand: feeBrand, value: 100n } } : m;
 
+  const flow = scenario.offerArgs?.flow?.map(
+    m => withFee({ ...m, amount: $(m.amount) }) as MovementDesc,
+  );
+  const offerArgs = flow ? harden({ flow }) : harden({});
   mustMatch(offerArgs, makeOfferArgsShapes(brand).rebalance);
 
   const proposal = objectMap(scenario.proposal, $$);
   mustMatch(proposal, makeProposalShapes(brand).rebalance);
+
   return harden({
+    ...scenario,
     before: $$(scenario.before),
     proposal,
     offerArgs,