progress

near · Oct 9, 2024 · 0dd0594 · 0dd0594
1 parent 2ab8871
commit 0dd0594
Show file tree

Hide file tree

Showing 9 changed files with 226 additions and 249 deletions.
diff --git a/docs/3.tutorials/auction/1.1-basic.md b/docs/3.tutorials/auction/1.1-basic.md
diff --git a/docs/3.tutorials/auction/1.2-testing.md b/docs/3.tutorials/auction/1.2-testing.md
@@ -7,9 +7,9 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import {Github, Language} from "@site/src/components/codetabs"
 
-In the previous section we went through the contract's code, analyzing how it worked. Now, we need to test it and make sure it works as expected! For contracts there are two types of testing you can do: unit testing and sandbox testing.
+In the previous section, we went through the contract's code, analyzing how it worked. Now, we need to test it and make sure it works as expected! For contracts, there are two types of testing you can do: unit testing and sandbox testing.
 
-Here, we will focus on the sandbox testing, as it enables to deploy the contract in a realistic environment, allowing us to create multiple accounts and interact with the contract as if it was deployed on the blockchain.
+Here, we will focus on sandbox testing, as it enables one to deploy the contract in a realistic environment, allowing us to create multiple accounts and interact with the contract as if it was deployed on the blockchain.
 
 :::info unit testing
 
@@ -21,21 +21,21 @@ Unit tests are built into the language and are used to test the contract functio
 
 ## Account Creation
 
-The first thing our test does is to create multiple accounts with 10 $NEAR tokens each, and deploy the contract into one of them.
+The first thing our test does is to create multiple accounts with 10 $NEAR tokens each and deploy the contract to one of them.
 
 <Tabs groupId="code-tabs">
     <TabItem value="js" label="🌐 JavaScript">
         <Github fname="main.ava.js" language="javascript"
-                url="https://github.com/near-examples/auctions-tutorial/blob/main/contract-ts/01-basic-auction/sandbox-test/main.ava.js#L12"
-                start="12" end="22" />
+                url="https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/contract-ts/01-basic-auction/sandbox-test/main.ava.js#L12-L23"
+                start="12" end="23" />
         
         To deploy the contract, we pass the path to the compiled WASM contract as an argument to the test in `package.json`. Indeed, when executing `npm run test`, the command will first compile the contract and then run the tests.
 
     </TabItem>
     <TabItem value="rust" label="🦀 Rust">
         <Github fname="test_basics.rs" language="rust"
-                url="https://github.com/near-examples/auctions-tutorial/blob/main/contract-rs/01-basic-auction/tests/test_basics.rs#L10"
-                start="17" end="28" />
+                url="https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/contract-rs/01-basic-auction/tests/test_basics.rs#L17-l29"
+                start="17" end="29" />
 
         Notice that the sandbox compiles the code itself, so we do not need to pre-compile the contract before running the tests.
     </TabItem>
@@ -52,8 +52,8 @@ To initialize, the contract's account calls itself, invoking the `init` function
     <TabItem value="js" label="🌐 JavaScript">
 
         <Github fname="main.ava.js" language="javascript"
-                url="https://github.com/near-examples/auctions-tutorial/blob/main/contract-ts/01-basic-auction/sandbox-test/main.ava.js"
-                start="25" end="27" />
+                url="https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/contract-ts/01-basic-auction/sandbox-test/main.ava.js#L26-L29"
+                start="26" end="29" />
 
 :::warning Time Units
 
@@ -66,8 +66,8 @@ The contract measures time in **nanoseconds**, for which we need to multiply the
     <TabItem value="rust" label="🦀 Rust">
 
         <Github fname="test_basics.rs" language="rust"
-                url="https://github.com/near-examples/auctions-tutorial/blob/main/contract-rs/01-basic-auction/tests/test_basics.rs"
-                start="30" end="37" />
+                url="https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/contract-rs/01-basic-auction/tests/test_basics.rs#L31-L38"
+                start="31" end="38" />
 
 :::warning Time Units
 
@@ -88,25 +88,25 @@ Notice that the time is passed as a `String` to the contract, this is because sm
 
 ## Bidding
 
-Now that the contract is deployed and initialized, we can start biding and checking if the contract behaves as expected.
+Now that the contract is deployed and initialized, we can start bidding and checking if the contract behaves as expected.
 
-We first make `alice` place a bid of 1 NEAR, and check that the contract correctly registers the bid. Then, we make `bob` place a bid of 2 NEAR, and check that the highest bid is updated, and that `alice` gets its NEAR refunded.
+We first make `alice` place a bid of 1 NEAR, and check that the contract correctly registers the bid. Then, we have `bob` place a bid of 2 NEAR, and check that the highest bid is updated, and that `alice` gets her NEAR refunded.
 
 <Tabs groupId="code-tabs">
 
     <TabItem value="js" label="🌐 JavaScript">
 
         <Github fname="main.ava.js" language="javascript"
