Zkllvm outdated info #48

khannanov-nil · 2024-05-21T06:57:45Z

This PR removes all outdated info from zkLLVM docs and replaces it with newly written how-tos

Changelog:

Added a new page (Structs and enums in Rust) to Best practices and limitations. The page describes how to avoid field reordering when compiling Rust code (see Rust compiler reorders fields in structures zkLLVM#607) for details
Added a new Use cases section containing how-tos for advanced users
Added a new page (Primer) to Use cases. The page briefly explains how to use CMake and Cargo for dependency management
Added a new how-to series (Create a zkBridge) to Use cases. The content is mostly taken from existing examples (some circuits are still written from scratch) but with additional explanations and formattings

vercel · 2024-05-21T06:57:48Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
docs-nil-foundation	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 23, 2024 9:15am

makxenov · 2024-05-21T12:14:36Z

zkllvm/use-cases/primer.mdx

+mkdir cmake && cd cmake
+```
+
+Add the [**`CircuitCompile.cmake` module from the zkLLVM repository**](https://github.com/NilFoundation/zkLLVM/blob/master/cmake/CircuitCompile.cmake) to the `./new_circuit/cmake` directory:


SInce we require zkllvm package to be installed, CircuitCompile.cmake is a part of it, so the copying is not necessary, we can simply adjust module path to its fixed location:

list(APPEND CMAKE_MODULE_PATH "/usr/lib/zkllvm/share/zkllvm")

I guess find_package(zkllvm) works here, isn't it? So user won't need to hardcode the path

No, it does not work.

Hmm, that's weird, how am I supposed to ship cmake modules then through apt packages...

@makxenov I see, this makes more sense! I've revised the flow and the CMake config to mention this

makxenov · 2024-05-21T12:31:32Z

zkllvm/use-cases/primer.mdx

+find_package(crypto3 REQUIRED)
+```
+
+:::tip[Boost]


I would omit this tip. Boost is an internal dependency of crypto3, so crypto3::all target is responsible for providing it. We should not care about it here unless our circuit uses Boost directly. But in this case Boost does not deserve a special mention, because it's equal to any alternative library.

Alright, this makes sense. I have removed the tip

makxenov · 2024-05-21T12:31:59Z

zkllvm/use-cases/primer.mdx

+    circuit SOURCES ${SOURCES}
+    LINK_LIBRARIES
+    crypto3::all
+    ${Boost_LIBRARIES}


Same here, please remove this line.

agreed, removed

makxenov · 2024-05-21T12:34:17Z

zkllvm/use-cases/primer.mdx

+    ${Boost_LIBRARIES}
+)
+
+set(binary_name circuit.ll)


Setting a variable but not using it after looks a little bit strange. Maybe replace it with a comment: "add_circuit() will generate IR with name circuit.ll"?

Yes, you're right. I have amended this part

makxenov · 2024-05-21T12:43:47Z

zkllvm/use-cases/primer.mdx

+cmake -G "Unix Makefiles" -B ./build -DCMAKE_BUILD_TYPE=Release . -Dcrypto3_DIR=/path/to/crypto3/installation
+```
+
+This method is useful if a dependency is installed in a custom location rather than `/usr/local/` or any other location requiring root permissions.


Actually the permissions of a directory make no difference in specifying the path. I would say that this method could be useful in case if crypto3_DIR is not fixed (for example, a user is writing a script that installs circuit dependencies and then calls cmake), and one doesn't want to hardcode path in a file.

Thank you, I have revised the explanation

makxenov · 2024-05-21T12:48:18Z

zkllvm/use-cases/zk-bridge/hashes.mdx

+
+# Write a circuit with hashes
+
+This 'how-to' series constructs a 'mock' zero knowledge bridge from scratch. The series starts with writing a simple circuit that uses hashes and ends with creating an algorithm for state-proof verification.


Maybe I'm wrong, but usually zero-knowledge contains hyphen when using as an adjective.

You are 100% right, I've added the hyphen

makxenov · 2024-05-21T12:57:24Z

zkllvm/use-cases/primer.mdx

+Add the required library to the project configuration:
+
+```cmake
+set(crypto3_DIR "path/to/crypto3_headers")


Let's emphasize here that we need a /path/to/crypto3/installation. Headers are not enough, cmake must be able to find crypto3Config.

I see, I changed the path description

akokoshn · 2024-05-21T13:23:07Z

