chore(docs): zp's nits (#6608)

Entering some friendly competition with dear @catmcgee on nits PRs
AztecProtocol · May 29, 2024 · defd2ba · defd2ba
1 parent 03511f5
commit defd2ba
Show file tree

Hide file tree

Showing 9 changed files with 73 additions and 96 deletions.
diff --git a/docs/docs/aztec.md b/docs/docs/aztec.md
@@ -1,65 +1,46 @@
 ---
-title: Aztec
+title: Programmable Privacy
 sidebar_position: 0
 ---
 
 import Disclaimer from "@site/src/components/Disclaimers/\_wip_disclaimer.mdx";
 import ReactPlayer from "react-player/youtube";
 
-Aztec is an L2 that brings programmable privacy to Ethereum.
-
-## Private Smart Contracts on Aztec
-
-A smart contract on Aztec is a collection of functions, written as ZK-SNARK circuits. These circuits can have different modes of execution:
-
-1. Private Functions -- can read and write private state, read historical public state, consume or send messages to / from Ethereum, and read Ethereum state. They can call other private functions in the same contract, or other contracts, and can call public functions.
-2. Public Functions -- can read and write public state, write private state, consume or send messages to / from Ethereum and read Ethereum state. They can call other public functions on the same or other contracts.
-3. Portal Contracts -- these are contracts on Ethereum that can receive messages from Aztec or send messages to Aztec from Ethereum contracts.
-
-Using these different modes of execution, developers can build applications with user privacy, data privacy and code privacy.
-
-- User privacy - transactions may not reveal information about the sender or the recipient.
-- Data privacy - transactions may not reveal information about the payload of the transaction, e.g., the asset or value being transacted.
-- Code privacy - transactions may not reveal the program logic.
-
-Watch Zac, CEO of Aztec, describe our approach to building a privacy preserving smart contract blockchain.
-
-<ReactPlayer
-  controls
-  light
-  width="100%"
-  url="https://www.youtube.com/watch?v=09nDPDN1ORA"
-/>
-
-### Private-public Composability
-
-You can watch Mike, Aztec PM, talk about public-private composability in Aztec at Devcon here.
-
-<ReactPlayer
-  controls
-  light
-  width="100%"
-  url="https://www.youtube.com/watch?v=7Oc0tjdbi70&t=17723s"
-/>
-
 ## How Aztec is being built
 
-Aztec is being built and launched as a credibly neutral, decentralized network. The protocol is being developed as open source software by Aztec (the company) and our community. Together we are designing, building and auditing much of the software that will be run by network stakeholders such as infrastructure providers in order to create Aztec.
+Aztec will launch as a credibly neutral, decentralized network. The protocol is being developed as open source software by Aztec Labs and the community. Together we are designing, building and auditing much of the software that will be run by Aztec network stakeholders, such as infrastructure providers, wallets, and other core services.
+
+Contributors to Aztec uphold many of the values of the Ethereum community:
+- building in public
+- having a rigorous commitment to open source
+- believe in a permissionless, compliant, scalable and censorship-resistant system.
 
-Contributors to Aztec uphold many of the values of the Ethereum community -- building in public, a rigorous commitment to open source and a goal to build a permission-less, censorship resistance system.
+## Our Cryptography
 
-## Noir
+Aztec is inspired on Ethereum. We believe in transparency for the protocol, but privacy for the user. This programmability is achieved through Smart Contracts, which are in fact Zero-Knowledge circuits.
 
