Merge branch 'master' into omni-rs

blog/2025-01-01.md

@@ -0,0 +1,110 @@
+---
+title: A Year in Docs
+authors: [gagdiez]
+slug: a-year-in-docs
+tags: [updates]
+---
+
+*2024 was a great year for NEAR Docs! Let's take a look at what we achieved together*
+
+<p><img src="/docs/blog/2024-review/2024-blog.jpg" /></p>
+
+<!-- truncate -->
+
+## New Year, New Opportunities
+
+There is something that we like to do every new year, and that is to take a look at how our docs changed through the past year.
+
+You see, NEAR is a live ecosystem, where new features are added constantly, products and projects emerge, and our docs need to reflect that. This means that we are always adding, removing, and updating content.
+
+By looking at the changes we made, we get to remember what we achieved - it is always nice to see all we built in a year - and it also helps us discover what we lost along the way!
+
+Join us while we take a look at the changes we made in 2024, and what we are planning for 2025.
+
+## Consolidating Documentation
+
+One of the main issues we tackled this year was consolidating our documentation.
+
+Users often complained that we had a lot of content spread across different sections, pages, and repositories, and we wanted to bring it all together in one place.
+
+At the beginning of 2024, we had different menus for [Concepts](/concepts/basics/protocol), [Smart Contracts](/build/smart-contracts/what-is), [Web Applications](/build/web3-apps/what-is), and [Data Infrastructure](/build/data-infrastructure/what-is).
+
+We decided to merge all these pages into a single `Docs` section, with a shared navigation bar, so you can always easily jump from one topic to another.
+
+![Navigation](/docs/blog/2024-review/2024-blog.jpg)
+_Navigation before (left) and now (right), notice how many links were removed from both top and left navigation bars!_
+
+To keep the sidebar clean, we added a `What is...` page for each major topic, which helps you to understand the basics and decide if that section is what you are looking for.
+
+For example, we now have the following pages:
+
+- [What is NEAR Protocol?](/concepts/basics/protocol)
+- [What is Chain Abstraction?](/build/chain-abstraction/what-is)
+- [What is a Smart Contract?](/build/smart-contracts/what-is)
+
+## Code Explainer
+
+During this year, we took a couple of weeks to build an in-house tool to simplify explaining code!
+
+![code explainer](/docs/blog/2024-review/2024-blog-2.jpg)
+
+The new `Code Explainer` allows us to easily explain long snippets of code, by highlighting the essential parts and adding text blocks to explain what is happening.
+
+Our new [Smart Contract Anatomy](/build/smart-contracts/anatomy/) section looks amazing and is much easier to understand now!
+
+## 2024: A Year of Growth
+
+This year we have been busy adding new sections, pages, and tutorials to our documentation. Let's briefly go through some of them.
+
+### Primitives
+
+One of the first things we added was a section about [Primitives](/build/primitives/what-is), which explains the basic building blocks of NEAR Protocol.
+
+![Primitives](/docs/blog/2024-review/2024-blog-3.jpg)
+
+In the new Primitives section, we show how to create and use [NFTs](/build/primitives/nft), [FTs](/build/primitives/ft), [DAOs](/build/primitives/dao), [Linkdrops](/build/primitives/linkdrop), [Oracles](/build/primitives/oracles), and [Decentralized Exchanges](/build/primitives/dex).
+
+Every page is full of snippets that explain how to leverage each primitive from any tool that you are using, be it the bash terminal, a web application, or from within a smart contract.
+
+### Chain Abstraction
+
+We also added a section about [Chain Abstraction](/build/chain-abstraction/what-is), which explains how NEAR accounts can be used to control accounts on other chains.
+
+![alt text](/docs/blog/2024-review/2024-blog-4.jpg)
+_Did you know you can control Ethereum and Bitcoin accounts from NEAR?_
+
+We expect to make this section grow in 2025, as we plan to add more tutorials and examples on interacting with chains like Base, Solana, and Polygon.
+
+### New Beginner's Guide
+
+In 2024 we also released a brand new [Step-by-Step Guide to Mastering Near](/tutorials/auction/introduction). This guide is perfect for beginners, as it explains everything from creating an account to deploying a smart contract, creating a web application for it, and even how to monitor the contract's activity!
+
+![Beginner's Guide](/docs/blog/2024-review/2024-blog-5.jpg)
+
+It is our most complete guide yet! But stay tuned, as we are planning to add more tutorials and examples to it in 2025.
+
+### NEAR API
+
+We also released a new version of our [API documentation](/tools/near-api), which now includes all API flavors - JavaScript, Rust, and Python.
+
+![API](/docs/blog/2024-review/2024-blog-6.jpg)
+
+In this new version, we added a lot of examples on how to use the API in the most common scenarios, as well as linked all the code to a single [GitHub repository](https://github.com/near-examples), to make it easier for us to test it, and for you to copy and paste the code.
+
+### Near Examples
+
+An important part of our documentation is the examples it references. We have been working hard to make sure that all examples are up-to-date and working.
+
+For example, we have updated all our canonical examples (Hello Near, Counter, Donations, NFT, FT) to use the latest version of core libraries (`near-api`, `near-sdk` and `wallet-selector`)
+
+## Looking Forward
+
+We are excited to start 2025 with a lot of new ideas and projects in mind. We are planning to add new examples about how to build complex DeFi applications on NEAR, as well as adding community projects such as [Pikespeak](https://doc.pikespeak.ai/), [FastNear](https://github.com/fastnear/explorer-api), and [NearBlocks](https://api.nearblocks.io/api-docs/)
+
+More importantly, we expect 2025 to be the year of AI, focusing on building docs showing how easy is to use [NEAR AI](https://near.ai) to build and deploy machine learning models on NEAR.
+
+By focusing on AI, we also expect to bring new ways to engage with our documentation, such as a chatbot that can help you find the right page!
+
+Of course, everything is being developed using open-source tools and libraries, so you can easily replicate what we are doing.
+
+We are excited to start this new year, and hope you are too! 🚀

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

@@ -195,7 +195,7 @@ This call will return:
 ```
 
 :::info
-Find a code example about quering storage status on [this link](https://github.com/crustio/crust-demo/blob/main/near/src/index.ts#L144-L147).
+Find a code example about querying storage status on [this link](https://github.com/crustio/crust-demo/blob/main/near/src/index.ts#L144-L147).
 :::
 
 #### 4. Add file prepaid

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

@@ -8,13 +8,6 @@ sidebar_label: Storage Staking
 >
 > In storage staking (sometimes called _state_ staking), the account that owns a smart contract must stake (or lock) tokens according to the amount of data stored in that smart contract, effectively reducing the balance of the contract's account.
 
-<blockquote className="info">
-<strong>Coming from Ethereum?</strong><br /><br />
-
-If you’re familiar with Ethereum’s pricing model, you may know that, like NEAR, the protocol charges a fee (called "gas") for each transaction. Unlike NEAR, Ethereum's gas fee accounts for the amount of data stored via that transaction. This essentially means that anyone can pay once to store permanent data on-chain. This is a poor economic design for at least two reasons: 1. The people running the network (miners, in the case of Ethereum 1) are not appropriately incentivized to store large amounts of data, since a gas fee far charged in the distant past can increase storage costs forever, and 2. The users of a smart contract are charged for the data they send to store in it, rather than charging the owner of the smart contract.
-
-</blockquote>
-
 ## How does NEAR's design align incentives?
 
 Storage-staked tokens are unavailable for other uses, such as validation staking. This increases the yield that validators will receive. Learn more in [the economics whitepaper](https://pages.near.org/papers/economics-in-sharded-blockchain/).

docs/2.build/2.smart-contracts/anatomy/collections.md

@@ -186,7 +186,7 @@ All structures need to be initialized using a **unique `prefix`**, which will be
 
     <Github fname="contract.ts" language="js"
           url="https://github.com/near-examples/storage-examples/blob/main/collections-js/src/contract.ts"
-          start="6" end="21" />
+          start="6" end="25" />
 
 :::tip
 
@@ -239,7 +239,7 @@ Implements a [vector/array](https://en.wikipedia.org/wiki/Array_data_structure)
   <TabItem value="js" label="🌐 JavaScript">
     <Github fname="contract.ts" language="js"
             url="https://github.com/near-examples/storage-examples/blob/main/collections-js/src/contract.ts"
-            start="34" end="58" />
+            start="48" end="73" />
   </TabItem>
   <TabItem value="rust" label="🦀 Rust">
     <Github fname="vector.rs" language="rust"
@@ -261,7 +261,7 @@ Implements a [map/dictionary](https://en.wikipedia.org/wiki/Associative_array) w
   <TabItem value="js" label="🌐 JavaScript">
     <Github fname="contract.ts" language="js"
           url="https://github.com/near-examples/storage-examples/blob/main/collections-js/src/contract.ts"
-          start="97" end="116" />
+          start="111" end="131" />
   </TabItem>
   <TabItem value="rust" label="🦀 Rust">
     <Github fname="lookup_map.rs" language="rust"
@@ -279,7 +279,7 @@ Implements a [map/dictionary](https://en.wikipedia.org/wiki/Associative_array) w
   <TabItem value="js" label="🌐 JavaScript">
     <Github fname="contract.ts" language="js"
           url="https://github.com/near-examples/storage-examples/blob/main/collections-js/src/contract.ts"
-          start="118" end="137" />
+          start="132" end="152" />
   </TabItem>
   <TabItem value="rust" label="🦀 Rust">
     <Github fname="iterable_map.rs" language="rust"
@@ -297,7 +297,7 @@ Implements a [set](https://en.wikipedia.org/wiki/Set_(abstract_data_type)) which
 
   <TabItem value="js" label="🌐 JavaScript">
     <Github fname="contract.ts" language="js"
-      url="https://github.com/near-examples/storage-examples/blob/main/collections-js/src/contract.ts" start="60" end="74" />
+      url="https://github.com/near-examples/storage-examples/blob/main/collections-js/src/contract.ts" start="74" end="89" />
   </TabItem>
 
   <TabItem value="rust" label="🦀 Rust">
@@ -317,7 +317,7 @@ Implements a [map/dictionary](https://en.wikipedia.org/wiki/Associative_array) w
   <TabItem value="js" label="🌐 JavaScript">
     <Github fname="contract.ts" language="js"
           url="https://github.com/near-examples/storage-examples/blob/main/collections-js/src/contract.ts"
-          start="76" end="95" />
+          start="90" end="110" />
   </TabItem>
   <TabItem value="rust" label="🦀 Rust">
     <Github fname="iterable_set.rs" language="rust"
@@ -359,7 +359,7 @@ When nesting SDK collections, be careful to **use different prefixes** for all c
   <TabItem value="js" label="🌐 JavaScript">
 
     <Github fname="nested.ts" language="js"
-            url="https://github.com/near-examples/storage-examples/blob/main/collections-js/src/contract.ts" start="140" end="182"/>
+            url="https://github.com/near-examples/storage-examples/blob/main/collections-js/src/contract.ts" start="153" end="196"/>
 
   </TabItem>
 

docs/2.build/4.web3-apps/backend/backend.md

@@ -2,6 +2,9 @@
 id: backend-login
 title: Authenticate NEAR Users 
 ---
+
+import {Github} from "@site/src/components/codetabs"
+
 Recently NEAR has approved a new standard that, among other things, enables users to authenticate into a backend service.
 
 The basic idea is that the user will sign a challenge with their NEAR wallet, and the backend will verify the signature. If the signature is valid, then the user is authenticated.
@@ -60,86 +63,5 @@ const signature = wallet.signMessage({ message, recipient, nonce: challenge, cal
 ### 3. Verify the Signature
 Once the user has signed the challenge, the wallet will call the `callbackUrl` with the signature. The backend can then verify the signature.
 
-```js
-const naj = require('near-api-js')
-const js_sha256 = require("js-sha256")
-
-class Payload {
-    constructor({ message, nonce, recipient, callbackUrl }) {
-        // The tag's value is a hardcoded value as per
-        // defined in the NEP [NEP413](https://github.com/near/NEPs/blob/master/neps/nep-0413.md)
-        this.tag = 2147484061;
-        this.message = message;
-        this.nonce = nonce;
-        this.recipient = recipient;
-        if (callbackUrl) { this.callbackUrl = callbackUrl }
-    }
-}
-
-const payloadSchema = {
-    struct: {
-      tag: "u32",
-      message: "string",
-      nonce: { array: { type: "u8", len: 32 } },
-      recipient: "string",
-      // Must be of type { option: "string" }
-      callbackUrl: { option: "string" },
-    },
-  };
-
-export async function authenticate({ accountId, publicKey, signature }) {
-  // A user is correctly authenticated if:
-  // - The key used to sign belongs to the user and is a Full Access Key
-  // - The object signed contains the right message and domain
-  const full_key_of_user = await verifyFullKeyBelongsToUser({ accountId, publicKey })
-  const valid_signature = verifySignature({ publicKey, signature })
-  return valid_signature && full_key_of_user
-}
-
-export function verifySignature({ publicKey, signature }) {
-  // Reconstruct the payload that was **actually signed**
-  const payload = new Payload({ message: MESSAGE, nonce: CHALLENGE, recipient: APP, callbackUrl: cURL });
-  const borsh_payload = borsh.serialize(payloadSchema, payload);
-  const to_sign = Uint8Array.from(js_sha256.sha256.array(borsh_payload))
-
-  // Reconstruct the signature from the parameter given in the URL
-  let real_signature = Buffer.from(signature, 'base64')
-
-  // Use the public Key to verify that the private-counterpart signed the message
-  const myPK = naj.utils.PublicKey.from(publicKey)
-  return myPK.verify(to_sign, real_signature)
-}
-
-export async function verifyFullKeyBelongsToUser({ publicKey, accountId }) {
-  // Call the public RPC asking for all the users' keys
-  let data = await fetch_all_user_keys({ accountId })
-
-  // if there are no keys, then the user could not sign it!
-  if (!data || !data.result || !data.result.keys) return false
-
-  // check all the keys to see if we find the used_key there
-  for (const k in data.result.keys) {
-    if (data.result.keys[k].public_key === publicKey) {
-      // Ensure the key is full access, meaning the user had to sign
-      // the transaction through the wallet
-      return data.result.keys[k].access_key.permission == "FullAccess"
-    }
-  }
-
-  return false // didn't find it
-}
-
-// Aux method
-async function fetch_all_user_keys({ accountId }) {
-  const keys = await fetch(
-    "https://rpc.testnet.near.org",
-    {
-      method: 'post',
-      headers: { 'Content-Type': 'application/json; charset=utf-8' },
-      body: `{"jsonrpc":"2.0", "method":"query", "params":["access_key/${accountId}", ""], "id":1}`
-    }).then(data => data.json()).then(result => result)
-  return keys
-}
-
-module.exports = { authenticate, verifyFullKeyBelongsToUser, verifySignature };
-```
+<Github fname="authenticate.js" language="javascript"
+      url="https://github.com/near-examples/near-api-examples/blob/main/javascript/examples/verify-signature/authentication.js" />

docs/3.tutorials/near-components/bos-loader.md

@@ -5,7 +5,7 @@ title: BOS Loader
 
 # BOS Loader
 
-In this article you'll learn how to develop, test, and deploy BOS components using CLI tools. You can use this workflow to tap into the colaboration, pull-request, and other GitHub benefits while still deploying components to the BOS. 
+In this article you'll learn how to develop, test, and deploy BOS components using CLI tools. You can use this workflow to tap into the collaboration, pull-request, and other GitHub benefits while still deploying components to the BOS. 
 
 [BOS Component Loader](https://github.com/near/bos-loader) serves a local directory of component files as a JSON payload properly formatted to be plugged into a BOS `redirectMap`. When paired with a viewer configured to call out to this loader, it enables local component development.
 

docs/4.tools/near-api.md

@@ -905,6 +905,22 @@ When deleting an access key, you need to specify the public key of the key you w
 
 ---
 
+## Validate Message Signatures
+
+Users can sign messages using the `wallet-selector` `signMessage` method, which returns a signature. This signature can be verified using the following code:
+
+<Tabs groupId="api">
+  <TabItem value="js" label="🌐 JavaScript">
+
+    <Github fname="authenticate.js" language="javascript"
+      url="https://github.com/near-examples/near-api-examples/blob/main/javascript/examples/verify-signature/authentication.js" />
+
+  </TabItem>
+</Tabs>
+
+---
+
+
 ## Utilities
 
 ### NEAR to yoctoNEAR {#near-to-yoctonear}

docs/6.integrations/tokens.md

@@ -1499,7 +1499,7 @@ Now, let's try to follow the steps described in the previous section and determi
   4. Loop through `result` » `receipts_outcome` until finding the object where `id` is equal to the value from step 2. Similar to step 1, this object will also contain a `status` field that should contain the key `SuccessReceiptId`. Again, if this isn't there no fungible tokens were transferred, otherwise get the value of the `SuccessReceiptId`. In the above example, this value is `4Tc8MsrJZSMpNZx7u4jSqxr3WhRzqxaNHxLJFqz8tUPR`.
   5. Similar to the previous step, loop through the `result` » `receipts_outcome` until you find the object where the `id` matches the value from step 4. In that object check that `outcome` » `status` has the `SuccessValue` field. This `SuccessValue` represents how many fungible tokens the receiving contract is "returning" to the fungible token contract. Note that in the example above the value is `Ijki`, which is the base64-encoded version of `"9"`. At this point, we know that 10 fungible tokens were sent (from step 3) and 9 were taken.
 
-For additional clarity, let's take a look at one more optional aspect. In step 4 we isolated an obeject in `result` » `receipts_outcome`. There's an array of `receipt_ids` that's particularly interesting. The first element in the array is the receipt ID `EB69xtJiLRh9RNzAHgBGmom8551hrK2xSRreqbjvJgu5`. If we loop through the `result` » `receipts_outcome` and find this as the value for the `id` key, we'll see what happened in the function `ft_on_transfer` which takes place in the contract receiving the fungible tokens. In this object the `status` » `SuccessValue` is `IjEi` which is the base64-encoded value of `"1"`.
+For additional clarity, let's take a look at one more optional aspect. In step 4 we isolated an object in `result` » `receipts_outcome`. There's an array of `receipt_ids` that's particularly interesting. The first element in the array is the receipt ID `EB69xtJiLRh9RNzAHgBGmom8551hrK2xSRreqbjvJgu5`. If we loop through the `result` » `receipts_outcome` and find this as the value for the `id` key, we'll see what happened in the function `ft_on_transfer` which takes place in the contract receiving the fungible tokens. In this object the `status` » `SuccessValue` is `IjEi` which is the base64-encoded value of `"1"`.
 
 In summary:
 1. A user called the fungible token contract with the method `ft_transfer_call` specifying the receiver account, how many tokens to send, and custom info.