chore(docs): revision election dApp tutorial

Author: jessevanmuijden

.changeset/cyan-countries-joke.md

@@ -0,0 +1,5 @@
+---
+'@kadena/docs': patch
+---
+
+revision election dApp tutorial

packages/apps/docs/src/pages/build/guides/election-dapp-tutorial/01-getting-started.md

@@ -52,8 +52,8 @@ workspace. Kadena has developed a "PACT" extension for this editor. It features
 syntax highlighting, error reporting and code coverage reporting to improve your
 smart contract development workflow. The extension does require you to have `pact`
 and `pact-lsp` installed on your computer. You can configure the path to each
-executable in the plugin settings. If you are using another editor, you may also
-profit from just `pact-lsp` which provides the syntax highlighting. The links
+executable in the extension's settings. If you are using another editor, you may also
+profit from just `pact-lsp` which provides syntax highlighting for Pact code. The links
 to the installation instructions are listed on the
 [main page](/build/guides/election-dapp-tutorial) of this tutorial.
 
@@ -67,7 +67,7 @@ Let's explore these folders one by one.
 
 This is where the `.pact` files for your smart contracts go, as well as `.repl`
 files that will be used to test your smart contracts in isolation. You will
-notice a `./root` folder that already contains some `.pact` files. They contain
+notice a `./root` folder that already contains some `.pact` files. These files contain
 Pact modules that the smart contracts you will create in later chapters depend
 on. They only need to be there for local testing with `.repl` files. You do not
 need to deploy them to the blockchain alongside your own `.pact` files, because
