Proposal-validator_list_v2.adoc

Proposal For Version 2 of Validator Lists

Current Version 1 Format

The currently supported validator list format can be described with following json schemas:

v1 outer schema

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "https://xrpl.org/vl.outer.schema.v1.json",
    "title": "xrpl validator list, signed wrapper",
    "type": "object",
    "required": [ "manifest", "blob", "signature", "version" ],
    "properties": {
        "public_key": {
            "type": "string",
            "description": "hex encoded public key string for the publisher of the list",
            "$comment": "This field does not seem to be used by any code currently. Should implementation be comparing to the public/master key that is part of the manifest ?"
        },
        "manifest": {
            "type": "string",
            "description": "base64 encoded string that is a serialized manifest for the publisher of the list",
            "$comment": "The only manifest data current used is the master/public key field"
        },
        "blob": {
            "type": "string",
            "description": "base64 encoded string that when decoded is a json payload containing the actual validator list (see inner format)"
        },
        "signature": {
            "type": "string",
            "description": "hex encoded string that is used to verify the blob payload was signed by the public key (master key) in the manifest"
        },
        "version": {
            "type": "integer",
            "description": "version number for the validator list schema.",
            "minimum": 1
        }
    }
}

v1 blob schema after decoding

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "https://xrpl.org/vl.inner.schema.v1.json",
    "title": "xrpl validator list",
    "type": "object",
    "required": [ "sequence", "expiration", "validators" ],
    "properties": {
        "sequence": {
            "type": "integer",
            "description": "each published list must specify a sequence greater than the last published."
        },
        "expiration": {
            "type": "integer",
            "description": "time point denoted in seconds since xrpl epoch start (2000-01-01 00:00:00 utc)"
        },
        "validators": {
            "type": "array",
            "description": "array of validator objects",
            "items": {
                "type": "object",
                "required": [ "manifest", "validation_public_key" ],
                "properties": {
                    "manifest": {
                        "type": "string",
                        "description": "base64 encoded string that is a serialized manifest for the validator"
                    },
                    "validation_public_key": {
                        "type": "string",
                        "description": "hex encoded string that is public key for verifying validations from this validator"
                    }
                }
            }
        }
    }
}

Proposed Version 2 Format

The outer format will remain unchanged.

The inner json in the decoded blob will change to:

v2 blob schema after decoding

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "https://xrpl.org/vl.inner.schema.v2.json",
    "title": "xrpl validator lists",
    "type": "array",
    "items": {
        "type": "object",
        "required": [ "sequence", "valid-from", "valid-until", "validators" ],
        "properties": {
            "sequence": {
                "type": "integer",
                "description": "this field will be used to sort/order the items in array.",
                "$comment": "any gaps in sequence numbers will invalidate the entire list."
            },
            "valid-from": {
                "type": "string",
                "format": "date-time",
                "description": "the beginning of the validity time window, ISO 8601 compliant date-time value",
            },
            "valid-until": {
                "type": "string",
                "format": "date-time",
                "description": "the end of the validity time window, ISO 8601 compliant date-time value",
            },
            "validators": {
                "type": "array",
                "description": "array of validator objects",
                "items": {
                    "type": "object",
                    "required": [ "manifest", "validation_public_key" ],
                    "properties": {
                        "manifest": {
                            "type": "string",
                            "description": "base64 encoded string that is a serialized manifest for the validator"
                        },
                        "validation_public_key": {
                            "type": "string",
                            "description": "hex encoded string that is public key for verifying validations from this validator"
                        }
                    }
                }
            }
        }
    }
}

Processing Rules

Given a v2 array of validator lists (encoded in blob), the following validation will be performed:

• The range of sequence numbers must be continuous. Any gaps in sequence numbers will invalidate the entire list of lists (reported as error when processing).

• Any sequence number that has valid_from >= valid_until invalidates the entire list of lists.

• For a given sequence number N, the adjacent sequence lists (if present) must overlap in validity intervals, i.e.:

  • valid_untilN-1 >= valid_fromN AND

  • valid_untilN >= valid_fromN+1 AND

  • valid_fromN > valid_fromN-1

  Failure to meet this criteria for any sequence invalidates the entire list of lists.

• TBD: whether to permit cases where the validity interval for seq N is entirely contained within the interval for N-1.

Processing Notes

The result of all validator lists (across all configured sites) must be merged into a single timeline of lists. Each point on the timeline is an ordered set of valid_from time points across all lists. The data contained in a given interval is the merged list of validators that are valid during the given timeline interval.

For simplicity, this master/merged timeline should be rebuilt from scratch whenever any list changes. List changes were previously determined by sequence number alone (since there was a single sequence value). With v2, a list will be assumed to have changed when the signature changes (blob signature will have to be stored).

A v1 list can be incorporated into this timeline/structure by treating the first successful load timepoint as the valid_from value and expiration as the valid_until value. Since v1 lists only have a single value, none of the interval overlap requirements need to be checked.

At any given time, the current validator set will be chosen from the merged timeline based on ledger close time - i.e. transition to a new validator set if needed will be performed by the ledger close event. The current validator set N will be determined such that valid_fromN+1 > close time >= valid_fromN. The set of trusted validators is updated at the beginning of each consensus round and will be based on the current validator set.