Updates with more info

[Dominik1999]

I am adding some more info to the Transaction chapter. It explains a transaction as a process and provides a bit more context.

This is still a draft, but you can already comment. I will go over it a second time to also incorporate Bobbin's feedback.

[phklive]

I think that we added some valuable missing information but that we have also made it a lot lower level / complex to read.

Let's try to find a good middleground.

[phklive]

Getting closer.

Some examples might go a lil too low-level + we are talking about implementation detail types, e.g, TransactionArguments or BlockHeader, might be okay for now.

[bobbinth]

Thank you! I think we are moving in the right direction - though, we are not quite there yet. One aspect is that language/phrasing can be improved throughout - but for now I won't focus on this. More importantly, I think we are missing some important pieces and I would also re-shuffle things a bit. Here is how I'm thinking of the overall structure:

1. We start with a short intro which explains some very basic things about the transaction (i.e., a transaction updates a state of one account but consumes/produces 0 or more notes) and motivation for the design. So, I wouldn't have "what's the purpose of ..." section - this content can just go after the first paragraph.
2. After intro, I would go into the lifecycle - to explain how a transaction is executed. Some important concepts to bring up here:
   a. The sequence in which things happen (prologue, notes, tx script, epilogue).
   b. Accounts involved in a transaction, concept of native vs. foreign (state of native account can be updated, but state of foreign accounts can only be read).
   c. How notes work - i.e., notes can call methods of the account, create other notes, set transaction expiration etc.
   d. How transaction script works and why it is needed.
   e. The role of the nonce - i.e., it needs to be incremented if account state changes, we use it for transaction authentication.
   f. How a transaction uses a reference block and why it is needed (e.g., notes consumed in a transaction must have been created before the reference block). Also, maybe I'd bring up the concept of ephemeral notes here (i.e., not all notes need to be authenticated).
3. Give an example of a simple transaction. I would probably just do consuming a P2ID note. Or maybe we can do 2 examples: consuming a P2ID note and issuing a P2ID note. I probably wouldn't go into the SWAP note (we could have a separate file section for this in the future). But I would get pretty detailed here - e.g., would use procedure names even (e.g., "note calls receive_assets procedure on an account).
4. Next, I would go into different transaction types (local vs. network).
   a. For local transactions, I would bring up delegated proving.
   b. For network transactions, we could even explain the example from the deck of how handling shared state works.
5. A section mentioning some limitations (e.g., at most 1K notes consumed/produced per transaction) and maybe performance data (a simple transaction takes about 90K cycles, signature verification is the dominant cost).

[Dominik1999]

Thanks @bobbinth. I changed the structure and mostly followed your approach. Let's not focus on the language now, but ensure we describe all protocol rules and provide sufficient examples to make it easy to follow.

Can you take a look, Bobbin, to see if we describe "Consuming a P2ID note" in the right depth?
In general, somewhere in the docs, we should also describe the current transaction kernel, including the memory layout, the procedures, and different contexts. But I am not sure if this makes sense before we have the Rust compiler.

@phklive can you take a stab at "Creating a P2ID note"?

[PhilippGackstatter]

Not a full review yet, but some initial comments.

[PhilippGackstatter]

I think we should give at least one or two examples for what this really means. As it is, I don't think readers can really grasp what this is supposed to mean.

[Dominik1999]

Thanks, I added some examples in the paragraph

[PhilippGackstatter]

This is just a suggestion, but I think explaining this flow would be best done by using a concrete example and then making generalized statements from there, rather than using just generalized statements.
For example, we could explain how a SWAP note with ETH/POL assets involving accounts from Alice/Bob would be executed, which could look something like this:

• Assuming Alice has created a swap note with ETH at this point and Bob wants to consume it and swap it against POL.
• Prologue: The note data, consisting of the SWAP note script and the ETH it contains, are loaded from the advice provider into the VM and are verified against the commitments of the transaction, INPUT_NOTES_COMMITMENT (concrete). The prologue does this for all data in the advice provider and verifies it against commitments that the transaction is executed against (generalized).
• Swap note execution
  • The transaction kernel executes the swap note's script, because it is the only note in the transaction (concrete). If there were other notes in the transaction those would be executed subsequently (generalized).
  • This loads the note's asset (ETH) from the note and transfers it to the account from Bob . This involves calls to kernel to get the note asset and calls to the interface of Bob's account. The note inputs are loaded which contains Alice's account ID. POL is taken from Bob's account and a note is created for Alice via a kernel call (concrete). Generally, a note script can call various kernel procedures to get the assets of the note or the block height of the chain. It can also call any account procedure of the account the transaction is executed against (generalized).

