Skip to content
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

[parent] Documentation for Sierra libfuncs #25

Open
2 of 5 tasks
mazurroman opened this issue Jan 31, 2024 · 10 comments
Open
2 of 5 tasks

[parent] Documentation for Sierra libfuncs #25

mazurroman opened this issue Jan 31, 2024 · 10 comments
Assignees
Labels
documentation Improvements or additions to documentation

Comments

@mazurroman
Copy link
Contributor

mazurroman commented Jan 31, 2024

This is the parent task for Siera Libfuncs documentation.

List of child issues:

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

Sierra libfuncs definition

Source materials

NOT TRUSTED source materials — outdated / incorrect

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).

@mazurroman mazurroman changed the title Documentation for corelib libfuncs [draft] Documentation for corelib libfuncs Feb 8, 2024
@mazurroman mazurroman added the documentation Improvements or additions to documentation label Feb 16, 2024
@remybar
Copy link
Collaborator

remybar commented Feb 24, 2024

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
Copy link
Collaborator

remybar commented Feb 25, 2024

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
Copy link
Contributor Author

mazurroman commented Feb 25, 2024

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
Copy link
Collaborator

remybar commented Feb 25, 2024

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
Copy link
Collaborator

remybar commented Feb 25, 2024

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
Copy link

TAdev0 commented Feb 26, 2024

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
Copy link

TAdev0 commented Feb 26, 2024

@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
Copy link
Contributor Author

@barabanovro can you share more light on how Fallthrough works

@barabanovro
Copy link
Contributor

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.

@mazurroman mazurroman changed the title [draft] Documentation for corelib libfuncs Documentation for corelib libfuncs Feb 26, 2024
@remybar
Copy link
Collaborator

remybar commented Feb 27, 2024

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

@mazurroman mazurroman changed the title Documentation for corelib libfuncs [parent] Documentation for Sierra libfuncs Mar 6, 2024
@mazurroman mazurroman moved this from Triage to Todo in cairovm.codes Mar 6, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
Status: Todo
Development

No branches or pull requests

4 participants