Updates to readme and cosmetic changes to figures #247

bazzilic · 2023-11-09T18:30:33Z

Some parts of our existing readme were quite outdated
Two illustrations we had in the readme were more or less the same illustration, so I only left one
Since there are time after time attempts to mock Taiga out, and there is rising interest in Taiga from the outside, I think it's appropriate to give a super condensed crash course on Taiga in the README
Added an example of a basic transaction in the end, will add some more in the future

XuyangSong

lgtm
Could you help review the updates? @vveiln @Acentelles @joebebel

XuyangSong · 2023-11-10T08:55:28Z

README.md

-The state transition is considered to be valid if validity predicates of 
-all involved parties are satisfied, and the Action circuit check passed 
-successfully.
+Taiga transactions consist of valid partial transactions (sometimes referred to as "intents"). Every partial transaction consists of exactly two input notes and two output notes. Output notes are crafted by the creator of the partial transaction. If a transaction gets executed, its output notes are "created": added to the merkle tree. A Partial transaction is considered valid if all programs (VPs) associated with the notes comprising it are valid (result in `true`). If we don't need all 4 note slots in a partial transaction, we can use "padding" notes: they are same as real notes, but have the `is_merkle_checked` flag set to `false`. Padding notes can also be used to describe the user intent by attaching an intent VP to it. Intent VP can describe arbitrarily complex logic of a valid state change: unless it is satisfied, the whole partial transaction would not be valid and therefore can't be part of a valid transaction.


we can use "padding" notes: they are same as real notes, but have the is_merkle_checked flag set to false.

Could we clarify the three names: padding, ephemeral, and dummy notes?
In the codebase, I use the "padding" to indicate a note with a FALSE is_merkle_checked flag and zero value(quantity). And padding notes are only used to pad when the number doesn't reach 2.
We used to call a note with a FALSE is_merkle_checked flag dummy or ephemeral. But the dummy in the Zcash protocol means a zero-value note. I lean to call it ephemeral.
The spec team might have the definition somewhere? @vveiln

It's a discussion that happens as long as I remember. I personally don't like the term ephemeral now, even though I suggested it in the first place 😄 at the time, I thought they only exist within a transaction and disappear without a trace, but then it turned out they still get their nullifiers and commitments added to the state for privacy purposes, so they are not as ephemeral as I thought! But if everyone agrees on ephemeral (or ghost 👻 notes!) that's fine.

Here I call them padding because that's what they are for. Ephemeral notes used for padding. I can see how this particular phrasing might seem like I add a new term, so i'll see how I can fix that.

I personally never liked to call them ephemeral, but this is what we call them in the spec right now, so I'd suggest to stick to ephemeral for now. We def shouldn't call them padding notes: they can be used for padding, but also for much more than just padding

vveiln

Overall lgtm, left a few comments

vveiln · 2023-11-10T10:06:57Z

README.md

-application rules, 
-and Taiga makes sure that the rules are being followed with the help of 
-the [Action circuit](./book/src/action.md).
+A [Note](./book/src/notes.md) represents an Anoma resource in Taiga. Notes are immutable and have a "denomination" and a non-negative value, among other fields. Every note has several executable programs (often referred to as [Validity Predicates](./book/src/validity-predicates.md) or VPs) associated with it. Input for programs is the notes plus a number of additional public and private inputs to the VPs. Taiga programs result in a state change, which includes a list of destroyed (or "nullified") notes and a list of newly created notes. Any existing note being input into a program gets destroyed. Destroying a note means revealing its nullifier, a secret value bound to the note. Note ownership is determined by knowledge of the nullifier plus arbitrary logic in a VP associated with the note. Creating a note means computing its commitment (a hash), and adding it to a merkle tree. The global state of Anoma is a hashset of note nullifiers and a commitment tree.


I would explain in a couple of words what you mean by "denomination", especially since you use " "

Every note has several executable programs

Doesn't have to be several, unless several can mean just one too

Input for programs is the notes

What notes and what is the purpose of those programs?

Taiga programs result in a state change,

Kinda vague enough to count as correct but still gives an incorrect vibe. They validate the proposed state change, don't create it

I feel like we should switch to "consume" instead of "destroy" but it is a low priority question

Note ownership is determined by knowledge of the nullifier plus arbitrary logic in a VP associated with the note.

Questionable. The difference is also somewhat vague, but I would say that note ownership = knowledge of the nullifier (although we might want to clarify the difference between the case when the nullifier is published and is known to everyone), but owning a note alone doesn't allow you to induce the state change (in that sense, the state change is "owned" by a VP, because in the end VPs define if the state is acceptable)

To address some of your questions, the purpose of this particular text is to be short and provide an intuitive overview of the whole lifecycle rather than be fully technically correct (we have specs for that).

They validate the proposed state change, don't create it

Not since transparent execution is part of Taiga too. Transparent VPs can create state changes.

switch to "consume" instead of "destroy"

Maybe in the specs, but this was a point that I didn't understand for a while in the beginning that "spent" or "consumed" notes essentially get destroyed.

I would say that note ownership = knowledge of the nullifier

I meant an (optional) user VP, which would provide an additional factor for authorizing spending the note.

Not since transparent execution is part of Taiga too. Transparent VPs can create state changes.

Hmm interesting. The whole idea of state change created by a predicate doesn't make sense to me, are transparent predicates still predicates?

Maybe in the specs, but this was a point that I didn't understand for a while in the beginning that "spent" or "consumed" notes essentially get destroyed.

I get what you mean, but this phrasing also confuses people. They think it literally stops existing, but it just becomes invalid (yet sort of exists in the form of cm/nf being stored). We can say destroyed for now, people are probably confused no matter what word we use 😅

