Merge pull request #189 from radicle-dev/message-doc

Add ledger message documentation to core

Author: Thomas Scholtes

DEVELOPING.md

@@ -63,7 +63,7 @@ Packages
   transactions and read state.
 * `core` contains basic types used throughout the Radicle Registry.
   If e.g. a trait or a datatype is used by more than one of the above packages,
-  it should probably go into `core`.
+  it should probably go into `core`. See `./core/README.md` for details.
 
 
 Running checks and tests

core/README.md

@@ -0,0 +1,28 @@
+radicle-registry-core
+=====================
+
+This package provides the types that constitute the registry ledger and provides
+exhaustive documentation how these types behave in the ledger.
+
+These types are the entities that are stored in the state, the different
+transaction message types, and their constituent types.
+
+Transaction Messages
+--------------------
+
+Transaction messages effect a change in the ledger state. They are submitted to
+the ledger as part of a transaction. All possible transaction messages are
+defined in the `message` module.
+
+For each message we document how it changes the state and what preconditions
+must be satisfied. The documentation must be comprehensive and exhaustive and
+cover all edge cases. The documentation for a message has the following sections
+
+<dl>
+  <dt>State changes</dt>
+  <dd>Describes which entities are added, removed, or updated in the ledger
+  state.</dd>
+  <dt>State-dependent validations</dt>
+  <dd>Describes the validations that are required for the message to be applied
+  successfully and that depend on the current ledger state state.</dd>
+</dd>

core/src/message.rs

@@ -13,40 +13,111 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-//! Transaction related types used in the Radicle Registry.
-
+//! All transaction messages that can be submitted to the ledger
+//!
+//! See the README.md for more information on how to document messages.
 extern crate alloc;
 
 use crate::{AccountId, Balance, Bytes128, CheckpointId, ProjectId};
 use parity_scale_codec::{Decode, Encode};
 use sp_core::H256;
 
+/// Registers a project on the Radicle Registry with the given ID.
+///
+/// # State changes
+///
+/// If successful, a new [crate::Project] with the given properties is added to the state.
+///
+/// [crate::Project::members] is initialized with the transaction author as the only member.
+///
+/// [crate::Project::account_id] is generated randomly.
+///
+/// # State-dependent validations
+///
+/// A project with the same ID must not yet exist.
+///
+/// A checkpoint with the given ID must exist.
 #[derive(Decode, Encode, Clone, Debug, Eq, PartialEq)]
 pub struct RegisterProject {
     pub id: ProjectId,
+
+    /// Initial checkpoint of the project.
     pub checkpoint_id: CheckpointId,
+
+    /// Opaque metadata that cannot be changed.
+    ///
+    /// Used by the application.
     pub metadata: Bytes128,
 }
 
+/// Add a new checkpoint to the state.
+///
+/// # State changes
+///
+/// If successful, adds a new [crate::Checkpoint] with the given parameters to the state.
+///
+/// # State-dependent validations
+///
+/// If `previous_checkpoint_id` is provided a checkpoint with the given ID must exist in the state.
 #[derive(Decode, Encode, Clone, Debug, Eq, PartialEq)]
 pub struct CreateCheckpoint {
     pub project_hash: H256,
     pub previous_checkpoint_id: Option<CheckpointId>,
 }
 
+/// Updates [crate::Project::current_cp].
+///
+/// # State changes
+///
+/// If successful, adds a new [crate::Checkpoint] with the given parameters to the state.
+///
+/// # State-dependent validations
+///
+/// The project `project_id` must exist.
+///
+/// The checkpoint `new_checkpoint_id` must exist.
+///
+/// The transaction author must be in [crate::Project::members] of the given project.
 #[derive(Decode, Encode, Clone, Debug, Eq, PartialEq)]
 pub struct SetCheckpoint {
     pub project_id: ProjectId,
     pub new_checkpoint_id: CheckpointId,
 }
 
+/// Transfer funds from a project account to an account
+///
+/// # State changes
+///
+/// If successful, `balance` is deducated from the project account and added to the the recipient
+/// account. The project account is given by [crate::Project::account_id] of the given project.
+///
+/// If the recipient account did not exist before, it is created. The recipient account may be a
+/// user account or a project account.
+///
+/// # State-dependent validations
+///
+/// The author must be a member of [crate::Project::members].
+///
+/// The project account must have a balance of at least `balance`.
 #[derive(Decode, Encode, Clone, Debug, Eq, PartialEq)]
 pub struct TransferFromProject {
     pub project: ProjectId,
     pub recipient: AccountId,
     pub value: Balance,
 }
 
