|
|
@@ -1,211 +1,278 @@
|
|
|
-# WIP: Rome Testnet Specification
|
|
|
+# Acropolis Testnet Specification
|
|
|
|
|
|
-## Table Of Content
|
|
|
+## Table Of Contents
|
|
|
|
|
|
-- [Purpose](#purpose)
|
|
|
-- [Decisions](#decisions)
|
|
|
-- [Work In Progress](#work-in-progress)
|
|
|
+- [Document](#document)
|
|
|
+- [Caveat](#caveat)
|
|
|
- [Glossary](#glossary)
|
|
|
-- [Notation](#notation)
|
|
|
-- [Rome](#rome)
|
|
|
- - [Overview](#overview)
|
|
|
- - [Roles](#roles)
|
|
|
- - [Substrate Runtime](#substrate-runtime)
|
|
|
+- [Format](#format)
|
|
|
+- [Overview](#overview)
|
|
|
+- [Substrate Runtime](#substrate-runtime)
|
|
|
+ - [Runtime Version](#runtime-version)
|
|
|
+ - [Native Version](#native-version)
|
|
|
+ - [Substrate Version](#substrate-version)
|
|
|
+ - [Modules](#modules)
|
|
|
+ - [Forum](#forum)
|
|
|
+ - [Proposals](#proposals)
|
|
|
+ - [CouncilElection](#councilelection)
|
|
|
+ - [Council](#council)
|
|
|
+ - [Memo](#memo)
|
|
|
+ - [Members](#members)
|
|
|
+ - [Migration](#migration)
|
|
|
+ - [Actors](#actors)
|
|
|
+ - [DataObjectTypeRegistry](#dataobjecttyperegistry)
|
|
|
+ - [DataDirectory](#datadirectory)
|
|
|
+ - [DataObjectStorageRegistry](#dataobjectstorageregistry)
|
|
|
+ - [DownloadSessions](#downloadsessions)
|
|
|
+ - [SRML Modules](#srml-modules)
|
|
|
+ - [Runtime API](#runtime-api)
|
|
|
+<!-- - [Communication Protocols](#communication-protocols) -->
|
|
|
+
|
|
|
+## Document
|
|
|
+
|
|
|
+The purpose of this document is to serve as a starting point for the implementation phase of the given testnet. It is only a starting point in the sense that the implementation effort will always depart from the up front specification to some, possibly substantial, extent, but no effort is made to synchronise the specification at any time. Instead, the any such synchronisation would be done in the specification of a future network. The value of such a specification is primarily to establish a relatively precise shared understanding among all contributors to a testnet release.
|
|
|
+
|
|
|
+## Caveat
|
|
|
+
|
|
|
+Parts of the specification are not well harmonised with the rest, in particular the storage system, due to time constraints. Read graciously, this will be resolved later. Also, a substantial number of modules are not yet specced, as already implemented modules from prior testnets are being reused. Full specs will eventually be available as future networks are released where changes are made to these modules. Lastly, a number off communication protocols are not captured in this spec due to time constraints, they will be introduced for later networks.
|
|
|
|
|
|
-## Document Purpose
|
|
|
-
|
|
|
-The life time and purpose of this docuemnt is separated into two distinct phases,
|
|
|
-
|
|
|
-- Enable greater
|
|
|
-- xxx
|
|
|
-- audience
|
|
|
-- use case
|
|
|
-- scope
|
|
|
-- frist ry, tierative arrive at standard, extract generalised template for joystrema and other Susbtrate teams.
|
|
|
-
|
|
|
-## How to read this specification
|
|
|
-
|
|
|
-Given the descrbied purpose of this document, the style of specification admits to the following constraints
|
|
|
-
|
|
|
-- S
|
|
|
-
|
|
|
-Take Substrate for granted, and SRML momdules, dont explicitly described.
|
|
|
-
|
|
|
-
|
|
|
-<explain how you wille xplain different parts, what each part of the explanation does>
|
|
|
-
|
|
|
-### Substrate
|
|
|
-
|
|
|
-We are speicfying what:
|
|
|
+## Glossary
|
|
|
|
|
|
-- explain how to intereprt speciciation, so we understand `map`, build et.
|
|
|
-- xxxx
|
|
|
+- **Substrate:** A blockchain SDK, used for this testnet, that abstracts away concerns about consensus and p2p communication.
|
|
|
|
|
|
-what bout built in stuff, like types `origin`, and functions, like `ensure_signed`.
|
|
|
+- **Runtime:** Application specific consensus code written for the Substrate SDK. Includes state and transaction rules specific to the application, but excludes consensus algorithm and p2p networking.
|
|
|
|
|
|
-what about block level callback?
|
|
|
+- **Substrate Module:** A substrate runtime is partitioned into functionality integrated units, called modules, which have their own local state, transaction types and events.
|
|
|
|
|
|
-variables
|
|
|
- - **origin** : instance variable for signed
|
|
|
- - **who**: instance variable when is signed
|
|
|
+- **SRML:** Substrate standard runtime library (SRML), is a set of highly reusable Substrate modules.
|
|
|
|
|
|
+- **AURA:** Component of consensus responsible for block authoring.
|
|
|
|
|
|
-#### Extrinsics
|
|
|
+- **GRANDPA:** Component of consensus responsible for block finality.
|
|
|
|
|
|
+<!--
|
|
|
+## Format
|
|
|
|
|
|
+[Read here to understand the format of this specification.](specification-format.md)
|
|
|
|
|
|
-##### Errors
|
|
|
+-->
|
|
|
|
|
|
-All errors have their own precondition. The errors are listed in the order which corresponds to what order they would be invoked if _multiple_ error conditions were satisified simultanously. If this cannot be expressed as a single linear list, the section must reflect this informaiton in some other way in a fully unambigous manner.
|
|
|
+## Overview
|
|
|
|
|
|
-Error scenarios, which thus have no side effects, and no events. The section title is used as error message. The full precondition for each case is not only the listed condition in the same row, but also the combined failure of all listed preconditions of prior rows.
|
|
|
+The Acropolis testnet features the following roles
|
|
|
|
|
|
-##### Side effects
|
|
|
+- **Validator**: Block producer and validator.
|
|
|
+- **Council Member:** Council participant, currently only involved in voting on runtime upgrades.
|
|
|
+- **Storage Provider**: Does storage and distribution of content, peer provider synchronisation, as well as upload liaison.
|
|
|
+- **Forum Moderator**: A single actor role for managing the new on-chain forum.
|
|
|
|
|
|
-Assume that all error preconditions are simultnaously false, denoted by predicate `NO_ERROR`.
|
|
|
+This release also sees the introduction of a new storage infrastructure based on IPFS for distribution and synchronisation, and IPNS for host resolution. A generalised host resolution module is also introduced as part of making the latter functionality possible, and it will be reused for host resolution across the platform.
|
|
|
|
|
|
-##### Terminiantion
|
|
|
-Important to notice that its very deeply specified, where even the order of error triggering in scenarios with mulitple simultanous errors, is commited to up front, compared to a loser standard of saying that, if you have one of these problems, you will get at least one fo these errors,w hich would drop order.
|
|
|
+A full featured hierarchical topic based, and single moderator, membership forum is also introduced.
|
|
|
|
|
|
-- **pre-condition:** first order predicate in the runtime state and the transaction paramters which must hold _exactly_ for transaction to be accepted. e.g. that proper person has isgned?
|
|
|
-- **post-condition**: first order predicate in the runtime state and the transaction parameters which must hold _exactly_ when the transaction is accepted. The value of state variable `X` _after_ a transaction is handled, is denoted by `X'`. Hence, as an example, the condition that an integer variable `foo` has been incremented after a transaction is captured by the following predicate: `foo' == foo + 1`. Notice that blockchain state, like event logs ands o on, are not part of this, hence they are not in post-condition. (perhaps change?). It is OK to use separately defined functions to define this predicate, but these cannot have side effects.
|
|
|
+## Substrate Runtime
|
|
|
|
|
|
-Notice that no _iomplementaiton_ is ever provided, only how transaction generate new state constraints. This allows us to avoid any implementation specific types, and also allows all modules to be defiend in terms of what actual types are instantioned in the parametric `T::` trait, rather than introduce lots of trait abstractions.
|
|
|
+### Runtime Version
|
|
|
|
|
|
+- **spec_name:** `joystream-node`
|
|
|
+- **impl_name:** `joystream-node`
|
|
|
+- **authoring_version:** `5`
|
|
|
+- **spec_version:** `4`
|
|
|
+- **impl_version:** `0`
|
|
|
+- **apis:** `RUNTIME_API_VERSIONS`
|
|
|
|
|
|
-cponditionals are basically valid Rust code.
|
|
|
+### Native Version
|
|
|
|
|
|
-side ffects are pure, no
|
|
|
+- **runtime_version:** [Runtime Version](#runtime-version)
|
|
|
+<!-- - **can_author_with:** Default::default() -->
|
|
|
|
|
|
-functions used can only be pure, i.e. only depend on explicit parameters, and also have 0 side effcts.
|
|
|
+### Substrate Version
|
|
|
|
|
|
+`1.0.0`
|
|
|
|
|
|
-Always read stroage variables of any module through type, not varible name.
|
|
|
+### Modules
|
|
|
|
|
|
-##### REsult
|
|
|
+These are the Joystream specific modules, for each module, there is either a link to a module specification document, or no link, for already implemented modules (see [caveat](#caveat)). Standard configurations, for example based on values from the System module, are omitted.
|
|
|
|
|
|
-Here, all values are either before or after execution, using same tag symbol.
|
|
|
+An integrated explanation of the modules constituting the storage system is found [here](storage-system.md).
|
|
|
|
|
|
-##### Events
|
|
|
+#### Forum
|
|
|
|
|
|
-Same as result
|
|
|
+- **Description**: An on-chain discussion forum for members.
|
|
|
+- **Specification**: [**READ HERE**](runtime/forum-module.md)
|
|
|
+- **Status:** New.
|
|
|
+- **Configuration:**
|
|
|
+ - _ForumUserRegistry_: Proxy call to `get_profile` on [Membership](#membership) module.
|
|
|
|
|
|
-### Protocols
|
|
|
+#### Proposals
|
|
|
|
|
|
-<here we write stuff about how to read and understand our protocols>
|
|
|
+- **Description**: Proposal system, currently only supports runtime upgrades.
|
|
|
+- **Specification**: [**NA**](#)
|
|
|
+- **Status:** Unchanged from Athens.
|
|
|
+- **Configuration:**
|
|
|
+ - _Members_ : [Membership](#membership) module.
|
|
|
|
|
|
+#### CouncilElection
|
|
|
|
|
|
-## Glossary
|
|
|
+- **Description**: Council election manager for council system.
|
|
|
+- **Specification**: [**NA**](#)
|
|
|
+- **Status:** Unchanged from Athens.
|
|
|
+- **Configuration:**
|
|
|
+ - _CouncilElected_: [Council](#council) module
|
|
|
+ - _Members_: [Membership](#membership) module.
|
|
|
|
|
|
-- **Substrate:** A blockchain SDK
|
|
|
-- **Runtime:** Application specific consensus code written for the Substrate SDK. Includes state and transaction rules specific to the application, but excludes consensus algorithm and p2p networking.
|
|
|
-- **Substrate Module:** A substrate rutnime is partitoned into state and corresponding transaction types .. <= bad explanation.
|
|
|
-- **SRML:** Substrate standard runtime library (srml), is a set of highly reusable Substrate modules which come with the
|
|
|
-- **GRANDPA:** Consensus algorthm used.
|
|
|
+#### Council
|
|
|
|
|
|
-## Notation
|
|
|
+- **Description**: Council system.
|
|
|
+- **Specification**: [**NA**](#)
|
|
|
+- **Status:** Unchanged from Athens.
|
|
|
+- **Configuration:**
|
|
|
+ - _CouncilTermEnded_: [CouncilElection](#councilelection) module.
|
|
|
|
|
|
-- Code is written in Rust.
|
|
|
-- When describing state variables, the standard storage encoding,decoding offered by Substrate `decl_storage` is used, in particular
|
|
|
- - xx
|
|
|
- - xx
|
|
|
- - xx
|
|
|
-- In some cases transaction logic may be written in psuedocode, or just free form, over fully valid Rust.
|
|
|
+#### Memo
|
|
|
|
|
|
-## Specification
|
|
|
+- **Description**: Account based public message field.
|
|
|
+- **Specification**: [**NA**](#)
|
|
|
+- **Status:** Unchanged from Athens.
|
|
|
+- **Configuration:** Standard only.
|
|
|
|
|
|
-### Overview
|
|
|
+#### Membership
|
|
|
|
|
|
-something high level?
|
|
|
+- **Description**: Membership registry.
|
|
|
+- **Specification**: [**NA**](#)
|
|
|
+- **Status:** Unchanged from Athens.
|
|
|
+- **Configuration:**
|
|
|
+ - _Roles_: [Actors](#actors) module
|
|
|
+ - _MemberId_: `u64`
|
|
|
+ - _PaidTermId_: `u64`
|
|
|
+ - _SubscriptionId_: `u64`
|
|
|
|
|
|
-### Substrate Runtime
|
|
|
+#### Discovery
|
|
|
|
|
|
-#### WIP: API
|
|
|
+- **Description**: Host resolution system for public keys.
|
|
|
+- **Specification**: [**READ-HERE**](runtime/discovery-module.md)
|
|
|
+- **Status:** New.
|
|
|
+- **Configuration:**
|
|
|
+ - _Roles_: Shim trait which enables account lookup and by proxying to [Actors](#actors) module. Keeping this brief, since it will change.
|
|
|
|
|
|
-put lots of stuff here about what is in impl_runtime_apis! {}?
|
|
|
+#### Migration
|
|
|
|
|
|
-#### Substrate Version
|
|
|
+- **Description**: Runs migration & initialisation routines after on-chain upgrade from past testnet (Athens).
|
|
|
+- **Specification**: [**READ HERE**](runtime/migration-module.md)
|
|
|
+- **Status:** Updated to include initialisation of new forum after upgrade.
|
|
|
+- **Configuration:** Standard only.
|
|
|
|
|
|
-`1.0.0`
|
|
|
-
|
|
|
-#### [Types](#types)
|
|
|
+#### Actors
|
|
|
|
|
|
-#### functions
|
|
|
+- **Description**: Staking manager for storage system.
|
|
|
+- **Specification**: [**READ HERE**](runtime/staking-module.md)
|
|
|
+- **Status:** Unchanged from Athens.
|
|
|
+- **Configuration:**
|
|
|
+ - _Members_: [Membership](#membership) module.
|
|
|
+ - _OnActorRemoved_: Proxy call to `remove_account_info` on [Discovery](#discovery).
|
|
|
|
|
|
-like snure signed_
|
|
|
+#### DataObjectTypeRegistry
|
|
|
|
|
|
-https://crates.parity.io/srml_system/fn.ensure_signed.html
|
|
|
+- **Description**:
|
|
|
+- **Specification**: [**READ HERE**](runtime/data-object-type-registry-module.md)
|
|
|
+- **Status:** Unchanged from Athens.
|
|
|
+- **Configuration:**
|
|
|
+ - _DataObjectTypeId_: `u64`
|
|
|
|
|
|
-#### Modules
|
|
|
+#### DataDirectory
|
|
|
|
|
|
-These are the Joystream specific modules, and thus the only ones that actually need to have implementation done or altered.
|
|
|
+- **Description**:
|
|
|
+- **Specification**: [**READ HERE**](runtime/data-directory-module.md)
|
|
|
+- **Status:** Unchanged from Athens.
|
|
|
+- **Configuration:**
|
|
|
+ - _ContentId_: `primitives::H256`
|
|
|
+ - _SchemaId_: `u64`
|
|
|
+ - _Members_: [Membership](#membership) module.
|
|
|
+ - _Roles_: same as `Roles` configuration of [Discovery](#discovery) module.
|
|
|
+ - _IsActiveDataObjectType_: [DataObjectTypeRegistry](#dataobjecttyperegistry)
|
|
|
|
|
|
-- [**Proposals**](proposal-module.md)
|
|
|
-- [**CouncilElection**](council-election-module.md)
|
|
|
-- [**Council**](council-module.md)
|
|
|
-- [**Memo**](memo-module.md)
|
|
|
-- [**Members**](members-module.md)
|
|
|
- - MemberId : String
|
|
|
-- [**Migration**](migration-module.md)
|
|
|
-- [**Actors**](actors-module.md)
|
|
|
-- [**DataObjectTypeRegistry**](data-object-type-registry-module.md)
|
|
|
-- [**DataDirectory**](data-directory-module.md)
|
|
|
-- [**DataObjectStorageRegistry**](data-object-storage-registry-module.md)
|
|
|
-- [**DownloadSessions**](download-sessions-module.md)
|
|
|
-
|
|
|
-##### SRML
|
|
|
+#### DataObjectStorageRegistry
|
|
|
+
|
|
|
+- **Description**:
|
|
|
+- **Specification**: [**READ HERE**](runtime/data-object-storage-registry-module.md)
|
|
|
+- **Status:** Unchanged from Athens.
|
|
|
+- **Configuration:**
|
|
|
+ - _DataObjectStorageRelationshipId_: `u64`
|
|
|
+ - _Members_: [Membership](#membership) module.
|
|
|
+ - _Roles_: same as `Roles` configuration of [Discovery](#discovery) module.
|
|
|
+ - _ContentIdExists_: [DataDirectory](#datadirectory)
|
|
|
+
|
|
|
+#### DownloadSessions
|
|
|
+
|
|
|
+- **Description**: Manages download sessions in storage system.
|
|
|
+- **Specification**: [**NA**](#)
|
|
|
+- **Status:** Not used.
|
|
|
+- **Configuration:**
|
|
|
+ - _DownloadSessionId_: `u64`
|
|
|
+ - _ContentHasStorage_: [DataObjectStorageRegistry](#dataobjectstorageregistry)
|
|
|
+
|
|
|
+### SRML Modules
|
|
|
|
|
|
These modules are part of the runtime, but are already implemented part of the SRML.
|
|
|
|
|
|
-- [**System**](system-module.md)
|
|
|
-- [**Timestamp**](timestamp-module.md)
|
|
|
-- [**Consensus**](consensus-module.md)
|
|
|
-- [**Aura**](aura-module.md)
|
|
|
-- [**Indices**](indices-module.md)
|
|
|
-- [**Balances**](balance-module.md)
|
|
|
-- [**Session**](session-module.md)
|
|
|
-- [**Staking**](proposal-module.md)
|
|
|
-- [**Sudo**](proposal-module.md)
|
|
|
-- [**Grandpa**](proposal-module.md)
|
|
|
+- **System**: The system module provides low-level access to core types and cross-cutting utilities.
|
|
|
+- **Timestamp**: The Timestamp module provides functionality to get and set the on-chain time.
|
|
|
+- **Consensus**: The consensus module manages the authority set for the native code.
|
|
|
+- **Aura**: The Aura module extends Aura consensus by managing offline reporting.
|
|
|
+- **Indices**: An index is a short form of an address. This module handles allocation of indices for a newly created accounts.
|
|
|
+- **Balances**: The balances module provides functionality for handling accounts and balances.
|
|
|
+- **Session**: Is told the validators and allows them to manage their session keys for the consensus module.
|
|
|
+- **Staking**: The staking module is the means by which a set of network maintainers (known as _authorities_ in some contexts and _validators_ in others) are chosen based upon those who voluntarily place funds under deposit.
|
|
|
+- **Sudo**: The sudo module allows for a single account (called the "sudo key") to execute dispatchable functions that require a `Root` call or designate a new account to replace them as the sudo key.
|
|
|
+- **Grandpa**: This manages the GRANDPA authority set ready for the native code.
|
|
|
+
|
|
|
+### Runtime APIs
|
|
|
|
|
|
-#### MISSING STUFF
|
|
|
+The runtime implements the following set of APIs.
|
|
|
|
|
|
-#### Migrations
|
|
|
+#### [Core](https://crates.parity.io/substrate_client/runtime_api/trait.Core.html)
|
|
|
|
|
|
-list of what other runtimes one will introduce a migration from....
|
|
|
+- **version**: Return [Runtime Version](#runtime-version)
|
|
|
+- **execute_block**: Executive module `execute_block` routine.
|
|
|
+- **initialize_block**: Executive module `initialize_block` routine.
|
|
|
+- **authorities**: Executive module `apply_extrinsic` routine.
|
|
|
|
|
|
-"HOW TO DESCRIBE A MIGRATION"
|
|
|
+#### [Metadata](https://crates.parity.io/substrate_client/runtime_api/trait.Metadata.html)
|
|
|
|
|
|
-### Protocols
|
|
|
+- **metadata**: Runtime `metadata` routine.
|
|
|
|
|
|
-xxxx
|
|
|
+#### [BlockBuilder](https://crates.parity.io/substrate_client/block_builder/api/trait.BlockBuilder.html)
|
|
|
|
|
|
-#### Roles
|
|
|
+- **apply_extrinsic**: Executive module `apply_extrinsic` routine.
|
|
|
+- **finalize_block**: Executive module `finalize_block` routine.
|
|
|
+- **inherent_extrinsics**: `create_extrinsics` routine on inherent data.
|
|
|
+- **check_inherents**: Inherent `check_extrinsics` routine on block.
|
|
|
+- **random_seed**: System module `random_seed` routine.
|
|
|
|
|
|
-- role 1
|
|
|
-- role 2
|
|
|
+#### [TaggedTransactionQueue](https://crates.parity.io/substrate_client/runtime_api/trait.TaggedTransactionQueue.html)
|
|
|
|
|
|
-#### RPC
|
|
|
+- **validate_transaction**: Executive module `validate_transaction` routine.
|
|
|
|
|
|
-xxxx
|
|
|
+#### [OffchainWorkerApi](https://crates.parity.io/substrate_offchain/trait.OffchainWorkerApi.html)
|
|
|
|
|
|
-#### Peer To Peer
|
|
|
+- **offchain_worker**: Executive module `offchain_worker` routine.
|
|
|
|
|
|
-##### Messages
|
|
|
+#### [GrandpaApi](https://crates.parity.io/substrate_finality_grandpa_primitives/trait.GrandpaApi.html)
|
|
|
|
|
|
-###### Join
|
|
|
+- **grandpa_pending_change**, **grandpa_forced_change**, **grandpa_authorities**: Default.
|
|
|
|
|
|
-xxxxx
|
|
|
+#### [AuraApi](https://crates.parity.io/substrate_consensus_aura/trait.AuraApi.html)
|
|
|
|
|
|
-###### Leave
|
|
|
+- **slot_duration**: Auro module `slot_duration` routine.
|
|
|
|
|
|
-xxx
|
|
|
+#### [AuthoritiesApi](#)
|
|
|
|
|
|
-###### Advertise
|
|
|
+- **authorities**: Consensus module `authorities` routine.
|
|
|
|
|
|
-xxxxx
|
|
|
+<!--
|
|
|
|
|
|
+## Communication Protocols
|
|
|
|
|
|
-## References
|
|
|
+**TBD.**
|
|
|
|
|
|
-1. xxxx
|
|
|
+-->
|
Bedeho Mender