search

walnuthq / cairovm.codes

Source code for cairovm.codes — a web app to compile Cairo programs into Sierra and CASM with step-through execution capabilities.
https://cairovm.codes
MIT License
29 stars 24 forks source link

[parent] Documentation for Sierra libfuncs #25

Open mazurroman opened 5 months ago

mazurroman commented 5 months ago

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

remybar commented 4 months ago

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 commented 4 months ago

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 commented 4 months ago

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 commented 4 months ago

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 commented 4 months ago

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 commented 4 months ago

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 commented 4 months ago

@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 commented 4 months ago

@barabanovro can you share more light on how Fallthrough works

barabanovro commented 4 months ago

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 commented 4 months ago

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