[parent] Documentation for Sierra libfuncs

[mazurroman]

This is the parent task for Siera Libfuncs documentation.

List of child issues:

• [doc] core libfuncs - implement the page skeleton #67
• [doc] core libfuncs - write the documentation #68
• [doc] core libfuncs : alloc_local + array related libfuncs #69
• [doc] core libfuncs - bitwise , bool related libfuncs, box_forward_snapshot, branch_align and bytes31 related libfuncs #70
• [doc] core libfuncs - elliptic curve related libfuncs #71

Google doc with libfuncs documentation
https://docs.google.com/document/d/1Co0Rms68InGbPfp2xWckdrCuom0wIYPmDwWKXimESc0/edit

Sierra libfuncs definition

• https://github.com/starkware-libs/cairo/blob/82d75ae81da57010ef44a945c0387835dfed9a0e/crates/cairo-lang-starknet/src/allowed_libfuncs_lists/experimental.json
• https://github.com/starkware-libs/cairo/blob/82d75ae81da57010ef44a945c0387835dfed9a0e/crates/cairo-lang-starknet/src/allowed_libfuncs_lists/audited.json

Source materials

NOT TRUSTED source materials — outdated / incorrect

• https://github.com/sierra-docs/sierra-docs.github.io deployed here: https://sierra-docs.github.io/

More context

Inspiration for this task started with this message from Eni Telegram:

would be nice to have an accessible way of knowing the inner structure / behavior of everything that's in there, like what's the bit struture of a signed integer? how can I safely do conversions using this type? what does checked_mul do exactly?

A lot of stuff can be guessed from names / return types but it's not always crystal clear, improving on this would make cairo more accessible to newcomers, especially if it comes with a website to consult core functions and traits

perhaps we can launch a community effort around this (cc @AbdelStark 👀)

Design
We could have a table similar to the Instructions table at evm.codes homepage. Each table item can be expanded and provide more details (try it on evm.codes).

[remybar]

Here, the idea is to create a table of every sierra libfuncs in a same way than the OPCODE table on evm.codes, right ? So, a table of libfuncs names and their short description and show a lot of details when we click on a libfunc (like inputs/outputs, errors, ...).

I can start working on it in background 👍
Do you have any resource to share ? Like a list of existing libfuncs for example :-)

[remybar]

Ok, I found this list which is audited libfuncs: https://github.com/starkware-libs/cairo/blob/82d75ae81da57010ef44a945c0387835dfed9a0e/crates/cairo-lang-starknet/src/allowed_libfuncs_lists/audited.json

It should be a good start point :-)

[mazurroman]

Hey @remybar glad to hear you're up for this one :) According the link you shared there are 128 Sierra libfuncs as of today. It would be good to split the documentation work into multiple issues for better tracking, and also to allow multiple people work on it.

What about one issue for 10 libfuncs? Or do you have a different suggestion how to split the work?

[remybar]

Hey @remybar glad to hear you're up for this one :) According the link you shared there are 128 Sierra libfuncs as of today. It would be good to split the documentation work into multiple issues for better tracking, and also to allow multiple people work on it.

What about one issue for 10 libfuncs? Or do you have a different suggestion how to split the work?

Yes, good idea 👍
I would create a "parent" issue to create the structure of this page and several "child" issues to fill the page. We can probably split the list in some categories like "array", "storage", "uint", etc ... as several functions look pretty similar.

I can do that tomorrow and I can start working on the page structure.

[remybar]

Note that there is also an experimental list with a lot of functions too 😅
https://github.com/starkware-libs/cairo/blob/82d75ae81da57010ef44a945c0387835dfed9a0e/crates/cairo-lang-starknet/src/allowed_libfuncs_lists/experimental.json

But let's start with audited functions first ;-)

[TAdev0]

hey @remybar @mazurroman
I started working on it today as well, just sent a gdoc to Roman as we discussed one or two weeks ago.
Good idea to split it into multiple issues

Btw, experimentals are almost the same as audited, there is a just a few differences, less than 10 libfuncs

[TAdev0]

@remybar here is the gdoc so you can check

https://docs.google.com/document/d/1Co0Rms68InGbPfp2xWckdrCuom0wIYPmDwWKXimESc0/edit

Still not sure about how the ''Fallthrough'' mechanism works (for array_get for example)

[mazurroman]

@barabanovro can you share more light on how Fallthrough works

[barabanovro]

Hey @TAdev0

The program executes the next statement through the fall-through branch, storing the libfunc results (output refs) in variables inside round brackets.

As for the array_get libfunc, by looking into Sierra statements and the variables-to-values map, I discovered that we get these values in result branches: { fallthrough([<RangeCheck>], [Box<T>]) 27([<RangeCheck>]) }, where Box<T> is the element at the given index.

[remybar]

I've found this github which contains some documentation of Sierra libfuncs:

• https://github.com/sierra-docs/sierra-docs.github.io
• deployed here: https://sierra-docs.github.io