Skip to content

Latest commit

 

History

History
152 lines (116 loc) · 6.54 KB

cap-0046-09.md

File metadata and controls

152 lines (116 loc) · 6.54 KB
Raw

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 ConfigUpgradeSets 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.