Skip to content

Commit d955bf3

Browse files
maciektrDelevoXDG
maciektr
and
DelevoXDG
authored
Add docs for execute, prove and verify, update docs (#2036)
fixes #1949 #1950 #1894 #2035 --------- Signed-off-by: maciektr <[email protected]> Co-authored-by: Maksim Zdobnikau <[email protected]>
1 parent bf30ab7 commit d955bf3

11 files changed

+326
-10
lines changed

‎website/.vitepress/config.mjs

+6
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,19 @@ const sidebar = {
2525
p("Formatting", "/docs/guides/formatting"),
2626
p("Defining custom profiles", "/docs/guides/defining-custom-profiles"),
2727
p("Defining custom scripts", "/docs/guides/defining-custom-scripts"),
28+
p(
29+
"Creating executable package",
30+
"/docs/guides/creating-executable-package",
31+
),
2832
p("Using Scarb in CI", "/docs/guides/using-scarb-in-ci"),
2933
],
3034
},
3135
{
3236
text: "Core extensions",
3337
items: [
3438
p("Testing", "/docs/extensions/testing"),
39+
p("Execute", "/docs/extensions/execute"),
40+
p("Prove and verify", "/docs/extensions/prove-and-verify"),
3541
p("Cairo runner", "/docs/extensions/cairo-run"),
3642
{
3743
text: "Starknet",

‎website/constants.data.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
export default {
22
load() {
33
return {
4-
edition: "2023_10",
4+
edition: "2024_07",
55
};
66
},
77
};

‎website/docs/extensions/cairo-run.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,11 @@
22
import { data as rel } from "../../github.data";
33
</script>
44

5-
# Using cairo-run in Scarb projects
5+
# Using cairo-run in Scarb projects <Badge type="warning" text="deprecated" />
6+
7+
> [!WARNING]
8+
> Scarb cairo-run is scheduled for deprecation in unspecified future.
9+
> Please use [`scarb execute`](./execute.md) instead.
610
711
The `scarb cairo-run` command executes a function from a local package.
812
It does automatically compile the cairo code within the package so using `scarb build` beforehand is not necessary.

‎website/docs/extensions/execute.md

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
<script setup>
2+
import { data as rel } from "../../github.data";
3+
</script>
4+
5+
# Scarb execute
6+
7+
The `scarb execute` command executes a function from a local package.
8+
It does automatically compile the Cairo code within the package so using `scarb build` beforehand is not necessary.
9+
If `scarb build` or `scarb execute` has been previously used and the package hasn't changed since,
10+
this automatic build can be optionally skipped with the `--no-build` flag.
11+
Only packages defining the [executable target](../reference/targets#executable-target) can be executed.
12+
13+
## Choosing a function to run
14+
15+
If your package defines multiple main functions (see [choosing the main function](../reference/targets#choosing-the-main-function)),
16+
you need to specify which executable target should be run.
17+
18+
This can be achieved through one of two flags:
19+
20+
- `--executable-name` to choose the target by its name.
21+
- `--executable-function` to choose the target by the main function it defines.
22+
23+
Those flags are mutually exclusive.
24+
25+
## Saving the execution information
26+
27+
The execution will be carried out for one of two execution targets: `standalone` or `bootloader`.
28+
You can choose the target with the `--target` flag:
29+
30+
- **Standalone**: executes program as-is, execution is intended to be directly proven with `scarb prove`.
31+
- **Bootloader**: program’s execution is expected to be wrapped by
32+
the [bootloader’s](https://github.com/Moonsong-Labs/cairo-bootloader?tab=readme-ov-file#cairo-bootloader) execution,
33+
which itself will be proven via Stwo.
34+
35+
See more on [proving and verifying execution](./prove-and-verify.md) page.
36+
37+
## Resource usage and program output
38+
39+
To print the Cairo program output, you can use the `--print-program-output` flag.
40+
Otherwise, the output will be discarded.
41+
42+
To print detailed execution resources usage, you can use the `--print-resource-usage` flag.
43+
This will show information about:
44+
45+
- `n_steps`
46+
- `n_memory_holes`
47+
- `builtin_instance_counter`
48+
- `syscalls`
49+
50+
In case your Cairo program panics, the panic reason will be shown on the output, and the program will exit with a
51+
non-zero exit code.
52+
53+
## Program arguments
54+
55+
The executable function may accept arguments.
56+
They can be passed to the `scarb execute` command via either `--arguments` or `--arguments-file` flag.
57+
58+
The expected input with `--arguments` is a comma-separated list of integers.
59+
This list should correspond to the Cairo’s Serde of main’s arguments, for example:
60+
61+
| main’s signature | valid arguments example | valid arguments file contents example |
62+
| :------------------------------------- | :---------------------- | :------------------------------------ |
63+
| `fn main(num: u8)` | 1 | ["0x1"] |
64+
| `fn main(num1: u8, num2: u16)` | 1,27 | ["0x1", "0x1b"] |
65+
| `fn main(num1: u8, tuple: (u16, u16))` | 1,2,27 | ["0x1", "0x2", "0x1b"] |
66+
| `fn main(num1: u8, num2: u256)` | 1,2,27 | ["0x1", "0x2", "0x1b"] |
67+
| `fn main(num1: u8, arr: Array<u8>)` | 1,2,1,2 | ["0x1", "0x2", "0x1", "0x2"] |
68+
69+
Note that when using `--arguments-file`, the expected input is an array of felts represented as hex string.
70+
See the [documentation](https://docs.starknet.io/architecture-and-concepts/smart-contracts/serialization-of-cairo-types/) for more information about Cairo’s Serde.

‎website/docs/extensions/prove-and-verify.md

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Proving and verifying execution
2+
3+
> [!WARNING]
4+
> Soundness of the proof is not yet guaranteed by Stwo, use at your own risk!
5+
6+
> [!WARNING]
7+
> The prover is not available on Windows. Sorry for your inconvenience.
8+
9+
> [!WARNING]
10+
> The `stwo-cairo` prover can be significantly slower when used through Scarb.
11+
> See [performance](#Performance) section.
12+
13+
Scarb integrates the [`stwo-cairo` prover](https://github.com/starkware-libs/stwo-cairo) which can be used through `scarb prove`
14+
and `scarb verify` commands.
15+
16+
## Proving Cairo execution
17+
18+
Only packages defining the [executable target](../reference/targets.md/#Executable-target) can be proven.
19+
To prove the execution, you need to run the `scarb execute` command first, which will save execution information under the `target/execute/<target name>` directory.
20+
For each execution, a new output directory will be created, with consecutive number as names (e.g. `execution1`, `execution2`, ...).
21+
To clean the target directory, you can use the `scarb clean` command.
22+
23+
To prove the execution, you can run:
24+
25+
```shell
26+
scarb prove --execution-id <index of the relevant execution>
27+
```
28+
29+
You can also run `scarb prove` with the `--execute` flag, which will run the `scarb execute` command automatically
30+
before proving the execution for you.
31+
When running with `--execute` flag, you can specify the same arguments as for `scarb execute` command.
32+
See [`scarb execute`](./execute.md) documentation for more information.
33+
34+
The proof for the trace files inside the execution folder will be generated, and a `proof.json` file will be placed inside the execution directory.
35+
36+
## Verifying Cairo proof
37+
38+
To verify the proof, you can run:
39+
40+
```shell
41+
scarb verify <path to proof json file>
42+
```
43+
44+
## Performance
45+
46+
The `stwo-cairo` prover can highly benefit from platform specific optimizations, that are not available when Scarb
47+
is run from a precompiled binary.
48+
For the best performance, it is recommended to build `scarb-prove` and `scarb-verify` crates from source,
49+
with following compilation flags: `RUSTFLAGS="-C target-cpu=native -C opt-level=3" --features="std"`.
50+
To use manually compiled binaries with Scarb, replace the `scarb-prove` and `scarb-verify` binaries in the Scarb
51+
installation directory, or add them to the `PATH` environment variable **before** any other Scarb related binaries.
52+
For production use, it is recommended to use the `stwo-cairo` prover directly.

‎website/docs/guides/creating-executable-package.md

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
<script setup>
2+
import { data as rel } from "../../github.data";
3+
import {data as constants} from "../../constants.data";
4+
</script>
5+
6+
## Defining an Executable Package
7+
8+
Start a new Scarb project with `scarb new <project_name>`.
9+
In your `Scarb.toml` file:
10+
11+
1. Set the package to compile to a Cairo executable by adding `[executable]` (note that `lib` or `starknet-contract` targets cannot be executed in this way).
12+
2. Add the `cairo_execute="{{ rel.stable.starknetPackageVersionReq }}"` plugin to your dependencies.
13+
3. Disable gas usage by adding `enable-gas = false` under the `[cairo]` section (gas is only supported for `lib` or `starknet-contract` targets).
14+
15+
Below we have an example of the manifest file of a simple executable
16+
17+
```
18+
[package]
19+
name = "test_execute"
20+
version = "0.1.0"
21+
edition = "{{ constants.edition }}"
22+
23+
[[target.executable]]
24+
25+
[cairo]
26+
enable-gas = false
27+
28+
[dependencies]
29+
cairo_execute = "{{ rel.stable.starknetPackageVersionReq }}"
30+
```
31+
32+
Now we can move on to the code itself. An executable project must have **exactly one function** annotated with the `#[executable]` attribute. Consider the following simple `lib.cairo` file of an executable project:
33+
34+
```
35+
#[executable]
36+
fn main(num: u8) -> u8 {
37+
num
38+
}
39+
```
40+
41+
You can now run:
42+
43+
```
44+
scarb execute -p test_execute --print-program-output --arguments 5
45+
```
46+
47+
Where `test_execute` is the name of the package with the executable target (as defined in our Scarb.toml manifest).
48+
49+
The above command runs our executable function within the `test-execute` package and prints the program's output segment.
50+
51+
The execution information will be saved under the `target/execute/<target name>` directory.
52+
For each execution, a new output directory will be created, with consecutive number as names (e.g. `execution1`, `execution2`, ...).
53+
To clean the target directory, you can use the `scarb clean` command.
54+
55+
For more information see detailed [`scarb execute`](../extensions/execute.md) documentation.

‎website/docs/reference/manifest.md

+19-5
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
<script setup>
22
import {data as constants} from "../../constants.data";
3+
import { data as rel } from "../../github.data";
34
</script>
45

56
# The Manifest Format
@@ -85,20 +86,25 @@ publish = true
8586

8687
### `cairo-version`
8788

88-
The `cairo-version` field is an optional key that tells Scarb what version of the Cairo language and compiler your
89-
package can be compiled with.
89+
The `cairo-version` field is an optional key that tells Scarb what range of versions of the Cairo language and compiler
90+
your package can be compiled with.
9091
If the currently running version of the Scarb compiler does not match this requirement, Scarb will exit with an error,
9192
telling the user what version is required.
9293
This field takes a [semver version requirement](./specifying-dependencies#version-requirements).
9394

9495
```toml
9596
[package]
96-
cairo-version = "1.0.0"
97+
cairo-version = "^{{ rel.preview.version }}"
9798
```
9899

99100
Setting the `cairo-version` key in `[package]` will affect all targets in the package.
101+
100102
The value in this field will not affect the version of the compiler run by Scarb.
101103
Scarb always uses its built-in version of the Cairo compiler.
104+
It will instead show an error message to the user if the version of the Cairo compiler is not compatible with the project.
105+
106+
Checking Cairo version requirements can be skipped with `--ignore-cairo-version` argument.
107+
Scarb will attempt to compile the project disregarding this field, even if it's not compatible with the builtin compiler version.
102108

103109
### `include`
104110

@@ -332,8 +338,7 @@ The possible values are `default` or `avoid`.
332338
If `avoid` strategy is set, the compiler will only inline function annotated with `#[inline(always)]` attribute.
333339

334340
> [!WARNING]
335-
> Using the `avoid` strategy may result in a slower execution of the compiled code and significantly larger artefacts
336-
> size.
341+
> Using the `avoid` strategy may result in a slower execution of the compiled code.
337342
> Please use with caution, only if your tooling requires that.
338343
> You can use profile settings overwriting, for more granular control of which builds use the avoid strategy.
339344
@@ -388,6 +393,15 @@ See [Scripts](./scripts) page.
388393

389394
## `[tool]`
390395

396+
> [!WARNING]
397+
> In context of a workspace, the `[tool]` section still needs to be defined on the package to take effect.
398+
> Packages can inherit `tool` section from workspace manifest, but only explicitly.
399+
> See [Workspaces](./workspaces#tool) page for more detailed information.
400+
401+
> [!WARNING]
402+
> Profiles can be used to change values defined in `[tool]` section.
403+
> See [Profiles](./profiles#overriding-tool-metadata) page for more detailed information.
404+
391405
This section can be used for tools which would like to store package configuration in Scarb.toml.
392406
Scarb by default will warn about unused keys in Scarb.toml to assist in detecting typos and such.
393407
The `[tool]` table, however, is completely ignored by Scarb and will not be warned about.

‎website/docs/reference/scripts.md

+5
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,11 @@ bar = "echo 'World!'"
1818
This section should not contain any values with type different from string, including subtables, arrays, or numbers.
1919
In case the section is empty, it will be ignored.
2020

21+
> [!WARNING]
22+
> In context of a workspace, the `[scripts]` section still needs to be defined on the package to take effect.
23+
> Packages can inherit `scripts` section from workspace manifest, but only explicitly.
24+
> See [Workspaces](./workspaces#scripts) page for more detailed information.
25+
2126
### Special script names
2227

2328
Some script names are reserved for special purposes and their execution might be associated with additional logic.

0 commit comments

Comments
 (0)