Skip to content

Commit

Permalink
Reorg auction docs (#2250)
Browse files Browse the repository at this point in the history 
* start auction reorg

* progress

* progress for wednesday

* more progress

* complete auction

* fix links

* fix code snippets

* fix: snippets

* fix: move to main branch

---------

Co-authored-by: PiVortex <[email protected]>
Co-authored-by: gagdiez <[email protected]>
  • Loading branch information
@PiVortex @gagdiez
3 people authored Oct 11, 2024
1 parent a29efbf commit f619a4b
Show file tree
Hide file tree
Showing 14 changed files with 592 additions and 523 deletions.
37 changes: 19 additions & 18 deletions docs/3.tutorials/auction/0-intro.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,17 +13,16 @@ We'll start from a simple auction contract and slowly build on top of it to crea

By the time you finish this tutorial, you will have learned several concepts and how to use many key privitives along the way:

- [Creating a simple smart contract](./1.1-basic.md)
- [Creating a simple smart contract](./1.1-basic.md#the-contracts-state)
- [Writing tests for a contract](./1.2-testing.md)
- [Deploying a contract to testnet](./1.3-deploy.md)

<!-- - [Locking a contract](./2-locking.md)
- [Making cross-contract calls](./3-nft.md#transferring-the-nft-to-the-winner)
- [Using Non-Fungible Tokens](./3-nft.md)
- [Using Fungible Tokens](./4-ft.md)
- [Creating a frontend to interact with the contract](./5-frontend.md)
- [Using an indexing API to keep track of the contract's activity](./6-indexing.md)
- [Modifying a contract factory to deploy your own contracts](./7-factory.md) -->
- [Locking a contract](./1.3-deploy.md#locking-the-contract)
- [Creating a frontend to interact with the contract](./2.1-frontend.md)
- [Using an indexing API to view historical bids](./2.2-indexing.md)
- [Making cross-contract calls](./3.1-nft.md#transferring-the-nft-to-the-winner)
- [Using Non-Fungible Tokens](./3.1-nft.md)
- [Using Fungible Tokens](./3.2-ft.md)
- [Modifying a factory contract to deploy your own contracts](./4-factory.md)

---

Expand Down Expand Up @@ -80,21 +79,23 @@ We will be using [NEAR CLI](../../4.tools/cli.md) to interact with the blockchai

This series will touch on different level of the NEAR tech stack. Each section will be independent of the previous one, so feel free to jump into the section that interests you the most.

#### 1. Smart Contract
#### 1. Smart contracts 101
1. [The Auction Contract](./1.1-basic.md): We cover a simple auction smart contract
2. [Testing the Contract](./1.2-testing.md): Learn how to test your contract in a realistic environment
3. [Deploying the Contract](./1.3-deploy.md): Deploy your contract to the NEAR blockchain
4. Updating and Locking a Contract (soon): Discover what it means to lock a contract
5. Giving an NFT to the Winner (soon) : Give the highest bidder an NFT to signal their win
6. Integrating Fungible Tokens (soon) : Allow people to use fungible tokens to bid (e.g. stable coins)

#### 2. Frontend
#### 2. Frontends 101

1. [Creating the frontend](./2.1-frontend.md): Lets learn how to connect a frontend with your smart contract
2. [indexing historical data](./2.2-indexing.md): Use APIs to keep track of historical bids

1. Creating the frontend (soon): Lets learn how to connect a frontend with your smart contract
2. Easily query on-chain data (soon): Use open APIs to keep track of the users and their bidding price
#### 3. Using Primitives
1. [Giving an NFT to the Winner](./3.1-nft.md): Give the highest bidder an NFT to signal their win
2. [Integrating Fungible Tokens](./3.2-ft.md): Allow people to use fungible tokens to bid (e.g. stable coins)
3. [Updating the frontend](./3.3-new-frontend.md): Update the frontend to use the extended functionality of the contract.

#### 3. Factory
1. Creating a factory (soon): Allow users to easily deploy and initialize their own auction contracts
#### 3. Auction Factory
1. [Creating a factory](./4-factory.md): Allow users to easily deploy and initialize their own auction contracts

---

Expand Down
110 changes: 79 additions & 31 deletions docs/3.tutorials/auction/1.1-basic.md
View file

Large diffs are not rendered by default.

58 changes: 30 additions & 28 deletions docs/3.tutorials/auction/1.2-testing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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/main/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/main/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>
Expand All @@ -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/main/contract-ts/01-basic-auction/sandbox-test/main.ava.js#L26-L29"
start="26" end="29" />

:::warning Time Units

Expand All @@ -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/main/contract-rs/01-basic-auction/tests/test_basics.rs#L31-L38"
start="31" end="38" />

:::warning Time Units

Expand All @@ -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/main/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" />
start="42" end="74" />

</TabItem>

Expand All @@ -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/main/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/main/contract-rs/01-basic-auction/tests/test_basics.rs#L77-L83"
start="77" end="83" />

</TabItem>

Expand All @@ -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/main/contract-rs/01-basic-auction/tests/test_basics.rs#L95-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
Expand Down Expand Up @@ -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.
36 changes: 26 additions & 10 deletions docs/3.tutorials/auction/1.3-deploy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

:::

Expand Down Expand Up @@ -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">
Expand All @@ -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
Expand All @@ -92,11 +110,11 @@ 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
near call <contractId> bid --accountId <bidderId> --amount 1
near call <contractId> bid --accountId <bidderId> --amount 1

# get the highest bid
near view <contractId> get_highest_bid
Expand All @@ -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.

:::
Loading

0 comments on commit f619a4b

Please sign in to comment.