Skip to content

Commit

Permalink
Fix links for Block, Chunk, ExecutionOutcome, Transaction, Shard, Rec…
Browse files Browse the repository at this point in the history
…eipt (#1856)

* Fix links for Block, Chunk, ExecutionOutcome, Transaction, Shard, Receipt

* Apply suggestions from code review

---------

Co-authored-by: Damián Parrino <bucanero@users.noreply.github.com>
  • Loading branch information
PolyProgrammist and bucanero authored Mar 29, 2024
1 parent 4b9cd88 commit d0dad11
Show file tree
Hide file tree
Showing 5 changed files with 31 additions and 31 deletions.
18 changes: 9 additions & 9 deletions docs/1.concepts/data-flow/near-data-flow.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.
20 changes: 10 additions & 10 deletions docs/1.concepts/data-flow/token-transfer-flow.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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)
Expand Down
10 changes: 5 additions & 5 deletions docs/3.tutorials/indexer/nft-indexer.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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).

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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).

Expand Down
Loading

0 comments on commit d0dad11

Please sign in to comment.