-                url="https://github.com/near-examples/auctions-tutorial/blob/main/contract-ts/01-basic-auction/sandbox-test/main.ava.js"
-                start="45" end="60" />
+                url="https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/contract-ts/01-basic-auction/sandbox-test/main.ava.js#L46-L61"
+                start="46" end="61" />
 
     </TabItem>
 
     <TabItem value="rust" label="🦀 Rust">
 
         <Github fname="test_basics.rs" language="rust"
-                url="https://github.com/near-examples/auctions-tutorial/blob/main/contract-rs/01-basic-auction/tests/test_basics.rs"
-                start="41" end="73" />
+                url="https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/contract-rs/01-basic-auction/tests/test_basics.rs"
+                start="42" end="74" />
 
     </TabItem>
 
@@ -126,16 +126,16 @@ When testing we should also check that the contract does not allow invalid calls
     <TabItem value="js" label="🌐 JavaScript">
 
         <Github fname="main.ava.js" language="javascript"
-                url="https://github.com/near-examples/auctions-tutorial/blob/main/contract-ts/01-basic-auction/sandbox-test/main.ava.js#L63"
-                start="63" end="63" />
+                url="https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/contract-ts/01-basic-auction/sandbox-test/main.ava.js#L64"
+                start="64" end="64" />
 
     </TabItem>
 
     <TabItem value="rust" label="🦀 Rust">
 
         <Github fname="test_basics.rs" language="rust"
-                url="https://github.com/near-examples/auctions-tutorial/blob/main/contract-rs/01-basic-auction/tests/test_basics.rs"
-                start="76" end="82" />
+                url="https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/contract-rs/01-basic-auction/tests/test_basics.rs"
+                start="77" end="83" />
 
     </TabItem>
 
@@ -144,27 +144,29 @@ When testing we should also check that the contract does not allow invalid calls
 ---
 
 ## Fast Forwarding Time
-The sandbox allows us to fast forward time, which is useful to test the contract when the auction is over. The test advances 200 blocks in order to pass a minute, and thus finishing the auction.
+The sandbox allows us to fast-forward time, which is useful for testing the contract when the auction is over. The test advances 200 blocks in order to pass a minute, and thus allowing the auction to be claimed. 
 
-Any bid made after the auction ends should be rejected.
+After which the auction can now be claimed. Once claimed the test checks that the auctioneer has received the correct amount of $NEAR tokens.
 
 <Tabs groupId="code-tabs">
     <TabItem value="js" label="🌐 JavaScript">
 
         <Github fname="main.ava.js" language="javascript"
-                url="https://github.com/near-examples/auctions-tutorial/blob/main/contract-ts/01-basic-auction/sandbox-test/main.ava.js"
-                start="65" end="69" />
+                url="https://github.com/near-examples/auctions-tutorial/blob/main/contract-ts/01-basic-auction/sandbox-test/main.ava.js#L69-L81"
+                start="69" end="81" />
 
     </TabItem>
     <TabItem value="rust" label="🦀 Rust">
 
         <Github fname="test_basics.rs" language="rust"
-                url="https://github.com/near-examples/auctions-tutorial/blob/main/contract-rs/01-basic-auction/tests/test_basics.rs"
-                start="85" end="95" />
+                url="https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/contract-rs/01-basic-auction/tests/test_basics.rs#L96-L112"
+                start="95" end="112" />
 
     </TabItem>
 </Tabs>
 
+If you review the tests in full you'll see that we also test other invalid calls such as the auctioneer trying to claim the auction before it is over and a user attempting to bid once the auction is over.
+
 ---
 
 ## Executing the tests 
@@ -202,6 +204,6 @@ All tests should pass, and you should see the output of the tests in the console
 
 ## Conclusion 
 
-In this part of the tutorial, we've seen how to use our sandbox testing environment to test the contract. We've tested the contract's initialization, biding, and time advancement.
+In this part of the tutorial, we've seen how to use our sandbox testing environment to test the contract. We've tested the contract's initialization, bidding, and time advancement.
 
-You are now ready to move to the next section, where we will deploy the contract to `testnet` and interact with it through the CLI.
+You are now ready to move to the [next section](./1.3-deploy.md), where we will deploy the contract to `testnet` and interact with it through the CLI.
diff --git a/docs/3.tutorials/auction/1.3-deploy.md b/docs/3.tutorials/auction/1.3-deploy.md
@@ -7,13 +7,13 @@ import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import {Github, Language} from "@site/src/components/codetabs"
 
-In the previous sections we saw how a simple auction smart contract is implemented, and checked its correctness using sandbox testing.
+In the previous sections, we saw how a simple auction smart contract is implemented, and checked its correctness using sandbox testing.
 
-The time has come to release it on the actual blockchain and interact with it! In this section, we will show you how to create a simple testnet account, deploy the contract and interact with it from the CLI.
+The time has come to release it on the actual blockchain and interact with it! In this section, we will show you how to create a simple testnet account, deploy the contract, and interact with it from the CLI.
 
 :::info Networks
 
