Description

Bitwise operations such as AND, OR, and XOR, are not basic operations for felts.
The Bitwise builtin is an ad-hoc module to enable those common operations
and require implicit arguments.

Write a basic exercise to demonstrate how to use bit-wise in Cairo.

Resource:

• https://www.cairo-lang.org/docs/reference/common_library.html#common-library-bitwise

Acceptance criteria

• Add a common library exercise on bit-wise operation using builtins
• The contract compiles and tests pass
• An exercise patch is generated

Description

Felts can be used to pack multiple pieces of data more efficiently.
Show how to can encode and decode multiple variables in a felt using bitwise operations and bit masking.

Resource:

• https://www.cairo-lang.org/docs/reference/common_library.html#common-library-bitwise
• https://perama-v.github.io/cairo/background/integer_lift/

Acceptance criteria

• Add a bitwise exercise on data packing
• The contract compiles and tests pass
• An exercise patch is generated

Right now we have 5 beginners exercises, that cover:

• storage
• externals and views
• structures
• arrays and recursion
• basic revocated references occurences

I believe we can add a few more exercises to cover more of cairo features and edge cases.
Feel free to submit ideas about what you would like to see this tutorial cover in the future !

When adding a new section to the exercises, one must provide .patch files that contains the solutions
A tool to automatize the generation of such files would be welcome.
A shell script is probably the way to go here

Description

Show that Cairo uses the assert keyword for two purposes:

• Verifying a value against a memory location
• Assigning a value to a memory location

Resource:

• https://www.cairo-lang.org/docs/hello_cairo/intro.html#the-assert-statement
• https://www.cairo-lang.org/docs/how_cairo_works/consts.html#the-assert-statement-and-compound-expressions

Acceptance criteria

• The exercise shows different uses of assert
• The contract compiles and tests pass
• An exercise patch is generated

Description

A felt, field element, is the first class citizens in Cairo.
Write an exercise about the primitive type felt and the basic field operations it supports.

Resource:

• https://www.cairo-lang.org/docs/how_cairo_works/cairo_intro.html#field-elements

Acceptance criteria

• The exercise shows basic +, -, *, / operations on felts.
• The contract compiles and tests pass
• An exercise patch is generated

Currently when the CLI is executed from another folder than the repository, the error is not clear.
One must update this, by checking if the exercises can be reached.

Description

The native hash function in Cairo is the pedersen hash builtin.
Show how to use the hash2 function on multiple inputs.

Resource:

• https://www.cairo-lang.org/docs/how_cairo_works/builtins.html#introduction
• https://perama-v.github.io/cairo/cairo-common-library/#hash

Acceptance criteria

• The exercise show how to hash a message
• The contract compiles and tests pass
• An exercise patch is generated

Starkware has released a new version of the Cairo lang, version 0.8.2, we might want to update our dependency/exercises.

We can do this using the patch_and_test_exercises.sh script and check if it returned an error code or 0.

To discuss:
In the current implementation the script test that each exercise that have a patch, pass the test.
Maybe we instead want to check for each existing exercises if 1) it have a patch 2) it pass the tests once patched
Should it be blocking in order to guarantee that every added exercise is doable ?

Non-working binaries have been released in the past, which is not acceptable.

We must add a simple smoke test in the binary build workflow, running a simple --help would assure the binary at least runs without error.

Beginner section is a heritage from the Amsterdam workshop, and it would benefit from being split into thematic section based on what concept each exercise teaches.
This would help students work on a consistent pedagogical path.

Using patch objects, we can write unit test to verify the exercises all have a working solution.
https://github.com/techtonik/python-patch for example can be used.

Description

When displaying a solution with the command python starklings.py -s path/to/exercise.cairo, mid-file changes are applied one line above the actual changes which can break solutions.
This looks like an off-by-one issue in the patch library used in src/solutions.py

Acceptance criteria

• Patching an exercise file should give the same output as patch exercise.cairo solution.cairo -o -

First step is to check whether a release template would be useful, following the model there https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes
Second is to check if this can automatically done from the Github action creating the release: https://github.com/onlydustxyz/starklings/blob/main/.github/workflows/build_binaries.yml#L48

Hi,

Links in exercices are outadated, for example in beginner/ex01.cairo the link https://starknet.io/documentation/events/ should be replaced by : https://starknet.io/docs/hello_starknet/events.html

I'll do a PR if I have time to finish exercices 😅

Since Protostar is used directly as a Python package, the built binary fails at running.
This seems to be due to missing files that Protostar needs and are not packaged, namely cairo.ebnf.

One might take inspiration from protostar build configuration to figure out how they do.

We currently use a subprocess to call protostar, requiring the user to have protostar installed, which is unnecessary.
We can directly use Protostar as a library and call it to test our files.

If the user saves multiple times a file, and the checker is still running, a new checker will be spawned for each save, making the tool check concurrently the same file.
We need to have a single check at a time to make the experience smooth for the user.

1. loop through a list of exercises
2. parse each file
3. stop on the first having the "I'm not done" comment
4. Execute related test. And output Done / Not Done

We'd like to follow Rustlings practice by clearing the console output when the program communicates with the user, instead of always appending to the previous prints.
This will make the console more readable and the experience enhanced.

Some users face issues when running a too recent version of the tool because they did not update their local repo. We should check that the release commit is present in the local commit history when running the tool to make sure it will run smoothly.

Description

Create a recursion exercise on iteration over structs using arrays pointers.
The exercise should use MyStruct.SIZE in the loop call and recover the struct using type casting.

