Improve context definition in protocol library docs
- Lingua principale
- Rust
- Stelle
- 132
- Fork
- 167
- Merge medio
- 1g 23h
- PR unite (30g)
- 110
Descrizione
As a follow-up for #1799 we may want to consider the best way to define "Context".
#1799 added a table in the docs that documents the procedures of `miden` lib (https://0xmiden.github.io/miden-docs/imported/miden-base/src/protocol_library.html#contexts). That page defines the "Context" of a procedure from which it can be called.
For instance, `miden::account::add_asset` has the `Native & Account` context, which means the procedure can only be called when the current account is the native one and when the calling procedure is part of the account code.
This may be a bit confusing (e.g. https://github.com/0xMiden/miden-base/pull/1799#discussion_r2315568181) because as in this example, this could imply that `output_note::add_asset` with the `Native` context cannot be called from a note script, but it actually can. The question here is how to improve this to make it less confusing.
**Actual Contexts**
A better approach here is probably a more user-centric one. One that explicitly and exhaustively lists the "contexts" from which an API can be called. These contexts are `NoteScript`, `TxScript`, `ForeignAccount`, `NativeAccount` and `AuthProcedure`.
For instance:
- the `Native` requirement for `output_note::add_asset` mentioned above would not be representable in this model. We would simply say that `output_note::add_asset` can be called from note scripts. This is fine because if a note script calls into a foreign account, then that changes the context to a foreign account and the procedure can no longer be called. If that call finishes, the context switches back and the API is callable again. So because a `NoteScript` context calling into the kernel always executes against the native account, this is fine. So overall, for `output_note::add_asset` we would explicitly list `NoteScript`, `TxScript`, `NativeAccount` and `AuthProcedure`.
- for `account::incr_nonce`, we would specify `AuthProcedure` as the only context.
The downside of this is a bit more verbosity on the doc page, but that's probably acceptable.
If we go with this, we should elaborate on the definition of contexts and list the concrete ones that exist, so users can build a good mental model for this.
**Rename**
The reason why I chose "Context" was because this table already existed in previous versions and it used the notion of VM contexts to explain the permissions. However, I somewhat changed the definition of context without renaming it and so one potential fix is to choose a different name. What `Native` or `Account` really represent are preconditions for a successfull call to these APIs, e.g. the transaction kernel's current account must be the native one and the procedure must be called from the account context. So a potential fix could be to rename "Context" into "Preconditions" or "Requirements".
**Fix**
One thing we can fix as part of this is the context for `output_note::create`. It currently says `Native & Account` but, in the current model it would actually only be `Native`, since output notes can be created from note or transaction scripts.
I would go with the "actual contexts" from above which seems like a better overall approach, but let me know your thoughts.
Guida per i contributori
Apri la guida per i contributori
Valutazione
Questa issue non è ancora stata valutata.