ADR 0004: Runtime Governance
Component
Oasis Core
Changelog
- 2020-10-07: Add per-role max node limits, minimum required election pool size
- 2020-09-30: Add entity whitelist admission policy max nodes limit
- 2020-09-17: Initial draft
Status
Accepted
Context
Currently all runtimes can only be governed by a single entity -- the runtime owner. In this regard governance means being able to update certain fields in the runtime descriptor stored by the consensus layer registry service. On one hand the runtime descriptor contains security-critical parameters and on the other there needs to be a mechanism through which the runtimes can be upgraded (especially so for TEE-based runtimes where a specific runtime binary is enforced via remote attestation mechanisms).
This proposal extends runtime governance options and enables a path towards runtimes that can define their own governance mechanisms. This proposal assumes that ADR 0003 has been adopted and runtimes can have their own accounts in the staking module.
Decision
This proposal takes a simplistic but powerful approach which allows each runtime to choose its governance model upon its first registration. It does so through a newly introduced field in the runtime descriptor which indicates how the runtime descriptor can be updated in the future.
Runtime Descriptor
The runtime descriptor version is bumped to 2
. Version 1
descriptors are
accepted at genesis and are converted to the new format by assuming the entity
governance model as that is the only option in v1. All new runtime registrations
must use the v2 descriptor.
Governance Model
This proposal updates the runtime descriptor by adding fields as follows:
type Runtime struct {
// GovernanceModel specifies the runtime governance model.
GovernanceModel RuntimeGovernanceModel `json:"governance_model"`
// ... existing fields omitted ...
}
// RuntimeGovernanceModel specifies the runtime governance model.
type RuntimeGovernanceModel uint8
const (
GovernanceEntity RuntimeGovernanceModel = 1
GovernanceRuntime RuntimeGovernanceModel = 2
GovernanceConsensus RuntimeGovernanceModel = 3
)
// ... some text serialization methods omitted ...
The governance_model
field can specifiy one of the following governance
models:
-
Entity governance (
GovernanceEntity
). This causes the runtime to behave exactly as before, the runtime owner (indicated byentity_id
in the runtime descriptor) is the only one who can update the runtime descriptor viaregistry.RegisterRuntime
method calls.The runtime owner is also the one that needs to provide the required stake in escrow in order to avoid the runtime from being suspended. As before note that anyone can delegate the required stake to the runtime owner in order to enable runtime operation (but the owner can always prevent the runtime from operating by performing actions which would cause the stake claims to no longer be satisfied).
-
Runtime-defined governance (
GovernanceRuntime
). In this case the runtime itself is the only one who can update the runtime descriptor by emitting a runtime message. The runtime owner (indicated byentity_id
) is not able to perform any updates after the initial registration and such attempts must returnErrForbidden
.The runtime itself is the one that needs to provide the required stake in escrow in order to avoid the runtime from being suspended. This assumes that runtimes can have accounts in the staking module as specified by ADR 0003. Note that anyone can delegate the required stake to a runtime in order to enable its operation.
-
Consensus layer governance (
GovernanceConsensus
). In this case only the consensus layer itself can update the runtime descriptor either through a network upgrade or via a consensus layer governance mechanism not specified by this proposal.Runtimes using this governance model are never suspended and do not need to provide stake in escrow.
Runtimes using this governance model cannot be registered/updated via regular registry method calls or runtime messages (doing so must return
ErrForbidden
). Instead such a runtime can only be registered at genesis, through a network upgrade or via a consensus layer governance mechanism not specified by this proposal.
Entity Whitelist Admission Policy
The entity whitelist admission policy configuration structure is changed to allow specifying the maximum number of nodes that each entity can register under the given runtime for each role.
type EntityWhitelistConfig struct {
// MaxNodes is the maximum number of nodes that an entity can register under
// the given runtime for a specific role. If the map is empty or absent, the
// number of nodes is unlimited. If the map is present and non-empty, the
// the number of nodes is restricted to the specified maximum (where zero
// means no nodes allowed), any missing roles imply zero nodes.
MaxNodes map[node.RolesMask]uint16 `json:"max_nodes,omitempty"`
}
type EntityWhitelistRuntimeAdmissionPolicy struct {
Entities map[signature.PublicKey]EntityWhitelistConfig `json:"entities"`
}
The new max_nodes
field specifies the maximum number of nodes an entity can
register for the given runtime for each role. If the map is empty or absent, the
number of nodes is unlimited. If the map is present and non-empty, the number of
nodes is restricted to the specified number (where zero means no nodes are
allowed). Any missing roles imply zero nodes.
Each key (roles mask) in the max_nodes
map must specify a single role,
otherwise the runtime descriptor is rejected with ErrInvalidArgument
.
When transforming runtime descriptors from version 1, an entry in the entities
field maps to an EntityWhitelistConfig
structure with max_nodes
absent,
denoting that an unlimited number of nodes is allowed (as before).
Minimum Required Committee Election Pool Size
The executor and storage runtime parameters are updated to add a new field defining the minimum required committee election pool size. The committee scheduler is updated to refuse election for a given runtime committee in case the number of candidate nodes is less than the configured minimum pool size.
type ExecutorParameters struct {
// MinPoolSize is the minimum required candidate compute node pool size.
MinPoolSize uint64 `json:"min_pool_size"`
// ... existing fields omitted ...
}
type StorageParameters struct {
// MinPoolSize is the minimum required candidate storage node pool size.
MinPoolSize uint64 `json:"min_pool_size"`
// ... existing fields omitted ...
}
The value of min_pool_size
must be non-zero and must be equal to or greater
than the corresponding sum of group_size
and group_backup_size
. Otherwise
the runtime descriptor is rejected with ErrInvalidArgument
.
When transforming runtime descriptors from version 1, min_pool_size
for the
executor committee is computed as group_size + group_backup_size
while the
min_pool_size
for the storage committee is equal to group_size
.
State
This proposal introduces/updates the following consensus state in the registry module:
Stored Runtime Descriptors
Since the runtime descriptors can now be updated by actors other than the
initial registering entity, it does not make sense to store signed runtime
descriptors. The value of storage key prefixed with 0x13
which previously
contained signed runtime descriptors is modified to store plain runtime
descriptors.
Genesis Document
This proposal updates the registry part of the genesis document as follows:
-
The type of the
runtimes
field is changed to a list of runtime descriptors (was a list of signed runtime descriptors before). -
The type of the
suspended_runtimes
field is changed to a list of runtime descriptors (was a list of signed runtime descriptors before).
Runtime descriptors must be transformed to support the new fields.
Transaction Methods
This proposal updates the following transaction methods in the registry module:
Register Runtime
Runtime registration enables a new runtime to be created or an existing runtime to be updated (in case the governance model allows it).
Method name:
registry.RegisterRuntime
The body of a register runtime transaction must be a Runtime
descriptor.
The signer of the transaction must be the owning entity key.
Registering a runtime may require sufficient stake in either the owning entity's (when entity governance is used) or the runtime's (when runtime governance is used) escrow account.
Changing the governance model from GovernanceEntity
to GovernanceRuntime
is
allowed. Any other governance model changes are not allowed and must fail with
ErrForbidden
. Support for other changes is deferred to a consensus layer
governance mechanism not specified by this proposal.
Using the GovernanceRuntime
governance model for a runtime of any kind other
than KindCompute
must return ErrInvalidArgument
.
Messages
This proposal introduces the following runtime messages:
Update Runtime Descriptor
The update runtime descriptor message enables a runtime to update its own descriptor when the current governance model allows it.
Field name:
update_runtime
Body:
type UpdateRuntimeMessage struct {
registry.Runtime
}
The body of the update runtime descriptor message is a new runtime descriptor that must be for the runtime emitting this message. Otherwise the message is considered malformed.
The actions performed when processing the message are the same as those
performed when processing the registry.RegisterRuntime
method call, just made
on the runtime's (instead of an entity's) behalf.
Consensus Parameters
Registry
This proposal introduces the following new consensus parameters in the registry module:
enable_runtime_governance_models
(set ofRuntimeGovernanceModel
) specifies the set of runtime governance models that are allowed to be used when creating/updating registrations (either via method calls or via runtime messages). In case a runtime is using a governance model not specified in this list, an update to such a runtime must fail withErrForbidden
.
Rust Runtime Support Library
The Rust runtime support library (oasis-core-runtime
) must be updated to
support the updated and newly needed message structures (the runtime descriptor
and the update runtime message).
Consequences
Positive
-
Runtimes can define their governance model, enabling them to become more decentralized while still allowing upgrades.
-
Runtimes using the entity whitelist admission policy can limit the number of nodes that each entity can register.
-
Runtimes can specify the minimum size of the compute/storage node pool from which committees are elected.
Negative
Neutral
References
- ADR 0003 - Consensus/Runtime Token Transfer