-NEAR has two main networks for you to use: `testnet` and `mainnet`. The `testnet` network behaves exactly as the main network, but uses test tokens with no real value
+NEAR has two main networks for you to use: `testnet` and `mainnet`. The `testnet` network behaves exactly as the main network but uses test tokens with no real value
 
 :::
 
@@ -59,9 +59,11 @@ To deploy the contract, you need to compile the contract code into WebAssembly (
 
     # initialize the contract, it finishes in 2 minutes
     MINUTE_FROM_NOW=$(date -v+2M +%s000000000)
-    near call <contractId> init '{"end_time": "'$MINUTE_FROM_NOW'"}' --accountId <contractId>
+    near call <contractId> init '{"end_time": "'$MINUTE_FROM_NOW'", "auctioneer": "<auctioneerId>"}' --accountId <contractId>
     ```
 
+    Replace `<auctioneerId>` with the name of another account, this should not be the same as the contract account as we intend on removing its keys.
+
     </TabItem>
 
     <TabItem value="rust" label="🦀 Rust">
@@ -82,8 +84,24 @@ To deploy the contract, you need to compile the contract code into WebAssembly (
 
 </Tabs>
 
+---
+
+## Locking the contract
 
-Now that the contract is deployed and initialized we can send transactions to it using the CLI. 
+As mentioned previously we should lock the account by removing the keys. This allows our users to interact with the contract without having to trust the account owner.
+
+```bash
+near account delete-keys 
+```
+
+Next, specify the contract account and click the right arrow → to delete all the keys. Make sure you select testnet. 
+
+:::caution
+Be extra careful to delete the keys from the correct account as you'll never be able to access the account again!
+:::
+
+
+Now that the contract is deployed, initialized, and locked we can send transactions to it using the CLI. 
 
 :::tip Interactive CLI
 NEAR's CLI is interactive meaning you can type `near` and click through all the possible options without having to remember certain commands
@@ -92,7 +110,7 @@ NEAR's CLI is interactive meaning you can type `near` and click through all the
 ---
 
 ## Interacting with the Contract
-We are now ready to start bidding by calling the `bid` function on the contract. We recommend you to create **two new accounts** to simulate different bidders.
+We are now ready to start bidding by calling the `bid` function on the contract. We recommend that you create **two new accounts** to simulate different bidders.
 
 ```bash
 # call the contract to bid 
@@ -118,8 +136,6 @@ Do not use testnet as your **only way** to test contracts. Always test your cont
 
 :::tip Frontend
 
-Generally you will use the CLI only to deploy and initialize the contract. After, all interactions will be made from a frontend
-
-We will cover this topic in the future, after we have finished adding more features to the auction contract
+Generally, you will use the CLI only to deploy and initialize the contract. Afterward, all interactions will be made from a frontend. This is why in the [next section](./2.1-frontend.md) we'll move on to creating a frontend to interact with the contract.
 
 :::
diff --git a/docs/3.tutorials/auction/2.1-frontend.md b/docs/3.tutorials/auction/2.1-frontend.md
@@ -1,4 +1,31 @@
 ---
 id: creating-a-frontend
 title: Creating a Frontend
----
+---
+
+Now that we have successfully created a contract, it's time to build a frontend to provide a user-friendly interface for interacting with it. Up until now, we have been using the CLI to send transactions and view the contract's state. However, frontends offer a more intuitive way for end users to interact with the contract. They can display all the relevant information in one place, allow users to make calls with a simple button click, and only require a wallet as a prerequisite.
+
+## Frontend structure
+
+Navigate to the auction frontend.
+
+```bash
+cd frotends/01-frontend
+```
+
+Here we have a simple Next.js frontend that we'll walk through to understand the basics of creating a frontend for a NEAR smart contract.
+
+For starters, let's take a look at how the code in the frontend is structured by doing a quick overview of the important files.
+
+| File                             | Description                                                                     |
+|----------------------------------|---------------------------------------------------------------------------------|
+| **_app.js**           | Responsible for rending the page, initiates the wallet object and adds it to global context  |
+| **index.js**          | The main page where the projects components are loaded into and contains most of the logic for the application like viewing the state of the contract and logic for placing a bid |
+| **near.js**           | Contains the wallet class that has methods to interact with the wallet and blockchain |
+| **context.js**        | Holds the global context - the wallet object and the signed in account ID - that can be accessed anywhere |
+| **config.js**         | Specifies the account ID of the auction contract |
+| **Navigation.jsx**    | A component that contains a button to sign users in and out of wallets |
+| **Bid.jsx**           | A component allowing a user to make a bid |
+| **LastBid.jsx**       | A component that displays the highest bid and when the highest bid will next refresh |
+| **AuctionItem.jsx**   | A component that displays information about the NFT being auctioned  |
+| **Timer.jsx**         | A component that shows how long till the auction is over, or, if over, displays a button to claim the auction and then states the auction is over