+/// Transfer funds from one account to another.
+///
+/// # State changes
+///
+/// If successful, `balance` is deducated from the transaction author account and added to the the
+/// recipient account. If the recipient account did not exist before, it is created.
+///
+/// The recipient account may be a user account or a project account.
+///
+/// # State-dependent validations
+///
+/// The author account must have a balance of at least `balance`.
 #[derive(Decode, Encode, Clone, Debug, Eq, PartialEq)]
 pub struct Transfer {
     pub recipient: AccountId,

registry-spec/src/lib.rs

@@ -23,134 +23,6 @@
 pub mod error;
 pub mod types;
 
-/// A trait exposing the Radicle registry transactions described in the
-/// whitepaper.
-///
-/// The methods here return `Result<types::TxHash, E>` for some error type `E` as they
-/// will be applying a modification on the Registry global state, and return
-/// the hash of the applied transaction if they succeed.
-pub trait RegistryTransactions {
-    /// Transfer an amount of currency from one account to another.
-    ///
-    /// Method preconditions:
-    /// * Amount to be transferred is greater than or equal to 1 (one) unit of
-    /// currency.
-    fn transfer_oscoin(
-        // Account from which to send currency.
-        from_acc: types::AccountId,
-        // Account into which currency will be transferred.
-        to_acc: types::AccountId,
-        amount: types::Balance,
-    ) -> Result<types::TxHash, error::TransferError>;
-
-    /// Registers a project on the Radicle Registry and returns the new project’s ID.
-    ///
-    /// The transaction’s sender account becomes the initial maintainer of the
-    /// project, once it has been accepted into the registry.
-    ///
-    /// After submitting this transaction, the project will enter the
-    /// `PendingRegistrations` set, after which it can either be accepted or
-    /// rejected by an account in the `ROOT_ACCOUNT`s set with the appropriate
-    /// `accept_project/reject_project` transaction.
-    ///
-    /// Further, after submitting this transaction, regardless of whether the
-    /// project is later accepted or rejected, the registration fee is deducted
-    /// from the transaction sender's account - if no such available balance is
-    /// found, it will result in an error.
-    fn register_project(
-        // Requested name of the project to be registered.
-        project_id: types::ProjectId,
-        project_checkpoint: types::CheckpointId,
-        project_contract: types::Contract,
-        project_ownership_proof: types::ProjectOwnershipProof,
-        project_meta: types::Meta,
-    ) -> Result<types::TxHash, error::RegisterProjectError>;
-
-    /// Accept a project that has been submitted for registration.
-    ///
-    /// It is then removed from the pending registrations set, and can then be
-    /// retrieved using the `get_project()` method from `RegistryView`.
-    fn accept_project(
-        // Hash of the `register_project` transaction for the `Project` in
-        // question.
-        t_hash: types::TxHash,
-    ) -> Result<types::ProjectId, error::ProjectRegistrationVoteError>;
-
-    /// Reject a project that has been submitted for registration.
-    /// It is then removed from the pending registrations set.
-    fn reject_project(
-        // Hash of the `register_project` transaction for the `Project` in
-        // question.
-        t_hash: types::TxHash,
-    ) -> Result<types::TxHash, error::ProjectRegistrationVoteError>;
-
-    /// Transaction used to annul a previous `register_project` transaction,
-    /// if it has not been approved/rejected yet.
-    ///
-    /// If successful, the project referred to will be removed from the
-    /// pending registrations set
-    /// (see RegistryView::get_pending_project_registrations).
-    fn withdraw_project(
-        // Hash of the `register_project` whose candidacy is being withdrawn.
-        t_hash: types::TxHash,
-    ) -> Result<types::TxHash, error::WithdrawProjectError>;
-
-    /// Unregistering a project from the Radicle Registry.
-    ///
-    /// As is the case above, this transaction may also be handled outside the
-    /// registry.
-    fn unregister_project(
-        id: types::ProjectId,
-    ) -> Result<types::TxHash, error::UnregisterProjectError>;
-
-    /// Checkpointing a project in Radicle's registry.
-    fn checkpoint(
-        // Hash of the previous `checkpoint` associated with this project.
-        parent: Option<types::CheckpointId>,
-        // New project hash - if `set-checkpoint` if used with this checkpoint,
-        // this will become the project's current state hash.
-        new_project_hash: types::Hash,
-        new_project_version: types::Version,
-        // Hash-linked list of the checkpoint's contributions. To see more
-        // about this type, go to types::Contribution.
-        contribution_list: types::ContributionList,
-        // A vector of dependency updates. See types::DependencyUpdate
-        // for more information.
-        //
-        // It is to be treated as a list i.e. processed from left to right.
-        dependency_updates: Vec<types::DependencyUpdate>,
-    ) -> Result<types::TxHash, error::CheckpointError>;
-
-    /// Set a project's checkpoint in the Radicle registry.
-    ///
-    /// If a `set_checkpoint` transaction is successful, the project's new
-    /// checkpoint in the Radicle Registry will be the one passed to the
-    /// transaction.
-    ///
-    /// Anyone is allowed to execute this transaction.
-    ///
-    /// The project's first checkpoint, `k_0`, must be an ancestor of the
-    /// supplied checkpoint.
-    fn set_checkpoint(
-        // Id of the project to be updated.
-        project_id: types::ProjectId,
-        // Id of the checkpoint to be associated to the above project.
-        checkpoint_id: types::CheckpointId,
-    ) -> Result<types::TxHash, error::SetCheckpointError>;
-
-    /// Set a project's contract in the Radicle registry.
-    ///
-    /// If successful, it will set the project's contract to the one that was
-    /// supplied in the transaction.
-    fn set_contract(
-        // Id of the project whose contract is to be updated.
-        id: types::ProjectId,
-        //
-        // New contract to be associated to the project.
-        contract: types::Contract,
-    ) -> Result<types::TxHash, error::SetContractError>;
-}
-
 /// Functions to access information from the registry state.
 pub trait RegistryView {
     /// Returns the project registered at the given address.