Distributing fees to Reserve

[anilhelvaci]

Context

In The Inter Protocol Whitepaper's Section 2.4, there mentioned a Reserve Pool. I assume that Reserve Pool is the one in packages/interProtocol/src/reserve/assetReserve.js when I'm asking my question. If I'm wrong please point me to the correct Reserve Pool.

Question

I don't quite understand how the distribution of fees collected from vaultFactory, amm and stakeFactory end up in assetReserve.js. In econ-behaviors' startRewardDistributer method there's this code. Below is the snippet:

await E(instanceKit.creatorFacet).setDestinations({
    RewardDistributor:
      rewardDistributorDepositFacet &&
      E(instanceKit.creatorFacet).makeDepositFacetDestination(
        rewardDistributorDepositFacet,
      ),
    Reserve: E(instanceKit.creatorFacet).makeOfferDestination(
      'Collateral',
      E.get(reserveKit).publicFacet,
      'makeAddCollateralInvitation',
    ),
  });

As far as I can understand here's the flow;

sequenceDiagram
    boot->>+feeDistributer: Set destinations
    Note over boot,feeDistributer: Reward, Reserve
    feeDistributer ->> feeDistributer: update shareConfig
    feeDistributer ->> vaultFacotry/amm/stakeFactory: collectFees
    feeDistributer ->> bank (Reward Pool): pushPayment
    feeDistributer ->> assetReserve (Reserve Pool): pushPayment

Loading

My questions;
The signature of makeOfferDestination is like below;

 /**
     * Create a destination that generates invitations and makes Zoe offers.
     *
     * @param {ERef<ZoeService>} zoe
     * @param {string} keyword
     * @param {unknown} target
     * @param {PropertyKey} makeInvitationMethod
     * @param {unknown[]} [args]
     */
    makeOfferDestination: (
      zoe,
      keyword,
      target,
      makeInvitationMethod,
      args = [],
    ) => {
    // Method body...
    }

But in startRewardDistributor's ;

