cap-0046-09.md

February 27, 2024 ยท View on GitHub

Preamble

CAP: 0046-09
Title: Network Configuration Ledger Entries
Working Group:
    Owner: Dmytro Kozhevin <@dmkozh>
    Authors: Dmytro Kozhevin <@dmkozh>, Siddharth Suresh <@sisuresh>
    Consulted:
Status: Final
Created: 2022-11-01
Discussion:
Protocol version: 20

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 validator vote. 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,ConfigUpgradeSet, and ConfigUpgradeSetKey.

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 entries

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 a ConfigUpgradeSet struct that contains all the updated ConfigSettingEntry entries. The LedgerUpgrade in StellarValue that validators will vote on will contain only an ConfigUpgradeSetKey, which containts a contractID, and the SHA-256 hash of the ConfigUpgradeSet. The actual ConfigUpgradeSet will need to exist on ledger in a ContractDataEntry, and the validators will look it up using the ConfigUpgradeSetKey. This means that a Wasm contract will need to be used to write the proposed upgrade. The specs of the entry written is as follows -

  • It should be a TEMPORARY entry, so make sure it's bumped to live long enough for the upgrade.
  • The SCVal key should be of type SCV_BYTES, where the value is the SHA-256 hash of the ConfigUpgradeSet.
  • The SCVal val should also be of type SCV_BYTES, where the value is the serialized XDR of the ConfigUpgradeSet.

Once the proposed upgrade is setup, you'll need to share the ConfigUpgradeSetKey with the other validators so they can vote for it. Note that the validators will verify that the hash in ConfigUpgradeSetKey matches the hash of the upgrade stored in the ContractDataEntry, and will only vote for upgrades that follow this rule. Validators should however still apply any valid hash the network accepts (even if that specific validator didn't vote for the upgrade).

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.

Disabling Soroban Transactions

The submission of Soroban transactions can be disabled by setting ConfigSettingContractExecutionLanesV0::ledgerMaxTxCount to 0 in under the ConfigSettingID CONFIG_SETTING_CONTRACT_EXECUTION_LANES. Doing this will lock the validators out from creating config setting upgrades using Wasm contracts, which means the ConfigUpgradeSet mechanism cannot be used to re-enable Soroban.

To allow increasing ledgerMaxTxCount from 0, we introduce the ability to set the value using the traditional upgrade mechanism. There's a new LedgerUpgrade type LEDGER_UPGRADE_MAX_SOROBAN_TX_SET_SIZE, which contains a uint32 newMaxSorobanTxSetSize to update ConfigSettingContractExecutionLanesV0::ledgerMaxTxCount.

Minimum values

The protocol should define minimum values for every upgradeable config setting so that it should always be possible to install a contract (assuming ledgerMaxTxCount isn't 0) that saves enough state to write the largest ConfigUpgradeEntry to allow for any config setting upgrade. Any CAP that introduces a new case under ConfigSettingEntry should also define the minimum values.

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.