Skip to content
This repository has been archived by the owner on Nov 15, 2023. It is now read-only.

Child bounties comments #11053

Merged
merged 6 commits into from
Apr 16, 2022
Merged

Child bounties comments #11053

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
1a208a8
* formatting
nuke-web3 Mar 12, 2022
433ce7d
rm `parent_*` change
nuke-web3 Mar 16, 2022
6070cce
parent_bounty_id
nuke-web3 Mar 16, 2022
0810054
parent_index rm
nuke-web3 Mar 16, 2022
c011d40
fmt
nuke-web3 Mar 16, 2022
926111d
Apply suggestions from code review
nuke-web3 Mar 16, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 29 additions & 17 deletions frame/bounties/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,43 +2,55 @@

## 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.
Comment on lines +21 to +26
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

needs a check on my understanding

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are right:

substrate/frame/bounties/src/lib.rs

Line 668 in 26ea757

T::ChildBountyManager::child_bounties_count(bounty_id) == 0,


### 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
deposit is returned when/if the bounty is completed.
- **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

### 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
Expand Down
24 changes: 16 additions & 8 deletions frame/bounties/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -165,9 +173,9 @@ pub enum BountyStatus<AccountId, BlockNumber> {
},
}

/// The child-bounty manager.
/// The child bounty manager.
pub trait ChildBountyManager<Balance> {
/// 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.
Expand Down Expand Up @@ -221,7 +229,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<BalanceOf<Self>>;
}

Expand All @@ -246,7 +254,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,
Expand Down Expand Up @@ -542,7 +550,7 @@ pub mod pallet {
Bounties::<T>::try_mutate_exists(bounty_id, |maybe_bounty| -> DispatchResult {
let mut bounty = maybe_bounty.as_mut().ok_or(Error::<T>::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::<T>::HasActiveChildBounty
Expand Down Expand Up @@ -600,8 +608,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);

Expand Down Expand Up @@ -653,7 +661,7 @@ pub mod pallet {
|maybe_bounty| -> DispatchResultWithPostInfo {
let bounty = maybe_bounty.as_ref().ok_or(Error::<T>::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::<T>::HasActiveChildBounty
Expand Down
30 changes: 19 additions & 11 deletions frame/child-bounties/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
52 changes: 26 additions & 26 deletions frame/child-bounties/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
//!
Expand All @@ -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)]

Expand Down Expand Up @@ -101,7 +101,7 @@ pub struct ChildBounty<AccountId, Balance, BlockNumber> {
pub enum ChildBountyStatus<AccountId, BlockNumber> {
/// 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.
Expand Down Expand Up @@ -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<u32>;

Expand All @@ -162,7 +162,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,
}

Expand All @@ -189,14 +189,14 @@ pub mod pallet {
#[pallet::getter(fn child_bounty_count)]
pub type ChildBountyCount<T: Config> = 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<T: Config> =
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<T: Config> = StorageDoubleMap<
Expand Down Expand Up @@ -231,7 +231,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`].
///
Expand Down Expand Up @@ -430,12 +430,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.
///
Expand Down Expand Up @@ -489,7 +489,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| {
Expand Down Expand Up @@ -527,7 +527,7 @@ pub mod pallet {
update_due < frame_system::Pallet::<T>::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.
Expand Down Expand Up @@ -559,7 +559,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
Expand Down Expand Up @@ -824,7 +824,7 @@ impl<T: Config> Pallet<T> {
// 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.
Expand All @@ -839,7 +839,7 @@ impl<T: Config> Pallet<T> {
},
}

// 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::<T>::mutate(parent_bounty_id, |value| {
*value = value.saturating_sub(child_bounty.fee)
Expand Down Expand Up @@ -877,7 +877,7 @@ impl<T: Config> Pallet<T> {
}

// 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<T: Config> pallet_bounties::ChildBountyManager<BalanceOf<T>> for Pallet<T> {
fn child_bounties_count(
Expand Down