From fe65ca46dd3f1b2e0f76b974b845829396fdbd44 Mon Sep 17 00:00:00 2001 From: Sarah Schwartz <58856580+sarahschwartz@users.noreply.github.com> Date: Tue, 19 Dec 2023 16:10:26 -0700 Subject: [PATCH] docs: configure spell check, minor improvements (#5369) This PR configures the spell-check added to the docs workflow in the github-actions repo: https://github.com/FuelLabs/github-actions/pull/23 The files checked are configured in `.spellcheck.yml`. This is also where you can configure what types of elements are ignored. Right now it ignores: - All code blocks that have a language (and will check code blocks that do not have a language) - Anything in between backticks - Words in `spell-check-custom-words.txt` (case sensitive, only exact match) - Numbers, even if they are attached to a word - Links in markdown link format #### Handling errors: If the test fails: - look up the word in the question to verify it is a real word and is correctly spelled - If it is a file name or is code, use backticks to ignore the word. - If it is a real word that is spelled correctly, or an acronym that is either common or is defined already, add it to `spell-check-custom-words.txt`. - If needed, rewrite the sentence. Ex: DON'T use "`lock`ing" and add "ing" to the custom words list. Instead, rewrite the sentence as "locking with the `lock` method". - If it otherwise should be ignored, you can configure the pipeline in `.spellcheck.yml`. --------- Co-authored-by: Sophie Dankel <47993817+sdankel@users.noreply.github.com> --- .github/workflows/docs.yml | 3 +- docs/book/.spellcheck.yml | 28 +++ docs/book/spell-check-custom-words.txt | 187 ++++++++++++++++++ docs/book/src/SUMMARY.md | 50 ++--- docs/book/src/advanced/assembly.md | 4 +- docs/book/src/advanced/associated_types.md | 2 +- docs/book/src/advanced/traits.md | 6 +- docs/book/src/basics/blockchain_types.md | 2 +- docs/book/src/basics/built_in_types.md | 6 +- docs/book/src/basics/constants.md | 2 +- docs/book/src/basics/index.md | 2 +- .../methods_and_associated_functions.md | 2 +- .../src/basics/structs_tuples_and_enums.md | 2 +- .../blockchain-development/access_control.md | 2 +- .../calling_contracts.md | 8 +- .../blockchain-development/native_assets.md | 2 +- docs/book/src/common-collections/index.md | 10 +- .../src/common-collections/storage_vec.md | 18 +- docs/book/src/examples/fizzbuzz.md | 4 +- docs/book/src/examples/index.md | 2 +- docs/book/src/forc/commands/forc_addr2line.md | 2 +- docs/book/src/forc/commands/forc_build.md | 2 +- docs/book/src/forc/commands/forc_check.md | 2 +- docs/book/src/forc/commands/forc_clean.md | 2 +- .../src/forc/commands/forc_completions.md | 2 +- .../src/forc/commands/forc_contract-id.md | 2 +- docs/book/src/forc/commands/forc_init.md | 2 +- docs/book/src/forc/commands/forc_new.md | 2 +- .../src/forc/commands/forc_parse-bytecode.md | 2 +- docs/book/src/forc/commands/forc_plugins.md | 2 +- .../src/forc/commands/forc_predicate-root.md | 2 +- docs/book/src/forc/commands/forc_template.md | 2 +- docs/book/src/forc/commands/forc_test.md | 2 +- docs/book/src/forc/commands/forc_update.md | 2 +- docs/book/src/forc/dependencies.md | 4 +- docs/book/src/forc/index.md | 2 +- docs/book/src/forc/manifest_reference.md | 16 +- .../forc/plugins/forc_client/forc_deploy.md | 2 +- .../src/forc/plugins/forc_client/forc_run.md | 2 +- .../forc/plugins/forc_client/forc_submit.md | 2 +- .../src/forc/plugins/forc_client/index.md | 6 +- docs/book/src/forc/plugins/forc_crypto.md | 2 +- docs/book/src/forc/plugins/forc_doc.md | 2 +- docs/book/src/forc/plugins/forc_explore.md | 2 +- docs/book/src/forc/plugins/forc_fmt.md | 2 +- docs/book/src/forc/plugins/forc_lsp.md | 2 +- .../book/src/introduction/standard_library.md | 2 +- docs/book/src/lsp/installation.md | 2 +- .../book/src/reference/compiler_intrinsics.md | 2 +- .../src/reference/contributing_to_sway.md | 4 +- docs/book/src/reference/keywords.md | 10 +- docs/book/src/reference/rust_differences.md | 2 +- docs/book/src/sway-program-types/index.md | 2 +- docs/book/src/sway-program-types/libraries.md | 6 +- docs/book/src/sway-program-types/scripts.md | 4 +- .../src/sway-program-types/smart_contracts.md | 6 +- docs/book/src/testing/testing-with-rust.md | 14 +- forc-plugins/forc-debug/docs/walkthrough.md | 25 ++- 58 files changed, 353 insertions(+), 140 deletions(-) create mode 100644 docs/book/.spellcheck.yml create mode 100644 docs/book/spell-check-custom-words.txt diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c1f83a27c3c..ad352609cf9 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -12,4 +12,5 @@ jobs: test: uses: FuelLabs/github-actions/.github/workflows/mdbook-docs.yml@master with: - docs-src-path: 'docs/book/src' \ No newline at end of file + docs-src-path: 'docs/book/src' + spellcheck-config-path: 'docs/book/.spellcheck.yml' \ No newline at end of file diff --git a/docs/book/.spellcheck.yml b/docs/book/.spellcheck.yml new file mode 100644 index 00000000000..8030b91c02a --- /dev/null +++ b/docs/book/.spellcheck.yml @@ -0,0 +1,28 @@ +matrix: + - name: SPCheck + aspell: + lang: en + dictionary: + encoding: utf-8 + wordlists: + - docs/book/spell-check-custom-words.txt + pipeline: + - pyspelling.filters.context: + context_visible_first: true + escapes: \\[\\`~] + delimiters: + # Ignore all code blocks + - open: '(?s)^(?P *`{3,}\s*(\w+\s*,?\s*)+.*?)$' + close: '^( *`{3,})$' + - pyspelling.filters.markdown: + markdown_extensions: + - pymdownx.superfences: + - pyspelling.filters.html: + comments: false + ignores: + - code + - pre + sources: + - '**/book/src/*.md' + - '**/book/src/**/*.md' + default_encoding: utf-8 diff --git a/docs/book/spell-check-custom-words.txt b/docs/book/spell-check-custom-words.txt new file mode 100644 index 00000000000..52bc4fc8749 --- /dev/null +++ b/docs/book/spell-check-custom-words.txt @@ -0,0 +1,187 @@ +ABI +ABIs +ASM +IDE +IDEs +LSP +namespace +ALU +APIs +JSON +BrowserStack +CLI +Deserialization +deserializing +DApp +subcurrency +Subcurrency +intrinsics +Intrinsics +workspace +workspaces +Workspaces +neovim +EVM +EVM's +EOA +ERC +Ethereum +Ethereum's +FVM +FuelVM +Fuelup +Github +GraphQL +Infura +JSON +LSP +Merkle +PoA +PoS +PoW +RPC +SDK +SDK's +SDKs +SauceLabs +Sepolia +Structs +Sway +TAI +TODO +TypeScript +UTF +UTXO +UTXOs +Utils +VM +VSCode +abigen +args +async +backend +backtraces +blockchain +blockchain's +bytecode +codespace +codespaces +config +cryptographic +customizable +customizations +dapp +dev +dropdown +enum +enums +env +forc +frontend +fuelup +fullstack +graphQL +graphql +http +https +js +localhost +mainnet +mempool +merkle +monorepo +monorepos +natively +npm +nvm +onboarding +params +pnpm +prerelease +queryable +quickstart +relayer +relayers +repo +repos +runnable +stateful +struct +structs +struct's +testnet +testnets +toolchain +toolchains +urql +validator +validators +superABI +superABIs +SuperABIs +supertraits +compositional +typeclass +turbofish +DSL +TOML +IPFS +Bitwise +Bitwise +runtime +runtimes +formatter +deployable +Utils +ETH +initializer +initializers +destructuring +instantiation +VMs +superset +CEI +pre +entrancy +interoperable +blockchains +keccak +SHA +UI +backtrace +Collateralized +collateralized +submodule +DEX +TypeChain +inlines +inlining +MiB +FuelVM's +deterministically +CLI +VS +GraphViz +DOT +DCA +AST +GitHub +decrypt +subcommand +subcommands +Subcommands +supertrait +supertraits +Supertraits +incrementor +monomorphization +Booleans +boolean +Orchestrator +orchestrator +growable +arity +tuple's +unary +SRC +DEX \ No newline at end of file diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index c72c9c3561a..655b0947318 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -10,7 +10,7 @@ - [Examples](./examples/index.md) - [Counter](./examples/counter.md) - [Subcurrency](./examples/subcurrency.md) - - [FizzBuzz](./examples/fizzbuzz.md) + - [`FizzBuzz`](./examples/fizzbuzz.md) - [Wallet Smart Contract](./examples/wallet_smart_contract.md) - [Program Types](./sway-program-types/index.md) - [Contracts](./sway-program-types/smart_contracts.md) @@ -69,28 +69,28 @@ - [Workspaces](./forc/workspaces.md) - [Dependencies](./forc/dependencies.md) - [Commands](./forc/commands/index.md) - - [forc addr2line](./forc/commands/forc_addr2line.md) - - [forc build](./forc/commands/forc_build.md) - - [forc check](./forc/commands/forc_check.md) - - [forc clean](./forc/commands/forc_clean.md) - - [forc completions](./forc/commands/forc_completions.md) - - [forc contract-id](./forc/commands/forc_contract-id.md) - - [forc init](./forc/commands/forc_init.md) - - [forc new](./forc/commands/forc_new.md) - - [forc parse-bytecode](./forc/commands/forc_parse-bytecode.md) - - [forc plugins](./forc/commands/forc_plugins.md) - - [forc predicate-root](./forc/commands/forc_predicate-root.md) - - [forc test](./forc/commands/forc_test.md) - - [forc update](./forc/commands/forc_update.md) - - [forc template](./forc/commands/forc_template.md) + - [`forc addr2line`](./forc/commands/forc_addr2line.md) + - [`forc build`](./forc/commands/forc_build.md) + - [`forc check`](./forc/commands/forc_check.md) + - [`forc clean`](./forc/commands/forc_clean.md) + - [`forc completions`](./forc/commands/forc_completions.md) + - [`forc contract-id`](./forc/commands/forc_contract-id.md) + - [`forc init`](./forc/commands/forc_init.md) + - [`forc new`](./forc/commands/forc_new.md) + - [`forc parse-bytecode`](./forc/commands/forc_parse-bytecode.md) + - [`forc plugins`](./forc/commands/forc_plugins.md) + - [`forc predicate-root`](./forc/commands/forc_predicate-root.md) + - [`forc test`](./forc/commands/forc_test.md) + - [`forc update`](./forc/commands/forc_update.md) + - [`forc template`](./forc/commands/forc_template.md) - [Plugins](./forc/plugins/index.md) - - [forc client](./forc/plugins/forc_client/index.md) - - [forc deploy](./forc/plugins/forc_client/forc_deploy.md) - - [forc run](./forc/plugins/forc_client/forc_run.md) - - [forc submit](./forc/plugins/forc_client/forc_submit.md) - - [forc crypto](./forc/plugins/forc_crypto.md) - - [forc debug](./forc/plugins/forc_debug.md) - - [forc doc](./forc/plugins/forc_doc.md) - - [forc explore](./forc/plugins/forc_explore.md) - - [forc fmt](./forc/plugins/forc_fmt.md) - - [forc lsp](./forc/plugins/forc_lsp.md) + - [`forc client`](./forc/plugins/forc_client/index.md) + - [`forc deploy`](./forc/plugins/forc_client/forc_deploy.md) + - [`forc run`](./forc/plugins/forc_client/forc_run.md) + - [`forc submit`](./forc/plugins/forc_client/forc_submit.md) + - [`forc crypto`](./forc/plugins/forc_crypto.md) + - [`forc debug`](./forc/plugins/forc_debug.md) + - [`forc doc`](./forc/plugins/forc_doc.md) + - [`forc explore`](./forc/plugins/forc_explore.md) + - [`forc fmt`](./forc/plugins/forc_fmt.md) + - [`forc lsp`](./forc/plugins/forc_lsp.md) diff --git a/docs/book/src/advanced/assembly.md b/docs/book/src/advanced/assembly.md index 313191d0f01..3bad77ecab6 100644 --- a/docs/book/src/advanced/assembly.md +++ b/docs/book/src/advanced/assembly.md @@ -1,10 +1,10 @@ # Inline Assembly in Sway -While many users will never have to touch assembly language while writing sway code, it is a powerful tool that enables many advanced use-cases (ie: optimizations, building libraries, etc). +While many users will never have to touch assembly language while writing sway code, it is a powerful tool that enables many advanced use-cases (e.g., optimizations, building libraries, etc). ## ASM Block -In Sway, the way we use assembly inline is to declare an asm block like this: +In Sway, the way we use assembly inline is to declare an `asm` block like this: ```sway asm() {...} diff --git a/docs/book/src/advanced/associated_types.md b/docs/book/src/advanced/associated_types.md index e9606225943..1828026ebb4 100644 --- a/docs/book/src/advanced/associated_types.md +++ b/docs/book/src/advanced/associated_types.md @@ -61,7 +61,7 @@ In this example, `get_value` is a trait method that returns an associated type ` ## Use Cases Associated types are particularly useful in scenarios where you want to define traits that work with different -types of data structures or abstractions, allowing the implementor to specify the concrete types. Some common use cases include: +types of data structures or abstractions, allowing the implementer to specify the concrete types. Some common use cases include: - Collections: Traits for generic collections that allow users to specify the type of elements. - Iterator Patterns: Traits for implementing iterators with varying element types. diff --git a/docs/book/src/advanced/traits.md b/docs/book/src/advanced/traits.md index 08a039ae851..ed87d3b3732 100644 --- a/docs/book/src/advanced/traits.md +++ b/docs/book/src/advanced/traits.md @@ -20,7 +20,7 @@ We have just declared a trait called `Compare`. After the name of the trait, the ## Implementing a Trait -Ok, so I know that numbers can be equal. I want to implement my `Compare` trait for `u64`. Let's take a look at how that is done: +The example below implements a `Compare` trait for `u64` to check if two numbers are equal. Let's take a look at how that is done: ```sway impl Compare for u64 { @@ -34,8 +34,8 @@ The above snippet declares all of the methods in the trait `Compare` for the typ ## Supertraits -When using multiple traits, scenarios often come up where one trait may require functionality from another trait. This is where supertraits come in as they allow you to require a trait when implementing another -trait (ie. a trait with a trait). A good example of this is the `Ord` trait of the `core` library of Sway. The `Ord` trait requires the `Eq` trait, so `Eq` is kept as a separate trait as one may decide to implement `Eq` +When using multiple traits, scenarios often come up where one trait may require functionality from another trait. This is where supertraits come in as they allow you to require a trait when implementing another trait, i.e., a trait with a trait. +A good example of this is the `Ord` trait of the `core` library of Sway. The `Ord` trait requires the `Eq` trait, so `Eq` is kept as a separate trait as one may decide to implement `Eq` without implementing other parts of the `Ord` trait. ```sway diff --git a/docs/book/src/basics/blockchain_types.md b/docs/book/src/basics/blockchain_types.md index 86b0ff799b3..e91312eda34 100644 --- a/docs/book/src/basics/blockchain_types.md +++ b/docs/book/src/basics/blockchain_types.md @@ -54,7 +54,7 @@ let forty_two: b256 = my_contract_id.into(); -The `Identity` type is an enum that allows for the handling of both `Address` and `ContractId` types. This is useful in cases where either type is accepted, e.g. receiving funds from an identified sender, but not caring if the sender is an address or a contract. +The `Identity` type is an enum that allows for the handling of both `Address` and `ContractId` types. This is useful in cases where either type is accepted, e.g., receiving funds from an identified sender, but not caring if the sender is an address or a contract. An `Identity` is implemented as follows. diff --git a/docs/book/src/basics/built_in_types.md b/docs/book/src/basics/built_in_types.md index f7e500589b2..f42bb1525bc 100644 --- a/docs/book/src/basics/built_in_types.md +++ b/docs/book/src/basics/built_in_types.md @@ -52,7 +52,7 @@ computation gets reverted automatically by FuelVM. additional overflow/underflow checks inserted, which generally results in somewhat higher gas consumption. -The same does not happen with 256-bit operations, including `b256`, which uses specialized operations and are as performant as possible. +The same does not happen with 256-bit operations, including `b256`, which uses specialized operations and are as efficient as possible. ## Boolean Type @@ -82,7 +82,7 @@ In Sway, string literals are stored as variable length string slices. Which mean let my_string: str = "fuel"; ``` -String slices, because they contain pointers have limited usage. They cannot be used is constants, storages, configurables, nor as main function argument or returns. +String slices, because they contain pointers, have limited usage. They cannot be used in constants, storage, configurable constants, nor as main function arguments or returns. For these cases one must use string arrays, as described below. @@ -174,7 +174,7 @@ let x = [1, 2, 3, 4, 5]; Arrays are allocated on the stack since their size is known. An array's size is _always_ static, i.e. it cannot change. An array of five elements cannot become an array of six elements. -Arrays can be iterated over, unlike tuples. An array's type is written as the type the array contains followed by the number of elements, semicolon-separated and within square brackets, e.g. `[u64; 5]`. To access an element in an array, use the _array indexing syntax_, i.e. square brackets. +Arrays can be iterated over, unlike tuples. An array's type is written as the type the array contains followed by the number of elements, semicolon-separated and within square brackets, e.g., `[u64; 5]`. To access an element in an array, use the _array indexing syntax_, i.e. square brackets. Array elements can also be mutated if the underlying array is declared as mutable: diff --git a/docs/book/src/basics/constants.md b/docs/book/src/basics/constants.md index be52dcec323..d5d8a48413b 100644 --- a/docs/book/src/basics/constants.md +++ b/docs/book/src/basics/constants.md @@ -46,7 +46,7 @@ The identifier is the name of the constant used in the path. The type is the typ definition has to implement. -You can _define_ an associated const directly in the interface surface of a trait: +You can _define_ an associated `const` directly in the interface surface of a trait: ```sway script; diff --git a/docs/book/src/basics/index.md b/docs/book/src/basics/index.md index cc2aaffa186..8f0511b9e8b 100644 --- a/docs/book/src/basics/index.md +++ b/docs/book/src/basics/index.md @@ -1,6 +1,6 @@ # Sway Language basics -Sway is a programming language designed for the FuelVM. It is a statically typed, compiled language with type inference and traits. Sway aims to make smart contract development safer and more performant through the use of strong static analysis and compiler feedback. +Sway is a programming language designed for the FuelVM. It is a statically typed, compiled language with type inference and traits. Sway aims to make smart contract development safer and more efficient through the use of strong static analysis and compiler feedback. Get started with the basics of Sway: diff --git a/docs/book/src/basics/methods_and_associated_functions.md b/docs/book/src/basics/methods_and_associated_functions.md index f21ed9a7b49..b25443a8dda 100644 --- a/docs/book/src/basics/methods_and_associated_functions.md +++ b/docs/book/src/basics/methods_and_associated_functions.md @@ -6,7 +6,7 @@ Methods are similar to functions in that we declare them with the `fn` keyword a _Associated functions_ are very similar to _methods_, in that they are also defined in the context of a struct or enum, but they do not actually use any of the data in the struct and as a result do not take _self_ as a parameter. Associated functions could be standalone functions, but they are included in a specific type for organizational or semantic reasons. -To declare methods and associated functions for a struct or enum, use an _impl block_. Here, `impl` stands for implementation. +To declare methods and associated functions for a struct or enum, use an `impl` block. Here, `impl` is short for implementation. ```sway diff --git a/docs/book/src/basics/structs_tuples_and_enums.md b/docs/book/src/basics/structs_tuples_and_enums.md index d28973dbd5b..4ec75211eb1 100644 --- a/docs/book/src/basics/structs_tuples_and_enums.md +++ b/docs/book/src/basics/structs_tuples_and_enums.md @@ -19,7 +19,7 @@ In order to instantiate the struct we use _struct instantiation syntax_, which i There are three ways to instantiate the struct. -- Hardcoding values for the fields +- Hard coding values for the fields - Passing in variables with names different than the struct fields - Using a shorthand notation via variables that are the same as the field names diff --git a/docs/book/src/blockchain-development/access_control.md b/docs/book/src/blockchain-development/access_control.md index 279a2b12d1c..08fa6b5f39d 100644 --- a/docs/book/src/blockchain-development/access_control.md +++ b/docs/book/src/blockchain-development/access_control.md @@ -29,7 +29,7 @@ The `msg_sender` function works as follows: Many contracts require some form of ownership for access control. The [SRC-5 Ownership Standard](https://github.com/FuelLabs/sway-standards/tree/master/standards/src_5) has been defined to provide a interoperable interface for ownership within contracts. -To accomplish this, use the [Ownerhsip Library](https://github.com/FuelLabs/sway-libs/tree/master/libs/ownership) to keep track of the owner. This allows setting and revoking ownership using the variants `Some(..)` and `None` respectively. This is better, safer, and more readable than using the `Identity` type directly where revoking ownership has to be done using some magic value such as `std::constants::ZERO_B256` or otherwise. +To accomplish this, use the [Ownership Library](https://github.com/FuelLabs/sway-libs/tree/master/libs/ownership) to keep track of the owner. This allows setting and revoking ownership using the variants `Some(..)` and `None` respectively. This is better, safer, and more readable than using the `Identity` type directly where revoking ownership has to be done using some magic value such as `std::constants::ZERO_B256` or otherwise. - The following is an example of how to properly lock a function such that only the owner may call a function: diff --git a/docs/book/src/blockchain-development/calling_contracts.md b/docs/book/src/blockchain-development/calling_contracts.md index f49a83ddfff..cb9dbbe42f3 100644 --- a/docs/book/src/blockchain-development/calling_contracts.md +++ b/docs/book/src/blockchain-development/calling_contracts.md @@ -2,7 +2,7 @@ Smart contracts can be _called_ by other contracts or scripts. In the FuelVM, this is done primarily with the [`call`](https://fuellabs.github.io/fuel-specs/master/vm/instruction_set#call-call-contract) instruction. -Sway provides a nice way to manage callable interfaces with its `abi` system. The Fuel ABI specification can be found [here](https://fuellabs.github.io/fuel-specs/master/protocol/abi). +Sway provides a nice way to manage callable interfaces with its ABI system. The Fuel ABI specification can be found [here](https://fuellabs.github.io/fuel-specs/master/protocol/abi). ## Example @@ -78,7 +78,7 @@ fn main() { A common attack vector for smart contracts is [re-entrancy](https://docs.soliditylang.org/en/v0.8.4/security-considerations.html#re-entrancy). Similar to the EVM, the FuelVM allows for re-entrancy. -A _stateless_ re-entrancy guard is included in the [sway-libs](https://github.com/FuelLabs/sway-libs) library. The guard will panic (revert) at run time if re-entrancy is detected. +A _stateless_ re-entrancy guard is included in the [`sway-libs`](https://github.com/FuelLabs/sway-libs) library. The guard will panic (revert) at run time if re-entrancy is detected. ```sway contract; @@ -152,9 +152,9 @@ In case there is a storage read after an interaction, the CEI analyzer will issu In addition to storage reads and writes after an interaction, the CEI analyzer reports analogous warnings about: -- balance tree updates, i.e. balance tree reads with subsequent writes, which may be produced by the `tr` and `tro` asm instructions or library functions using them under the hood; +- balance tree updates, i.e. balance tree reads with subsequent writes, which may be produced by the `tr` and `tro` ASM instructions or library functions using them under the hood; - balance trees reads with `bal` instruction; -- changes to the output messages that can be produced by the `__smo` intrinsic function or the `smo` asm instruction. +- changes to the output messages that can be produced by the `__smo` intrinsic function or the `smo` ASM instruction. ## Differences from the EVM diff --git a/docs/book/src/blockchain-development/native_assets.md b/docs/book/src/blockchain-development/native_assets.md index 7d8c8deab3a..d16a3d67947 100644 --- a/docs/book/src/blockchain-development/native_assets.md +++ b/docs/book/src/blockchain-development/native_assets.md @@ -15,7 +15,7 @@ However, unlike the EVM, the process for sending _any_ native asset is the same. All contracts in Fuel can mint and burn their own native token. Contracts can also receive and transfer any native asset including their own. Internal balances of all native assets pushed through calls or minted by the contract are tracked by the FuelVM and can be queried at any point using the balance_of function from the `std` library. Therefore, there is no need for any manual accounting of the contract's balances using persistent storage. -The `std` library provides handy methods for accessing Fuel's native assset operations. +The `std` library provides handy methods for accessing Fuel's native asset operations. In this example, we show a basic liquidity pool contract minting its own native asset LP token. diff --git a/docs/book/src/common-collections/index.md b/docs/book/src/common-collections/index.md index 707c5fc4f19..d173d0ba8e0 100644 --- a/docs/book/src/common-collections/index.md +++ b/docs/book/src/common-collections/index.md @@ -4,12 +4,12 @@ Sway’s standard library includes a number of very useful data structures calle A vector on the heap allows you to store a variable number of values next to each other. -A storage vector is similar to a vector on the heap but uses persistent storage. +A `StorageVec` is similar to a vector on the heap but uses persistent storage. -A storage map allows you to associate a value with a particular key. +A `StorageMap` allows you to associate a value with a particular key. -We’ll discuss how to create and update vectors, storage vectors, and storage maps, as well as what makes each special. +We’ll discuss how to create and update a vector, `StorageVec`, and `StorageMap`, as well as what makes each special. - [Vectors on the Heap](./vec.md) -- [Storage Vectors](./storage_vec.md) -- [Storage Maps](./storage_map.md) +- [`StorageVec`](./storage_vec.md) +- [`StorageMap`](./storage_map.md) diff --git a/docs/book/src/common-collections/storage_vec.md b/docs/book/src/common-collections/storage_vec.md index 54124808afd..f8a12ca6e96 100644 --- a/docs/book/src/common-collections/storage_vec.md +++ b/docs/book/src/common-collections/storage_vec.md @@ -10,9 +10,9 @@ In order to use `StorageVec`, you must first import `StorageVec` as follows: Another major difference between `Vec` and `StorageVec` is that `StorageVec` can only be used in a contract because only contracts are allowed to access persistent storage. -## Creating a New Storage Vector +## Creating a New `StorageVec` -To create a new empty storage vector, we have to declare the vector in a `storage` block as follows: +To create a new empty `StorageVec`, we have to declare the vector in a `storage` block as follows: ```sway {{#include ../../../../examples/storage_vec/src/main.sw:storage_vec_decl}} @@ -20,17 +20,17 @@ To create a new empty storage vector, we have to declare the vector in a `storag Just like any other storage variable, two things are required when declaring a `StorageVec`: a type annotation and an initializer. The initializer is just an empty struct of type `StorageVec` because `StorageVec` itself is an empty struct! Everything that is interesting about `StorageVec` is implemented in its methods. -Storage vectors, just like `Vec`, are implemented using generics which means that the `StorageVec` type provided by the standard library can hold any type. When we create a storage vector to hold a specific type, we can specify the type within angle brackets. In the example above, we’ve told the Sway compiler that the `StorageVec` in `v` will hold elements of the `u64` type. +Storage vectors, just like `Vec`, are implemented using generics which means that the `StorageVec` type provided by the standard library can hold any type. When we create a `StorageVec` to hold a specific type, we can specify the type within angle brackets. In the example above, we’ve told the Sway compiler that the `StorageVec` in `v` will hold elements of the `u64` type. -## Updating a Storage Vector +## Updating a `StorageVec` -To add elements to a storage vector, we can use the `push` method, as shown below: +To add elements to a `StorageVec`, we can use the `push` method, as shown below: ```sway {{#include ../../../../examples/storage_vec/src/main.sw:storage_vec_push}} ``` -Note two details here. First, in order to use `push`, we need to first access the vector using the `storage` keyword. Second, because `push` requires accessing storage, a `storage` annotation is required on the ABI function that calls `push`. While it may seem that `#[storage(write)]` should be enough here, the `read` annotation is also required because each call to `push` requires _reading_ (and then updating) the length of the storage vector which is also stored in persistent storage. +Note two details here. First, in order to use `push`, we need to first access the vector using the `storage` keyword. Second, because `push` requires accessing storage, a `storage` annotation is required on the ABI function that calls `push`. While it may seem that `#[storage(write)]` should be enough here, the `read` annotation is also required because each call to `push` requires _reading_ (and then updating) the length of the `StorageVec` which is also stored in persistent storage. > **Note** > The storage annotation is also required for any private function defined in the contract that tries to push into the vector. @@ -69,13 +69,13 @@ Storage vectors, just like `Vec`, can only store values that are the same typ {{#include ../../../../examples/storage_vec/src/main.sw:storage_vec_multiple_types_enum}} ``` -Then we can declare a storage vector in a `storage` block to hold that enum and so, ultimately, holds different types: +Then we can declare a `StorageVec` in a `storage` block to hold that enum and so, ultimately, holds different types: ```sway {{#include ../../../../examples/storage_vec/src/main.sw:storage_vec_multiple_types_decl}} ``` -We can now push different enum variants to the storage vector as follows: +We can now push different enum variants to the `StorageVec` as follows: ```sway {{#include ../../../../examples/storage_vec/src/main.sw:storage_vec_multiple_types_fn}} @@ -83,7 +83,7 @@ We can now push different enum variants to the storage vector as follows: Now that we’ve discussed some of the most common ways to use storage vectors, be sure to review the API documentation for all the many useful methods defined on `StorageVec` by the standard library. For now, these can be found in the [source code for `StorageVec`](https://github.com/FuelLabs/sway/blob/master/sway-lib-std/src/storage.sw). For example, in addition to `push`, a `pop` method removes and returns the last element, a `remove` method removes and returns the element at some chosen index within the vector, an `insert` method inserts an element at some chosen index within the vector, etc. -## Nested Storage Vecs +## Nested Storage Vectors It is possible to nest storage vectors as follows: diff --git a/docs/book/src/examples/fizzbuzz.md b/docs/book/src/examples/fizzbuzz.md index 65274ac06cd..3d0bfe98ef7 100644 --- a/docs/book/src/examples/fizzbuzz.md +++ b/docs/book/src/examples/fizzbuzz.md @@ -1,6 +1,6 @@ -# FizzBuzz +# `FizzBuzz` -This example is not the traditional [FizzBuzz](https://en.wikipedia.org/wiki/Fizz_buzz#Programming); instead it is the smart contract version! A script can call the `fizzbuzz` ABI method of this contract with some `u64` value and receive back its fizzbuzzability as an `enum`. +This example is not the traditional [`FizzBuzz`](https://en.wikipedia.org/wiki/Fizz_buzz#Programming); instead it is the smart contract version! A script can call the `fizzbuzz` ABI method of this contract with some `u64` value and receive back the result as an `enum`. The format for custom structs and enums such as `FizzBuzzResult` will be automatically included in the ABI JSON so that off-chain code can handle the encoded form of the returned data. diff --git a/docs/book/src/examples/index.md b/docs/book/src/examples/index.md index 48a4e24e76d..91d82ca6f03 100644 --- a/docs/book/src/examples/index.md +++ b/docs/book/src/examples/index.md @@ -4,5 +4,5 @@ Some basic example contracts to see how Sway and Forc work. - [Counter](./counter.md) - [Subcurrency](./subcurrency.md) -- [FizzBuzz](./fizzbuzz.md) +- [`FizzBuzz`](./fizzbuzz.md) - [Wallet Smart Contract](./wallet_smart_contract.md) diff --git a/docs/book/src/forc/commands/forc_addr2line.md b/docs/book/src/forc/commands/forc_addr2line.md index 9da1be10b3f..cd1835e1c49 100644 --- a/docs/book/src/forc/commands/forc_addr2line.md +++ b/docs/book/src/forc/commands/forc_addr2line.md @@ -1 +1 @@ -# forc addr2line +# `forc addr2line` diff --git a/docs/book/src/forc/commands/forc_build.md b/docs/book/src/forc/commands/forc_build.md index f7285039bd7..950396b5f28 100644 --- a/docs/book/src/forc/commands/forc_build.md +++ b/docs/book/src/forc/commands/forc_build.md @@ -1 +1 @@ -# forc build +# `forc build` diff --git a/docs/book/src/forc/commands/forc_check.md b/docs/book/src/forc/commands/forc_check.md index 49f24c6bc70..88bd1757b61 100644 --- a/docs/book/src/forc/commands/forc_check.md +++ b/docs/book/src/forc/commands/forc_check.md @@ -1 +1 @@ -# forc check +# `forc check` diff --git a/docs/book/src/forc/commands/forc_clean.md b/docs/book/src/forc/commands/forc_clean.md index bbe1d3db337..5ce65cb93c3 100644 --- a/docs/book/src/forc/commands/forc_clean.md +++ b/docs/book/src/forc/commands/forc_clean.md @@ -1 +1 @@ -# forc clean +# `forc clean` diff --git a/docs/book/src/forc/commands/forc_completions.md b/docs/book/src/forc/commands/forc_completions.md index 91ae73c0015..309573d4870 100644 --- a/docs/book/src/forc/commands/forc_completions.md +++ b/docs/book/src/forc/commands/forc_completions.md @@ -1 +1 @@ -# forc completions +# `forc completions` diff --git a/docs/book/src/forc/commands/forc_contract-id.md b/docs/book/src/forc/commands/forc_contract-id.md index f6c47b041e2..81c0f140465 100644 --- a/docs/book/src/forc/commands/forc_contract-id.md +++ b/docs/book/src/forc/commands/forc_contract-id.md @@ -1 +1 @@ -# forc contract-id +# `forc contract-id` diff --git a/docs/book/src/forc/commands/forc_init.md b/docs/book/src/forc/commands/forc_init.md index 9931411557d..0a5ba539d84 100644 --- a/docs/book/src/forc/commands/forc_init.md +++ b/docs/book/src/forc/commands/forc_init.md @@ -1 +1 @@ -# forc init +# `forc init` diff --git a/docs/book/src/forc/commands/forc_new.md b/docs/book/src/forc/commands/forc_new.md index 0e6e939318c..58fd660c119 100644 --- a/docs/book/src/forc/commands/forc_new.md +++ b/docs/book/src/forc/commands/forc_new.md @@ -1 +1 @@ -# forc new +# `forc new` diff --git a/docs/book/src/forc/commands/forc_parse-bytecode.md b/docs/book/src/forc/commands/forc_parse-bytecode.md index 79d718cc9f7..80c67edb461 100644 --- a/docs/book/src/forc/commands/forc_parse-bytecode.md +++ b/docs/book/src/forc/commands/forc_parse-bytecode.md @@ -1 +1 @@ -# forc parse-bytecode +# `forc parse-bytecode` diff --git a/docs/book/src/forc/commands/forc_plugins.md b/docs/book/src/forc/commands/forc_plugins.md index a6cfa94c56e..bc0e7aa6c00 100644 --- a/docs/book/src/forc/commands/forc_plugins.md +++ b/docs/book/src/forc/commands/forc_plugins.md @@ -1 +1 @@ -# forc plugins +# `forc plugins` diff --git a/docs/book/src/forc/commands/forc_predicate-root.md b/docs/book/src/forc/commands/forc_predicate-root.md index 863450ebb50..9ed1d7ca56d 100644 --- a/docs/book/src/forc/commands/forc_predicate-root.md +++ b/docs/book/src/forc/commands/forc_predicate-root.md @@ -1 +1 @@ -# forc predicate-root +# `forc predicate-root` diff --git a/docs/book/src/forc/commands/forc_template.md b/docs/book/src/forc/commands/forc_template.md index a6cd711e7aa..4bc677ff08c 100644 --- a/docs/book/src/forc/commands/forc_template.md +++ b/docs/book/src/forc/commands/forc_template.md @@ -1 +1 @@ -# forc template +# `forc template` diff --git a/docs/book/src/forc/commands/forc_test.md b/docs/book/src/forc/commands/forc_test.md index 85254c0002e..7c4ce2723b7 100644 --- a/docs/book/src/forc/commands/forc_test.md +++ b/docs/book/src/forc/commands/forc_test.md @@ -1 +1 @@ -# forc test +# `forc test` diff --git a/docs/book/src/forc/commands/forc_update.md b/docs/book/src/forc/commands/forc_update.md index 0dcb013a3d0..6805c316eed 100644 --- a/docs/book/src/forc/commands/forc_update.md +++ b/docs/book/src/forc/commands/forc_update.md @@ -1 +1 @@ -# forc update +# `forc update` diff --git a/docs/book/src/forc/dependencies.md b/docs/book/src/forc/dependencies.md index b495b320e2e..12222f0cba8 100644 --- a/docs/book/src/forc/dependencies.md +++ b/docs/book/src/forc/dependencies.md @@ -1,6 +1,6 @@ # Dependencies -Forc has a dependency management system which can pull packages using git and ipfs. This allows users to build and share Forc libraries. +Forc has a dependency management system which can pull packages using git and `ipfs`. This allows users to build and share Forc libraries. ## Adding a dependency @@ -24,7 +24,7 @@ Depending on a local library using `path`: custom_lib = { path = "../custom_lib" } ``` -For `ipfs` sources, `forc` will fetch the specified `cid` using either a local ipfs node or a public gateway. `forc` automatically tries to connect to local `ipfs` node and if it fails, fallbacks to using `https://ipfs.io/`, as a gateway. +For `ipfs` sources, `forc` will fetch the specified `cid` using either a local `ipfs` node or a public gateway. `forc` automatically tries to connect to local `ipfs` node. If it fails, it defaults to using `https://ipfs.io/` as a gateway. The following example adds a dependency with an `ipfs` source. diff --git a/docs/book/src/forc/index.md b/docs/book/src/forc/index.md index b53d75e65a0..2f1c992037e 100644 --- a/docs/book/src/forc/index.md +++ b/docs/book/src/forc/index.md @@ -2,6 +2,6 @@ Forc stands for Fuel Orchestrator. Forc provides a variety of tools and commands for developers working with the Fuel ecosystem, such as scaffolding a new project, formatting, running scripts, deploying contracts, testing contracts, and more. If you're coming from a Rust background, forc is similar to cargo. -If you are new to Forc, see the [Forc Project](../introduction/forc_project.md) introduction section. +If you are new to Forc, see the [Forc Project](https://docs.fuel.network/docs/sway/introduction/forc_project/) introduction section. For a comprehensive overview of the Forc CLI commands, see the [Commands](./commands/index.md) section. diff --git a/docs/book/src/forc/manifest_reference.md b/docs/book/src/forc/manifest_reference.md index be543ccef50..126ee75e5ca 100644 --- a/docs/book/src/forc/manifest_reference.md +++ b/docs/book/src/forc/manifest_reference.md @@ -31,8 +31,8 @@ An example `Forc.toml` is shown below. Under `[project]` the following fields ar Also for the following fields, a default value is provided so omitting them is allowed: -* `entry` - (default : _main.sw_) -* `implicit-std` - (default : _true_) +* `entry` - (default : `main.sw` ) +* `implicit-std` - (default : `true` ) ```toml [project] @@ -69,15 +69,15 @@ The `[build-profile]` tables provide a way to customize compiler settings such a The following fields can be provided for a build-profile: * `print-ast` - Whether to print out the generated AST or not, defaults to false. -* `print-dca-graph` - Whether to print out the computed DCA graph (in GraphViz DOT format), defaults to false. -* `print-dca-graph-url-format` - The URL format to be used in the generated DOT file, an example for vscode would be: "vscode://file/{path}:{line}:{col}" +* `print-dca-graph` - Whether to print out the computed Dead Code Analysis (DCA) graph (in GraphViz DOT format), defaults to false. +* `print-dca-graph-url-format` - The URL format to be used in the generated DOT file, an example for VS Code would be: `vscode://file/{path}:{line}:{col}`. * `print-ir` - Whether to compile to bytecode (false) or to print out the generated IR (true), defaults to false. * `print-finalized-asm` - Whether to compile to bytecode (false) or to print out the generated ASM (true), defaults to false. * `print-intermediate-asm` - Whether to compile to bytecode (false) or to print out the generated ASM (true), defaults to false. * `terse` - Terse mode. Limited warning and error output, defaults to false. * `time_phases` - Whether to output the time elapsed over each part of the compilation process, defaults to false. -* `include_tests` - Whether or not to include test functions in parsing, type-checking and codegen, this is set to true by invocations like `forc test`, defaults to false. -* `json_abi_with_callpaths` - Whether to json abi with callpaths instead of names for struct and enums, defaults to false. +* `include_tests` - Whether or not to include test functions in parsing, type-checking, and code generation. This is set to true by invocations like `forc test`, but defaults to false. +* `json_abi_with_callpaths` - Whether to generate a JSON ABI with `callpaths` instead of names for structs and enums, defaults to false. This option can help prevent conflicting struct or enum definitions by using the full path instead of the name. * `error_on_warnings` - Whether to treat errors as warnings, defaults to false. There are two default `[build-profile]` available with every manifest file. These are `debug` and `release` profiles. If you want to override these profiles, you can provide them explicitly in the manifest file like the following example: @@ -105,7 +105,7 @@ terse = true Since `release` and `debug` implicitly included in every manifest file, you can use them by just passing `--release` or by not passing anything (debug is default). For using a user defined build profile there is `--build-profile ` option available to the relevant commands. (For an example see [forc-build](../forc/commands/forc_build.md)) -Note that providing the corresponding cli options (like `--finalized-asm`) will override the selected build profile. For example if you pass both `--release` and `--finalized-asm`, release build profile is omitted and resulting build profile would have a structure like the following: +Note that providing the corresponding CLI options (like `--finalized-asm`) will override the selected build profile. For example if you pass both `--release` and `--finalized-asm`, release build profile is omitted and resulting build profile would have a structure like the following: ```toml print-ast = false @@ -122,7 +122,7 @@ experimental-private-modules = false ## The `[patch]` section -The [patch] section of `Forc.toml` can be used to override dependencies with other copies. The example provided below patches source with master branch of the same repo. +The [patch] section of `Forc.toml` can be used to override dependencies with other copies. The example provided below patches `https://github.com/fuellabs/sway` with the `test` branch of the same repo. ```toml [project] diff --git a/docs/book/src/forc/plugins/forc_client/forc_deploy.md b/docs/book/src/forc/plugins/forc_client/forc_deploy.md index 5fd00d93425..96a3b57a5a5 100644 --- a/docs/book/src/forc/plugins/forc_client/forc_deploy.md +++ b/docs/book/src/forc/plugins/forc_client/forc_deploy.md @@ -1 +1 @@ -# forc deploy +# `forc deploy` diff --git a/docs/book/src/forc/plugins/forc_client/forc_run.md b/docs/book/src/forc/plugins/forc_client/forc_run.md index 7d6f88c8db5..008a92b9593 100644 --- a/docs/book/src/forc/plugins/forc_client/forc_run.md +++ b/docs/book/src/forc/plugins/forc_client/forc_run.md @@ -1 +1 @@ -# forc run +# `forc run` diff --git a/docs/book/src/forc/plugins/forc_client/forc_submit.md b/docs/book/src/forc/plugins/forc_client/forc_submit.md index ad314de43e7..54e1e5f6c5e 100644 --- a/docs/book/src/forc/plugins/forc_client/forc_submit.md +++ b/docs/book/src/forc/plugins/forc_client/forc_submit.md @@ -1 +1 @@ -# forc submit +# `forc submit` diff --git a/docs/book/src/forc/plugins/forc_client/index.md b/docs/book/src/forc/plugins/forc_client/index.md index 2ecce8826b6..ce9ca27d64e 100644 --- a/docs/book/src/forc/plugins/forc_client/index.md +++ b/docs/book/src/forc/plugins/forc_client/index.md @@ -1,4 +1,4 @@ -# forc-client +# `forc-client` Forc plugin for interacting with a Fuel node. @@ -18,7 +18,7 @@ By default `fuel-core` runs without UTXO validation, this allows you to send inv If you want to run `fuel-core` with UTXO validation, you can pass `--utxo-validation` to `fuel-core run`. -To install `forc-wallet` please refer to `forc-wallet`'s [github repo](https://github.com/FuelLabs/forc-wallet#forc-wallet). +To install `forc-wallet` please refer to `forc-wallet`'s [GitHub repo](https://github.com/FuelLabs/forc-wallet#forc-wallet). 1. Construct the transaction by using either `forc deploy` or `forc run`. To do so simply run `forc deploy` or `forc run` with your desired parameters. For a list of parameters please refer to the [forc-deploy](./forc_deploy.md) or [forc-run](./forc_run.md) section of the book. Once you run either command you will be asked the address of the wallet you are going to be signing with. After the address is given the transaction will be generated and you will be given a transaction ID. At this point CLI will actively wait for you to insert the signature. 2. Take the transaction ID generated in the first step and sign it with `forc wallet sign --account tx-id `. This will generate a signature. @@ -62,7 +62,7 @@ To interact with the latest testnet, use the `--testnet` flag. When this flag is forc-deploy --testnet ``` -It is also possible to pass the exact node url while using `forc-deploy` or `forc-run` which can be done using `--node-url` flag. +It is also possible to pass the exact node URL while using `forc-deploy` or `forc-run` which can be done using `--node-url` flag. ```sh forc-deploy --node-url https://beta-3.fuel.network diff --git a/docs/book/src/forc/plugins/forc_crypto.md b/docs/book/src/forc/plugins/forc_crypto.md index 7c5aa994161..c0789970b64 100644 --- a/docs/book/src/forc/plugins/forc_crypto.md +++ b/docs/book/src/forc/plugins/forc_crypto.md @@ -1 +1 @@ -# forc crypto +# `forc crypto` diff --git a/docs/book/src/forc/plugins/forc_doc.md b/docs/book/src/forc/plugins/forc_doc.md index 2f664873b33..e554a752e6d 100644 --- a/docs/book/src/forc/plugins/forc_doc.md +++ b/docs/book/src/forc/plugins/forc_doc.md @@ -1 +1 @@ -# forc doc +# `forc doc` diff --git a/docs/book/src/forc/plugins/forc_explore.md b/docs/book/src/forc/plugins/forc_explore.md index c8d4ca5ed5b..b86cb623cdf 100644 --- a/docs/book/src/forc/plugins/forc_explore.md +++ b/docs/book/src/forc/plugins/forc_explore.md @@ -1 +1 @@ -# forc explore +# `forc explore` diff --git a/docs/book/src/forc/plugins/forc_fmt.md b/docs/book/src/forc/plugins/forc_fmt.md index f49f6b7877b..667a7c1b635 100644 --- a/docs/book/src/forc/plugins/forc_fmt.md +++ b/docs/book/src/forc/plugins/forc_fmt.md @@ -1 +1 @@ -# forc fmt +# `forc fmt` diff --git a/docs/book/src/forc/plugins/forc_lsp.md b/docs/book/src/forc/plugins/forc_lsp.md index 624d69001f7..b5a93f24f24 100644 --- a/docs/book/src/forc/plugins/forc_lsp.md +++ b/docs/book/src/forc/plugins/forc_lsp.md @@ -1 +1 @@ -# forc lsp +# `forc lsp` diff --git a/docs/book/src/introduction/standard_library.md b/docs/book/src/introduction/standard_library.md index 81a46e3d0d7..1c5c101f93b 100644 --- a/docs/book/src/introduction/standard_library.md +++ b/docs/book/src/introduction/standard_library.md @@ -7,7 +7,7 @@ Similar to Rust, Sway comes with its own standard library. The Sway Standard Library is the foundation of portable Sway software, a set of minimal shared abstractions for the broader Sway ecosystem. It offers core types, like `Result` and `Option`, library-defined operations on language primitives, native asset management, blockchain contextual operations, access control, storage management, and support for types from other VMs, among many other things. -The entire Sway standard library is a Forc project called `std`, and is available directly here: (navigate to the appropriate tagged release if the latest `master` is not compatible). For the latest `std` documentation see: . +The entire Sway standard library is a Forc project called `std`, and is available directly [here](https://github.com/FuelLabs/sway/tree/master/sway-lib-std). Navigate to the appropriate tagged release if the latest `master` is not compatible. You can find the latest `std` documentation [here](https://fuellabs.github.io/sway/master/std/). ## Using the Standard Library diff --git a/docs/book/src/lsp/installation.md b/docs/book/src/lsp/installation.md index da121453361..381bf90a72b 100644 --- a/docs/book/src/lsp/installation.md +++ b/docs/book/src/lsp/installation.md @@ -1,6 +1,6 @@ # Installation -The Sway language server is contained in the [forc-lsp](../forc/plugins/forc_lsp.md) binary, which is installed as part of the [Fuel toolchain](../introduction/fuel_toolchain.md). Once installed, it can be used with a variety of IDEs. It must be installed for any of the IDE plugins to work. +The Sway language server is contained in the [`forc-lsp`](../forc/plugins/forc_lsp.md) binary, which is installed as part of the [Fuel toolchain](../introduction/fuel_toolchain.md). Once installed, it can be used with a variety of IDEs. It must be installed for any of the IDE plugins to work. > **Note**: There is no need to manually run `forc-lsp` (the plugin will automatically start it), however both `forc` and `forc-lsp` must be in your `$PATH`. To check if `forc` is in your `$PATH`, type `forc --help` in your terminal. diff --git a/docs/book/src/reference/compiler_intrinsics.md b/docs/book/src/reference/compiler_intrinsics.md index ebeda03ac06..5ae7bb7fba3 100644 --- a/docs/book/src/reference/compiler_intrinsics.md +++ b/docs/book/src/reference/compiler_intrinsics.md @@ -106,7 +106,7 @@ ___ __gtf(index: u64, tx_field_id: u64) -> T ``` -**Description:** Returns transaction field with ID `tx_field_id` at index `index`, if applicable. This is a wrapper around FuelVM's [`gtf` instruction](https://fuellabs.github.io/fuel-specs/master/vm/instruction_set#gtf-get-transaction-fields). The resuting field is cast to `T`. +**Description:** Returns transaction field with ID `tx_field_id` at index `index`, if applicable. This is a wrapper around FuelVM's [`gtf` instruction](https://fuellabs.github.io/fuel-specs/master/vm/instruction_set#gtf-get-transaction-fields). The resulting field is cast to `T`. **Constraints:** None. diff --git a/docs/book/src/reference/contributing_to_sway.md b/docs/book/src/reference/contributing_to_sway.md index 97edb5f16d6..844a31b0b3d 100644 --- a/docs/book/src/reference/contributing_to_sway.md +++ b/docs/book/src/reference/contributing_to_sway.md @@ -28,7 +28,7 @@ First, open a new terminal and start `fuel-core` with: fuel-core ``` -Then open a second terminal, cd into the `sway` repo and run: +Then open a second terminal, `cd` into the `sway` repo and run: ```sh cargo run --bin test @@ -49,7 +49,7 @@ There are many ways in which you may contribute to the Sway project, some of whi - Reporting bugs - Adding documentation to the Sway book -- Adding new features or bugfixes for which there is already an open issue +- Adding new features or bug fixes for which there is already an open issue - Making feature requests Check out our [Help Wanted](https://github.com/FuelLabs/sway/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22), [Sway Book](https://github.com/FuelLabs/sway/issues?q=is%3Aopen+is%3Aissue+label%3A%22The+Sway+Book%22) or [Good First Issue](https://github.com/FuelLabs/sway/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) issues to find a suitable task. diff --git a/docs/book/src/reference/keywords.md b/docs/book/src/reference/keywords.md index 449b5e82a60..57dd52f4b11 100644 --- a/docs/book/src/reference/keywords.md +++ b/docs/book/src/reference/keywords.md @@ -4,15 +4,15 @@ The following list contains keywords that are reserved for current or future use by the Sway language. As such, they cannot be used as identifiers. Identifiers are names of functions, variables, parameters, modules, constants, attributes, types or -traits, ect. +traits, etc. ## Keywords Currently in Use The following is a list of keywords currently in use, with their functionality described. -- `as` - rename items in `use` statements, eg `use type::a as alias_name` -- [`abi`](../sway-program-types/smart_contracts.md#the-abi-declaration) - defines a smart contract ABI in a syntactcally similar way to traits +- `as` - rename items in `use` statements, e.g., `use type::a as alias_name` +- [`abi`](../sway-program-types/smart_contracts.md#the-abi-declaration) - defines a smart contract ABI in a syntactically similar way to traits - [`break`](../basics/control_flow.md#break-and-continue) - exit a loop immediately - [`const`](../basics/constants.md) - define constant items - [`continue`](../basics/control_flow.md#break-and-continue) - continue to the next loop iteration @@ -23,7 +23,7 @@ functionality described. - [`if`](../basics/control_flow.md#if-expressions) - branch based on the result of a conditional expression - `impl` - implement inherent or trait functionality - `let` - bind a variable -- [`match`](../basics/control_flow.md#match-expressions) - exhaustfully match a value to patterns +- [`match`](../basics/control_flow.md#match-expressions) - exhaustively match a value to patterns - `mod` - define a module - `mut` - denote mutability in references, or pattern bindings - `pub` - denote public visibility of Sway data structures, traits, or modules @@ -78,7 +78,7 @@ Keywords associated with defining the type of Sway program to compile ### Attribute Keywords -Keywords associated with defining the funcitonallity of attributes +Keywords associated with defining the functionality of attributes - [`allow`](./attributes.md#allow) - overrides checks that would otherwise result in errors or warnings - [`doc`](./attributes.md#doc) - specifies documentation diff --git a/docs/book/src/reference/rust_differences.md b/docs/book/src/reference/rust_differences.md index 3943a9258f8..c9505814b20 100644 --- a/docs/book/src/reference/rust_differences.md +++ b/docs/book/src/reference/rust_differences.md @@ -19,7 +19,7 @@ enum Foo { } ``` -In Sway, enums are simplified. Enums variants must all specify exactly one type. This type represents their interior data. This is actually isomorphic to what Rust offers, just with a different syntax. I'll now rewrite the above enum but with Sway syntax: +In Sway, enums are simplified. Enums variants must all specify exactly one type. This type represents their interior data. This is actually isomorphic to what Rust offers, but with a different syntax. You can see the above enum but with Sway syntax below: ```sway // This is equivalent Sway syntax for the above Rust enum. diff --git a/docs/book/src/sway-program-types/index.md b/docs/book/src/sway-program-types/index.md index 18c97dae3a3..fdd076181da 100644 --- a/docs/book/src/sway-program-types/index.md +++ b/docs/book/src/sway-program-types/index.md @@ -7,7 +7,7 @@ A Sway program itself has a type: it is either a _contract_, a _predicate_, a _s Every Sway file _must_ begin with a declaration of what type of program it is. A project can have many libraries within it, but only one contract, script, or predicate. Scripts and predicates require `main` functions to serve as entry points, while contracts instead publish an ABI. This chapter will go into detail about all of these various types of programs and what purposes they serve. -Contracts are used primarily for protocols or systems that operate within a fixed set of rules. A good example would be a staking contract or a decentralized exchange. +Contracts are used primarily for protocols or systems that operate within a fixed set of rules. A good example would be a staking contract or a decentralized exchange (also called a DEX). Scripts are used for complex on-chain interactions that won't persist. An example of this may be using a DEX and Lender to create a leveraged position (borrow, swap, re-collateralize, borrow) which is a complex transaction that would usually take multiple steps. diff --git a/docs/book/src/sway-program-types/libraries.md b/docs/book/src/sway-program-types/libraries.md index 37c30554d05..e2a1c312eba 100644 --- a/docs/book/src/sway-program-types/libraries.md +++ b/docs/book/src/sway-program-types/libraries.md @@ -34,7 +34,7 @@ library; use ::revert::revert; ``` -- The `enum` definition which starts with the keyword `pub` to indicate that this `Option` is publically available _outside_ the `option` library: +- The `enum` definition which starts with the keyword `pub` to indicate that this `Option` is publicly available _outside_ the `option` library: ```sway pub enum Option { @@ -91,7 +91,7 @@ mod vm; // .. Other deps ``` -with other libraries contained in the `src` folder, like the vm library (inside of `src/vm.sw`): +with other libraries contained in the `src` folder, like the `vm` library (inside of `src/vm.sw`): ```sway library; @@ -100,7 +100,7 @@ mod evm; // ... ``` -and it's own sub-library evm located in `src/vm/evm.sw`: +and it's own sub-library `evm` located in `src/vm/evm.sw`: ```sway library; diff --git a/docs/book/src/sway-program-types/scripts.md b/docs/book/src/sway-program-types/scripts.md index 9ee4d421566..4f1c051a940 100644 --- a/docs/book/src/sway-program-types/scripts.md +++ b/docs/book/src/sway-program-types/scripts.md @@ -10,9 +10,9 @@ This example script calls a contract: {{#include ../../../../examples/wallet_contract_caller_script/src/main.sw}} ``` -Scripts, similar to predicates, rely on a `main()` function as an entry point. You can call other functions defined in a script from the `main()` function or call another contract via an [abi cast](./smart_contracts.md#calling-a-smart-contract-from-a-script). +Scripts, similar to predicates, rely on a `main()` function as an entry point. You can call other functions defined in a script from the `main()` function or call another contract via an [ABI cast](./smart_contracts.md#calling-a-smart-contract-from-a-script). -An example use case for a script would be a router that trades funds through multiple DEXes to get the price for the input asset, or a script to re-adjust a Collateralized Debt Position via a flashloan. +An example use case for a script would be a router that trades funds through multiple decentralized exchanges to get the price for the input asset, or a script to re-adjust a Collateralized Debt Position via a flash loan. ## Scripts and the SDKs diff --git a/docs/book/src/sway-program-types/smart_contracts.md b/docs/book/src/sway-program-types/smart_contracts.md index ff5458ba1c1..4ab98187d99 100644 --- a/docs/book/src/sway-program-types/smart_contracts.md +++ b/docs/book/src/sway-program-types/smart_contracts.md @@ -12,9 +12,9 @@ The interface of a smart contract, also just called a contract, must be defined As with any Sway program, the program starts with a declaration of what [program type](./index.md) it is. A contract must also either define or import an [ABI declaration](#the-abi-declaration) and implement it. - + It is considered good practice to define your ABI in a separate library and import it into your contract. This allows callers of your contract to simply import the ABI directly and use it in their scripts to call your contract. - + Let's take a look at an ABI declaration in a library: @@ -85,7 +85,7 @@ Now that we have defined our interface and implemented it for our contract, we n {{#include ../../../../examples/wallet_contract_caller_script/src/main.sw}} ``` -The main new concept is the _abi cast_: `abi(AbiName, contract_address)`. This returns a `ContractCaller` type which can be used to call contracts. The methods of the ABI become the methods available on this contract caller: `send_funds` and `receive_funds`. We then directly call the contract ABI method as if it was just a regular method. You also have the option of specifying the following special parameters inside curly braces right before the main list of parameters: +The main new concept is the `abi cast`: `abi(AbiName, contract_address)`. This returns a `ContractCaller` type which can be used to call contracts. The methods of the ABI become the methods available on this contract caller: `send_funds` and `receive_funds`. We then directly call the contract ABI method as if it was just a regular method. You also have the option of specifying the following special parameters inside curly braces right before the main list of parameters: 1. `gas`: a `u64` that represents the gas being forwarded to the contract when it is called. 2. `coins`: a `u64` that represents how many coins are being forwarded with this call. diff --git a/docs/book/src/testing/testing-with-rust.md b/docs/book/src/testing/testing-with-rust.md index 022d38dea62..ff1befdd8f4 100644 --- a/docs/book/src/testing/testing-with-rust.md +++ b/docs/book/src/testing/testing-with-rust.md @@ -9,11 +9,10 @@ and our Rust code we can add integration testing. To add Rust integration testing to a Forc project we can use [the `sway-test-rs` cargo generate template](https://github.com/FuelLabs/sway/tree/master/templates/sway-test-rs). -This template makes it easy for Sway devs to add the boilerplate required when +This template makes it easier for Sway developers to add the boilerplate required when setting up their Rust integration testing. -Let's add a Rust integration test to [the fresh project we created in the -introduction](../introduction/forc_project.md). +Let's add a Rust integration test to [the fresh project we created in the introduction](../introduction/forc_project.md). ### 1. Enter the project @@ -36,8 +35,8 @@ template. Let's make sure we have the `cargo generate` command installed! cargo install cargo-generate ``` -> _**Note**: You can learn more about cargo generate by visiting [its -> repository](https://github.com/cargo-generate/cargo-generate)._ +> _**Note**: You can learn more about cargo generate by visiting the +> [cargo-generate repository](https://github.com/cargo-generate/cargo-generate)._ ### 3. Generate the test harness @@ -88,8 +87,7 @@ We have two new files! ### 4. Build the forc project Before running the tests, we need to build our contract so that the necessary -ABI, storage and bytecode artifacts are available. We can do so with `forc -build`: +ABI, storage and bytecode artifacts are available. We can do so with `forc build`: ```console $ forc build @@ -175,7 +173,7 @@ following: ```rust,ignore use fuels::{prelude::*, types::ContractId}; -// Load abi from json +// Load ABI from JSON abigen!(TestContract, "out/debug/my-fuel-project-abi.json"); async fn get_contract_instance() -> (TestContract, ContractId) { diff --git a/forc-plugins/forc-debug/docs/walkthrough.md b/forc-plugins/forc-debug/docs/walkthrough.md index 4451a22229a..bb8e7fc25a3 100755 --- a/forc-plugins/forc-debug/docs/walkthrough.md +++ b/forc-plugins/forc-debug/docs/walkthrough.md @@ -1,4 +1,4 @@ -## An example project +# An example project First, we need a project to debug, so create a new project using @@ -28,7 +28,6 @@ fn main() { } ``` - ## Building and bytecode output Now we are ready to build the thing. @@ -74,7 +73,7 @@ We can recognize the `while` loop by the conditional jumps `JNZI`. The condition ## Setting up the debugging We can start up the debug infrastructure. On a new terminal session run `fuel-core run --db-type in-memory --debug`; we need to have that running because it actually executes the program. Now we can fire up the debugger itself: `forc-debug`. Now -if everything is set up correctly, you shoould see the debugger prompt (`>> `). You can use `help` command to list available commands. +if everything is set up correctly, you shoould see the debugger prompt (`>>`). You can use `help` command to list available commands. Now we would like to inspect the program while it's running. To do this, we first need to send the script to the executor, i.e. `fuel-core`. To do so, we need a *transaction specification*, `tx.json`. It looks something like this: @@ -158,7 +157,7 @@ Stopped on breakpoint at address 0 of contract 0x0000000000000000000000000000000 Now we have stopped execution at the breakpoint on entry (address `0`). We can now inspect the initial state of the VM. -``` +```text >> register ggas reg[0x9] = 1000000 # ggas @@ -170,7 +169,7 @@ reg[0x9] = 1000000 # ggas However, that's not too interesting either, so let's just execute until the end, and then reset the vm to remove the breakpoints. -``` +```text >> continue Receipt: Log { id: 0000000000000000000000000000000000000000000000000000000000000000, ra: 120, rb: 0, rc: 0, rd: 0, pc: 10380, is: 10336 } @@ -183,14 +182,14 @@ Terminated Next, we will setup a breakpoint to check the state on each iteration of the `while` loop. For instance, if we'd like to see what numbers get multiplied together, we could set up a breakpoint before the operation. The bytecode has only a single `MUL` instruction: -``` +```text half-word byte op raw notes 14 56 MUL { ra: 18, rb: 18, rc: 17 } 1b 49 24 40 ``` We can set a breakpoint on its address, at halfword-offset `14`. -``` +```text >>> breakpoint 14 >> start_tx tx.json @@ -202,7 +201,7 @@ Stopped on breakpoint at address 56 of contract 0x000000000000000000000000000000 Now we can inspect the inputs tu multiply. Looking at [the specification](https://github.com/FuelLabs/fuel-specs/blob/master/src/fuel-vm/instruction-set.md#mul-multiply) tells us that the instruction `MUL { ra: 18, rb: 18, rc: 17 }` means `reg[18] = reg[18] * reg[17]`. So inpecting the inputs tells us that -``` +```text >> r 18 17 reg[0x12] = 1 # reg18 @@ -211,7 +210,7 @@ reg[0x11] = 1 # reg17 So on the first round the numbers are `1` and `1`, so we can continue to the next iteration: -``` +```text >> c Stopped on breakpoint at address 56 of contract 0x0000000000000000000000000000000000000000000000000000000000000000 @@ -225,7 +224,7 @@ reg[0x11] = 2 # reg17 And the next one: -``` +```text >> c Stopped on breakpoint at address 56 of contract 0x0000000000000000000000000000000000000000000000000000000000000000 @@ -238,7 +237,7 @@ reg[0x11] = 3 # reg17 And fourth one: -``` +```text >> c Stopped on breakpoint at address 56 of contract 0x0000000000000000000000000000000000000000000000000000000000000000 @@ -252,7 +251,7 @@ reg[0x11] = 4 # reg17 And round 5: -``` +```text >> c Stopped on breakpoint at address 56 of contract 0x0000000000000000000000000000000000000000000000000000000000000000 @@ -276,7 +275,7 @@ At this point we can look at the values From this we can clearly see that the left side, register `17` is the `counter` variable, and register `18` is `result`. Now the counter equals the given factorial function argument `5`, and the loop terminates. So when we continue, the program finishes without encountering any more breakpoints: -``` +```text >> c Receipt: Log { id: 0000000000000000000000000000000000000000000000000000000000000000, ra: 120, rb: 0, rc: 0, rd: 0, pc: 10380, is: 10336 }