0xMiden / 0xMiden/protocol

Improve context definition in protocol library docs

オープン
#1,909 コメント 9 件 リアクション 1 件 担当者 0 名 GitHub で見る
documentation
主要言語
Rust
スター
132
フォーク
167
平均マージ
1日 23時間
マージ済み PR(30日)
110

説明

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.

コントリビューションガイド

コントリビューションガイドを開く

評価

この issue はまだ評価されていません。

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。