feat(docs): fix portals tutorial formatting (#2929)

WIP [x] Formatting issues with `#include_code` [x] Name uniswap -> uniswap integration [x] Fixing setup # Checklist: Remove the checklist to signal you've completed it. Enable auto-merge if the PR is ready to merge. - [ ] If the pull request requires a cryptography review (e.g. cryptographic algorithm implementations) I have added the 'crypto' tag. - [ ] I have reviewed my diff in github, line by line and removed unexpected formatting changes, testing logs, or commented-out code. - [ ] Every change is related to the PR description. - [ ] I have [linked](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) this pull request to relevant issues (if any exist).
AztecProtocol · Oct 23, 2023 · ab19b67 · ab19b67
1 parent 655c322
commit ab19b67
Show file tree

Hide file tree

Showing 8 changed files with 68 additions and 62 deletions.
diff --git a/docs/docs/dev_docs/tutorials/token_portal/minting_on_aztec.md b/docs/docs/dev_docs/tutorials/token_portal/minting_on_aztec.md
@@ -10,11 +10,12 @@ In our `token-bridge` nargo project in `aztec-contracts`, under `src` there is a
 
 ```rust
 mod util;
-#include_code token_bridge_imports /yarn-project/noir-contracts/src/contracts/token_bridge_contract/src/main.nr rust raw
+#include_code token_bridge_imports /yarn-project/noir-contracts/src/contracts/token_bridge_contract/src/main.nr raw
   use crate::token_interface::Token;
   use crate::util::{get_mint_public_content_hash, get_mint_private_content_hash, get_withdraw_content_hash};
-#include_code token_bridge_storage_and_constructor /yarn-project/noir-contracts/src/contracts/token_bridge_contract/src/main.nr rust raw
+#include_code token_bridge_storage_and_constructor /yarn-project/noir-contracts/src/contracts/token_bridge_contract/src/main.nr raw
 ```
+
 This imports Aztec-related dependencies and our two helper files `token_interface.nr` and `util.nr`.
 (The code above will give errors right now - this is because we haven't implemented util and token_interface yet.)
 

diff --git a/docs/docs/dev_docs/tutorials/token_portal/setup.md b/docs/docs/dev_docs/tutorials/token_portal/setup.md
@@ -21,32 +21,35 @@ However if you’d rather skip this part, our dev-rels repo contains the starter
 - [docker](https://docs.docker.com/)
 - [Aztec sandbox](https://docs.aztec.network/dev_docs/getting_started/sandbox) - you should have this running before starting the tutorial
 
-```sh
+```bash
 /bin/sh -c "$(curl -fsSL 'https://sandbox.aztec.network')"
 ```
 
 - Nargo
 
-```sh
+```bash
 curl -L https://raw.githubusercontent.com/noir-lang/noirup/main/install | sh
 noirup -v #include_noir_version
 ```
 
-# Create the root project
+# Create the root project and packages
 
 Our root project will house everything ✨
 
-```sh
+```bash
 mkdir aztec-token-bridge
+cd aztec-token-bridge && mkdir packages
 ```
 
+We will hold our projects inside of `packages` to follow the design of the project in the [repo](https://github.com/AztecProtocol/dev-rel/tree/main/tutorials/token-bridge-e2e).
+
 # Create a nargo project
 
-Now inside `aztec-token-bridge` create a new directory called `aztec-contracts`
+Now inside `packages` create a new directory called `aztec-contracts`
 
 Inside `aztec-contracts`, create a nargo contract project by running
 
-```sh
+```bash
 mkdir aztec-contracts
 cd aztec-contracts
 nargo new --contract token_bridge
@@ -87,26 +90,28 @@ aztec-contracts
 
 # Create a JS hardhat project
 
-In the root dir `aztec-token-bridge`, create a new directory called `l1-contracts` and run `npx hardhat init` inside of it. Keep hitting enter so you get the default setup (Javascript project)
+In the `packages` dir, create a new directory called `l1-contracts` and run `yarn init -yp &&
+npx hardhat init` inside of it. Keep hitting enter so you get the default setup (Javascript project)
 
-```sh
+```bash
 mkdir l1-contracts
 cd l1-contracts
+yarn init -yp
 npx hardhat init
 ```
 
-Once you have a hardhat project set up, delete the existing contracts and create a `TokenPortal.sol`:
+Once you have a hardhat project set up, delete the existing contracts, tests, and scripts, and create a `TokenPortal.sol`:
 
-```sh
-cd contracts
-rm *.sol
+```bash
+rm -rf contracts test scripts
+mkdir contracts && cd contracts
 touch TokenPortal.sol
 ```
 
 Now add dependencies that are required. These include interfaces to Aztec Inbox, Outbox and Registry smart contracts, OpenZeppelin contracts, and NomicFoundation.
 
-```sh
-yarn add @aztec/l1-contracts @nomicfoundation/hardhat-network-helpers @nomicfoundation/hardhat-chai-matchers @nomiclabs/hardhat-ethers @nomiclabs/hardhat-etherscan @types/chai @types/mocha @typechain/ethers-v5 @typechain/hardhat chai hardhat-gas-reporter solidity-coverage ts-node typechain typescript @openzeppelin/contracts
+```bash
+yarn add @aztec/foundation @aztec/l1-contracts @openzeppelin/contracts && yarn add --dev @nomicfoundation/hardhat-network-helpers @nomicfoundation/hardhat-chai-matchers @nomiclabs/hardhat-ethers @nomiclabs/hardhat-etherscan @types/chai @types/mocha @typechain/ethers-v5 @typechain/hardhat chai hardhat-gas-reporter solidity-coverage ts-node typechain typescript
 
 ```
 
@@ -134,9 +139,9 @@ In this directory, we will write TS code that will interact with our L1 and L2 c
 
 We will use `viem` in this tutorial and `jest` for testing.
 
-Inside the root directory, run
+Inside the `packages` directory, run
 
-```sh
+```bash
 mkdir src && cd src && yarn init -yp
 yarn add @aztec/aztec.js @aztec/noir-contracts @aztec/types @aztec/foundation @aztec/l1-artifacts viem "@types/node@^20.8.2"
 yarn add -D jest @jest/globals ts-jest
@@ -236,13 +241,13 @@ Then create a jest config file: `jest.config.json`
 
 You will also need to install some dependencies:
 
-```sh
+```bash
 yarn add --dev typescript @types/jest ts-jest
 ```
 
 Finally, we will create a test file. Run this in the `src` directory.:
 
-```sh
+```bash
 mkdir test && cd test
 touch cross_chain_messaging.test.ts
 ```

diff --git a/docs/docs/dev_docs/tutorials/token_portal/typescript_glue_code.md b/docs/docs/dev_docs/tutorials/token_portal/typescript_glue_code.md
@@ -4,9 +4,9 @@ title: Deploy & Call Contracts with Typescript
 
 In this step we will write a Typescript test to interact with the sandbox and call our contracts!
 
-Go to the `src/test` directory in your root dir and create a new file called `cross_chain_messaging.test.ts`:
+Go to the `src/test` directory in your `packages` dir and create a new file called `cross_chain_messaging.test.ts`:
 
-```sh
+```bash
 cd src/test
 touch cross_chain_messaging.test.ts
 ```
@@ -60,11 +60,11 @@ const [PortalERC20Abi, PortalERC20Bytecode] =
 const [TokenPortalAbi, TokenPortalBytecode] =
   getL1ContractABIAndBytecode("TokenPortal");
 
-#include_code deployL1Contract /yarn-project/ethereum/src/deploy_l1_contracts.ts typescript raw
+#include_code deployL1Contract /yarn-project/ethereum/src/deploy_l1_contracts.ts raw
 
-#include_code deployAndInitializeTokenAndBridgeContracts /yarn-project/end-to-end/src/shared/cross_chain_test_harness.ts typescript raw
+#include_code deployAndInitializeTokenAndBridgeContracts /yarn-project/end-to-end/src/shared/cross_chain_test_harness.ts raw
 
-#include_code delay /yarn-project/end-to-end/src/fixtures/utils.ts typescript raw
+#include_code delay /yarn-project/end-to-end/src/fixtures/utils.ts raw
 ```
 
 This code
@@ -165,7 +165,7 @@ This fetches the wallets from the sandbox and deploys our cross chain harness on
 
 ```bash
 cd packages/src
-yarn test
+DEBUG='aztec:canary_uniswap' yarn test
 ```
 
 ### Error handling

diff --git a/docs/docs/dev_docs/tutorials/token_portal/withdrawing_to_l1.md b/docs/docs/dev_docs/tutorials/token_portal/withdrawing_to_l1.md
@@ -57,7 +57,7 @@ We call this pattern _designed caller_ which enables a new paradigm **where we c
 
 Congratulations, you have written all the contracts we need for this tutorial! Now let's compile them.
 
-Compile your Solidity contracts using hardhat. Run this in the root of your project:
+Compile your Solidity contracts using hardhat. Run this in the `packages` directory:
 
 ```bash
 cd l1-contracts

diff --git a/docs/docs/dev_docs/tutorials/uniswap/l1_portal.md b/docs/docs/dev_docs/tutorials/uniswap/l1_portal.md
@@ -20,9 +20,9 @@ import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 import {IRegistry} from "@aztec/l1-contracts/src/core/interfaces/messagebridge/IRegistry.sol";
 import {DataStructures} from "@aztec/l1-contracts/src/core/libraries/DataStructures.sol";
 import {Hash} from "@aztec/l1-contracts/src/core/libraries/Hash.sol";
-```
 
-#include_code setup l1-contracts/test/portals/UniswapPortal.sol solidity raw
+#include_code setup l1-contracts/test/portals/UniswapPortal.sol raw
+```
 
 In this set up we defined the `initialize()` function and a struct (`LocalSwapVars`) to manage assets being swapped.
 

diff --git a/docs/docs/dev_docs/tutorials/uniswap/setup.md b/docs/docs/dev_docs/tutorials/uniswap/setup.md
@@ -11,7 +11,7 @@ If you don’t have this, you can find the code for it [in our dev-rels repo](ht
 To interact with Uniswap we need to add its interface. In the root repo we created in the [token bridge tutorial](../token_portal/main.md), run this:
 
 ```bash
-cd l1-contracts
+cd packages/l1-contracts
 mkdir external && cd external
 touch ISwapRouter.sol
 ```

diff --git a/docs/docs/dev_docs/tutorials/uniswap/typescript_glue_code.md b/docs/docs/dev_docs/tutorials/uniswap/typescript_glue_code.md
@@ -4,9 +4,9 @@ title: Deploy & Call Contracts with Typescript
 
 In this step, we We will now write a Typescript to interact with the sandbox and see our Solidity and Aztec.nr contracts in action.
 
-In the root folder, go to `src` dir we created in [the token bridge tutorial](../token_portal/setup.md).
+In the `packages` directory, go to `src` dir we created in [the token bridge tutorial](../token_portal/setup.md).
 
-```sh
+```bash
 cd src/test
 touch uniswap.test.ts
 ```
@@ -22,14 +22,14 @@ We will write two tests:
 
 To compile the Solidity contracts, run this:
 
-```sh
+```bash
 cd l1-contracts
 npx hardhat compile
 ```
 
 and the Aztec.nr contracts:
 
-```sh
+```bash
 cd aztec-contracts
 aztec-cli compile --typescript ../../src/test/fixtures uniswap
 ```
@@ -59,7 +59,7 @@ export FORK_URL=<YOUR_RPC_URL e.g. https://mainnet.infura.io/v3/API_KEY>
 
 Now rerun the sandbox:
 
-```sh
+```bash
 /bin/sh -c "$(curl -fsSL 'https://sandbox.aztec.network')"
 ```
 
@@ -114,9 +114,9 @@ const MNEMONIC = "test test test test test test test test test test test junk";
 const hdAccount = mnemonicToAccount(MNEMONIC);
 const expectedForkBlockNumber = 17514288;
 
-#include_code uniswap_l1_l2_test_setup_const yarn-project/end-to-end/src/shared/uniswap_l1_l2.ts typescript raw
-#include_code uniswap_setup yarn-project/canary/src/uniswap_trade_on_l1_from_l2.test.ts typescript raw
-#include_code uniswap_l1_l2_test_beforeAll yarn-project/end-to-end/src/shared/uniswap_l1_l2.ts typescript raw
+#include_code uniswap_l1_l2_test_setup_const yarn-project/end-to-end/src/shared/uniswap_l1_l2.ts raw
+#include_code uniswap_setup yarn-project/canary/src/uniswap_trade_on_l1_from_l2.test.ts raw
+#include_code uniswap_l1_l2_test_beforeAll yarn-project/end-to-end/src/shared/uniswap_l1_l2.ts raw
 ```
 
 ## Private flow test
@@ -131,13 +131,13 @@ const expectedForkBlockNumber = 17514288;
 
 Make sure your sandbox is running.
 
-```sh
+```bash
 cd ~/.aztec && docker-compose up
 ```
 
 Then run this in the root directory.
 
 ```bash
-cd src
+cd packages/src
 yarn test uniswap
 ```
diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -54,7 +54,7 @@ const sidebars = {
 
     {
       type: "html",
-      value: '<span class="sidebar-divider" />',
+      value: '<span clasuns="sidebar-divider" />',
     },
 
     // SPECIFICATION
@@ -244,7 +244,7 @@ const sidebars = {
           ],
         },
         {
-          label: "Build Uniswap with Portals",
+          label: "Swap on L1 Uniswap from L2 with Portals",
           type: "category",
           link: {
             type: "doc",
@@ -311,27 +311,27 @@ const sidebars = {
         },
         "dev_docs/contracts/common_errors",
         {
-           label: "Resources",
-           type: "category",
-           items: [
-             //"dev_docs/contracts/resources/style_guide",
-             {
-               label: "Common Patterns",
-               type: "category",
-        //       link: {
-        //         type: "doc",
-        //         id: "dev_docs/contracts/resources/common_patterns/main",
-        //       },
-               items: [
+          label: "Resources",
+          type: "category",
+          items: [
+            //"dev_docs/contracts/resources/style_guide",
+            {
+              label: "Common Patterns",
+              type: "category",
+              //       link: {
+              //         type: "doc",
+              //         id: "dev_docs/contracts/resources/common_patterns/main",
+              //       },
+              items: [
                 "dev_docs/contracts/resources/common_patterns/authwit",
-        //         "dev_docs/contracts/resources/common_patterns/sending_tokens_to_user",
-        //         "dev_docs/contracts/resources/common_patterns/sending_tokens_to_contract",
-        //         "dev_docs/contracts/resources/common_patterns/access_control",
-        //         "dev_docs/contracts/resources/common_patterns/interacting_with_l1",
-               ],
-             },
-           ],
-         },
+                //         "dev_docs/contracts/resources/common_patterns/sending_tokens_to_user",
+                //         "dev_docs/contracts/resources/common_patterns/sending_tokens_to_contract",
+                //         "dev_docs/contracts/resources/common_patterns/access_control",
+                //         "dev_docs/contracts/resources/common_patterns/interacting_with_l1",
+              ],
+            },
+          ],
+        },
         // {
         //   label: "Security Considerations",
         //   type: "category",