From 7ef6857395f4e68fcca1dea08e4e9e5077a44659 Mon Sep 17 00:00:00 2001
From: wacban <wac.banasik@gmail.com>
Date: Thu, 24 Oct 2024 12:04:05 +0100
Subject: [PATCH 01/30] template

---
 neps/nep-XXXX.md | 136 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 136 insertions(+)
 create mode 100644 neps/nep-XXXX.md

diff --git a/neps/nep-XXXX.md b/neps/nep-XXXX.md
new file mode 100644
index 000000000..47b65bdac
--- /dev/null
+++ b/neps/nep-XXXX.md
@@ -0,0 +1,136 @@
+---
+NEP: 0
+Title: NEP Template
+Authors: Todd Codrington III <satoshi@fakenews.org>
+Status: Approved
+DiscussionsTo: https://github.com/nearprotocol/neps/pull/0000
+Type: Developer Tools
+Version: 1.1.0
+Created: 2022-03-03
+LastUpdated: 2023-03-07
+---
+
+[This is a NEP (NEAR Enhancement Proposal) template, as described in [NEP-0001](https://github.com/near/NEPs/blob/master/neps/nep-0001.md). Use this when creating a new NEP. The author should delete or replace all the comments or commented brackets when merging their NEP.]
+
+<!-- NEP Header Preamble
+
+Each NEP must begin with an RFC 822 style header preamble. The headers must appear in the following order:
+
+NEP: The NEP title in no more than 4-5 words.
+
+Title: NEP title
+
+Author: List of author name(s) and optional contact info. Examples FirstName LastName <satoshi@fakenews.org>, FirstName LastName (@GitHubUserName)>
+
+Status: The NEP status -- New | Approved | Deprecated.
+
+DiscussionsTo (Optional): URL of current canonical discussion thread, e.g. GitHub Pull Request link.
+
+Type: The NEP type -- Protocol | Contract Standard | Wallet Standard | DevTools Standard.
+
+Requires (Optional): NEPs may have a Requires header, indicating the NEP numbers that this NEP depends on.
+
+Replaces (Optional): A newer NEP marked with a SupercededBy header must have a Replaces header containing the number of the NEP that it rendered obsolete.
+
+SupersededBy (Optional): NEPs may also have a SupersededBy header indicating that a NEP has been rendered obsolete by a later document; the value is the number of the NEP that replaces the current document.
+
+Version: The version number. A new NEP should start with 1.0.0, and future NEP Extensions must follow Semantic Versioning.
+
+Created: The Created header records the date that the NEP was assigned a number, should be in ISO 8601 yyyy-mm-dd format, e.g. 2022-12-31.
+
+LastUpdated: The Created header records the date that the NEP was assigned a number, should be in ISO 8601 yyyy-mm-dd format, e.g. 2022-12-31.
+
+See example above -->
+
+## Summary
+
+[Provide a short human-readable (~200 words) description of the proposal. A reader should get from this section a high-level understanding about the issue this NEP is addressing.]
+
+## Motivation
+
+[Explain why this proposal is necessary, how it will benefit the NEAR protocol or community, and what problems it solves. Also describe why the existing protocol specification is inadequate to address the problem that this NEP solves, and what potential use cases or outcomes.]
+
+## Specification
+
+[Explain the proposal as if you were teaching it to another developer. This generally means describing the syntax and semantics, naming new concepts, and providing clear examples. The specification needs to include sufficient detail to allow interoperable implementations getting built by following only the provided specification. In cases where it is infeasible to specify all implementation details upfront, broadly describe what they are.]
+
+## Reference Implementation
+
+[This technical section is required for Protocol proposals but optional for other categories. A draft implementation should demonstrate a minimal implementation that assists in understanding or implementing this proposal. Explain the design in sufficient detail that:
+
+* Its interaction with other features is clear.
+* Where possible, include a Minimum Viable Interface subsection expressing the required behavior and types in a target programming language. (ie. traits and structs for rust, interfaces and classes for javascript, function signatures and structs for c, etc.)
+* It is reasonably clear how the feature would be implemented.
+* Corner cases are dissected by example.
+* For protocol changes: A link to a draft PR on nearcore that shows how it can be integrated in the current code. It should at least solve the key technical challenges.
+
+The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work.]
+
+## Security Implications
+
+[Explicitly outline any security concerns in relation to the NEP, and potential ways to resolve or mitigate them. At the very least, well-known relevant threats must be covered, e.g. person-in-the-middle, double-spend, XSS, CSRF, etc.]
+
+## Alternatives
+
+[Explain any alternative designs that were considered and the rationale for not choosing them. Why your design is superior?]
+
+## Future possibilities
+
+[Describe any natural extensions and evolutions to the NEP proposal, and how they would impact the project. Use this section as a tool to help fully consider all possible interactions with the project in your proposal. This is also a good place to "dump ideas"; if they are out of scope for the NEP but otherwise related. Note that having something written down in the future-possibilities section is not a reason to accept the current or a future NEP. Such notes should be in the section on motivation or rationale in this or subsequent NEPs. The section merely provides additional information.]
+
+## Consequences
+
+[This section describes the consequences, after applying the decision. All consequences should be summarized here, not just the "positive" ones. Record any concerns raised throughout the NEP discussion.]
+
+### Positive
+
+* p1
+
+### Neutral
+
+* n1
+
+### Negative
+
+* n1
+
+### Backwards Compatibility
+
+[All NEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. Author must explain a proposes to deal with these incompatibilities. Submissions without a sufficient backwards compatibility treatise may be rejected outright.]
+
+## Unresolved Issues (Optional)
+
+[Explain any issues that warrant further discussion. Considerations
+
+* What parts of the design do you expect to resolve through the NEP process before this gets merged?
+* What parts of the design do you expect to resolve through the implementation of this feature before stabilization?
+* What related issues do you consider out of scope for this NEP that could be addressed in the future independently of the solution that comes out of this NEP?]
+
+## Changelog
+
+[The changelog section provides historical context for how the NEP developed over time. Initial NEP submission should start with version 1.0.0, and all subsequent NEP extensions must follow [Semantic Versioning](https://semver.org/). Every version should have the benefits and concerns raised during the review. The author does not need to fill out this section for the initial draft. Instead, the assigned reviewers (Subject Matter Experts) should create the first version during the first technical review. After the final public call, the author should then finalize the last version of the decision context.]
+
+### 1.0.0 - Initial Version
+
+> Placeholder for the context about when and who approved this NEP version.
+
+#### Benefits
+
+> List of benefits filled by the Subject Matter Experts while reviewing this version:
+
+* Benefit 1
+* Benefit 2
+
+#### Concerns
+
+> Template for Subject Matter Experts review for this version:
+> Status: New | Ongoing | Resolved
+
+|   # | Concern | Resolution | Status |
+| --: | :------ | :--------- | -----: |
+|   1 |         |            |        |
+|   2 |         |            |        |
+
+## Copyright
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

From 55bf0b3ec6a9ef06ecc9fc968567fcfdf5936123 Mon Sep 17 00:00:00 2001
From: wacban <wac.banasik@gmail.com>
Date: Thu, 24 Oct 2024 12:15:55 +0100
Subject: [PATCH 02/30] rename

---
 neps/{nep-XXXX.md => nep-0568.md} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename neps/{nep-XXXX.md => nep-0568.md} (100%)

diff --git a/neps/nep-XXXX.md b/neps/nep-0568.md
similarity index 100%
rename from neps/nep-XXXX.md
rename to neps/nep-0568.md

From 2ac4b05ed2638d0bb9eaed561d7e172cd925adf8 Mon Sep 17 00:00:00 2001
From: wacban <wac.banasik@gmail.com>
Date: Thu, 24 Oct 2024 12:16:32 +0100
Subject: [PATCH 03/30] metadata

---
 neps/nep-0568.md | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index 47b65bdac..ca95a2715 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -1,13 +1,13 @@
 ---
-NEP: 0
-Title: NEP Template
-Authors: Todd Codrington III <satoshi@fakenews.org>
-Status: Approved
-DiscussionsTo: https://github.com/nearprotocol/neps/pull/0000
-Type: Developer Tools
-Version: 1.1.0
-Created: 2022-03-03
-LastUpdated: 2023-03-07
+NEP: 568
+Title: Resharding V3
+Authors: Adam Chudas, Aleksandr Logunov, Andrea Spurio, Marcelo Diop-Gonzalez, Shreyan Gupta, Waclaw Banasik
+Status: Draft
+DiscussionsTo: https://github.com/near/nearcore/issues/11881
+Type: Protocol
+Version: 1.0.0
+Created: 2024-10-24
+LastUpdated: 2024-10-24
 ---
 
 [This is a NEP (NEAR Enhancement Proposal) template, as described in [NEP-0001](https://github.com/near/NEPs/blob/master/neps/nep-0001.md). Use this when creating a new NEP. The author should delete or replace all the comments or commented brackets when merging their NEP.]
@@ -126,10 +126,10 @@ The section should return to the examples given in the previous section, and exp
 > Template for Subject Matter Experts review for this version:
 > Status: New | Ongoing | Resolved
 
-|   # | Concern | Resolution | Status |
-| --: | :------ | :--------- | -----: |
-|   1 |         |            |        |
-|   2 |         |            |        |
+|    # | Concern | Resolution | Status |
+| ---: | :------ | :--------- | -----: |
+|    1 |         |            |        |
+|    2 |         |            |        |
 
 ## Copyright
 

From 5ef6b9db6d6e2f2e5cd6aec8806df7a1d74ff659 Mon Sep 17 00:00:00 2001
From: wacban <wac.banasik@gmail.com>
Date: Thu, 24 Oct 2024 12:42:19 +0100
Subject: [PATCH 04/30] summary

---
 neps/nep-0568.md | 52 +++++++++++++++++++-----------------------------
 1 file changed, 20 insertions(+), 32 deletions(-)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index ca95a2715..11535ebb2 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -2,7 +2,7 @@
 NEP: 568
 Title: Resharding V3
 Authors: Adam Chudas, Aleksandr Logunov, Andrea Spurio, Marcelo Diop-Gonzalez, Shreyan Gupta, Waclaw Banasik
-Status: Draft
+Status: New
 DiscussionsTo: https://github.com/near/nearcore/issues/11881
 Type: Protocol
 Version: 1.0.0
@@ -10,41 +10,23 @@ Created: 2024-10-24
 LastUpdated: 2024-10-24
 ---
 
-[This is a NEP (NEAR Enhancement Proposal) template, as described in [NEP-0001](https://github.com/near/NEPs/blob/master/neps/nep-0001.md). Use this when creating a new NEP. The author should delete or replace all the comments or commented brackets when merging their NEP.]
+## Summary 
 
-<!-- NEP Header Preamble
+Summary
 
-Each NEP must begin with an RFC 822 style header preamble. The headers must appear in the following order:
+This proposal introduces a new resharding implementation and shard layout for
+production networks.
 
-NEP: The NEP title in no more than 4-5 words.
+Resharding V3 is a significantly redesigned approach, addressing limitations of
+the previous versions, [Resharding V1][NEP-040] and [Resharding V2][NEP-508].
+The earlier solutions became obsolete due to major protocol changes since
+Resharding V2, including the introduction of Stateless Validation, Single Shard
+Tracking, and Mem-Trie.
 
-Title: NEP title
-
-Author: List of author name(s) and optional contact info. Examples FirstName LastName <satoshi@fakenews.org>, FirstName LastName (@GitHubUserName)>
-
-Status: The NEP status -- New | Approved | Deprecated.
-
-DiscussionsTo (Optional): URL of current canonical discussion thread, e.g. GitHub Pull Request link.
-
-Type: The NEP type -- Protocol | Contract Standard | Wallet Standard | DevTools Standard.
-
-Requires (Optional): NEPs may have a Requires header, indicating the NEP numbers that this NEP depends on.
-
-Replaces (Optional): A newer NEP marked with a SupercededBy header must have a Replaces header containing the number of the NEP that it rendered obsolete.
-
-SupersededBy (Optional): NEPs may also have a SupersededBy header indicating that a NEP has been rendered obsolete by a later document; the value is the number of the NEP that replaces the current document.
-
-Version: The version number. A new NEP should start with 1.0.0, and future NEP Extensions must follow Semantic Versioning.
-
-Created: The Created header records the date that the NEP was assigned a number, should be in ISO 8601 yyyy-mm-dd format, e.g. 2022-12-31.
-
-LastUpdated: The Created header records the date that the NEP was assigned a number, should be in ISO 8601 yyyy-mm-dd format, e.g. 2022-12-31.
-
-See example above -->
-
-## Summary
-
-[Provide a short human-readable (~200 words) description of the proposal. A reader should get from this section a high-level understanding about the issue this NEP is addressing.]
+The primary objective of Resharding V3 is to increase chain capacity by
+splitting overutilized shards. A secondary aim is to lay the groundwork for
+supporting Dynamic Resharding, Instant Resharding, and Shard Merging in future
+updates.
 
 ## Motivation
 
@@ -134,3 +116,9 @@ The section should return to the examples given in the previous section, and exp
 ## Copyright
 
 Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
+
+
+<!-- links --> 
+
+[NEP-040]: https://github.com/near/NEPs/blob/master/specs/Proposals/0040-split-states.md
+[NEP-508]: https://github.com/near/NEPs/blob/master/neps/nep-0508.md

From 62f127c7a516a5fcfb1ba7fe62df0eaa7733dbe7 Mon Sep 17 00:00:00 2001
From: wacban <wac.banasik@gmail.com>
Date: Thu, 24 Oct 2024 13:27:25 +0100
Subject: [PATCH 05/30] specification

---
 neps/nep-0568.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index 11535ebb2..310bdcbd4 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -36,6 +36,56 @@ updates.
 
 [Explain the proposal as if you were teaching it to another developer. This generally means describing the syntax and semantics, naming new concepts, and providing clear examples. The specification needs to include sufficient detail to allow interoperable implementations getting built by following only the provided specification. In cases where it is infeasible to specify all implementation details upfront, broadly describe what they are.]
 
+
+Resharding will be scheduled in advance by the NEAR developer team. The new
+shard layout will be hardcoded into the neard binary and linked to the protocol
+version. As the protocol upgrade progresses, resharding will be triggered during
+the post-processing phase of the last block of the epoch. At this point, the
+state of the parent shard will be split between two child shards. From the first
+block of the new protocol version onward, the chain will operate with the new
+shard layout.
+
+There are two key dimensions to consider: state storage and protocol features,
+along with a few additional details.
+
+1) State Storage: Currently, the state of a shard is stored in three distinct
+formats: the state, the flat state, and the mem-trie. Each of these
+representations must be resharded. Logically, resharding is an almost
+instantaneous event that occurs before the first block under the new shard
+layout. However, in practice, some of this work may be deferred to
+post-processing, as long as the chain's view reflects a fully resharded state.
+
+1) Protocol Features: Several protocol features must integrate smoothly with the
+  resharding process, including:
+* Stateless Validation: Resharding must be validated and proven through
+  stateless validation mechanisms.
+* State Sync: Nodes must be able to sync the states of the child
+  shards post-resharding.
+* Cross-Shard Traffic: Receipts sent to the parent shard may need to be
+  reassigned to one of the child shards.
+* Receipt Handling: Delayed, postponed, buffered, and promise-yield receipts
+  must be correctly distributed between the child shards.
+* ShardId Semantics: The shard identifiers will become abstract identifiers
+  where today they are number in the 0..num_shards range.
+
+### State Storage - Mem Trie
+
+### State Storage - Flat State
+
+### State Storage - State
+
+### Stateless Validation
+
+### State Sync
+
+### Cross Shard Traffic
+
+### Receipt Handling - Delayed, Postponed, PromiseYield
+
+### Receipt Handling - Buffered
+
+### ShardId Semantics
+
 ## Reference Implementation
 
 [This technical section is required for Protocol proposals but optional for other categories. A draft implementation should demonstrate a minimal implementation that assists in understanding or implementing this proposal. Explain the design in sufficient detail that:
@@ -60,6 +110,8 @@ The section should return to the examples given in the previous section, and exp
 
 [Describe any natural extensions and evolutions to the NEP proposal, and how they would impact the project. Use this section as a tool to help fully consider all possible interactions with the project in your proposal. This is also a good place to "dump ideas"; if they are out of scope for the NEP but otherwise related. Note that having something written down in the future-possibilities section is not a reason to accept the current or a future NEP. Such notes should be in the section on motivation or rationale in this or subsequent NEPs. The section merely provides additional information.]
 
+
+
 ## Consequences
 
 [This section describes the consequences, after applying the decision. All consequences should be summarized here, not just the "positive" ones. Record any concerns raised throughout the NEP discussion.]

From bec1ae6665c1d520bcd2e2f9f7a345daf6f0106d Mon Sep 17 00:00:00 2001
From: wacban <wac.banasik@gmail.com>
Date: Thu, 24 Oct 2024 13:42:43 +0100
Subject: [PATCH 06/30] formatting template texts

---
 neps/nep-0568.md | 27 +++++++++++++++++++++------
 1 file changed, 21 insertions(+), 6 deletions(-)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index 310bdcbd4..f11cb6bba 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -12,8 +12,6 @@ LastUpdated: 2024-10-24
 
 ## Summary 
 
-Summary
-
 This proposal introduces a new resharding implementation and shard layout for
 production networks.
 
@@ -25,17 +23,20 @@ Tracking, and Mem-Trie.
 
 The primary objective of Resharding V3 is to increase chain capacity by
 splitting overutilized shards. A secondary aim is to lay the groundwork for
-supporting Dynamic Resharding, Instant Resharding, and Shard Merging in future
+supporting Dynamic Resharding, Instant Resharding and Shard Merging in future
 updates.
 
 ## Motivation
 
+```
 [Explain why this proposal is necessary, how it will benefit the NEAR protocol or community, and what problems it solves. Also describe why the existing protocol specification is inadequate to address the problem that this NEP solves, and what potential use cases or outcomes.]
+```
 
 ## Specification
 
+```
 [Explain the proposal as if you were teaching it to another developer. This generally means describing the syntax and semantics, naming new concepts, and providing clear examples. The specification needs to include sufficient detail to allow interoperable implementations getting built by following only the provided specification. In cases where it is infeasible to specify all implementation details upfront, broadly describe what they are.]
-
+```
 
 Resharding will be scheduled in advance by the NEAR developer team. The new
 shard layout will be hardcoded into the neard binary and linked to the protocol
@@ -88,6 +89,7 @@ post-processing, as long as the chain's view reflects a fully resharded state.
 
 ## Reference Implementation
 
+```
 [This technical section is required for Protocol proposals but optional for other categories. A draft implementation should demonstrate a minimal implementation that assists in understanding or implementing this proposal. Explain the design in sufficient detail that:
 
 * Its interaction with other features is clear.
@@ -97,24 +99,31 @@ post-processing, as long as the chain's view reflects a fully resharded state.
 * For protocol changes: A link to a draft PR on nearcore that shows how it can be integrated in the current code. It should at least solve the key technical challenges.
 
 The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work.]
+```
 
 ## Security Implications
 
+```
 [Explicitly outline any security concerns in relation to the NEP, and potential ways to resolve or mitigate them. At the very least, well-known relevant threats must be covered, e.g. person-in-the-middle, double-spend, XSS, CSRF, etc.]
+```
 
 ## Alternatives
 
+```
 [Explain any alternative designs that were considered and the rationale for not choosing them. Why your design is superior?]
+```
 
 ## Future possibilities
 
+```
 [Describe any natural extensions and evolutions to the NEP proposal, and how they would impact the project. Use this section as a tool to help fully consider all possible interactions with the project in your proposal. This is also a good place to "dump ideas"; if they are out of scope for the NEP but otherwise related. Note that having something written down in the future-possibilities section is not a reason to accept the current or a future NEP. Such notes should be in the section on motivation or rationale in this or subsequent NEPs. The section merely provides additional information.]
-
-
+```
 
 ## Consequences
 
+```
 [This section describes the consequences, after applying the decision. All consequences should be summarized here, not just the "positive" ones. Record any concerns raised throughout the NEP discussion.]
+```
 
 ### Positive
 
@@ -130,19 +139,25 @@ The section should return to the examples given in the previous section, and exp
 
 ### Backwards Compatibility
 
+```
 [All NEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. Author must explain a proposes to deal with these incompatibilities. Submissions without a sufficient backwards compatibility treatise may be rejected outright.]
+```
 
 ## Unresolved Issues (Optional)
 
+```
 [Explain any issues that warrant further discussion. Considerations
 
 * What parts of the design do you expect to resolve through the NEP process before this gets merged?
 * What parts of the design do you expect to resolve through the implementation of this feature before stabilization?
 * What related issues do you consider out of scope for this NEP that could be addressed in the future independently of the solution that comes out of this NEP?]
+```
 
 ## Changelog
 
+```
 [The changelog section provides historical context for how the NEP developed over time. Initial NEP submission should start with version 1.0.0, and all subsequent NEP extensions must follow [Semantic Versioning](https://semver.org/). Every version should have the benefits and concerns raised during the review. The author does not need to fill out this section for the initial draft. Instead, the assigned reviewers (Subject Matter Experts) should create the first version during the first technical review. After the final public call, the author should then finalize the last version of the decision context.]
+```
 
 ### 1.0.0 - Initial Version
 

From d72d5096ac54cee832561e1057f27553ff6feee7 Mon Sep 17 00:00:00 2001
From: Waclaw Banasik <wacban@users.noreply.github.com>
Date: Mon, 28 Oct 2024 13:22:15 +0000
Subject: [PATCH 07/30] fix lints

---
 neps/nep-0568.md | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index f11cb6bba..e15fd8e9f 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -28,13 +28,13 @@ updates.
 
 ## Motivation
 
-```
+```text
 [Explain why this proposal is necessary, how it will benefit the NEAR protocol or community, and what problems it solves. Also describe why the existing protocol specification is inadequate to address the problem that this NEP solves, and what potential use cases or outcomes.]
 ```
 
 ## Specification
 
-```
+```text
 [Explain the proposal as if you were teaching it to another developer. This generally means describing the syntax and semantics, naming new concepts, and providing clear examples. The specification needs to include sufficient detail to allow interoperable implementations getting built by following only the provided specification. In cases where it is infeasible to specify all implementation details upfront, broadly describe what they are.]
 ```
 
@@ -89,7 +89,7 @@ post-processing, as long as the chain's view reflects a fully resharded state.
 
 ## Reference Implementation
 
-```
+```text
 [This technical section is required for Protocol proposals but optional for other categories. A draft implementation should demonstrate a minimal implementation that assists in understanding or implementing this proposal. Explain the design in sufficient detail that:
 
 * Its interaction with other features is clear.
@@ -103,25 +103,25 @@ The section should return to the examples given in the previous section, and exp
 
 ## Security Implications
 
-```
+```text
 [Explicitly outline any security concerns in relation to the NEP, and potential ways to resolve or mitigate them. At the very least, well-known relevant threats must be covered, e.g. person-in-the-middle, double-spend, XSS, CSRF, etc.]
 ```
 
 ## Alternatives
 
-```
+```text
 [Explain any alternative designs that were considered and the rationale for not choosing them. Why your design is superior?]
 ```
 
 ## Future possibilities
 
-```
+```text
 [Describe any natural extensions and evolutions to the NEP proposal, and how they would impact the project. Use this section as a tool to help fully consider all possible interactions with the project in your proposal. This is also a good place to "dump ideas"; if they are out of scope for the NEP but otherwise related. Note that having something written down in the future-possibilities section is not a reason to accept the current or a future NEP. Such notes should be in the section on motivation or rationale in this or subsequent NEPs. The section merely provides additional information.]
 ```
 
 ## Consequences
 
-```
+```text
 [This section describes the consequences, after applying the decision. All consequences should be summarized here, not just the "positive" ones. Record any concerns raised throughout the NEP discussion.]
 ```
 
@@ -139,13 +139,13 @@ The section should return to the examples given in the previous section, and exp
 
 ### Backwards Compatibility
 
-```
+```text
 [All NEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. Author must explain a proposes to deal with these incompatibilities. Submissions without a sufficient backwards compatibility treatise may be rejected outright.]
 ```
 
 ## Unresolved Issues (Optional)
 
-```
+```text
 [Explain any issues that warrant further discussion. Considerations
 
 * What parts of the design do you expect to resolve through the NEP process before this gets merged?
@@ -155,7 +155,7 @@ The section should return to the examples given in the previous section, and exp
 
 ## Changelog
 
-```
+```text
 [The changelog section provides historical context for how the NEP developed over time. Initial NEP submission should start with version 1.0.0, and all subsequent NEP extensions must follow [Semantic Versioning](https://semver.org/). Every version should have the benefits and concerns raised during the review. The author does not need to fill out this section for the initial draft. Instead, the assigned reviewers (Subject Matter Experts) should create the first version during the first technical review. After the final public call, the author should then finalize the last version of the decision context.]
 ```
 

From 47f22f9b3bf357c6936a8ba7c0698d19f8e5a9d5 Mon Sep 17 00:00:00 2001
From: Waclaw Banasik <wacban@users.noreply.github.com>
Date: Tue, 29 Oct 2024 10:29:09 +0000
Subject: [PATCH 08/30] Resharding V3 - added future possibilities (#569)

Filling in the future possibilities section - and looking for more ideas :)
---
 neps/nep-0568.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index e15fd8e9f..d4f9adfff 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -115,9 +115,9 @@ The section should return to the examples given in the previous section, and exp
 
 ## Future possibilities
 
-```text
-[Describe any natural extensions and evolutions to the NEP proposal, and how they would impact the project. Use this section as a tool to help fully consider all possible interactions with the project in your proposal. This is also a good place to "dump ideas"; if they are out of scope for the NEP but otherwise related. Note that having something written down in the future-possibilities section is not a reason to accept the current or a future NEP. Such notes should be in the section on motivation or rationale in this or subsequent NEPs. The section merely provides additional information.]
-```
+* Dynamic Resharding - In this proposal, resharding is scheduled in advance and hardcoded within the neard binary. In the future, we aim to enable the chain to dynamically trigger and execute resharding autonomously, allowing it to adjust capacity automatically based on demand.
+* Fast Dynamic Resharding - In the Dynamic Resharding extension, the new shard layout is configured for the second upcoming epoch. This means that a full epoch must pass before the chain transitions to the updated shard layout. In the future, our goal is to accelerate this process by finalizing the previous epoch more quickly, allowing the chain to adopt the new layout as soon as possible.
+* Shard Merging - In this proposal the only allowed resharding operation is shard splitting. In the future, we aim to enable shard merging, allowing underutilized shards to be combined with neighboring shards. This would allow the chain to free up resources and reallocate them where they are most needed.
 
 ## Consequences
 

From 8d8e761f6ea898e2a01802565eae77a5e5cbb091 Mon Sep 17 00:00:00 2001
From: Andrea <Trisfald@users.noreply.github.com>
Date: Tue, 29 Oct 2024 16:34:12 +0100
Subject: [PATCH 09/30] Add flat state specs to resharding NEP (#570)

Filling the specification section about flat state.
---
 neps/nep-0568.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index d4f9adfff..b04a336e4 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -73,6 +73,37 @@ post-processing, as long as the chain's view reflects a fully resharded state.
 
 ### State Storage - Flat State
 
+Flat State is a collection of key-value pairs stored on disk and each entry
+contains a reference to its ShardId. When splitting a shard, every item inside
+its Flat State must be correctly reassigned to either one of the new children;
+due to technical limitations such operation can't be completed instantaneously.
+
+Flat State main purposes are allowing the creation of State Sync snapshots and
+the construction of Mem Tries. Fortunately, these two operations can be delayed
+until resharding is completed. Note also that with Mem Tries enabled the chain
+can move forward even if the current status of Flat State is not in sync with
+the latest block. 
+
+For the reason stated above, the chosen strategy is to reshard Flat State in a
+long-running background task. The new shards' states must converge with their
+Mem Tries representation in a reasonable amount of time.
+
+Splitting a shard's Flat State is performed in multiple steps:
+1) A post-processing 'split' task is created during the last block of the old
+   shard layout, instantaneously. 
+2) The 'split' task runs in parallel with the chain for a certain amount of
+   time. Inside this routine every key-value pair belonging to the shard being
+   split (also called parent shard) is copied into either the left or the right
+   child Flat State. Entries linked to receipts are handled in a special way.
+3) Once the task is completed, the parent shard Flat State is cleaned up. The
+   children shards Flat States have their state in sync with last block of the
+   old shard layout.
+4) Children shards must apply the delta changes from the first block of the new
+   shard layout until the final block of the canonical chain. This operation is
+   done in another background task to avoid slowdowns while processing blocks.
+5) Children shards Flat States are now ready and can be used to take State Sync
+   snapshots and to reload Mem Tries.
+
 ### State Storage - State
 
 ### Stateless Validation

From 1ee5a74b24317defd53c3bbd0a1b881033fbc815 Mon Sep 17 00:00:00 2001
From: Waclaw Banasik <wacban@users.noreply.github.com>
Date: Tue, 29 Oct 2024 15:47:23 +0000
Subject: [PATCH 10/30] fix lints

---
 neps/nep-0568.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index b04a336e4..07ce68761 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -58,6 +58,7 @@ post-processing, as long as the chain's view reflects a fully resharded state.
 
 1) Protocol Features: Several protocol features must integrate smoothly with the
   resharding process, including:
+
 * Stateless Validation: Resharding must be validated and proven through
   stateless validation mechanisms.
 * State Sync: Nodes must be able to sync the states of the child
@@ -89,6 +90,7 @@ long-running background task. The new shards' states must converge with their
 Mem Tries representation in a reasonable amount of time.
 
 Splitting a shard's Flat State is performed in multiple steps:
+
 1) A post-processing 'split' task is created during the last block of the old
    shard layout, instantaneously. 
 2) The 'split' task runs in parallel with the chain for a certain amount of

From 6c984415ce0399429ae2f6bcc516acc901ce0220 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Adam=20Chuda=C5=9B?=
 <18039094+staffik@users.noreply.github.com>
Date: Wed, 6 Nov 2024 16:43:05 +0100
Subject: [PATCH 11/30] State Storage - State (#571)

---
 neps/nep-0568.md | 106 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index 07ce68761..b44878e81 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -107,6 +107,28 @@ Splitting a shard's Flat State is performed in multiple steps:
    snapshots and to reload Mem Tries.
 
 ### State Storage - State
+// TODO Describe integration with cold storage once design is ready
+
+Each shard’s Trie is stored in the `State` column of the database, with keys prefixed by `ShardUId`, followed by a node's hash.
+This structure uniquely identifies each shard’s data. To avoid copying all entries under a new `ShardUId` during resharding,
+a mapping strategy allows child shards to access ancestor shard data without directly creating new entries.
+
+A naive approach to resharding would involve copying all `State` entries with a new `ShardUId` for a child shard, effectively duplicating the state.
+This method, while straightforward, is not feasible because copying a large state would take too much time.
+Resharding needs to appear complete between two blocks, so a direct copy would not allow the process to occur quickly enough.
+
+To address this, Resharding V3 employs an efficient mapping strategy, using the `DBCol::ShardUIdMapping` column
+to link each child shard’s `ShardUId` to the closest ancestor’s `ShardUId` holding the relevant data.
+This allows child shards to access and update state data under the ancestor shard’s prefix without duplicating entries.
+
+Initially, `ShardUIdMapping` is empty, as existing shards map to themselves. During resharding, a mapping entry is added to `ShardUIdMapping`,
+pointing each child shard’s `ShardUId` to the appropriate ancestor. Mappings persist as long as any descendant shard references the ancestor’s data.
+Once a node stops tracking all children and descendants of a shard, the entry for that shard can be removed, allowing its data to be garbage collected.
+For archival nodes, mappings are retained indefinitely to maintain access to the full historical state.
+
+This mapping strategy enables efficient shard management during resharding events,
+supporting smooth transitions without altering storage structures directly.
+
 
 ### Stateless Validation
 
@@ -134,6 +156,90 @@ Splitting a shard's Flat State is performed in multiple steps:
 The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work.]
 ```
 
+### State Storage - State mapping
+
+To enable efficient shard state management during resharding, Resharding V3 uses the `DBCol::ShardUIdMapping` column.
+This mapping allows child shards to reference ancestor shard data, avoiding the need for immediate duplication of state entries. 
+
+#### Mapping application in adapters
+
+The core of the mapping logic is applied in `TrieStoreAdapter` and `TrieStoreUpdateAdapter`, which act as layers over the general `Store` interface.
+Here’s a breakdown of the key functions involved:
+
+- **Key resolution**:
+  The `get_key_from_shard_uid_and_hash` function is central to determining the correct `ShardUId` for state access.
+  At a high level, operations use the child shard's `ShardUId`, but within this function,
+  the `DBCol::ShardUIdMapping` column is checked to determine if an ancestor `ShardUId` should be used instead.
+
+  ```rust
+  fn get_key_from_shard_uid_and_hash(
+      store: &Store,
+      shard_uid: ShardUId,
+      hash: &CryptoHash,
+  ) -> [u8; 40] {
+      let mapped_shard_uid = store
+          .get_ser::<ShardUId>(DBCol::StateShardUIdMapping, &shard_uid.to_bytes())
+          .expect("get_key_from_shard_uid_and_hash() failed")
+          .unwrap_or(shard_uid);
+      let mut key = [0; 40];
+      key[0..8].copy_from_slice(&mapped_shard_uid.to_bytes());
+      key[8..].copy_from_slice(hash.as_ref());
+      key
+  }
+  ```
+
+  This function first attempts to retrieve a mapped ancestor `ShardUId` from `DBCol::ShardUIdMapping`.
+  If no mapping exists, it defaults to the provided child `ShardUId`.
+  This resolved `ShardUId` is then combined with the `node_hash` to form the final key used in `State` column operations.
+
+- **State access operations**:
+  The `TrieStoreAdapter` and `TrieStoreUpdateAdapter` use `get_key_from_shard_uid_and_hash` to correctly resolve the key for both reads and writes.
+  Example methods include:
+
+   ```rust
+   // In TrieStoreAdapter
+   pub fn get(&self, shard_uid: ShardUId, hash: &CryptoHash) -> Result<Arc<[u8]>, StorageError> {
+      let key = get_key_from_shard_uid_and_hash(self.store, shard_uid, hash);
+      self.store.get(DBCol::State, &key)
+   }
+
+   // In TrieStoreUpdateAdapter
+   pub fn increment_refcount_by(
+      &mut self,
+      shard_uid: ShardUId,
+      hash: &CryptoHash,
+      data: &[u8],
+      increment: NonZero<u32>,
+   ) {
+      let key = get_key_from_shard_uid_and_hash(self.store, shard_uid, hash);
+      self.store_update.increment_refcount_by(DBCol::State, key.as_ref(), data, increment);
+   }
+   ```
+  The `get` function retrieves data using the resolved `ShardUId` and key, while `increment_refcount_by` manages reference counts,
+  ensuring correct tracking even when accessing data under an ancestor shard.
+
+#### Mapping retention and cleanup
+
+Mappings in `DBCol::ShardUIdMapping` persist as long as any descendant relies on an ancestor’s data.
+To manage this, the `set_shard_uid_mapping` function in `TrieStoreUpdateAdapter` adds a new mapping during resharding:
+```rust
+fn set_shard_uid_mapping(&mut self, child_shard_uid: ShardUId, parent_shard_uid: ShardUId) {
+    self.store_update.set(
+        DBCol::StateShardUIdMapping,
+        child_shard_uid.to_bytes().as_ref(),
+        &borsh::to_vec(&parent_shard_uid).expect("Borsh serialize cannot fail"),
+    )
+}
+```
+
+When a node stops tracking all descendants of a shard, the associated mapping entry can be removed, allowing RocksDB to perform garbage collection.
+For archival nodes, mappings are retained permanently to ensure access to the historical state of all shards.
+
+This implementation ensures efficient and scalable shard state transitions,
+allowing child shards to use ancestor data without creating redundant entries.
+
+
+
 ## Security Implications
 
 ```text

From 08b18342bfb57cad6c83ab6d8f4046c03c1b6e34 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Adam=20Chuda=C5=9B?= <adam@chudas.net>
Date: Wed, 6 Nov 2024 16:45:07 +0100
Subject: [PATCH 12/30] fix lint

---
 neps/nep-0568.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index b44878e81..8a27a0c04 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -107,6 +107,7 @@ Splitting a shard's Flat State is performed in multiple steps:
    snapshots and to reload Mem Tries.
 
 ### State Storage - State
+
 // TODO Describe integration with cold storage once design is ready
 
 Each shard’s Trie is stored in the `State` column of the database, with keys prefixed by `ShardUId`, followed by a node's hash.
@@ -238,8 +239,6 @@ For archival nodes, mappings are retained permanently to ensure access to the hi
 This implementation ensures efficient and scalable shard state transitions,
 allowing child shards to use ancestor data without creating redundant entries.
 
-
-
 ## Security Implications
 
 ```text

From 6e431ff588f9fce53a4255c8959dbe5865398b45 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Adam=20Chuda=C5=9B?= <adam@chudas.net>
Date: Wed, 6 Nov 2024 16:55:21 +0100
Subject: [PATCH 13/30] fix lint

---
 neps/nep-0568.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index 8a27a0c04..285d3524c 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -167,7 +167,7 @@ This mapping allows child shards to reference ancestor shard data, avoiding the
 The core of the mapping logic is applied in `TrieStoreAdapter` and `TrieStoreUpdateAdapter`, which act as layers over the general `Store` interface.
 Here’s a breakdown of the key functions involved:
 
-- **Key resolution**:
+* **Key resolution**:
   The `get_key_from_shard_uid_and_hash` function is central to determining the correct `ShardUId` for state access.
   At a high level, operations use the child shard's `ShardUId`, but within this function,
   the `DBCol::ShardUIdMapping` column is checked to determine if an ancestor `ShardUId` should be used instead.
@@ -193,7 +193,7 @@ Here’s a breakdown of the key functions involved:
   If no mapping exists, it defaults to the provided child `ShardUId`.
   This resolved `ShardUId` is then combined with the `node_hash` to form the final key used in `State` column operations.
 
-- **State access operations**:
+* **State access operations**:
   The `TrieStoreAdapter` and `TrieStoreUpdateAdapter` use `get_key_from_shard_uid_and_hash` to correctly resolve the key for both reads and writes.
   Example methods include:
 
@@ -216,6 +216,7 @@ Here’s a breakdown of the key functions involved:
       self.store_update.increment_refcount_by(DBCol::State, key.as_ref(), data, increment);
    }
    ```
+
   The `get` function retrieves data using the resolved `ShardUId` and key, while `increment_refcount_by` manages reference counts,
   ensuring correct tracking even when accessing data under an ancestor shard.
 
@@ -223,6 +224,7 @@ Here’s a breakdown of the key functions involved:
 
 Mappings in `DBCol::ShardUIdMapping` persist as long as any descendant relies on an ancestor’s data.
 To manage this, the `set_shard_uid_mapping` function in `TrieStoreUpdateAdapter` adds a new mapping during resharding:
+
 ```rust
 fn set_shard_uid_mapping(&mut self, child_shard_uid: ShardUId, parent_shard_uid: ShardUId) {
     self.store_update.set(

From 5368857ee874d82038ba5d406529e191a8dac2f9 Mon Sep 17 00:00:00 2001
From: Waclaw Banasik <wacban@users.noreply.github.com>
Date: Thu, 7 Nov 2024 11:28:08 +0000
Subject: [PATCH 14/30] ShardId Semantics (#572)

---
 neps/nep-0568.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index 285d3524c..98615acf0 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -143,6 +143,10 @@ supporting smooth transitions without altering storage structures directly.
 
 ### ShardId Semantics
 
+Currently, shard IDs are represented as numbers within the range `[0,n)`, where n is the total number of shards. These shard IDs are sorted in the same order as the account ID ranges assigned to them. While this approach is straightforward, it complicates resharding operations, particularly when splitting a shard in the middle of the range. Such a split requires reindexing all subsequent shards with higher IDs, adding complexity to the process.
+
+In this NEP, we propose updating the ShardId semantics to allow for arbitrary identifiers. Although ShardIds will remain integers, they will no longer be restricted to the `[0,n)` range, and they may appear in any order. The only requirement is that each ShardId must be unique. In practice, during resharding, the ID of a parent shard will be removed from the ShardLayout, and the new child shards will be assigned unique IDs - `max(shard_ids)+1` and `max(shard_ids)+2`.
+
 ## Reference Implementation
 
 ```text

From a7bbee7b091abe192467cc4b1fe784e8fbf18a18 Mon Sep 17 00:00:00 2001
From: Shreyan Gupta <shreyan.gupta96@gmail.com>
Date: Thu, 14 Nov 2024 22:04:09 +0530
Subject: [PATCH 15/30] ReshardingV3 memtrie (#574)

Adding memtrie section to resharding
---
 neps/assets/nep-0568/NEP-HybridMemTrie.png | Bin 0 -> 20185 bytes
 neps/assets/nep-0568/NEP-SplitState.png    | Bin 0 -> 81729 bytes
 neps/nep-0568.md                           |  65 +++++++++++++++++++--
 3 files changed, 61 insertions(+), 4 deletions(-)
 create mode 100644 neps/assets/nep-0568/NEP-HybridMemTrie.png
 create mode 100644 neps/assets/nep-0568/NEP-SplitState.png

diff --git a/neps/assets/nep-0568/NEP-HybridMemTrie.png b/neps/assets/nep-0568/NEP-HybridMemTrie.png
new file mode 100644
index 0000000000000000000000000000000000000000..013c761f8a6722a96c6a34686d9c73f017e3c6f2
GIT binary patch
literal 20185
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
PvQFm$DafDamr(pKQO?#D

literal 0
HcmV?d00001

diff --git a/neps/assets/nep-0568/NEP-SplitState.png b/neps/assets/nep-0568/NEP-SplitState.png
new file mode 100644
index 0000000000000000000000000000000000000000..a160a5949b648e3dd00eeecc3d9f834f0b23f068
GIT binary patch
literal 81729
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

literal 0
HcmV?d00001

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index 98615acf0..9f536e9bc 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -69,8 +69,41 @@ post-processing, as long as the chain's view reflects a fully resharded state.
   must be correctly distributed between the child shards.
 * ShardId Semantics: The shard identifiers will become abstract identifiers
   where today they are number in the 0..num_shards range.
+* Congestion Info: CongestionInfo in the chunk header would be recalculated for the child
+  shards at the resharding boundary. Proof must be compatible with Stateless Validation.
 
-### State Storage - Mem Trie
+### State Storage - MemTrie
+
+MemTrie is the in-memory representation of the trie that the runtime uses for all trie accesses. This is kept in sync with the Trie representation in state.
+
+As of today it isn't mandatory for nodes to have MemTrie feature enabled but going forward, with ReshardingV3, all nodes would require to have MemTrie enabled for resharding to happen successfully.
+
+For the purposes of resharding, we need an efficient way to split the MemTrie into two child tries based on the boundary account. This splitting happens at the epoch boundary when the new epoch is expected to have the two child shards. The set of requirements around MemTrie splitting are:
+* MemTrie splitting needs to be "instant", i.e. happen efficiently within the span of one block. The child tries need to be available for the processing of the next block in the new epoch.
+* MemTrie splitting needs to be compatible with stateless validation, i.e. we need to generate a proof that the memtrie split proposed by the chunk producer is correct.
+* The proof generated for splitting the MemTrie needs to be compatible with the limits of the size of state witness that we send to all chunk validators. This prevents us from doing things like iterating through all trie keys for delayed receipts etc.
+
+With ReshardingV3 design, there's no protocol change to the structure of MemTries, however the implementation constraints required us to introduce the concept of a Frozen MemTrie. More details are in the [implementation](#state-storage---memtrie-1) section below.
+
+Based on the requirements above, we came up with an algorithm to efficiently split the parent trie into two child tries. Trie entries can be divided into three categories based on whether the trie keys have an `account_id` prefix and based on the total number of such trie keys. Splitting of these keys is handled in different ways.
+
+#### TrieKey with AccountID prefix
+
+This category includes most of the trie keys like `TrieKey::Account`, `TrieKey::ContractCode`, `TrieKey::PostponedReceipt`, etc. For these keys, we can efficiently split the trie based on the boundary account trie key. Note that we only need to read all the intermediate nodes that form a part of the split key. In the example below, if "pass" is the split key, we access all the nodes along the path of `root` -> `p` -> `a` -> `s` -> `s`, while not needing to touch any of the other intermediate nodes like `o` -> `s` -> `t` in key "post". The accessed nodes form a part of the state witness as those are the only nodes that the validators would need to verify that the resharding split is correct. This limits the size of the witness to effectively O(depth) of trie for each trie key in this category.
+
+![Splitting Trie diagram](assets/nep-0568/NEP-SplitState.png)
+
+#### Singleton TrieKey
+
+This category includes the trie keys `TrieKey::DelayedReceiptIndices`, `TrieKey::PromiseYieldIndices`, `TrieKey::BufferedReceiptIndices`. Notably, these are just a single entry (or O(num_shard) entries) in the trie and hence are small enough to read and modify for the children tries efficiently.
+
+#### Indexed TrieKey
+
+This category includes the trie keys `TrieKey::DelayedReceipt`, `TrieKey::PromiseYieldTimeout` and `TrieKey::BufferedReceipt`. The number of entries for these keys can potentially be arbitrarily large and it's not feasible to iterate through all the entries. In pre-stateless validation world, where we didn't care about state witness size limits, for ReshardingV2 we could just iterate over all delayed receipts and split them into the respective child shards.
+
+For ReshardingV3, these are handled by either of the two strategies
+- `TrieKey::DelayedReceipt` and `TrieKey::PromiseYieldTimeout` are handled by duplicating entries across both child shards as each entry could belong to either of the child shards. More details in the [Delayed Receipts](#delayed-receipt-handling) and [Promise Yield](#promiseyield-receipt-handling) sections below.
+- `TrieKey::BufferedReceipt` are independent of the account_id and therefore can be sent to either of the child shards, but not both. We copy the buffered receipts and the associated metadata to the child shard with the lower index. More details in the [Buffered Receipts](#buffered-receipt-handling) section below.
 
 ### State Storage - Flat State
 
@@ -137,9 +170,9 @@ supporting smooth transitions without altering storage structures directly.
 
 ### Cross Shard Traffic
 
-### Receipt Handling - Delayed, Postponed, PromiseYield
-
-### Receipt Handling - Buffered
+### Delayed Receipt Handling
+### PromiseYield Receipt Handling
+### Buffered Receipt Handling
 
 ### ShardId Semantics
 
@@ -160,6 +193,30 @@ In this NEP, we propose updating the ShardId semantics to allow for arbitrary id
 
 The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work.]
 ```
+### State Storage - MemTrie
+
+The current implementation of MemTrie uses a pool of memory (`STArena`) to allocate and deallocate nodes and internal pointers in this pool to reference child nodes. MemTries, unlike the State representation of Trie, do not work with the hash of the nodes but internal memory pointers directly. Additionally, MemTries are not thread safe and one MemTrie exists per shard.
+
+As described in [MemTrie](#state-storage---memtrie) section above, we need an efficient way to split the MemTrie into two child MemTries within a span of 1 block. What makes this challenging is that the current implementation of MemTrie is not thread safe and can not be shared across two shards.
+
+The naive way to create two MemTries for the child shards would be to iterate through all the entries of the parent MemTrie and fill in these values into the child MemTries. This however is prohibitively time consuming.
+
+The solution to this problem was to introduce the concept of Frozen MemTrie (with a `FrozenArena`) which is a cloneable, read-only, thread-safe snapshot of a MemTrie. We can call the `freeze` method on an existing MemTrie that converts it into a Frozen MemTrie. Note that this process consumes the original MemTrie and we can no longer allocate and deallocate nodes to it.
+
+Along with `FrozenArena`, we also introduce a `HybridArena` which is effectively a base made of `FrozenArena` with a top layer of `STArena` where we support allocating and deallocating new nodes into the MemTrie. Newly allocated nodes can reference/point to nodes in the `FrozenArena`. We use this Hybrid MemTrie as a temporary MemTrie while the flat storage is being constructed in the background.
+
+While Frozen MemTries provide the benefits of being compatible with instant resharding, they come at the cost of memory consumption. Once a MemTrie is frozen, since it doesn't support deallocation of memory, it continues to consume as much memory as it did at the time of freezing. In case a node is tracking only one of the child shards, a Frozen MemTrie would continue to use the same amount of memory as the parent trie. Due to this, Hybrid MemTries are only a temporary solution and we rebuild the MemTrie for the children once the post-processing step for Flat Storage is completed.
+
+Additionally, a node would have to support 2x the memory footprint of a single trie as after resharding, we would have two copies of the trie in memory, one from the temporary Hybrid MemTrie in use for block production, and other from the background MemTrie that would be under construction. Once the background MemTrie is fully constructed and caught up with the latest block, we do an in-place swap of the Hybrid MemTrie with the new child MemTrie and deallocate the memory from the Hybrid MemTrie.
+
+During a resharding event, at the boundary of the epoch, when we need to split the parent shard into the two child shards, we do the following steps:
+1. Freeze the parent MemTrie arena to create a read-only frozen arena that represents a snapshot of the state as of the time of freezing, i.e. after postprocessing last block of epoch. Note that we no longer require the parent MemTrie in runtime going forward.
+2. We cheaply clone the Frozen MemTrie for both the child MemTries to use. Note that this doesn't clone the parent arena memory, but just increases the refcount.
+3. We then create a new MemTrie with HybridArena for each of the children. The base of the MemTrie is the read-only FrozenArena while all new node allocations happens on a dedicated STArena memory pool for each child MemTrie. This is the temporary MemTrie that we use while Flat Storage is being built in the background.
+4. Once the Flat Storage is constructed in the post processing step of resharding, we use that to load a new MemTrie and catchup to the latest block.
+5. After the new child MemTrie has caught up to the latest block, we do an in-place swap in Client and discard the Hybrid MemTrie.
+
+![Hybrid MemTrie diagram](assets/nep-0568/NEP-HybridMemTrie.png)
 
 ### State Storage - State mapping
 

From 65ece27c2a0e95398aa367fc5783991b078b6973 Mon Sep 17 00:00:00 2001
From: Shreyan Gupta <shreyan.gupta96@gmail.com>
Date: Fri, 15 Nov 2024 00:10:29 +0530
Subject: [PATCH 16/30] lint

---
 neps/nep-0568.md | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index 9f536e9bc..7627a75d4 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -79,6 +79,7 @@ MemTrie is the in-memory representation of the trie that the runtime uses for al
 As of today it isn't mandatory for nodes to have MemTrie feature enabled but going forward, with ReshardingV3, all nodes would require to have MemTrie enabled for resharding to happen successfully.
 
 For the purposes of resharding, we need an efficient way to split the MemTrie into two child tries based on the boundary account. This splitting happens at the epoch boundary when the new epoch is expected to have the two child shards. The set of requirements around MemTrie splitting are:
+
 * MemTrie splitting needs to be "instant", i.e. happen efficiently within the span of one block. The child tries need to be available for the processing of the next block in the new epoch.
 * MemTrie splitting needs to be compatible with stateless validation, i.e. we need to generate a proof that the memtrie split proposed by the chunk producer is correct.
 * The proof generated for splitting the MemTrie needs to be compatible with the limits of the size of state witness that we send to all chunk validators. This prevents us from doing things like iterating through all trie keys for delayed receipts etc.
@@ -102,8 +103,10 @@ This category includes the trie keys `TrieKey::DelayedReceiptIndices`, `TrieKey:
 This category includes the trie keys `TrieKey::DelayedReceipt`, `TrieKey::PromiseYieldTimeout` and `TrieKey::BufferedReceipt`. The number of entries for these keys can potentially be arbitrarily large and it's not feasible to iterate through all the entries. In pre-stateless validation world, where we didn't care about state witness size limits, for ReshardingV2 we could just iterate over all delayed receipts and split them into the respective child shards.
 
 For ReshardingV3, these are handled by either of the two strategies
-- `TrieKey::DelayedReceipt` and `TrieKey::PromiseYieldTimeout` are handled by duplicating entries across both child shards as each entry could belong to either of the child shards. More details in the [Delayed Receipts](#delayed-receipt-handling) and [Promise Yield](#promiseyield-receipt-handling) sections below.
-- `TrieKey::BufferedReceipt` are independent of the account_id and therefore can be sent to either of the child shards, but not both. We copy the buffered receipts and the associated metadata to the child shard with the lower index. More details in the [Buffered Receipts](#buffered-receipt-handling) section below.
+
+* `TrieKey::DelayedReceipt` and `TrieKey::PromiseYieldTimeout` are handled by duplicating entries across both child shards as each entry could belong to either of the child shards. More details in the [Delayed Receipts](#delayed-receipt-handling) and [Promise Yield](#promiseyield-receipt-handling) sections below.
+
+* `TrieKey::BufferedReceipt` are independent of the account_id and therefore can be sent to either of the child shards, but not both. We copy the buffered receipts and the associated metadata to the child shard with the lower index. More details in the [Buffered Receipts](#buffered-receipt-handling) section below.
 
 ### State Storage - Flat State
 
@@ -171,7 +174,9 @@ supporting smooth transitions without altering storage structures directly.
 ### Cross Shard Traffic
 
 ### Delayed Receipt Handling
+
 ### PromiseYield Receipt Handling
+
 ### Buffered Receipt Handling
 
 ### ShardId Semantics
@@ -193,6 +198,7 @@ In this NEP, we propose updating the ShardId semantics to allow for arbitrary id
 
 The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work.]
 ```
+
 ### State Storage - MemTrie
 
 The current implementation of MemTrie uses a pool of memory (`STArena`) to allocate and deallocate nodes and internal pointers in this pool to reference child nodes. MemTries, unlike the State representation of Trie, do not work with the hash of the nodes but internal memory pointers directly. Additionally, MemTries are not thread safe and one MemTrie exists per shard.
@@ -210,6 +216,7 @@ While Frozen MemTries provide the benefits of being compatible with instant resh
 Additionally, a node would have to support 2x the memory footprint of a single trie as after resharding, we would have two copies of the trie in memory, one from the temporary Hybrid MemTrie in use for block production, and other from the background MemTrie that would be under construction. Once the background MemTrie is fully constructed and caught up with the latest block, we do an in-place swap of the Hybrid MemTrie with the new child MemTrie and deallocate the memory from the Hybrid MemTrie.
 
 During a resharding event, at the boundary of the epoch, when we need to split the parent shard into the two child shards, we do the following steps:
+
 1. Freeze the parent MemTrie arena to create a read-only frozen arena that represents a snapshot of the state as of the time of freezing, i.e. after postprocessing last block of epoch. Note that we no longer require the parent MemTrie in runtime going forward.
 2. We cheaply clone the Frozen MemTrie for both the child MemTries to use. Note that this doesn't clone the parent arena memory, but just increases the refcount.
 3. We then create a new MemTrie with HybridArena for each of the children. The base of the MemTrie is the read-only FrozenArena while all new node allocations happens on a dedicated STArena memory pool for each child MemTrie. This is the temporary MemTrie that we use while Flat Storage is being built in the background.

From 615a92f3e4f7b05e74762f587ccb889398b40874 Mon Sep 17 00:00:00 2001
From: Andrea <Trisfald@users.noreply.github.com>
Date: Fri, 15 Nov 2024 15:54:34 +0100
Subject: [PATCH 17/30] Add reference implementation for Flat state to
 resharding NEP (#575)

---
 neps/nep-0568.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index 7627a75d4..720c165c9 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -225,6 +225,91 @@ During a resharding event, at the boundary of the epoch, when we need to split t
 
 ![Hybrid MemTrie diagram](assets/nep-0568/NEP-HybridMemTrie.png)
 
+### State Storage - Flat State
+
+Resharding Flat State is a time consuming operation and it runs in parallel with block processing for several block heights.
+Thus, there are a few important aspects to consider during implementation:
+- Flat State's own status should be resilient to application crashes.
+- The parent shard's Flat State should be split at the correct block height.
+- New shards' Flat States should eventually converge to same representation the chain is using to process blocks (MemTries).
+- Resharding should work correctly in the presence of chain forks.
+- Retired shards are cleaned up.
+
+Note that the Flat States of the newly created shards won't be available until resharding is completed. This is fine because the temporary MemTries are
+built instantly and they can satisfy all block processing needs.
+
+The main component responsible to carry out resharding on Flat State is the [FlatStorageResharder](https://github.com/near/nearcore/blob/f4e9dd5d6e07089dfc789221ded8ec83bfe5f6e8/chain/chain/src/flat_storage_resharder.rs#L68).
+
+#### Flat State's status persistence
+Every shard Flat State has a status associated to it and stored in the database, called `FlatStorageStatus`. We propose to extend the existing object
+by adding the new enum variant named `FlatStorageStatus::Resharding`. This approach has two benefits. First, the progress of any Flat State resharding is
+persisted to disk, which makes the operation resilient to a node crash or restart. Second, resuming resharding on node restart shares the same code path as Flat
+State creation (see `FlatStorageShardCreator`), reducing the code duplication factor.
+
+`FlatStorageStatus` is updated at every committable step of resharding. The commit points are the following:
+- Beginning of resharding or, in other words, the last block of the old shard layout.
+- Scheduling of the _"split parent shard"_ task.
+- Execution, cancellation or failure of the _"split parent shard"_ task.
+- Execution or failure of any _"child catchup"_ task.
+
+#### Splitting a shard Flat State
+
+When, at the end of an epoch, the shard layout changes we identify a so called _resharding block_ that corresponds to the last block of the current epoch.
+A task to split the parent shard's Flat State is scheduled to happen after the _resharding block_ becomes final. The reason to wait for the finality condition
+is to avoid a split on a block that might be excluded from the canonical chain; needless to say, such situation would lock the node
+into an erroneous state.
+
+Inside the split task we iterate over the Flat State and copy each element into either child. This routine is performed in batches in order to lessen the performance 
+impact on the node.
+
+Finally, if the split completes successfully, the parent shard Flat State is removed from the database and the children Flat States enter a catch-up phase.
+
+One current technical limitation is that, upon a node crash or restart, the _"split parent shard"_ task will start copying all elements again from the beginning.
+
+A reference implementation of splitting a Flat State can be found in [FlatStorageResharder::split_shard_task](https://github.com/near/nearcore/blob/fecce019f0355cf89b63b066ca206a3cdbbdffff/chain/chain/src/flat_storage_resharder.rs#L295).
+
+#### Values assignment from parent to child shards
+Key-value pairs in the parent shard Flat State are inherited by children according to the rules stated below.
+
+Elements inherited by the child shard which tracks the `account_id` contained in the key:
+- `ACCOUNT`
+- `CONTRACT_DATA`
+- `CONTRACT_CODE`
+- `ACCESS_KEY`
+- `RECEIVED_DATA`
+- `POSTPONED_RECEIPT_ID`
+- `PENDING_DATA_COUNT`
+- `POSTPONED_RECEIPT`
+- `PROMISE_YIELD_RECEIPT`
+
+Elements inherited by both children:
+- `DELAYED_RECEIPT_OR_INDICES`
+- `PROMISE_YIELD_INDICES`
+- `PROMISE_YIELD_TIMEOUT`
+- `BANDWIDTH_SCHEDULER_STATE`
+
+Elements inherited only be the lowest index child:
+- `BUFFERED_RECEIPT_INDICES `
+- `BUFFERED_RECEIPT`
+
+#### Bring children shards up to date with the chain's head
+Children shards' Flat States build a complete view of their content at the height of the `resharding block` sometime during the new epoch 
+after resharding. At that point in time many new blocks have been processed already, and these will most likely contain updates for the new shards. A catch-up step is necessary to apply all Flat State deltas accumulated until now.
+
+This phase of resharding doesn't have to take extra steps to handle chain forks. On one hand, the catch-up task doesn't start until the parent shard 
+splitting is done, and at such point we know the `resharding block` is final; on the other hand, Flat State deltas are capable of handling forks automatically.
+
+The catch-up task commits to the database "batches" of Flat State deltas. If the application crashes or restarts the task will resume from where it left.
+
+Once all Flat State deltas are applied, the child shard's status is changed to `Ready` and clean up of Flat State deltas leftovers is performed. 
+
+A reference implementation of the catch-up task can be found in [FlatStorageResharder::shard_catchup_task](https://github.com/near/nearcore/blob/fecce019f0355cf89b63b066ca206a3cdbbdffff/chain/chain/src/flat_storage_resharder.rs#L564).
+
+#### Failure of Flat State resharding
+
+In the current proposal any failure during Flat State resharding is considered non-recoverable. 
+`neard` will attempt resharding again on restart, but no automatic recovery is implemented.
+
 ### State Storage - State mapping
 
 To enable efficient shard state management during resharding, Resharding V3 uses the `DBCol::ShardUIdMapping` column.

From e488308046352d6451f926ee8fe0bb6076979484 Mon Sep 17 00:00:00 2001
From: Trisfald <trisfald@gmail.com>
Date: Fri, 15 Nov 2024 16:08:16 +0100
Subject: [PATCH 18/30] fix lint

---
 neps/nep-0568.md | 56 +++++++++++++++++++++++++++---------------------
 1 file changed, 32 insertions(+), 24 deletions(-)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index 720c165c9..04aacf072 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -229,11 +229,12 @@ During a resharding event, at the boundary of the epoch, when we need to split t
 
 Resharding Flat State is a time consuming operation and it runs in parallel with block processing for several block heights.
 Thus, there are a few important aspects to consider during implementation:
-- Flat State's own status should be resilient to application crashes.
-- The parent shard's Flat State should be split at the correct block height.
-- New shards' Flat States should eventually converge to same representation the chain is using to process blocks (MemTries).
-- Resharding should work correctly in the presence of chain forks.
-- Retired shards are cleaned up.
+
+* Flat State's own status should be resilient to application crashes.
+* The parent shard's Flat State should be split at the correct block height.
+* New shards' Flat States should eventually converge to same representation the chain is using to process blocks (MemTries).
+* Resharding should work correctly in the presence of chain forks.
+* Retired shards are cleaned up.
 
 Note that the Flat States of the newly created shards won't be available until resharding is completed. This is fine because the temporary MemTries are
 built instantly and they can satisfy all block processing needs.
@@ -241,16 +242,18 @@ built instantly and they can satisfy all block processing needs.
 The main component responsible to carry out resharding on Flat State is the [FlatStorageResharder](https://github.com/near/nearcore/blob/f4e9dd5d6e07089dfc789221ded8ec83bfe5f6e8/chain/chain/src/flat_storage_resharder.rs#L68).
 
 #### Flat State's status persistence
+
 Every shard Flat State has a status associated to it and stored in the database, called `FlatStorageStatus`. We propose to extend the existing object
 by adding the new enum variant named `FlatStorageStatus::Resharding`. This approach has two benefits. First, the progress of any Flat State resharding is
 persisted to disk, which makes the operation resilient to a node crash or restart. Second, resuming resharding on node restart shares the same code path as Flat
 State creation (see `FlatStorageShardCreator`), reducing the code duplication factor.
 
 `FlatStorageStatus` is updated at every committable step of resharding. The commit points are the following:
-- Beginning of resharding or, in other words, the last block of the old shard layout.
-- Scheduling of the _"split parent shard"_ task.
-- Execution, cancellation or failure of the _"split parent shard"_ task.
-- Execution or failure of any _"child catchup"_ task.
+
+* Beginning of resharding or, in other words, the last block of the old shard layout.
+* Scheduling of the _"split parent shard"_ task.
+* Execution, cancellation or failure of the _"split parent shard"_ task.
+* Execution or failure of any _"child catchup"_ task.
 
 #### Splitting a shard Flat State
 
@@ -269,30 +272,35 @@ One current technical limitation is that, upon a node crash or restart, the _"sp
 A reference implementation of splitting a Flat State can be found in [FlatStorageResharder::split_shard_task](https://github.com/near/nearcore/blob/fecce019f0355cf89b63b066ca206a3cdbbdffff/chain/chain/src/flat_storage_resharder.rs#L295).
 
 #### Values assignment from parent to child shards
+
 Key-value pairs in the parent shard Flat State are inherited by children according to the rules stated below.
 
 Elements inherited by the child shard which tracks the `account_id` contained in the key:
-- `ACCOUNT`
-- `CONTRACT_DATA`
-- `CONTRACT_CODE`
-- `ACCESS_KEY`
-- `RECEIVED_DATA`
-- `POSTPONED_RECEIPT_ID`
-- `PENDING_DATA_COUNT`
-- `POSTPONED_RECEIPT`
-- `PROMISE_YIELD_RECEIPT`
+
+* `ACCOUNT`
+* `CONTRACT_DATA`
+* `CONTRACT_CODE`
+* `ACCESS_KEY`
+* `RECEIVED_DATA`
+* `POSTPONED_RECEIPT_ID`
+* `PENDING_DATA_COUNT`
+* `POSTPONED_RECEIPT`
+* `PROMISE_YIELD_RECEIPT`
 
 Elements inherited by both children:
-- `DELAYED_RECEIPT_OR_INDICES`
-- `PROMISE_YIELD_INDICES`
-- `PROMISE_YIELD_TIMEOUT`
-- `BANDWIDTH_SCHEDULER_STATE`
+
+* `DELAYED_RECEIPT_OR_INDICES`
+* `PROMISE_YIELD_INDICES`
+* `PROMISE_YIELD_TIMEOUT`
+* `BANDWIDTH_SCHEDULER_STATE`
 
 Elements inherited only be the lowest index child:
-- `BUFFERED_RECEIPT_INDICES `
-- `BUFFERED_RECEIPT`
+
+* `BUFFERED_RECEIPT_INDICES `
+* `BUFFERED_RECEIPT`
 
 #### Bring children shards up to date with the chain's head
+
 Children shards' Flat States build a complete view of their content at the height of the `resharding block` sometime during the new epoch 
 after resharding. At that point in time many new blocks have been processed already, and these will most likely contain updates for the new shards. A catch-up step is necessary to apply all Flat State deltas accumulated until now.
 

From 12fd9941bac716f804e082f1b09a0f1618eba986 Mon Sep 17 00:00:00 2001
From: Waclaw Banasik <wacban@users.noreply.github.com>
Date: Mon, 18 Nov 2024 15:33:54 +0000
Subject: [PATCH 19/30] motivation (#576)

---
 neps/nep-0568.md | 8 +-------
 1 file changed, 1 insertion(+), 7 deletions(-)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index 04aacf072..3391794c8 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -28,16 +28,10 @@ updates.
 
 ## Motivation
 
-```text
-[Explain why this proposal is necessary, how it will benefit the NEAR protocol or community, and what problems it solves. Also describe why the existing protocol specification is inadequate to address the problem that this NEP solves, and what potential use cases or outcomes.]
-```
+The sharded architecture of the NEAR Protocol is a cornerstone of its design, enabling parallel and distributed execution that significantly boosts overall throughput. Resharding plays a pivotal role in this system, allowing the network to adjust the number of shards to accommodate growth. By increasing the number of shards, resharding ensures the network can scale seamlessly, alleviating existing congestion, managing the rising traffic demands, and welcoming new customers. This adaptability is essential for maintaining the protocol's performance, reliability, and capacity to support a thriving, ever-expanding ecosystem.
 
 ## Specification
 
-```text
-[Explain the proposal as if you were teaching it to another developer. This generally means describing the syntax and semantics, naming new concepts, and providing clear examples. The specification needs to include sufficient detail to allow interoperable implementations getting built by following only the provided specification. In cases where it is infeasible to specify all implementation details upfront, broadly describe what they are.]
-```
-
 Resharding will be scheduled in advance by the NEAR developer team. The new
 shard layout will be hardcoded into the neard binary and linked to the protocol
 version. As the protocol upgrade progresses, resharding will be triggered during

From 03eeeea2b450b2f247da018bf1510d5fa32432f0 Mon Sep 17 00:00:00 2001
From: Waclaw Banasik <wacban@users.noreply.github.com>
Date: Tue, 19 Nov 2024 16:04:46 +0000
Subject: [PATCH 20/30] move some summary to motivation

---
 neps/nep-0568.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index 3391794c8..310de3ec6 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -15,12 +15,6 @@ LastUpdated: 2024-10-24
 This proposal introduces a new resharding implementation and shard layout for
 production networks.
 
-Resharding V3 is a significantly redesigned approach, addressing limitations of
-the previous versions, [Resharding V1][NEP-040] and [Resharding V2][NEP-508].
-The earlier solutions became obsolete due to major protocol changes since
-Resharding V2, including the introduction of Stateless Validation, Single Shard
-Tracking, and Mem-Trie.
-
 The primary objective of Resharding V3 is to increase chain capacity by
 splitting overutilized shards. A secondary aim is to lay the groundwork for
 supporting Dynamic Resharding, Instant Resharding and Shard Merging in future
@@ -30,6 +24,12 @@ updates.
 
 The sharded architecture of the NEAR Protocol is a cornerstone of its design, enabling parallel and distributed execution that significantly boosts overall throughput. Resharding plays a pivotal role in this system, allowing the network to adjust the number of shards to accommodate growth. By increasing the number of shards, resharding ensures the network can scale seamlessly, alleviating existing congestion, managing the rising traffic demands, and welcoming new customers. This adaptability is essential for maintaining the protocol's performance, reliability, and capacity to support a thriving, ever-expanding ecosystem.
 
+Resharding V3 is a significantly redesigned approach, addressing limitations of
+the previous versions, [Resharding V1][NEP-040] and [Resharding V2][NEP-508].
+The earlier solutions became obsolete due to major protocol changes since
+Resharding V2, including the introduction of Stateless Validation, Single Shard
+Tracking, and Mem-Trie.
+
 ## Specification
 
 Resharding will be scheduled in advance by the NEAR developer team. The new

From 080ac3cc60c7745aa8473e52a5fe32d612846eb4 Mon Sep 17 00:00:00 2001
From: Marcelo Diop-Gonzalez <marcelo827@gmail.com>
Date: Wed, 20 Nov 2024 00:19:51 -0500
Subject: [PATCH 21/30] Resharding V3 - add a few state sync details (#573)

---
 neps/nep-0568.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index 310de3ec6..cdf15490d 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -165,6 +165,12 @@ supporting smooth transitions without altering storage structures directly.
 
 ### State Sync
 
+Changes to the state sync protocol aren't typically conisdered protocol changes requiring a version bump, since it's concerned with downloading state that isn't present locally, rather than with the rules of execution of blocks and chunks. But it might still be helpful to outline some planned changes to state sync intended to make the resharding implementation easier to work with.
+
+When nodes sync state (either because they've fallen far behind the chain, or because they're going to become a chunk producer for a new shard in a future epoch), they first identify a point in the chain they'd like to sync to. Then they download the tries corresponding to that point in the chain and apply all chunks from that point until they're caught up. Currently, the tries downloaded initially are those corresponding to the `prev_state_root` field of the last new chunk before the current epoch's first block. This means the state downloaded is the state at some point in the previous epoch.
+
+The change we propose is to move the initial state download point to one in the current epoch rather than the previous. This allows some simplification in the resharding implementation, and reduces the size of the state we need to download. Suppose that the previous epoch's shard `S` was split into shards `S'` and `S''` in the current epoch, and that a chunk producer that wasn't tracking shard `S` or any of its children in the current epoch will become a chunk producer for `S'` in the next epoch. Then with the old state sync algorithm, that chunk producer would download the pre-split state for shard `S`. Then when it's done, it would need to perform the resharding that all the other nodes had already done. This isn't a correctness issue, but it simplifies the implementation somewhat if we instead download only the state for shard `S'`, and it allows the node to download only the state belonging to `S'`, which is much smaller.
+
 ### Cross Shard Traffic
 
 ### Delayed Receipt Handling
@@ -396,6 +402,12 @@ For archival nodes, mappings are retained permanently to ensure access to the hi
 This implementation ensures efficient and scalable shard state transitions,
 allowing child shards to use ancestor data without creating redundant entries.
 
+### State Sync
+
+The state sync algorithm defines a `sync_hash` that is used in many parts of the implementation. This is always the first block of the current epoch, which the node should be aware of once it has synced headers to the current point in the chain. A node performing state sync first makes a request (currently to centralized storage on GCS, but in the future to other nodes in the network) for a `ShardStateSyncResponseHeader` corresponding to that `sync_hash` and the Shard ID of the shard it's interested in. Among other things, this header includes the last new chunk before `sync_hash` in the shard, and a `StateRootNode` with hash equal to that chunk's `prev_state_root` field. Then the node downloads (again from GCS, but in the future it'll be from other nodes) the nodes of the trie with that `StateRootNode` as its root. Afterwards, it applies new chunks in the shard until it's caught up.
+
+ As described above, the state we download is the state in the shard after applying the second to last new chunk before `sync_hash`, which belongs to the previous epoch (since `sync_hash` is the first block of the new epoch). To move the point in the chain of the initial state download to the current epoch, we could either move the `sync_hash` forward or we could change the state sync protocol (perhaps changing the meaning of the `sync_hash` and the fields of the `ShardStateSyncResponseHeader`, or somehow changing these structures more significantly). The former is an easier first implementation, since it would not require any changes to the state sync protocol other than to the expected `sync_hash`. We would just need to move the `sync_hash` to a point far enough along in the chain so that the `StateRootNode` in the `ShardStateSyncResponseHeader` refers to state in the current epoch. Currently we plan on implementing it that way, but we may revisit making more extensive changes to the state sync protocol later.
+
 ## Security Implications
 
 ```text

From 910cf6c7e3e2b22762bb7312a840261a44717ece Mon Sep 17 00:00:00 2001
From: Aleksandr Logunov <the.alex.logunov@gmail.com>
Date: Sat, 23 Nov 2024 02:21:26 +0400
Subject: [PATCH 22/30] Resharding V3 - state witness, implementation (#577)

Adding State Witness section and filling some empty sections.
---
 neps/nep-0568.md | 135 ++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 110 insertions(+), 25 deletions(-)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index cdf15490d..24a4ec221 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -163,6 +163,38 @@ supporting smooth transitions without altering storage structures directly.
 
 ### Stateless Validation
 
+As only a fraction of nodes track the split shard, there is a need to prove the transition from state root of parent shard 
+to new state roots for children shards to other validators.
+Otherwise the chunk producers for split shard may collude and provide invalid state roots,
+which may compromise the protocol, for example, with minting tokens out of thin air.
+
+The design allows to generate and check this state transition in the time, negligible compared to the time it takes to apply chunk.
+As shown above in [State Storage - MemTrie](#state-storage---memtrie) section, generation and verification logic consists of constant number of trie lookups.
+More specifically, we implement `retain_split_shard(boundary_account, RetainMode::{Left, Right})` method for trie, which leaves only keys in trie that
+belong to the left or right child shard. 
+Inside, we implement `retain_multi_range(intervals)` method, where `intervals` is a vector of trie key intervals to retain.
+Each interval corresponds to unique trie key type prefix byte (`Account`, `AccessKey`, etc.) and either defines an interval from empty key to `boundary_account` key for left shard, or from `boundary_account` to infinity for right shard.
+`retain_multi_range` is recursive. Based on current trie key prefix covered by current node, it either:
+
+* returns node back, if subtree is fully contained within some interval;
+* returns "empty" node, if subtree is outside of all intervals;
+* otherwise, descends into all children and constructs new node with children returned by recursive calls.
+
+Implementation is agnostic to the trie storage used for retrieving nodes, it applies to both memtrie and partial storage (state proof). 
+
+* calling it for memtrie generates a proof and new state root;
+* calling it for partial storage generates a new state root. If method doesn't fail with error that node wasn't found in the proof, it means that proof was sufficient, and it remains to compare generated state root with the one proposed by chunk producer.
+
+### State Witness
+
+Resharding state transition becomes one of `implicit_transitions` in `ChunkStateWitness`. It must be validated between processing last chunk (potentially missing) in the old epoch and the first chunk (potentially missing) in the new epoch. `ChunkStateTransition` fields also nicely correspond to the resharding state transition: in `block_hash` we store the hash of the last block of the parent shard, in `base_state` we store the resharding proof, and in `post_state_root` we store the proposed state root.
+
+Note that it leads to **two** state transitions corresponding to the same block hash. On the chunk producer side, the first transition is stored for the `(block_hash, parent_shard_uid)` pair and the second one is stored for the `(block_hash, child_shard_uid)` pair.
+
+The chunk validator has all the blocks, so it identifies whether implicit transition corresponds to applying missing chunk or resharding independently. This is implemented in `get_state_witness_block_range`, which iterates from `state_witness.chunk_header.prev_block_hash()` to the block with includes last last chunk for the (parent) shard, if it exists.
+
+Then, on `validate_chunk_state_witness`, if implicit transition corresponds to resharding, chunk validator calls `retain_split_shard` and proves state transition from parent to child shard.
+
 ### State Sync
 
 Changes to the state sync protocol aren't typically conisdered protocol changes requiring a version bump, since it's concerned with downloading state that isn't present locally, rather than with the rules of execution of blocks and chunks. But it might still be helpful to outline some planned changes to state sync intended to make the resharding implementation easier to work with.
@@ -187,18 +219,59 @@ In this NEP, we propose updating the ShardId semantics to allow for arbitrary id
 
 ## Reference Implementation
 
-```text
-[This technical section is required for Protocol proposals but optional for other categories. A draft implementation should demonstrate a minimal implementation that assists in understanding or implementing this proposal. Explain the design in sufficient detail that:
+### Overview
+<!-- markdownlint-disable MD029 -->
+
+1. Any node tracking shard must determine if it should split shard in the last block before the epoch where resharding should happen.
+
+```pseudocode
+should_split_shard(block, shard_id):
+  shard_layout = epoch_manager.shard_layout(block.epoch_id())
+  next_shard_layout = epoch_manager.shard_layout(block.next_epoch_id())
+  if epoch_manager.is_next_block_epoch_start(block) && 
+    shard_layout != next_shard_layout &&
+    next_shard_layout.shard_split_map().contains(shard_id):
+    return Some(next_shard_layout.split_shard_event(shard_id))
+  return None
+```
+
+2. This logic is triggered on block postprocessing, which means that block is valid and is being persisted to disk.
 
-* Its interaction with other features is clear.
-* Where possible, include a Minimum Viable Interface subsection expressing the required behavior and types in a target programming language. (ie. traits and structs for rust, interfaces and classes for javascript, function signatures and structs for c, etc.)
-* It is reasonably clear how the feature would be implemented.
-* Corner cases are dissected by example.
-* For protocol changes: A link to a draft PR on nearcore that shows how it can be integrated in the current code. It should at least solve the key technical challenges.
+```pseudocode
+on chain.postprocess_block(block):
+  next_shard_layout = epoch_manager.shard_layout(block.next_epoch_id())
+  if let Some(split_shard_event) = should_split_shard(block, shard_id):
+    resharding_manager.split_shard(split_shard_event)
+```
+
+3. The event triggers changes in all state storage components.
 
-The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work.]
+```pseudocode
+on resharding_manager.split_shard(split_shard_event, next_shard_layout):
+  set State mapping
+  start FlatState resharding
+  process MemTrie resharding:
+    freeze MemTrie, create HybridMemTries
+    for each child shard:
+      mem_tries[parent_shard].retain_split_shard(boundary_account)
 ```
 
+4. `retain_split_shard` leaves only keys in trie that belong to the left or right child shard. 
+It retains trie key intervals for left or right child as described above. Simultaneously the proof is generated.
+In the end, we get new state root, hybrid memtrie corresponding to child shard, and the proof.
+Proof is saved as state transition for pair `(block, new_shard_uid)`.
+
+5. The proof is sent as one of implicit transitions in ChunkStateWitness.
+
+6. On chunk validation path, chunk validator understands if resharding is 
+a part of state transition, using the same `should_split_shard` condition.
+
+7. It calls `Trie(state_transition_proof).retain_split_shard(boundary_account)` 
+which should succeed if proof is sufficient and generates new state root.
+
+8. Finally, it checks that the new state root matches the state root proposed in `ChunkStateWitness`.
+If the whole `ChunkStateWitness` is valid, then chunk validator sends endorsement which also endorses the resharding.
+
 ### State Storage - MemTrie
 
 The current implementation of MemTrie uses a pool of memory (`STArena`) to allocate and deallocate nodes and internal pointers in this pool to reference child nodes. MemTries, unlike the State representation of Trie, do not work with the hash of the nodes but internal memory pointers directly. Additionally, MemTries are not thread safe and one MemTrie exists per shard.
@@ -296,7 +369,7 @@ Elements inherited by both children:
 
 Elements inherited only be the lowest index child:
 
-* `BUFFERED_RECEIPT_INDICES `
+* `BUFFERED_RECEIPT_INDICES`
 * `BUFFERED_RECEIPT`
 
 #### Bring children shards up to date with the chain's head
@@ -410,15 +483,32 @@ The state sync algorithm defines a `sync_hash` that is used in many parts of the
 
 ## Security Implications
 
-```text
-[Explicitly outline any security concerns in relation to the NEP, and potential ways to resolve or mitigate them. At the very least, well-known relevant threats must be covered, e.g. person-in-the-middle, double-spend, XSS, CSRF, etc.]
-```
+### Fork Handling
+
+In theory, it can happen that there will be more than one candidate block which finishes the last epoch with old shard layout. For previous implementations it didn't matter because resharding decision was made in the beginning previous epoch. Now, the decision is made on the epoch boundary, so the new implementation handles this case as well.
+
+### Proof Validation
+
+With single shard tracking, nodes can't independently validate new state roots after resharding, because they don't have state of shard being split. That's why we generate resharding proofs, whose generation and validation may be a new weak point. However, `retain_split_shard` is equivalent to constant number of lookups in the trie, so its overhead its negligible. Even if proof is invalid, it will only imply that `retain_split_shard` fails early, similarly to other state transitions.
 
 ## Alternatives
 
-```text
-[Explain any alternative designs that were considered and the rationale for not choosing them. Why your design is superior?]
-```
+In the solution space which would keep blockchain stateful, we also considered an alternative to handle resharding through mechanism of `Receipts`. The workflow would be to:
+
+* create empty `target_shard`,
+* require `source_shard` chunk producers to create special `ReshardingReceipt(source_shard, target_shard, data)` where `data` would be an interval of key-value pairs in `source_shard` alongside with the proof,
+* then, `target_shard` trackers and validators would process that receipt, validate the proof and insert the key-value pairs into the new shard.
+
+However, `data` would occupy most of the whole state witness capacity and introduce overhead of proving every single interval in `source_shard`. Moreover, approach to sync target shard "dynamically" also requires some form of catchup, which makes it much less feasible than chosen approach.
+
+Another question is whether we should tie resharding to epoch boundaries. This would allow to come from resharding decision to completion much faster. But for that, we would need to:
+
+* agree if we should reshard in the middle of the epoch or allow "fast epoch completion" which has to be implemented,
+* keep chunk producers tracking "spare shards" ready to receive items from split shards,
+* on resharding event, implement specific form of state sync, on which source and target chunk producers would agree on new state roots offline,
+* then, new state roots would be validated by chunk validators in the same fashion.
+
+While it is much closer to Dynamic Resharding (below), it requires much more changes to the protocol. And the considered idea works very well as intermediate step to that, if needed.
 
 ## Future possibilities
 
@@ -428,27 +518,22 @@ The state sync algorithm defines a `sync_hash` that is used in many parts of the
 
 ## Consequences
 
-```text
-[This section describes the consequences, after applying the decision. All consequences should be summarized here, not just the "positive" ones. Record any concerns raised throughout the NEP discussion.]
-```
-
 ### Positive
 
-* p1
+* The protocol is able to execute resharding even while only a fraction of nodes track the split shard.
+* State for new shard layouts is computed in the matter of minutes instead of hours, thus ecosystem stability during resharding is greatly increased. As before, from the point of view of NEAR users it is instantaneous.
 
 ### Neutral
 
-* n1
+N/A
 
 ### Negative
 
-* n1
+* The storage components need to handle additional complexity of controlling the shard layout change.
 
 ### Backwards Compatibility
 
-```text
-[All NEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. Author must explain a proposes to deal with these incompatibilities. Submissions without a sufficient backwards compatibility treatise may be rejected outright.]
-```
+Resharding is backwards compatible with existing protocol logic.
 
 ## Unresolved Issues (Optional)
 

From 8ab6927b9ab387131923f5bad74167832ecca1fc Mon Sep 17 00:00:00 2001
From: Shreyan Gupta <shreyan.gupta96@gmail.com>
Date: Mon, 25 Nov 2024 22:44:35 +0530
Subject: [PATCH 23/30] [resharding] Add sections for receipt handling (#578)

This is complete except for section `Handling buffered receipts that
target parent shard` which is still being discussed.
---
 neps/nep-0568.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index 24a4ec221..5ddb2acbb 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -207,10 +207,101 @@ The change we propose is to move the initial state download point to one in the
 
 ### Delayed Receipt Handling
 
+The delayed receipts queue contains all incoming receipts that could not be executed as part of a block due to resource constraints like compute cost, gas limits etc. The entries in the delayed receipt queue can belong to any of the accounts as part of the shard. During a resharding event, we ideally need to split the delayed receipts across both the child shards according to the associated account_id with the receipt.
+
+The singleton trie key `DelayedReceiptIndices` holds the start_index and end_index associated with the delayed receipt entries for the shard. The trie key `DelayedReceipt { index }` contains the actual delayed receipt associated with some account_id. These are processed in a fifo queue order during chunk execution.
+
+Note that the delayed receipt trie keys do not have the `account_id` prefix. In ReshardingV2, we followed the trivial solution of iterating through all the delayed receipt queue entries and assigning them to the appropriate child shard, however due to constraints on the state witness size limits and instant resharding, this approach is no longer feasible for ReshardingV3.
+
+For ReshardingV3, we decided to handle the resharding by duplicating the entries of the delayed receipt queue across both the child shards. This is great from the perspective of state witness size and instant resharding as we only need to access the delayed receipt queue root entry in the trie, however it breaks the assumption that all delayed receipts in a shard belong to the accounts within that shard.
+
+To resolve this, with the new protocol version, we changed the implementation of runtime to discard executing delayed receipts that don't belong to the account_id on that shard.
+
+Note that no delayed receipts are lost during resharding as all receipts get executed exactly once based on which of the child shards does the associated account_id belong to.
+
 ### PromiseYield Receipt Handling
 
+Promise Yield were introduced as part of NEP-519 to enable defer replying to caller function while response is being prepared. As part of Promise Yield implementation, it introduced three new trie keys, `PromiseYieldIndices`, `PromiseYieldTimeout` and `PromiseYieldReceipt`.
+
+* `PromiseYieldIndices`: This is a singleton key that holds the start_index and end_index of the keys in `PromiseYieldTimeout`
+* `PromiseYieldTimeout { index }`: Along with the receiver_id and data_id, this stores the expires_at block height till which we need to wait to receive a response.
+* `PromiseYieldReceipt { receiver_id, data_id }`: This is the receipt created by the account.
+
+An account can call the `promise_yield_create` host function that increments the `PromiseYieldIndices` along with adding a new entry into the `PromiseYieldTimeout` and `PromiseYieldReceipt`.
+
+The `PromiseYieldTimeout` is sorted as per the time of creation and has an increasing value of expires_at block height. In the runtime, we iterate over all the expired receipts and create a blank receipt to resolve the entry in `PromiseYieldReceipt`.
+
+The account can call the `promise_yield_resume` host function multiple times and if this is called before the expiry period, we use this to resolve the promise yield receipt. Note that the implementation allows for multiple resolution receipts to be created, including the expiry receipt, but only the first one is used for the actual resolution of the promise yield receipt.
+
+We use this implementation quirk to facilitate resharding implementation. The resharding strategy for the three trie keys are:
+
+* `PromiseYieldIndices`: Duplicate across both child shards.
+* `PromiseYieldTimeout { index }`: Duplicate across both child shards.
+* `PromiseYieldReceipt { receiver_id, data_id }`: Since this key has the account_id prefix, we can split the entries across both child shards based on the prefix.
+
+After duplication of the `PromiseYieldIndices` and `PromiseYieldTimeout`, when the entries of `PromiseYieldTimeout` eventually get dequeued at the expiry height of the following happens:
+
+* If the promise yield receipt associated with the dequeued entry IS NOT a part of the child trie, we create a timeout resolution receipt and it gets ignored.
+* If the promise yield receipt associated with the dequeued entry IS part of the child trie, the promise yield implementation continues to work as expected.
+
+This means we don't have to make any special changes in the runtime for handling resharding of promise yield receipts.
+
 ### Buffered Receipt Handling
 
+Buffered Receipts were introduced as part of NEP-539, cross-shard congestion control. As part of the implementation, it introduced two new trie keys, `BufferedReceiptIndices` and `BufferedReceipt`.
+
+* `BufferedReceiptIndices`: This is a singleton key that holds the start_index and end_index of the keys in `BufferedReceipt` for each shard_id.
+* `BufferedReceipt { receiving_shard, index }`: This holds the actual buffered receipt that needs to be sent to the receiving_shard.
+
+Note that the targets of the buffered receipts belong to external shards and during a resharding event, we would need to handle both, the set of buffered receipts in the parent shard, as well as the set of buffered receipts in other shards that target the parent shard.
+
+#### Handling buffered receipts in parent shard
+
+Since buffered receipts target external shards, it is fine to assign buffered receipts to either of the child shards. For simplicity, we assign all the buffered receipts to the child shard with the lower index, i.e. copy `BufferedReceiptIndices` and `BufferedReceipt` to the child shard with lower index while keeping `BufferedReceiptIndices` as empty for child shard with higher index.
+
+#### Handling buffered receipts that target parent shard
+
+TODO(shreyan)
+
+### Congestion Control
+
+Along with having buffered receipts, each chunk also publishes a CongestionInfo to the chunk header that has information about the congestion of the shard as of processing block.
+
+```rust
+pub struct CongestionInfoV1 {
+    /// Sum of gas in currently delayed receipts.
+    pub delayed_receipts_gas: u128,
+    /// Sum of gas in currently buffered receipts.
+    pub buffered_receipts_gas: u128,
+    /// Size of borsh serialized receipts stored in state because they
+    /// were delayed, buffered, postponed, or yielded.
+    pub receipt_bytes: u64,
+    /// If fully congested, only this shard can forward receipts.
+    pub allowed_shard: u16,
+}
+```
+
+After a resharding event, we need to properly initialize the congestion info for the child shards. Here's how we handle each of the fields
+
+#### delayed_receipts_gas
+
+Since the resharding strategy for delayed receipts is to duplicate them across both the child shards, we simply copy the value of `delayed_receipts_gas` across both shards.
+
+#### buffered_receipts_gas
+
+Since the resharding strategy for buffered receipts is to assign all the buffered receipts to the lower index child, we copy the `buffered_receipts_gas` from parent to lower index child and set `buffered_receipts_gas` to zero for upper index child.
+
+#### receipt_bytes
+
+This field is harder to deal with as it contains the information from both delayed receipts and buffered receipts. To calculate this field properly, we would need the distribution of the receipt_bytes across both delayed receipts and buffered receipts. The current solution is to start storing metadata about the total `receipt_bytes` for buffered receipts in the trie. This way we have the following:
+
+* For child with lower index, receipt_bytes is the sum of both delayed receipts bytes and congestion control bytes, hence `receipt_bytes = parent.receipt_bytes`
+* For child with upper index, receipt_bytes is just the bytes from delayed receipts, hence `receipt_bytes = parent.receipt_bytes - buffered_receipt_bytes`
+
+#### allowed_shard
+
+This field is calculated by a round-robin mechanism which can be independently calculated for both the child shards. Since we are changing the [ShardId semantics](#shardid-semantics), we need to change implementation to use `ShardIndex` instead of `ShardID` which is just an assignment for each shard_id to the contiguous index `[0, num_shards)`.
+
 ### ShardId Semantics
 
 Currently, shard IDs are represented as numbers within the range `[0,n)`, where n is the total number of shards. These shard IDs are sorted in the same order as the account ID ranges assigned to them. While this approach is straightforward, it complicates resharding operations, particularly when splitting a shard in the middle of the range. Such a split requires reindexing all subsequent shards with higher IDs, adding complexity to the process.

From 09dc287fc2d5c75727f6d876ff4077627e79a1f7 Mon Sep 17 00:00:00 2001
From: wacban <wac.banasik@gmail.com>
Date: Wed, 4 Dec 2024 17:55:10 +0000
Subject: [PATCH 24/30] cross shard traffic

---
 neps/nep-0568.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index 5ddb2acbb..1cb7fc000 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -205,6 +205,46 @@ The change we propose is to move the initial state download point to one in the
 
 ### Cross Shard Traffic
 
+When the shard layout changes, it is crucial to handle cross-shard traffic
+correctly, especially in the presence of missing chunks. Care must be taken to
+ensure that no receipt is lost or duplicated. There are two important receipt
+types that need to be considered - the outgoing receipts and the incoming
+receipts.
+
+Note - this proposal reuses the approach taken by ReshardingV2. 
+
+#### Outgoing Receipts
+
+Each new chunk in a shard contains a list of outgoing receipts generated during
+the processing of the previous chunk in that shard.
+
+In cases where chunks are missing at the resharding boundary, both child shards
+could theoretically include the outgoing receipts from their shared ancestor
+chunk. However, this naive approach would lead to the duplication of receipts,
+which must be avoided.
+
+The proposed solution is to reassign the outgoing receipts from the parent chunk
+to only one of the child shards. Specifically, the child shard with the lower
+shard ID will claim all outgoing receipts from the parent, while the other child
+will receive none. This ensures that all receipts are processed exactly once. 
+
+#### Incoming Receipts
+
+To process a chunk in a shard, it is necessary to gather all outgoing receipts
+from other shards that are targeted at this shard. These receipts must then be
+included as incoming receipts.
+
+In the presence of missing chunks, the new chunk must collect receipts from all
+previous blocks, spanning the period since the last new chunk in this shard.
+This range may cross the resharding boundary.
+
+When this occurs, the chunk must also consider receipts that were previously
+targeted at its parent shard. However, it must filter these receipts to include
+only those where the recipient lies within the current shard, discarding those
+where the recipient belongs to the sibling shard in the new shard layout. This
+filtering process ensures that every receipt is processed exactly once and in
+the correct shard. 
+
 ### Delayed Receipt Handling
 
 The delayed receipts queue contains all incoming receipts that could not be executed as part of a block due to resource constraints like compute cost, gas limits etc. The entries in the delayed receipt queue can belong to any of the accounts as part of the shard. During a resharding event, we ideally need to split the delayed receipts across both the child shards according to the associated account_id with the receipt.

From d889993958a8413ec2510fd80341a35e15611be9 Mon Sep 17 00:00:00 2001
From: Marcelo Diop-Gonzalez <marcelo827@gmail.com>
Date: Fri, 13 Dec 2024 05:48:14 -0500
Subject: [PATCH 25/30] state sync: reword to make clear it's not just for
 convenience (#579)

---
 neps/nep-0568.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index 1cb7fc000..e127861ad 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -197,11 +197,11 @@ Then, on `validate_chunk_state_witness`, if implicit transition corresponds to r
 
 ### State Sync
 
-Changes to the state sync protocol aren't typically conisdered protocol changes requiring a version bump, since it's concerned with downloading state that isn't present locally, rather than with the rules of execution of blocks and chunks. But it might still be helpful to outline some planned changes to state sync intended to make the resharding implementation easier to work with.
+Changes to the state sync protocol aren't typically conisdered protocol changes requiring a version bump, since it's concerned with downloading state that isn't present locally, rather than with the rules of execution of blocks and chunks. But it might still be helpful to outline some planned changes to state sync related to resharding.
 
 When nodes sync state (either because they've fallen far behind the chain, or because they're going to become a chunk producer for a new shard in a future epoch), they first identify a point in the chain they'd like to sync to. Then they download the tries corresponding to that point in the chain and apply all chunks from that point until they're caught up. Currently, the tries downloaded initially are those corresponding to the `prev_state_root` field of the last new chunk before the current epoch's first block. This means the state downloaded is the state at some point in the previous epoch.
 
-The change we propose is to move the initial state download point to one in the current epoch rather than the previous. This allows some simplification in the resharding implementation, and reduces the size of the state we need to download. Suppose that the previous epoch's shard `S` was split into shards `S'` and `S''` in the current epoch, and that a chunk producer that wasn't tracking shard `S` or any of its children in the current epoch will become a chunk producer for `S'` in the next epoch. Then with the old state sync algorithm, that chunk producer would download the pre-split state for shard `S`. Then when it's done, it would need to perform the resharding that all the other nodes had already done. This isn't a correctness issue, but it simplifies the implementation somewhat if we instead download only the state for shard `S'`, and it allows the node to download only the state belonging to `S'`, which is much smaller.
+The change we propose is to move the initial state download point to one in the current epoch rather than the previous. This keeps shard IDs consistent throughout the state sync logic, allows some simplification in the resharding implementation, and reduces the size of the state we need to download. Suppose that the previous epoch's shard `S` was split into shards `S'` and `S''` in the current epoch, and that a chunk producer that wasn't tracking shard `S` or any of its children in the current epoch will become a chunk producer for `S'` in the next epoch. Then with the old state sync algorithm, that chunk producer would download the pre-split state for shard `S`. Then when it's done, it would need to perform the resharding that all the other nodes had already done. This isn't a correctness issue, but it simplifies the implementation somewhat if we instead download only the state for shard `S'`, and it allows the node to download only the state belonging to `S'`, which is much smaller.
 
 ### Cross Shard Traffic
 

From 0ae4721769a2fcecb2b41024dd64032485073c6e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Adam=20Chuda=C5=9B?=
 <18039094+staffik@users.noreply.github.com>
Date: Fri, 13 Dec 2024 12:43:31 +0100
Subject: [PATCH 26/30] resharding: cold storage (#580)

---
 neps/nep-0568.md | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index e127861ad..bec8dd340 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -138,8 +138,6 @@ Splitting a shard's Flat State is performed in multiple steps:
 
 ### State Storage - State
 
-// TODO Describe integration with cold storage once design is ready
-
 Each shard’s Trie is stored in the `State` column of the database, with keys prefixed by `ShardUId`, followed by a node's hash.
 This structure uniquely identifies each shard’s data. To avoid copying all entries under a new `ShardUId` during resharding,
 a mapping strategy allows child shards to access ancestor shard data without directly creating new entries.
@@ -155,11 +153,18 @@ This allows child shards to access and update state data under the ancestor shar
 Initially, `ShardUIdMapping` is empty, as existing shards map to themselves. During resharding, a mapping entry is added to `ShardUIdMapping`,
 pointing each child shard’s `ShardUId` to the appropriate ancestor. Mappings persist as long as any descendant shard references the ancestor’s data.
 Once a node stops tracking all children and descendants of a shard, the entry for that shard can be removed, allowing its data to be garbage collected.
-For archival nodes, mappings are retained indefinitely to maintain access to the full historical state.
 
 This mapping strategy enables efficient shard management during resharding events,
 supporting smooth transitions without altering storage structures directly.
 
+#### Integration with cold storage (archival nodes)
+
+Cold storage uses the same mapping strategy to manage shard state during resharding:
+* When state data is migrated from hot to cold storage, it retains the parent shard’s `ShardUId` prefix, ensuring consistency with the mapping strategy.
+* While copying data for the last block of the epoch where resharding occured, the `DBCol::StateShardUIdMapping` column is copied into cold storage. This ensures that mappings are updated alongside the shard state data.
+* These mappings are permanent in cold storage, aligning with its role in preserving historical state.
+
+This approach minimizes complexity while maintaining consistency across hot and cold storage.
 
 ### Stateless Validation
 

From cf3174f38c832e126b6a7878d71f8778f240859c Mon Sep 17 00:00:00 2001
From: Waclaw Banasik <wacban@users.noreply.github.com>
Date: Fri, 13 Dec 2024 13:11:19 +0100
Subject: [PATCH 27/30] lint

---
 neps/nep-0568.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index bec8dd340..6013bdd39 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -160,6 +160,7 @@ supporting smooth transitions without altering storage structures directly.
 #### Integration with cold storage (archival nodes)
 
 Cold storage uses the same mapping strategy to manage shard state during resharding:
+
 * When state data is migrated from hot to cold storage, it retains the parent shard’s `ShardUId` prefix, ensuring consistency with the mapping strategy.
 * While copying data for the last block of the epoch where resharding occured, the `DBCol::StateShardUIdMapping` column is copied into cold storage. This ensures that mappings are updated alongside the shard state data.
 * These mappings are permanent in cold storage, aligning with its role in preserving historical state.

From c4f5e3051d27eee1073526d20d0ec638300446a7 Mon Sep 17 00:00:00 2001
From: Shreyan Gupta <shreyan.gupta96@gmail.com>
Date: Mon, 16 Dec 2024 16:06:38 +0530
Subject: [PATCH 28/30] Add section on buffered receipt handling

---
 neps/nep-0568.md | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index 6013bdd39..5491ba349 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -307,7 +307,23 @@ Since buffered receipts target external shards, it is fine to assign buffered re
 
 #### Handling buffered receipts that target parent shard
 
-TODO(shreyan)
+This scenario is slightly more complex to deal with. At the boundary of resharding, we may have buffered receipts created before the resharding event targeting the parent shard. At the same time, we may also have buffered receipts that are generated after the resharding event that directly target the child shard. The receipts from both parent and child buffered receipts queue need to appropriately sent to the child shard depending on the account_id while respecting the outgoing limits calculated by bandwidth scheduler and congestion control. 
+
+The flow of handling buffered receipts before ReshardingV3 is as follows:
+
+1. Calculate `outgoing_limit` for each shard.
+2. For each shard, try and forward as many in-order receipts as possible from the buffer while respecting `outgoing_limit`.
+3. Apply chunk and `try_forward` newly generated receipts. The newly generated receipts are forwarded if we have enough limit else they are put in the buffered queue.
+
+The solution for ReshardingV3 is to first try draining the parent queue before moving onto draining the child queue. The modified flow would look something like:
+
+1. Calculate `outgoing_limit` for both the child shards using congestion info from parent.
+2. Forwarding receipts
+    * First try forward as many in-order receipts as possible from parent shard buffer. Stop either when we drain the parent buffer or as soon as we exhaust the `outgoing_limit` of either of the children shards.
+    * Next try forward as many in-order receipts as possible from child shard buffer.
+3. Apply chunk and `try_forward` newly generated receipts remains the same.
+
+The minor downside to this approach is that we don't have guarantees between order of receipt generation and order of receipt forwarding, but that's anyway the case today with buffered receipts.
 
 ### Congestion Control
 

From 1efd6cf18b05973c1e7ff1e67893804f4eec95ac Mon Sep 17 00:00:00 2001
From: Shreyan Gupta <shreyan.gupta96@gmail.com>
Date: Mon, 16 Dec 2024 20:39:07 +0530
Subject: [PATCH 29/30] [resharding] ChatGPT modulation (#581)

Some beautification courtesy ChatGPT.

I double checked everything, we aren't changing any meaning.
---
 neps/nep-0568.md | 593 +++++++++++++++++++----------------------------
 1 file changed, 243 insertions(+), 350 deletions(-)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index 5491ba349..6e4d9dd93 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -10,324 +10,244 @@ Created: 2024-10-24
 LastUpdated: 2024-10-24
 ---
 
-## Summary 
+## Summary
 
-This proposal introduces a new resharding implementation and shard layout for
-production networks.
+This proposal introduces a new resharding implementation and shard layout for production networks.
 
-The primary objective of Resharding V3 is to increase chain capacity by
-splitting overutilized shards. A secondary aim is to lay the groundwork for
-supporting Dynamic Resharding, Instant Resharding and Shard Merging in future
-updates.
+The primary objective of Resharding V3 is to increase chain capacity by splitting overutilized shards. A secondary aim is to lay the groundwork for supporting Dynamic Resharding, Instant Resharding, and Shard Merging in future updates.
 
 ## Motivation
 
-The sharded architecture of the NEAR Protocol is a cornerstone of its design, enabling parallel and distributed execution that significantly boosts overall throughput. Resharding plays a pivotal role in this system, allowing the network to adjust the number of shards to accommodate growth. By increasing the number of shards, resharding ensures the network can scale seamlessly, alleviating existing congestion, managing the rising traffic demands, and welcoming new customers. This adaptability is essential for maintaining the protocol's performance, reliability, and capacity to support a thriving, ever-expanding ecosystem.
+The sharded architecture of the NEAR Protocol is a cornerstone of its design, enabling parallel and distributed execution that significantly boosts overall throughput. Resharding plays a pivotal role in this system, allowing the network to adjust the number of shards to accommodate growth. By increasing the number of shards, resharding ensures the network can scale seamlessly, alleviating existing congestion, managing rising traffic demands, and welcoming new participants. This adaptability is essential for maintaining the protocol's performance, reliability, and capacity to support a thriving, ever-expanding ecosystem.
 
-Resharding V3 is a significantly redesigned approach, addressing limitations of
-the previous versions, [Resharding V1][NEP-040] and [Resharding V2][NEP-508].
-The earlier solutions became obsolete due to major protocol changes since
-Resharding V2, including the introduction of Stateless Validation, Single Shard
-Tracking, and Mem-Trie.
+Resharding V3 is a significantly redesigned approach, addressing limitations of the previous versions, [Resharding V1][NEP-040] and [Resharding V2][NEP-508]. The earlier solutions became obsolete due to major protocol changes since Resharding V2, including the introduction of Stateless Validation, Single Shard Tracking, and Mem-Trie.
 
 ## Specification
 
-Resharding will be scheduled in advance by the NEAR developer team. The new
-shard layout will be hardcoded into the neard binary and linked to the protocol
-version. As the protocol upgrade progresses, resharding will be triggered during
-the post-processing phase of the last block of the epoch. At this point, the
-state of the parent shard will be split between two child shards. From the first
-block of the new protocol version onward, the chain will operate with the new
-shard layout.
-
-There are two key dimensions to consider: state storage and protocol features,
-along with a few additional details.
-
-1) State Storage: Currently, the state of a shard is stored in three distinct
-formats: the state, the flat state, and the mem-trie. Each of these
-representations must be resharded. Logically, resharding is an almost
-instantaneous event that occurs before the first block under the new shard
-layout. However, in practice, some of this work may be deferred to
-post-processing, as long as the chain's view reflects a fully resharded state.
-
-1) Protocol Features: Several protocol features must integrate smoothly with the
-  resharding process, including:
-
-* Stateless Validation: Resharding must be validated and proven through
-  stateless validation mechanisms.
-* State Sync: Nodes must be able to sync the states of the child
-  shards post-resharding.
-* Cross-Shard Traffic: Receipts sent to the parent shard may need to be
-  reassigned to one of the child shards.
-* Receipt Handling: Delayed, postponed, buffered, and promise-yield receipts
-  must be correctly distributed between the child shards.
-* ShardId Semantics: The shard identifiers will become abstract identifiers
-  where today they are number in the 0..num_shards range.
-* Congestion Info: CongestionInfo in the chunk header would be recalculated for the child
-  shards at the resharding boundary. Proof must be compatible with Stateless Validation.
+Resharding will be scheduled in advance by the NEAR developer team. The new shard layout will be hardcoded into the `neard` binary and linked to the protocol version. As the protocol upgrade progresses, resharding will be triggered during the post-processing phase of the last block of the epoch. At this point, the state of the parent shard will be split between two child shards. From the first block of the new protocol version onward, the chain will operate with the new shard layout.
+
+There are two key dimensions to consider: state storage and protocol features, along with additional details.
+
+1. **State Storage**: Currently, the state of a shard is stored in three distinct formats: the state, the flat state, and the mem-trie. Each of these representations must be resharded. Logically, resharding is an almost instantaneous event that occurs before the first block under the new shard layout. However, in practice, some of this work may be deferred to post-processing, as long as the chain's view reflects a fully resharded state.
+
+2. **Protocol Features**: Several protocol features must integrate smoothly with the resharding process, including:
+
+    * **Stateless Validation**: Resharding must be validated and proven through stateless validation mechanisms.
+    * **State Sync**: Nodes must be able to synchronize the states of the child shards post-resharding.
+    * **Cross-Shard Traffic**: Receipts sent to the parent shard may need to be reassigned to one of the child shards.
+    * **Receipt Handling**: Delayed, postponed, buffered, and promise-yield receipts must be correctly distributed between the child shards.
+    * **ShardId Semantics**: The shard identifiers will become abstract identifiers where today they are numbers in the `0..num_shards` range.
+    * **Congestion Info**: `CongestionInfo` in the chunk header will be recalculated for the child shards at the resharding boundary. Proof must be compatible with Stateless Validation.
 
 ### State Storage - MemTrie
 
-MemTrie is the in-memory representation of the trie that the runtime uses for all trie accesses. This is kept in sync with the Trie representation in state.
+MemTrie is the in-memory representation of the trie that the runtime uses for all trie accesses. It is kept in sync with the Trie representation in the state.
 
-As of today it isn't mandatory for nodes to have MemTrie feature enabled but going forward, with ReshardingV3, all nodes would require to have MemTrie enabled for resharding to happen successfully.
+Currently, it isn't mandatory for nodes to have the MemTrie feature enabled, but going forward with Resharding V3, all nodes will be required to have MemTrie enabled for resharding to happen successfully.
 
-For the purposes of resharding, we need an efficient way to split the MemTrie into two child tries based on the boundary account. This splitting happens at the epoch boundary when the new epoch is expected to have the two child shards. The set of requirements around MemTrie splitting are:
+For resharding, we need an efficient way to split the MemTrie into two child tries based on the boundary account. This splitting happens at the epoch boundary when the new epoch is expected to have the two child shards. The requirements for MemTrie splitting are:
 
-* MemTrie splitting needs to be "instant", i.e. happen efficiently within the span of one block. The child tries need to be available for the processing of the next block in the new epoch.
-* MemTrie splitting needs to be compatible with stateless validation, i.e. we need to generate a proof that the memtrie split proposed by the chunk producer is correct.
-* The proof generated for splitting the MemTrie needs to be compatible with the limits of the size of state witness that we send to all chunk validators. This prevents us from doing things like iterating through all trie keys for delayed receipts etc.
+* **Instantaneous Splitting**: MemTrie splitting needs to happen efficiently within the span of one block. The child tries need to be available for processing the next block in the new epoch.
+* **Compatibility with Stateless Validation**: We need to generate a proof that the MemTrie split proposed by the chunk producer is correct.
+* **State Witness Size Limits**: The proof generated for splitting the MemTrie needs to comply with the size limits of the state witness sent to all chunk validators. This prevents us from iterating through all trie keys for delayed receipts, etc.
 
-With ReshardingV3 design, there's no protocol change to the structure of MemTries, however the implementation constraints required us to introduce the concept of a Frozen MemTrie. More details are in the [implementation](#state-storage---memtrie-1) section below.
+With the Resharding V3 design, there's no protocol change to the structure of MemTries; however, implementation constraints required us to introduce the concept of a Frozen MemTrie. More details are in the [implementation](#state-storage---memtrie-1) section below.
 
-Based on the requirements above, we came up with an algorithm to efficiently split the parent trie into two child tries. Trie entries can be divided into three categories based on whether the trie keys have an `account_id` prefix and based on the total number of such trie keys. Splitting of these keys is handled in different ways.
+Based on these requirements, we developed an algorithm to efficiently split the parent trie into two child tries. Trie entries can be divided into three categories based on whether the trie keys have an `account_id` prefix and the total number of such trie keys. Splitting of these keys is handled differently.
 
-#### TrieKey with AccountID prefix
+#### TrieKey with AccountID Prefix
 
-This category includes most of the trie keys like `TrieKey::Account`, `TrieKey::ContractCode`, `TrieKey::PostponedReceipt`, etc. For these keys, we can efficiently split the trie based on the boundary account trie key. Note that we only need to read all the intermediate nodes that form a part of the split key. In the example below, if "pass" is the split key, we access all the nodes along the path of `root` -> `p` -> `a` -> `s` -> `s`, while not needing to touch any of the other intermediate nodes like `o` -> `s` -> `t` in key "post". The accessed nodes form a part of the state witness as those are the only nodes that the validators would need to verify that the resharding split is correct. This limits the size of the witness to effectively O(depth) of trie for each trie key in this category.
+This category includes most trie keys like `TrieKey::Account`, `TrieKey::ContractCode`, `TrieKey::PostponedReceipt`, etc. For these keys, we can efficiently split the trie based on the boundary account trie key. We only need to read all the intermediate nodes that form part of the split key. In the example below, if "pass" is the split key, we access all the nodes along the path of `root` ➔ `p` ➔ `a` ➔ `s` ➔ `s`, while not needing to touch other intermediate nodes like `o` ➔ `s` ➔ `t` in key "post". The accessed nodes form part of the state witness, as those are the only nodes needed by validators to verify that the resharding split is correct. This limits the size of the witness to effectively O(depth) of the trie for each trie key in this category.
 
 ![Splitting Trie diagram](assets/nep-0568/NEP-SplitState.png)
 
 #### Singleton TrieKey
 
-This category includes the trie keys `TrieKey::DelayedReceiptIndices`, `TrieKey::PromiseYieldIndices`, `TrieKey::BufferedReceiptIndices`. Notably, these are just a single entry (or O(num_shard) entries) in the trie and hence are small enough to read and modify for the children tries efficiently.
+This category includes the trie keys `TrieKey::DelayedReceiptIndices`, `TrieKey::PromiseYieldIndices`, and `TrieKey::BufferedReceiptIndices`. These are just a single entry (or O(num_shard) entries) in the trie and are small enough to read and modify efficiently for the child tries.
 
 #### Indexed TrieKey
 
-This category includes the trie keys `TrieKey::DelayedReceipt`, `TrieKey::PromiseYieldTimeout` and `TrieKey::BufferedReceipt`. The number of entries for these keys can potentially be arbitrarily large and it's not feasible to iterate through all the entries. In pre-stateless validation world, where we didn't care about state witness size limits, for ReshardingV2 we could just iterate over all delayed receipts and split them into the respective child shards.
-
-For ReshardingV3, these are handled by either of the two strategies
+This category includes the trie keys `TrieKey::DelayedReceipt`, `TrieKey::PromiseYieldTimeout`, and `TrieKey::BufferedReceipt`. The number of entries for these keys can potentially be arbitrarily large, making it infeasible to iterate through all entries. In the pre-stateless validation world, where we didn't care about state witness size limits, for Resharding V2 we could iterate over all delayed receipts and split them into the respective child shards.
 
-* `TrieKey::DelayedReceipt` and `TrieKey::PromiseYieldTimeout` are handled by duplicating entries across both child shards as each entry could belong to either of the child shards. More details in the [Delayed Receipts](#delayed-receipt-handling) and [Promise Yield](#promiseyield-receipt-handling) sections below.
+For Resharding V3, these are handled by one of two strategies:
 
-* `TrieKey::BufferedReceipt` are independent of the account_id and therefore can be sent to either of the child shards, but not both. We copy the buffered receipts and the associated metadata to the child shard with the lower index. More details in the [Buffered Receipts](#buffered-receipt-handling) section below.
+* **Duplication Across Child Shards**: `TrieKey::DelayedReceipt` and `TrieKey::PromiseYieldTimeout` are handled by duplicating entries across both child shards, as each entry could belong to either child shard. More details are in the [Delayed Receipts](#delayed-receipt-handling) and [Promise Yield](#promiseyield-receipt-handling) sections below.
+* **Assignment to Lower Index Child**: `TrieKey::BufferedReceipt` is independent of the `account_id` and can be sent to either of the child shards, but not both. We copy the buffered receipts and the associated metadata to the child shard with the lower index. More details are in the [Buffered Receipts](#buffered-receipt-handling) section below.
 
 ### State Storage - Flat State
 
-Flat State is a collection of key-value pairs stored on disk and each entry
-contains a reference to its ShardId. When splitting a shard, every item inside
-its Flat State must be correctly reassigned to either one of the new children;
-due to technical limitations such operation can't be completed instantaneously.
+Flat State is a collection of key-value pairs stored on disk, with each entry containing a reference to its `ShardId`. When splitting a shard, every item inside its Flat State must be correctly reassigned to one of the new child shards; however, due to technical limitations, such an operation cannot be completed instantaneously.
 
-Flat State main purposes are allowing the creation of State Sync snapshots and
-the construction of Mem Tries. Fortunately, these two operations can be delayed
-until resharding is completed. Note also that with Mem Tries enabled the chain
-can move forward even if the current status of Flat State is not in sync with
-the latest block. 
+Flat State's main purposes are allowing the creation of State Sync snapshots and the construction of Mem Tries. Fortunately, these two operations can be delayed until resharding is completed. Note also that with Mem Tries enabled, the chain can move forward even if the current status of Flat State is not in sync with the latest block.
 
-For the reason stated above, the chosen strategy is to reshard Flat State in a
-long-running background task. The new shards' states must converge with their
-Mem Tries representation in a reasonable amount of time.
+For these reasons, the chosen strategy is to reshard Flat State in a long-running background task. The new shards' states must converge with their Mem Tries representation in a reasonable amount of time.
 
 Splitting a shard's Flat State is performed in multiple steps:
 
-1) A post-processing 'split' task is created during the last block of the old
-   shard layout, instantaneously. 
-2) The 'split' task runs in parallel with the chain for a certain amount of
-   time. Inside this routine every key-value pair belonging to the shard being
-   split (also called parent shard) is copied into either the left or the right
-   child Flat State. Entries linked to receipts are handled in a special way.
-3) Once the task is completed, the parent shard Flat State is cleaned up. The
-   children shards Flat States have their state in sync with last block of the
-   old shard layout.
-4) Children shards must apply the delta changes from the first block of the new
-   shard layout until the final block of the canonical chain. This operation is
-   done in another background task to avoid slowdowns while processing blocks.
-5) Children shards Flat States are now ready and can be used to take State Sync
-   snapshots and to reload Mem Tries.
+1. A post-processing "split" task is created instantaneously during the last block of the old shard layout.
+2. The "split" task runs in parallel with the chain for a certain amount of time. Inside this routine, every key-value pair belonging to the shard being split (also called the parent shard) is copied into either the left or the right child Flat State. Entries linked to receipts are handled in a special way.
+3. Once the task is completed, the parent shard's Flat State is cleaned up. The child shards' Flat States have their state in sync with the last block of the old shard layout.
+4. Child shards must apply the delta changes from the first block of the new shard layout until the final block of the canonical chain. This operation is done in another background task to avoid slowdowns while processing blocks.
+5. Child shards' Flat States are now ready and can be used to take State Sync snapshots and to reload Mem Tries.
 
 ### State Storage - State
 
-Each shard’s Trie is stored in the `State` column of the database, with keys prefixed by `ShardUId`, followed by a node's hash.
-This structure uniquely identifies each shard’s data. To avoid copying all entries under a new `ShardUId` during resharding,
-a mapping strategy allows child shards to access ancestor shard data without directly creating new entries.
+Each shard’s Trie is stored in the `State` column of the database, with keys prefixed by `ShardUId`, followed by a node's hash. This structure uniquely identifies each shard’s data. To avoid copying all entries under a new `ShardUId` during resharding, a mapping strategy allows child shards to access ancestor shard data without directly creating new entries.
 
-A naive approach to resharding would involve copying all `State` entries with a new `ShardUId` for a child shard, effectively duplicating the state.
-This method, while straightforward, is not feasible because copying a large state would take too much time.
-Resharding needs to appear complete between two blocks, so a direct copy would not allow the process to occur quickly enough.
+A naive approach to resharding would involve copying all `State` entries with a new `ShardUId` for a child shard, effectively duplicating the state. This method, while straightforward, is not feasible because copying a large state would take too much time. Resharding needs to appear complete between two blocks, so a direct copy would not allow the process to occur quickly enough.
 
-To address this, Resharding V3 employs an efficient mapping strategy, using the `DBCol::ShardUIdMapping` column
-to link each child shard’s `ShardUId` to the closest ancestor’s `ShardUId` holding the relevant data.
-This allows child shards to access and update state data under the ancestor shard’s prefix without duplicating entries.
+To address this, Resharding V3 employs an efficient mapping strategy, using the `DBCol::ShardUIdMapping` column to link each child shard’s `ShardUId` to the closest ancestor’s `ShardUId` holding the relevant data. This allows child shards to access and update state data under the ancestor shard’s prefix without duplicating entries.
 
-Initially, `ShardUIdMapping` is empty, as existing shards map to themselves. During resharding, a mapping entry is added to `ShardUIdMapping`,
-pointing each child shard’s `ShardUId` to the appropriate ancestor. Mappings persist as long as any descendant shard references the ancestor’s data.
-Once a node stops tracking all children and descendants of a shard, the entry for that shard can be removed, allowing its data to be garbage collected.
+Initially, `ShardUIdMapping` is empty, as existing shards map to themselves. During resharding, a mapping entry is added to `ShardUIdMapping`, pointing each child shard’s `ShardUId` to the appropriate ancestor. Mappings persist as long as any descendant shard references the ancestor’s data. Once a node stops tracking all children and descendants of a shard, the entry for that shard can be removed, allowing its data to be garbage collected.
 
-This mapping strategy enables efficient shard management during resharding events,
-supporting smooth transitions without altering storage structures directly.
+This mapping strategy enables efficient shard management during resharding events, supporting smooth transitions without altering storage structures directly.
 
-#### Integration with cold storage (archival nodes)
+#### Integration with Cold Storage (Archival Nodes)
 
 Cold storage uses the same mapping strategy to manage shard state during resharding:
 
 * When state data is migrated from hot to cold storage, it retains the parent shard’s `ShardUId` prefix, ensuring consistency with the mapping strategy.
-* While copying data for the last block of the epoch where resharding occured, the `DBCol::StateShardUIdMapping` column is copied into cold storage. This ensures that mappings are updated alongside the shard state data.
+* While copying data for the last block of the epoch where resharding occurred, the `DBCol::StateShardUIdMapping` column is copied into cold storage. This ensures that mappings are updated alongside the shard state data.
 * These mappings are permanent in cold storage, aligning with its role in preserving historical state.
 
 This approach minimizes complexity while maintaining consistency across hot and cold storage.
 
 ### Stateless Validation
 
-As only a fraction of nodes track the split shard, there is a need to prove the transition from state root of parent shard 
-to new state roots for children shards to other validators.
-Otherwise the chunk producers for split shard may collude and provide invalid state roots,
-which may compromise the protocol, for example, with minting tokens out of thin air.
+Since only a fraction of nodes track the split shard, it is necessary to prove the transition from the state root of the parent shard to the new state roots for the child shards to other validators. Without this proof, chunk producers for the split shard could collude and provide invalid state roots, potentially compromising the protocol, such as by minting tokens out of thin air.
+
+The design ensures that generating and verifying this state transition is negligible in time compared to applying a chunk. As detailed in the [State Storage - MemTrie](#state-storage---memtrie) section, the generation and verification logic involves a constant number of trie lookups. Specifically, we implement the `retain_split_shard(boundary_account, RetainMode::{Left, Right})` method for the trie, which retains only the keys in the trie that belong to the left or right child shard. Internally, this method uses `retain_multi_range(intervals)`, where `intervals` is a vector of trie key intervals to retain. Each interval corresponds to a unique trie key type prefix byte (`Account`, `AccessKey`, etc.) and defines an interval from the empty key to the `boundary_account` key for the left shard, or from the `boundary_account` to infinity for the right shard.
 
-The design allows to generate and check this state transition in the time, negligible compared to the time it takes to apply chunk.
-As shown above in [State Storage - MemTrie](#state-storage---memtrie) section, generation and verification logic consists of constant number of trie lookups.
-More specifically, we implement `retain_split_shard(boundary_account, RetainMode::{Left, Right})` method for trie, which leaves only keys in trie that
-belong to the left or right child shard. 
-Inside, we implement `retain_multi_range(intervals)` method, where `intervals` is a vector of trie key intervals to retain.
-Each interval corresponds to unique trie key type prefix byte (`Account`, `AccessKey`, etc.) and either defines an interval from empty key to `boundary_account` key for left shard, or from `boundary_account` to infinity for right shard.
-`retain_multi_range` is recursive. Based on current trie key prefix covered by current node, it either:
+The `retain_multi_range` method is recursive. Based on the current trie key prefix covered by the current node, it either:
 
-* returns node back, if subtree is fully contained within some interval;
-* returns "empty" node, if subtree is outside of all intervals;
-* otherwise, descends into all children and constructs new node with children returned by recursive calls.
+* Returns the node if the subtree is fully contained within an interval.
+* Returns an "empty" node if the subtree is outside all intervals.
+* Descends into all children and constructs a new node with children returned by recursive calls.
 
-Implementation is agnostic to the trie storage used for retrieving nodes, it applies to both memtrie and partial storage (state proof). 
+This implementation is agnostic to the trie storage used for retrieving nodes and applies to both MemTries and partial storage (state proof).
 
-* calling it for memtrie generates a proof and new state root;
-* calling it for partial storage generates a new state root. If method doesn't fail with error that node wasn't found in the proof, it means that proof was sufficient, and it remains to compare generated state root with the one proposed by chunk producer.
+* Calling it for MemTrie generates a proof and a new state root.
+* Calling it for partial storage generates a new state root. If the method does not fail with an error indicating that a node was not found in the proof, it means the proof was sufficient, and it remains to compare the generated state root with the one proposed by the chunk producer.
 
 ### State Witness
 
-Resharding state transition becomes one of `implicit_transitions` in `ChunkStateWitness`. It must be validated between processing last chunk (potentially missing) in the old epoch and the first chunk (potentially missing) in the new epoch. `ChunkStateTransition` fields also nicely correspond to the resharding state transition: in `block_hash` we store the hash of the last block of the parent shard, in `base_state` we store the resharding proof, and in `post_state_root` we store the proposed state root.
+The resharding state transition becomes one of the `implicit_transitions` in `ChunkStateWitness`. It must be validated between processing the last chunk (potentially missing) in the old epoch and the first chunk (potentially missing) in the new epoch. The `ChunkStateTransition` fields correspond to the resharding state transition: the `block_hash` stores the hash of the last block of the parent shard, the `base_state` stores the resharding proof, and the `post_state_root` stores the proposed state root.
 
-Note that it leads to **two** state transitions corresponding to the same block hash. On the chunk producer side, the first transition is stored for the `(block_hash, parent_shard_uid)` pair and the second one is stored for the `(block_hash, child_shard_uid)` pair.
+This results in **two** state transitions corresponding to the same block hash. On the chunk producer side, the first transition is stored for the `(block_hash, parent_shard_uid)` pair, and the second one is stored for the `(block_hash, child_shard_uid)` pair.
 
-The chunk validator has all the blocks, so it identifies whether implicit transition corresponds to applying missing chunk or resharding independently. This is implemented in `get_state_witness_block_range`, which iterates from `state_witness.chunk_header.prev_block_hash()` to the block with includes last last chunk for the (parent) shard, if it exists.
+The chunk validator, having all the blocks, identifies whether the implicit transition corresponds to applying a missing chunk or resharding independently. This is implemented in `get_state_witness_block_range`, which iterates from `state_witness.chunk_header.prev_block_hash()` to the block that includes the last chunk for the (parent) shard, if it exists.
 
-Then, on `validate_chunk_state_witness`, if implicit transition corresponds to resharding, chunk validator calls `retain_split_shard` and proves state transition from parent to child shard.
+Then, in `validate_chunk_state_witness`, if the implicit transition corresponds to resharding, the chunk validator calls `retain_split_shard` and proves the state transition from the parent to the child shard.
 
 ### State Sync
 
-Changes to the state sync protocol aren't typically conisdered protocol changes requiring a version bump, since it's concerned with downloading state that isn't present locally, rather than with the rules of execution of blocks and chunks. But it might still be helpful to outline some planned changes to state sync related to resharding.
+Changes to the state sync protocol are not typically considered protocol changes requiring a version bump, as they concern downloading state that is not present locally rather than the rules for executing blocks and chunks. However, it is helpful to outline some planned changes to state sync related to resharding.
 
-When nodes sync state (either because they've fallen far behind the chain, or because they're going to become a chunk producer for a new shard in a future epoch), they first identify a point in the chain they'd like to sync to. Then they download the tries corresponding to that point in the chain and apply all chunks from that point until they're caught up. Currently, the tries downloaded initially are those corresponding to the `prev_state_root` field of the last new chunk before the current epoch's first block. This means the state downloaded is the state at some point in the previous epoch.
+When nodes sync state (either because they have fallen far behind the chain or because they will become a chunk producer for a new shard in a future epoch), they first identify a point in the chain to sync to. They then download the tries corresponding to that point in the chain and apply all chunks from that point until they are caught up. Currently, the tries downloaded initially correspond to the `prev_state_root` field of the last new chunk before the first block of the current epoch. This means the state downloaded is from some point in the previous epoch.
 
-The change we propose is to move the initial state download point to one in the current epoch rather than the previous. This keeps shard IDs consistent throughout the state sync logic, allows some simplification in the resharding implementation, and reduces the size of the state we need to download. Suppose that the previous epoch's shard `S` was split into shards `S'` and `S''` in the current epoch, and that a chunk producer that wasn't tracking shard `S` or any of its children in the current epoch will become a chunk producer for `S'` in the next epoch. Then with the old state sync algorithm, that chunk producer would download the pre-split state for shard `S`. Then when it's done, it would need to perform the resharding that all the other nodes had already done. This isn't a correctness issue, but it simplifies the implementation somewhat if we instead download only the state for shard `S'`, and it allows the node to download only the state belonging to `S'`, which is much smaller.
+The proposed change is to move the initial state download point to one in the current epoch rather than the previous one. This keeps shard IDs consistent throughout the state sync logic, simplifies the resharding implementation, and reduces the size of the state to be downloaded. Suppose the previous epoch's shard `S` was split into shards `S'` and `S''` in the current epoch, and a chunk producer that was not tracking shard `S` or any of its children in the current epoch will become a chunk producer for `S'` in the next epoch. With the old state sync algorithm, that chunk producer would download the pre-split state for shard `S`. Then, when it is done, it would need to perform the resharding that all other nodes had already done. While this is not a correctness issue, it simplifies the implementation if we instead download only the state for shard `S'`, allowing the node to download only the state belonging to `S'`, which is much smaller.
 
-### Cross Shard Traffic
+### Cross-Shard Traffic
 
-When the shard layout changes, it is crucial to handle cross-shard traffic
-correctly, especially in the presence of missing chunks. Care must be taken to
-ensure that no receipt is lost or duplicated. There are two important receipt
-types that need to be considered - the outgoing receipts and the incoming
-receipts.
+When the shard layout changes, it is crucial to handle cross-shard traffic correctly, especially in the presence of missing chunks. Care must be taken to ensure that no receipt is lost or duplicated. There are two important receipt types that need to be considered: outgoing receipts and incoming receipts.
 
-Note - this proposal reuses the approach taken by ReshardingV2. 
+*Note: This proposal reuses the approach taken by Resharding V2.*
 
 #### Outgoing Receipts
 
-Each new chunk in a shard contains a list of outgoing receipts generated during
-the processing of the previous chunk in that shard.
+Each new chunk in a shard contains a list of outgoing receipts generated during the processing of the previous chunk in that shard.
 
-In cases where chunks are missing at the resharding boundary, both child shards
-could theoretically include the outgoing receipts from their shared ancestor
-chunk. However, this naive approach would lead to the duplication of receipts,
-which must be avoided.
+In cases where chunks are missing at the resharding boundary, both child shards could theoretically include the outgoing receipts from their shared ancestor chunk. However, this naive approach would lead to the duplication of receipts, which must be avoided.
 
-The proposed solution is to reassign the outgoing receipts from the parent chunk
-to only one of the child shards. Specifically, the child shard with the lower
-shard ID will claim all outgoing receipts from the parent, while the other child
-will receive none. This ensures that all receipts are processed exactly once. 
+The proposed solution is to reassign the outgoing receipts from the parent chunk to only one of the child shards. Specifically, the child shard with the lower shard ID will claim all outgoing receipts from the parent, while the other child will receive none. This ensures that all receipts are processed exactly once.
 
 #### Incoming Receipts
 
-To process a chunk in a shard, it is necessary to gather all outgoing receipts
-from other shards that are targeted at this shard. These receipts must then be
-included as incoming receipts.
+To process a chunk in a shard, it is necessary to gather all outgoing receipts from other shards that are targeted at this shard. These receipts must then be included as incoming receipts.
 
-In the presence of missing chunks, the new chunk must collect receipts from all
-previous blocks, spanning the period since the last new chunk in this shard.
-This range may cross the resharding boundary.
+In the presence of missing chunks, the new chunk must collect receipts from all previous blocks, spanning the period since the last new chunk in this shard. This range may cross the resharding boundary.
 
-When this occurs, the chunk must also consider receipts that were previously
-targeted at its parent shard. However, it must filter these receipts to include
-only those where the recipient lies within the current shard, discarding those
-where the recipient belongs to the sibling shard in the new shard layout. This
-filtering process ensures that every receipt is processed exactly once and in
-the correct shard. 
+When this occurs, the chunk must also consider receipts that were previously targeted at its parent shard. However, it must filter these receipts to include only those where the recipient lies within the current shard, discarding those where the recipient belongs to the sibling shard in the new shard layout. This filtering process ensures that every receipt is processed exactly once and in the correct shard.
 
 ### Delayed Receipt Handling
 
-The delayed receipts queue contains all incoming receipts that could not be executed as part of a block due to resource constraints like compute cost, gas limits etc. The entries in the delayed receipt queue can belong to any of the accounts as part of the shard. During a resharding event, we ideally need to split the delayed receipts across both the child shards according to the associated account_id with the receipt.
+The delayed receipts queue contains all incoming receipts that could not be executed as part of a block due to resource constraints like compute cost, gas limits, etc. The entries in the delayed receipt queue can belong to any of the accounts within the shard. During a resharding event, we ideally need to split the delayed receipts across both child shards according to the associated `account_id` with the receipt.
 
-The singleton trie key `DelayedReceiptIndices` holds the start_index and end_index associated with the delayed receipt entries for the shard. The trie key `DelayedReceipt { index }` contains the actual delayed receipt associated with some account_id. These are processed in a fifo queue order during chunk execution.
+The singleton trie key `DelayedReceiptIndices` holds the `start_index` and `end_index` associated with the delayed receipt entries for the shard. The trie key `DelayedReceipt { index }` contains the actual delayed receipt associated with some `account_id`. These are processed in a FIFO queue order during chunk execution.
 
-Note that the delayed receipt trie keys do not have the `account_id` prefix. In ReshardingV2, we followed the trivial solution of iterating through all the delayed receipt queue entries and assigning them to the appropriate child shard, however due to constraints on the state witness size limits and instant resharding, this approach is no longer feasible for ReshardingV3.
+Note that the delayed receipt trie keys do not have the `account_id` prefix. In Resharding V2, we followed the trivial solution of iterating through all the delayed receipt queue entries and assigning them to the appropriate child shard. However, due to constraints on the state witness size limits and instant resharding, this approach is no longer feasible for Resharding V3.
 
-For ReshardingV3, we decided to handle the resharding by duplicating the entries of the delayed receipt queue across both the child shards. This is great from the perspective of state witness size and instant resharding as we only need to access the delayed receipt queue root entry in the trie, however it breaks the assumption that all delayed receipts in a shard belong to the accounts within that shard.
+For Resharding V3, we decided to handle the resharding by duplicating the entries of the delayed receipt queue across both child shards. This is beneficial from the perspective of state witness size and instant resharding, as we only need to access the delayed receipt queue root entry in the trie. However, it breaks the assumption that all delayed receipts in a shard belong to the accounts within that shard.
 
-To resolve this, with the new protocol version, we changed the implementation of runtime to discard executing delayed receipts that don't belong to the account_id on that shard.
+To resolve this, with the new protocol version, we changed the implementation of the runtime to discard executing delayed receipts that don't belong to the `account_id` on that shard.
 
-Note that no delayed receipts are lost during resharding as all receipts get executed exactly once based on which of the child shards does the associated account_id belong to.
+Note that no delayed receipts are lost during resharding, as all receipts get executed exactly once based on which of the child shards the associated `account_id` belongs to.
 
 ### PromiseYield Receipt Handling
 
-Promise Yield were introduced as part of NEP-519 to enable defer replying to caller function while response is being prepared. As part of Promise Yield implementation, it introduced three new trie keys, `PromiseYieldIndices`, `PromiseYieldTimeout` and `PromiseYieldReceipt`.
+Promise Yield was introduced as part of NEP-519 to enable deferring replies to the caller function while the response is being prepared. As part of the Promise Yield implementation, it introduced three new trie keys: `PromiseYieldIndices`, `PromiseYieldTimeout`, and `PromiseYieldReceipt`.
 
-* `PromiseYieldIndices`: This is a singleton key that holds the start_index and end_index of the keys in `PromiseYieldTimeout`
-* `PromiseYieldTimeout { index }`: Along with the receiver_id and data_id, this stores the expires_at block height till which we need to wait to receive a response.
+* `PromiseYieldIndices`: This is a singleton key that holds the `start_index` and `end_index` of the keys in `PromiseYieldTimeout`.
+* `PromiseYieldTimeout { index }`: Along with the `receiver_id` and `data_id`, this stores the `expires_at` block height until which we need to wait to receive a response.
 * `PromiseYieldReceipt { receiver_id, data_id }`: This is the receipt created by the account.
 
 An account can call the `promise_yield_create` host function that increments the `PromiseYieldIndices` along with adding a new entry into the `PromiseYieldTimeout` and `PromiseYieldReceipt`.
 
-The `PromiseYieldTimeout` is sorted as per the time of creation and has an increasing value of expires_at block height. In the runtime, we iterate over all the expired receipts and create a blank receipt to resolve the entry in `PromiseYieldReceipt`.
+The `PromiseYieldTimeout` is sorted by time of creation and has an increasing value of `expires_at` block height. In the runtime, we iterate over all the expired receipts and create a blank receipt to resolve the entry in `PromiseYieldReceipt`.
 
-The account can call the `promise_yield_resume` host function multiple times and if this is called before the expiry period, we use this to resolve the promise yield receipt. Note that the implementation allows for multiple resolution receipts to be created, including the expiry receipt, but only the first one is used for the actual resolution of the promise yield receipt.
+The account can call the `promise_yield_resume` host function multiple times, and if this is called before the expiry period, we use this to resolve the promise yield receipt. Note that the implementation allows for multiple resolution receipts to be created, including the expiry receipt, but only the first one is used for the actual resolution of the promise yield receipt.
 
-We use this implementation quirk to facilitate resharding implementation. The resharding strategy for the three trie keys are:
+We use this implementation quirk to facilitate the resharding implementation. The resharding strategy for the three trie keys is:
 
-* `PromiseYieldIndices`: Duplicate across both child shards.
-* `PromiseYieldTimeout { index }`: Duplicate across both child shards.
-* `PromiseYieldReceipt { receiver_id, data_id }`: Since this key has the account_id prefix, we can split the entries across both child shards based on the prefix.
+* **Duplicate Across Both Child Shards**:
+  * `PromiseYieldIndices`
+  * `PromiseYieldTimeout { index }`
+* **Split Based on Prefix**:
+  * `PromiseYieldReceipt { receiver_id, data_id }`: Since this key has the `account_id` prefix, we can split the entries across both child shards based on the prefix.
 
-After duplication of the `PromiseYieldIndices` and `PromiseYieldTimeout`, when the entries of `PromiseYieldTimeout` eventually get dequeued at the expiry height of the following happens:
+After duplication of the `PromiseYieldIndices` and `PromiseYieldTimeout`, when the entries of `PromiseYieldTimeout` eventually get dequeued at the expiry height, the following happens:
 
-* If the promise yield receipt associated with the dequeued entry IS NOT a part of the child trie, we create a timeout resolution receipt and it gets ignored.
-* If the promise yield receipt associated with the dequeued entry IS part of the child trie, the promise yield implementation continues to work as expected.
+* If the promise yield receipt associated with the dequeued entry **is not** part of the child trie, we create a timeout resolution receipt, and it gets ignored.
+* If the promise yield receipt associated with the dequeued entry **is** part of the child trie, the promise yield implementation continues to work as expected.
 
-This means we don't have to make any special changes in the runtime for handling resharding of promise yield receipts.
+This means we don't have to make any special changes in the runtime for handling the resharding of promise yield receipts.
 
 ### Buffered Receipt Handling
 
-Buffered Receipts were introduced as part of NEP-539, cross-shard congestion control. As part of the implementation, it introduced two new trie keys, `BufferedReceiptIndices` and `BufferedReceipt`.
+Buffered Receipts were introduced as part of NEP-539 for cross-shard congestion control. As part of the implementation, it introduced two new trie keys: `BufferedReceiptIndices` and `BufferedReceipt`.
 
-* `BufferedReceiptIndices`: This is a singleton key that holds the start_index and end_index of the keys in `BufferedReceipt` for each shard_id.
-* `BufferedReceipt { receiving_shard, index }`: This holds the actual buffered receipt that needs to be sent to the receiving_shard.
+* `BufferedReceiptIndices`: This is a singleton key that holds the `start_index` and `end_index` of the keys in `BufferedReceipt` for each `shard_id`.
+* `BufferedReceipt { receiving_shard, index }`: This holds the actual buffered receipt that needs to be sent to the `receiving_shard`.
 
-Note that the targets of the buffered receipts belong to external shards and during a resharding event, we would need to handle both, the set of buffered receipts in the parent shard, as well as the set of buffered receipts in other shards that target the parent shard.
+Note that the targets of the buffered receipts belong to external shards, and during a resharding event, we would need to handle both the set of buffered receipts in the parent shard and the set of buffered receipts in other shards that target the parent shard.
 
-#### Handling buffered receipts in parent shard
+#### Handling Buffered Receipts in Parent Shard
 
-Since buffered receipts target external shards, it is fine to assign buffered receipts to either of the child shards. For simplicity, we assign all the buffered receipts to the child shard with the lower index, i.e. copy `BufferedReceiptIndices` and `BufferedReceipt` to the child shard with lower index while keeping `BufferedReceiptIndices` as empty for child shard with higher index.
+Since buffered receipts target external shards, it is acceptable to assign buffered receipts to either of the child shards. For simplicity, we assign all the buffered receipts to the child shard with the lower index, i.e., copy `BufferedReceiptIndices` and `BufferedReceipt` to the child shard with the lower index while keeping `BufferedReceiptIndices` empty for the child shard with the higher index.
 
-#### Handling buffered receipts that target parent shard
+#### Handling Buffered Receipts that Target Parent Shard
 
-This scenario is slightly more complex to deal with. At the boundary of resharding, we may have buffered receipts created before the resharding event targeting the parent shard. At the same time, we may also have buffered receipts that are generated after the resharding event that directly target the child shard. The receipts from both parent and child buffered receipts queue need to appropriately sent to the child shard depending on the account_id while respecting the outgoing limits calculated by bandwidth scheduler and congestion control. 
+This scenario is slightly more complex. At the boundary of resharding, we may have buffered receipts created before the resharding event targeting the parent shard. At the same time, we may also have buffered receipts generated after the resharding event that directly target the child shard. The receipts from both the parent and child buffered receipts queue need to be appropriately sent to the child shard depending on the `account_id`, while respecting the outgoing limits calculated by the bandwidth scheduler and congestion control.
 
-The flow of handling buffered receipts before ReshardingV3 is as follows:
+The flow of handling buffered receipts before Resharding V3 is as follows:
 
 1. Calculate `outgoing_limit` for each shard.
-2. For each shard, try and forward as many in-order receipts as possible from the buffer while respecting `outgoing_limit`.
-3. Apply chunk and `try_forward` newly generated receipts. The newly generated receipts are forwarded if we have enough limit else they are put in the buffered queue.
+2. For each shard, try to forward as many in-order receipts as possible from the buffer while respecting `outgoing_limit`.
+3. Apply chunk and `try_forward` newly generated receipts. The newly generated receipts are forwarded if we have enough limit; otherwise, they are put in the buffered queue.
 
-The solution for ReshardingV3 is to first try draining the parent queue before moving onto draining the child queue. The modified flow would look something like:
+The solution for Resharding V3 is to first try draining the parent queue before moving on to draining the child queue. The modified flow would look like this:
 
-1. Calculate `outgoing_limit` for both the child shards using congestion info from parent.
-2. Forwarding receipts
-    * First try forward as many in-order receipts as possible from parent shard buffer. Stop either when we drain the parent buffer or as soon as we exhaust the `outgoing_limit` of either of the children shards.
-    * Next try forward as many in-order receipts as possible from child shard buffer.
-3. Apply chunk and `try_forward` newly generated receipts remains the same.
+1. Calculate `outgoing_limit` for both child shards using congestion info from the parent.
+2. Forwarding receipts:
+    * First, try to forward as many in-order receipts as possible from the parent shard buffer. Stop either when we drain the parent buffer or when we exhaust the `outgoing_limit` of either of the child shards.
+    * Next, try to forward as many in-order receipts as possible from the child shard buffer.
+3. Applying chunk and `try_forward` newly generated receipts remains the same.
 
-The minor downside to this approach is that we don't have guarantees between order of receipt generation and order of receipt forwarding, but that's anyway the case today with buffered receipts.
+The minor downside to this approach is that we don't have guarantees between the order of receipt generation and the order of receipt forwarding, but that's already the case today with buffered receipts.
 
 ### Congestion Control
 
-Along with having buffered receipts, each chunk also publishes a CongestionInfo to the chunk header that has information about the congestion of the shard as of processing block.
+Along with having buffered receipts, each chunk also publishes a `CongestionInfo` to the chunk header that contains information about the congestion of the shard during block processing.
 
 ```rust
 pub struct CongestionInfoV1 {
@@ -343,165 +263,150 @@ pub struct CongestionInfoV1 {
 }
 ```
 
-After a resharding event, we need to properly initialize the congestion info for the child shards. Here's how we handle each of the fields
+After a resharding event, it is essential to properly initialize the congestion info for the child shards. Here is how each field is handled:
 
-#### delayed_receipts_gas
+#### `delayed_receipts_gas`
 
-Since the resharding strategy for delayed receipts is to duplicate them across both the child shards, we simply copy the value of `delayed_receipts_gas` across both shards.
+Since the resharding strategy for delayed receipts is to duplicate them across both child shards, we simply copy the value of `delayed_receipts_gas` to both shards.
 
-#### buffered_receipts_gas
+#### `buffered_receipts_gas`
 
-Since the resharding strategy for buffered receipts is to assign all the buffered receipts to the lower index child, we copy the `buffered_receipts_gas` from parent to lower index child and set `buffered_receipts_gas` to zero for upper index child.
+Given that the strategy for buffered receipts is to assign all buffered receipts to the lower index child, we copy the `buffered_receipts_gas` from the parent to the lower index child and set `buffered_receipts_gas` to zero for the higher index child.
 
-#### receipt_bytes
+#### `receipt_bytes`
 
-This field is harder to deal with as it contains the information from both delayed receipts and buffered receipts. To calculate this field properly, we would need the distribution of the receipt_bytes across both delayed receipts and buffered receipts. The current solution is to start storing metadata about the total `receipt_bytes` for buffered receipts in the trie. This way we have the following:
+This field is more complex as it includes information from both delayed receipts and buffered receipts. To calculate this field accurately, we need to know the distribution of `receipt_bytes` across both delayed receipts and buffered receipts. The current solution is to store metadata about the total `receipt_bytes` for buffered receipts in the trie. This way, we have the following:
 
-* For child with lower index, receipt_bytes is the sum of both delayed receipts bytes and congestion control bytes, hence `receipt_bytes = parent.receipt_bytes`
-* For child with upper index, receipt_bytes is just the bytes from delayed receipts, hence `receipt_bytes = parent.receipt_bytes - buffered_receipt_bytes`
+* For the child with the lower index, `receipt_bytes` is the sum of both delayed receipts bytes and buffered receipts bytes, hence `receipt_bytes = parent.receipt_bytes`.
+* For the child with the higher index, `receipt_bytes` is just the bytes from delayed receipts, hence `receipt_bytes = parent.receipt_bytes - parent.buffered_receipt_bytes`.
 
-#### allowed_shard
+#### `allowed_shard`
 
-This field is calculated by a round-robin mechanism which can be independently calculated for both the child shards. Since we are changing the [ShardId semantics](#shardid-semantics), we need to change implementation to use `ShardIndex` instead of `ShardID` which is just an assignment for each shard_id to the contiguous index `[0, num_shards)`.
+This field is calculated using a round-robin mechanism, which can be independently determined for both child shards. Since we are changing the [ShardId semantics](#shardid-semantics), we need to update the implementation to use `ShardIndex` instead of `ShardID`, which is simply an assignment for each `shard_id` to the contiguous index `[0, num_shards)`.
 
 ### ShardId Semantics
 
-Currently, shard IDs are represented as numbers within the range `[0,n)`, where n is the total number of shards. These shard IDs are sorted in the same order as the account ID ranges assigned to them. While this approach is straightforward, it complicates resharding operations, particularly when splitting a shard in the middle of the range. Such a split requires reindexing all subsequent shards with higher IDs, adding complexity to the process.
+Currently, shard IDs are represented as numbers within the range `[0, n)`, where `n` is the total number of shards. These shard IDs are sorted in the same order as the account ID ranges assigned to them. While this approach is straightforward, it complicates resharding operations, particularly when splitting a shard in the middle of the range. Such a split requires reindexing all subsequent shards with higher IDs, adding complexity to the process.
 
-In this NEP, we propose updating the ShardId semantics to allow for arbitrary identifiers. Although ShardIds will remain integers, they will no longer be restricted to the `[0,n)` range, and they may appear in any order. The only requirement is that each ShardId must be unique. In practice, during resharding, the ID of a parent shard will be removed from the ShardLayout, and the new child shards will be assigned unique IDs - `max(shard_ids)+1` and `max(shard_ids)+2`.
+In this NEP, we propose updating the ShardId semantics to allow for arbitrary identifiers. Although ShardIds will remain integers, they will no longer be restricted to the `[0, n)` range, and they may appear in any order. The only requirement is that each ShardId must be unique. In practice, during resharding, the ID of a parent shard will be removed from the ShardLayout, and the new child shards will be assigned unique IDs - `max(shard_ids) + 1` and `max(shard_ids) + 2`.
 
 ## Reference Implementation
 
 ### Overview
 <!-- markdownlint-disable MD029 -->
 
-1. Any node tracking shard must determine if it should split shard in the last block before the epoch where resharding should happen.
+1. Any node tracking a shard must determine if it should split the shard in the last block before the epoch where resharding should happen.
 
 ```pseudocode
 should_split_shard(block, shard_id):
-  shard_layout = epoch_manager.shard_layout(block.epoch_id())
-  next_shard_layout = epoch_manager.shard_layout(block.next_epoch_id())
-  if epoch_manager.is_next_block_epoch_start(block) && 
-    shard_layout != next_shard_layout &&
-    next_shard_layout.shard_split_map().contains(shard_id):
-    return Some(next_shard_layout.split_shard_event(shard_id))
-  return None
+    shard_layout = epoch_manager.shard_layout(block.epoch_id())
+    next_shard_layout = epoch_manager.shard_layout(block.next_epoch_id())
+    if epoch_manager.is_next_block_epoch_start(block) && 
+        shard_layout != next_shard_layout &&
+        next_shard_layout.shard_split_map().contains(shard_id):
+        return Some(next_shard_layout.split_shard_event(shard_id))
+    return None
 ```
 
-2. This logic is triggered on block postprocessing, which means that block is valid and is being persisted to disk.
+2. This logic is triggered during block post-processing, which means that the block is valid and is being persisted to disk.
 
 ```pseudocode
 on chain.postprocess_block(block):
-  next_shard_layout = epoch_manager.shard_layout(block.next_epoch_id())
-  if let Some(split_shard_event) = should_split_shard(block, shard_id):
-    resharding_manager.split_shard(split_shard_event)
+    next_shard_layout = epoch_manager.shard_layout(block.next_epoch_id())
+    if let Some(split_shard_event) = should_split_shard(block, shard_id):
+        resharding_manager.split_shard(split_shard_event)
 ```
 
 3. The event triggers changes in all state storage components.
 
 ```pseudocode
 on resharding_manager.split_shard(split_shard_event, next_shard_layout):
-  set State mapping
-  start FlatState resharding
-  process MemTrie resharding:
-    freeze MemTrie, create HybridMemTries
-    for each child shard:
-      mem_tries[parent_shard].retain_split_shard(boundary_account)
+    set State mapping
+    start FlatState resharding
+    process MemTrie resharding:
+        freeze MemTrie, create HybridMemTries
+        for each child shard:
+            mem_tries[parent_shard].retain_split_shard(boundary_account)
 ```
 
-4. `retain_split_shard` leaves only keys in trie that belong to the left or right child shard. 
-It retains trie key intervals for left or right child as described above. Simultaneously the proof is generated.
-In the end, we get new state root, hybrid memtrie corresponding to child shard, and the proof.
-Proof is saved as state transition for pair `(block, new_shard_uid)`.
+4. `retain_split_shard` leaves only keys in the trie that belong to the left or right child shard. It retains trie key intervals for the left or right child as described above. Simultaneously, the proof is generated. In the end, we get a new state root, hybrid MemTrie corresponding to the child shard, and the proof. Proof is saved as state transition for pair `(block, new_shard_uid)`.
 
-5. The proof is sent as one of implicit transitions in ChunkStateWitness.
+5. The proof is sent as one of the implicit transitions in `ChunkStateWitness`.
 
-6. On chunk validation path, chunk validator understands if resharding is 
-a part of state transition, using the same `should_split_shard` condition.
+6. On the chunk validation path, the chunk validator determines if resharding is part of the state transition using the same `should_split_shard` condition.
 
-7. It calls `Trie(state_transition_proof).retain_split_shard(boundary_account)` 
-which should succeed if proof is sufficient and generates new state root.
+7. It calls `Trie(state_transition_proof).retain_split_shard(boundary_account)`, which should succeed if the proof is sufficient and generates a new state root.
 
-8. Finally, it checks that the new state root matches the state root proposed in `ChunkStateWitness`.
-If the whole `ChunkStateWitness` is valid, then chunk validator sends endorsement which also endorses the resharding.
+8. Finally, it checks that the new state root matches the state root proposed in `ChunkStateWitness`. If the whole `ChunkStateWitness` is valid, then the chunk validator sends an endorsement, which also endorses the resharding.
 
 ### State Storage - MemTrie
 
-The current implementation of MemTrie uses a pool of memory (`STArena`) to allocate and deallocate nodes and internal pointers in this pool to reference child nodes. MemTries, unlike the State representation of Trie, do not work with the hash of the nodes but internal memory pointers directly. Additionally, MemTries are not thread safe and one MemTrie exists per shard.
+The current implementation of MemTrie uses a memory pool (`STArena`) to allocate and deallocate nodes, with internal pointers in this pool referencing child nodes. Unlike the State representation of the Trie, MemTries do not work with node hashes but with internal memory pointers directly. Additionally, MemTries are not thread-safe, and one MemTrie exists per shard.
 
-As described in [MemTrie](#state-storage---memtrie) section above, we need an efficient way to split the MemTrie into two child MemTries within a span of 1 block. What makes this challenging is that the current implementation of MemTrie is not thread safe and can not be shared across two shards.
+As described in the [MemTrie](#state-storage---memtrie) section above, we need an efficient way to split the MemTrie into two child MemTries within the span of one block. The challenge lies in the current implementation of MemTrie, which is not thread-safe and cannot be shared across two shards.
 
-The naive way to create two MemTries for the child shards would be to iterate through all the entries of the parent MemTrie and fill in these values into the child MemTries. This however is prohibitively time consuming.
+A naive approach to creating two MemTries for the child shards would involve iterating through all entries of the parent MemTrie and populating these values into the child MemTries. However, this method is prohibitively time-consuming.
 
-The solution to this problem was to introduce the concept of Frozen MemTrie (with a `FrozenArena`) which is a cloneable, read-only, thread-safe snapshot of a MemTrie. We can call the `freeze` method on an existing MemTrie that converts it into a Frozen MemTrie. Note that this process consumes the original MemTrie and we can no longer allocate and deallocate nodes to it.
+The solution to this problem is to introduce the concept of a Frozen MemTrie (with a `FrozenArena`), which is a cloneable, read-only, thread-safe snapshot of a MemTrie. By calling the `freeze` method on an existing MemTrie, we convert it into a Frozen MemTrie. This process consumes the original MemTrie, making it no longer available for node allocation and deallocation.
 
-Along with `FrozenArena`, we also introduce a `HybridArena` which is effectively a base made of `FrozenArena` with a top layer of `STArena` where we support allocating and deallocating new nodes into the MemTrie. Newly allocated nodes can reference/point to nodes in the `FrozenArena`. We use this Hybrid MemTrie as a temporary MemTrie while the flat storage is being constructed in the background.
+Along with `FrozenArena`, we also introduce a `HybridArena`, which effectively combines a base `FrozenArena` with a top layer of `STArena` that supports allocating and deallocating new nodes into the MemTrie. Newly allocated nodes can reference nodes in the `FrozenArena`. This Hybrid MemTrie serves as a temporary MemTrie while the flat storage is being constructed in the background.
 
-While Frozen MemTries provide the benefits of being compatible with instant resharding, they come at the cost of memory consumption. Once a MemTrie is frozen, since it doesn't support deallocation of memory, it continues to consume as much memory as it did at the time of freezing. In case a node is tracking only one of the child shards, a Frozen MemTrie would continue to use the same amount of memory as the parent trie. Due to this, Hybrid MemTries are only a temporary solution and we rebuild the MemTrie for the children once the post-processing step for Flat Storage is completed.
+While Frozen MemTries facilitate instant resharding, they come at the cost of memory consumption. Once a MemTrie is frozen, it continues to consume the same amount of memory as it did at the time of freezing, as it does not support memory deallocation. If a node tracks only one of the child shards, a Frozen MemTrie would continue to use the same amount of memory as the parent trie. Therefore, Hybrid MemTries are only a temporary solution, and we rebuild the MemTrie for the children after resharding is completed.
 
-Additionally, a node would have to support 2x the memory footprint of a single trie as after resharding, we would have two copies of the trie in memory, one from the temporary Hybrid MemTrie in use for block production, and other from the background MemTrie that would be under construction. Once the background MemTrie is fully constructed and caught up with the latest block, we do an in-place swap of the Hybrid MemTrie with the new child MemTrie and deallocate the memory from the Hybrid MemTrie.
+Additionally, a node would need to support twice the memory footprint of a single trie. After resharding, there would be two copies of the trie in memory: one from the temporary Hybrid MemTrie used for block production and another from the background MemTrie under construction. Once the background MemTrie is fully constructed and caught up with the latest block, we perform an in-place swap of the Hybrid MemTrie with the new child MemTrie and deallocate the memory from the Hybrid MemTrie.
 
-During a resharding event, at the boundary of the epoch, when we need to split the parent shard into the two child shards, we do the following steps:
+During a resharding event at the epoch boundary, when we need to split the parent shard into two child shards, we follow these steps:
 
-1. Freeze the parent MemTrie arena to create a read-only frozen arena that represents a snapshot of the state as of the time of freezing, i.e. after postprocessing last block of epoch. Note that we no longer require the parent MemTrie in runtime going forward.
-2. We cheaply clone the Frozen MemTrie for both the child MemTries to use. Note that this doesn't clone the parent arena memory, but just increases the refcount.
-3. We then create a new MemTrie with HybridArena for each of the children. The base of the MemTrie is the read-only FrozenArena while all new node allocations happens on a dedicated STArena memory pool for each child MemTrie. This is the temporary MemTrie that we use while Flat Storage is being built in the background.
-4. Once the Flat Storage is constructed in the post processing step of resharding, we use that to load a new MemTrie and catchup to the latest block.
-5. After the new child MemTrie has caught up to the latest block, we do an in-place swap in Client and discard the Hybrid MemTrie.
+1. **Freeze the Parent MemTrie**: Create a read-only frozen arena representing a snapshot of the state at the time of freezing (after post-processing the last block of the epoch). The parent MemTrie is no longer required in runtime going forward.
+2. **Clone the Frozen MemTrie**: Clone the Frozen MemTrie cheaply for both child MemTries to use. This does not clone the parent arena's memory but merely increases the reference count.
+3. **Create Hybrid MemTries for Each Child**: Create a new MemTrie with `HybridArena` for each child. The base of the MemTrie is the read-only `FrozenArena`, while all new node allocations occur in a dedicated `STArena` memory pool for each child MemTrie. This temporary MemTrie is used while Flat Storage is being built in the background.
+4. **Rebuild MemTrie**: Once resharding is completed, we use it to load a new MemTrie and catch up to the latest block.
+5. **Swap and Clean Up**: After the new child MemTrie has caught up to the latest block, we perform an in-place swap in the client and discard the Hybrid MemTrie.
 
 ![Hybrid MemTrie diagram](assets/nep-0568/NEP-HybridMemTrie.png)
 
 ### State Storage - Flat State
 
-Resharding Flat State is a time consuming operation and it runs in parallel with block processing for several block heights.
-Thus, there are a few important aspects to consider during implementation:
+Resharding the Flat State is a time-consuming operation that runs in parallel with block processing for several block heights. Therefore, several important aspects must be considered during implementation:
 
-* Flat State's own status should be resilient to application crashes.
-* The parent shard's Flat State should be split at the correct block height.
-* New shards' Flat States should eventually converge to same representation the chain is using to process blocks (MemTries).
-* Resharding should work correctly in the presence of chain forks.
-* Retired shards are cleaned up.
+* **Flat State's Status Persistence**: Flat State's status should be resilient to application crashes.
+* **Correct Block Height**: The parent shard's Flat State should be split at the correct block height.
+* **Convergence with Mem Trie**: New shards' Flat States should eventually converge to the same representation the chain uses to process blocks (MemTries).
+* **Chain Forks Handling**: Resharding should work correctly in the presence of chain forks.
+* **Retired Shards Cleanup**: Retired shards should be cleaned up.
 
-Note that the Flat States of the newly created shards won't be available until resharding is completed. This is fine because the temporary MemTries are
-built instantly and they can satisfy all block processing needs.
+Note that the Flat States of the newly created shards will not be available until resharding is completed. This is acceptable because the temporary MemTries are built instantly and can satisfy all block processing needs.
 
-The main component responsible to carry out resharding on Flat State is the [FlatStorageResharder](https://github.com/near/nearcore/blob/f4e9dd5d6e07089dfc789221ded8ec83bfe5f6e8/chain/chain/src/flat_storage_resharder.rs#L68).
+The main component responsible for carrying out resharding on Flat State is the [FlatStorageResharder](https://github.com/near/nearcore/blob/f4e9dd5d6e07089dfc789221ded8ec83bfe5f6e8/chain/chain/src/flat_storage_resharder.rs#L68).
 
-#### Flat State's status persistence
+#### Flat State's Status Persistence
 
-Every shard Flat State has a status associated to it and stored in the database, called `FlatStorageStatus`. We propose to extend the existing object
-by adding the new enum variant named `FlatStorageStatus::Resharding`. This approach has two benefits. First, the progress of any Flat State resharding is
-persisted to disk, which makes the operation resilient to a node crash or restart. Second, resuming resharding on node restart shares the same code path as Flat
-State creation (see `FlatStorageShardCreator`), reducing the code duplication factor.
+Every shard's Flat State has a status associated with it and stored in the database, called `FlatStorageStatus`. We propose extending the existing object by adding a new enum variant named `FlatStorageStatus::Resharding`. This approach has two benefits. First, the progress of any Flat State resharding is persisted to disk, making the operation resilient to a node crash or restart. Second, resuming resharding on node restart shares the same code path as Flat State creation (see `FlatStorageShardCreator`), reducing code duplication.
 
-`FlatStorageStatus` is updated at every committable step of resharding. The commit points are the following:
+`FlatStorageStatus` is updated at every committable step of resharding. The commit points are as follows:
 
-* Beginning of resharding or, in other words, the last block of the old shard layout.
-* Scheduling of the _"split parent shard"_ task.
-* Execution, cancellation or failure of the _"split parent shard"_ task.
-* Execution or failure of any _"child catchup"_ task.
+* Beginning of resharding, at the last block of the old shard layout.
+* Scheduling of the "split parent shard" task.
+* Execution, cancellation, or failure of the "split parent shard" task.
+* Execution or failure of any "child catchup" task.
 
-#### Splitting a shard Flat State
+#### Splitting a Shard's Flat State
 
-When, at the end of an epoch, the shard layout changes we identify a so called _resharding block_ that corresponds to the last block of the current epoch.
-A task to split the parent shard's Flat State is scheduled to happen after the _resharding block_ becomes final. The reason to wait for the finality condition
-is to avoid a split on a block that might be excluded from the canonical chain; needless to say, such situation would lock the node
-into an erroneous state.
+When the shard layout changes at the end of an epoch, we identify a **resharding block** corresponding to the last block of the current epoch. A task to split the parent shard's Flat State is scheduled to occur after the resharding block becomes final. The finality condition is necessary to avoid splitting on a block that might be excluded from the canonical chain, which would lock the node into an erroneous state.
 
-Inside the split task we iterate over the Flat State and copy each element into either child. This routine is performed in batches in order to lessen the performance 
-impact on the node.
+Inside the split task, we iterate over the Flat State and copy each element into either child. This routine is performed in batches to lessen the performance impact on the node.
 
-Finally, if the split completes successfully, the parent shard Flat State is removed from the database and the children Flat States enter a catch-up phase.
+Finally, if the split completes successfully, the parent shard's Flat State is removed from the database, and the child shards' Flat States enter a catch-up phase.
 
-One current technical limitation is that, upon a node crash or restart, the _"split parent shard"_ task will start copying all elements again from the beginning.
+One current technical limitation is that, upon a node crash or restart, the "split parent shard" task will start copying all elements again from the beginning.
 
 A reference implementation of splitting a Flat State can be found in [FlatStorageResharder::split_shard_task](https://github.com/near/nearcore/blob/fecce019f0355cf89b63b066ca206a3cdbbdffff/chain/chain/src/flat_storage_resharder.rs#L295).
 
-#### Values assignment from parent to child shards
+#### Assigning Values from Parent to Child Shards
 
-Key-value pairs in the parent shard Flat State are inherited by children according to the rules stated below.
+Key-value pairs in the parent shard's Flat State are inherited by children according to the following rules:
 
-Elements inherited by the child shard which tracks the `account_id` contained in the key:
+**Elements inherited by the child shard tracking the `account_id` contained in the key:**
 
 * `ACCOUNT`
 * `CONTRACT_DATA`
@@ -513,51 +418,45 @@ Elements inherited by the child shard which tracks the `account_id` contained in
 * `POSTPONED_RECEIPT`
 * `PROMISE_YIELD_RECEIPT`
 
-Elements inherited by both children:
+**Elements inherited by both children:**
 
 * `DELAYED_RECEIPT_OR_INDICES`
 * `PROMISE_YIELD_INDICES`
 * `PROMISE_YIELD_TIMEOUT`
 * `BANDWIDTH_SCHEDULER_STATE`
 
-Elements inherited only be the lowest index child:
+**Elements inherited only by the lowest index child:**
 
 * `BUFFERED_RECEIPT_INDICES`
 * `BUFFERED_RECEIPT`
 
-#### Bring children shards up to date with the chain's head
+#### Bringing Child Shards Up to Date with the Chain's Head
 
-Children shards' Flat States build a complete view of their content at the height of the `resharding block` sometime during the new epoch 
-after resharding. At that point in time many new blocks have been processed already, and these will most likely contain updates for the new shards. A catch-up step is necessary to apply all Flat State deltas accumulated until now.
+Child shards' Flat States build a complete view of their content at the height of the resharding block sometime during the new epoch after resharding. At that point, many new blocks have already been processed, and these will most likely contain updates for the new shards. A catch-up step is necessary to apply all Flat State deltas accumulated until now.
 
-This phase of resharding doesn't have to take extra steps to handle chain forks. On one hand, the catch-up task doesn't start until the parent shard 
-splitting is done, and at such point we know the `resharding block` is final; on the other hand, Flat State deltas are capable of handling forks automatically.
+This phase of resharding does not require extra steps to handle chain forks. The catch-up task does not start until the parent shard splitting is done, ensuring the resharding block is final. Additionally, Flat State deltas can handle forks automatically.
 
-The catch-up task commits to the database "batches" of Flat State deltas. If the application crashes or restarts the task will resume from where it left.
+The catch-up task commits batches of Flat State deltas to the database. If the application crashes or restarts, the task will resume from where it left off.
 
-Once all Flat State deltas are applied, the child shard's status is changed to `Ready` and clean up of Flat State deltas leftovers is performed. 
+Once all Flat State deltas are applied, the child shard's status is changed to `Ready`, and cleanup of Flat State delta leftovers is performed.
 
 A reference implementation of the catch-up task can be found in [FlatStorageResharder::shard_catchup_task](https://github.com/near/nearcore/blob/fecce019f0355cf89b63b066ca206a3cdbbdffff/chain/chain/src/flat_storage_resharder.rs#L564).
 
-#### Failure of Flat State resharding
+#### Failure of Flat State Resharding
 
-In the current proposal any failure during Flat State resharding is considered non-recoverable. 
-`neard` will attempt resharding again on restart, but no automatic recovery is implemented.
+In the current proposal, any failure during Flat State resharding is considered non-recoverable. `neard` will attempt resharding again on restart, but no automatic recovery is implemented.
 
-### State Storage - State mapping
+### State Storage - State Mapping
 
-To enable efficient shard state management during resharding, Resharding V3 uses the `DBCol::ShardUIdMapping` column.
-This mapping allows child shards to reference ancestor shard data, avoiding the need for immediate duplication of state entries. 
+To enable efficient shard state management during resharding, Resharding V3 uses the `DBCol::ShardUIdMapping` column. This mapping allows child shards to reference ancestor shard data, avoiding the need for immediate duplication of state entries.
 
-#### Mapping application in adapters
+#### Mapping Application in Adapters
 
-The core of the mapping logic is applied in `TrieStoreAdapter` and `TrieStoreUpdateAdapter`, which act as layers over the general `Store` interface.
-Here’s a breakdown of the key functions involved:
+The core of the mapping logic is applied in `TrieStoreAdapter` and `TrieStoreUpdateAdapter`, which act as layers over the general `Store` interface. Here’s a breakdown of the key functions involved:
 
-* **Key resolution**:
-  The `get_key_from_shard_uid_and_hash` function is central to determining the correct `ShardUId` for state access.
-  At a high level, operations use the child shard's `ShardUId`, but within this function,
-  the `DBCol::ShardUIdMapping` column is checked to determine if an ancestor `ShardUId` should be used instead.
+* **Key Resolution**:
+
+  The `get_key_from_shard_uid_and_hash` function is central to determining the correct `ShardUId` for state access. At a high level, operations use the child shard's `ShardUId`, but within this function, the `DBCol::ShardUIdMapping` column is checked to determine if an ancestor `ShardUId` should be used instead.
 
   ```rust
   fn get_key_from_shard_uid_and_hash(
@@ -576,41 +475,37 @@ Here’s a breakdown of the key functions involved:
   }
   ```
 
-  This function first attempts to retrieve a mapped ancestor `ShardUId` from `DBCol::ShardUIdMapping`.
-  If no mapping exists, it defaults to the provided child `ShardUId`.
-  This resolved `ShardUId` is then combined with the `node_hash` to form the final key used in `State` column operations.
+  This function first attempts to retrieve a mapped ancestor `ShardUId` from `DBCol::ShardUIdMapping`. If no mapping exists, it defaults to the provided child `ShardUId`. This resolved `ShardUId` is then combined with the `node_hash` to form the final key used in `State` column operations.
+
+* **State Access Operations**:
 
-* **State access operations**:
-  The `TrieStoreAdapter` and `TrieStoreUpdateAdapter` use `get_key_from_shard_uid_and_hash` to correctly resolve the key for both reads and writes.
-  Example methods include:
+  The `TrieStoreAdapter` and `TrieStoreUpdateAdapter` use `get_key_from_shard_uid_and_hash` to correctly resolve the key for both reads and writes. Example methods include:
 
-   ```rust
-   // In TrieStoreAdapter
-   pub fn get(&self, shard_uid: ShardUId, hash: &CryptoHash) -> Result<Arc<[u8]>, StorageError> {
+  ```rust
+  // In TrieStoreAdapter
+  pub fn get(&self, shard_uid: ShardUId, hash: &CryptoHash) -> Result<Arc<[u8]>, StorageError> {
       let key = get_key_from_shard_uid_and_hash(self.store, shard_uid, hash);
       self.store.get(DBCol::State, &key)
-   }
+  }
 
-   // In TrieStoreUpdateAdapter
-   pub fn increment_refcount_by(
+  // In TrieStoreUpdateAdapter
+  pub fn increment_refcount_by(
       &mut self,
       shard_uid: ShardUId,
       hash: &CryptoHash,
       data: &[u8],
       increment: NonZero<u32>,
-   ) {
+  ) {
       let key = get_key_from_shard_uid_and_hash(self.store, shard_uid, hash);
       self.store_update.increment_refcount_by(DBCol::State, key.as_ref(), data, increment);
-   }
-   ```
+  }
+  ```
 
-  The `get` function retrieves data using the resolved `ShardUId` and key, while `increment_refcount_by` manages reference counts,
-  ensuring correct tracking even when accessing data under an ancestor shard.
+  The `get` function retrieves data using the resolved `ShardUId` and key, while `increment_refcount_by` manages reference counts, ensuring correct tracking even when accessing data under an ancestor shard.
 
-#### Mapping retention and cleanup
+#### Mapping Retention and Cleanup
 
-Mappings in `DBCol::ShardUIdMapping` persist as long as any descendant relies on an ancestor’s data.
-To manage this, the `set_shard_uid_mapping` function in `TrieStoreUpdateAdapter` adds a new mapping during resharding:
+Mappings in `DBCol::ShardUIdMapping` persist as long as any descendant relies on an ancestor’s data. To manage this, the `set_shard_uid_mapping` function in `TrieStoreUpdateAdapter` adds a new mapping during resharding:
 
 ```rust
 fn set_shard_uid_mapping(&mut self, child_shard_uid: ShardUId, parent_shard_uid: ShardUId) {
@@ -622,59 +517,57 @@ fn set_shard_uid_mapping(&mut self, child_shard_uid: ShardUId, parent_shard_uid:
 }
 ```
 
-When a node stops tracking all descendants of a shard, the associated mapping entry can be removed, allowing RocksDB to perform garbage collection.
-For archival nodes, mappings are retained permanently to ensure access to the historical state of all shards.
+When a node stops tracking all descendants of a shard, the associated mapping entry can be removed, allowing RocksDB to perform garbage collection. For archival nodes, mappings are retained permanently to ensure access to the historical state of all shards.
 
-This implementation ensures efficient and scalable shard state transitions,
-allowing child shards to use ancestor data without creating redundant entries.
+This implementation ensures efficient and scalable shard state transitions, allowing child shards to use ancestor data without creating redundant entries.
 
 ### State Sync
 
-The state sync algorithm defines a `sync_hash` that is used in many parts of the implementation. This is always the first block of the current epoch, which the node should be aware of once it has synced headers to the current point in the chain. A node performing state sync first makes a request (currently to centralized storage on GCS, but in the future to other nodes in the network) for a `ShardStateSyncResponseHeader` corresponding to that `sync_hash` and the Shard ID of the shard it's interested in. Among other things, this header includes the last new chunk before `sync_hash` in the shard, and a `StateRootNode` with hash equal to that chunk's `prev_state_root` field. Then the node downloads (again from GCS, but in the future it'll be from other nodes) the nodes of the trie with that `StateRootNode` as its root. Afterwards, it applies new chunks in the shard until it's caught up.
+The state sync algorithm defines a `sync_hash` used in many parts of the implementation. This is always the first block of the current epoch, which the node should be aware of once it has synced headers to the current point in the chain. A node performing state sync first makes a request for a `ShardStateSyncResponseHeader` corresponding to that `sync_hash` and the Shard ID of the shard it's interested in. Among other things, this header includes the last new chunk before `sync_hash` in the shard and a `StateRootNode` with a hash equal to that chunk's `prev_state_root` field. Then the node downloads the nodes of the trie with that `StateRootNode` as its root. Afterwards, it applies new chunks in the shard until it's caught up.
 
- As described above, the state we download is the state in the shard after applying the second to last new chunk before `sync_hash`, which belongs to the previous epoch (since `sync_hash` is the first block of the new epoch). To move the point in the chain of the initial state download to the current epoch, we could either move the `sync_hash` forward or we could change the state sync protocol (perhaps changing the meaning of the `sync_hash` and the fields of the `ShardStateSyncResponseHeader`, or somehow changing these structures more significantly). The former is an easier first implementation, since it would not require any changes to the state sync protocol other than to the expected `sync_hash`. We would just need to move the `sync_hash` to a point far enough along in the chain so that the `StateRootNode` in the `ShardStateSyncResponseHeader` refers to state in the current epoch. Currently we plan on implementing it that way, but we may revisit making more extensive changes to the state sync protocol later.
+As described above, the state we download is the state in the shard after applying the second-to-last new chunk before `sync_hash`, which belongs to the previous epoch (since `sync_hash` is the first block of the new epoch). To move the point in the chain of the initial state download to the current epoch, we could either move the `sync_hash` forward or change the state sync protocol (perhaps changing the meaning of the `sync_hash` and the fields of the `ShardStateSyncResponseHeader`, or somehow changing these structures more significantly). The former is an easier first implementation, as it would not require any changes to the state sync protocol other than to the expected `sync_hash`. We would just need to move the `sync_hash` to a point far enough along in the chain so that the `StateRootNode` in the `ShardStateSyncResponseHeader` refers to the state in the current epoch. Currently, we plan on implementing it that way, but we may revisit making more extensive changes to the state sync protocol later.
 
 ## Security Implications
 
 ### Fork Handling
 
-In theory, it can happen that there will be more than one candidate block which finishes the last epoch with old shard layout. For previous implementations it didn't matter because resharding decision was made in the beginning previous epoch. Now, the decision is made on the epoch boundary, so the new implementation handles this case as well.
+In theory, it's possible that more than one candidate block finishes the last epoch with the old shard layout. For previous implementations, it didn't matter because the resharding decision was made at the beginning of the previous epoch. Now, the decision is made at the epoch boundary, so the new implementation handles this case as well.
 
 ### Proof Validation
 
-With single shard tracking, nodes can't independently validate new state roots after resharding, because they don't have state of shard being split. That's why we generate resharding proofs, whose generation and validation may be a new weak point. However, `retain_split_shard` is equivalent to constant number of lookups in the trie, so its overhead its negligible. Even if proof is invalid, it will only imply that `retain_split_shard` fails early, similarly to other state transitions.
+With single shard tracking, nodes can't independently validate new state roots after resharding because they don't have the state of the shard being split. That's why we generate resharding proofs, whose generation and validation may be a new weak point. However, `retain_split_shard` is equivalent to a constant number of lookups in the trie, so its overhead is negligible. Even if the proof is invalid, it will only imply that `retain_split_shard` fails early, similar to other state transitions.
 
 ## Alternatives
 
-In the solution space which would keep blockchain stateful, we also considered an alternative to handle resharding through mechanism of `Receipts`. The workflow would be to:
+In the solution space that would keep the blockchain stateful, we also considered an alternative to handle resharding through the mechanism of `Receipts`. The workflow would be to:
 
-* create empty `target_shard`,
-* require `source_shard` chunk producers to create special `ReshardingReceipt(source_shard, target_shard, data)` where `data` would be an interval of key-value pairs in `source_shard` alongside with the proof,
-* then, `target_shard` trackers and validators would process that receipt, validate the proof and insert the key-value pairs into the new shard.
+* Create an empty `target_shard`.
+* Require `source_shard` chunk producers to create special `ReshardingReceipt(source_shard, target_shard, data)` where `data` would be an interval of key-value pairs in `source_shard` along with the proof.
+* Then, `target_shard` trackers and validators would process that receipt, validate the proof, and insert the key-value pairs into the new shard.
 
-However, `data` would occupy most of the whole state witness capacity and introduce overhead of proving every single interval in `source_shard`. Moreover, approach to sync target shard "dynamically" also requires some form of catchup, which makes it much less feasible than chosen approach.
+However, `data` would occupy most of the state witness capacity and introduce the overhead of proving every single interval in `source_shard`. Moreover, the approach to sync the target shard "dynamically" also requires some form of catch-up, which makes it much less feasible than the chosen approach.
 
-Another question is whether we should tie resharding to epoch boundaries. This would allow to come from resharding decision to completion much faster. But for that, we would need to:
+Another question is whether we should tie resharding to epoch boundaries. This would allow us to move from the resharding decision to completion much faster. But for that, we would need to:
 
-* agree if we should reshard in the middle of the epoch or allow "fast epoch completion" which has to be implemented,
-* keep chunk producers tracking "spare shards" ready to receive items from split shards,
-* on resharding event, implement specific form of state sync, on which source and target chunk producers would agree on new state roots offline,
-* then, new state roots would be validated by chunk validators in the same fashion.
+* Agree if we should reshard in the middle of the epoch or allow "fast epoch completion," which has to be implemented.
+* Keep chunk producers tracking "spare shards" ready to receive items from split shards.
+* On resharding event, implement a specific form of state sync, on which source and target chunk producers would agree on new state roots offline.
+* Then, new state roots would be validated by chunk validators in the same fashion.
 
-While it is much closer to Dynamic Resharding (below), it requires much more changes to the protocol. And the considered idea works very well as intermediate step to that, if needed.
+While it is much closer to Dynamic Resharding (below), it requires many more changes to the protocol. The considered idea works well as an intermediate step toward that, if needed.
 
-## Future possibilities
+## Future Possibilities
 
-* Dynamic Resharding - In this proposal, resharding is scheduled in advance and hardcoded within the neard binary. In the future, we aim to enable the chain to dynamically trigger and execute resharding autonomously, allowing it to adjust capacity automatically based on demand.
-* Fast Dynamic Resharding - In the Dynamic Resharding extension, the new shard layout is configured for the second upcoming epoch. This means that a full epoch must pass before the chain transitions to the updated shard layout. In the future, our goal is to accelerate this process by finalizing the previous epoch more quickly, allowing the chain to adopt the new layout as soon as possible.
-* Shard Merging - In this proposal the only allowed resharding operation is shard splitting. In the future, we aim to enable shard merging, allowing underutilized shards to be combined with neighboring shards. This would allow the chain to free up resources and reallocate them where they are most needed.
+* **Dynamic Resharding**: In this proposal, resharding is scheduled in advance and hardcoded within the `neard` binary. In the future, we aim to enable the chain to dynamically trigger and execute resharding autonomously, allowing it to adjust capacity automatically based on demand.
+* **Fast Dynamic Resharding**: In the Dynamic Resharding extension, the new shard layout is configured for the second upcoming epoch. This means that a full epoch must pass before the chain transitions to the updated shard layout. In the future, our goal is to accelerate this process by finalizing the previous epoch more quickly, allowing the chain to adopt the new layout as soon as possible.
+* **Shard Merging**: In this proposal, the only allowed resharding operation is shard splitting. In the future, we aim to enable shard merging, allowing underutilized shards to be combined with neighboring shards. This would allow the chain to free up resources and reallocate them where they are most needed.
 
 ## Consequences
 
 ### Positive
 
-* The protocol is able to execute resharding even while only a fraction of nodes track the split shard.
-* State for new shard layouts is computed in the matter of minutes instead of hours, thus ecosystem stability during resharding is greatly increased. As before, from the point of view of NEAR users it is instantaneous.
+* The protocol can execute resharding even while only a fraction of nodes track the split shard.
+* State for new shard layouts is computed in a matter of minutes instead of hours, greatly increasing ecosystem stability during resharding. As before, from the point of view of NEAR users, it is instantaneous.
 
 ### Neutral
 
@@ -682,7 +575,7 @@ N/A
 
 ### Negative
 
-* The storage components need to handle additional complexity of controlling the shard layout change.
+* The storage components need to handle the additional complexity of controlling the shard layout change.
 
 ### Backwards Compatibility
 

From 74301d0b612802d123ee503ec73b27ac9b6fafe0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Adam=20Chuda=C5=9B?=
 <18039094+staffik@users.noreply.github.com>
Date: Fri, 3 Jan 2025 18:19:38 +0100
Subject: [PATCH 30/30] fix(resharding): update pseudocode (#583)

---
 neps/nep-0568.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/neps/nep-0568.md b/neps/nep-0568.md
index 6e4d9dd93..ebdcebc81 100644
--- a/neps/nep-0568.md
+++ b/neps/nep-0568.md
@@ -509,10 +509,14 @@ Mappings in `DBCol::ShardUIdMapping` persist as long as any descendant relies on
 
 ```rust
 fn set_shard_uid_mapping(&mut self, child_shard_uid: ShardUId, parent_shard_uid: ShardUId) {
+    let mapped_parent_shard_uid = store
+          .get_ser::<ShardUId>(DBCol::StateShardUIdMapping, &parent_shard_uid.to_bytes())
+          .expect("set_shard_uid_mapping() failed")
+          .unwrap_or(parent_shard_uid);
     self.store_update.set(
         DBCol::StateShardUIdMapping,
         child_shard_uid.to_bytes().as_ref(),
-        &borsh::to_vec(&parent_shard_uid).expect("Borsh serialize cannot fail"),
+        &borsh::to_vec(&mapped_parent_shard_uid).expect("Borsh serialize cannot fail"),
     )
 }
 ```