Merge branch 'master' into multichain-reorg

Author: gagdiez

docs/data-infrastructure/indexers.md

@@ -91,6 +91,17 @@ Because indexers listen to the *stream of data* from the blockchain and the data
 Another example that highlights the need for a "wide query" is when you use a seed phrase to recover one or more accounts. Since a seed phrase essentially represents a signing key pair, the recovery is for all accounts that share the associated public key. Therefore, when a seed phrase is used to recover an account via [NEAR Wallet](https://wallet.near.org), the query requires that all accounts with a matching public key are found and recovered. Utilizing [Near Lake Framework](https://github.com/near/near-lake-framework-rs) can be used to store this data in a permanent database and this allows [NEAR Wallet](https://wallet.near.org) to perform such "wide queries". This is impossible to achieve using JSON-RPC only.
 
 ---
+
+## Indexers in the NEAR ecosystem
+
+There are [multiple indexing options](../tools/data-services.md) available in the NEAR ecosystem. If you are ready to host your own indexer, we recommend using the [Near Lake Framework](./lake-framework/near-lake.md) as it is simple, reliable, and available in multiple languages (JavaScript, Rust, Python). 
+
+If speed is critical for your indexing needs, consider using [Near Indexer](./near-indexer.md). However, please note that maintaining it can be more complex and costly, as it essentially operates as an independent node in the network. 
+
+If you prefer not to host your own solution, you can utilize [third-party services](../tools/data-services.md).
+
+---
+
 ## Summary
 
 We hope this article gives you an understanding of the Indexer concept. Also, we hope now you can easily decide whether you need an indexer for your application.

docs/data-infrastructure/tutorials/near-indexer.md

@@ -128,17 +128,31 @@ After we finish initializing the indexer, and configuring it, we can start it by
       ```
     </TabItem>
 </Tabs>
+
+<details>
+<summary>How it works</summary>
+
+- The command initializes the indexer's configuration: home directory, sync mode, streaming mode, finality, etc.
+- Creates a Tokio runtime on a dedicated thread.
+- Creates an instance of the Indexer using the provided configuration, starts it, and streams blocks to our handler. Within the handler (`listen_blocks` method), there is an infinite loop that parses block data for each new block received.
+
+<Github fname="main.rs" language="rust"
+        url="https://github.com/near/nearcore/blob/master/tools/indexer/example/src/main.rs"
+        start="271" end="289" />
+
+</details>
+
 #### Run into an Error?
 - If your indexer cannot find `boot nodes`, check the [boot nodes](#boot-nodes) section
 ---
 
 ## Parsing the Block Data
 
-From the block data, we can access the transactions, their receipts and actions. See the code below for an example of how to parse the block data:
+Within the `listen_blocks` method, we can parse the block data as it flows from the stream. From the block data, we can access the transactions, their receipts, and actions. See the code below for an example of how to parse the block data:
 
 <Github fname="main.rs" language="rust"
         url="https://github.com/near/nearcore/blob/master/tools/indexer/example/src/main.rs"
-        start="13" end="243" />
+        start="10" end="254" />
 
 ---
 
@@ -183,8 +197,8 @@ You can choose Indexer Framework sync mode by setting what to stream:
 - BlockHeight(u64) - Specific block height to start syncing from.
 
 <Github fname="main.rs" language="rust"
-        url="https://github.com/near-examples/near-indexer/blob/main/src/main.rs"
-        start="34" end="34" />
+        url="https://github.com/near/nearcore/blob/master/tools/indexer/example/src/main.rs"
+        start="274" end="274" />
 
 <hr class="subsection" />
 
@@ -195,8 +209,8 @@ You can choose Indexer Framework streaming mode by setting what to stream:
 - WaitForFullSync - Don't stream until the node is fully synced
 
 <Github fname="main.rs" language="rust"
-        url="https://github.com/near-examples/near-indexer/blob/main/src/main.rs"
-        start="35" end="35" />
+        url="https://github.com/near/nearcore/blob/master/tools/indexer/example/src/main.rs"
+        start="275" end="275" />
 
 <hr class="subsection" />
 
@@ -208,8 +222,8 @@ You can choose finality level at which blocks are streamed:
 - Final - `final`, the block is final and irreversible.
 
 <Github fname="main.rs" language="rust"
-        url="https://github.com/near-examples/near-indexer/blob/main/src/main.rs"
-        start="36" end="36" />
+        url="https://github.com/near/nearcore/blob/master/tools/indexer/example/src/main.rs"
+        start="276" end="276" />
 
 <hr class="subsection" />
 
@@ -285,11 +299,11 @@ You can also use NEAR Indexer Framework as a dependency in your own Rust project
 
 ```toml
 [dependencies]
-near-indexer = { git = "https://github.com/near/nearcore", tag = "2.8.0" }
-near-indexer-primitives = { git = "https://github.com/near/nearcore", tag = "2.8.0" }
-near-config-utils = { git = "https://github.com/near/nearcore", tag = "2.8.0" }
-near-o11y = { git = "https://github.com/near/nearcore", tag = "2.8.0" }
-near-primitives = { git = "https://github.com/near/nearcore", tag = "2.8.0" }
+near-indexer = { git = "https://github.com/near/nearcore", tag = "2.9.1" }
+near-indexer-primitives = { git = "https://github.com/near/nearcore", tag = "2.9.1" }
+near-config-utils = { git = "https://github.com/near/nearcore", tag = "2.9.1" }
+near-o11y = { git = "https://github.com/near/nearcore", tag = "2.9.1" }
+near-primitives = { git = "https://github.com/near/nearcore", tag = "2.9.1" }
 ```
 
 <MovingForwardSupportSection />

docs/index.md

@@ -73,9 +73,9 @@ import LandingHero from '@site/src/components/LandingHero';
       title="Smart Contracts"
     >
       <ul>
-        <li><a href="/smart-contracts/what-is">What are Smart Contracts?</a></li>
-        <li><a href="/smart-contracts/quickstart">Quickstart ✨</a></li>
-        <li><a href="/smart-contracts/anatomy/">Contract's Anatomy</a></li>
+        <li><a href="/smart-contracts/what-is">Learn what is a Smart Contract</a></li>
+        <li><a href="/smart-contracts/quickstart">Build your First Contract ✨</a></li>
+        <li><a href="/smart-contracts/anatomy/">Understand Fundamental Concepts</a></li>
       </ul>
     </Card>
   </div>

docs/primitives/ft/sdk-contract-tools.md

@@ -0,0 +1,126 @@
+---
+id: sdk-contract-tools
+title: Create FT using Contract Tools
+sidebar_label: Create FT using Contract Tools
+description: "Learn how to create a fungible token (FT) using Contract Tools package"
+---
+
+import {Github} from "@site/src/components/UI/Codetabs";
+import MovingForwardSupportSection from '@site/src/components/MovingForwardSupportSection';
+
+In this tutorial, we will create a fungible token (FT) using the [NEAR SDK Contract Tools](https://github.com/near/near-sdk-contract-tools) package. This package is a collection of common tools and patterns to simplify smart contract development, including:
+
+- Storage fee management
+- Escrow pattern and derive macro
+- Owner pattern and derive macro
+- Pause pattern and derive macro
+- Role-based access control
+- Derive macros for [NEP standards](./standard.md)
+  - NEP-141 (fungible token), extension NEP-148
+  - NEP-145 (storage management), and integrations for the fungible token and non-fungible token standards
+  - NEP-171 (non-fungible token), extensions NEP-177, NEP-178, NEP-181
+  - NEP-297 (events)
+
+---
+
+## Introduction
+
+While one can create a fungible token (FT) contract from scratch using only the `near-sdk` and `near_contract_standards` (e.g. [FT contract](https://github.com/near-examples/FT)), a simpler approach is to use `near-sdk-contract-tools`.
+
+`near-sdk-contract-tools` allows us implement the logic for minting/burning logic, access control, and other FT standards by simply deriving macros on our contract struct, as `OpenZeppelin` does for Ethereum contracts.
+
+---
+
+## Basic FT Methods
+
+To derive basic FT methods to our contract, we need to derive `FungibleToken` macro to our contract struct:
+
+<Github fname="lib.rs" language="rust"
+        url="https://github.com/near-examples/ft-contract-tools/blob/main/src/lib.rs"
+        start="9" end="12" />
+
+This will bring all the basic FT methods defined in NEP-141 standard to our contract:
+- `new`
+- `contract_source_metadata`
+- `ft_balance_of`
+- `ft_metadata`
+- `ft_total_supply`
+- `storage_balance_bounds`
+- `storage_balance_of`
+- `ft_resolve_transfer`
+- `ft_transfer`
+- `ft_transfer_call`
+- `storage_deposit`
+- `storage_unregister`
+- `storage_withdraw`
+
+To bring basic owner methods to our contract, we can also derive the `Owner` macro which adds the following methods:
+- `own_get_owner`
+- `own_get_proposed_owner`
+- `own_accept_owner`
+- `own_propose_owner`
+- `own_renounce_owner`
+
+---
+
+## Initialization
+
+To initialize the basic FT contract with custom owner, metadata and storage bounds implement `new` method:
+
+<Github fname="lib.rs" language="rust"
+        url="https://github.com/near-examples/ft-contract-tools/blob/main/src/lib.rs"
+        start="14" end="45" />
+
+---
+
+## Transfer Hook
+
+If we want to customize how the transfer of tokens work (i.e. modify the `ft_transfer` method), we need to implement a hook. Hooks are a way to **wrap (inject code before and after)** component functions:
+
+<Github fname="transfer_hook.rs" language="rust"
+        url="https://github.com/near-examples/ft-contract-tools/blob/main/src/transfer_hook.rs"
+        start="5" end="33" />
+
+Then derive it to our contract struct:
+
+<Github fname="lib.rs" language="rust"
+        url="https://github.com/near-examples/ft-contract-tools/blob/main/src/lib.rs"
+        start="9" end="12" />
+
+---
+
+## Minting
+
+By default, the FT standards do not include a minting method. However, we can easily mint tokens for the owner by implementing a `mint` method, which only the owner can call:
+
+<Github fname="mint.rs" language="rust"
+        url="https://github.com/near-examples/ft-contract-tools/blob/main/src/mint.rs"
+        start="5" end="33" />
+
+:::tip
+
+You can modify this method as you need, for example, to allow minting only when the contract is not paused (requires deriving [`Pausable`](https://github.com/near/near-sdk-contract-tools/tree/develop?tab=readme-ov-file#macro-combinations) hook), or to allow minting only to specific accounts with a certain role or from whitelist with custom limitations
+
+:::
+
+---
+
+## Burning
+
+In the same way that minting is not included in the FT standards, burning is also not included. However, we can also easily implement it.
+
+To burn tokens from the owner's account, we can add a `burn` method which is also only callable by the owner:
+
+<Github fname="burn.rs" language="rust"
+        url="https://github.com/near-examples/ft-contract-tools/blob/main/src/burn.rs"
+        start="5" end="25" />
+
+---
+
+## Conclusion
+
+Using `near-sdk-contract-tools` is a very simple and flexible way to create FT contract with minimal boilerplate which allows us to focus on the business logic.
+
+You can further extend this contract with more features like pausing, role-based access control, escrow pattern, and more by deriving corresponding macros from the package.
+
+<MovingForwardSupportSection />

docs/primitives/nft/sdk-contract-tools.md

@@ -0,0 +1,133 @@
+---
+id: nft-contract-tools
+title: Create NFT using Contract Tools
+sidebar_label: Create NFT using Contract Tools
+description: "Learn how to create a non-fungible token (NFT) using Contract Tools package"
+---
+
+import {Github} from "@site/src/components/UI/Codetabs";
+import MovingForwardSupportSection from '@site/src/components/MovingForwardSupportSection';
+
+In this tutorial, you will create a non-fungible token (NFT) using the [NEAR SDK Contract Tools](https://github.com/near/near-sdk-contract-tools) package. This package is a collection of common tools and patterns to simplify smart contract development, including:
+
+- Storage fee management
+- Escrow pattern and derive macro
+- Owner pattern and derive macro
+- Pause pattern and derive macro
+- Role-based access control
+- Derive macros for [NEP standards](./standard.md)
+  - [NEP-141](https://github.com/near/NEPs/blob/master/neps/nep-0141.md) (fungible token), extension [NEP-148](https://github.com/near/NEPs/blob/master/neps/nep-0148.md)
+  - [NEP-145](https://github.com/near/NEPs/blob/master/neps/nep-0145.md) (storage management), and integrations for the fungible token and non-fungible token standards
+  - [NEP-171](https://github.com/near/NEPs/blob/master/neps/nep-0171.md) (non-fungible token), extensions [NEP-177](https://github.com/near/NEPs/blob/master/neps/nep-0177.md), [NEP-178](https://github.com/near/NEPs/blob/master/neps/nep-0178.md), [NEP-181](https://github.com/near/NEPs/blob/master/neps/nep-0181.md)
+  - [NEP-297](https://github.com/near/NEPs/blob/master/neps/nep-0297.md) (events)
+
+---
+
+## Introduction
+
+While one can create a non-fungible token (NFT) contract from scratch using only the `near-sdk` and `near_contract_standards` (e.g. [NFT contract](https://github.com/near-examples/NFT)), a simpler approach is to use `near-sdk-contract-tools`.
+
+`near-sdk-contract-tools` allows you to implement the minting/burning logic, access control, and other NFT standards by simply deriving macros on the contract's `struct`, as `OpenZeppelin` does for Ethereum contracts.
+
+---
+
+## Basic NFT Methods
+
+To derive basic NFT methods to your smart contract, you need to derive the `NonFungibleToken` macro to the contract's `struct`:
+
+<Github fname="lib.rs" language="rust"
+        url="https://github.com/near-examples/nft-contract-tools/blob/main/src/lib.rs"
+        start="9" end="12" />
+
+This will bring all the basic NFT methods to the contract:
+- `new`
+- `contract_source_metadata`
+- `nft_is_approved`
+- `nft_metadata`
+- `nft_supply_for_owner`
+- `nft_token`
+- `nft_tokens`
+- `nft_tokens_for_owner`
+- `nft_total_supply`
+- `nft_approve`
+- `nft_resolve_transfer`
+- `nft_revoke`
+- `nft_revoke_all`
+- `nft_transfer`
+- `nft_transfer_call`
+- `storage_balance_bounds`
+- `storage_balance_of`
+- `storage_deposit`
+- `storage_unregister`
+- `storage_withdraw`
+
+To bring basic owner methods to the contract, you also need to derive the `Owner` macro, which adds the following methods:
+- `own_get_owner`
+- `own_get_proposed_owner`
+- `own_accept_owner`
+- `own_propose_owner`
+- `own_renounce_owner`
+
+---
+
+## Initialization
+
+To initialize the basic NFT contract with a custom owner, metadata, and storage bounds, implement the `new` method:
+
+<Github fname="lib.rs" language="rust"
+        url="https://github.com/near-examples/nft-contract-tools/blob/main/src/lib.rs"
+        start="14" end="45" />
+
+---
+
+## Transfer Hook
+
+If you want to customize how the token transfer works (i.e., modify the `nft_transfer` method), you need to implement a hook. Hooks are a way to **wrap (inject code before and after)** component functions:
+
+<Github fname="transfer_hook.rs" language="rust"
+        url="https://github.com/near-examples/nft-contract-tools/blob/main/src/transfer_hook.rs"
+        start="5" end="33" />
+
+Then derive it to our contract struct:
+
+<Github fname="lib.rs" language="rust"
+        url="https://github.com/near-examples/nft-contract-tools/blob/main/src/lib.rs"
+        start="9" end="12" />
+
+---
+
+## Minting
+
+By default, the NFT standards do not include a minting method. However, you can easily mint tokens for the owner by implementing an `nft_mint` method:
+
+<Github fname="mint.rs" language="rust"
+        url="https://github.com/near-examples/nft-contract-tools/blob/main/src/mint.rs"
+        start="10" end="40" />
+
+:::tip
+
+You can modify this method as you need, for example, to allow minting only when the contract is not paused (requires deriving [`Pausable`](https://github.com/near/near-sdk-contract-tools/tree/develop?tab=readme-ov-file#macro-combinations) hook), or to enable minting only to specific accounts with a certain role or from a whitelist with custom limitations.
+
+:::
+
+---
+
+## Burning
+
+In the same way that minting is not included in the NFT standards, burning is also not included. However, you can also easily implement it.
+
+To allow users to burn their tokens, you can add a `burn` method:
+
+<Github fname="burn.rs" language="rust"
+        url="https://github.com/near-examples/nft-contract-tools/blob/main/src/burn.rs"
+        start="5" end="25" />
+
+---
+
+## Conclusion
+
+Using `near-sdk-contract-tools` is a simple and flexible way to create an NFT contract with minimal boilerplate, which allows you to focus on the business logic.
+
+You can further extend this contract with more features like pausing, role-based access control, escrow pattern, and more by deriving corresponding macros from the package.
+
+<MovingForwardSupportSection />