zkllvm/use-cases/zk-bridge/hashes.mdx

+    [[circuit]] bool verify_protocol_state_proof (
+        typename sha2<256>::block_type last_confirmed_block_hash,
+        std::array<block_data_type, 2> unconfirmed_blocks) {
+        for (int i = 0; i < 2; i++) {


Please don't use if where it possible

bool res = is_same(unconfirmed_blocks[i].prev_block_hash, last_confirmed_block_hash); typename sha2<256>::block_type evaluated_block_hash = hash<sha2<256>>(unconfirmed_blocks[i-1].prev_block_hash, unconfirmed_blocks[i-1].data); return res & is_same(unconfirmed_blocks[i].prev_block_hash, evaluated_block_hash);

thank you, I have rewritten the circuit function to eliminate the nested if

aleasims · 2024-05-21T23:05:38Z

Found a typo, which we missed in previous review: here.

Instead of & it have to be &&

aleasims · 2024-05-21T23:11:30Z

zkllvm/best-practices-limitations/rust-derive.mdx

+
+Whenever a Rust circuit is compiled, `rustc` applies various optimizations to reduce its memory usage.
+
+Among these memory optimizations is [**reordering fields in structs and enums to avoid unnecessary 'paddings' in circuit IRs**](https://users.rust-lang.org/t/disable-struct-reordering-optimization-when-emitting-llvm-bitcode/74951). Consider the following example:


I don't think it is a good idea to link to some random forum post in docs. If we really want to leave a link here, maybe it's better to link to Rust docs:

https://doc.rust-lang.org/reference/type-layout.html#representations

Or at to Nomicon:

https://doc.rust-lang.org/nomicon/repr-rust.html

you are 100% right. I failed to find a proper explanation of this specific problem but now the link is fixed

aleasims · 2024-05-21T23:12:40Z

zkllvm/best-practices-limitations/rust-derive.mdx

+To avoid this problem, use the `#[repr(C)]` directive:
+
+```rust
+#[derive(Copy, Clone)]


Missing #[repr(C)]

typo, added it back in

aleasims · 2024-05-21T23:15:22Z

zkllvm/best-practices-limitations/rust-derive.mdx

+
+Among these memory optimizations is [**reordering fields in structs and enums to avoid unnecessary 'paddings' in circuit IRs**](https://users.rust-lang.org/t/disable-struct-reordering-optimization-when-emitting-llvm-bitcode/74951). Consider the following example:
+
+```rust


It's not necessary, but maybe for demonstration purposes we can construct smaller example? This one is a bit too big than needed to illustrate the issue and probably it will be a bit harder for users to get the point.

Sure, I've simplified the example

aleasims · 2024-05-21T23:32:55Z

zkllvm/use-cases/zk-bridge/hashes.mdx

+            true
+        }
+    }
+    ```


The code of the function is wrong. Here is the fixed version:

fn verify_protocol_state_proof( last_confirmed_block_hash: Fq, unconfirmed_blocks: [BlockDataType; 2], ) -> bool { for i in 0..2 { if i == 0 { if !is_same(unconfirmed_blocks[i][0], last_confirmed_block_hash) { return false; } } else { let evaluated_block_hash = hash(unconfirmed_blocks[i - 1][0], unconfirmed_blocks[i - 1][1]); if !is_same(unconfirmed_blocks[i][0], evaluated_block_hash) { return false; } } } true }

you're right, a mix-up on my part

in any case, the function is now rewritten from scratch

aleasims · 2024-05-21T23:36:39Z

zkllvm/use-cases/zk-bridge/hashes.mdx

+
+    #[circuit]
+    #[unroll_for_loops]
+    fn verify_protocol_state_proof(


The same. Fixed version above

aleasims · 2024-05-21T23:43:51Z

zkllvm/use-cases/zk-bridge/zkbridge.mdx

+
+:::info[Rust directives]
+
+The `#[derive(Copy, Clone)]` makes it so that circuit code does not unintentionally take ownership of variables that are supposed to be changed/used later.


I'm not sure, what do you mean by that

…e directives

SKHDev195 added 4 commits May 15, 2024 15:59

primer added, how-to guides cont

2a118e0

added rust info to primer, hashes done

067e97f

cpp zkbridge added, need to add rust

e2a5311

use cases proofread, rust directives added to limitations

5014585

khannanov-nil added the documentation Improvements or additions to documentation label May 21, 2024

khannanov-nil requested review from akokoshn, aleasims and makxenov May 21, 2024 06:57

khannanov-nil self-assigned this May 21, 2024

makxenov reviewed May 21, 2024

View reviewed changes

akokoshn suggested changes May 21, 2024

View reviewed changes

aleasims reviewed May 21, 2024

View reviewed changes

addressed comments in primer

033eec0

vercel bot deployed to Preview May 22, 2024 05:51 View deployment

makxenov approved these changes May 22, 2024

View reviewed changes

addressed comments in hashes

1765011

vercel bot deployed to Preview May 22, 2024 07:30 View deployment

addressed comments in zkbridge and added logical AND to hashes

46ac51e

vercel bot deployed to Preview May 22, 2024 07:54 View deployment

addressed comments in Rust structs

0fc4c84

vercel bot deployed to Preview May 22, 2024 08:10 View deployment

example fix

e86539c

vercel bot deployed to Preview May 22, 2024 08:13 View deployment

khannanov-nil requested review from aleasims and akokoshn May 22, 2024 08:14

changed final Rust circuit to use refs in most functions, removed som…

e0cb199

…e directives

vercel bot deployed to Preview May 23, 2024 05:51 View deployment

akokoshn approved these changes May 23, 2024

View reviewed changes

removed unnecessary directives in Rust structs and enums

5b81f1d

vercel bot deployed to Preview May 23, 2024 09:15 View deployment

aleasims approved these changes May 23, 2024

View reviewed changes

khannanov-nil merged commit d380210 into master May 23, 2024
2 checks passed

khannanov-nil deleted the zkllvm-outdated-info branch May 23, 2024 09:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Zkllvm outdated info #48

Zkllvm outdated info #48

khannanov-nil commented May 21, 2024 •

edited

Loading

vercel bot commented May 21, 2024 •

edited

Loading

makxenov May 21, 2024

aleasims May 21, 2024

makxenov May 21, 2024

aleasims May 21, 2024

khannanov-nil May 22, 2024

makxenov May 21, 2024

khannanov-nil May 22, 2024

makxenov May 21, 2024

khannanov-nil May 22, 2024

makxenov May 21, 2024

khannanov-nil May 22, 2024

makxenov May 21, 2024

khannanov-nil May 22, 2024

makxenov May 21, 2024

khannanov-nil May 22, 2024

makxenov May 21, 2024

khannanov-nil May 22, 2024

akokoshn May 21, 2024

khannanov-nil May 22, 2024

aleasims commented May 21, 2024 •

edited

Loading

aleasims May 21, 2024

khannanov-nil May 22, 2024

aleasims May 21, 2024

khannanov-nil May 22, 2024

aleasims May 21, 2024

khannanov-nil May 22, 2024

aleasims May 21, 2024

khannanov-nil May 22, 2024

khannanov-nil May 22, 2024

aleasims May 21, 2024

aleasims May 21, 2024


		# Write a circuit with hashes

		This 'how-to' series constructs a 'mock' zero knowledge bridge from scratch. The series starts with writing a simple circuit that uses hashes and ends with creating an algorithm for state-proof verification.


		Whenever a Rust circuit is compiled, `rustc` applies various optimizations to reduce its memory usage.

		Among these memory optimizations is [reordering fields in structs and enums to avoid unnecessary 'paddings' in circuit IRs](https://users.rust-lang.org/t/disable-struct-reordering-optimization-when-emitting-llvm-bitcode/74951). Consider the following example:


		Among these memory optimizations is [reordering fields in structs and enums to avoid unnecessary 'paddings' in circuit IRs](https://users.rust-lang.org/t/disable-struct-reordering-optimization-when-emitting-llvm-bitcode/74951). Consider the following example:

		```rust


		:::info[Rust directives]

		The `#[derive(Copy, Clone)]` makes it so that circuit code does not unintentionally take ownership of variables that are supposed to be changed/used later.

Zkllvm outdated info #48

Zkllvm outdated info #48

Conversation

khannanov-nil commented May 21, 2024 • edited Loading

vercel bot commented May 21, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aleasims commented May 21, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

khannanov-nil commented May 21, 2024 •

edited

Loading

vercel bot commented May 21, 2024 •

edited

Loading

aleasims commented May 21, 2024 •

edited

Loading