diff --git a/frame/bounties/README.md b/frame/bounties/README.md index bf63fca5f34b2..232334cb1edd6 100644 --- a/frame/bounties/README.md +++ b/frame/bounties/README.md @@ -2,28 +2,38 @@ ## Bounty -**Note :: This pallet is tightly coupled with pallet-treasury** +> NOTE: This pallet is tightly coupled with pallet-treasury. -A Bounty Spending is a reward for a specified body of work - or specified set of objectives - that -needs to be executed for a predefined Treasury amount to be paid out. A curator is assigned after -the bounty is approved and funded by Council, to be delegated with the responsibility of assigning a -payout address once the specified set of objectives is completed. +A Bounty Spending is a reward for a specified body of work - or specified set of objectives - +that needs to be executed for a predefined Treasury amount to be paid out. A curator is assigned +after the bounty is approved and funded by Council, to be delegated with the responsibility of +assigning a payout address once the specified set of objectives is completed. -After the Council has activated a bounty, it delegates the work that requires expertise to a curator -in exchange of a deposit. Once the curator accepts the bounty, they get to close the active bounty. -Closing the active bounty enacts a delayed payout to the payout address, the curator fee and the -return of the curator deposit. The delay allows for intervention through regular democracy. The -Council gets to unassign the curator, resulting in a new curator election. The Council also gets to -cancel the bounty if deemed necessary before assigning a curator or once the bounty is active or -payout is pending, resulting in the slash of the curator's deposit. +After the Council has activated a bounty, it delegates the work that requires expertise to a +curator in exchange of a deposit. Once the curator accepts the bounty, they get to close the +active bounty. Closing the active bounty enacts a delayed payout to the payout address, the +curator fee and the return of the curator deposit. The delay allows for intervention through +regular democracy. The Council gets to unassign the curator, resulting in a new curator +election. The Council also gets to cancel the bounty if deemed necessary before assigning a +curator or once the bounty is active or payout is pending, resulting in the slash of the +curator's deposit. + +This pallet may opt into using a [`ChildBountyManager`] that enables bounties to be split into +sub-bounties, as children of anh established bounty (called the parent in the context of it's +children). + +> NOTE: The parent bounty cannot be closed if it has a non-zero number of it has active child +> bounties associated with it. ### Terminology -- **Bounty spending proposal:** A proposal to reward a predefined body of work upon completion by - the Treasury. +Bounty: + +- **Bounty spending proposal:** A proposal to reward a predefined body of work upon completion + by the Treasury. - **Proposer:** An account proposing a bounty spending. -- **Curator:** An account managing the bounty and assigning a payout address receiving the reward - for the completion of work. +- **Curator:** An account managing the bounty and assigning a payout address receiving the + reward for the completion of work. - **Deposit:** The amount held on deposit for placing a bounty proposal plus the amount held on deposit per byte within the bounty description. - **Curator deposit:** The payment from a candidate willing to curate an approved bounty. The @@ -31,7 +41,8 @@ payout is pending, resulting in the slash of the curator's deposit. - **Bounty value:** The total amount that should be paid to the Payout Address if the bounty is rewarded. - **Payout address:** The account to which the total or part of the bounty is assigned to. -- **Payout Delay:** The delay period for which a bounty beneficiary needs to wait before claiming. +- **Payout Delay:** The delay period for which a bounty beneficiary needs to wait before + claiming. - **Curator fee:** The reserved upfront payment for a curator for work related to the bounty. ## Interface @@ -39,6 +50,7 @@ payout is pending, resulting in the slash of the curator's deposit. ### Dispatchable Functions Bounty protocol: + - `propose_bounty` - Propose a specific treasury amount to be earmarked for a predefined set of tasks and stake the required deposit. - `approve_bounty` - Accept a specific treasury amount to be earmarked for a predefined body of diff --git a/frame/bounties/src/lib.rs b/frame/bounties/src/lib.rs index 98f2da305a06d..886c758bbe42e 100644 --- a/frame/bounties/src/lib.rs +++ b/frame/bounties/src/lib.rs @@ -35,10 +35,17 @@ //! curator or once the bounty is active or payout is pending, resulting in the slash of the //! curator's deposit. //! +//! This pallet may opt into using a [`ChildBountyManager`] that enables bounties to be split into +//! sub-bounties, as children of anh established bounty (called the parent in the context of it's +//! children). +//! +//! > NOTE: The parent bounty cannot be closed if it has a non-zero number of it has active child +//! > bounties associated with it. //! //! ### Terminology //! //! Bounty: +//! //! - **Bounty spending proposal:** A proposal to reward a predefined body of work upon completion //! by the Treasury. //! - **Proposer:** An account proposing a bounty spending. @@ -60,6 +67,7 @@ //! ### Dispatchable Functions //! //! Bounty protocol: +//! //! - `propose_bounty` - Propose a specific treasury amount to be earmarked for a predefined set of //! tasks and stake the required deposit. //! - `approve_bounty` - Accept a specific treasury amount to be earmarked for a predefined body of @@ -165,9 +173,9 @@ pub enum BountyStatus { }, } -/// The child-bounty manager. +/// The child bounty manager. pub trait ChildBountyManager { - /// Get the active child-bounties for a parent bounty. + /// Get the active child bounties for a parent bounty. fn child_bounties_count(bounty_id: BountyIndex) -> BountyIndex; /// Get total curator fees of children-bounty curators. @@ -231,7 +239,7 @@ pub mod pallet { /// Weight information for extrinsics in this pallet. type WeightInfo: WeightInfo; - /// The child-bounty manager. + /// The child bounty manager. type ChildBountyManager: ChildBountyManager>; } @@ -256,7 +264,7 @@ pub mod pallet { PendingPayout, /// The bounties cannot be claimed/closed because it's still in the countdown period. Premature, - /// The bounty cannot be closed because it has active child-bounties. + /// The bounty cannot be closed because it has active child bounties. HasActiveChildBounty, /// Too many approvals are already queued. TooManyQueued, @@ -552,7 +560,7 @@ pub mod pallet { Bounties::::try_mutate_exists(bounty_id, |maybe_bounty| -> DispatchResult { let mut bounty = maybe_bounty.as_mut().ok_or(Error::::InvalidIndex)?; - // Ensure no active child-bounties before processing the call. + // Ensure no active child bounties before processing the call. ensure!( T::ChildBountyManager::child_bounties_count(bounty_id) == 0, Error::::HasActiveChildBounty @@ -610,8 +618,8 @@ pub mod pallet { let err_amount = T::Currency::unreserve(&curator, bounty.curator_deposit); debug_assert!(err_amount.is_zero()); - // Get total child-bounties curator fees, and subtract it from master curator - // fee. + // Get total child bounties curator fees, and subtract it from the parent + // curator fee (the fee in present referenced bounty, `self`). let children_fee = T::ChildBountyManager::children_curator_fees(bounty_id); debug_assert!(children_fee <= fee); @@ -663,7 +671,7 @@ pub mod pallet { |maybe_bounty| -> DispatchResultWithPostInfo { let bounty = maybe_bounty.as_ref().ok_or(Error::::InvalidIndex)?; - // Ensure no active child-bounties before processing the call. + // Ensure no active child bounties before processing the call. ensure!( T::ChildBountyManager::child_bounties_count(bounty_id) == 0, Error::::HasActiveChildBounty diff --git a/frame/child-bounties/README.md b/frame/child-bounties/README.md index e07996d54957a..695b6616b1751 100644 --- a/frame/child-bounties/README.md +++ b/frame/child-bounties/README.md @@ -1,21 +1,29 @@ -# Child Bounties Pallet (pallet-child-bounties) +# Child Bounties Pallet ( `pallet-child-bounties` ) ## Child Bounty -> NOTE: This pallet is tightly coupled with pallet-treasury and pallet-bounties. +> NOTE: This pallet is tightly coupled with `pallet-treasury` and `pallet-bounties`. -With child bounties, a large bounty proposal can be divided into smaller chunks, for parallel execution, and for efficient governance and tracking of spent funds. - -A child-bounty is a smaller piece of work, extracted from a parent bounty. A curator is assigned after the child-bounty is created by the parent bounty curator, to be delegated with the responsibility of assigning a payout address once the specified set of tasks is completed. +With child bounties, a large bounty proposal can be divided into smaller chunks, +for parallel execution, and for efficient governance and tracking of spent funds. +A child bounty is a smaller piece of work, extracted from a parent bounty. +A curator is assigned after the child bounty is created by the parent bounty curator, +to be delegated with the responsibility of assigning a payout address once +the specified set of tasks is completed. ## Interface ### Dispatchable Functions -- `add_child_bounty` - Add a child-bounty for a parent-bounty to for dividing the work in smaller tasks. -- `propose_curator` - Assign an account to a child-bounty as candidate curator. -- `accept_curator` - Accept a child-bounty assignment from the parent-bounty curator, setting a curator deposit. +Child Bounty protocol: + +- `add_child_bounty` - Add a child bounty for a parent bounty to for dividing the work in + smaller tasks. +- `propose_curator` - Assign an account to a child bounty as candidate curator. +- `accept_curator` - Accept a child bounty assignment from the parent bounty curator, + setting a curator deposit. - `award_child_bounty` - Close and pay out the specified amount for the completed work. -- `claim_child_bounty` - Claim a specific child-bounty amount from the payout address. -- `unassign_curator` - Unassign an accepted curator from a specific child-bounty. -- `close_child_bounty` - Cancel the child-bounty for a specific treasury amount and close the bounty. +- `claim_child_bounty` - Claim a specific child bounty amount from the payout address. +- `unassign_curator` - Unassign an accepted curator from a specific child bounty. +- `close_child_bounty` - Cancel the child bounty for a specific treasury amount + and close the bounty. diff --git a/frame/child-bounties/src/lib.rs b/frame/child-bounties/src/lib.rs index 2fea61c045cf6..0bbd4512443d7 100644 --- a/frame/child-bounties/src/lib.rs +++ b/frame/child-bounties/src/lib.rs @@ -15,16 +15,16 @@ // See the License for the specific language governing permissions and // limitations under the License. -//! # Child Bounties Pallet ( pallet-child-bounties ) +//! # Child Bounties Pallet ( `pallet-child-bounties` ) //! //! ## Child Bounty //! -//! > NOTE: This pallet is tightly coupled with pallet-treasury and pallet-bounties. +//! > NOTE: This pallet is tightly coupled with `pallet-treasury` and `pallet-bounties`. //! //! With child bounties, a large bounty proposal can be divided into smaller chunks, //! for parallel execution, and for efficient governance and tracking of spent funds. -//! A child-bounty is a smaller piece of work, extracted from a parent bounty. -//! A curator is assigned after the child-bounty is created by the parent bounty curator, +//! A child bounty is a smaller piece of work, extracted from a parent bounty. +//! A curator is assigned after the child bounty is created by the parent bounty curator, //! to be delegated with the responsibility of assigning a payout address once the specified //! set of tasks is completed. //! @@ -33,22 +33,22 @@ //! ### Dispatchable Functions //! //! Child Bounty protocol: -//! - `add_child_bounty` - Add a child-bounty for a parent-bounty to for dividing the work in +//! - `add_child_bounty` - Add a child bounty for a parent bounty to for dividing the work in //! smaller tasks. -//! - `propose_curator` - Assign an account to a child-bounty as candidate curator. -//! - `accept_curator` - Accept a child-bounty assignment from the parent-bounty curator, setting a +//! - `propose_curator` - Assign an account to a child bounty as candidate curator. +//! - `accept_curator` - Accept a child bounty assignment from the parent bounty curator, setting a //! curator deposit. //! - `award_child_bounty` - Close and pay out the specified amount for the completed work. -//! - `claim_child_bounty` - Claim a specific child-bounty amount from the payout address. -//! - `unassign_curator` - Unassign an accepted curator from a specific child-bounty. -//! - `close_child_bounty` - Cancel the child-bounty for a specific treasury amount and close the +//! - `claim_child_bounty` - Claim a specific child bounty amount from the payout address. +//! - `unassign_curator` - Unassign an accepted curator from a specific child bounty. +//! - `close_child_bounty` - Cancel the child bounty for a specific treasury amount and close the //! bounty. // Most of the business logic in this pallet has been // originally contributed by "https://github.com/shamb0", // as part of the PR - https://github.com/paritytech/substrate/pull/7965. // The code has been moved here and then refactored in order to -// extract child-bounties as a separate pallet. +// extract child bounties as a separate pallet. #![cfg_attr(not(feature = "std"), no_std)] @@ -101,7 +101,7 @@ pub struct ChildBounty { pub enum ChildBountyStatus { /// The child-bounty is added and waiting for curator assignment. Added, - /// A curator has been proposed by the parent-bounty curator. Waiting for + /// A curator has been proposed by the parent bounty curator. Waiting for /// acceptance from the child-bounty curator. CuratorProposed { /// The assigned child-bounty curator of this bounty. @@ -136,7 +136,7 @@ pub mod pallet { pub trait Config: frame_system::Config + pallet_treasury::Config + pallet_bounties::Config { - /// Maximum number of child-bounties that can be added to a parent bounty. + /// Maximum number of child bounties that can be added to a parent bounty. #[pallet::constant] type MaxActiveChildBountyCount: Get; @@ -157,7 +157,7 @@ pub mod pallet { ParentBountyNotActive, /// The bounty balance is not enough to add new child-bounty. InsufficientBountyBalance, - /// Number of child-bounties exceeds limit `MaxActiveChildBountyCount`. + /// Number of child bounties exceeds limit `MaxActiveChildBountyCount`. TooManyChildBounties, } @@ -184,14 +184,14 @@ pub mod pallet { #[pallet::getter(fn child_bounty_count)] pub type ChildBountyCount = StorageValue<_, BountyIndex, ValueQuery>; - /// Number of child-bounties per parent bounty. + /// Number of child bounties per parent bounty. /// Map of parent bounty index to number of child bounties. #[pallet::storage] #[pallet::getter(fn parent_child_bounties)] pub type ParentChildBounties = StorageMap<_, Twox64Concat, BountyIndex, u32, ValueQuery>; - /// Child-bounties that have been added. + /// Child bounties that have been added. #[pallet::storage] #[pallet::getter(fn child_bounties)] pub type ChildBounties = StorageDoubleMap< @@ -226,7 +226,7 @@ pub mod pallet { /// parent bounty to child-bounty account, if parent bounty has enough /// funds, else the call fails. /// - /// Upper bound to maximum number of active child-bounties that can be + /// Upper bound to maximum number of active child bounties that can be /// added are managed via runtime trait config /// [`Config::MaxActiveChildBountyCount`]. /// @@ -427,12 +427,12 @@ pub mod pallet { /// the curator of the parent bounty, or any signed origin. /// /// For the origin other than T::RejectOrigin and the child-bounty - /// curator, parent-bounty must be in active state, for this call to + /// curator, parent bounty must be in active state, for this call to /// work. We allow child-bounty curator and T::RejectOrigin to execute - /// this call irrespective of the parent-bounty state. + /// this call irrespective of the parent bounty state. /// /// If this function is called by the `RejectOrigin` or the - /// parent-bounty curator, we assume that the child-bounty curator is + /// parent bounty curator, we assume that the child-bounty curator is /// malicious or inactive. As a result, child-bounty curator deposit is /// slashed. /// @@ -486,7 +486,7 @@ pub mod pallet { }, ChildBountyStatus::CuratorProposed { ref curator } => { // A child-bounty curator has been proposed, but not accepted yet. - // Either `RejectOrigin`, parent-bounty curator or the proposed + // Either `RejectOrigin`, parent bounty curator or the proposed // child-bounty curator can unassign the child-bounty curator. ensure!( maybe_sender.map_or(true, |sender| { @@ -524,7 +524,7 @@ pub mod pallet { update_due < frame_system::Pallet::::block_number() { // Slash the child-bounty curator if - // + the call is made by the parent-bounty curator. + // + the call is made by the parent bounty curator. // + or the curator is inactive. slash_curator(curator, &mut child_bounty.curator_deposit); // Continue to change bounty status below. @@ -556,7 +556,7 @@ pub mod pallet { /// /// The beneficiary will be able to claim the funds after a delay. /// - /// The dispatch origin for this call must be the master curator or + /// The dispatch origin for this call must be the parent curator or /// curator of this child-bounty. /// /// Parent bounty must be in active state, for this child-bounty call to @@ -835,7 +835,7 @@ impl Pallet { // Nothing extra to do besides the removal of the child-bounty below. }, ChildBountyStatus::Active { curator } => { - // Cancelled by master curator or RejectOrigin, + // Cancelled by parent curator or RejectOrigin, // refund deposit of the working child-bounty curator. let _ = T::Currency::unreserve(curator, child_bounty.curator_deposit); // Then execute removal of the child-bounty below. @@ -850,7 +850,7 @@ impl Pallet { }, } - // Revert the curator fee back to parent-bounty curator & + // Revert the curator fee back to parent bounty curator & // reduce the active child-bounty count. ChildrenCuratorFees::::mutate(parent_bounty_id, |value| { *value = value.saturating_sub(child_bounty.fee) @@ -888,7 +888,7 @@ impl Pallet { } // Implement ChildBountyManager to connect with the bounties pallet. This is -// where we pass the active child-bounties and child curator fees to the parent +// where we pass the active child bounties and child curator fees to the parent // bounty. impl pallet_bounties::ChildBountyManager> for Pallet { fn child_bounties_count(