I meant an (optional) user VP, which would provide an additional factor for authorizing spending the note.

I'm really nitpicking here, we don't have to specify this detail in the overview if it hinders more than it helps 🙂

are transparent predicates still predicates

We will know when transparent execution spec is finished! :D

becomes invalid

I can use the word "invalidated" probably

vveiln · 2023-11-10T10:17:38Z

README.md

-The state transition is considered to be valid if validity predicates of 
-all involved parties are satisfied, and the Action circuit check passed 
-successfully.
+Taiga transactions consist of valid partial transactions (sometimes referred to as "intents"). Every partial transaction consists of exactly two input notes and two output notes. Output notes are crafted by the creator of the partial transaction. If a transaction gets executed, its output notes are "created": added to the merkle tree. A Partial transaction is considered valid if all programs (VPs) associated with the notes comprising it are valid (result in `true`). If we don't need all 4 note slots in a partial transaction, we can use "padding" notes: they are same as real notes, but have the `is_merkle_checked` flag set to `false`. Padding notes can also be used to describe the user intent by attaching an intent VP to it. Intent VP can describe arbitrarily complex logic of a valid state change: unless it is satisfied, the whole partial transaction would not be valid and therefore can't be part of a valid transaction.


(sometimes referred to as "intents")

Intents being or not being partial transactions is a fight we should not bring up here. If we want to say something about intents, we should define them properly

added to the merkle tree.

Not just some merkle tree we have, the commitment tree

Padding notes can also be used to describe the user intent by attaching an intent VP to it.

And many other ways we didn't discuss probably. We shouldn't limit the purpose of these notes to two use cases. They could be used to pad or to carry intent vps, but they are not padding notes

vveiln · 2023-11-10T10:22:47Z

README.md

-The state transition is considered to be valid if validity predicates of 
-all involved parties are satisfied, and the Action circuit check passed 
-successfully.
+Taiga transactions consist of valid partial transactions (sometimes referred to as "intents"). Every partial transaction consists of exactly two input notes and two output notes. Output notes are crafted by the creator of the partial transaction. If a transaction gets executed, its output notes are "created": added to the merkle tree. A Partial transaction is considered valid if all programs (VPs) associated with the notes comprising it are valid (result in `true`). If we don't need all 4 note slots in a partial transaction, we can use "padding" notes: they are same as real notes, but have the `is_merkle_checked` flag set to `false`. Padding notes can also be used to describe the user intent by attaching an intent VP to it. Intent VP can describe arbitrarily complex logic of a valid state change: unless it is satisfied, the whole partial transaction would not be valid and therefore can't be part of a valid transaction.


I personally never liked to call them ephemeral, but this is what we call them in the spec right now, so I'd suggest to stick to ephemeral for now. We def shouldn't call them padding notes: they can be used for padding, but also for much more than just padding

vveiln · 2023-11-10T10:23:30Z

README.md


+Taiga transaction is valid if *1)* all contained partial transactions are valid; and *2)* the transaction is balanced: for every note denomination, the sum of values of all input notes of that denomination is equal to the sum of all output notes of the same denomination. A single partial transaction can be a valid transaction if it is valid.


A single partial transaction can be a valid transaction if it is valid

and balanced

Right, that's a typo 😄

bazzilic · 2023-11-14T12:27:54Z

I think I addressed most of the comments.

updates to readme and cosmetic changes to figures

66862e6

bazzilic requested a review from XuyangSong November 9, 2023 18:30

bazzilic added 3 commits November 10, 2023 02:31

typo

84b4fe4

links

b152714

small improvements

4779c4c

XuyangSong reviewed Nov 10, 2023

View reviewed changes

bazzilic requested review from Acentelles, vveiln and a user November 10, 2023 09:38

vveiln reviewed Nov 10, 2023

View reviewed changes

bazzilic added 2 commits November 14, 2023 19:54

update according to feedback

b68180e

[skip ci] updates to readme

6f32303

XuyangSong approved these changes Nov 14, 2023

View reviewed changes

bazzilic merged commit d4f2ae0 into main Nov 14, 2023

bazzilic deleted the vasily/readme branch November 14, 2023 14:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updates to readme and cosmetic changes to figures #247

Updates to readme and cosmetic changes to figures #247

bazzilic commented Nov 9, 2023

XuyangSong left a comment

XuyangSong Nov 10, 2023

bazzilic Nov 10, 2023

vveiln Nov 10, 2023

vveiln left a comment

vveiln Nov 10, 2023

vveiln Nov 10, 2023

vveiln Nov 10, 2023

vveiln Nov 10, 2023

vveiln Nov 10, 2023

vveiln Nov 10, 2023

bazzilic Nov 10, 2023 •

edited

Loading

vveiln Nov 10, 2023

bazzilic Nov 10, 2023

vveiln Nov 10, 2023

vveiln Nov 10, 2023

vveiln Nov 10, 2023

vveiln Nov 10, 2023

vveiln Nov 10, 2023

bazzilic Nov 10, 2023

bazzilic commented Nov 14, 2023


		Taiga transaction is valid if 1) all contained partial transactions are valid; and 2) the transaction is balanced: for every note denomination, the sum of values of all input notes of that denomination is equal to the sum of all output notes of the same denomination. A single partial transaction can be a valid transaction if it is valid.

Updates to readme and cosmetic changes to figures #247

Updates to readme and cosmetic changes to figures #247

Conversation

bazzilic commented Nov 9, 2023

XuyangSong left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vveiln left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bazzilic Nov 10, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bazzilic commented Nov 14, 2023

bazzilic Nov 10, 2023 •

edited

Loading