docs: some initial noir contract docs (#1449)

Apologies for the large and sweeping PR. It's the culmination of going
back-and-forth between doc writing and tweaking noir contracts as I go.

- Improved the preprocessor which embeds code into markdown files.
- Split the old 'concepts' doc into the new filing structure, and added
some content and code snippets.
- Renamed instances of "zk token" to "private token" throughout the
codebase (all cases: camel, pascal etc).
- Moved `zk_token_contract` to a `private_token_airdrop_contract`,
because it showcased some extra 'claim' functionality that might confuse
someone expecting basic functions.
- Created `private_token_contract` as a simpler version of
`zk_token_contract` (by removing anything about claim notes).
- Introduced an example contract demonstrating the basics of public
state.

.circleci/config.yml

@@ -712,7 +712,7 @@ jobs:
       - *setup_env
       - run:
           name: "Test"
-          command: ./scripts/cond_run_script end-to-end $JOB_NAME ./scripts/run_tests_local e2e_zk_token_contract.test.ts
+          command: ./scripts/cond_run_script end-to-end $JOB_NAME ./scripts/run_tests_local e2e_private_token_contract.test.ts
           working_directory: yarn-project/end-to-end
 
   e2e-block-building:

bootstrap_docker.sh

@@ -38,5 +38,5 @@ build_local $TARGET_PROJECT $ONLY_TARGET
 if [ -z "$TARGET_PROJECT" ]; then
   echo
   echo "Success! You could now run e.g.:"
-  echo "  docker run -ti --rm aztecprotocol/end-to-end:latest e2e_zk_token_contract.test"
+  echo "  docker run -ti --rm aztecprotocol/end-to-end:latest e2e_private_token_contract.test"
 fi

circuits/cpp/barretenberg/cpp/bin-test/Nargo.toml

@@ -1,4 +1,5 @@
 [package]
+name = ""
 authors = [""]
 compiler_version = "0.6.0"
 

docs/docs/dev_docs/contracts/abi.md

@@ -0,0 +1,18 @@
+Discuss:
+- Public Inputs ABIs for functions.
+- Args & args hashes
+- return values and return values hashes
+- etc.
+
+
+## Limitations
+
+### Num reads and writes
+
+### Num function calls
+
+### Num logs
+
+### Num key pair validations
+
+### No gas or fees yet

docs/docs/dev_docs/contracts/constrain.md

@@ -0,0 +1,2 @@
+Not sure what this one's for?
+`assert`?

docs/docs/dev_docs/contracts/contract.md

@@ -0,0 +1,26 @@
+# `contract`
+
+A contract is a collection of persistent [state variables](#state-variables), and [functions](#functions) which may modify these persistent states. Functions and states within a contract's scope are said to belong to that contract. A contract can only access and modify its own state. If a contract wishes to access or modify another contract's state, it must make a [call](#calling-functions) to an external function of that other contract. For anything to happen on the Aztec network, an external function of a contract needs to be called.
+
+A contract may be declared and given a name using the `contract` keyword (see snippet below). By convention, contracts are named in `PascalCase`.
+
+```rust title="contract keyword"
+// highlight-next-line
+contract MyContract {
+
+    // Functions and state variables belonging to this contract are not shown here.
+
+}
+```
+
+
+> A note for vanilla Noir devs: There is no [`main()`](https://noir-lang.org/getting_started/breakdown/#mainnr) function within a Noir Contract scope. This is because more than one function of a contract may be called and proven as external (as opposed to inlined by the compiler).
+
+## Structure of a contract
+
+- Private state variables
+- Public state variables
+- Private functions
+- Public functions
+- Encrypted events
+- Unencrypted events

docs/docs/dev_docs/contracts/control_structure.md

@@ -2,6 +2,12 @@
 title: Control Structures
 ---
 
+:::danger
+Question: this feels like the wrong title for a section about how to call functions. 'Control structure' in my mind is "if/else", "for", "while".
+
+Can we not put "how to call functions" in the [functions](./functions.md) section?
+:::
+
 # Function Calls
 
 ## Private Function Calls

docs/docs/dev_docs/contracts/deploying.md

@@ -0,0 +1 @@
+See sandbox section?

docs/docs/dev_docs/contracts/events.md

@@ -0,0 +1,17 @@
+## Events
+
+### Constraining events
+
+### Unencrypted Events
+
+### Encrypted Events
+
+### Costs
+
+Explain L1 cost to emit an event.
+
+## Processing events
+
+### Decrypting
+
+### Stev

docs/docs/dev_docs/contracts/functions.md

@@ -0,0 +1,50 @@
+# Functions
+
+## `constructor`
+
+- A special `constructor` function MUST be declared within a contract's scope.
+- 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 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.
+
+## secret functions
+
+## `open` functions
+
+## `unconstrained` functions
+
+
+
+# Calling functions
+
+## Inlining
+
+## Importing Contracts
+
+### Contract Interface
+
+## Constrained --> Unconstrained
+
+E.g. `get()`
+
+## Oracle calls
+
+## Private --> Private
+
+## Public --> Public
+
+## Private --> Public
+
+## `internal` keyword
+
+## Public --> Private
+
+## Recursive function calls
+
+## L1 --> L2
+
+## L2 --> L1
+
+## Delegatecall
+
+Talk a about the dangers of delegatecall too!

docs/docs/dev_docs/contracts/globals.md

@@ -0,0 +1,4 @@
+- timestamp
+- block number
+- chain id
+- version

docs/docs/dev_docs/contracts/layout.md

@@ -0,0 +1,15 @@
+# Layout
+## Directory structure
+
+Here's a common layout for a basic Noir Contract project:
+
+``` title="layout of an aztec contract project"
+─── my_aztec_contract_project
+       ├── src
+       │     ├── main.nr       <-- your contract
+       │     └── storage.nr    <-- state variable declarations (by convention)
+       └── Nargo.toml          <-- package and dependency management
+```
+
+
+> See the vanilla Noir docs for [more info on packages](https://noir-lang.org/modules_packages_crates/crates_and_packages).

docs/docs/dev_docs/contracts/main.md

@@ -11,9 +11,9 @@ We've extended the Noir language to understand the notion of an **'Aztec smart c
 - A **Noir Contract** is just an Aztec smart contract, written in Noir syntax.
 
 
-> Throughout these docs, we'll refer to "regular Noir" as being the version of Noir without the Noir Contract syntax.
-
-
+:::info
+Throughout these docs, we'll refer to "Vanilla Noir" as being the version of Noir without the Noir Contract syntax.
+:::
 
 # Getting started
 
@@ -31,13 +31,28 @@ There are a number of tools to make writing Noir Contracts more pleasant. See [h
 
 Download an Aztec Box. (Josh / Ze to build :) ).
 
+@Josh what's the best way to enable a 'one-command' creation of a noir project? (akin to https://noir-lang.org/getting_started/hello_world). I wonder if @aztec/cli should have this functionality? 
+
+@Josh I wonder if @aztec/cli would be a good place to hold 'Aztec Boxes'?
+- `aztec-cli unbox`
+- `aztec-cli unbox private_token`.
+
 Or, if you don't want to do that, here's more detail on doing it all yourself:
 
 :::danger TODO
 TODO
 :::
 
-## Creating a new contract package
 
-See [here](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/noir-contracts#creating-a-new-contract-package)
+## Example Noir Contract
+
+In keeping with the origins of blockchain, here's an example of a simple token contract. But here, the balances are private.
+
+#include_code easy_private_token_storage /yarn-project/noir-contracts/src/contracts/easy_private_token_contract/src/storage.nr rust
+
+#include_code easy_private_token_contract /yarn-project/noir-contracts/src/contracts/easy_private_token_contract/src/main.nr rust
+
+:::info Disclaimer
+Please note that any example contract set out herein is provided solely for informational purposes only and does not constitute any inducement to use or deploy. Any implementation of any such contract with an interface or any other infrastructure should be used in accordance with applicable laws and regulations.
+:::
 

docs/docs/dev_docs/contracts/resources/common_patterns/access_control.md

@@ -0,0 +1,5 @@
+# Access Control
+
+## msg_sender
+
+## slow updates tree (TBC!!!)