layers: standard library
breaking: api, serialization
Specification
Actors
Interface devs
Interface standardization org
Schema devs
Wallet and app devs
Contract issuers
Users
Schema and implementation development
It is up to the schema developer to ensure the consistency of schema operations
under multiple interfaces. The schema developer selects a set of interfaces for a
schema and should create a single unified interface inheriting all of them.
Next, an implementation of that interface has to be made for a schema.
If the schema developer fails to create a coherent interface users may lose the
ability to transact with a contract or see its full state.
NB: Since interfaces and implementations do not exist on the consensus level,
contract validation is interface- and implementation-independent; thus once a
user can create a valid transaction, any other user will be able to verify and
accept it even if the interface or implementation is broken.
Implementations and interfaces must commit to the developer's identity - like
schemata.
Inheritance and specialization
Interface inheritance is a form of interface specialization: a higher-order
interface inheriting from some other (called parent interface) can only add
or tighten what was defined before, but not relax.
Multiple inheritance is allowed, in this case, the higher-order interface sums
up what is possible with lower-order interfaces, by creating unnamed
intermediate interfaces inheriting the parents in the order they are specified.
In this case, the same specialization rules apply, such that at each step only
specialization may happen and the final interface specializes all the parent
interfaces.
Multiple inheritance is generally non-commutative on the order of the parent
interfaces.
Interface inheriting other interface(s) may only:
add more global, owned and public states;
specialize state type (but not replace);
add more valencies;
add more state, inputs and valencies to the operations if all the parent
interfaces mark operation is abstract and overridden;
put a higher bound on the minimal and a lower bound on the maximal number
of state types or assignments in the contract or any of the operations, but only if
all the parent interfaces;
add more error types;
change string explanation of existing error types;
add more error types to operations, even to final ones;
add more operation types;
make optional operations required;
define a default operation, but only if it wasn't defined in any of the parent
interfaces;
define a default assignment in an operation; if it wasn't defined for that
operation in any of the parent interfaces;
It is disallowed to:
change default operation, if one is defined in the parent interface;
change default assignment for an existing operation, if one is defined in a
parent interface;
relax bounds for the operation arguments or contract state;
change anything except error types in operations marked as final;
change error type names;
replace existing state types, if they are already specialized, or reduce their
specialization.
Once compiled, the higher-order interface includes all parent interfaces as part
of it in explicit form, however, it commits and stores the information on the
parent interface ids in their inheritance order.
Implementation implements this final interface, covering all parent interfaces
in a single data structure. However, when used, the implementation can be
dynamically specialized as a specific parent interface, excluding the rest of
the interfaces. This is possible and always deterministic due to the above
inheritance rules.
Updates and fixes
A schema developer or a third party may create a new implementation - for a new
interfaces or as an alternative to an existing implementation, implementing some
operations more efficiently (or fixing bugs).
Developers should include in the implementation an increasing version number,
which must be unique and incremental for a given developer identity.
These new implementations and new generic interfaces covering new cases can be
distributed by these devs as a part of contract, transfer, schema or interface
consignments. All these consignments can include multiple interfaces and
multiple implementations of the same or different interfaces for the same
schema. Users may import the new interfaces and implementations into their
stashes (upon validation) and switch on using them even for existing contracts
with a state.
The user verifies the interface, implementation and schema consistency, and also
checks the dev signatures. It is recommended not to accept interfaces and
implementations coming from untrusted parties.
Conflict resolution
If a stash contains multiple implementations of the same interface for the same
schema the wallet or an app must select the one which has the most dev trust.
If two or more have the same level of trust, then the one which has the highest
version number. If multiple implementations have the same version number, they
either have to be rejected to be included in the stash, or the one with the
highest lexicographic id number must be selected.
Specification
Actors
Schema and implementation development
It is up to the schema developer to ensure the consistency of schema operations under multiple interfaces. The schema developer selects a set of interfaces for a schema and should create a single unified interface inheriting all of them. Next, an implementation of that interface has to be made for a schema.
If the schema developer fails to create a coherent interface users may lose the ability to transact with a contract or see its full state.
NB: Since interfaces and implementations do not exist on the consensus level, contract validation is interface- and implementation-independent; thus once a user can create a valid transaction, any other user will be able to verify and accept it even if the interface or implementation is broken.
Implementations and interfaces must commit to the developer's identity - like schemata.
Inheritance and specialization
Interface inheritance is a form of interface specialization: a higher-order interface inheriting from some other (called parent interface) can only add or tighten what was defined before, but not relax.
Multiple inheritance is allowed, in this case, the higher-order interface sums up what is possible with lower-order interfaces, by creating unnamed intermediate interfaces inheriting the parents in the order they are specified. In this case, the same specialization rules apply, such that at each step only specialization may happen and the final interface specializes all the parent interfaces.
Multiple inheritance is generally non-commutative on the order of the parent interfaces.
Interface inheriting other interface(s) may only:
and a lower bound on the maximalnumber of state types or assignments in the contract or any of the operations, but only if all the parent interfaces;It is disallowed to:
Once compiled, the higher-order interface includes all parent interfaces as part of it in explicit form, however, it commits and stores the information on the parent interface ids in their inheritance order.
Implementation implements this final interface, covering all parent interfaces in a single data structure. However, when used, the implementation can be dynamically specialized as a specific parent interface, excluding the rest of the interfaces. This is possible and always deterministic due to the above inheritance rules.
Updates and fixes
A schema developer or a third party may create a new implementation - for a new interfaces or as an alternative to an existing implementation, implementing some operations more efficiently (or fixing bugs).
Developers should include in the implementation an increasing version number, which must be unique and incremental for a given developer identity.
These new implementations and new generic interfaces covering new cases can be distributed by these devs as a part of contract, transfer, schema or interface consignments. All these consignments can include multiple interfaces and multiple implementations of the same or different interfaces for the same schema. Users may import the new interfaces and implementations into their stashes (upon validation) and switch on using them even for existing contracts with a state.
The user verifies the interface, implementation and schema consistency, and also checks the dev signatures. It is recommended not to accept interfaces and implementations coming from untrusted parties.
Conflict resolution
If a stash contains multiple implementations of the same interface for the same schema the wallet or an app must select the one which has the most dev trust. If two or more have the same level of trust, then the one which has the highest version number. If multiple implementations have the same version number, they either have to be rejected to be included in the stash, or the one with the highest lexicographic id number must be selected.