Something like this, just to give a sense of what I mean, with more or less detail as we desire. My main point is that I find it much easier to grasp stuff like this if there is a concrete example and we make abstract, generalizable statements from there. An example is also much more likely to stay in memory than an abstract statement, so the learning effect is greater as well.

[Dominik1999]

We tried to describe the general protocol and then provide an example for illustrative purposes. I also like your approach.

For now we changed it from a bullet list to descriptive paragraphs. Hopefully this reads clearer now.

[PhilippGackstatter]

to dynamically adjust the note's spent conditions.

I'm struggling a bit to understand what this is trying to say. I can make a guess, but I think for readers learning about the protocol for the first time, this should be clearer.

[Dominik1999]

I changed it to a list of inputs.

[PhilippGackstatter]

If the note script - and therefore the note creator - allows, the note script can read those arguments.

Genuine question: What does this refer to? In what way does the note script allow the note script (itself?) to read transaction arguments?

[Dominik1999]

I changed the formulation to

- **Transaction arguments (optional)**: For every note, the executor can inject transaction arguments that are present at runtime. If the note script - and therefore the note creator - allows, the note script can execute considering those arguments.

I provide an example at the end of the file:

> - Note and `Transaction` scripts can read the state of foreign accounts during execution. This is called foreign procedure invocation. For example, the price of an asset for the **Swap** script might depend on a certain value stored in the oracle account.
>
> - An example of the right usage of `Transaction` arguments is the consumption of a **Swap** note. Those notes allow asset exchange based on predefined conditions. Example:
    - The note's consumption condition is defined as "anyone can consume this note to take X units of asset A if they simultaneously create a note sending Y units of asset B back to the creator."
    - If an executor wants to buy only a fraction `(X-m)` of asset A, they provide this amount via transaction arguments. The executor would provide the value `m`.
    - The note script then enforces the correct transfer:
        - A new note is created returning `Y-((m*Y)/X)` of asset B to the sender.
        - A second note is created, holding the remaining `(X-m)` of asset A for future consumption.

[PhilippGackstatter]

I think this is missing a bit more details to make clear how someone would use this. Basically just mentioning that one transaction can create a note and another can consume it within the same batch/block (whichever one we want to mention here is fine) does not cause it to be registered on chain would be enough I think.

Also, here we call it ephemeral notes but in the protocol we call them unauthenticated notes. Personally, I would prefer ephemeral, but we should align on this.

[Dominik1999]

Excellent point, we should rename it in the code. Can you open an issue?

[Dominik1999]

I changed it to

- Usually, notes that are consumed in a `Transaction` must be recorded on-chain in order for the `Transaction` to succeed. However, in Miden there is the concept of **ephemeral notes** that can be consumed in a `Transaction` before being registered on-chain. This allows the executor to consume notes before they reach the blockchain. One can build a sub-second order book by allowing its traders to build faster transactions that depend on each other and are being validated or nullified in batches.

[bobbinth]

I'm not sure we need this as a separate section. Most of this should be covered when we describe transaction execution flow above. But we could have more "targeted" sections explaining things in additional details. For example, would could have a small section explaining "Transaction arguments" (could be 2 - 3 paragraphs).

[Dominik1999]

I put the Transaction inputs now before explaining the Transaction execution flow. I think the inputs are important to describe the rules the executor must adhere to executing a transaction.

[bobbinth]

Similar to the previous comment - not sure this needs to be a separate section. I think most info here should be incorporated into the description of transaction flow.

[Dominik1999]

Do you have a strong opinion about that? I changed the sub-chapter now to ### Difference between note and transaction scripts. It provides a bit more detail. We can incorporate it into the general flow.