-Noir is a domain specific programming language for writing zero-knowledge circuits. On Aztec a smart contract is a collection of circuits that developers write using Noir.
+To allow for this, we focus on two main components:
+- **Noir** - We started developing Noir long before Aztec came into being. As an easy, open-source domain specific programming language for writing zero-knowledge circuits, it became the perfect language for writing [Aztec Smart Contracts](aztec/concepts/smart_contracts/index.md). Read about standalone Noir in the [Noir Lang Documentation](https://noir-lang.org).
+- **Honk** - A collection of cutting-edge cryptography, from proving systems, to compilers, and other sidecars. These will support Aztec's rollup and allow for fast, private, client-side proving.
 
-You can find more information and resources for learning about Noir smart contracts on [this page](aztec/concepts/smart_contracts/index.md).
+## Media
 
-## Cryptography
+### Privacy Preserving Smart Contracts
+  <ReactPlayer
+    controls
+    light
+    width="100%"
+    url="https://www.youtube.com/watch?v=09nDPDN1ORA"
+  />
 
-To support Aztec's rollup, our cryptography team is building [Honk](https://github.com/AztecProtocol/barretenberg/tree/master/cpp/src/barretenberg/honk), a cutting edge proving system that makes Aztec possible, under the Apache 2.0 License.
+### Public-private Composability
 
-## Participate
+  <ReactPlayer
+    controls
+    light
+    width="100%"
+    url="https://www.youtube.com/watch?v=7Oc0tjdbi70&t=17723s"
+  />
 
-Keep up with the latest discussion and join the conversation in the [Aztec forum](https://discourse.aztec.network) or [Discord server](https://discord.gg/DgWG2DBMyB).
 
 <Disclaimer />;
diff --git a/docs/docs/aztec/core_components.md b/docs/docs/aztec/core_components.md
@@ -3,29 +3,20 @@ title: Core Components
 sidebar_position: 1
 ---
 
-Aztec Labs is building a layer 2 rollup on Ethereum focused on 3 things:
 
-- Data privacy
-- Confidentiality
-- Trustlessness
+## Private Smart Contracts
 
-## Data privacy
+A smart contract on Aztec is a collection of functions, written as ZK-SNARK circuits. These circuits can have different modes of execution:
 
-Data privacy refers to the ability of Aztec smart contract to have private (encrypted) state. Aztec abstracts away many of the complexities associated with managing private state, providing developers with an interface that feels familiar, but is much more powerful.
+1. Private Functions -- can read and write private state, read historical public state, consume or send messages to / from Ethereum, and read Ethereum state. They can call other private functions in the same contract, or other contracts, and can call public functions.
+2. Public Functions -- can read and write public state, write private state, consume or send messages to / from Ethereum and read Ethereum state. They can call other public functions on the same or other contracts.
+3. Portal Contracts -- these are contracts on Ethereum that can receive messages from Aztec or send messages to Aztec from Ethereum contracts.
 
-## Confidentiality
+Using these different modes of execution, developers can build applications with user privacy, data privacy and code privacy.
 
-Confidentiality is the ability of Aztec smart contracts to execute private functions and transactions. Aztec provides a secure, private environment for the execution of sensitive operations, ensuring private information and decrypted data are not accessible to unauthorized applications.
-
-When a user sends a private transaction on the network, the only information that an external observer can infer is that a transaction was sent. Transaction data, the sender, and the recipient can all be obfuscated.
-
-Aztec achieved this level of privacy by leveraging a Private eXecution Environment (PXE). This software runs client-side, for example in a browser, and is responsible for managing private keys, encrypting and decrypting data, and executing private functions. The PXE is also responsible for generating proofs of private function execution, which are then sent to the sequencer for inclusion in the rollup.
-
-## Trustlessness
-
-Aztec is building a permissionless, censorship resistant, peer-to-peer network. It aims to be credibly neutral, where the same transparent rules apply to everyone, enforced by the protocol.
-
-Aztec will have a network of sequencers that stake tokens to participate in the network. Sequencers are responsible for aggregating transactions into a block, generating proofs of the state updates (or delegating proof generation to the prover network) and posting it to the rollup contract on Ethereum, along with any required public data for data availability.
+- User privacy - transactions may not reveal information about the sender or the recipient.
+- Data privacy - transactions may not reveal information about the payload of the transaction, e.g., the asset or value being transacted.
+- Code privacy - transactions may not reveal the program logic.
 
 ## High level network architecture
 

diff --git a/docs/docs/guides/local_env/versions-updating.md b/docs/docs/guides/local_env/versions-updating.md
@@ -11,7 +11,7 @@ When developing and referring to example .nr files/snippets, it is helpful to ve
 
 :::note
 The `aztec-nargo` versions follow `nargo` versions, which is different to the Aztec tool versions.
-:::note
+:::
 
 The latest version of the Aztec tooling is currently `#include_aztec_version` , updating roughly every week.
 
@@ -23,7 +23,7 @@ Check the `git=` github url, tag, and directory.
 
 :::note
 The folder structure changed at **0.24.0** from `yarn-project/aztec-nr` to `noir-projects/aztec-nr`.  More details [here](https://docs.aztec.network/misc/migration_notes#aztecnr-aztec-nr-contracts-location-change-in-nargotoml)
-:::note
+:::
 
 ### Example contract versions
 Example contracts serve as a helpful reference between versions of the aztec-nr framework since they are strictly maintained with each release.
@@ -42,15 +42,15 @@ diff ~/nargo/github.com/AztecProtocol/aztec-packages-v0.23.0/yarn-project/noir-c
 57a58
 >         note_type_id: Field,
 ```
-:::tip
+:::
 
 ### Language server version (aztec-nargo)
 The [Noir LSP](https://docs.aztec.network/developers/contracts/main.md#install-noir-lsp-recommended) uses your local version of `aztec-nargo`, and thus also `aztec-nargo compile`.
 The path of the former (once installed) can be seen by hovering over "Nargo" in the bottom status bar of VS Code, and the latter via the `which aztec-nargo` command.
 
 :::caution
 For Aztec contract files, this should be `aztec-nargo` and for noir-only files this should be `nargo`. Mismatching tools and file types will generate misleading syntax and compiler errors.
-:::caution
+:::
 
 This can present confusion when opening older contracts (and dependencies) written in older version of noir, such as:
 - Logs filled with errors from the dependencies

diff --git a/docs/docs/guides/smart_contracts/writing_contracts/_category_.json b/docs/docs/guides/smart_contracts/writing_contracts/_category_.json
@@ -0,0 +1,6 @@
+{
+    "position": 0,
+    "collapsible": true,
+    "collapsed": true,
+    "label": "Writing Contracts"
+}
diff --git a/docs/docs/guides/smart_contracts/writing_contracts/index.md b/docs/docs/guides/smart_contracts/writing_contracts/index.md
diff --git a/docs/docs/guides/smart_contracts/writing_contracts/storage/notes.md b/docs/docs/guides/smart_contracts/writing_contracts/storage/notes.md
@@ -50,7 +50,7 @@ By virtue of being append only, notes are not edited. If two transactions amend
 :::info
 - Only those with appropriate keys/information will be able to successfully read private values that they have permission to
 - Notes can be read outside of a transaction or "off-chain" with no changes to data structures on-chain
-:::info
+:::
 
 When a note is read in a transaction, a subsequent read from another transaction of the same note would reveal a link between the two. So to preserve privacy, notes that are read in a transaction are said to be "consumed" (defined below), and new note(s) are then created with a unique hash (includes transaction identifier).
 
@@ -63,7 +63,7 @@ When interpreting a value, the local private execution checks that its notes (of
 ### Updating
 :::note
 Only those with appropriate keys/information will be able to successfully nullify a value that they have permission to.
-:::note
+:::
 
 To update a value, its previous note hash(es) are nullified. The new note value is updated in the PXE, and the updated note hash inserted into the note hash tree.
 

diff --git a/docs/docs/reference/smart_contract_reference/index.md b/docs/docs/reference/smart_contract_reference/index.md
diff --git a/docs/docs/vision.mdx b/docs/docs/vision.mdx
@@ -1,28 +1,40 @@
 ---
-title: Vision
+title: Aztec's Vision
+sidebar_label: Vision
 sidebar_position: 1
 ---
 
 import Disclaimer from "@site/src/components/Disclaimers/_wip_disclaimer.mdx";
 
-## The world's encrypted ledger
+We are building the [Aztec Network](https://aztec.network/), a fully programmable private [ZK-rollup](https://ethereum.org/en/developers/docs/scaling/zk-rollups/) on [Ethereum](https://ethereum.org/) to enable developers to create decentralized applications with encryption and scale.
 
-Our vision is to create a fairer, more open financial eco-system, built with encryption at its core.
+These are our core values.
 
-We believe decentralization is premised on individual rights — without widely accessible encryption, we compromise our ability to choose how we live our lives and earn our livelihoods.
+### Privacy
 
-We are building the [Aztec Network](https://aztec.network/), a fully programmable private [ZK-rollup](https://ethereum.org/en/developers/docs/scaling/zk-rollups/) on [Ethereum](https://ethereum.org/) to enable developers to create decentralized applications with encryption and scale.
+The only true zero-knowledge rollup, built with a privacy-first UTXO architecture to allow developers to build privacy preserving programable applications.
+
+It refers to the ability of Aztec smart contract to have private (encrypted) state. Aztec abstracts away many of the complexities associated with managing private state, providing developers with an interface that feels familiar, but is much more powerful.
+
+Aztec provides a secure, private environment for the execution of sensitive operations, ensuring private information and decrypted data are not accessible to unauthorized applications.
 
-## Values
+When a user sends a private transaction on the network, the only information that an external observer can infer is that a transaction was sent.
+
+## Accessibility
+
+Proving transaction validity via recursive aggregation of zero-knowledge proofs, significantly reduces transaction costs, keeping the protocol accessible to the masses.
+
+## Trustlessness
+
+We believe decentralization is premised on individual rights — without widely accessible encryption, we compromise our ability to choose how we live our lives and earn our livelihoods.
 
-- **Private.**: The only true zero-knowledge rollup, built with a privacy-first UTXO architecture to allow developers to build privacy preserving programable applications.
-- **Accessible.**: Proving transaction validity via recursive aggregation of zero-knowledge proofs, significantly reduces transaction costs, keeping the protocol accessible to the masses.
-- **Compliant**: The programmable nature of Aztec smart contracts, enables dApp developers to code privacy-preserving audit and compliance checks into apps, while fully preserving a credible neutral protocol layer.
+Aztec is building a permissionless, censorship resistant, peer-to-peer network. It aims to be credibly neutral, where the same transparent rules apply to everyone, enforced by the protocol.
 
-#### _Zac Williamson, CEO and Co-founder, Aztec_
+Aztec will have a network of sequencers that stake tokens to participate in the network. Sequencers are responsible for aggregating transactions into a block, generating proofs of the state updates (or delegating proof generation to the prover network) and posting it to the rollup contract on Ethereum, along with any required public data for data availability.
 
-> “When we started Aztec, the technology to scale blockchains privately didn’t exist. Since then, we’ve assembled a team of world-class cryptographers who continuously redefine the state-of-the-art. Inventing PLONK — the paradigm-defining universal zk-SNARK — showcases our ability to produce technology that matches our ambitions: unlocking an entire universe of blockchain applications that couldn’t exist without privacy.”
+## Compliance
 
-To achieve these goals, we are pioneering the cryptography and research needed to bring our next generation, privacy-preserving zk-roll-up to mainnet.
+The programmable nature of Aztec smart contracts, enables dApp developers to code privacy-preserving audit and compliance checks into apps, while fully preserving a credible neutral protocol layer.
+goals, we are pioneering the cryptography and research needed to bring our next generation, privacy-preserving zk-roll-up to mainnet.
 
 <Disclaimer />
diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js
@@ -55,6 +55,7 @@ const config = {
             );
           },
           routeBasePath: "/",
+          include: ["**/*.{md,mdx}"],
           remarkPlugins: [math],
           rehypePlugins: [
             [