-
Notifications
You must be signed in to change notification settings - Fork 312
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
CAP-46-09: Updated and formalized the configuration settings proposal. (
#1291) This has been moved from CAP-0046-02 in order to separate configuration and contract lifecycle specification. The main difference is the proposal to store only the hash of the upgrade set in `SCPValue`. Otherwise, this expands on the details omitted from the original proposal. Co-authored-by: Siddharth Suresh <[email protected]>
- Loading branch information
Showing
3 changed files
with
227 additions
and
52 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,152 @@ | ||
| ## Preamble | ||
|
|
||
| ``` | ||
| CAP: 0046-09 | ||
| Title: Network Configuration Ledger Entries | ||
| Working Group: | ||
| Owner: Dmytro Kozhevin <@dmkozh> | ||
| Authors: Dmytro Kozhevin <@dmkozh> | ||
| Consulted: | ||
| Status: Draft | ||
| Created: 2022-11-01 | ||
| Discussion: | ||
| Protocol version: TBD | ||
| ``` | ||
|
|
||
| ## Simple Summary | ||
|
|
||
| This proposal defines a new ledger entry type to store various network-wide | ||
| configuration and a way to upgrade such configuration entries. | ||
|
|
||
| ## Motivation and Goals Alignment | ||
|
|
||
| See the Soroban overview CAP for overall Soroban motivation. | ||
|
|
||
| The configuration entries in particular are motivated by the need to store a | ||
| large amount of Soroban-related configuration, such as the host function | ||
| metering data, contract fee structure, contract size limits etc. Currently the | ||
| network-wide configuration is only stored in the `LedgerHeader`, which would be | ||
| infeasible to use given that the Soroban-related information may require tens | ||
| of kilobytes of space to be stored. | ||
|
|
||
|
|
||
| ## Abstract | ||
|
|
||
| This CAP introduces a special type of configuration `LedgerEntry` that can only | ||
| be modified via a protocol upgrade. It also specifies the general rules for | ||
| adding and modifying these entries. | ||
|
|
||
| ## Specification | ||
|
|
||
| ### XDR | ||
|
|
||
| See the XDR diffs in the Soroban overview CAP, specifically those referring to | ||
| the `ConfigSettingEntry` and `ConfigUpgradeSet`. | ||
|
|
||
| ### Configuration settings entries | ||
|
|
||
| This CAP adds a general mechanism for validators to store and update | ||
| configuration settings using ledger upgrades. The smart contracts require a | ||
| significant amount of configuration related to fees and metering and hence this | ||
| CAP accounts for large and complex configuration settings. | ||
|
|
||
| In order to prevent bloating of the `LedgerHeader` the settings are stored in | ||
| the ledger as a new type of `LedgerEntry`: `ConfigSettingEntry`. Every | ||
| `ConfigSettingEntry` is uniquely identified by its type (`ConfigSettingID`) and | ||
| hence at most one entry of each type may exist in the ledger. Setting entries | ||
| are represented by arbitrary XDR. | ||
|
|
||
| `ConfigSettingID` and its corresponding payload should correspond to an 'atomic' | ||
| set of configuration settings, i.e. those that are expected to be used and | ||
| upgraded together. For example, contract size limit, metering data and fee data | ||
| would all be represented by the separate entries (or more granular entries if | ||
| needed). | ||
|
|
||
| #### Adding and removing setting etnries | ||
|
|
||
| New settings may only be introduced during the protocol version upgrades. Every | ||
| CAP introducing the new setting must also define its default value to be used | ||
| during the protocol version upgrade. When the upgrade happens, all the new | ||
| settings defined for the upgrade are created in the ledger with respective | ||
| default values. | ||
|
|
||
| Removal of the setting types could happen during the protocol version upgrade | ||
| too. However, given that the footprint of a single ledger entry is negligible | ||
| at the scale of ledger, there is really no need to maintain the removal | ||
| mechanism. Not being able to remove the setting by accident is also safer, as | ||
| the settings are fundamental components to any functionality needing them. | ||
| Hence this CAP assumes the settings are always persisted in the ledger after | ||
| they are introduced (similar to e.g. `LedgerHeader` parameters). | ||
|
|
||
| ### Configuration upgrade mechanism | ||
|
|
||
| Every configuration setting entry is considered to be atomic for the sake of the | ||
| upgrade, i.e. an upgrade must provide the full XDR of the setting, even if it | ||
| is only being partially updated. This is done to simplify the upgrade format | ||
| (otherwise we'd need to introduce some key-value mechanism of specifying | ||
| upgraded fields). | ||
|
|
||
| Multiple configuration setting entries may be upgraded at once using | ||
| `ConfigUpgradeSet` struct that contrains all the updated `ConfigSettingEntry` | ||
| entries. Similar to the transaction sets, the network needs to agree on hash of | ||
| the `ConfigUpgradeSet`, hence only hash is added to `SCPValue`. While upgrades | ||
| are rare events, the size of the setting entry is not bounded and the number of | ||
| `SCPValues` in the network is large enough (thousands of messages per node as | ||
| of writing this) to have a risk of significantly reducing the network bandwidth | ||
| during the upgrade. | ||
|
|
||
| The actual upgrade set contents are pulled from the peers in a similar fashion | ||
| to the transaction sets (if needed at all; ideally all the validators would | ||
| have exactly the same upgrade set). | ||
|
|
||
| #### `ConfigUpgradeSet` validation | ||
|
|
||
| `ConfigUpgradeSet` is considered valid when: | ||
|
|
||
| - all the `updatedEntry` values have unique `configSettingID` values | ||
| - `updateEntry` are ordered by the integer values of the `ConfigSettingID` enum | ||
| - every `updatedEntry` is valid itself | ||
|
|
||
| Individual config settings are validated in the way defined by the CAPs | ||
| introducing them. | ||
|
|
||
| #### `ConfigUpgradeSet` acceptance | ||
|
|
||
| In order to vote for the config upgrade set, besides validating the | ||
| `ConfigUpgradeSet` contents, validators also need to be able to accept them | ||
| according to their own scheduled upgrades. | ||
|
|
||
| The validator will accept a valid nominated `ConfigUpgradeSet` when it can | ||
| accept every updated entry in it. As a general rule, the validator should | ||
| accept a given updated `ConfigSettingEntry` when the validator has exactly the | ||
| same upgrade scheduled. However, the acceptance rules can be adjusted by the | ||
| CAP introducing the config entry. For example, if entries describe CPU costs of | ||
| executing a host function, it could be viable to allow any of the nominated | ||
| upgrade values to be within 1% of the scheduled upgrade. | ||
|
|
||
| If there are ever multiple valid `ConfigUpgradeSet`s that validator can accept, | ||
| the one that has the most entries should be picked. Ties are resolved in favor | ||
| of the lowest hash value. | ||
|
|
||
| Note, that unlike with regular ledger upgrades, the network won't try to build a | ||
| viable set of upgrades if only some of the entries are valid or accepted. So | ||
| the whole `ConfigUpgradeSet` can be considered to be atomic from the upgrade | ||
| standpoint. | ||
|
|
||
| ## Resource Utilization | ||
|
|
||
| No substantial changes to resource utilization are expected, including the | ||
| upgrade events. | ||
|
|
||
| ## Security Concerns | ||
|
|
||
| Compared to the existing ledger upgrades that normally are limited to very | ||
| simple changes like bumping the protocol version, the configuration upgrades to | ||
| schedule are much harder to review from the validator perspective. It's also | ||
| not plausible that every validator would do complex operations like host | ||
| function cost calibration. Hence the upgrade sets to nominate have to be | ||
| distributed via the trusted and secure channels. Both these issues increase the | ||
| risks of applying a malicious upgrade to the network (for example by | ||
| distributing it to validators as an impersonated trusted party). Although the | ||
| influence scope of such a malicious upgrade would be reasonably limited and | ||
| likely concern only the Smart Contracts. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters