MIP-13: Suzuka DA Migrations Format

  • Description: Data format which describes migrations of the canonical state of the DA over time.
  • Authors: Mikhail Zabaluev
  • Desiderata: MD-13

Abstract

The format of a well-known file defining migrations of the DA blob format enacted on specified block heights. This would be a hardfork or coordinated approach (TODO: clarify terminology) to upgrades, in that each node participating in the network SHOULD be deployed with an up to date copy of the file describing the migrations up to and above the current block height.

Motivation

In order to allow for safe upgrades, data model changes, and DA migrations, it has been proposed that we provide a data format which describes the canonical state of the DA over time.

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.

DA Migration Configuration Format

The format of a well-known file defining migrations is a JSON serialization of a map where keys indicate the block height at which the configuration in the value starts applying. The values are objects with named fields specifying the format settings. The top-level configuration envelope specifies the current version of the format to permit breaking changes in the future.

{
  "version": 1,
  "migrations": {
    "123456": {
      "namespace": "deadbeef01234567890",
      "transaction_format": 1,
      "block_format": 2,
      "ordering_rule": 3,
      "node_version": "1.2"
    }
  }
}

the Rust definition of the value struct:

#[derive(Serialize, Deserialize)]
pub struct DASettings {
    namespace: Namespace,
    transaction_format: TransactionFormatVersion,
    block_format: BlockFormatVersion,
    ordering_rule: OrderingRuleVersion,
    node_version: NodeVersionReq,
}

Here, Namespace is the data type representing a Celestia namespace ID with the human-readable serialization as a hex string. The *Version types are enums initially defined with a single V1 member each. NodeVersionReq serializes into a SemVer-conforming version specification in the MAJOR.MINOR format.

Principles of managing migrations

Each new entry in the migration table SHALL use a unique Celestia namespace identifier to prevent confusion and detect accidental misconfiguration early.

The configuration in all nodes in the network SHOULD be updated well in advance of the block height at which a new change is introduced. The expected process in governance stage 0 is a coordinated upgrade.

The node_version field gives the semver minimum version of the Suzuka full node software that is REQUIRED to use these settings. A node that does not satisfy the version requirement for any of the encountered entries MUST reject the configuration and report an error.

The producers and consumers of DA blobs MUST implement all versions encountered in the configuration file and apply the settings accordingly to the block height of the data blobs. No mixing of different DA formats between blobs submitted by correct nodes for the same block height is supported by this specification.

Future evolution of the DA migration configuration format

New fields can be added to the DASettings structures in future revisions of this specifications without changing the value of the top-level version field. Implementations SHALL ignore the fields not defined in the revision of the specification they support. If interpretation of such newly added field values in a specific migration requires behavior not supported by older versions of the node software, this SHOULD be communicated to non-compliant nodes with the compatibility requirement in the node_version field.

Any values of known fields of DASettings that are not supported by the current implementation SHALL result in rejecting the configuration and reporting an error. The implementation MAY check the compatibility requirement given by node_version before reporting errors on unsupported values.

Reference Implementation

Verification

Needs discussion.

Errata

Appendix