Investments & Vault Balance tracking

[SovereignAndrey]

We need a way to capture and track the following from Vault investments (both invest/redeem directions apply):

• AccountsStrategy Invest events for an endowment:
  • Token address
  • Strategy Key
  • Destination Chain
  • Endowment ID
  • Locked / Liquid amounts
• AccountsStrategy Redeem events for an endowment:
  • Token amount
  • Strategy key
  • Destination Chain
  • Locked / Liquid Amounts
  • Endowment ID
• Router cross-chain transaction status set/update events should update in the "AccountsStrategy" record. Possibly like a "routerStatus" field?
• Lookup a Vault balance by endowment ID
  • ie. What is the vault shares balance for a given Endowment ID?
• Vault balances updated upon deposit / withdraw event
  • Similar to Accounts balances adjustments done today in Polygon subgraph for Accounts deposit/withdraw events

COS

• Polygon subgraph captures AccountsStrategy invest/redeem events and records them
• Polygon subgraph captures Router events and records them for status change
• New Ethereum subgraph exists for tracking Vault balances for each endowment and updates them as deposit/withdraw events get emitted

[0xNeshi]

New Ethereum subgraph exists for tracking Vault balances for each endowment and updates them as deposit/withdraw events get emitted

@SovereignAndrey so a separate Subgraph needs to be created and deployed that tracks Vault balances for each endowment that's created on Ethereum? Or are Vault living on Ethereum?

Can you please expand on the context surrounding this requirement?

[SovereignAndrey]

@misicnenad Sure thing! :) We will need to have subgraph capabilities on all chains (both polygon and non-polygon chains) in order to track what vaults exists, their statuses, and to know the token balances for Endowments and track changes to those. In the case of non-polygon subgraph chains this will the only items it's concerned with, but the polygon subgraph will simply be expanded to have vault tracking abilities (once we launch polygon native vaults). Our Subgraphs will need to have entities that are largely concerned with tracking vaults and their investments.

In short, the web app should be able to:

• Pull a list of Strategies
• Pull a single strategy by it's Strategy Key ID (strategy entities hold the locked / liquid vault contacts linked to a strategy)
• Pull a list of vaults (filtering by things like Vault Status [Approved/Closed/Etc] or Strategy Key)
• Pull a single vault's info by the vault
• Get the balance of vault shares/tokens for an endowment

To achieve this we'll need to watch events like:

• Local Registrar strategies add / updated (create an modify strategy and vault records)
• Vault deposit / withdraw events to adjust endowment's token balances
• Vault harvest events to adjust token balances

[0xNeshi]

@SovereignAndrey

• AccountsStrategy Invest events for an endowment
• AccountsStrategy Redeem events for an endowment

1. Does this mean we want to be recording invest/redeem events themselves OR do we want to create some entity to track which endowment has how many funds invested for a specific strategy on a specific chain and just use those event emissions to update the entity?
Requirements and comment #21 (comment) above suggest we basically need a new entity structure similar to the Accounts - Endowment + EndowmentTokenLocked + EndowmentTokenLiquid we have now.

• Router cross-chain transaction status set/update events should update in the "AccountsStrategy" record. Possibly like a "routerStatus" field?

2. Does this "status" refer to IVault.VaultActionStatus?
It probably refers to LocalRegistrarLib.StrategyApprovalState?
3. This requirement mentions "Router cross-chain transaction status", but what about same-chain transaction status, should it be tracked as well?
We currently do not differentiate between same-chain & cross-chain Tx statuses AFAIK.
Since there are no local-chain (polygon) vaults and there will come a need to track those as well, we can use the fact that those local-chain vaults will be treated no differently than non-polygon vaults, i.e. this shouldn't affect the implementation in Subgraph in anyway, the same entity structure can be used for all types of vaults, correct?

• Lookup a Vault balance by endowment ID
  • ie. What is the vault shares balance for a given Endowment ID?

4. Just to check if I understood this correctly:
   • each strategy has one and only one network associated with it
   • once an endowment invests some funds using strategy A, those funds are deployed to a locked and/or liquid Vault on a predefined network (based on strategy)
   • so "Vaults" from this requirement are the locked & liquid ones to which an endowment invests and which they redeem from

