docs: market params design_doc

[toteki]

New ADR (as folder is not yet moved/renamed) absorbs some previous changes and proposes three similarly themed parameters:

• MaxSupplyUtilization
• MaxCollateralShare
• MinCollateralLiquidity (alternative: MaxCollateralUtilization)

This has been split off from #1141 into a docs-only PR for process.

---

Author Checklist

All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.

I have...

• included the correct type prefix in the PR title
• added ! to the type prefix if API or client breaking change
• added appropriate labels to the PR
• targeted the correct branch (see PR Targeting)
• provided a link to the relevant issue or specification
• added a changelog entry to CHANGELOG.md
• included comments for documenting Go code
• updated the relevant documentation or specification
• reviewed "Files changed" and left comments if necessary
• confirmed all CI checks have passed

Reviewers Checklist

All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.

I have...

• confirmed the correct type prefix in the PR title
• confirmed all author checklist items have been addressed
• reviewed state machine logic
• reviewed API design and naming
• reviewed documentation is accurate
• reviewed tests and test coverage
• manually tested (if applicable)

[robert-zaremba]

Is there anything new in this PR?

• I thought you were mentioning to reverse collateral_utilization. It stays the same in this PR. Also, as noted in docs: ADR-4: max collateral utilization #940, reversing doesn't help. I think you are noting this in this PR as well (in alternatives section). Commenting about it because I thought that this was the motivation to block Add MaxCollateralUtilization or MinCollateralLiquidity to Token Registry #1036.
• If this is going to improve documentation, then let's put it as a documentation (in x/leverage/spec)

[robert-zaremba]

Why moving this definitions?

[toteki]

It was not part of the original decision - since ADR-003 will be renamed to a design doc (and already functioned as one), this is an attempt to apply the rule "don't modify old design docs, but make a new one instead."

Since multiple parameters are being added in the same timeframe, it made sense to group the proposals.

[robert-zaremba]

I know, but they are related to the borrowing as well.
Hence, if we are moving this then let's already organize it in a documentation, rather than scatter it around decision docs.

[toteki]

What specifically should I do to this PR before merging? As it stands, it is a completed design doc representing parameters which were added together on a single theme.

Moving the collateral utilization definition back to 003 violates "don't modify old design docs" rule. Removing this document altogether and putting it in the spec goes against our decision to use design doc PRs.

As I see it, this should either be merged unchanged, or moved to the design docs folder first then merged. Spec updates are a separate issue and do not happen during the initial design PR.

[toteki]

Is there anything new in this PR?

• Adds two new parameters MaxCollateralShare and MaxSupplyUtilization
• Renames + redefines MaxCollateralUtilization to MinCollateralLiquidity
• Moves the latter to a new doc with the others

[toteki]

This is the first PR that was split off from #1141, and should ideally be merged before #1159.

[robert-zaremba]

1. It would be great if we already start moving towards a nice documentation flow, and link definitions and whatever is needed into the design docs. If we desided that the design docs are going to be static (won't change after the design is settled), then we end up with scattered pieces distributed among decision discussed in desig docs.
2. For completeness, let's already place this document in docs/design_docs

[adamewozniak]

Suggested change

	Stable assets will have high max collateral utilization (can go even to 50). Volatile assets should have significantly smaller collateral utilization, and assets with high risk should have max collateral utilization close to 1.
	Stable assets will have high max collateral utilization (up to to 50). Volatile assets should have significantly smaller collateral utilization, and assets with high risk should have max collateral utilization close to 1.

[robert-zaremba]

I hoped we won't merge PRs without updated documentation (spec dir)

[toteki]

I hoped we won't merge PRs without updated documentation (spec dir)

Current practice is to update spec simultaneous with implementation, so it is always exactly up to date (as opposed to containing unimplemented features).

As an example, the proto update with these parameters also added them to the Token struct in the spec.

We will likely update the descriptions (specifically failure conditions) of Msg types in the spec, in the same PR as those limits are introduced in code.

Also since spec is scheduled for overhaul (to be fleshed out to be an adequate source of truth) we can wait until v3 release candidate is out to do the large spec updates.

If the above turns out to be bad practice, we can revisit it - for now, I want to rush v3.

[robert-zaremba]

Current practice is to update spec simultaneous with implementation, so it is always exactly up to date (as opposed to containing unimplemented features).

I have never seen that. The whole motivation to redo the adr process and put more pressure to the documentation was that both were and still are very outdated.

We will likely update the descriptions (specifically failure conditions) of Msg types in the spec,

We should really link it to the code / or proto file rather than copying it. This way we are sure the we will be up to date.

[robert-zaremba]

True - we don't need to update the docs now, we don't have that task. But if in any current tasks we are updating something then we should already slowly construct the updated docs.