1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453
// This file is part of Tetcore. // Copyright (C) 2017-2021 Parity Technologies (UK) Ltd. // SPDX-License-Identifier: Apache-2.0 // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. //! # Treasury Module //! //! The Treasury module provides a "pot" of funds that can be managed by stakeholders in the system //! and a structure for making spending proposals from this pot. //! //! - [`treasury::Config`](./trait.Config.html) //! - [`Call`](./enum.Call.html) //! //! ## Overview //! //! The Treasury Module itself provides the pot to store funds, and a means for stakeholders to //! propose, approve, and deny expenditures. The chain will need to provide a method (e.g. //! inflation, fees) for collecting funds. //! //! By way of example, the Council could vote to fund the Treasury with a portion of the block //! reward and use the funds to pay developers. //! //! //! ### Terminology //! //! - **Proposal:** A suggestion to allocate funds from the pot to a beneficiary. //! - **Beneficiary:** An account who will receive the funds from a proposal iff the proposal is //! approved. //! - **Deposit:** Funds that a proposer must lock when making a proposal. The deposit will be //! returned or slashed if the proposal is approved or rejected respectively. //! - **Pot:** Unspent funds accumulated by the treasury module. //! //! ## Interface //! //! ### Dispatchable Functions //! //! General spending/proposal protocol: //! - `propose_spend` - Make a spending proposal and stake the required deposit. //! - `reject_proposal` - Reject a proposal, slashing the deposit. //! - `approve_proposal` - Accept the proposal, returning the deposit. //! //! ## GenesisConfig //! //! The Treasury module depends on the [`GenesisConfig`](./struct.GenesisConfig.html). #![cfg_attr(not(feature = "std"), no_std)] #[cfg(test)] mod tests; mod benchmarking; pub mod weights; #[cfg(feature = "std")] use serde::{Serialize, Deserialize}; use tetcore_std::prelude::*; use fabric_support::{decl_module, decl_storage, decl_event, ensure, print, decl_error}; use fabric_support::traits::{ Currency, Get, Imbalance, OnUnbalanced, ExistenceRequirement::{KeepAlive}, ReservableCurrency, WithdrawReasons }; use tp_runtime::{Permill, ModuleId, RuntimeDebug, traits::{ Zero, StaticLookup, AccountIdConversion, Saturating }}; use fabric_support::weights::{Weight, DispatchClass}; use fabric_support::traits::{EnsureOrigin}; use codec::{Encode, Decode}; use fabric_system::{ensure_signed}; pub use weights::WeightInfo; pub type BalanceOf<T, I=DefaultInstance> = <<T as Config<I>>::Currency as Currency<<T as fabric_system::Config>::AccountId>>::Balance; pub type PositiveImbalanceOf<T, I=DefaultInstance> = <<T as Config<I>>::Currency as Currency<<T as fabric_system::Config>::AccountId>>::PositiveImbalance; pub type NegativeImbalanceOf<T, I=DefaultInstance> = <<T as Config<I>>::Currency as Currency<<T as fabric_system::Config>::AccountId>>::NegativeImbalance; pub trait Config<I=DefaultInstance>: fabric_system::Config { /// The treasury's module id, used for deriving its sovereign account ID. type ModuleId: Get<ModuleId>; /// The staking balance. type Currency: Currency<Self::AccountId> + ReservableCurrency<Self::AccountId>; /// Origin from which approvals must come. type ApproveOrigin: EnsureOrigin<Self::Origin>; /// Origin from which rejections must come. type RejectOrigin: EnsureOrigin<Self::Origin>; /// The overarching event type. type Event: From<Event<Self, I>> + Into<<Self as fabric_system::Config>::Event>; /// Handler for the unbalanced decrease when slashing for a rejected proposal or bounty. type OnSlash: OnUnbalanced<NegativeImbalanceOf<Self, I>>; /// Fraction of a proposal's value that should be bonded in order to place the proposal. /// An accepted proposal gets these back. A rejected proposal does not. type ProposalBond: Get<Permill>; /// Minimum amount of funds that should be placed in a deposit for making a proposal. type ProposalBondMinimum: Get<BalanceOf<Self, I>>; /// Period between successive spends. type SpendPeriod: Get<Self::BlockNumber>; /// Percentage of spare funds (if any) that are burnt per spend period. type Burn: Get<Permill>; /// Handler for the unbalanced decrease when treasury funds are burned. type BurnDestination: OnUnbalanced<NegativeImbalanceOf<Self, I>>; /// Weight information for extrinsics in this noble. type WeightInfo: WeightInfo; /// Runtime hooks to external noble using treasury to compute spend funds. type SpendFunds: SpendFunds<Self, I>; } /// A trait to allow the Treasury Noble to spend it's funds for other purposes. /// There is an expectation that the implementer of this trait will correctly manage /// the mutable variables passed to it: /// * `budget_remaining`: How much available funds that can be spent by the treasury. /// As funds are spent, you must correctly deduct from this value. /// * `imbalance`: Any imbalances that you create should be subsumed in here to /// maximize efficiency of updating the total issuance. (i.e. `deposit_creating`) /// * `total_weight`: Track any weight that your `spend_fund` implementation uses by /// updating this value. /// * `missed_any`: If there were items that you want to spend on, but there were /// not enough funds, mark this value as `true`. This will prevent the treasury /// from burning the excess funds. #[impl_trait_for_tuples::impl_for_tuples(30)] pub trait SpendFunds<T: Config<I>, I=DefaultInstance> { fn spend_funds( budget_remaining: &mut BalanceOf<T, I>, imbalance: &mut PositiveImbalanceOf<T, I>, total_weight: &mut Weight, missed_any: &mut bool, ); } /// An index of a proposal. Just a `u32`. pub type ProposalIndex = u32; /// A spending proposal. #[cfg_attr(feature = "std", derive(Serialize, Deserialize))] #[derive(Encode, Decode, Clone, PartialEq, Eq, RuntimeDebug)] pub struct Proposal<AccountId, Balance> { /// The account proposing it. proposer: AccountId, /// The (total) amount that should be paid if the proposal is accepted. value: Balance, /// The account to whom the payment should be made if the proposal is accepted. beneficiary: AccountId, /// The amount held on deposit (reserved) for making this proposal. bond: Balance, } decl_storage! { trait Store for Module<T: Config<I>, I: Instance=DefaultInstance> as Treasury { /// Number of proposals that have been made. ProposalCount get(fn proposal_count): ProposalIndex; /// Proposals that have been made. pub Proposals get(fn proposals): map hasher(twox_64_concat) ProposalIndex => Option<Proposal<T::AccountId, BalanceOf<T, I>>>; /// Proposal indices that have been approved but not yet awarded. pub Approvals get(fn approvals): Vec<ProposalIndex>; } add_extra_genesis { build(|_config| { // Create Treasury account let account_id = <Module<T, I>>::account_id(); let min = T::Currency::minimum_balance(); if T::Currency::free_balance(&account_id) < min { let _ = T::Currency::make_free_balance_be( &account_id, min, ); } }); } } decl_event!( pub enum Event<T, I=DefaultInstance> where Balance = BalanceOf<T, I>, <T as fabric_system::Config>::AccountId, { /// New proposal. \[proposal_index\] Proposed(ProposalIndex), /// We have ended a spend period and will now allocate funds. \[budget_remaining\] Spending(Balance), /// Some funds have been allocated. \[proposal_index, award, beneficiary\] Awarded(ProposalIndex, Balance, AccountId), /// A proposal was rejected; funds were slashed. \[proposal_index, slashed\] Rejected(ProposalIndex, Balance), /// Some of our funds have been burnt. \[burn\] Burnt(Balance), /// Spending has finished; this is the amount that rolls over until next spend. /// \[budget_remaining\] Rollover(Balance), /// Some funds have been deposited. \[deposit\] Deposit(Balance), } ); decl_error! { /// Error for the treasury module. pub enum Error for Module<T: Config<I>, I: Instance> { /// Proposer's balance is too low. InsufficientProposersBalance, /// No proposal or bounty at that index. InvalidIndex, } } decl_module! { pub struct Module<T: Config<I>, I: Instance=DefaultInstance> for enum Call where origin: T::Origin { /// Fraction of a proposal's value that should be bonded in order to place the proposal. /// An accepted proposal gets these back. A rejected proposal does not. const ProposalBond: Permill = T::ProposalBond::get(); /// Minimum amount of funds that should be placed in a deposit for making a proposal. const ProposalBondMinimum: BalanceOf<T, I> = T::ProposalBondMinimum::get(); /// Period between successive spends. const SpendPeriod: T::BlockNumber = T::SpendPeriod::get(); /// Percentage of spare funds (if any) that are burnt per spend period. const Burn: Permill = T::Burn::get(); /// The treasury's module id, used for deriving its sovereign account ID. const ModuleId: ModuleId = T::ModuleId::get(); type Error = Error<T, I>; fn deposit_event() = default; /// Put forward a suggestion for spending. A deposit proportional to the value /// is reserved and slashed if the proposal is rejected. It is returned once the /// proposal is awarded. /// /// # <weight> /// - Complexity: O(1) /// - DbReads: `ProposalCount`, `origin account` /// - DbWrites: `ProposalCount`, `Proposals`, `origin account` /// # </weight> #[weight = T::WeightInfo::propose_spend()] pub fn propose_spend( origin, #[compact] value: BalanceOf<T, I>, beneficiary: <T::Lookup as StaticLookup>::Source ) { let proposer = ensure_signed(origin)?; let beneficiary = T::Lookup::lookup(beneficiary)?; let bond = Self::calculate_bond(value); T::Currency::reserve(&proposer, bond) .map_err(|_| Error::<T, I>::InsufficientProposersBalance)?; let c = Self::proposal_count(); <ProposalCount<I>>::put(c + 1); <Proposals<T, I>>::insert(c, Proposal { proposer, value, beneficiary, bond }); Self::deposit_event(RawEvent::Proposed(c)); } /// Reject a proposed spend. The original deposit will be slashed. /// /// May only be called from `T::RejectOrigin`. /// /// # <weight> /// - Complexity: O(1) /// - DbReads: `Proposals`, `rejected proposer account` /// - DbWrites: `Proposals`, `rejected proposer account` /// # </weight> #[weight = (T::WeightInfo::reject_proposal(), DispatchClass::Operational)] pub fn reject_proposal(origin, #[compact] proposal_id: ProposalIndex) { T::RejectOrigin::ensure_origin(origin)?; let proposal = <Proposals<T, I>>::take(&proposal_id).ok_or(Error::<T, I>::InvalidIndex)?; let value = proposal.bond; let imbalance = T::Currency::slash_reserved(&proposal.proposer, value).0; T::OnSlash::on_unbalanced(imbalance); Self::deposit_event(Event::<T, I>::Rejected(proposal_id, value)); } /// Approve a proposal. At a later time, the proposal will be allocated to the beneficiary /// and the original deposit will be returned. /// /// May only be called from `T::ApproveOrigin`. /// /// # <weight> /// - Complexity: O(1). /// - DbReads: `Proposals`, `Approvals` /// - DbWrite: `Approvals` /// # </weight> #[weight = (T::WeightInfo::approve_proposal(), DispatchClass::Operational)] pub fn approve_proposal(origin, #[compact] proposal_id: ProposalIndex) { T::ApproveOrigin::ensure_origin(origin)?; ensure!(<Proposals<T, I>>::contains_key(proposal_id), Error::<T, I>::InvalidIndex); Approvals::<I>::append(proposal_id); } /// # <weight> /// - Complexity: `O(A)` where `A` is the number of approvals /// - Db reads and writes: `Approvals`, `pot account data` /// - Db reads and writes per approval: /// `Proposals`, `proposer account data`, `beneficiary account data` /// - The weight is overestimated if some approvals got missed. /// # </weight> fn on_initialize(n: T::BlockNumber) -> Weight { // Check to see if we should spend some funds! if (n % T::SpendPeriod::get()).is_zero() { Self::spend_funds() } else { 0 } } } } impl<T: Config<I>, I: Instance> Module<T, I> { // Add public immutables and private mutables. /// The account ID of the treasury pot. /// /// This actually does computation. If you need to keep using it, then make sure you cache the /// value and only call this once. pub fn account_id() -> T::AccountId { T::ModuleId::get().into_account() } /// The needed bond for a proposal whose spend is `value`. fn calculate_bond(value: BalanceOf<T, I>) -> BalanceOf<T, I> { T::ProposalBondMinimum::get().max(T::ProposalBond::get() * value) } /// Spend some money! returns number of approvals before spend. pub fn spend_funds() -> Weight { let mut total_weight: Weight = Zero::zero(); let mut budget_remaining = Self::pot(); Self::deposit_event(RawEvent::Spending(budget_remaining)); let account_id = Self::account_id(); let mut missed_any = false; let mut imbalance = <PositiveImbalanceOf<T, I>>::zero(); let proposals_len = Approvals::<I>::mutate(|v| { let proposals_approvals_len = v.len() as u32; v.retain(|&index| { // Should always be true, but shouldn't panic if false or we're screwed. if let Some(p) = Self::proposals(index) { if p.value <= budget_remaining { budget_remaining -= p.value; <Proposals<T, I>>::remove(index); // return their deposit. let _ = T::Currency::unreserve(&p.proposer, p.bond); // provide the allocation. imbalance.subsume(T::Currency::deposit_creating(&p.beneficiary, p.value)); Self::deposit_event(RawEvent::Awarded(index, p.value, p.beneficiary)); false } else { missed_any = true; true } } else { false } }); proposals_approvals_len }); total_weight += T::WeightInfo::on_initialize_proposals(proposals_len); // Call Runtime hooks to external noble using treasury to compute spend funds. T::SpendFunds::spend_funds( &mut budget_remaining, &mut imbalance, &mut total_weight, &mut missed_any); if !missed_any { // burn some proportion of the remaining budget if we run a surplus. let burn = (T::Burn::get() * budget_remaining).min(budget_remaining); budget_remaining -= burn; let (debit, credit) = T::Currency::pair(burn); imbalance.subsume(debit); T::BurnDestination::on_unbalanced(credit); Self::deposit_event(RawEvent::Burnt(burn)) } // Must never be an error, but better to be safe. // proof: budget_remaining is account free balance minus ED; // Thus we can't spend more than account free balance minus ED; // Thus account is kept alive; qed; if let Err(problem) = T::Currency::settle( &account_id, imbalance, WithdrawReasons::TRANSFER, KeepAlive ) { print("Inconsistent state - couldn't settle imbalance for funds spent by treasury"); // Nothing else to do here. drop(problem); } Self::deposit_event(RawEvent::Rollover(budget_remaining)); total_weight } /// Return the amount of money in the pot. // The existential deposit is not part of the pot so treasury account never gets deleted. pub fn pot() -> BalanceOf<T, I> { T::Currency::free_balance(&Self::account_id()) // Must never be less than 0 but better be safe. .saturating_sub(T::Currency::minimum_balance()) } } impl<T: Config<I>, I: Instance> OnUnbalanced<NegativeImbalanceOf<T, I>> for Module<T, I> { fn on_nonzero_unbalanced(amount: NegativeImbalanceOf<T, I>) { let numeric_amount = amount.peek(); // Must resolve into existing but better to be safe. let _ = T::Currency::resolve_creating(&Self::account_id(), amount); Self::deposit_event(RawEvent::Deposit(numeric_amount)); } }