From d0dad11ec2c6e5a7c76500e7e52c13eba5277dd0 Mon Sep 17 00:00:00 2001 From: Vadim Volodin Date: Fri, 29 Mar 2024 10:58:07 -0300 Subject: [PATCH] Fix links for Block, Chunk, ExecutionOutcome, Transaction, Shard, Receipt (#1856) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Fix links for Block, Chunk, ExecutionOutcome, Transaction, Shard, Receipt * Apply suggestions from code review --------- Co-authored-by: Damián Parrino --- docs/1.concepts/data-flow/near-data-flow.md | 18 ++++++++--------- .../data-flow/token-transfer-flow.md | 20 +++++++++---------- docs/3.tutorials/indexer/nft-indexer.md | 10 +++++----- .../3.tutorials/indexer/python-nft-indexer.md | 10 +++++----- .../tutorial/indexer-tutorials/nft-indexer.md | 4 ++-- 5 files changed, 31 insertions(+), 31 deletions(-) diff --git a/docs/1.concepts/data-flow/near-data-flow.md b/docs/1.concepts/data-flow/near-data-flow.md index 63eaf1e7f4c..7e1dc51acf2 100644 --- a/docs/1.concepts/data-flow/near-data-flow.md +++ b/docs/1.concepts/data-flow/near-data-flow.md @@ -33,27 +33,27 @@ In fact, any blockchain flow can be represented as an infinity timeline that has And a block appears on that timeline with some interval. Each of these blocks holds the information about the previous one, thus, creating a *chain of blocks*. -NEAR Protocol has a sharded nature, meaning that more than one parallel network, called a [Shard](https://near-indexers.io/docs/data-flow-and-structures/structures/shard), can be live at any moment. And each Shard produces a chunk of a block at a given interval. A Block in NEAR Blockchain is a collection of the block chunks from all shards. Block chunk is shortened to [Chunk](https://near-indexers.io/docs/data-flow-and-structures/structures/chunk) in NEAR Protocol documentation. +NEAR Protocol has a sharded nature, meaning that more than one parallel network, called a [Shard](https://docs.near.org/develop/lake/structures/shard), can be live at any moment. And each Shard produces a chunk of a block at a given interval. A Block in NEAR Blockchain is a collection of the block chunks from all shards. Block chunk is shortened to [Chunk](https://docs.near.org/develop/lake/structures/chunk) in NEAR Protocol documentation. Returning to the data flow itself. The best we can do is to imagine tracks like we could see in audio/video editing apps. Each Shard has its own set of tracks. The top track is for Chunks. They appear no matter what at a given interval, for NEAR Blockchain the interval is about one second. Chunks are being produced even if nothing is happening on the blockchain. ![Timeline as tracks](/docs/flow/02-tracks.png) -But what do we mean by saying something is happening? We mean that something has triggered some changes in the blockchain. And the most well known method to trigger any changes is to send a [Transaction](https://near-indexers.io/docs/data-flow-and-structures/structures/transaction) to the blockchain with instructions of what we want to change and who has requested those changes. +But what do we mean by saying something is happening? We mean that something has triggered some changes in the blockchain. And the most well-known method to trigger any changes is to send a [Transaction](https://docs.near.org/develop/lake/structures/transaction) to the blockchain with instructions of what we want to change and who has requested those changes. -A transaction needs to be constructed, signed and sent to the blockchain. Once it is executed we expect to have a result - [ExecutionOutcome](https://near-indexers.io/docs/data-flow-and-structures/structures/execution_outcome). Oh, that is simple. But it’s not really accurate for NEAR Blockchain. +A transaction needs to be constructed, signed and sent to the blockchain. Once it is executed we expect to have a result - [ExecutionOutcome](https://docs.near.org/develop/lake/structures/execution-outcome). Oh, that is simple. But it’s not really accurate for NEAR Blockchain. ![Transaction execution](/docs/flow/03-tx-outcome-receipt.png) -In the beginning there is a [Transaction](https://near-indexers.io/docs/data-flow-and-structures/structures/transaction), it contains instructions we want to be executed on the blockchain. Transaction is sent to NEAR Blockchain. +In the beginning there is a [Transaction](https://docs.near.org/develop/lake/structures/transaction), it contains instructions we want to be executed on the blockchain. Transaction is sent to NEAR Blockchain. -And yes, it is executed there immediately BUT the immediate result of the transaction execution is always just *an acknowledgement that it will be executed on the chain;* this internal execution request is known as [Receipt](https://near-indexers.io/docs/data-flow-and-structures/structures/receipt). You can think of the [Receipt](https://near-indexers.io/docs/data-flow-and-structures/structures/receipt) as an internal transaction that exists to pass information across shards. +And yes, it is executed there immediately BUT the immediate result of the transaction execution is always just *an acknowledgement that it will be executed on the chain;* this internal execution request is known as [Receipt](https://docs.near.org/develop/lake/structures/receipt). You can think of the [Receipt](https://docs.near.org/develop/lake/structures/receipt) as an internal transaction that exists to pass information across shards. Let’s get back to the tracks to look at the example. -Assuming we have two accounts living on different [Shards](https://near-indexers.io/docs/data-flow-and-structures/structures/shard) **alice.near** and **bob.near**. **alice.near** creates a [Transaction](https://near-indexers.io/docs/data-flow-and-structures/structures/transaction) to send a few tokens to **bob.near**. The [Transaction](https://near-indexers.io/docs/data-flow-and-structures/structures/transaction) is immediately executed and the [ExecutionOutcome](https://near-indexers.io/docs/data-flow-and-structures/structures/execution_outcome) for the [Transaction](https://near-indexers.io/docs/data-flow-and-structures/structures/transaction) is always a [Receipt](https://near-indexers.io/docs/data-flow-and-structures/structures/receipt). +Assuming we have two accounts living on different [Shards](https://docs.near.org/develop/lake/structures/shard) **alice.near** and **bob.near**. **alice.near** creates a [Transaction](https://docs.near.org/develop/lake/structures/transaction) to send a few tokens to **bob.near**. The [Transaction](https://docs.near.org/develop/lake/structures/transaction) is immediately executed and the [ExecutionOutcome](https://docs.near.org/develop/lake/structures/execution-outcome) for the [Transaction](https://docs.near.org/develop/lake/structures/transaction) is always a [Receipt](https://docs.near.org/develop/lake/structures/receipt). -But this [Receipt](https://near-indexers.io/docs/data-flow-and-structures/structures/receipt) cannot be executed here, because **bob.near** doesn’t live on the same Shard as **alice.near**, so **the Receipt must be executed on the receiver’s Shard**. So the Receipt is moving to the Shard where **bob.near** belongs to. +But this [Receipt](https://docs.near.org/develop/lake/structures/receipt) cannot be executed here, because **bob.near** doesn’t live on the same Shard as **alice.near**, so **the Receipt must be executed on the receiver’s Shard**. So the Receipt is moving to the Shard where **bob.near** belongs to. On the destination Shard the Receipt is executed and the process is considered as done. @@ -69,8 +69,8 @@ So the final scheme will look like: ## Summary -We have learnt the main principles of how data is flowing in NEAR Protocol. We have found out that [Transactions](https://near-indexers.io/docs/data-flow-and-structures/structures/transaction) execute and the [ExecutionOutcome](https://near-indexers.io/docs/data-flow-and-structures/structures/execution_outcome) of the Transaction is always a [Receipt](https://near-indexers.io/docs/data-flow-and-structures/structures/receipt). +We have learnt the main principles of how data is flowing in NEAR Protocol. We have found out that [Transactions](https://docs.near.org/develop/lake/structures/transaction) execute and the [ExecutionOutcome](https://docs.near.org/develop/lake/structures/execution-outcome) of the Transaction is always a [Receipt](https://docs.near.org/develop/lake/structures/receipt). -Now we know that [Receipt](https://near-indexers.io/docs/data-flow-and-structures/structures/receipt) is a main internal asset for NEAR Protocol blockchain and it has a power of traveling between [Shards](https://near-indexers.io/docs/data-flow-and-structures/structures/shard). We learnt the NEAR Data flow on a simple example. Of course in real life with more complex transactions, that involve cross-contract calls, there will be more Receipts and ExecutionOutcomes. +Now we know that [Receipt](https://docs.near.org/develop/lake/structures/receipt) is a main internal asset for NEAR Protocol blockchain and it has a power of traveling between [Shards](https://docs.near.org/develop/lake/structures/shard). We learnt the NEAR Data flow on a simple example. Of course in real life with more complex transactions, that involve cross-contract calls, there will be more Receipts and ExecutionOutcomes. We hope this article is useful and you will be able to build your dApps and indexers easily with the knowledge of how data if flowing in NEAR Protocol. diff --git a/docs/1.concepts/data-flow/token-transfer-flow.md b/docs/1.concepts/data-flow/token-transfer-flow.md index 0ab1b4b2340..04ec8bb5560 100644 --- a/docs/1.concepts/data-flow/token-transfer-flow.md +++ b/docs/1.concepts/data-flow/token-transfer-flow.md @@ -41,24 +41,24 @@ OK, this should be enough for introduction, now let's move on to examples. Basically it is an extension of the example from the [NEAR Data Flow](near-data-flow.md) article. -Assume we have two accounts **alice.near** and **bob.near**. They belong to different [Shards](https://near-indexers.io/docs/data-flow-and-structures/structures/shard). **alice.near** sends a few tokens to **bob.near**. +Assume we have two accounts **alice.near** and **bob.near**. They belong to different [Shards](https://docs.near.org/develop/lake/structures/shard). **alice.near** sends a few tokens to **bob.near**. -A [Transaction](https://near-indexers.io/docs/data-flow-and-structures/structures/transaction) signed by **alice.near** is sent to the network. It is immediately executed, [ExecutionOutcome](https://near-indexers.io/docs/data-flow-and-structures/structures/execution_outcome) is the output or result from converting the transaction into a [Receipt](https://near-indexers.io/docs/data-flow-and-structures/structures/receipt). +A [Transaction](https://docs.near.org/develop/lake/structures/transaction) signed by **alice.near** is sent to the network. It is immediately executed, [ExecutionOutcome](https://docs.near.org/develop/lake/structures/execution-outcome) is the output or result from converting the transaction into a [Receipt](https://docs.near.org/develop/lake/structures/receipt). ![Transaction execution](/docs/flow/03-tx-outcome-receipt.png) -During the above process **alice.near**, the sender, was charged a fee (gas). The [Receipt](https://near-indexers.io/docs/data-flow-and-structures/structures/receipt) created as result of the [Transaction](https://near-indexers.io/docs/data-flow-and-structures/structures/transaction) follows these rules: +During the above process **alice.near**, the sender, was charged a fee (gas). The [Receipt](https://docs.near.org/develop/lake/structures/receipt) created as result of the [Transaction](https://docs.near.org/develop/lake/structures/transaction) follows these rules: -1. It will be executed not earlier than next [Block](https://near-indexers.io/docs/data-flow-and-structures/structures/block) -2. It **must** be executed on the receiver's [Shard](https://near-indexers.io/docs/data-flow-and-structures/structures/shard) +1. It will be executed not earlier than next [Block](https://docs.near.org/develop/lake/structures/block) +2. It **must** be executed on the receiver's [Shard](https://docs.near.org/develop/lake/structures/shard) -So, in our case the receiver is **bob.near** and that account belongs to a different [Shard](https://near-indexers.io/docs/data-flow-and-structures/structures/shard) that's why the [Receipt](https://near-indexers.io/docs/data-flow-and-structures/structures/receipt) moves to the receiver's Shard and is put in the execution queue. +So, in our case the receiver is **bob.near** and that account belongs to a different [Shard](https://docs.near.org/develop/lake/structures/shard) that's why the [Receipt](https://docs.near.org/develop/lake/structures/receipt) moves to the receiver's Shard and is put in the execution queue. In our example the Receipt is executed in the very next Block. ![The Receipt is executed in the next Block](/docs/flow/04-send-nears-flow.png) -Almost done. Remember the refund? So the [ExecutionOutcome](https://near-indexers.io/docs/data-flow-and-structures/structures/execution_outcome) for the Receipt will be another Receipt that is refunding the Gas to the sender. **bob.near** has received tokens from **alice.near**. Now, **alice.near** becomes the receiver for a new (and last) Receipt (keep in mind the sender in this Receipt is always **system**). +Almost done. Remember the refund? So the [ExecutionOutcome](https://docs.near.org/develop/lake/structures/execution-outcome) for the Receipt will be another Receipt that is refunding the Gas to the sender. **bob.near** has received tokens from **alice.near**. Now, **alice.near** becomes the receiver for a new (and last) Receipt (keep in mind the sender in this Receipt is always **system**). Keep in mind rule #2: the Receipt must be executed on the receiver's Shard. So this Receipt moves to the Shard where **alice.near** belongs to. And it is the last execution in this process. @@ -69,13 +69,13 @@ This is it. Tokens has been transferred from the account on one Shard to the acc ## Token transfer between accounts found on the same shard -Let's have a look at the example where both accounts are on the same [Shard](https://near-indexers.io/docs/data-flow-and-structures/structures/shard). The process is the same as in the previous example, except there are no Receipts moving from one Shard to another. +Let's have a look at the example where both accounts are on the same [Shard](https://docs.near.org/develop/lake/structures/shard). The process is the same as in the previous example, except there are no Receipts moving from one Shard to another. -A [Transaction](https://near-indexers.io/docs/data-flow-and-structures/structures/transaction) signed by **alice.near** is sent to the network. It is immediately executed, [ExecutionOutcome](https://near-indexers.io/docs/data-flow-and-structures/structures/execution_outcome) is the result of converting the transaction into a [Receipt](https://near-indexers.io/docs/data-flow-and-structures/structures/receipt). +A [Transaction](https://docs.near.org/develop/lake/structures/transaction) signed by **alice.near** is sent to the network. It is immediately executed, [ExecutionOutcome](https://docs.near.org/develop/lake/structures/execution-outcome) is the result of converting the transaction into a [Receipt](https://docs.near.org/develop/lake/structures/receipt). ![Transaction execution](/docs/flow/03-tx-outcome-receipt.png) -The Receipt is already on the receiver's Shard, so it is put in the execution queue of the next [Block](https://near-indexers.io/docs/data-flow-and-structures/structures/block). It is executed in the next Block, and the [ExecutionOutcome](https://near-indexers.io/docs/data-flow-and-structures/structures/execution_outcome) result is a new Receipt with the refund to the initial sender, **alice.near**. +The Receipt is already on the receiver's Shard, so it is put in the execution queue of the next [Block](https://docs.near.org/develop/lake/structures/block). It is executed in the next Block, and the [ExecutionOutcome](https://docs.near.org/develop/lake/structures/execution-outcome) result is a new Receipt with the refund to the initial sender, **alice.near**. The Same rules apply to this Receipt, it is put into the execution queue and executed in the next Block. ![Complete scheme of Token transfer between the account from the same Shards](/docs/flow-token-transfer/02-same-shard-complete.png) diff --git a/docs/3.tutorials/indexer/nft-indexer.md b/docs/3.tutorials/indexer/nft-indexer.md index 97d0cff1044..774e48221b5 100644 --- a/docs/3.tutorials/indexer/nft-indexer.md +++ b/docs/3.tutorials/indexer/nft-indexer.md @@ -14,7 +14,7 @@ sidebar_label: NFT Indexer ## The End This tutorial ends with a working NFT indexer built on top [NEAR Lake Framework JS](https://near-indexers.io/docs/projects/near-lake-framework). The indexer is watching for `nft_mint` [Events](https://nomicon.io/Standards/EventsFormat) and prints some relevant data: -- `receiptId` of the [Receipt](https://near-indexers.io/docs/data-flow-and-structures/structures/receipt) where the mint has happened +- `receiptId` of the [Receipt](https://docs.near.org/develop/lake/structures/receipt) where the mint has happened - Marketplace - NFT owner account name - Links to the NFTs on the marketplaces @@ -23,7 +23,7 @@ The final source code is available on the GitHub [`near-examples/near-lake-nft-i ## Motivation -NEAR Protocol had introduced a nice feature [Events](https://nomicon.io/Standards/EventsFormat). The Events allow a contract developer to add standardized logs to the [`ExecutionOutcomes`](https://near-indexers.io/docs/data-flow-and-structures/structures/execution_outcome) thus allowing themselves or other developers to read those logs in more convenient manner via API or indexers. +NEAR Protocol had introduced a nice feature [Events](https://nomicon.io/Standards/EventsFormat). The Events allow a contract developer to add standardized logs to the [`ExecutionOutcomes`](https://docs.near.org/develop/lake/structures/execution-outcome) thus allowing themselves or other developers to read those logs in more convenient manner via API or indexers. The Events have a field `standard` which aligns with NEPs. In this tutorial we'll be talking about [NEP-171 Non-Fungible Token standard](https://github.com/near/NEPs/discussions/171). @@ -173,8 +173,8 @@ async function handleStreamerMessage( First of all let's find out where we can catch the Events. We hope you are familiar with how the [Data Flow in NEAR Blockchain](https://near-indexers.io/docs/data-flow-and-structures/flow/near-data-flow), but let's revise our knowledge: - Mint an NFT is an action in an NFT contract (doesn't matter which one) -- Actions are located in a [Receipt](https://near-indexers.io/docs/data-flow-and-structures/structures/receipt) -- A result of the Receipt execution is [ExecutionOutcome](https://near-indexers.io/docs/data-flow-and-structures/structures/execution_outcome) +- Actions are located in a [Receipt](https://docs.near.org/develop/lake/structures/receipt) +- A result of the Receipt execution is [ExecutionOutcome](https://docs.near.org/develop/lake/structures/execution-outcome) - `ExecutionOutcome` in turn, catches the logs a contract "prints" - [Events](https://nomicon.io/Standards/EventsFormat) built on top of the logs @@ -206,7 +206,7 @@ async function handleStreamerMessage( } ``` -We have iterated through all the [Shards](https://near-indexers.io/docs/data-flow-and-structures/structures/shard) and collected the lists of all ExecutionOutcomes into a single list (in our case we don't care on which Shard did the mint happen) +We have iterated through all the [Shards](https://docs.near.org/develop/lake/structures/shard) and collected the lists of all ExecutionOutcomes into a single list (in our case we don't care on which Shard did the mint happen) Now we want to deal only with those ExecutionOutcomes that contain logs of Events format. Such logs start with `EVENT_JSON:` according to the [Events docs](https://nomicon.io/Standards/EventsFormat#events). diff --git a/docs/3.tutorials/indexer/python-nft-indexer.md b/docs/3.tutorials/indexer/python-nft-indexer.md index bc5e42bed14..c98b783e612 100644 --- a/docs/3.tutorials/indexer/python-nft-indexer.md +++ b/docs/3.tutorials/indexer/python-nft-indexer.md @@ -14,7 +14,7 @@ sidebar_label: "NFT indexer for Python" ## The Goal This tutorial ends with a working NFT indexer built on top [NEAR Lake Framework for Python](https://near-indexers.io/docs/projects/near-lake-framework). The indexer is watching for `nft_mint` [Events](https://nomicon.io/Standards/EventsFormat) and prints some relevant data: -- `receipt_id` of the [Receipt](https://near-indexers.io/docs/data-flow-and-structures/structures/receipt) where the mint has happened +- `receipt_id` of the [Receipt](https://docs.near.org/develop/lake/structures/receipt) where the mint has happened - Marketplace - NFT owner account name - Links to the NFTs on the marketplaces @@ -23,7 +23,7 @@ The final source code is available on the GitHub [`frolvanya/near-lake-nft-index ## Motivation -NEAR Protocol had introduced a nice feature [Events](https://nomicon.io/Standards/EventsFormat). The Events allow a contract developer to add standardized logs to the [`ExecutionOutcomes`](https://near-indexers.io/docs/data-flow-and-structures/structures/execution_outcome) thus allowing themselves or other developers to read those logs in more convenient manner via API or indexers. +NEAR Protocol had introduced a nice feature [Events](https://nomicon.io/Standards/EventsFormat). The Events allow a contract developer to add standardized logs to the [`ExecutionOutcomes`](https://docs.near.org/develop/lake/structures/execution-outcome) thus allowing themselves or other developers to read those logs in more convenient manner via API or indexers. The Events have a field `standard` which aligns with NEPs. In this tutorial we'll be talking about [NEP-171 Non-Fungible Token standard](https://github.com/near/NEPs/discussions/171). @@ -122,8 +122,8 @@ async def handle_streamer_message(streamer_message: near_primitives.StreamerMess First of all let's find out where we can catch the Events. We hope you are familiar with how the [Data Flow in NEAR Blockchain](https://near-indexers.io/docs/data-flow-and-structures/flow/near-data-flow), but let's revise our knowledge: - Mint an NFT is an action in an NFT contract (doesn't matter which one) -- Actions are located in a [Receipt](https://near-indexers.io/docs/data-flow-and-structures/structures/receipt) -- A result of the Receipt execution is [ExecutionOutcome](https://near-indexers.io/docs/data-flow-and-structures/structures/execution_outcome) +- Actions are located in a [Receipt](https://docs.near.org/develop/lake/structures/receipt) +- A result of the Receipt execution is [ExecutionOutcome](https://docs.near.org/develop/lake/structures/execution-outcome) - `ExecutionOutcome` in turn, catches the logs a contract "prints" - [Events](https://nomicon.io/Standards/EventsFormat) built on top of the logs @@ -142,7 +142,7 @@ async def handle_streamer_message(streamer_message: near_primitives.StreamerMess pass ``` -We have iterated through the logs of all ExecutionOutcomes of [Shards](https://near-indexers.io/docs/data-flow-and-structures/structures/shard) (in our case we don't care on which Shard did the mint happen) +We have iterated through the logs of all ExecutionOutcomes of [Shards](https://docs.near.org/develop/lake/structures/shard) (in our case we don't care on which Shard did the mint happen) Now we want to deal only with those ExecutionOutcomes that contain logs of Events format. Such logs start with `EVENT_JSON:` according to the [Events docs](https://nomicon.io/Standards/EventsFormat#events). diff --git a/docs/bos/tutorial/indexer-tutorials/nft-indexer.md b/docs/bos/tutorial/indexer-tutorials/nft-indexer.md index 78422522296..23dc904efc1 100644 --- a/docs/bos/tutorial/indexer-tutorials/nft-indexer.md +++ b/docs/bos/tutorial/indexer-tutorials/nft-indexer.md @@ -16,7 +16,7 @@ You can request access through [this link](http://bit.ly/near-queryapi-beta). This tutorial creates a working NFT indexer using [NEAR QueryAPI](../../queryapi/intro.md), and builds a [NEAR component](../../../bos/tutorial/quickstart.md) that presents the data. The indexer is watching for `nft_mint` [Events](https://nomicon.io/Standards/EventsFormat) and captures some relevant data: -- `receiptId` of the [Receipt](https://near-indexers.io/docs/data-flow-and-structures/structures/receipt) where the mint has happened +- `receiptId` of the [Receipt](https://docs.near.org/develop/lake/structures/receipt) where the mint has happened - `receiverId` - Marketplace - Links to the transaction on NEAR Explorer @@ -31,7 +31,7 @@ The indexer's source code can be found by [following this link](https://near.org ### NFT Events -NEAR Protocol supports [Events](https://nomicon.io/Standards/EventsFormat). These `Events` allow a contract developer to add standardized logs to the [`ExecutionOutcomes`](https://near-indexers.io/docs/data-flow-and-structures/structures/execution_outcome) thus allowing themselves or other developers to read those logs in more convenient manner via API or indexers. Events have a field `standard` which aligns with NEPs. In this tutorial we'll be talking about [NEP-171 Non-Fungible Token standard](https://nomicon.io/Standards/Tokens/NonFungibleToken/Core). +NEAR Protocol supports [Events](https://nomicon.io/Standards/EventsFormat). These `Events` allow a contract developer to add standardized logs to the [`ExecutionOutcomes`](https://docs.near.org/develop/lake/structures/execution-outcome) thus allowing themselves or other developers to read those logs in more convenient manner via API or indexers. Events have a field `standard` which aligns with NEPs. In this tutorial we'll be talking about [NEP-171 Non-Fungible Token standard](https://nomicon.io/Standards/Tokens/NonFungibleToken/Core). The indexer watches all the NFTs minted following the [NEP-171 Events](https://nomicon.io/Standards/Tokens/NonFungibleToken/Event) standard. It should detect every single NFT minted, and store a basic set of data like: in what Receipt it was minted, and which marketplace created it (for example, [Paras](https://paras.id), [ShardDog](https://shard.dog), and [Mintbase](https://mintbase.io)).