Reserve: E(instanceKit.creatorFacet).makeOfferDestination(
      'Collateral',
      E.get(reserveKit).publicFacet,
      'makeAddCollateralInvitation',

1. The method is called without the first argument which is zoe
2. The keyword is Collateral, shouldn't it be Fee as the IST is collected under the keyword Fee in collectFees.js like below;

    const collectFees = seat => {
      const amount = feeSeat.getAmountAllocated(keyword, feeBrand);
      atomicTransfer(zcf, feeSeat, seat, { [keyword]: amount }, { Fee: amount }); // To keyword is `Fee`
   
      seat.exit();
      return `paid out ${amount.value}`;
    };

Am I wrong or is this a bug? @dckc . If I'm wrong, can someone please point me to the correct direction?

Thanks 🙏

[tgrecojs]

I did some investigating by running ava ./test/test-gov-collateral.js. Here is the information I gathered.

1. The method is called without the first argument which is zoe

I inspected the arguments passed into makeOfferDestination, and it seems like you may have found a bug.

Below is what the results of that looked like

inside makeOfferDestination:::: ::: {
  zoe: 'Collateral',
  keyword: Promise { <pending> },
  target: 'makeAddCollateralInvitation',
  makeInvitationMethod: undefined,
  args: []
}
inside makeOfferDestination:::: ::: {
  zoe: 'Collateral',
  keyword: Promise { <pending> },
  target: 'makeAddCollateralInvitation',
  makeInvitationMethod: undefined,
  args: []
}

Another thing to note is that the code stopped executing makeOfferDestination before Far is called.

The keyword is Collateral, shouldn't it be Fee as the IST is collected under the keyword Fee in collectFees.js like below;

I think that collectFees will use the keyword param to create the feeSeat side of the offer so that it would look like the following:

 atomicTransfer(zcf, feeSeat, seat, { Collateral: amount }, { Fee: amount }); // To keyword is `Fee`

I believe this would be OK and that "Fee" does not need to be passed in as the argument for keyword. Interestingly enough though, inspecting the arguments passed into collectFees isn't showing "Collateral", but rather it shows "Minted" and "Fee".

inside collectFees::: ::: {
  seat: Object [Alleged: zcfSeat] {},
  feeSeat: Object [Alleged: zcfSeat] {},
  feeBrand: Object [Alleged: IST brand] {},
  keyword: 'Minted',
  amount: { brand: Object [Alleged: IST brand] {}, value: 0n }
}
inside collectFees::: ::: {
  seat: Object [Alleged: zcfSeat] {},
  feeSeat: Object [Alleged: zcfSeat] {},
  feeBrand: Object [Alleged: IST brand] {},
  keyword: 'Minted',
  amount: { brand: Object [Alleged: IST brand] {}, value: 0n }
}
inside collectFees::: ::: {
  seat: Object [Alleged: zcfSeat] {},
  feeSeat: Object [Alleged: zcfSeat] {},
  feeBrand: Object [Alleged: IST brand] {},
  keyword: 'Minted',
  amount: { brand: Object [Alleged: IST brand] {}, value: 0n }
}
inside collectFees::: ::: {
  seat: Object [Alleged: zcfSeat] {},
  feeSeat: Object [Alleged: zcfSeat] {},
  feeBrand: Object [Alleged: IST brand] {},
  keyword: 'Minted',
  amount: { brand: Object [Alleged: IST brand] {}, value: 0n }
}
inside collectFees::: ::: {
  seat: Object [Alleged: zcfSeat] {},
  feeSeat: Object [Alleged: zcfSeat] {},
  feeBrand: Object [Alleged: IST brand] {},
  keyword: 'Fee',
  amount: { brand: Object [Alleged: IST brand] {}, value: 0n }
}

There are a few more logs than this, but I left them out. That said, I think this behavior is correct, but maybe @dckc can add more context from here.

[anilhelvaci]

Thanks for your detailed answer! @tgrecojs

[anilhelvaci]

What tool did you use to produce these logs? @tgrecojs

inside makeOfferDestination:::: ::: {
  zoe: 'Collateral',
  keyword: Promise { <pending> },
  target: 'makeAddCollateralInvitation',
  makeInvitationMethod: undefined,
  args: []
}
inside makeOfferDestination:::: ::: {
  zoe: 'Collateral',
  keyword: Promise { <pending> },
  target: 'makeAddCollateralInvitation',
  makeInvitationMethod: undefined,
  args: []
}

Thanks 🙏

[dckc]

I have a relevant PR in progress:

• feat(inter-protocol): set keyword shares on feeDistributor #6962

perhaps I can take a closer look when i swap that back in.

Meanwhile, perhaps @Chris-Hibbert or @turadg has a moment to look into this.

[anilhelvaci]

This PR uses makeDepositFacetDestination method to create a destination for Reserve:

 const reserveDestination = creatorFacet.makeDepositFacetDestination(deposit2);

But when I look at the econ-behaviors, it uses makeOfferDestination method to create the destination which I'm not able to find any tests using that method.

await E(instanceKit.creatorFacet).setDestinations({
    RewardDistributor:
      rewardDistributorDepositFacet &&
      E(instanceKit.creatorFacet).makeDepositFacetDestination(
        rewardDistributorDepositFacet,
      ),
    Reserve: E(instanceKit.creatorFacet).makeOfferDestination(
      'Collateral',
      E.get(reserveKit).publicFacet,
      'makeAddCollateralInvitation',
    ),
  });

And makeOfferDestination needs zoe as it's first argument, maybe this got overlooked.

[anilhelvaci]

I think I'm all clear now. As far as I can understand the fee distribution to Reserve functions like below;

flowchart 
    subgraph econ-behaviors
        startRewardDist[Start Reward Distribution] --> startIns[Start feeDistributer]
        farSetDest[Set Fee Destinations and Shares]
        crCol[Make a collector]
        startCol[Start Periodic Collection]
        startCol -- Repeat 3 times for 'VF', 'AMM' and 'SF' ---crCol
    end
    feeDistributer -- creatorFacet --> farSetDest
    startIns -- Start instance and return creatorFacet --> feeDistributer
    farSetDest -- creatorFacet.setDestinations --> setDest
    config --> crCol
    crCol -- Create and return new collector --> makeCol
    makeCol -- Collector --> startCol
    startCol --> startP
    subgraph feeDistributer
        collectors[(Collectors)]
        config[(Share Configuration)]
        setDest[Set Destinations]
        makeCol[Make a new collector]
        startP[Start Collection]
        start[startDistributing] -- On every interval --> schedule[schedulePayments]
        schedule -- For every collector -->collectors
        clct[Collect Fee]
        schedule -- Collector --> clct
        clct -- Collected Fee -->dist[Distribute]
        dist -- For every share and destination -->config
        dist -- Share and Destination --> pay[PushPayment]
        setDest -- Update --> config
        startP -- Add new collector --> collectors
        startP --> clct
    end
    pay -- Fee --> assetRes[Reserve Pool]

Loading

Please let me know if there's anything I'm missing. @turadg @Chris-Hibbert @dckc

[dckc]

The args bug above is #7046 .
Thanks for finding it, folks!