Skip to content

Update info on finalities #2514

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
May 12, 2025
Merged

Update info on finalities #2514

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b83676c
Update info on finalities
gagdiez Apr 8, 2025
0fa4ca3
Update docs/api/rpc/setup.md
gagdiez Apr 8, 2025
be27fce
added link to blog
gagdiez Apr 8, 2025
941557f
fix: added explanation
Apr 16, 2025
6623aa9
minor edits
Apr 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions docs/api/rpc/setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,14 @@ The block IDs of transactions shown in [NearBlocks Explorer](https://testnet.nea

## Using `finality` param {#using-finality-param}

The `finality` param has two options: `optimistic` and `final`.
1. `optimistic` uses the latest block recorded on the node that responded to your query _(< 1 second delay after the transaction is submitted)_
2. `final` is for a block that has been validated on at least 66% of the nodes in the network _(usually takes 2 blocks / approx. 2 second delay)_
The `finality` param has three options: `optimistic`, `near-final` and `final`:

1. `optimistic` the transaction is in a block that might be skipped _(< 1 second delay after the transaction is submitted)_
2. `near-final` the transaction is in a block that is irreversible, unless at least one block producer is slashed _(1 block / approx. 1 second delay)_
3. `final` the block is final and irreversible _(usually takes 2 blocks / approx. 2 second delay)_
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

optimistic still requires a block to be produced and broadcasted, so in the worst case if transaction landed right after the previous block was produced it will take 1 block to wait until the next block will start forming, then 1 block to get included+converted to receipt in the block (at this point, 2 "seconds" since submission, the transaction will be in an "optimistic" block), then 1 block to execute the receipt + N blocks for cross-account interaction (if needed), and so if someone is looking for "optimistic transaction execution result", they will see it in the block T+3, where T is the optimistic block height at the moment of transaction submission, the block with the transaction result will become "near-final" at T+4 timestamp, and the block will become "final" at T+5 timestamp.

Also, with nearcore 2.6.0 (released yesterday to testnet), the block production time was reduced to 0.6s, so the seconds reference might need to be adjusted accordingly (T+3 will become 1.8s instead of 3s)


:::info

The `near-final` finallity has enough guarantees for any normal operations, and thus should be preferred for most applications, you can learn more about it [in this official blog post](https://near.org/blog/doomslug-comparison)

:::
Loading