Docs CRs

[steve0xp]

Scope

This issue encompasses possible docs change requests (CRs). It is a live issue. It is also a referencable note to help create said CRs to the docs when we have time. If the ideas here are worthwhile, we will open issues and respective PR(s) to make the changes in the docs.

Ref: BalancerV3 Docs

[steve0xp]

1. The smart contract example within Create a custom AMM with a novel invariant page needs to be corrected.
2. Additional context on calling IVault(vault).registerPool() and IVault(vault).initialize() would be nice. It would go hand in hand with the explanation on the proxy architecture.
3. Proxy architecture with diagrams outlining how things work would be nice too (just explaining the inheritance visually is easier I find versus tracking things down in the code itself). Once one tracks it in the code itself, it is easy to forget too :O

[steve0xp]

Testing Sections

IMO, it would be cool to see a testing section in the docs outlining how Balancer provides a test suite that a developer has to ensure works with their pool (custom or not). This is similar to how Yearn strategies are tested against the YearnV2 architecture.

Questions:

1. Is this of interest to Balancer? Does Balancer already provide this kind of test suite? If not, how difficult is it to make the a custom pool test file that would cover what is necessary on this?

[steve0xp]

Custom Pool Factory

• Use of custom factory for pool deployments, and aspects related to it.
  • Key Gotchas include: Sequence of things: creating your pool, then your factory that inheritsBasePoolFactory, then deployment.
  • Possible nice to haves: test suite ensuring custom pool factory fits key testing coverage in Balancer architecture (if applicable).

[johngrantuk]

• Smart contract example corrections: Yes please :) PRs correcting any mistakes are very welcome.
• Additional context on register/initialize: If you found this tricky to understand I imagine others would too so please feel free to open PRs with suggestions on how to improve. Worth covering in call too.
• Proxy architecture diagrams: Not quite clear what this covers, can discuss in call.
• Testing section: Interesting. Would definitely be worth discussing further. Can you point to some good examples please? Also how would this differ to what we're trying to achieve with scaffold-balancer with testing templates/examples?
• Pool factory: I imagine we should just add some docs about this as its not covered at all?

[MattPereira]

TokenConfig Notes

• Only specific combinations of tokenType, rateProvider, and yieldFeeExempt are allowed for the TokenConfig that is used to create a new pool

  • https://github.com/balancer/balancer-v3-monorepo/blob/b91e0273fbd0e7073789066b1461e4873e1cb560/pkg/vault/contracts/VaultExtension.sol#L221-L234

• The TokenConfig must have "proper token order (alphanumeric)". Does that look at the token names or symbols?

[MattPereira]

On the "Create a custom AMM with a novel invariant" page of docs, in the "Deploy your pool" section, the third step says "Call vault.intialize with a link leading to IVaultExtension.sol code.
https://docs-v3.balancer.fi/build-a-custom-amm/build-an-amm/create-custom-amm-with-novel-invariant.html#deploy-your-pool

This is confusing because the only way to initialize a pool is through the router so maybe referencing router.initialize would make more sense?

[steve0xp]

Additional Questions / Areas that May Need Details in the Docs (if not already in updated versions):

• If pools are permissionless, then if I created a random pool contract, what would it have to do to be able to be registered with the vault (aside from the tokens having proper rateProvider info perhaps (which may not be needed actually)?)
• How does building off of the baseFactory help Balancer subgraph pick up necessary info from children pools?

TokenConfig - more info on it as requested before.

• Can we have clarity on the token config reversion scenarios? This LoCmakes me wonder, and we troubleshot scenarios using the same tokens and different configs and it didn't revert (though we can test more extensively).
  • For further context: John Grants had stated the following: "...I believe there is a check at Vault level that makes sure you cannot register a Pool with DAI/DAI or BAL/BAL."
• Perhaps point to appropriate smart contract files in the monorepo to help elaborate (since there is conditional logic and probably natspec for it already): VaultExtension.sol and function registerPool()

[t-phoenix]

Deployment steps for Core System Contract

Scaffold-balancer-v3 is seamless in providing playground dev experience with balancer v3 pools, but it lacks in providing steps to replicate the necessary deployment process for core system contracts like vault, Router, permit2, extensions, etc.

Specially with vaultFactory overexceeding smart-contract size limit, it becomes really difficult to deploy core smart-contracts.

[MattPereira]

Hey @t-phoenix
The scope for scaffold is to focus on helping devs create v3 pools and hooks

Not sure what plan is for supporting deployment of v3 core contracts, but feel free to ask on our discord dev support channel

[MattPereira]

Cleaning up outdated issue