Assuming the previous assumptions were correct, that means a "Vault" in Subgraph sense would be the "entity" mentioned in point 1) that would be tracking balances for each endowment. It would also mean that each "Vault" would be defined as a unique combination of endowment ID + strategy ID + vault type (locked/liquid) (no need to include "network", as it's closely tied to strategy ID) identified by the strategy ID its connected to, with balances being tracked by separate entities defined as endowment ID + vault type (locked/liquid), see point 1).

Is this analysis correct?

5. Are only Vault "shares" balances important for tracking? Or do we need to keep track of the exact "balance" inside the vaults as well?

• Vault balances updated upon deposit / withdraw event
  • Similar to Accounts balances adjustments done today in Polygon subgraph for Accounts deposit/withdraw events

6. I.e. "we need to update the Subgraph entity which tracks Vault shares per endowment on every deposit/withdraw", right?

7. Just to reiterate the Router-related question, how does Router Tx status field fit into this vault-shares-tracking entity?
If the status type is referring to LocalRegistrarLib.StrategyApprovalState, then the logic for including it is clear.

[SovereignAndrey]

If the status type is referring to LocalRegistrarLib.StrategyApprovalState,

Yes. That's the status I'm referring to for Strategies. 👍

[SovereignAndrey]

this shouldn't affect the implementation in Subgraph in anyway, the same entity structure can be used for all types of vaults, correct?

That's correct. When the time comes for native polygon vaults it'll just be a matter of adding the contracts tracked and the re-using the Vault/Strategy entites.

[SovereignAndrey]

Assuming the previous assumptions were correct, that means a "Vault" in Subgraph sense would be the "entity" mentioned in point 1) that would be tracking balances for each endowment. It would also mean that each "Vault" would be identified by the strategy ID its connected to, with balances being tracked by separate entities defined as endowment ID + vault type (locked/liquid), see point 1).

I think something like the following might work: Strategy (ID: strategy Key) has lockedVault & liquidVault fields that are the Address for vault contracts (which could serve as a Vault entity ID key too if we need that to hold info other than balance info). When those Vault contracts emit Deposit/Withdraw/Harvest events we catch them and can use the Strategy Key + Vault Addr + endow ID as an ID Key on a VaultBalance entity to track tokens held. VaultBalance can have relations to Vault & def needs a link to Endowment. Endowment needs a one:many link to [VaultBalances] so we can easily see all VaultBalances for a given Endowment.

[SovereignAndrey]

Are only Vault "shares" balances important for tracking? Or do we need to keep track of the exact "balance" inside the vaults as well?

Vault entity can def hold the total shares issues. 💯 @stevieraykatz might have ideas about other important things we can track there, but total shares seems like a good starting point.

[SovereignAndrey]

I.e. "we need to update the Subgraph entity which tracks Vault shares per endowment on every deposit/withdraw", right?

Yes, correct! And on harvests too since funds will come out for taxes and some of locked vault holdings gets moved over to liquid vault.

[0xNeshi]

@misicnenad answered a few and have noted ser @stevieraykatz for the contract specific questions/comments.

1. Will there be a need to still track all the deposit/withdraw/harvest transactions on a Vault?

Not that I can think of. This is only something we'd need to pull for a single endowment to show in at table on the web app

2. Will Vaults and Strategies live behind proxies, like our other contracts?

cc: @stevieraykatz

3. Which networks do we/will we have our Vaults deployed to?

Today: Ethereum
Near future: Ethereum + Polygon

4. Why do both IVault.VaultConfig and IStrategy.StrategyConfig have baseToken and yieldToken fields? Can they differ between the two?

cc: @stevieraykatz

5. Are fields strategySelector and strategyId the same thing?

I believe so, but @stevieraykatz can correct me if I'm misremembering.

6. Which token are apTokenName and apTokenSymbol referring to exactly, baseToken or yieldToken?

cc: @stevieraykatz

7. If the network tied to a strategy is closely related to said strategy (considering strategyId can only ever be tied to just one network, see LocalRegistrarLib.StrategyParams), why is it not kept in IStrategy.StrategyConfig? Same question for strategy's approval status, which is stored together with the formerly mentioned fields in LocalRegistrarLib.StrategyParams?

cc: @stevieraykatz

8. The relationship between Strategy and Vaults is a bit convoluted:

cc: @stevieraykatz

[0xNeshi]

@SovereignAndrey

3. Which networks do we/will we have our Vaults deployed to?

Today: Ethereum
Near future: Ethereum + Polygon

But all deposit/withdraw/harvest Txs (that are of interest) will be initiated from Polygon? In other words, Accounts diamond, or more specifically its AccountsStrategy facet, will be deployed only on Polygon?

The reason I'm asking is that if we'll have to listen to events emitted on multiple networks and not just Polygon, we'll have to deploy multiple Subgraphs, see this response on an issue in official repo.
This would be doable, as there is an extension for cross-chain GraphQL queries (link below), but will admittedly be a more complex (we'll need a way to connect event emissions that are related, but emitted on different chains).
https://github.com/graphprotocol/graph-client/tree/main/examples/cross-chain-extension