@@ -81,11 +81,11 @@ For the front-end of the election website, a basic React app was created. You
 could use any other framework to create the front-end, because the connection
 with the blockchain is established through the
 [Kadena Client](https://www.npmjs.com/package/@kadena/client) npm package
-that can be imported in any JavaScript project. At the end of the line, this
+that can be imported in any JavaScript project. In the end, this
 package simply makes HTTP API requests to the blockchain.
-Inside of the React components, data is manipulated by calling service methods
-the services get a specific implementation of repositories injected, depending
-on the projects configuration. Initially, the project is configured to use
+Inside of the React components, data is manipulated by calling service methods.
+The services get a specific implementation of repositories injected, depending
+on the project's configuration. Initially, the project is configured to use
 the in-memory implementation of repositories. The in-memory repositories
 simply perform all data operations on JavaScript arrays and objects defined
 in the same file. This implementation was created for you to have a simple
@@ -99,9 +99,9 @@ repository implementation will be provided later in this chapter.
 
 In this folder you will find several JavaScript snippets that use the Kadena
 Client library to perform actions against the blockchain that are not directly
-related to the functionality of the election dApp per se, like deploy and
+related to the functionality of the election dApp per se, like deploying and
 upgrading smart contracts, creating and funding accounts, and more. You will
-learn more about these snippets in the following chapters.
+learn more about these snippets in the upcoming chapters.
 
 ## Run the front-end
 
@@ -115,7 +115,7 @@ npm install
 npm run start
 ```
 
-Open a browser window and visit `http://localhost:3000`. You will see the working
+Open a browser window and visit `http://localhost:5173`. You will see the working
 front-end of the election website. Because all data is manipulated in memory,
 you can freely click around and submit data. The state of the front-end will be
 reset as soon as you refresh the page. The website shows a list of candidates
@@ -132,5 +132,5 @@ At this point you should have a working development environment and an understan
 of the project structure. You have installed and run the front-end of the election
 website, and you have an understanding of its features. In the next chapter of this
 tutorial you will run a blockchain on your own computer using Docker. After that,
-you will be ready to start developing smart contracts and creating the Devnet
+you will be ready to start developing smart contracts and work on the Devnet
 implementations of the front-end repositories.

packages/apps/docs/src/pages/build/guides/election-dapp-tutorial/02-running-devnet.md

@@ -87,7 +87,7 @@ Chainweaver will be executed against Devnet.
 
 In Chainweaver, expand the left navigation bar and click contracts. Select
 `Module Explorer` at the top of the right panel to reveal a list of contracts
-that are already deployed on your Devnet. Next to the search box on top of
+that are already deployed on your Devnet. Next to the search box above
 that list, change `All chains` to any particular chain to narrow down the
 list to the unique contracts that are deployed to Devnet by default:
 
@@ -119,7 +119,7 @@ documentation of the following functions:
 
  * transfer
  * transfer-create
- * get-balance
+ * details
  * create-account
 
 These are some of the first smart contract functions that you will interact
@@ -214,7 +214,7 @@ your local Devnet:
 ```
 
 Notice that the list is exactly the same as the list displayed in the module
-explorer of Chainweaver. Both these tools can be used interchangably to interact
+explorer of Chainweaver. Both these tools can be used interchangeably to interact
 with the Kadena blockchain. They both support the execution of simple read
 operations as well as the execution of complex multi-step transactions, as will
 become clear when you will be using both approaches to test the smart contracts
@@ -229,7 +229,7 @@ are deployed on the Kadena networks by default and how you can explore them usin
 either Chainweaver or the Kadena JavaScript client. In the next chapter, you will
 create an account on Devnet. This account will govern several aspects of the smart
 contracts you will create in this tutorial: the namespace, keyset definition and
-module. The account will also get exclusive permission to call certain functions in the
+modules. The account will also get exclusive permission to call certain functions in the
 election smart contract, such as adding candidates. After setting up this account,
 namespace and keyset definitions, all will be in place to deploy the smart contract
 that will become the new back-end of the election website.

packages/apps/docs/src/pages/build/guides/election-dapp-tutorial/03-admin-account.md

@@ -52,7 +52,7 @@ via the top section of the
 navigation bar on the left side of the window. When you click `+ Generate Key` on the
 top right, a new public key will be added to the list of public keys. Click `Add k: Account`
 on the right of this new public key and your k:account will be added to the accounts
-that you are watching via Chainweaver. Expand the row of the account you justed added
+that you are watching via Chainweaver. Expand the row of the account you just added
 by clicking the arrow on the left side of the account name. You will see that no KDA balance
 exists for this account on any of the chains and the information about the owner and keyset
 of the account is missing. This indicates that your account does not yet exist on Devnet.
@@ -95,16 +95,16 @@ npm run generate-types:coin:devnet
 
 Now you are ready to run the npm script that executes the snippet `./transferCreate.ts`. Open up this
 file in your editor to learn how the Kadena JavaScript client is used to call the `transfer-create`
-function of the `coin` module to create and fund your admin account. After importing the depencies
+function of the `coin` module to create and fund your admin account. After importing the dependencies
 and creating the client with the right (Devnet) configuration, the
 main function is called with information about the sender, the receiver and the amount. The amount
-of KDA to transfer to the receiver is hardcoded to 20. The receiver will be you admin account name,
+of KDA to transfer to the receiver is hardcoded to 20. The receiver will be your admin account name,
 which you will specify as an argument when running the script. The sender, `sender00`, is one
 of the pre-installed Devnet test accounts that holds some KDA on all chains. The public and private
 key for this account were copied over from GitHub. Inside the main function, the amount to transfer
-is converted to a PactDecimal, which boils down to this format: `{ decimal: '20.0' }`. Then, the
+is converted to a `PactDecimal`, which boils down to this format: `{ decimal: '20.0' }`. Then, the
 transaction is created. Creating this transaction is slightly more complex than the `list-modules`
-you learned about in the previous chapter.
+transaction you learned about in the previous chapter.
 
 Instead of passing raw Pact code as a string to `Pact.builder.execution()`, the `coin['transferCreate']`
 function is called on `Pact.modules` to generate the correct Pact code for you, based on the
@@ -126,22 +126,26 @@ admin account. Replace `k:account` with your admin account.
 npm run transfer-create:devnet -- k:account
 ```
 
-After a few seconds, `Write succeeded` should be printed in the terminal window. Verify that your account was created by checking the account details using the Kadena JavaScript client.
+After a few seconds, `Write succeeded` should be printed in the terminal window. Verify that
+your account was created by checking the account details using the Kadena JavaScript client.
 Replace `k:account` with your admin account.
 
 ```bash
 npm run coin-details:devnet -- k:account
 ```
 
 This time, the script should print out the account name, the KDA balance and the receiver guard
-of the account. Chainweaver will tell the same story. Navigate to `Accounts` in the top section of the left menu bar. Expand your admin account to view the information on all chains. You will
+of the account. Chainweaver will tell the same story. Navigate to `Accounts` in the top section
+of the left menu bar. Expand your admin account to view the information on all chains. You will
 see that on chain 1 you are the owner, one keyset is defined and the balance is 20 KDA.
 
 ## Next steps
 
 In this chapter you learned how to create a key for a Kadena account using Chainweaver and to
 create and fund this account using the Kadena JavaScript client. You verified the creation
-of the account in `Accounts` view of Chainweaver and by calling the `details` function of the `coin` module on Devnet using the Kadena JavaScript client. The admin user will use its KDA
-to pay gas fees charged for deploying keysets, deploying smart contracts and sending transactions to nominate candidates for the election. In the following chapter you will learn
+of the account in `Accounts` view of Chainweaver and by calling the `details` function of the
+`coin` module on Devnet using the Kadena JavaScript client. The admin user will use its KDA
+to pay gas fees charged for deploying keysets, deploying smart contract modules and sending
+transactions to nominate candidates for the election. In the following chapter you will learn
 how to create a namespace in which you will later define an admin keyset and deploy your
 smart contracts.

packages/apps/docs/src/pages/build/guides/election-dapp-tutorial/04-namespaces.md

@@ -10,12 +10,13 @@ tags: [pact, smart contract, typescript, tutorial]
 
 # Chapter 04: Namespaces
 
-Toward the end of this tutorial you will deploy your election smart contract
-to Testnet. Everyone else who is following along with this tutorial will do the same.
-If everyone would deploy Pact modules with the same name, however, it would become impossible
-to distinguish your Pact module from all the others. Therefore, it is not allowed to
+After you have completed this entire tutorial, you may want to deploy your election
+smart contract to Testnet. Many others like you would perhaps like to do the same.
+If everyone would deploy Pact modules with the same name to the same network, however,
+it would become impossible to distinguish your Pact module from all the others. Therefore,
+it is not allowed to
 deploy a Pact module with a name that already exists on the chain you are deploying to
-and your deployment transaction will fail with an error if you would try. Fortunately,
+and your deployment transaction will fail with an error if you try. Fortunately,
 Kadena offers a solution to this problem by introducing namespaces. You can create
 your own unique namespace on the blockchain and you get to decide who can update the
 namespace or use it to define keysets and modules inside it. As long as you choose a
@@ -195,7 +196,7 @@ bottom of the `namespace.yml` file and run it.
 ### Redefine the namespace as the new admin
 
 To further prove that the namespace was successfully updated in the previous steps, it should
-be tested that the `user-keyset` will now be able to redefine the contract. You will need
+be tested that the `user-keyset` will now be able to redefine the namespace. You will need
 to load the signature of the `user-keyset` into the context of the Pact REPL and write a
 transaction to redefine the namespace. The transaction will be the same as the previous one,
 but this time it is wrapped inside an `expect` function instead of `expect-failure`.
@@ -221,21 +222,23 @@ Add the following transaction at the bottom of the `namespace.yml` file and run
 If all is well, `Load successful` will be displayed at the bottom of the output. In conclusion,
 you defined a namespace `election` and specified a keyset that is allowed to govern the
 namespace and a keyset that is allowed to use the namespace. You wrote an automated test
-script to verify that indeed only the governance keyset can redefine the namespace. The
-namespace was redefined in a way that handed over governance permissions to another keyset.
-Great work.
+script to verify that indeed only the governance keyset can redefine the namespace. Finally, the
+namespace was redefined in such a way that governance permissions were handed over to another
+keyset. Great work!
 
 ## Exercise: Define a principal namespace
 
 Choosing an arbitrary namespace name like `election-your-name` still provides no guarantee
 that, by coincidence, this namespace is not already defined by someone else. To ensure
 that your namespace will be unique, you can create a principal namespace. The
-`create-principal-namespace` from the `ns` module creates a principle namespace name
+`create-principal-namespace` from the `ns` module creates a principal namespace name
 that is a hash of a keyset, prefixed with `n_`. In this example, you will use an `admin-keyset`
 that contains the public key of the `sender00` account, because `ns.create-principal-namespace`
 only accepts valid public keys inside the keyset. The `ns` module is readily available
 on Mainnet, Testnet and Devnet, but to use it in the Pact REPL it needs to be loaded
-from the local filesystem. The output of `ns.create-principal-namespace` called with the
+from the local filesystem. To that end, the `ns` module should be loaded from the local
+`./pact/root` folder of the project for testing purposes.The output of
+`ns.create-principal-namespace` called with the
 `admin-keyset` can be stored in a variable (`ns-name`) and passed to the `define-namespace`
 as the first argument. In the `./pact` folder create `principal-namespace.repl` file and paste the following
 code into it.
@@ -282,7 +285,7 @@ and holds KDA on chain 1. Otherwise, repeat the steps in the previous chapter to
 and fund your admin account. Chainweaver needs to remain open, because you will use
 it to sign the transaction for defining the namespace. Switch to your editor and open
 the file `./snippets/principal-namespace.ts`. The `pactCommand` variable contains the
-crucial bit of Pact code for defining a principle namespace, which you just tested in
+crucial bit of Pact code for defining a principal namespace, which you just tested in
 the Pact REPL. Also, recognize how the keyset data is added in a similar fashion as in
 the `.repl` file, with slightly different syntax. For the transaction on Devnet, a signer
 is also added, which was not required in the Pact REPL. After the transaction is defined,
@@ -311,7 +314,7 @@ If everything went well, you will see something similar to the following output.
 }
 ```
 
-Congratulations! You have defined a principle namespace on your local Devnet that
+Congratulations! You have defined a principal namespace on your local Devnet that
 can be governed and used by your admin account.
 
 ## Next steps