Resources:

• https://www.cairo-lang.org/docs/how_cairo_works/consts.html#typed-references
• https://www.cairo-lang.org/docs/how_cairo_works/consts.html#arrays

Acceptance criteria

• The exercise explains how to loop through a struct array using recursion
• The contract compiles and tests pass
• An exercise patch is generated

When the development team adds commits to the main branch, and the students git pull these changes without benefiting from an update of the CLI, they might encounter unwanted behaviour.
For example, removing the advanced exercises broke the CLI and needs a publish.

Description

The common library contains predefined functions to handle common math operations.
Such as <, <=, > 0, range checks, absolute value, felt division.
Provide an exercise to learn how to use those functions.

Resource:

• https://perama-v.github.io/cairo/examples/math/

Acceptance criteria

• The exercise showcase math common library functions
• The contract compiles and tests pass
• An exercise patch is generated

Current exercises are written in cairo, in a contracts folder. The test are written in python in the tests folder.

We want to replicate the process of Rustlings, so exercises must have their tests directly written in the exercise file, and organized in a exercises folder by pedagogic theme, such as storage or references for example.

Currently the mechanism used to display the solution is to apply a patch to the exercise file.
Whenever a change exists in the file, the patch is still applied on a modified file compared to what the patch is expecting.

A simple solution would be to git stash the file and then git stash pop once the solution is computed.

Description

Show how to create stark_keys using a randomly generated private key.
Cairo has a python module for generating key pairs on the Stark curve.

Resource:

• https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/crypto/starkware/crypto/signature/signature.py
• https://perama-v.github.io/cairo/examples/verify_ecdsa/

Acceptance criteria

• The exercise show how to create stark keys
• The contract compiles and tests pass
• An exercise patch is generated

Each exercise will be a Protostar test, the tool must run the test in order to complete the exercise.

Description

In Cairo, there are several natural ways of scanning array elements.
Provide an exercise on looping through an array in different traversal directions using recursion.

Now that we have a file watcher, and an exercise runner, we need to make them work together!

Description

Users can sign messages using their stark_key as seen on the key pair exercise.
Cairo implements the signing in python and the verification in Cairo.
Provide an exercise that verifies a generated signature using the ecdsa builtin.

Resource:

• https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/crypto/starkware/crypto/signature/signature.py
• https://perama-v.github.io/cairo/examples/verify_ecdsa/

Acceptance criteria

• The exercise show how to securely verify an ECDSA signature.
• The contract compiles and tests pass
• An exercise patch is generated

using this command (on a specific exercise or while in watch mode) will patch the exercise file with it's solution
steps:

• git restore -s origin/main <path to exercise file> (in order to get rid of any user modification and avoid conflicts)
• patch <path to exercise file> <path to corresponding patch file>

Many exercises related to low-level cairo can be added, like:

• low-level function calls, including:
  • retrieve function arguments / implicits / returns as a struct
  • how to pass arguments
  • how to retrieve arguments
• how to be generic with structs (handle structs as felt*)

Hello,
I can't display the solution for an exercise.
How to reproduce this issue:
get to the root of the repo,
Use the command : starklings -s exercises/recursions/recursion01.cairo

We need a python linter

Since protostar outputs changed with 0.2.0, we need to adapt the assertions we make in the wrapper around protostar.

Best solution would be to directly use the python API of Protostar, but we need the package to be published for that.

Description

Implement a basic exercise to understand how short strings are defined in Cairo

Acceptance criteria

• The exercise shows how Cairo handles felt-encoded strings
• The contract compiles and tests pass
• An exercise patch is generated

Recursions are a big part of the Cairo language, they must be introduced as exercises.

From basic recursions to the very common recursive pointer update pattern, exercises should cover the most encountered recursive patterns found in Cairo.

We realized that the first exercise of the beginner track lost a lot of students, so we are bringing a sequel in the form of a syntax theme.

Description

Hints are a very powerful tool when programming in Cairo, they allow deferring part of a computation to an external program.
With this great power comes the great responsibility of making sure the external computation is safe.

Write a basic exercise that demonstrate how to instantiate a variable inside a Cairo hint.

Resource:

• https://www.cairo-lang.org/docs/how_cairo_works/hints.html

Acceptance criteria

• The exercise uses Cairo hints
• The contract compiles and tests pass
• An exercise patch is generated

https://github.com/Textualize/textual ?

The current documentation is confusing between the two instructions sets, people wanting to use the tool tend to also install all the dev environment only required to contribute to the project.

Currently the --version command fails at printing the tool version and the Cairo lang version.
This might be an issue with the file path used to grab the version in the pyproject.toml file.

I've followed all the installation steps, but when I run starklings, the only command-line flags that are available are --help and --version. I'm running this all on a 2020 MacBook Pro (Intel). I have done the following

1. Install protostar
2. git clone https://github.com/onlydustxyz/starklings.git
3. cd starklings
4. curl -L https://raw.githubusercontent.com/onlydustxyz/starklings/master/install.sh | bash
   Am I doing something wrong here?

Exercises are currently checked in the binary directory, which is of very low interest for a real world use case.
Exercises should be modified by the user in its cloned repository.

These exercises where basically made for a workshop in Amsterdam, and do not really fit in the Starklings spirit anymore.

One should remove them.

Implicit arguments is a very powerful feature of the Cairo language, Starklings should integrate exercises about these.

We got several times the feedback that it would be nice to be able to preview the whole content of the exercises. Can be useful when you start to learn.