finish treasury recipe, consider merging

JoshOrndorff · Sep 6, 2019 · 32e4db9 · 32e4db9
1 parent eeff977
commit 32e4db9
Show file tree

Hide file tree

Showing 17 changed files with 38 additions and 12 deletions.
diff --git a/kitchen/collateral/README.md b/kitchen/collateral/README.md
diff --git a/kitchen/storage/constants/Cargo.toml → kitchen/constants/Cargo.toml b/kitchen/storage/constants/Cargo.toml → kitchen/constants/Cargo.toml
diff --git a/kitchen/storage/constants/src/lib.rs → kitchen/constants/src/lib.rs b/kitchen/storage/constants/src/lib.rs → kitchen/constants/src/lib.rs
diff --git a/kitchen/collateral/imbalances/Cargo.toml → kitchen/imbalances/Cargo.toml b/kitchen/collateral/imbalances/Cargo.toml → kitchen/imbalances/Cargo.toml
diff --git a/kitchen/collateral/imbalances/src/lib.rs → kitchen/imbalances/src/lib.rs b/kitchen/collateral/imbalances/src/lib.rs → kitchen/imbalances/src/lib.rs
diff --git a/kitchen/storage/list/Cargo.toml → kitchen/list/Cargo.toml b/kitchen/storage/list/Cargo.toml → kitchen/list/Cargo.toml
diff --git a/kitchen/storage/list/src/lib.rs → kitchen/list/src/lib.rs b/kitchen/storage/list/src/lib.rs → kitchen/list/src/lib.rs
diff --git a/kitchen/collateral/lockable/Cargo.toml → kitchen/lockable/Cargo.toml b/kitchen/collateral/lockable/Cargo.toml → kitchen/lockable/Cargo.toml
diff --git a/kitchen/collateral/lockable/src/lib.rs → kitchen/lockable/src/lib.rs b/kitchen/collateral/lockable/src/lib.rs → kitchen/lockable/src/lib.rs
diff --git a/kitchen/collateral/reservable/Cargo.toml → kitchen/reservable/Cargo.toml b/kitchen/collateral/reservable/Cargo.toml → kitchen/reservable/Cargo.toml
diff --git a/kitchen/collateral/reservable/README.md → kitchen/reservable/README.md b/kitchen/collateral/reservable/README.md → kitchen/reservable/README.md
diff --git a/kitchen/collateral/reservable/src/lib.rs → kitchen/reservable/src/lib.rs b/kitchen/collateral/reservable/src/lib.rs → kitchen/reservable/src/lib.rs
diff --git a/kitchen/treasury/src/lib.rs b/kitchen/treasury/src/lib.rs
@@ -7,7 +7,6 @@ use support::traits::{
 };
 use runtime_primitives::traits::{Zero, AccountIdConversion};
 use runtime_primitives::ModuleId;
-use parity_scale_codec::{Encode, Decode};
 use system::{self, ensure_signed};
 
 type BalanceOf<T> = <<T as Trait>::Currency as Currency<<T as system::Trait>::AccountId>>::Balance;

diff --git a/kitchen/storage/value/Cargo.toml → kitchen/value/Cargo.toml b/kitchen/storage/value/Cargo.toml → kitchen/value/Cargo.toml
diff --git a/kitchen/storage/value/src/lib.rs → kitchen/value/src/lib.rs b/kitchen/storage/value/src/lib.rs → kitchen/value/src/lib.rs
diff --git a/src/tour/README.md b/src/tour/README.md
@@ -1,5 +1,12 @@
 # SRML Tour
 
