feat(docs): document noir macros #2016

Maddiaa0 · 2023-09-05T14:43:33Z

Documents how the macros work and what they do.

Also adds some information about the context objects, they are required to understand the macros abstraction.

closes: #2063

docs/docs/dev_docs/contracts/functions.md

LHerskind

The renders generally get really funky indention @iAmMichaelConnor might have an idea there?

docs/docs/dev_docs/contracts/context.md

LHerskind · 2023-09-11T10:56:33Z

docs/docs/dev_docs/contracts/context.md

+Behind the scenes, Aztec noir will pass data the kernel needs to and from a circuit, this is abstracted away from the developer. In an developer's eyes; the context is a useful structure that allows access and mutate the state of the `Aztec` blockchain.
+
+## Two context's one API
+The `Aztec` blockchain contains two execution environments (ADD REFERENCE). 


The ADD REFERENCE should either be fixed or have an issue or something.

docs/docs/dev_docs/contracts/context.md

LHerskind · 2023-09-11T11:57:18Z

docs/docs/dev_docs/contracts/functions.md

+
+When calling the `consume_l1_to_l2_message` function on a contract; a number of actions are performed by `Aztec.nr`.
+
+1. The `msgKey` value (passed to the consume message function) is used to look up the contents of the l1 message.


Idea time, should we have this as an oracle instead to get it out of the input parameters here.

that would leave the node with alot of extra indexing

Why? You don't need the oracle to index it, you just use the oracle to pass in the value 🤷, that could happen similarly to the auth witnesses, but it allow us to update with an index down the line if useful.

LHerskind · 2023-09-11T12:04:39Z

docs/docs/dev_docs/contracts/functions.md

+
+Each Aztec function has access to a [context](./context.md) object. This object although ergonomically a global variable, is local. It is initialized from the inputs provided by the kernel, and a hash of the function's inputs.
+
+#include_code context-example-context-return /yarn-project/noir-contracts/src/contracts/docs_example_contract/src/main.nr rust


Should there be a small header here as well?

LHerskind · 2023-09-11T12:05:56Z

docs/docs/dev_docs/contracts/portals/main.md

-    ...
-}
-```
+#include_code send_to_portal /yarn-project/noir-contracts/src/contracts/non_native_token_contract/src/main.nr rust


Needs to be updated along with #2177. Adding a comment here for reference.

LHerskind · 2023-09-11T12:11:24Z

docs/docs/dev_docs/contracts/portals/main.md

-    DataStructures.L1Actor recipient;
-    bytes32 content;
-}
+<!-- TODO: the rest of these docs should have code snippets updates -->


Is there an issue, or should it be fixed in this pr?

did it in this pr, will revert in this one

fix(docs): use code snippet macros in bridge docs #2205

LHerskind · 2023-09-11T12:12:03Z

docs/docs/dev_docs/contracts/syntax.md

+aztec = { git="https://github.com/AztecProtocol/aztec-packages", tag="master", directory="yarn-project/noir-libs/noir-aztec" }
+```
+
+Note: currently the dependency name ***MUST*** be `aztec`. The framework expects this namespace to be available when compiling into contracts. This limitation may be removed in the future.


Would probably be better to make this a larger note os one of the info boxes.

iAmMichaelConnor · 2023-09-11T12:29:58Z

The renders generally get really funky indention @iAmMichaelConnor might have an idea there?

Funky indentation? Of code snippets, you mean? I opened an issue earlier about weird code snippet indentation #2189

…ackages into md/document-macros

… md/document-macros

…ackages into md/document-macros

Documents the global variables

LHerskind

Tiny nits.

LHerskind · 2023-09-18T18:02:11Z

docs/docs/dev_docs/contracts/functions.md

@@ -97,7 +98,7 @@ Aztec.nr uses an attribute system to annotate a function's type. Annotating a fu

 However; `#aztec(private)` is just syntactic sugar. At compile time, the framework inserts code that allows the function to interact with the [kernel](../../concepts/advanced/circuits/kernels/private_kernel.md).

-To help illustrate how this interacts with the internals of Aztec and its kernel circuits, we can take an example private function, and explore what it looks like after Aztec.nr's macro expansion.
+To help illustrate how this interacts with the internals of #public-contextAztec and its kernel circuits, we can take an example private function, and explore what it looks like after Aztec.nr's macro expansion.


Whats going on with the # in here? Seems off.

LHerskind · 2023-09-18T18:04:19Z

docs/docs/dev_docs/contracts/functions.md

+
+When calling the `consume_l1_to_l2_message` function on a contract; a number of actions are performed by `Aztec.nr`.
+
+1. The `msgKey` value (passed to the consume message function) is used to look up the contents of the l1 message.


Why? You don't need the oracle to index it, you just use the oracle to pass in the value 🤷, that could happen similarly to the auth witnesses, but it allow us to update with an index down the line if useful.

