From 0dd059451214ed202cb71e695db2037b2d266585 Mon Sep 17 00:00:00 2001 From: PiVortex Date: Wed, 9 Oct 2024 15:42:12 +0700 Subject: [PATCH] progress --- docs/3.tutorials/auction/1.1-basic.md | 110 +++++++++++++----- docs/3.tutorials/auction/1.2-testing.md | 60 +++++----- docs/3.tutorials/auction/1.3-deploy.md | 34 ++++-- docs/3.tutorials/auction/2.1-frontend.md | 29 ++++- docs/3.tutorials/auction/3.1-nft.md | 22 ++-- docs/3.tutorials/auction/3.2-ft.md | 61 +++++----- docs/3.tutorials/auction/3.3-new-frontend.md | 36 +++--- docs/3.tutorials/auction/old-indexing.md | 8 +- docs/3.tutorials/auction/old-locking.md | 115 ------------------- 9 files changed, 226 insertions(+), 249 deletions(-) delete mode 100644 docs/3.tutorials/auction/old-locking.md diff --git a/docs/3.tutorials/auction/1.1-basic.md b/docs/3.tutorials/auction/1.1-basic.md index 6896591972f..d6314143dd0 100644 --- a/docs/3.tutorials/auction/1.1-basic.md +++ b/docs/3.tutorials/auction/1.1-basic.md @@ -7,11 +7,11 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import {Github, Language} from "@site/src/components/codetabs" -In this section, we will analyze a simple auction contract, which allows users to place bids and track the highest bidder. After, we will cover how to test the contract, as well as how to deploy it on `testnet`. +In this section, we will analyze a simple auction contract, which allows users to place bids, track the highest bidder and claim tokens at the end of the auction. After, we will cover how to test the contract, as well as how to deploy it on `testnet`. :::info Documentation -During this tutorial we will be relying on the [Smart Contract Documentation](../../2.build/2.smart-contracts/quickstart.md) and its different sections +During this tutorial, we will be relying on the [Smart Contract Documentation](../../2.build/2.smart-contracts/quickstart.md) and its different sections ::: @@ -25,7 +25,7 @@ Make sure to read the [Prerequisites](./0-intro.md) section and install the nece ## Cloning the contract -To get started we'll clone the [tutorial's repository](https://github.com/near-examples/auctions-tutorial) from Github. The repository contains the same smart contracts written in JavaScript (`./contract-ts`) and Rust (`./contract-rs`). +To get started we'll clone the [tutorial's repository](https://github.com/near-examples/auctions-tutorial) from GitHub. The repository contains the same smart contracts written in JavaScript (`./contract-ts`) and Rust (`./contract-rs`). Navigate to the folder of the language you prefer, and then to the `01-basic-auction` folder. @@ -56,7 +56,7 @@ Navigate to the folder of the language you prefer, and then to the `01-basic-auc :::info Frontend -The repository also contains a frontend application that interacts with the contract. You can find it in the `frontend` folder. We will cover the frontend in a future section +The repository also contains a frontend application that interacts with the contract. You can find it in the `frontends` folder. We will cover the frontend in a future section ::: @@ -71,11 +71,11 @@ The contract allows users to place bids using $NEAR tokens and keeps track of th + url="https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/contract-ts/01-basic-auction/src/contract.ts#L4-L14" + start="4" end="14" /> #### Decorator - A first thing to notice is that the main class of the contract is marked using the `@NearBindgen` decorator, which allows also to further specify that the contract **must be initialized** before being used. + The first thing to notice is that the main class of the contract is marked using the `@NearBindgen` decorator, which allows also to further specify that the contract **must be initialized** before being used. #### Storage (aka State) Another important information revealed by the code is that a contract can store different types of data, in this case: @@ -84,17 +84,19 @@ The contract allows users to place bids using $NEAR tokens and keeps track of th - `bid`: a `BigInt` representing an amount of $NEAR tokens in `yoctonear` (`1Ⓝ = 10^24 yⓃ`) - `bidder`: an `AccountId` that represents which account placed the bid - `auction_end_time` a `BigInt` representing a `unix timestamp` in **nanoseconds** + - `auctioneer` an `AccountId` that states who can withdraw the funds at the end of the auction + - `claimed` a `boolean` that tracks if the auctioneer has claimed the funds + url="https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/contract-rs/01-basic-auction/src/lib.rs#L5-L19" + start="5" end="19" /> #### Macros - A first thing to notice is the use of the `#[near(contract_state)]` macro to denote the main structure, and derive the `PanicOnDefault` to specify that the contract **must be initialized** before being used. + A first thing to notice is the use of the `#[near(contract_state)]` macro to denote the main structure and derive the `PanicOnDefault` to specify that the contract **must be initialized** before being used. We also use the `#[near(serializers = [json, borsh])]` macro to enable both `borsh` and `JSON` (de)serialization of the `Bid` structure. As a rule of thumb: use the `json` serializer for structs that will be used as input / output of functions, and `borsh` for those that will be saved to state. @@ -105,6 +107,8 @@ The contract allows users to place bids using $NEAR tokens and keeps track of th - `bid`: a `NearToken` which simplifies handling $NEAR token amounts - `bidder`: the `AccountId` that placed the bid - `auction_end_time` is a `U64` representing a `unix timestamp` in **nanoseconds** + - `auctioneer` an `AccountId` that states who can withdraw the funds at the end of the auction + - `claimed` a `boolean` that tracks if the auctioneer has claimed the funds @@ -113,7 +117,7 @@ The contract allows users to place bids using $NEAR tokens and keeps track of th :::tip Learn More -You can read more about the contract's structure and type of data it can store in the following documentation pages: +You can read more about the contract's structure and the type of data it can store in the following documentation pages: - [Basic Contract's Anatomy](../../2.build/2.smart-contracts/anatomy/anatomy.md) - [Contract's State](../../2.build/2.smart-contracts/anatomy/storage.md) - [Data Types](../../2.build/2.smart-contracts/anatomy/types.md) @@ -131,8 +135,8 @@ Lets now take a look at the initialization function, which we need to call to de + url="https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/contract-ts/01-basic-auction/src/contract.ts#L16-#L21" + start="16" end="21" /> #### Decorator We denote the initialization function using the `@initialize({ privateFunction: true })` decorator. The `privateFunction:true` denotes that the function can only be called by the account on which the contract is deployed. @@ -142,11 +146,11 @@ Lets now take a look at the initialization function, which we need to call to de + url="https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/contract-rs/01-basic-auction/src/lib.rs#L23-L35" + start="23" end="35" /> #### Macros - We denote the initialization function using the `#[init]` macro. Notice that the initialization function needs to return a instance of `Self`, i.e. the contract's structure. + We denote the initialization function using the `#[init]` macro. Notice that the initialization function needs to return an instance of `Self`, i.e. the contract's structure. Meanwhile, the `#[private]` denotes that the function can only be called by the account on which the contract is deployed. @@ -158,7 +162,13 @@ Lets now take a look at the initialization function, which we need to call to de The end time is represented using a `unix timestamp` in **nano seconds**, and needs to be given as a `String` when calling the initialization function. This is because smart contracts cannot receive numbers larger than `52 bits` and `unix timestamps` are represented in `64 bits`. #### Initial Bid -Notice that we initialize the contract with a `1 yoctonear` bid, made from the `current account id`. This mean that, after the contract is initialized, the first bid will be placed by the contract at 10^-24 NEAR. +Notice that we initialize the contract with a `1 yoctonear` bid, made from the `current account id`. This means that, after the contract is initialized, the first bid will be placed by the contract at 10^-24 NEAR. + +#### Claimed +The `claimed` field is initialized as `false`, as the auctioneer has not claimed the funds yet. + +#### Auctioneer +The auctioneer is set by the deployer on initialization and is the account that will be able to claim the funds at the end of the auction. :::tip Learn More @@ -170,15 +180,15 @@ You can read more about the contract's interface in our [contract functions docu ## Read-only Functions -The contract implements two functions to give access to its stored data, i.e. the time at which the auction ends, and the highest bid so far. +The contract implements four functions to give access to its stored data, i.e. the highest bid so far (the amount and by whom), the time at which the auction ends, the auctioneer, and whether the auction has been claimed. + url="https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/contract-ts/01-basic-auction/src/contract.ts#L53-L71" + start="53" end="71" /> Functions that do not change the contract's state (i.e. that only read from it) are called `view` functions, and are decorated using the `@view` decorator. @@ -187,10 +197,10 @@ The contract implements two functions to give access to its stored data, i.e. th + url="https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/contract-rs/01-basic-auction/src/lib.rs#L78-L92" + start="78" end="92" /> - Functions that do not change the contract's state (i.e. that only read from it) are called `view` functions, and take a non-mutable reference to `self` (`&self`). + Functions that do not change the contract's state (i.e. that only read from it) are called `view` functions and take a non-mutable reference to `self` (`&self`). @@ -218,16 +228,16 @@ The function is quite simple: it verifies if the auction is still active and com + url="https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/contract-ts/01-basic-auction/src/contract.ts#L23-L43" + start="23" end="43" /> + url="https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/contract-rs/01-basic-auction/src/lib.rs#L37-L63" + start="37" end="63" /> @@ -239,18 +249,18 @@ The first thing to notice is that the function changes the state, and thus is ma Second, the function is marked as `payable`, this is because by default **functions do not accept $NEAR tokens**! If a user attaches tokens while calling a function that is not marked as `payable`, the transaction will fail. #### The Environment -Notice that the function can access information about the environment in which it is running, such as who called the function (`predecessor account`), how much tokens they attached as deposit (`attached deposit`), and the approximate `unix timestamp` at which the function is executing (`block timestamp`). +Notice that the function can access information about the environment in which it is running, such as who called the function (`predecessor account`), how many tokens they attached as deposit (`attached deposit`), and the approximate `unix timestamp` at which the function is executing (`block timestamp`). #### Token Transfer The function finishes by creating a `Promise` to transfer tokens to the previous bidder. This token amount will be deducted immediately and transferred in the next block after the current function has finished executing. -Note that on the first bid the contract will send 1 yoctonear to itself, this is fine as we can safely assume that the contract will have the lowest denomination of $NEAR available to send to itself. +Note that on the first bid, the contract will send 1 yoctonear to itself, this is fine as we can safely assume that the contract will have the lowest denomination of $NEAR available to send to itself.
Handling Funds -When a user attaches tokens to a call, the tokens are deposited on the contract's account before the function is executed. However, if the function raises an error during its execution, the tokens are immediately refunded to the user. +When a user attaches tokens to a call, the tokens are deposited to the contract's account before the function is executed. However, if the function raises an error during its execution, the tokens are immediately refunded to the user.
@@ -265,6 +275,44 @@ You can read more about the environment variables, payable functions and which a --- +## Claim function + +You'll notice that the contract has a final function called `claim`, this allows the auctioneer to claim the funds from the contract at the end of the auction. Since, on NEAR, a smart contract account and user account are the same, contracts can still have keys when they are deployed, thus a user could just claim the funds from the contract via a wallet. However, this presents a security issue since by having a key the key holder can take the funds from the contract at any point, maliciously change the contract's state or just delete the contract as a whole. By implementing a `claim` function we can later lock the contract by removing all access keys and have the auctioneer claim the funds via preset conditions via code. + + + + + + + + + + + + + + + + + +This function is quite simple it does four things: +1) Checks that the auction has ended (the current timestamp is past the auction end time). +2) Checks that the auction has not yet been claimed. +3) Sets the auction as now claimed. +4) And if these conditions hold true it transfers $NEAR equal to the highest bid to the auctioneer. + +:::tip Learn More + +You can read more about locking contracts in this section of the documentation: [locked accounts](../../1.concepts/protocol/access-keys.md#locked-accounts) + +::: + +--- + ## Conclusion -In this part of the tutorial, we've seen how a smart contract stores data, mutates the stored data, and views the data. In the next part, we will cover how to test the contract, so we can ensure it works as expected before deploying it to `testnet`. +In this part of the tutorial, we've seen how a smart contract stores data, mutates the stored data, and views the data. In the [next part](./1.2-testing.md), we will cover how to test the contract, so we can ensure it works as expected before deploying it to `testnet`. \ No newline at end of file diff --git a/docs/3.tutorials/auction/1.2-testing.md b/docs/3.tutorials/auction/1.2-testing.md index b21413fa87c..8ad2758ab2a 100644 --- 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. + 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. + 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. @@ -52,8 +52,8 @@ To initialize, the contract's account calls itself, invoking the `init` function + 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 + 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. + 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" /> + url="https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/contract-rs/01-basic-auction/tests/test_basics.rs" + start="42" end="74" /> @@ -126,16 +126,16 @@ When testing we should also check that the contract does not allow invalid calls + 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" /> + url="https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/contract-rs/01-basic-auction/tests/test_basics.rs" + start="77" end="83" /> @@ -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. + 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" /> + 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" /> +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. \ No newline at end of file diff --git a/docs/3.tutorials/auction/1.3-deploy.md b/docs/3.tutorials/auction/1.3-deploy.md index 955c9a3ff33..8bac918debb 100644 --- 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 init '{"end_time": "'$MINUTE_FROM_NOW'"}' --accountId + near call init '{"end_time": "'$MINUTE_FROM_NOW'", "auctioneer": ""}' --accountId ``` + Replace `` with the name of another account, this should not be the same as the contract account as we intend on removing its keys. + @@ -82,8 +84,24 @@ To deploy the contract, you need to compile the contract code into WebAssembly ( +--- + +## 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. ::: \ No newline at end of file diff --git a/docs/3.tutorials/auction/2.1-frontend.md b/docs/3.tutorials/auction/2.1-frontend.md index ccc47794fa5..116beb5524e 100644 --- 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 ---- \ No newline at end of file +--- + +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 diff --git a/docs/3.tutorials/auction/3.1-nft.md b/docs/3.tutorials/auction/3.1-nft.md index 92da4356cce..be5fdd0001e 100644 --- a/docs/3.tutorials/auction/3.1-nft.md +++ b/docs/3.tutorials/auction/3.1-nft.md @@ -21,7 +21,7 @@ When we create an auction we need to list the NFT. To specify which NFT is being @@ -29,7 +29,7 @@ When we create an auction we need to list the NFT. To specify which NFT is being Note that `token_id` is of type `TokenId` which is a String type alias that the NFT standards use for future-proofing. @@ -49,7 +49,7 @@ When the method `claim` is called the NFT needs to be transferred to the highest In near-sdk-js we cannot transfer the NFT and send the $NEAR independently so we will chain the promises. @@ -64,10 +64,10 @@ When the method `claim` is called the NFT needs to be transferred to the highest @@ -98,7 +98,7 @@ To deploy the NFT contract, this time we're going to use `dev deploy` which crea @@ -106,7 +106,7 @@ To deploy the NFT contract, this time we're going to use `dev deploy` which crea @@ -124,7 +124,7 @@ To start a proper auction the auction contract should own an NFT. To do this the @@ -132,7 +132,7 @@ To start a proper auction the auction contract should own an NFT. To do this the @@ -150,7 +150,7 @@ After `claim` is called, the test should verify that the auction winner now owns @@ -158,7 +158,7 @@ After `claim` is called, the test should verify that the auction winner now owns diff --git a/docs/3.tutorials/auction/3.2-ft.md b/docs/3.tutorials/auction/3.2-ft.md index f23cd3c984e..02fbf5bccaf 100644 --- a/docs/3.tutorials/auction/3.2-ft.md +++ b/docs/3.tutorials/auction/3.2-ft.md @@ -1,7 +1,6 @@ --- id: bidding-with-fts title: Bidding with FTs -sidebar_label: Bidding with FTs --- import Tabs from '@theme/Tabs'; @@ -21,7 +20,7 @@ We want to only accept bids in one type of fungible token; accepting many differ @@ -29,7 +28,7 @@ We want to only accept bids in one type of fungible token; accepting many differ @@ -51,7 +50,7 @@ The `ft_on_transfer` method always has the same interface; the FT contract will @@ -59,7 +58,7 @@ The `ft_on_transfer` method always has the same interface; the FT contract will @@ -74,7 +73,7 @@ We need to confirm that the user is attaching fungible tokens when calling the m @@ -82,7 +81,7 @@ We need to confirm that the user is attaching fungible tokens when calling the m @@ -96,7 +95,7 @@ The bidder's account ID is now given by the argument `sender_id`. @@ -104,7 +103,7 @@ The bidder's account ID is now given by the argument `sender_id`. @@ -119,10 +118,10 @@ When we want to return the funds to the previous bidder we now make a cross-cont @@ -134,17 +133,17 @@ When we want to return the funds to the previous bidder we now make a cross-cont We then return 0 because the method uses all the FTs in the call. @@ -172,7 +171,7 @@ When the auction is complete we need to send the fungible tokens to the auctione In JavaScript, since we need to return each cross-contract call we chain the NFT and FT transfer. @@ -182,7 +181,7 @@ When the auction is complete we need to send the fungible tokens to the auctione @@ -202,7 +201,7 @@ When the contract is deployed it is initialized with `new_default_meta` which se @@ -210,7 +209,7 @@ When the contract is deployed it is initialized with `new_default_meta` which se @@ -230,7 +229,7 @@ In our tests, since we are creating a new fungible token and new accounts we wil @@ -238,7 +237,7 @@ In our tests, since we are creating a new fungible token and new accounts we wil @@ -256,7 +255,7 @@ Then we will transfer the bidders FTs so they can use them to bid. A simple tran @@ -265,10 +264,10 @@ Then we will transfer the bidders FTs so they can use them to bid. A simple tran @@ -287,7 +286,7 @@ As stated previously, to bid on the auction the bidder now calls `ft_transfer_ca @@ -296,10 +295,10 @@ As stated previously, to bid on the auction the bidder now calls `ft_transfer_ca @@ -318,7 +317,7 @@ Previously, to check a user's $NEAR balance, we pulled the details from their ac @@ -327,10 +326,10 @@ Previously, to check a user's $NEAR balance, we pulled the details from their ac @@ -351,7 +350,7 @@ Previous to this, Bob made a bid of 60,000 and Alice was returned her bid bringi @@ -359,7 +358,7 @@ Previous to this, Bob made a bid of 60,000 and Alice was returned her bid bringi diff --git a/docs/3.tutorials/auction/3.3-new-frontend.md b/docs/3.tutorials/auction/3.3-new-frontend.md index a9a3da63933..b61901d0e4c 100644 --- a/docs/3.tutorials/auction/3.3-new-frontend.md +++ b/docs/3.tutorials/auction/3.3-new-frontend.md @@ -65,7 +65,7 @@ We have a config file that specifies the contract name of the auction that the f @@ -75,16 +75,16 @@ We have a config file that specifies the contract name of the auction that the f To be able to fully interact with the contract - send bids or claim the auction - you'll need a `wallet` to sign transactions. Wallets securely store your private keys and allow you to sign transactions without exposing your private key to the frontend. The wallet selector allows users to choose between a selection of wallets. -We abstract the wallet selector in our `near.js` file by exposing methods to complete various tasks. Feel free to [explore the file](https://github.com/near-examples/auctions-tutorial/blob/main/frontend/src/wallets/near.js) to understand how the wallet selector is implemented. +We abstract the wallet selector in our `near.js` file by exposing methods to complete various tasks. Feel free to [explore the file](https://github.com/near-examples/auctions-tutorial/blob/reorg-auction/frontend/src/wallets/near.js) to understand how the wallet selector is implemented. We implement a sign-in and sign-out button in the navigation component to call the respective methods in the `near.js` file. When a wallet is signed in a function call access key is created. This allows the frontend to sign nonpayable transactions on behalf of the user, to the specified contract, without requiring the user to sign each transaction in the wallet; this allows for a better user experience. However, in this example, the main transaction we'll send is to make bids, which is payable so the wallet will prompt the user to sign each transaction. @@ -92,10 +92,10 @@ We add the wallet and the account ID that is signed in to the global context mak @@ -107,10 +107,10 @@ To get all the information about the auction we call the method `get_auction_inf @@ -120,10 +120,10 @@ We then pass the information about the highest bidder into the `LastBid` compone @@ -131,7 +131,7 @@ When we display the latest bid, instead of just showing the bid amount directly @@ -143,7 +143,7 @@ We want to know the highest bid at all times, someone else could have placed a h --- @@ -154,7 +154,7 @@ The contract stores the end time of the auction in the number of nanoseconds sin --- @@ -165,7 +165,7 @@ We want to show what NFT is being auctioned. To do this we will call `nft_token` @@ -175,7 +175,7 @@ In the `AuctionItem` component we display the NFT image, name, and description. @@ -189,10 +189,10 @@ To make a bid we call the `ft_transfer_call` method on the FT contract which sub @@ -206,7 +206,7 @@ Once the auction is over (the current time is greater than the end time) the auc diff --git a/docs/3.tutorials/auction/old-indexing.md b/docs/3.tutorials/auction/old-indexing.md index 2e529f37cca..a5d51db2fce 100644 --- a/docs/3.tutorials/auction/old-indexing.md +++ b/docs/3.tutorials/auction/old-indexing.md @@ -24,7 +24,7 @@ NextJS allows us to easily create server-side functions with API routes. We need @@ -44,7 +44,7 @@ The API call itself does not filter out invalid transactions. A transaction may @@ -56,7 +56,7 @@ In our main page, we'll define a function to call the API route we just created. @@ -72,4 +72,4 @@ You may like to explore NEAR Blocks APIs further to see what other data you can In this short part of the tutorial, we've added the ability to display the previous 5 valid bids made to the auction contract. In doing this we learned how to interact with the NEAR Blocks APIs to retrieve historical data from the blockchain and how to make server-side calls in NextJS to not expose our API key. Now we have a pretty good frontend that displays all the information we need about the auction contract. -In the [final part](./7-factory.md) of this tutorial series you'll learn how to deploy a factory contract - a contract that deploys other contracts - to make it easier for anyone to launch a new auction. +In the [final part](./7-factory.md) of this tutorial series you'll learn how to deploy a factory contract - a contract that deploys other contracts - to make it easier for anyone to launch a new auction. \ No newline at end of file diff --git a/docs/3.tutorials/auction/old-locking.md b/docs/3.tutorials/auction/old-locking.md deleted file mode 100644 index 979f15bd8b6..00000000000 --- a/docs/3.tutorials/auction/old-locking.md +++ /dev/null @@ -1,115 +0,0 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import {Github} from "@site/src/components/codetabs" - -In the basic contract, the auctioneer would claim the tokens from the final bid of the contract via logging into the contract accounts wallet using a key. It is a security issue for there to exist a key for a smart contract since the key holder can take the funds from the contract at any point, maliciously change the contract or just delete the contract as a whole. To stop exploitation we will [lock](../../1.concepts/protocol/access-keys.md#locked-accounts) the contract by removing all access keys and implementing a new method to `claim` the tokens. - ---- - -## Adding an auctioneer - -When we introduce the `claim` method we want to make sure that the individual or entity that set up the auction receives the $NEAR tokens. To do this we now change the `init` method to initialize the contract with an `auctioneer`. - - - - - - - - - - - - - - - - - -Let's also introduce a boolean field named `claimed` to track whether the tokens have been claimed by the auctioneer yet. - ---- - -## Adding the claim method - -The `claim` method should only be callable when the auction is over, can only be executed once and should transfer the tokens to the auctioneer. We'll implement this as so: - - - - - - - - - - - - - - - - - ---- - -## Updating the tests - -If we update our contract then we should update our tests accordingly. For example, the tests will now need to add `auctioneer` to the arguments of `init`. - -We will now also test the `claim` method. The test will check that the `auctioneer` account has received the correct amount of $NEAR tokens. - - - - - - - - - - - - - - - - - -Note that the test doesn't check that the auctioneer has exactly 12 $NEAR since the auctioneer uses tokens through gas fees when calling `claim`. - ---- - -## Deploying and locking - -Go ahead and test, build, and deploy your new contract, as in part 1. Remember to add the `auctioneer` argument when initializing. - -Now that we have the `claim` method, we can deploy the contract without keys. Later, we will introduce a factory contract that deploys auctions to a locked account, but for now, we can manually remove the keys using the CLI to lock the account. - -``` -near account delete-keys -``` - -Next specify the contract account and click the right arrow → to delete all the keys. Make sure to 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! -::: - ---- - -## Conclusion - -In this part of the tutorial, you learned how to lock a contract by creating a new method to claim tokens, specify an account on initialization that will claim the tokens, and how to delete the contract account's keys with the CLI. - -In the [next part](./3-nft.md), we'll add a prize to the auction by introducing a new primitive; spoiler, the primitive is an NFT. We'll look at how to use non-fungible token standards to send NFTs and interact with multiple interacting contracts in sandbox testing. \ No newline at end of file