-This section is [srml-tour](https://github.com/JoshOrndorff/srml-tour). It intends to explain the features of SRML modules, demonstrate use cases, and explore the code. It is *in progress*, tracked in [issues](https://github.com/substrate-developer-hub/recipes/issues).
+[srml-tour](https://github.com/JoshOrndorff/srml-tour) intends to explain the features of SRML modules, demonstrate use cases, and explore the code. It is *in progress*, tracked in [issues](https://github.com/substrate-developer-hub/recipes/issues).
 
-* [smpl-treasury](./treasury.md), [kitchen/treasury](https://github.com/substrate-developer-hub/recipes/tree/master/kitchen/treasury) - (1) instantiate a pot (2) proxy spending through the pot (3) schedule spending with configurable module constants
+## smpl-treasury
+
+**[recipe](./treasury.md)**
+1. instantiate a pot 
+2. proxy spending through the pot 
+3. schedule spending with configurable module constants
+
+[kitchen/treasury](https://github.com/substrate-developer-hub/recipes/tree/master/kitchen/treasury)
diff --git a/src/tour/treasury.md b/src/tour/treasury.md
@@ -2,11 +2,17 @@
 
 This recipe demonstrates how [srml/treasury](https://github.com/paritytech/substrate/blob/master/srml/treasury/src/lib.rs) instantiates a pot of funds and schedules funding. *See [kitchen/treasury](https://github.com/substrate-developer-hub/recipes/tree/master/kitchen/treasury) for the full code*
 
-## instantiate a pot
+## Instantiate a Pot
+
+To instantiate a pool of funds, import [`ModuleId`](https://crates.parity.io/sr_primitives/struct.ModuleId.html) and [`AccountIdConversion`](https://crates.parity.io/sr_primitives/traits/trait.AccountIdConversion.html) from [sr-primitives](https://crates.parity.io/sr_primitives/index.html).
 
 ```rust
 use runtime_primitives::{ModuleId, traits::AccountIdConversion};
+```
+
+With these imports, a `MODULE_ID` constant can be generated as an identifier for the pool of funds. This identifier can be converted into an `AccountId` with the `into_account()` method provided by the [`AccountIdConversion`](https://crates.parity.io/sr_primitives/traits/trait.AccountIdConversion.html) trait.
 
+```rust
 const MODULE_ID: ModuleId = ModuleId(*b"example ");
 
 impl<T: Trait> Module<T> {
@@ -20,7 +26,11 @@ impl<T: Trait> Module<T> {
 }
 ```
 
-## proxy transfers
+Accessing the pot's balance is as simple as using the [`Currency`](https://crates.parity.io/srml_support/traits/trait.Currency.html) trait to access the balance of the associated `AccountId`.
+
+## Proxy Transfers
+
+In [srml/treasury](https://github.com/paritytech/substrate/blob/master/srml/treasury/src/lib.rs), approved spending proposals are queued in runtime storage before they are scheduled for execution. For the example dispatch queue, each entry represents a request to transfer `BalanceOf<T>` to `T::AccountId` from the pot.
 
 ```rust
 decl_storage! {
@@ -29,7 +39,11 @@ decl_storage! {
 		SpendQ get(spend_q): Vec<(T::AccountId, BalanceOf<T>)>;
 	}
 }
+```
 
+In other words, the dispatch queue holds the `AccountId` of the recipient (destination) in the first field of the tuple and the `BalanceOf<T>` in the second field. The runtime method for adding a spend request to the queue looks like this
+
+```rust
 decl_module! {
 	pub struct Module<T: Trait> for enum Call where origin: T::Origin {
         // uses the example treasury as a proxy for transferring funds
@@ -45,18 +59,27 @@ decl_module! {
 }
 ```
 
-## schedule spending
+This method transfers some funds to the pot along with the request to transfer the same funds from the pot to a recipient (the input field `dest: T::AccountId`).
+
+NOTE: *Instead of relying on direct requests, [srml/treasury](https://github.com/paritytech/substrate/blob/master/srml/treasury/src/lib.rs) coordinates spending decisions through a proposal process.*
+
+## Scheduling Spending
+
+To schedule spending like [`srml/treasury`](https://github.com/paritytech/substrate/blob/master/srml/treasury/src/lib.rs), first add a configurable module constant in the `Trait`. This constant determines how often the spending queue is executed.
 
 ```rust
 pub trait Trait: system::Trait {
     /// Period between successive spends.
 	type SpendPeriod: Get<Self::BlockNumber>;
 }
+```
 
+This constant is invoked in the runtime method [`on_finalize`](https://crates.parity.io/sr_primitives/traits/trait.OnFinalize.html) to schedule spending every `T::SpendPeriod::get()` blocks.
+
+```rust
 decl_module! {
 	pub struct Module<T: Trait> for enum Call where origin: T::Origin {
         // other runtime methods
-
         fn on_finalize(n: T::BlockNumber) {
             if (n % T::SpendPeriod::get()).is_zero() {
                 Self::spend_funds();
@@ -65,3 +88,5 @@ decl_module! {
     }
 }
 ```
+
+*To see the logic within `spend_funds`, see the [kitchen/treasury](https://github.com/substrate-developer-hub/recipes/tree/master/kitchen/treasury).* This recipe could be extended to give priority to certain spend requests or set a cap on the spends for a given `spend_funds()` call.