Skip to content

Commit

Permalink
feat(docs): algolia->typesense (#11034)
Browse files Browse the repository at this point in the history
Please read [contributing guidelines](CONTRIBUTING.md) and remove this
line.

---------

Co-authored-by: ludamad <adam.domurad@gmail.com>
Co-authored-by: josh crites <jc@joshcrites.com>
  • Loading branch information
3 people authored Jan 16, 2025
1 parent caf88fa commit d254f49
Show file tree
Hide file tree
Showing 29 changed files with 4,007 additions and 2,310 deletions.
Binary file modified docs/.yarn/install-state.gz
Binary file not shown.
12 changes: 6 additions & 6 deletions docs/HOW_WE_WRITE_DOCS.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# How we write docs

This doc covers the structure and tone of Aztec developer documentation. For the contribution guidelines, go [here](./CONTRIBUTING.md). Please keep in mind that this is constantly changing.
This doc covers the structure and tone of Aztec developer documentation. For the contribution guidelines, go [here](./CONTRIBUTING.md). Please keep in mind that this is constantly changing.

## Structure

### High level

Aztec docs are divided into two main sections - `Learn` and `Build`.
Aztec docs are divided into two main sections - `Learn` and `Build`.

Anyone technical can read the `Learn` section, whereas only developers who are actively building or starting to build on Aztec will read the `Build` section.

Expand All @@ -16,7 +16,7 @@ The `Build` section contains information that only developers need to know - thi

### Types of pages

The Aztec docs roughly follow the [Diataxis](https://diataxis.fr/) framework. It is recommended to read this website before contributing to the docs.
The Aztec docs roughly follow the [Diataxis](https://diataxis.fr/) framework. It is recommended to read this website before contributing to the docs.

Every page will fall into **one type of doc**. If your contribution covers multiple types, you will need to split it into multiple pages.

Expand All @@ -39,8 +39,8 @@ These are docs that developers can consult to know exact and succinct informatio
## Tone

* Concise and informative - for example, rather than repeating information, write "to learn more, read ..."
* Friendly and empathetic - for example, "you do not have to worry about this yet"
* Simple and jardon-avoidant when possible
* Friendly and empathetic - for example, "you do not have to worry about this yet"
* Simple and jardon-avoidant when possible
* Short sentences
* Unopinionated language - we know things are exciting sometimes, but try not to tell the developer what they should be excited about

Expand Down Expand Up @@ -85,4 +85,4 @@ The Aztec docs use a sidebar - https://docusaurus.io/docs/sidebar/items

## Indexing and Search

Algolia docs search - https://docusaurus.io/docs/search#algolia-index-configuration
Typesense docs search - https://typesense.org/
2 changes: 1 addition & 1 deletion docs/docs/aztec/concepts/storage/partial_notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ This is implemented by applying the `partial_note` attribute:

#include_code UintNote noir-projects/aztec-nr/uint-note/src/uint_note.nr rust

Those `G_x` are generators that generated [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/noir-projects/aztec-nr/aztec/src/generators.nr). Anyone can use them for separating different fields in a "partial note".
Those `G_x` are generators that generated [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/generators.nr). Anyone can use them for separating different fields in a "partial note".

We can see the complete implementation of creating and completing partial notes in an Aztec contract in the `setup_refund` and `complete_refund` functions.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,10 @@ authentication_witness_action = H(

Given the action, the developer can ask the `on_behalf_of` account contract if the action is authenticated or not.

```mermaid
```mdx
import { Mermaid } from '@docusaurus/theme-mermaid';

<Mermaid>
sequenceDiagram
actor Alice
participant AC as Alice Account
Expand All @@ -65,6 +68,7 @@ sequenceDiagram
Defi->>Defi: deposit(Token, 1000);
deactivate Defi
deactivate AC
</Mermaid>
```

:::info
Expand Down Expand Up @@ -185,7 +189,10 @@ An example of this would be our Uniswap example which performs a cross chain swa

Outlining more of the `swap` flow: this simplified diagram shows how it will look for contracts that are not wallets but also need to support authentication witnesses.

```mermaid
```mdx
import { Mermaid } from '@docusaurus/theme-mermaid';

<Mermaid>
sequenceDiagram
actor A as Alice
participant AC as Alice Account
Expand Down Expand Up @@ -220,6 +227,7 @@ sequenceDiagram
CC-->>CC: Emit L2->L1 message
deactivate CC;
deactivate AC;
</Mermaid>
```

:::info **TODO**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,10 @@ In the end a siloed note hash is computed in the kernel.
Some of the syntax below is a little butchered to make it easier to follow variables without the full code.
:::

```mermaid
```mdx
import { Mermaid } from '@docusaurus/theme-mermaid';

<Mermaid>
sequenceDiagram
alt Call
Token->>BalanceMap: Map::new(map_slot);
Expand All @@ -37,6 +40,7 @@ sequenceDiagram
end
Context->>Kernel: unique_note_hash = H(nonce, note_hash)
Context->>Kernel: siloed_note_hash = H(contract_address, unique_note_hash)
</Mermaid>
```
Notice the `siloed_note_hash` at the very end. It's a hash that will be inserted into the note hashes tree. To clarify what this really is, we "unroll" the values to their simplest components. This gives us a better idea around what is actually inserted into the tree.
Expand Down
18 changes: 15 additions & 3 deletions docs/docs/protocol-specs/calls/public-private-messaging.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,33 +19,45 @@ Since private functions execute first, they cannot 'wait' on the results of thei

By way of example, suppose a function makes a call to a public function, and then to a private function. The public function will not be executed immediately, but will instead be enqueued for the sequencer to execute later.

```mermaid
```mdx
import { Mermaid } from '@docusaurus/theme-mermaid';

<Mermaid>
graph LR
A[Private Function 1] --> |1st call| B(Public Function 1)
A --> |2nd call| C[Private Function 2]
C --> |return values| A
A --> |3rd call| D(Public Function 2)
A --> |4th call| E[Private Function 3]
E --> |return values| A
</Mermaid>
```

The order of execution will actually be:

```mermaid
```mdx
import { Mermaid } from '@docusaurus/theme-mermaid';

<Mermaid>
graph LR
A[Private Function 1] --> C[Private Function 2]
C --> |return values| A
A[Private Function 1] --> E[Private Function 3]
E --> |return values| A
A -----> |Enqueued| B(Public Function 1)
A -----> |Enqueued| D(Public Function 2)
</Mermaid>
```

And the order of proving will actually be:

```mermaid
```mdx
import { Mermaid } from '@docusaurus/theme-mermaid';

<Mermaid>
flowchart LR
A[Private Function 1] --> C[Private Function 2] --> E[Private Function 3] ----> B(Public Function 1) --> D(Public Function 2)
</Mermaid>
```

## Private to Public Messaging
Expand Down
12 changes: 10 additions & 2 deletions docs/docs/protocol-specs/circuits/high-level-topology.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,10 @@ A note for Aztec protocol developers: In this protocol spec, the order in which
<!-- Mike review: perhaps a more comprehensive example would be if f2 makes the calls to f4 and f5, to cover a case which isn't covered in the current example: If f2 calls f4 & f5, then which is processed by the kernel first out of f3, f4, or f5?
-->

```mermaid
```mdx
import { Mermaid } from '@docusaurus/theme-mermaid';

<Mermaid>
flowchart LR
f0([f0]) --> f1([f1])
f0 --> f2([f2])
Expand All @@ -27,11 +30,15 @@ flowchart LR
f3 --> f4([f4])
f3 -.-> F4
f3 --> f5([f5])
</Mermaid>
```

This transaction contains 6 private functions (f0 to f5) and 5 public functions (F0 to F4), with `f0` being the entrypoint. The entire transaction is processed as follows:

```mermaid
```mdx
import { Mermaid } from '@docusaurus/theme-mermaid';

<Mermaid>
flowchart TB
subgraph Transaction A
subgraph Private Functions
Expand Down Expand Up @@ -126,6 +133,7 @@ flowchart TB
MR1 --> MR2
MR2 --> ROOT
MR3 --> ROOT
</Mermaid>
```

A few things to note:
Expand Down
13 changes: 10 additions & 3 deletions docs/docs/protocol-specs/circuits/private-kernel-initial.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -296,7 +296,10 @@ Key:

<div style={{width: '40%'}}>

```mermaid
```mdx
import { Mermaid } from '@docusaurus/theme-mermaid';

<Mermaid>
classDiagram
direction LR
class ParentClass {
Expand All @@ -320,6 +323,7 @@ class D {
ParentClass *-- ChildClass: Composition.
A .. B: Perform a consistency check on values in these classes.
C ..> D: Copy the data from the inputs A to the outputs B\n(possibly with some modification along the way).
</Mermaid>
```

</div>
Expand All @@ -335,7 +339,10 @@ The diagram:
<div style={{overflowX: 'auto'}}>
<div style={{width: '200%'}}>

```mermaid
```mdx
import { Mermaid } from '@docusaurus/theme-mermaid';

<Mermaid>
classDiagram
direction TB

Expand Down Expand Up @@ -694,7 +701,7 @@ class PublicInputs {
}
ConstantData --* PublicInputs : constant_data
TransientAccumulatedData --* PublicInputs: transient_accumulated_data
</Mermaid>
```
</div>
Expand Down
6 changes: 4 additions & 2 deletions docs/docs/protocol-specs/circuits/private-kernel-inner.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,10 @@ NOTE TO ANYONE EDITING THIS DIAGRAM:
To save repeating yourself, you only need to edit the END of this diagram (demarcated clearly, further down the page - you'll see it). COPY-PASTE the beginning of this diagram (up to the demarcation) from ../private-kernel-initial.
-->

```mermaid
```mdx
import { Mermaid } from '@docusaurus/theme-mermaid';

<Mermaid>
classDiagram
direction TB

Expand Down Expand Up @@ -549,7 +552,6 @@ PrivateKernelPublicInputs ..> KERNEL_PROOF_VERIFICATION
KernelVerificationKey ..> KERNEL_VK_EXISTENCE_CHECK
KernelVKMembershipWitness ..> KERNEL_VK_EXISTENCE_CHECK


```
</div>
Expand Down
Loading

0 comments on commit d254f49

Please sign in to comment.