diff --git a/core/README.md b/core/README.md index d9922ab06..abc8aa43c 100644 --- a/core/README.md +++ b/core/README.md @@ -126,50 +126,50 @@ # Contribution Process -The Stellar Protocol, like most software in the world, continues to evolve over time to meet the +The Stellar protocol, like most software in the world, continues to evolve over time to meet the needs of our network's participants and to drive technology forward into new territory. Given the importance of the reliability and safety of the network, we ask that all of those who have ideas towards pushing Stellar's protocol development forward adhere to the following: -- Consider your idea and how it serves the fundamental goals of the Stellar Network and aligns with - values of the Stellar Protocol (which are listed below). If you cannot show how your proposal +- Consider your idea and how it serves the fundamental goals of the Stellar network and aligns with + values of the Stellar protocol (which are listed below). If you cannot show how your proposal aligns with those goals and values, it's unlikely to ever be implemented. - Gather feedback from discussion on the dev mailing list and other forums, and utilize it to begin a draft proposal, otherwise known as a CAP (Core Advancement Proposal). - Follow the proposal process listed below. -## Stellar Network Goals -- **The Stellar Network should be secure and reliable, and should bias towards safety, simplicity, +## Stellar network Goals +- **The Stellar network should be secure and reliable, and should bias towards safety, simplicity, reliability, and performance over new functionality.** -- **The Stellar Network should run at scale and at low cost to all participants of the network.** - * In support of this, the Stellar Network should support off-chain transactions, e.g. Starlight. +- **The Stellar network should run at scale and at low cost to all participants of the network.** + * In support of this, the Stellar network should support off-chain transactions, e.g. Starlight. * An explicit non-goal is limiting the hardware requirements of stellar-core to a personal computer. -- **The Stellar Network should facilitate simplicity and interoperability with other protocols and +- **The Stellar network should facilitate simplicity and interoperability with other protocols and networks.** - * In support of this, the Stellar Network should facilitate side-chain transactions to enable + * In support of this, the Stellar network should facilitate side-chain transactions to enable sub-networks. -- **The Stellar Network should enable cross-border payments, i.e. payments via exchange of assets, +- **The Stellar network should enable cross-border payments, i.e. payments via exchange of assets, throughout the globe, enabling users to make payments between assets in a manner that is fast, cheap, and highly usable.** - - In support of this, the Stellar Network should support an orderbook that values simplicity + - In support of this, the Stellar network should support an orderbook that values simplicity over functionality, and one that primarily serves to enable cross-border payments. - - In support of this, the Stellar Network should facilitate liquidity as a means to enabling + - In support of this, the Stellar network should facilitate liquidity as a means to enabling - cross-border payments. - - In support of this, the Stellar Network should enable asset issuance, but as a means of + - In support of this, the Stellar network should enable asset issuance, but as a means of - enabling cross-border payments. -- **The Stellar Network should support decentralization wherever possible, but not at the expense +- **The Stellar network should support decentralization wherever possible, but not at the expense of the majority of its values.** - There should be no privileged actors — we should support egalitarianism and everyone participating on the same playing field. -- **The Stellar Network should enable users to easily exchange their non-Stellar based assets to +- **The Stellar network should enable users to easily exchange their non-Stellar based assets to Stellar-based assets, and vice versa.** -- **The Stellar Network should make it easy for developers of Stellar projects to create highly +- **The Stellar network should make it easy for developers of Stellar projects to create highly usable products.** ## Stellar Protocol Development Values -- **The Stellar Protocol should serve the goals of the Stellar Network.** -- **The Stellar Protocol should bias towards simplicity.** +- **The Stellar protocol should serve the goals of the Stellar network.** +- **The Stellar protocol should bias towards simplicity.** - When possible, solutions should be considered outside of core protocol changes such as via [SEPs (Stellar Ecosystem Proposals)](../ecosystem/README.md) to minimize complexity in the Stellar protocol. @@ -187,12 +187,12 @@ towards pushing Stellar's protocol development forward adhere to the following: - Unobservable tx semantics (eg. performance or bug fixes) - Horizon semantics - Public APIs, Client Libraries/SDKs. -- **The Stellar Protocol should be clear, concise, and opinionated.** +- **The Stellar protocol should be clear, concise, and opinionated.** - New operations and functionality should be opinionated, and straightforward to use. - There should ideally be only one obvious way to accomplish a given task. -- **The Stellar Protocol should bias towards broad use cases, and bias against niche +- **The Stellar protocol should bias towards broad use cases, and bias against niche functionality.** -- **The Stellar Protocol should bias towards user safety.** +- **The Stellar protocol should bias towards user safety.** ## CAP Process These are the steps from [idea to deployment](https://www.youtube.com/watch?v=Otbml6WIQPo) on how diff --git a/core/cap-0076.md b/core/cap-0076.md index 8b6c15fdb..122c9900d 100644 --- a/core/cap-0076.md +++ b/core/cap-0076.md @@ -13,7 +13,7 @@ Protocol version: 24 ## Simple Summary -Fix the entries that have been archived in corrupted state due to a bug in protocol 23 *and have never had corruption observed*. Also update the fee pool to reflect the unintentional XLM burns. +Fixes the entries that have been archived in corrupted state due to a bug in protocol 23 *and have never had corruption observed*. Also updates the fee pool to reflect the unintentional XLM burns. ## Working Group @@ -21,17 +21,18 @@ As specified in the Preamble. ## Motivation -Protocol 23 has introduced a mechanism for evicting the persistent contract data and code entries into Hot Archive (see [CAP-62](./cap-0062.md) for details). However, due to an implementation bug, at the moment of the archival (i.e. when the entry gets removed from the live bucket list and is moved to the Hot Archive) an arbitrary historical state has been used instead of the most recent state. That means that some entries have been archived with a state that they had at some point at time, but not the most recent state. +Protocol 23 introduced a mechanism to evict persistent contract data and code entries into the Hot Archive (see [CAP-62](./cap-0062.md) for details). However, an implementation bug at the moment of archival (i.e. when the entry gets deleted from the live bucket list and added to the Hot Archive) used an arbitrary historical state instead of the most recent state. As a result, some entries were archived with stale data from a point in time that was not the latest snapshot. Consider the following example that illustrates how the bug manifests. Imagine a contract `C` that has a balance of 10 XLM. `C` then proceeds to spend 9 XLM and is left with 1 XLM balance. Then `C` doesn't perform any more XLM operations for a while and its balance entry gets archived. Due to a bug, the entry state where it had 10 XLM balance could get archived. If that was the case, then when someone would restore `C` balance, they would get back 10 XLM balance, thus effectively minting 9 XLM. Note, that until the entry has been restored its state is not observable on-chain and thus the 9 XLM mint is only meaningful from the moment of restoration. -The actual bug impact on Stellar Mainnet has been that 478 ledger entries have been archived with an incorrect state before validators disabled the state eviction at the protocol entries. Luckily, 394 entries out of these have never been restored (at least at the moment of writing this CAP; however, the restoration has been disabled at the overlay level for these entries and it's highly unlikely that any more restorations would have happened until protocol 24 upgrade). +On Stellar mainnet, the bug archived incorrect state for 478 ledger entries before validators disabled state eviction at the protocol level in ledger `59313516`. Luckily, 394 of those entries have never been restored (at least at the moment of writing this CAP; however, the restoration has been disabled at the overlay level for these entries and it's highly unlikely that any more restorations would have happened until the protocol 24 upgrade). -The 394 entries that have never been restored are hashed into ledger as a part of the Hot Archive. However, as mentioned above, archived entries don't have any other observable on-chain impact (i.e. it's not possible for any transaction to read or modify their value). Because of that it is possible to amend the state of the corrupted entries to the correct value without risking to break any on-chain logic or invariants. +The 394 entries that have never been restored are hashed into the ledger as a part of the Hot Archive. However, as mentioned above, archived entries don't have any other observable on-chain impact (i.e. it's not possible for any transaction to read or modify their value). Because of that it is possible to amend the state of the corrupted entries to the correct value without risking to break any on-chain logic or invariants. Amending the corrupted entries would be beneficial to the network as it avoids all sorts of issues that would occur if entries were restored in the corrupted state (such as unexpected token mints or burns, or protocols assuming invalid state). While it is a rare and unusual precedent for validators to make any changes to the on-chain state they don't own (i.e. anything beyond the network configuration itself), this particular kind of amendment has a very limited and verifiable scope. It is possible for any observer to ingest the correct (i.e. pre-archival) state for every amended entry from the history and then verify that it matches the state of the entry after protocol 24 upgrade. It is also possible to verify that only the affected entries get amended via replaying the history and examining the Hot Archive hash after the upgrade. These factors make it not possible for validators to maliciously update the entries that haven't been corrupted, or updating the corrupted entries to incorrect values *without that being visible for any external observer*. -Note, that this CAP does not allow amendment of any state that has actually been observed due to restoration. The only change that concerns restored corrupted entries is an amendment of the fee pool that is done just in order to reflect the total XLM balance on the network. +> [!NOTE] +> This CAP does not allow amendment of any state that has actually been observed due to restoration. The only change concerning restored corrupted entries is an amendment of the fee pool, implemented just in order to reflect the networks' total XLM balance. ### Goals Alignment @@ -49,7 +50,7 @@ The fee pool is amended by adding `31879035` stroops in order to account for the ### The list of the corrupted entries -The full list of the corrupted entries (including those that had been restored) is attached to this repository in [corrupted_hot_archive_entries.csv](./../contents/cap-0076/corrupted_hot_archive_entries.csv) file. +The full list of the corrupted entries (including those that had been restored) is attached to this repository in [corrupted_hot_archive_entries.csv](../contents/cap-0076/corrupted_hot_archive_entries.csv) file. The file contains 478 rows with 5 columns: @@ -65,26 +66,25 @@ The file contains 478 rows with 5 columns: The entry amendments may strictly happen only for the entries that are still in the Hot Archive at the moment of protocol upgrade, and that still are in the exact state that has been observed at the moment of the corrupted archival. -Specifically, for every `ledger_key` in [corrupted_hot_archive_entries](./../contents/cap-0076/corrupted_hot_archive_entries.csv) a check for an entry to be amendable will be performed. The check requires that all of the following conditions are true: +Specifically, for every `ledger_key` in [corrupted_hot_archive_entries](../contents/cap-0076/corrupted_hot_archive_entries.csv) a check for an entry to be amendable will be performed. The check requires that all of the following conditions are true: - There is no entry corresponding to the `ledger_key` in the current live state - `ledger_key` is not being archived in the upgrade ledger - An entry `E` corresponding to the `ledger_key` exists in the Hot Archive - `E == archived_entry` (where `archived_entry` is the corresponding value from the corrupted_hot_archive_entries table) -If the entry is amendable, then a new ledger entry with value ``correct_entry` - base64 encoded `LedgerEntry` XDR, the correct value that should have been archived (i.e. the value of the affected entry at the moment when it has been archived) -` (from the table) will be written to the Hot Archive and thus become the most recent state of the entry that will be used for the restoration. +If the entry is amendable, then a new ledger entry with value `correct_entry` (defined above) from the table will be written to the Hot Archive and thus become the most recent state of the entry that will be used for the restoration. Note, that since the amendment only occurs in the Hot Archive, the change will not be reflected in `LedgerCloseMeta`, as it can not contain Hot Archive changes. The change will only be observable due to the `bucketListHash` change in the upgrade ledger header. After the upgrade the amended changes will be observable at the moment of restoration (and they will have the state that matches the state they had prior to archival). #### Fee pool amendment -`31879035` stroops will be added to the `feePool` in the `LedgerHeader`. This change reflects the XLM burn that occurred due to bug. Specifically, two XLM contract balances have been restored with a balance that is lower than the balance they had before archival. The specific XLM burns are as follows (these can also be verified in [corrupted_hot_archive_entries](./../contents/cap-0076/corrupted_hot_archive_entries.csv)): +`31879035` stroops will be added to the `feePool` in the `LedgerHeader`. This change reflects the XLM burn that occurred due to bug. Specifically, two XLM contract balances have been restored with a balance that is lower than the balance they had before archival. The specific XLM burns are as follows (these can also be verified in [corrupted_hot_archive_entries](../contents/cap-0076/corrupted_hot_archive_entries.csv)): -- Contract `CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA` had XLM balance of `291100005` stroops before archival, but had `290100005` stroops at the moment of restoration (`1000000` stroops burned) +- Contract `CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA` had XLM balance of `291100005` stroops before archival, but had `290100005` stroops at the moment of restoration (`1000000` stroops burned) - Contract `CDLMAKG5TSJA6FGP7LLC2FKJRQW6DQYMEPP6FURFVULDEQMP3PRZ4ISI` had XLM balance of `1173140246` stroops before archival, but had `1142261211` stroops balance at the moment of restoration (`30879035` stroops burned) -Thus `1000000 + 30879035 = 31879035` stroops have been burned, which is reflected via `feePool`. +Thus `1000000 + 30879035 = 31879035` stroops were burned, which is reflected via `feePool`. ### Backwards Incompatibilities @@ -99,13 +99,13 @@ The upgrade ledger will need to do a few hundred additional disk lookups, but th As mentioned in the 'Motivation' section this CAP performs modification of the ledger state that is not directly owned by the validators, which comes with the inherent risk of malicious modifications, or non-malicious erroneous modifications that lead to the further state corruption that can then be abused by the attackers. In order to resolve these concerns to some degree, and in order to ensure that the amendments only bring back the entries to their valid state, the Stellar Core build that performs the upgrade will contain the tools that allow anyone to ensure that: -- During the replay of protocol 23 *only* the entries from [corrupted_hot_archive_entries](./../contents/cap-0076/corrupted_hot_archive_entries.csv) table are incorrectly incorrectly archived, and that their correct and archived states match those in the table +- During the replay of protocol 23 *only* the entries from [corrupted_hot_archive_entries](../contents/cap-0076/corrupted_hot_archive_entries.csv) table are incorrectly archived, and that their correct and archived states match those in the table - Ensure that *every* entry from the table has indeed been incorrectly archived - Ensure that during the protocol upgrade only the entries from the table have been updated, and that the update has brought them back to the correct state ## Test Cases -The audit process described in the section above is implemented in Stellar Core. It will have an optional config called `PATH_TO_PROTOCOL_23_CORRUPTION_FILE`, which is the file path to the [corrupted_hot_archive_entries](./../contents/cap-0076/corrupted_hot_archive_entries.csv) file. When set, Stellar Core will add a series of asserts to verify the correctness of the file when replaying protocol 23 ledgers, as described in the Security Concerns section. In order to independently verify the correctness of the affected archived keys, set this config option and run catchup starting from the initial protocol 23 ledger, 58762517. +The audit process described in the section above is implemented in Stellar Core. It will have an optional config called `PATH_TO_PROTOCOL_23_CORRUPTION_FILE`, which is the file path to the [corrupted_hot_archive_entries](../contents/cap-0076/corrupted_hot_archive_entries.csv) file. When set, Stellar Core will add a series of asserts to verify the correctness of the file when replaying protocol 23 ledgers, as described in the Security Concerns section. In order to independently verify the correctness of the affected archived keys, set this config option and run catchup starting from the initial protocol 23 ledger, `58762517`. ## Implementation diff --git a/ecosystem/README.md b/ecosystem/README.md index 5bcf91eef..d9b6447a0 100644 --- a/ecosystem/README.md +++ b/ecosystem/README.md @@ -1,7 +1,7 @@ # Stellar Ecosystem Proposals (SEPs) SEPs are ideas, standards, and specifications in the form of proposals that the -author is intending to be adopted by participants in the Stellar ecosystem. +author would like adopted by participants in the Stellar ecosystem. ## Roles @@ -12,7 +12,7 @@ All SEPs have individuals fulfilling the following roles: and the general success of the SEP. - **Maintainer** - The maintainer is optional. If not present, the maintainer is the author. The maintainer is responsible for reviewing changes to the - SEP. For SEPs that have ecosystem adoption, SDF may identify or become a + SEP. For SEPs that have ecosystem adoption, the SDF may identify or become a maintainer of last resort. A maintainer of last resort steps in and acts as the maintainer if the maintainer ceases to respond or engage. @@ -21,18 +21,18 @@ All SEPs have individuals fulfilling the following roles: - **Draft** - A SEP that is currently open for consideration, iteration and actively being discussed. It may change. - **FCP** - A SEP that has entered a Final Comment Period (FCP). An author - places their SEP in FCP when they wish to signal that they plan to cease - making changes. After at least one week has passed the SEP's status should - move to `Active` or `Final`, or back to `Draft`. If changes are required, it - should be moved back to `Draft`. + places their SEP in FCP to signal that they plan to cease making changes. The + author also decides whether they want a SEP considered for `Active` or + `Final` status. After at least one week passes for review and discussion, the + SEP's status either moves as elected or back to `Draft`, if it needs changes. - **Active** - A SEP ready to be adopted, and the proposal is a living document - and may still receive changes. The author intends the SEP in its current form - to be actively adopted. Changes can be made without changing the SEP number, - although in the interest of growing an ecosystem of interopable participants - the author should endeavor to make changes backwards compatible so that - participants who have already adopted the SEP can continue to participate. - Where changes cannot be backwards compatible, the major version should be - updated to clearly distinguish new incompatible versions. + which may still receive changes. The author intends the SEP in its current + form to be actively adopted. Changes can be made without changing the SEP + number, although in the interest of growing an ecosystem of interopable + participants the author should endeavor to make changes backwards compatible + so that participants who have already adopted the SEP can continue to + participate. Where changes cannot be backwards compatible, the major version + should be updated to clearly distinguish new incompatible versions. - **Final** - A SEP ready to be adopted, and the proposal is an immutable document and will no longer receive changes, other than minor errata. The author intends to make no further changes. Adopters can expect significant @@ -40,9 +40,9 @@ All SEPs have individuals fulfilling the following roles: ### Additional Statuses -- **Abandoned** - A SEP has been abandoned by the author. SDF may move a SEP - into this state if the SEP has no activity, no visible adoption, and the - author is not responsive. +- **Abandoned** - A SEP has been abandoned by the author. The SDF may approve + moving a SEP into this state if the SEP has no activity, no visible adoption, + and the author is not responsive. ## Proposals @@ -110,18 +110,17 @@ All SEPs have individuals fulfilling the following roles: # Contribution Process -The Stellar Ecosystem, like most software ecosystems in the world, continues to +The Stellar ecosystem, like most software ecosystems in the world, continues to evolve over time to meet the needs of our network's participants and to drive technology forward into new territory. -Unlike Stellar's Core development (CAPs), Stellar's Ecosystem Proposals are -intended to be a more dynamic way of introducing standards and protocols -utilized in the ecosystem that are built on top of the Stellar Network. It uses -a lightweight process. +Unlike Stellar's Core development (CAPs), Stellar's Ecosystem Proposals are a +more dynamic way of introducing standards and protocols used in the ecosystem +and built on top of the network. Thus it uses a lightweight pragmatism process. -A SEPs author is responsible for a proposals adoption. Other ecosystem -participants, including SDF, may encourage adoption of a proposal, but authors -should expect each proposal to stand on its own merits and authors and +A SEP's author is responsible for a proposals adoption. Other ecosystem +participants, including the SDF, may encourage adoption of a proposal, but +authors should expect each proposal to stand on its own merits and authors and maintainers should plan to drive adoption themselves. Before contributing, consider the following: @@ -130,7 +129,7 @@ Before contributing, consider the following: Dev Discord], or [stellar-dev mailing list], and utilize it to begin a draft proposal. - Follow the proposal process listed below. If you're having difficulty moving - the proposal forward, talk to folks in the ecosystem, or folks at SDF; + the proposal forward, talk to folks in the ecosystem, or folks at the SDF; they'll often have guidance on how to move things forward, as well as feedback regarding feasibility and how the proposal does or does not align with the Stellar Network's goals. @@ -178,16 +177,17 @@ following: - If your SEP requires images or other supporting files, they should be included in a subdirectory of the `contents` folder for that SEP, such as `contents/sep_happycoder_b274f73c/`. Links should be relative, for example a - link to an image from SEP-X would be + link to an image from `SEP-X` would be `../contents/sep_happycoder_b274f73c/image.png`. ### Draft: Further Iteration -From there, the following process will happen: +Next, the SDF reccomends an iterative-feedback process with the community: -- You should continue the discussion of the draft SEP on the [GitHub discussion - forum], [Stellar Dev Discord], or [stellar-dev mailing list] to gather - additional feedback. We welcome any additional PRs that iterate on the draft. +- Successful authors polish their designs with help from SEP users through a + discussion of the draft SEP on the [GitHub discussion forums], [Stellar Dev + Discord], or [stellar-dev mailing list] to gather additional feedback. The + SDF also welcomes any additional ecosystem PRs that iterate on the draft. - Keep the version of the SEP as a `v0.y.z` version while in draft. - Increment the minor or patch versions on each change while in draft. See [SEP Versioning].