Merge branch 'master' into near-api-section

blog/2024-10-24.md

@@ -0,0 +1,29 @@
+---
+title: New Tutorial - Master Applications on NEAR
+authors: [pivortex]
+slug: 2024-10-24-new-tutorial
+tags: [updates, tutorial, getting-started]
+hide_table_of_contents: true
+---
+
+You might have noticed that a [new tutorial](https://docs.near.org/tutorials/auction/introduction) has been added to the docs! This multi-part series is all about learning to build full applications on NEAR; you will see how to build an on-chain auction from start to finish, including the smart contract, deploying it on-chain, and creating a frontend to interact with it.
+
+<!-- truncate -->
+
+Along the way you will learn several key concepts and how to use many key primitives along the way: 
+- Creating a simple smart contract
+- Writing tests for a contract
+- Deploying a contract to `testnet`
+- Locking a contract
+- Creating a frontend to interact with the contract
+- Using an indexing API to view historical bids
+- Making cross-contract calls
+- Using Non-Fungible Tokens
+- Using Fungible Tokens
+- Modifying a factory contract to deploy your own contracts
+
+This tutorial is a great for beginners to follow all the way through, but each section can also be used as a reference guide for different concepts. If you have any feedback or any questions regarding the tutorial please feel free to reach out in the [Developer Telegram Channel](https://t.me/neardev). 
+
+**Start the tutorial [here](https://docs.near.org/tutorials/auction/introduction)**
+
+Let's keep building! 🚀

blog/authors.yml

@@ -39,3 +39,12 @@ ewiner:
   title: CTO & Managing Director, Pagoda
   url: https://github.com/ewiner
   image_url: https://github.com/ewiner.png
+
+pivortex:
+  name: Owen Hassall
+  title: DevRel
+  url: https://github.com/PiVortex
+  image_url: https://github.com/PiVortex.png
+  socials:
+    x: ThePiVortex
+    github: PiVortex

docs/1.concepts/3.advanced/indexers.md

@@ -88,4 +88,4 @@ We hope this article gives you an understanding of the Indexer concept. Also, we
 ## What's next?
 We encourage you to learn more about the [Lake Indexer project](/build/data-infrastructure/lake-framework/near-lake). Please, proceed to [Tutorials](/build/data-infrastructure/lake-framework/near-lake-state-changes-indexer) section to learn how to build an indexer on practice.
 
-Alternatively, there are a few other third-party indexers that are tightly integrated with the NEAR ecosystem. You can review all of your data sourcing options (including The Graph, Pagoda, Pikespeak, and SubQuery) under [data tools](/concepts/data-flow/data-storage#data-tools).
+Alternatively, there are a few other third-party indexers that are tightly integrated with the NEAR ecosystem. You can review all of your data sourcing options (including The Graph, Pagoda, Pikespeak, and SubQuery) under [indexing tools](/tools/indexing).

docs/1.concepts/basics/epoch.md

@@ -10,7 +10,7 @@ import TabItem from '@theme/TabItem';
 An **epoch** is a unit of time when validators of the network remain constant. It is measured in blocks:
 
 - Both `testnet` and `mainnet` have an epoch duration of 43,200 blocks. Ideally epochs last about 12 hours, since blocks are created every second (in reality, they take slightly longer to be created).
-- You can view this setting by querying the **[`protocol_config`](/api/rpc/setup#protocol-config)** RPC endpoint and searching for `epoch_length`.
+- You can view this setting by querying the **[`protocol_config`](/api/rpc/protocol#protocol-config)** RPC endpoint and searching for `epoch_length`.
 
 **Note:** Nodes garbage collect blocks after 5 epochs (~2.5 days) unless they are [archival nodes](https://near-nodes.io/intro/node-types#archival-node).
 

docs/1.concepts/basics/networks.md

@@ -34,7 +34,6 @@ NEAR Protocol operates on several networks each operating with their own indepen
 
 More on local development [here](https://near-nodes.io/validator/running-a-node)
 
-`near-cli` [network selection](/tools/near-cli#network-selection) variable is `local`
 
 ---
 

docs/1.concepts/basics/validators.md

@@ -23,40 +23,40 @@ In the NEAR networks, an attempt to manipulate the chain would mean taking contr
 ### Validator's Economy
 In exchange for servicing the network, validators are rewarded with a target number of NEAR every epoch. The target value is computed in such a way that, on an annualized basis, it will be 4.5% of the total supply.
 
-All transaction fees (minus the part which is allocated as the rebate for contracts) which are collected within each epoch are burned by the system. The inflationary reward is paid out to validators at the same rate regardless of the number of fees collected or burned. 
+All transaction fees (minus the part which is allocated as the rebate for contracts) which are collected within each epoch are burned by the system. The inflationary reward is paid out to validators at the same rate regardless of the number of fees collected or burned.
 
 
 ## Intro to Validators
 
 [Validators](https://pages.near.org/papers/the-official-near-white-paper/#economics) are responsible for producing blocks and the security of the network.
 
-Since Validators validate all shards, high requirements are set for running them (an 8-Core CPU with 16GB of RAM and 1 TB SSD of storage). The cost of running a block-producing validator node is estimated to be $330 per month for hosting. Please see our [hardware and cost estimates page](https://near-nodes.io/validator/hardware) for more info.
+Since Validators validate all shards, high requirements are set for running them (an 8-Core CPU with 16GB of RAM and 1 TB SSD of storage). The cost of running a block-producing validator node is estimated to be $330 per month for hosting. Please see our [hardware and cost estimates page](https://near-nodes.io/validator/hardware-validator) for more info.
 
 The current active Validators are available on the Explorer. The minimum seat price to become a block-producing validator is based on the 300th proposal. (If more than 300 proposals are submitted, the threshold will simply be the stake of the 300th proposal, provided that it’s larger than the minimum threshold of 25,500 $NEAR.) The current seat price to become a block-producing validator is updated live on the Explorer. Any validator nodes with stakes higher than the seat price can join the active set of Validators.
 
 <blockquote className="lesson">
 <strong>Is there a plan to support GPU compute if certain validator nodes can offer that or is it just CPU?</strong><br /><br />
-  
+
 We don't need GPU support as we are a POS chain and we require very little compute power.
 
 You can read more about our consensus strategy on our <a href="https://github.com/near/wiki/blob/master/Archive/validators/about.md" target="_blank" rel="noopener noreferrer">Validator Quickstart</a> and <a href="https://github.com/near/wiki/blob/master/Archive/validators/faq.md" target="_blank" rel="noopener noreferrer">Staking FA</a>.
 </blockquote>
 
 ## Chunk-Only Validators
 
-The Chunk-Only Producer is a more accessible role with lower hardware and token requirements. This new role will allow the network's validator number to grow, creating more opportunities to earn rewards and secure the NEAR Ecosystem. 
+The Chunk-Only Producer is a more accessible role with lower hardware and token requirements. This new role will allow the network's validator number to grow, creating more opportunities to earn rewards and secure the NEAR Ecosystem.
 
 [Chunk-Only Producers](https://pages.near.org/papers/the-official-near-white-paper/#economics) are solely responsible for [producing chunks](https://pages.near.org/papers/nightshade/#nightshade) (parts of the block from a shard, see [Nightshade](https://near.org/papers/nightshade/) for more detail) in one shard (a partition on the network). Because Chunk-Only Producers only need to validate one shard, they can run the validator node on a 8-Core CPU, with 16GB of RAM, and 500 GB SSD of storage.
 
 Like Validators, Chunk-Only Producers will receive, at minimum, 4.5% annual rewards. If less than 100% of the tokens on the network is staked, Chunk-Only Producers stand to earn even more annual rewards. For more details about the Validator’s economics, please check out [NEAR’s Economics Explained](https://near.org/blog/near-protocol-economics/).
 
-## Dedicated Validator Documentation Site 
+## Dedicated Validator Documentation Site
 
 If you'd like to further explore Validators and Nodes in general, you can visit the [Dedicated Validator Documentation Site](https://near-nodes.io/).
 
 <blockquote className="lesson">
 <strong>If a developer writes a vulnerable or malicious dApp, is a validator implicitly taking on risk?</strong><br /><br />
-  
+
 No. We have handled the potential damages to the network on the protocol level. For example, we have a lot of limiters that constrain how much data you can pass into a function call or how much compute you can do in one function call, etc.
 
 That said, smart contract developers will need to be responsible for their own dApps, as there is no stage gate or approval process. All vulnerability can only damage the smart contract itself. Luckily, updating smart contracts is very smooth on NEAR, so vulnerabilities can be updated/patched to an account in ways that cannot be done on other blockchains.

docs/1.concepts/protocol/gas.md

@@ -12,12 +12,12 @@ On every transaction the NEAR network charges a tiny fee known as **gas**. This
 3. **Incentivize developers** by giving contracts 30% of the gas they burn while executing
 4. Implement a **wall time** by capping transactions to `300Tgas` (~`300ms` of compute time)
 
-Gas in NEAR is computed on [**gas units**](#gas-units--gas-price) and charged using $NEAR tokens based on the network's [**gas price**](#gas-units--gas-price).
+Gas in NEAR is computed on [**gas units**](/concepts/protocol/gas#gas-units) and charged using $NEAR tokens based on the network's [**gas price**](/concepts/protocol/gas#gas-price).
 
 :::tip Did you know?
 In NEAR, attaching extra gas to a transaction does **not** make it faster. Actions cost a fixed amount of gas, and any extra gas attached is simply sent back to the user
 :::
- 
+
 ---
 
 ## Understanding Gas Fees
@@ -130,7 +130,7 @@ When you make a request to transfer funds, NEAR immediately deducts the appropri
   }
 ```
 
-You can query this value by using the [`protocol_config`](/api/rpc/setup#protocol-config) RPC endpoint and search for `action_receipt_creation_config`.
+You can query this value by using the [`protocol_config`](/api/rpc/protocol#protocol-config) RPC endpoint and search for `action_receipt_creation_config`.
 
 The appropriate amount for creating this receipt is also immediately deducted from your account.
 

docs/1.concepts/storage/storage-staking.md

@@ -26,7 +26,7 @@ On each incoming transaction that adds data.
 Let's walk through an example:
 
 1. You launch [a guest book app](https://examples.near.org/guest-book), deploying your app's smart contract to the account `example.near`
-2. Visitors to your app can add messages to the guest book. This means your users will, [by default](/concepts/protocol/gas#what-about-prepaid-gas), pay a small gas fee to send their message to your contract.
+2. Visitors to your app can add messages to the guest book. This means your users will, [by default](/concepts/protocol/gas#understanding-gas-fees), pay a small gas fee to send their message to your contract.
 3. When such a call comes in, NEAR will check that `example.near` has a large enough balance that it can stake an amount to cover the new storage needs. If it does not, the transaction will fail.
 
 ## The "million cheap data additions" attack
@@ -45,7 +45,7 @@ Note that a call to your smart contract to remove data has an associated gas fee
 
 Storage staking is priced in an amount set by the network, which is set to **1E19 yoctoNEAR per byte**, or **100kb per NEAR token (Ⓝ)**. [^1] [^2]
 
-NEAR's JSON RPC API provides [a way to query this initial setting](/api/rpc/setup#genesis-config) as well as a [a way to query the live config / recent blocks](/api/rpc/setup#protocol-config).
+NEAR's JSON RPC API provides [a way to query this initial setting](/api/rpc/protocol#genesis-config) as well as a [a way to query the live config / recent blocks](/api/rpc/protocol#protocol-config).
 
 ## Example cost breakdown
 

docs/1.concepts/web3/near.md

@@ -39,7 +39,7 @@ As we already discussed, users should pay computational costs for each transacti
 
 
 ![image](/docs/assets/web3/web3-7.png)
-    
+
 
 
 
@@ -69,7 +69,7 @@ The general flow for transactions signing looks like this:
 
 
 ![image](/docs/assets/web3/web3-9.png)
-    
+
 
 
 Each time we want to post a transaction, the client redirects the user to a wallet, where the transaction is approved and wallet returns a signed transaction back to the client (via redirect). This is a quite secure way of signing, since the private key is not exposed to the client, but constant redirects might quickly get annoying for users, especially if we just want to call smart contract functions that incur only small gas fees. That’s why NEAR introduced [two types of access keys](../../1.concepts/protocol/access-keys.md) - full keys and functional call keys. Full access keys, as the name implies, can be used to sign any types of transactions. Functional call keys, on the other hand, aim to solve this UX problem. They are tied to a specific contract, and have a budget for gas fees. Such a key can’t be used to sign transactions that transfers NEAR tokens (payable transactions), and can only be used to cover gas fees, that’s why it’s not so security-critical and can be stored on the client. Because of this, we can create a simplified signing flow for non-payable transactions. First of all, a login flow to obtain a Functional Call key is used.
@@ -97,7 +97,7 @@ Throughout this section, we’ve discussed how to call a smart contract from a c
 
 
 ![image](/docs/assets/web3/web3-12.png)
-    
+
 
 
 
@@ -115,7 +115,7 @@ Looks simple enough, but there are few gotchas:
 
 
 ![image](/docs/assets/web3/web3-14.png)
-    
+
 
 
 A few notes on failure modes - since smart contracts run on a decentralized environment, which means they are executed on multiple machines and there is no single point of failure, they won’t fail because of environment issues (e.g. because a machine suddenly lost power or network connectivity). The only possible failures come from the code itself, so they can be predicted and proper failover code added.
@@ -135,7 +135,7 @@ To support more complex data retrieval scenarios, smart contract data should be
 
 
 ![image](/docs/assets/web3/web3-15.png)
-    
+
 
 
 In order to simplify creation of indexers, [NEAR Indexer Framework](/concepts/advanced/near-indexer-framework) has been created. However, even with a framework available, extracting data from a transaction may not be an easy task, since each smart contract has its unique structure and data storage model. To simplify this process, smart contracts can write structured information about outcome into the logs  (e.g. in the JSON format). Each smart contract can use its own format for such logs, but the general format has been standardized as [Events](https://nomicon.io/Standards/EventsFormat).
@@ -182,7 +182,7 @@ Below this, we can inspect transaction actions (recall, that transactions may ha
 ![image](/docs/assets/web3/web3-18.png)
 
 
-At the end, transaction execution details, including token transfers, logs, cross-contract calls and gas refunds are provided. One thing that we haven’t covered yet is shown here - [receipts](../protocol/transactions.md#receipt-receipt). For most practical purposes they are just a transaction implementation detail. They are quite useful in a transaction explorer to understand how a transaction was executed, but aren’t really relevant outside of it.
+At the end, transaction execution details, including token transfers, logs, cross-contract calls and gas refunds are provided. One thing that we haven’t covered yet is shown here - [receipts](/concepts/protocol/transaction-execution#receipts--finality). For most practical purposes they are just a transaction implementation detail. They are quite useful in a transaction explorer to understand how a transaction was executed, but aren’t really relevant outside of it.
 
 ![image](/docs/assets/web3/web3-19.png)
 
@@ -192,8 +192,8 @@ At the end, transaction execution details, including token transfers, logs, cros
 
 During the development, and sometimes even in production, updates to a contract’s code (or even data) are needed. That’s why different contract upgrades mechanisms have been created.
 
-While developing the contract, we recommend just creating a new account each time you need to deploy a contract (the [create-account](../../4.tools/cli.md#near-create-account) command in NEAR CLI exists for this). With such an approach, you will start with a clean state each time.
- 
+While developing the contract, we recommend just creating a new account each time you need to deploy a contract (the [create-account](../../4.tools/cli.md#create) command in NEAR CLI exists for this). With such an approach, you will start with a clean state each time.
+
 However, once we move to a more stable environment, like testing or production, more sophisticated methods are needed. Redeployment of code is quite simple: we just issue another `DeployContract` transaction, and NEAR will handle the rest. The biggest challenge is to migrate contract state - [several approaches are possible](../../2.build/2.smart-contracts/release/upgrade.md#migrating-the-state), but all of them involve some kind of migration code.
 
 But we can take our upgrade strategy one step further. In the previous strategies, developers are fully in control of code upgrades. This is fine for many applications, but it requires some level of trust between users and developers, since malicious changes could be made at any moment and without the user’s consent (as it [sometimes happens](https://www.bleepingcomputer.com/news/security/dev-corrupts-npm-libs-colors-and-faker-breaking-thousands-of-apps/) in npm world). To solve this, a contract update process itself can also be decentralized - this is called [Programmatic Updates](../../2.build/2.smart-contracts/release/upgrade.md#programmatic-update). The exact strategy may vary, but the basic idea is that the contract update code is implemented in a smart contract itself, and a Full Access key to the contract account is removed from a blockchain (via DeleteKey transaction). In this way, an update strategy is transparent to everyone and cannot be changed by developers at will.