Merge branch 'master' into near-drop-example

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/basics/protocol.md

@@ -3,12 +3,13 @@ id: protocol
 title: What is NEAR?
 ---
 
-NEAR is a **user-friendly** and [**carbon-neutral**](https://near.org/blog/near-climate-neutral-product/) blockchain, built to be [fast, secure, and able to grow without limits](https://www.leewayhertz.com/comparison-of-blockchain-protocols#Parallel-comparison-of-various-blockchain-networks).
+NEAR is a **user-friendly** and [**carbon-neutral**](https://near.org/blog/near-climate-neutral-product/) blockchain, built to be [fast, secure, and infinitely scalable](https://www.leewayhertz.com/comparison-of-blockchain-protocols#Parallel-comparison-of-various-blockchain-networks).
 
 ![img](@site/static/docs/assets/welcome-pages/protocol.png)
 
+In technical terms, NEAR is a [layer one](https://coinmarketcap.com/academy/glossary/layer-1-blockchain), [sharded](https://near.org/blog/near-launches-nightshade-sharding-paving-the-way-for-mass-adoption), [proof-of-stake](https://en.wikipedia.org/wiki/Proof_of_stake) blockchain built with usability in mind.
 
-NEAR is the **blockchain for everyone**.
+In simpler terms, NEAR is the **blockchain for everyone**.
 
 <details>
 
@@ -36,14 +37,14 @@ NEAR is a technical marvel, offering built-in features such as named accounts an
 2. Simple sign-up: make an account using [email](https://dev.near.org/signup) or [telegram](https://web.telegram.org/k/#@herewalletbot)
 3. Transactions are **fast** _(~1.3s transactions)_ and **cheap** _(< 1¢ in fees)_
 4. You don't need to buy crypto thanks to **built-in account abstraction**
-5. [Access Keys](../protocol/access-keys.md) make it safe and easy to use.
+5. [Access Keys](../protocol/access-keys.md) make it safe and easy to use
 6. Control accounts on **other chains** thanks to [chain signatures](../abstraction/chain-signatures.md)
 
 ### 🛡️ Battle-Tested
 
-1. 4 years of **100% uptime** with more than [**800M** transactions](https://pikespeak.ai/near-world/overview) processed
-2. NEAR has sustained peaks of [>13M transactions](https://pikespeak.ai/near-world/overview) in a day
-3. In March 2024, the top three monthly [dApps](https://dappradar.com/rankings?range=30d), based on unique active wallets, were built on NEAR:
+1. 4 years of **100% uptime** and [**3 Billion** transactions](https://pikespeak.ai/near-world/overview) processed
+2. NEAR has sustained peaks of [>13M transactions](https://pikespeak.ai/near-world/overview) in a single day
+3. NEAR is home to decentralized apps with [millions of users](https://dappradar.com/rankings?range=30d):
     - [Kai-ching](https://cosmose.ai/)
     - [Sweat](https://sweateconomy.com/)
     - [Hot Wallet](https://t.me/herewalletbot/)

docs/1.concepts/protocol/access-keys.md

@@ -2,14 +2,14 @@
 id: access-keys
 title: Access Keys
 ---
-In all blockchains, users control their accounts by holding a `private key` (a secret only they know) and using it to sign [transactions](./transactions.md).
+In all blockchains, users control their accounts by holding a [`private key`](https://en.wikipedia.org/wiki/Public-key_cryptography) (a secret only they know) and using it to sign [transactions](./transactions.md).
 
 ![img](@site/static/docs/assets/welcome-pages/access-keys.png)
 
-NEAR accounts present the **unique** feature of being able to hold multiple [Access Keys](https://en.wikipedia.org/wiki/Public-key_cryptography), each with its **own set of permissions**. We distinguish two types of Keys:
+NEAR accounts present the **unique** feature of being able to hold **multiple Access Keys**, each with its **own set of permissions**. We distinguish two types of Keys:
 
 1. `Full-Access Keys`: Have full control over the account, and should **never be shared**
-2. `Function-Call Keys`: Can sign calls to specific contract, and are **meant to be shared**
+2. `Function-Call Keys`: Can only sign calls for specific contracts, and are **meant to be shared**
 
 ---
 
@@ -25,22 +25,24 @@ As the name suggests, `Full-Access` keys have full control of an account, meanin
 You should never share your `Full-Access`, otherwise you are giving **total control over the account**.
 
 :::tip
-The **first** Full-Access Key of an account is added when the account is **created**
+[Implicit accounts](./account-id.md#implicit-address) already have a `Full-Access Key` by default, while for [`named accounts`](./account-id.md#named-address) their first `Full-Access Key` is added on creation
 :::
 
 ---
 
 ## Function-Call Keys {#function-call-keys}
 
-`Function-Call` keys can only sign transactions calling a **specific contract**, and do **not allow** to **attach NEAR tokens** to the call. They are defined by three attributes:
-1. `receiver_id`: The **contract** which the key allows to call. No other contract can be called using this key
-2. `method_names` (Optional): The contract's **methods** the key allows to call. If omitted, all methods can be called
-3. `allowance` (Optional): The **amount of NEAR** allowed to be spent on [gas](gas.md). If omitted, the key can consume **unlimited** as gas
+`Function-Call` keys can only sign transactions calling a **specific contract**, and do **not allow** to **attach NEAR tokens** to the call.
 
-Function-Call keys have the main purpose of being shared, so third-parties can make contract calls in your name. This is useful in [multiple scenarios as we will see below](#benefits-of-function-call-keys).
+They are defined by three attributes:
+1. `receiver_id`: The **only contract** which the key allows to call, no other contract can be called with this key
+2. `method_names` (Optional): The contract's **methods** the key allows to call. If omitted, all contract's methods can be called
+3. `allowance` (Optional): The **amount of NEAR** allowed to be spent on [gas](gas.md). If omitted, the key can consume **unlimited** gas
+
+`Function Call Keys` are meant to be shared with applications, so third-parties can make contract calls in your name. This is useful in [multiple scenarios as we will see below](#benefits-of-function-call-keys).
 
 :::tip 
-`Function-Call` keys are secure to share, as they only permit calls to a specific contract and prohibit NEAR token transfers.
+`Function-Call` keys are secure to share, as they only permit calls to a specific contract and prohibit NEAR token transfers
 :::
 
 ---
@@ -62,11 +64,19 @@ Sharing this key is safe for the user, because even in the case of somebody stea
 
 ### Simple Onboarding
 
-Another common use-case of `Function-Call` keys is to simplify the **onboarding** process for new users. It works as follows:
+Another common use-case of `Function-Call` keys is to simplify the **onboarding** process for new users.
+
+It works as follows:
+
+1. Create a contract that has a method called `create_account`
+    - This method should only be callable by the contract itself and
+    - When executed, the method should create a new account and transfer some tokens to it
 
-First create a contract that has a method called `create_account`. This method should only be callable by the contract itself and, when executed, should create a new account and transfer some tokens to it.
+2. Add multiple `Function Call Keys` in the contract's account, that **only allow to call `create_account`**
 
-You can then create multiple `Function-Call` in the contract's account, that only allow to call `create_account`. Drop these keys to your friends, so they can call the method, and easily create an account with some tokens.
+3. Give these keys to your friends! They will be able to call the method, and easily create an account with some tokens
+
+Your main account and your funds will never be at risk, as the keys can only be used to call the `create_account` method.
 
 :::tip
 This is the basic principle behind [NEAR Drops](../../2.build/5.primitives/linkdrop.md), a way to distribute assets to a large number of users
@@ -94,4 +104,4 @@ Locking an account is very useful when one wants to deploy a contract, and let t
 
 :::warning
 An account could still add keys to itself through a smart contract, effectively allowing the contract to unlock the account. Notice that this can only be done if the contract is deployed before the account is locked
-:::
+:::

docs/1.concepts/protocol/account-id.md

@@ -6,12 +6,12 @@ title: Address (Account ID)
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-NEAR accounts are identified by a unique address, which take one of two forms:
-1. [**Implicit addresses**](#implicit-address), which are 64 characters long (e.g. `fb9243ce...`)
-2. [**Named addresses**](#named-address), which are simpler to remember and act as domains (e.g. `alice.near`)
+NEAR accounts are identified by a unique address, which takes one of two forms:
+1. [**Implicit address**](#implicit-address), which are 64 characters long (e.g. `fb9243ce...`)
+2. [**Named address**](#named-address), which act as domains (e.g. `alice.near`)
 
 :::tip Searching to create an account?
-You have multiple ways to create an account, you can [sign-up using your email](https://dev.near.org/signup) (note: email-based accounts currently have limited ability to transfer funds or sign transactions), get a mobile wallet through [telegram](https://web.telegram.org/k/#@herewalletbot), or create a [web wallet](https://app.mynearwallet.com).
+You have multiple ways to create an account, you can [sign-up using your email](https://dev.near.org/signup), get a mobile wallet through [telegram](https://web.telegram.org/k/#@herewalletbot), or create a [web wallet](https://wallet.meteorwallet.app/wallet).
 :::
 
 ---
@@ -24,7 +24,13 @@ For example:
 - Corresponds to the public key: `ed25519:CQLP1o1F3Jbdttek3GoRJYhzfT...`
 - And controls the account: `a96ad3cb539b653e4b869bd7cf26590690e8971...`
 
-Implicit accounts always *exist*, and thus do not need to be created. However, in order to use the account you will still need to fund it with NEAR tokens (or get somebody to pay the gas for your transaction).
+Implicit accounts always *exist*, and thus do not need to be created. However, in order to use the account you will still need to fund it with NEAR tokens (or get a relayer to pay your transaction's [gas](./gas.md)).
+
+:::tip
+
+In NEAR, you can delete the private key of an implicit account, which effectively locks the account and prevents anyone to control it
+
+:::
 
 <details>
 
@@ -46,9 +52,9 @@ near account create-account fund-later use-auto-generation save-to-folder ~/.nea
 ---
 
 ## Named Address
-In NEAR, users can register **named accounts** (e.g. `bob.near`) which are simpler to share and remember.
+Users can register **named accounts** (e.g. `bob.near`) which are easy to remember and share.
 
-Another advantage of named accounts is that they can create **sub-accounts** of themselves, effectively working as domains:
+An awesome feature of named accounts is that they can create **sub-accounts** of themselves, effectively working as domains:
 
 1. The [`registrar`](https://nearblocks.io/address/registrar) account can create top-level accounts (e.g. `near`, `sweat`, `kaiching`).
 2. The `near` account can create sub-accounts such as `bob.near` or `alice.near`