LHerskind · 2023-09-18T18:06:10Z

docs/docs/dev_docs/contracts/context.mdx

 1. Msg Sender
    - The message sender is the account (Aztec Contract) that sent the message to the current context. In the first call of the kernel circuit (often the account contract call), this value will be empty. For all subsequent calls the value will be the previous call. 

-    ( TODO: INCLUDE A DIAGRAM HERE SHOWING HOW IT GETS UPDATED ON CONTRACT CALLS )
+> The graphic below illustrates how the message sender changes throughout the kernel circuit iterations.
+<Image img={require("/img/context/sender_context_change.png")} />


Gud drawing.

LHerskind · 2023-09-19T08:44:13Z

docs/docs/dev_docs/contracts/functions.md

- A constructor doesn't have a name, because its purpose is clear: to initialise state.
- In Aztec terminology, a constructor is always a 'private function' (i.e. it cannot be an `open` function).
+- A constructor doesn't have a name, because its purpose is clear: to initialise contract state.
+- In Aztec terminology, a constructor is always a '`private` function' (i.e. it cannot be a `public` function).
 - A constructor behaves almost identically to any other function. It's just important for Aztec to be able to identify this function as special: it may only be called once, and will not be deployed as part of the contract.


Should probably add a comment that it also cannot call any public functions.

LHerskind · 2023-09-19T08:53:20Z

docs/package.json

@@ -5,7 +5,7 @@
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
-    "start:dev": "concurrently \"yarn preprocess:dev\" \"docusaurus start --host 0.0.0.0\"",
+    "start:dev": "concurrently \"yarn preprocess:dev\" \"docusaurus start --host 0.0.0.0 --port 3001\"",


… md/document-macros

…ackages into md/document-macros

… md/document-macros

LHerskind

The changes lgtm. When you get it building feel free to merge.

🤖 I have created a release *beep* *boop* --- <details><summary>aztec-packages: 0.7.10</summary> ## [0.7.10](aztec-packages-v0.7.9...aztec-packages-v0.7.10) (2023-09-20) ### Features * Aztec-cli unbox "really empty box" ([#2388](#2388)) ([b57182d](b57182d)) * **docs:** Document noir macros ([#2016](#2016)) ([1f1a17f](1f1a17f)) * **docs:** Include aztec rpc interface typedoc output in docs ([#2255](#2255)) ([62c9e9b](62c9e9b)) * **token portal standard:** Create a token portal standard ([#2351](#2351)) ([426a3ea](426a3ea)) ### Bug Fixes * **build:** Fix build system post deployment tests ([#2420](#2420)) ([d509dc3](d509dc3)) * CLI encoding for arrays and structs ([#2407](#2407)) ([85283bd](85283bd)) * Correct sandbox addresses in up-quick-start test ([#2412](#2412)) ([974d859](974d859)) * **docs:** Revert include aztec rpc interface typedoc output in docs ([#2255](#2255)) ([f852432](f852432)) * Handle falsy bigints in json-rpc ([#2403](#2403)) ([d100650](d100650)), closes [#2402](#2402) * **nargo_check.sh:** UNIX standard grep ([#2396](#2396)) ([02e788a](02e788a)) ### Miscellaneous * **docs:** Note getter options ([#2411](#2411)) ([8a95d8c](8a95d8c)) * Update docs url in config ([#2386](#2386)) ([e44066d](e44066d)) </details> <details><summary>barretenberg.js: 0.7.10</summary> ## [0.7.10](barretenberg.js-v0.7.9...barretenberg.js-v0.7.10) (2023-09-20) ### Miscellaneous * **barretenberg.js:** Synchronize aztec-packages versions </details> <details><summary>barretenberg: 0.7.10</summary> ## [0.7.10](barretenberg-v0.7.9...barretenberg-v0.7.10) (2023-09-20) ### Miscellaneous * **barretenberg:** Synchronize aztec-packages versions </details> --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).

Maddiaa0 added 2 commits September 5, 2023 14:42

feat: document macros

53a38e1

checkpoint

4e04bcb

iAmMichaelConnor reviewed Sep 6, 2023

View reviewed changes

docs/docs/dev_docs/contracts/functions.md Outdated Show resolved Hide resolved

iAmMichaelConnor reviewed Sep 6, 2023

View reviewed changes

docs/docs/dev_docs/contracts/functions.md Outdated Show resolved Hide resolved

Maddiaa0 added 3 commits September 6, 2023 11:11

feat: add context section to the docs

c1965dc

feat: clean up functions docs

464b3ae

feat: update context docs

2ab0f65

Maddiaa0 requested a review from LHerskind September 6, 2023 14:19

Maddiaa0 marked this pull request as ready for review September 6, 2023 14:20

