Agree on how to represent Liquid Newton contract public API

[szemate]

For Autonity 0.15 the Liquid Newton contract has been reworked the following way:

• Each validator has a "Liquid State" contract that stores the state of their Liquid Newton token,
• but the actual token methods are implemented by a single "Liquid Logic" contract that each Liquid State contract delegates calls to, in order to make contract upgrades easier;
• consequence: contract API users interact with Liquid State contracts, however the actual contract interface is defined by the Liquid Logic contract.

My questions are the following:

• Shall we hide the above complexity from API users, and present it as if it was a single token contract?
• If so, how should we refer to the contract interface? "Liquid Storage" or "Liquid Newton" or just "Liquid"? We should use the naming consistently around Autonity docs, autonity.py and autonity-cli.

@cmjc @aiman

[cmjc]

Hi @szemate @aiman great question.

I'd hide the complexity as it is implementation and not necessary in the docs.

Naming, "Liquid Newton" is right I think. I'd name the interface reference page "Liquid Newton", and the scope would be to document the functions defined in autonity/solidity/contracts/interfaces/ILiquidLogic.sol.

I think that keeps the docs simple, hides unneccessary complexity from the docs user, and gives simple, clean UX for the user looking to find the API reference for how to interact with the Liquid Newton contract functions for a validator.

The contract architecture could be described in a note box on the interface page, or even in the Concepts page Architecture, or in the Development section of the docs. You've done a pretty compact bullet point summary of it above.

Thoughts?

[cmjc]

Tagging @tbssajal for his thoughts 👍

[tbssajal]

We have an interface ILiquid.sol which is implemented by LiquidLogic. We can use that as well. We can refer the token to the address of the LiquidState contract and provide the interface which is supported by the contract.

[aiman]

The purpose of the docs is to document the Autonity Protocol API as it exists, so we should not hide any complexity. Just expose it as transparently as possible. The docs aren't the right place to "simplify" an API, that needs to happen at API level.