docs: adding intro to sway (#55)

* Content is complete just need to revise grammar and formatting * Majority of the information is here now time to make grammar edits * Fix UI * Finished revisions * Adding intro to sway as submodule * adding code imports and better code detection * fixing github audit * Removing submodule and fixing audit * Ready for review * Ready for review * Revert "Ready for review" This reverts commit 439e392. * Revert "Ready for review" This reverts commit 04e73fa. * Revert "Removing submodule and fixing audit" This reverts commit 82be9e4. * Audit fix * Updated intro-to-sway submodule to latest commit * Ready for review * Moving intro to sway example * Revert "Moving intro to sway example" This reverts commit 368ede7. * Update docs/guides/docs/intro-to-sway/contract-functions.mdx Co-authored-by: Sarah Schwartz <[email protected]> * Update docs/guides/docs/intro-to-sway/contract-structs.mdx Co-authored-by: Sarah Schwartz <[email protected]> * Update docs/guides/docs/intro-to-sway/contract-structs.mdx Co-authored-by: Sarah Schwartz <[email protected]> * Update docs/guides/docs/intro-to-sway/contract-abi.mdx Co-authored-by: Sarah Schwartz <[email protected]> * Update docs/guides/docs/intro-to-sway/contract-errors.mdx Co-authored-by: Sarah Schwartz <[email protected]> * small fixes * Update docs/guides/docs/intro-to-sway/rust-sdk.mdx Co-authored-by: Sarah Schwartz <[email protected]> * More changes * Checkpoint before continuing to resolve more comments * Going to continue on the weekend * Testing code import changeback * testing quickstart * Finished * Small change * New code changes * Andres comments * Pausing for now * Fix linter * Fix linter * Fix * Lint * lint * spell * Fixing indentation * Fix * Imports are looking good now * Removing intro to sway git module * Removing intro to sway git module * Remove existing 'docs/guides/examples' from the index * Submodule added * Fixing frontend tests * Almost ready for review * fix lint * Brining back in tests * fix * fix * stupid * fix * fix * updating * Resetting checks * adding to it * fix * Adding this for later * Updating intro to sway side * Update docs/guides/docs/intro-to-sway/typescript-sdk.mdx Co-authored-by: Sarah Schwartz <[email protected]> * Update docs/guides/docs/intro-to-sway/typescript-sdk.mdx Co-authored-by: Sarah Schwartz <[email protected]> * Update docs/guides/docs/intro-to-sway/contract-abi.mdx Co-authored-by: Sarah Schwartz <[email protected]> * fix * testing singular * test only playwrite * Playwrite tests seperate * parallelization * more extraction fixes * Ready for review * small fixes * fix * Sarah changes * Reaedy * Ready * Fixing test * Missing label --------- Co-authored-by: Sarah Schwartz <[email protected]>
FuelLabs · Nov 29, 2023 · 098cb54 · 098cb54
1 parent 6ed6042
commit 098cb54
Show file tree

Hide file tree

Showing 36 changed files with 2,064 additions and 122 deletions.
diff --git a/.github/workflows/guides.yml b/.github/workflows/guides.yml
@@ -33,13 +33,19 @@ jobs:
       - name: Lint Check
         run: markdownlint --config .markdownlint.yaml --ignore-path .markdownlintignore '**/*.mdx'
 
-  ## QUICKSTART TEST
-  quickstart-test:
+  ## QUICKSTART E2E TESTS
+  quickstart-e2e-tests:
     timeout-minutes: 30
-    name: build-quickstart-contract
+    name: Quickstart E2E Tests
     runs-on: ubuntu-latest
-    steps:
+    strategy:
+      matrix:
+        # note: must match the names in test.spec.ts 
+        guide:
+          - "dev quickstart" 
+          - "intro to sway"
 
+    steps:
     # SETUP
       - uses: actions/checkout@v3
         with:
@@ -74,26 +80,13 @@ jobs:
       - name: Set Default Beta-4 Toolchain
         run: fuelup toolchain install beta-4 && fuelup default beta-4
 
-    # BUILD & RUN QUICKSTART CONTRACT TEST
-      - name: Build Contract
-        run: forc build --path ./docs/guides/examples/quickstart/counter-contract
-      - name: Run contract tests
-        uses: actions-rs/cargo@v1
-        with:
-            command: test
-            args: --manifest-path ./docs/guides/examples/quickstart/counter-contract/Cargo.toml
-      - name: Check Cargo fmt & clippy
-        run: |
-            cd docs/guides/examples/quickstart/counter-contract
-            cargo fmt --all --check
-            cargo clippy --all-targets --all-features
+    # RUN E2E TESTS
+      - name: Run Playwright tests for ${{ matrix.guide }}
+        run: xvfb-run --auto-servernum pnpm test:guides --grep "${{ matrix.guide }}"
 
-    # RUN QUICKSTART E2E TEST
-      - name: Run Playwright tests
-        run: xvfb-run --auto-servernum pnpm test:guides
       - uses: actions/upload-artifact@v2
         if: always()
         with:
-          name: playwright-report
+          name: playwright-report-${{ matrix.guide }}
           path: playwright-report/
           retention-days: 30
diff --git a/.gitmodules b/.gitmodules
@@ -28,6 +28,9 @@
 [submodule "docs/fuel-specs"]
 	path = docs/fuel-specs
 	url = https://github.com/FuelLabs/fuel-specs.git
+[submodule "docs/guides/examples/intro-to-sway"]
+	path = docs/guides/examples/intro-to-sway
+	url = https://github.com/FuelLabs/intro-to-sway.git
 [submodule "docs/latest/sway"]
 	path = docs/latest/sway
 	url = https://github.com/FuelLabs/sway.git

diff --git a/docs/about-fuel/networks/beta-3.md b/docs/about-fuel/networks/beta-3.md
@@ -54,7 +54,7 @@ This installs the following components and versions:
 To set the `beta-3` toolchain as your default, run
 
 ```console
-$ fuelup default beta-3
+fuelup default beta-3
 default toolchain set to 'beta-3-aarch64-apple-darwin'
 ```
 

diff --git a/docs/guides/docs/guides.json b/docs/guides/docs/guides.json
@@ -11,6 +11,12 @@
     "featured": true,
     "tags": ["Getting Started", "Full Stack"]
   },