Maddiaa0 changed the title ~~feat(docs): document noir macros WIP~~ feat(docs): document noir macros Sep 6, 2023

Maddiaa0 added 5 commits September 7, 2023 14:34

feat: document macros

934604b

checkpoint

a6851f7

feat: add context section to the docs

5ea83e3

feat: clean up functions docs

6f324f6

feat: update context docs

319aada

LHerskind force-pushed the md/document-macros branch from 2ab0f65 to 319aada Compare September 7, 2023 13:34

LHerskind reviewed Sep 11, 2023

View reviewed changes

Maddiaa0 and others added 11 commits September 12, 2023 15:24

Merge branch 'md/document-macros' of github.com:AztecProtocol/aztec-p…

2db1fba

…ackages into md/document-macros

Merge branch 'master' into md/document-macros

b68ba49

fix: new aztec-noir path

9c20b42

compliation fix

3b571b7

Merge branch 'master' of github.com:AztecProtocol/aztec-packages into…

65de5b3

… md/document-macros

Merge branch 'master' into md/document-macros

801a7b3

fix: restore

b16f617

Merge branch 'master' into md/document-macros

2aa2a91

Merge branch 'master' into md/document-macros

7399b00

Merge branch 'master' into md/document-macros

757634c

fix: review notes

381c590

Maddiaa0 requested a review from LHerskind September 18, 2023 16:50

Maddiaa0 and others added 2 commits September 18, 2023 17:51

fix: remove this.png

8e8b214

Merge branch 'master' into md/document-macros

1cde337

Maddiaa0 enabled auto-merge (squash) September 18, 2023 16:51

Maddiaa0 and others added 7 commits September 18, 2023 17:56

fix

398e70f

Merge branch 'md/document-macros' of github.com:AztecProtocol/aztec-p…

171f3f6

…ackages into md/document-macros

fix: alter context to mdx for images

3ec0b0f

feat(docs): globals documentation (#2067)

b2033dd

Documents the global variables

fix: aztec-nr ref post merge

1d6561a

fix: package.json

27dcb8b

fix: update context.md refs to mdx

2b02a14

LHerskind reviewed Sep 19, 2023

View reviewed changes

Maddiaa0 and others added 5 commits September 19, 2023 10:58

nits

57f42b4

Merge branch 'master' of github.com:AztecProtocol/aztec-packages into…

c00bba6

… md/document-macros

fix: merge fix

8e04c5b

Merge branch 'md/document-macros' of github.com:AztecProtocol/aztec-p…

e8a0e21

…ackages into md/document-macros

Merge branch 'master' of github.com:AztecProtocol/aztec-packages into…

18b0094

… md/document-macros

LHerskind approved these changes Sep 19, 2023

View reviewed changes

skibbidy

c76ab7e

Maddiaa0 merged commit 1f1a17f into master Sep 19, 2023

Maddiaa0 deleted the md/document-macros branch September 19, 2023 14:22

AztecBot mentioned this pull request Sep 19, 2023

chore(master): Release 0.7.10 #2401

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(docs): document noir macros #2016

feat(docs): document noir macros #2016

Maddiaa0 commented Sep 5, 2023 •

edited

Loading

LHerskind left a comment

LHerskind Sep 11, 2023

LHerskind Sep 11, 2023

Maddiaa0 Sep 18, 2023

LHerskind Sep 18, 2023

LHerskind Sep 11, 2023

LHerskind Sep 11, 2023

LHerskind Sep 11, 2023

Maddiaa0 Sep 11, 2023 •

edited

Loading

LHerskind Sep 11, 2023

iAmMichaelConnor commented Sep 11, 2023

LHerskind left a comment

LHerskind Sep 18, 2023

LHerskind Sep 18, 2023

LHerskind Sep 18, 2023

LHerskind Sep 19, 2023

LHerskind Sep 19, 2023

LHerskind left a comment


		When calling the `consume_l1_to_l2_message` function on a contract; a number of actions are performed by `Aztec.nr`.

		1. The `msgKey` value (passed to the consume message function) is used to look up the contents of the l1 message.


		Each Aztec function has access to a [context](./context.md) object. This object although ergonomically a global variable, is local. It is initialized from the inputs provided by the kernel, and a hash of the function's inputs.

		#include_code context-example-context-return /yarn-project/noir-contracts/src/contracts/docs_example_contract/src/main.nr rust

feat(docs): document noir macros #2016

feat(docs): document noir macros #2016

Conversation

Maddiaa0 commented Sep 5, 2023 • edited Loading

LHerskind left a 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

Maddiaa0 Sep 11, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

iAmMichaelConnor commented Sep 11, 2023

LHerskind left a 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

LHerskind left a comment

Choose a reason for hiding this comment

Maddiaa0 commented Sep 5, 2023 •

edited

Loading

Maddiaa0 Sep 11, 2023 •

edited

Loading