-
Notifications
You must be signed in to change notification settings - Fork 206
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: Added new topic: Serialization of types in Cairo #1041
Conversation
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
e377a76
to
52312c0
Compare
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
52312c0
to
89c5f6d
Compare
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
89c5f6d
to
043b6e7
Compare
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
043b6e7
to
3bc8692
Compare
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
3bc8692
to
d200aa4
Compare
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
d200aa4
to
4a148df
Compare
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
4a148df
to
1031cfb
Compare
1031cfb
to
569e5f8
Compare
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
1 similar comment
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
d9f9273
to
61cc256
Compare
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
1 similar comment
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
61cc256
to
29bb104
Compare
29bb104
to
bd4f2d2
Compare
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
1 similar comment
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Reviewable status: 0 of 4 files reviewed, 31 unresolved discussions (waiting on @ArielElp and @Mrericsumner)
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 223 at r10 (raw file):
Previously, ArielElp wrote…
The serialization of
MyStruct
is ...
Done.
1a22949
to
67caf26
Compare
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Reviewable status: 0 of 4 files reviewed, 32 unresolved discussions (waiting on @ArielElp and @Mrericsumner)
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 180 at r7 (raw file):
Previously, stoobie (Steve Goodman) wrote…
Well, the variant's value is only added in the match expression. Without it, I don't have an example of the full serialization of any variant...unless I misunderstand something. Let's talk in person about this.
I removed the match expressions.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 195 at r7 (raw file):
Previously, ArielElp wrote…
I don't see the change
Done.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 167 at r10 (raw file):
Previously, ArielElp wrote…
The
WeekEnd
enum is serialized as follows:
Done.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 150 at r13 (raw file):
enum Week { Sunday: (), // index=1, the variant type is the unit type Monday: u256, // index=2
@ArielElp The variant Monday
's type is u256
. How is that represented in serialization without assigning it a value?
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
1 similar comment
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
39dd112
to
8f7436d
Compare
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
8f7436d
to
b74fe98
Compare
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
b74fe98
to
e674148
Compare
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Reviewed 1 of 2 files at r3, 1 of 3 files at r5, 1 of 1 files at r6, 1 of 1 files at r15, all commit messages.
Reviewable status: all files reviewed, 23 unresolved discussions (waiting on @Mrericsumner and @stoobie)
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 14 at r7 (raw file):
Previously, stoobie (Steve Goodman) wrote…
I changed it to:
The following types are smaller than 252 bits. For these types, each value is serialized as a list that contains a single value, of type \`felt252\`.
Too cumbersome IMO, going back to your first suggestion: "a single-member list that contains one felt252
value".
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 2 at r15 (raw file):
[id="serialization_of_types_in_Cairo"] = Serialization of types in Cairo
Serialization of Cairo types (change in both title and bar on the left)
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 4 at r15 (raw file):
= Serialization of types in Cairo When you interact with contracts, especially if you are a library or SDK developer that wants to create transactions, you need to understand how Cairo handles types that are larger than 252 bits so you can correctly formulate the calldata in a transaction.
construct
Code quote:
create
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 56 at r15 (raw file):
A `u256` value in Cairo is represented by two `felt252` values, as follows: * The first `felt252` value contains the 128 most significant bits, usually referred to as the high part of the original `u256` value.
I was mistaken here, first comes low and then high, please replace the ordering between those two bullets
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 61 at r15 (raw file):
For example: * A `u256` variable whose decimal value is `2` is serialized as `[0,2]`. To understand why, examine the binary representation of `2` and split it into two 128-bit parts, as follows:
following the above, change to [2,0]
Code quote:
[0,2]
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 88 at r15 (raw file):
// |=== * A `u256` variable whose decimal value is `2^128^` is serialized as `[1,0]`. To understand why, examine the binary representation of `2^128^` and split it into two 128-bit parts, as follows:
[0,1]
Code quote:
`[1,0]`
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 96 at r15 (raw file):
++++ * A `u256` variable whose decimal value is `2^129^+2^128^+20`, is serialized as `[3,20]`. To understand why, examine the binary representation of the `2^129^+2^128^+20` and split it into two 128-bit parts, as follows:
[20,3]
Code quote:
[3,20]
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 130 at r15 (raw file):
++++ \underbrace{3}_{\textit{number_of_array_members}} , \underbrace{0,10}_{\textit{serialized_member_0}} ,
replace ordering - 0, 10 (same for the numbers below and the final serialization)
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 142 at r15 (raw file):
An enum is serialized as follows: `<__index_of_enum_variant__>,<__serialized_variant_type_and_value__>`
serialized_variant
(just like in the array section you say serialized_member_0, serialized_member_1, and not type/value, we only deal with values here - you're explaining how to serialize the type)
Code quote:
erialized_variant_type_and_value
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 144 at r15 (raw file):
`<__index_of_enum_variant__>,<__serialized_variant_type_and_value__>` .Example: Serialization in an enum 1
Example: enum serialization 1 / enum serialization 2
also, this title is in the middle while example 2 title is left aligned, change to the same inlining
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 150 at r15 (raw file):
enum Week { Sunday: (), // index=1, the variant type is the unit type Monday: u256, // index=2
index =2, the variant type is u256
Code quote:
index=2
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 164 at r15 (raw file):
|`Week::Sunday` | Index=`1`. The variant's type is the unit type. | `[1]` |`Week::Monday(5)` a| Index=`2`. The variant's type is `u256`.| `[2,0,5]`
2,5,0 (my u256 mistake)
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 201 at r15 (raw file):
For example, consider the following definition of the struct `MyStruct` and its instantiation as `struct`:
remove this (just MyStruct
definition is enough)
Code quote:
and its instantiation as `struct`
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 213 at r15 (raw file):
---- The calldata is the same for both of the following instantiations of the struct's variants:
members
Code quote:
variants
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 213 at r15 (raw file):
---- The calldata is the same for both of the following instantiations of the struct's variants:
serialization
Code quote:
calldata
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 219 at r15 (raw file):
a|[source,cairo] ---- let struct1 = MyStruct {
please call it my_struct in both examples (rather than struct1)
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 242 at r15 (raw file):
| `a: 2` | For information on serializing `u256` values, see xref:#serialization_in_u256_values[] | [`0,2`]
2,0
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 259 at r15 (raw file):
. *`data: Array<felt252>`* + Contains one or more `felt252` values, each containing a maximum of 31 bytes.
This is not true.
Contains 31-byte chunks of the byte array (i.e., each felt252
has exactly 31 bytes). If we have less than 31 bytes, then this array is empty.
Code quote:
Contains one or more `felt252` values, each containing a maximum of 31 bytes
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 262 at r15 (raw file):
. *`pending_word: felt252`* + The last, or only, value is a `felt252` value that represents the remainder of the byte array. It consists of at most 30 bytes.
The remainder bytes after filling the data
array with full 31 bytes chunks. Consists of at most 30 bytes.
Code quote:
The last, or only, value is a `felt252` value that represents the remainder of the byte array. It consists of at most 30 bytes.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 269 at r15 (raw file):
.Example 1: A string shorter than 31 characters Consider the string `hello`, which is represented by the 5-byte hex value `0x68656c6c6f`. The resulting byte array is serialized as follows:
whose ASCII encoding is given by
Code quote:
which is represented by
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Dismissed @Mrericsumner from a discussion.
Reviewable status: all files reviewed, 22 unresolved discussions (waiting on @ArielElp and @Mrericsumner)
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 14 at r7 (raw file):
Previously, ArielElp wrote…
Too cumbersome IMO, going back to your first suggestion: "a single-member list that contains one
felt252
value".
Done.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 2 at r15 (raw file):
Previously, ArielElp wrote…
Serialization of Cairo types (change in both title and bar on the left)
Done.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 4 at r15 (raw file):
Previously, ArielElp wrote…
construct
Done.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 56 at r15 (raw file):
Previously, ArielElp wrote…
I was mistaken here, first comes low and then high, please replace the ordering between those two bullets
Done.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 61 at r15 (raw file):
Previously, ArielElp wrote…
following the above, change to
[2,0]
That means that I have to swap lines 65 and 66. As well as all subsequent such examples
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 88 at r15 (raw file):
Previously, ArielElp wrote…
[0,1]
Done.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 96 at r15 (raw file):
Previously, ArielElp wrote…
[20,3]
Done.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 130 at r15 (raw file):
Previously, ArielElp wrote…
replace ordering - 0, 10 (same for the numbers below and the final serialization)
Done. PTAL
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 142 at r15 (raw file):
Previously, ArielElp wrote…
serialized_variant
(just like in the array section you say serialized_member_0, serialized_member_1, and not type/value, we only deal with values here - you're explaining how to serialize the type)
Changing to <__serialized_variant__>
, simillar to arrays.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 144 at r15 (raw file):
Previously, ArielElp wrote…
Example: enum serialization 1 / enum serialization 2
also, this title is in the middle while example 2 title is left aligned, change to the same inlining
Done.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 150 at r15 (raw file):
Previously, ArielElp wrote…
index =2, the variant type is
u256
Done.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 164 at r15 (raw file):
Previously, ArielElp wrote…
2,5,0 (my u256 mistake)
Done.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 201 at r15 (raw file):
Previously, ArielElp wrote…
remove this (just
MyStruct
definition is enough)
Done.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 213 at r15 (raw file):
Previously, ArielElp wrote…
members
Done.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 213 at r15 (raw file):
Previously, ArielElp wrote…
serialization
Done.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 219 at r15 (raw file):
Previously, ArielElp wrote…
please call it my_struct in both examples (rather than struct1)
Done.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 242 at r15 (raw file):
Previously, ArielElp wrote…
2,0
Done.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 259 at r15 (raw file):
Previously, ArielElp wrote…
This is not true.
Contains 31-byte chunks of the byte array (i.e., each
felt252
has exactly 31 bytes). If we have less than 31 bytes, then this array is empty.
Done. PTAL.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 262 at r15 (raw file):
Previously, ArielElp wrote…
The remainder bytes after filling the
data
array with full 31 bytes chunks. Consists of at most 30 bytes.
Edited your wording slightly to this.
The bytes that remain after filling the \
data` array with full 31-byte chunks. The pending word consists of at most 30 bytes.`
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 269 at r15 (raw file):
Changed to:
Consider the string
hello
, which is whose ASCII encoding is the 5-byte hex value0x68656c6c6f
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Reviewable status: all files reviewed, 22 unresolved discussions (waiting on @ArielElp and @Mrericsumner)
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 269 at r15 (raw file):
Oops, corrected to:
Consider the string
hello
, whose ASCII encoding is the 5-byte hex value0x68656c6c6f
.
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Reviewed 1 of 2 files at r16.
Reviewable status: 3 of 4 files reviewed, 7 unresolved discussions (waiting on @Mrericsumner and @stoobie)
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 14 at r7 (raw file):
Previously, stoobie (Steve Goodman) wrote…
Done.
two "a"
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 56 at r15 (raw file):
Previously, stoobie (Steve Goodman) wrote…
Done.
low is still the least significant bits, the change was only whose first and whose second
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 65 at r15 (raw file):
[stem] ++++ \underbrace{0\cdots0}_{\text{128 bits}} |
please revert, no need to change any latex
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 93 at r15 (raw file):
++++ \underbrace{0\cdots01}_{\text{128 bits}} | \underbrace{0\cdots0}_{\text{128 bits}}
please revert, no need to change any latex
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 100 at r15 (raw file):
[stem] ++++ \underbrace{0\cdots011}_{\text{128 bits}} \|
please revert, no need to change any latex
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 259 at r15 (raw file):
Previously, stoobie (Steve Goodman) wrote…
Done. PTAL.
The previous sentence still exists.
Also, string --> the number of bytes (byte arrays are the way to do string in Cairo but we can represent just a sequence of bytes which does not describe any ASCII string)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Reviewable status: 3 of 4 files reviewed, 7 unresolved discussions (waiting on @ArielElp and @Mrericsumner)
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 14 at r7 (raw file):
Previously, ArielElp wrote…
two "a"
Done
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 56 at r15 (raw file):
Previously, ArielElp wrote…
low is still the least significant bits, the change was only whose first and whose second
Done.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 65 at r15 (raw file):
Previously, ArielElp wrote…
please revert, no need to change any latex
Done
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 93 at r15 (raw file):
Previously, ArielElp wrote…
please revert, no need to change any latex
Done.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 100 at r15 (raw file):
Previously, ArielElp wrote…
please revert, no need to change any latex
Done.
components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/serialization_of_types_in_Cairo.adoc
line 259 at r15 (raw file):
Changed to:
If the number of bytes in the byte array is less than 31, then this array is empty.
Also deleted the previous string.
5dc19bd
to
89c0e03
Compare
Your preview build is ready! ✨ Check the following link in 1-2 minutes: https://starknet-io.github.io/starknet-docs/pr-1041/documentation/ . |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Reviewable status: 2 of 4 files reviewed, 2 unresolved discussions (waiting on @Mrericsumner)
Description of the Changes
Added new topic: Serialization of multi-member constructs
PR Preview URL
Serialization of types in Cairo
Check List
<docs/feat/fix/chore>(optional scope): <description>
, e.g:fix: minor typos in code
This change is