+  "intro_to_sway": {
+    "title": "Introduction to Sway for Javascript developers",
+    "description": "Learn Sway fundamentals by building a marketplace dApp.",
+    "featured": false,
+    "tags": ["Full Stack"]
+  },
   "running_a_node": {
     "title": "Running a Node",
     "description": "Run a local Fuel node.",

diff --git a/docs/guides/docs/installation/index.mdx b/docs/guides/docs/installation/index.mdx
@@ -24,13 +24,13 @@ The Fuel toolchain is built on top of the Rust programming language. To install
 
 Run the following command in your shell; this downloads and runs `rustup-init.sh`, which in turn downloads and runs the correct version of the `rustup-init` executable for your platform.
 
-{/*install_rust_command:example:start*/}
+{/*ANCHOR: install_rust_command*/}
 
 ```console
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 ```
 
-{/*install_rust_command:example:end*/}
+{/*ANCHOR: install_rust_command*/}
 
 Check the official Rust documentation to get more information on [installing the Rust toolchain](https://www.rust-lang.org/tools/install).
 
@@ -51,13 +51,13 @@ This will install `forc`, `forc-client`, `forc-fmt`, `forc-lsp`, `forc-wallet` a
 
 👉 Just paste the following line in your terminal and press *Enter*.
 
-{/*install_fuelup_command:example:start*/}
+{/*ANCHOR: install_fuelup_command*/}
 
 ```sh
 curl --proto '=https' --tlsv1.2 -sSf https://install.fuel.network/fuelup-init.sh | sh
 ```
 
-{/*install_fuelup_command:example:end*/}
+{/*ANCHOR_END: install_fuelup_command*/}
 
 > 🚧 Be aware that currently  we do not natively support Windows. If you wish to use `fuelup` on Windows, please use Windows Subsystem for Linux.
 
@@ -142,13 +142,13 @@ To properly interact with the {props.fuelTestnetInlineCode} network it is necess
 👉 Run the following command to install the {props.fuelTestnetInlineCode} toolchain:
 {/*install_testnet:example:end*/}
 
-{/*install_testnet_command:example:start*/}
+{/*ANCHOR: install_testnet_command*/}
 
 ```console
 fuelup toolchain install beta-4
 ```
 
-{/*install_testnet_command:example:end*/}
+{/*ANCHOR_END: install_testnet_command*/}
 
 If the toolchain was successfully installed, you will see this output:
 
@@ -162,13 +162,13 @@ The toolchain was installed correctly, however is not in use yet. Next, you need
 👉 Set {props.fuelTestnetInlineCode} as your default toolchain with the following command:
 {/*set_default_testnet:example:end*/}
 
-{/*set_default_testnet_command:example:start*/}
+{/*ANCHOR: set_default_testnet_command*/}
 
 ```console
 fuelup default beta-4
 ```
 
-{/*set_default_testnet_command:example:end*/}
+{/*ANCHOR_END: set_default_testnet_command*/}
 
 You will get the following output indicating that you have successfully set {props.fuelTestnetInlineCode} as your default toolchain.
 

diff --git a/docs/guides/docs/intro-to-sway/checkpoint.mdx b/docs/guides/docs/intro-to-sway/checkpoint.mdx
@@ -0,0 +1,73 @@
+---
+title: Checkpoint
+category: Intro to Sway
+parent:
+  label: All Guides
+  link: /guides
+---
+
+# Checkpoint
+
+## Sway Contract Checkpoint
+
+If you have followed the previous steps correctly your `main.sw` marketplace contract should look like this:
+
+<CodeImport
+  file="../../examples/intro-to-sway/contract/src/main.sw"
+  comment="all"
+  commentType="//"
+  lang="sway"
+/>
+
+## Building the contract
+
+Here's a polished version of your instructions:
+
+To format your contract, execute the command:
+
+<TestAction
+id="format-contract"
+action={{
+  name: 'runCommand',
+  commandFolder: 'guides-testing/fuel-project/contract'
+}}
+/>
+
+```sh
+forc fmt
+```
+
+To compile your contract, navigate to the contract folder and run:
+
+<TestAction
+id="build-contract"
+action={{
+  name: 'runCommand',
+  commandFolder: 'guides-testing/fuel-project/contract'
+}}
+/>
+
+```sh
+forc build
+```
+
+Congratulations! You've successfully written a full contract in Sway!
+
+Post-compilation, the system will automatically generate `abi.json`, `storage_slots.json`, and `contract.bin`. You can locate these files in the following directory:
+
+```sh
+contract/out/debug/*
+```
+
+## Deploying the contract
+
+For detailed steps on deploying this contract, refer to the official Fuel developer quickstart guide:
+[Deploy the Contract](/guides/quickstart/building-a-smart-contract/#deploy-the-contract)
+
+To deploy, use the following command if you've already set up the forc-wallet and have testnet funds in your account. If not, follow the instructions above.
+
+```sh
+forc deploy --testnet
+```
+
+After deploying, remember to save your contract ID. You'll need it for frontend integration.
diff --git a/docs/guides/docs/intro-to-sway/contract-abi.mdx b/docs/guides/docs/intro-to-sway/contract-abi.mdx
@@ -0,0 +1,40 @@
+---
+title: ABI
+category: Intro to Sway
+parent:
+  label: All Guides
+  link: /guides
+---
+
+# Defining the ABI
+
+Next, we will define our ABI. ABI stands for Application Binary Interface. In a Sway contract, it serves as an outline of all the functions within the contract. For each function, you need to specify its name, input types, return types, level of storage access, and if it's payable.
+
+The ABI for our contract is structured as follows. Write the ABI provided below into your `main.sw` file:
+
+<TestAction
+id="sway-abi"
+action={{
+  name: 'modifyFile',
+  filepath: 'guides-testing/fuel-project/contract/src/main.sw'
+}}
+/>
+
+<CodeImport
+  file="../../examples/intro-to-sway/contract/src/main.sw"
+  comment="abi"
+  commentType="//"
+  lang="sway"
+/>
+
+Don't be worried about understanding the specifics of each function at this moment. We will dive into detailed explanations in the "Functions" section.
+
+## Functions Structure
+
+A function is defined using the `fn` keyword. In Sway, snake case is the convention, so instead of naming a function `myFunction`, you would name it `my_function`.
+
+If the function returns a value, its return type must be defined using a skinny arrow. Additionally, if the function has parameters, their types must also be specified. Semicolons are *required* at the end of each statement.
+
+If a function either reads from or writes to storage, you need to specify the access level above the function using annotations like `#[storage(read)]` or `#[storage(read, write)]`.
+
+For functions that are expected to receive funds when called, such as the `buy_item` function, the `#[payable]` annotation is required.
diff --git a/docs/guides/docs/intro-to-sway/contract-errors.mdx b/docs/guides/docs/intro-to-sway/contract-errors.mdx
@@ -0,0 +1,40 @@
+---
+title: Errors
+category: Intro to Sway
+parent:
+  label: All Guides
+  link: /guides
+---
+
+# Defining Error Handling
+
+Enumerations, commonly referred to as enums, are a type that can represent one of several possible variants. Within our contract, we can employ enums to craft custom error messages, facilitating more precise error handling within functions.
+
+Copy the custom error block into your `main.sw` file:
+
+<TestAction
+id="sway-errors"
+action={{
+  name: 'modifyFile',
+  filepath: 'guides-testing/fuel-project/contract/src/main.sw'
+}}
+/>
+
+<CodeImport
+  file="../../examples/intro-to-sway/contract/src/main.sw"
+  comment="error_handling"
+  commentType="//"
+  lang="sway"
+/>
+
+Within our contract, we can anticipate various scenarios where we'd want to throw an error and halt the transaction:
+
+1. Someone might attempt to pay for an item using an incorrect currency.
+2. An individual could try to purchase an item without possessing sufficient coins.
+3. Someone other than the owner might attempt to withdraw funds from the contract.
+
+For each situation, we can define specific return types for the errors:
+
+- For the `IncorrectAssetId` error, we can return the submitted asset id, which is of type `AssetId`.
+- In the case of the `NotEnoughTokens` error, we can define the return type as `u64` to indicate the number of coins involved.
+- For the `OnlyOwner` error, we can utilize the `Identity` of the message sender as the return value.