diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index e1be0e9..0a30083 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -6,16 +6,17 @@ * Runtime Descriptions ** xref:runtime/xcm_executor.adoc[XCM Executor] * Pallet Specifications -** xref:pallets/collator-selection.adoc[collator_selection] ** xref:pallets/aura_ext.adoc[cumulus_pallet_aura_ext] ** xref:pallets/parachain-system.adoc[cumulus_pallet_parachain_system] ** xref:pallets/xcmp-queue.adoc[cumulus_pallet_xcmp_queue] ** xref:pallets/assets.adoc[pallet_assets] ** xref:pallets/balances.adoc[pallet_balances] +** xref:pallets/collator-selection.adoc[pallet_collator_selection] ** xref:pallets/message-queue.adoc[pallet_message_queue] ** xref:pallets/multisig.adoc[pallet_multisig] ** xref:pallets/proxy.adoc[pallet_proxy] ** xref:pallets/transaction_payment.adoc[pallet_transaction_payment] +** xref:pallets/treasury.adoc[pallet_treasury] ** xref:pallets/xcm.adoc[pallet_xcm] * Misc ** xref:misc/multisig-accounts.adoc[Multisig Accounts] diff --git a/docs/modules/ROOT/pages/glossary.adoc b/docs/modules/ROOT/pages/glossary.adoc index 3f8963f..5636a4c 100644 --- a/docs/modules/ROOT/pages/glossary.adoc +++ b/docs/modules/ROOT/pages/glossary.adoc @@ -65,7 +65,7 @@ An asset meaning that it is not interchangeable with other assets of the same ty == H -=== Hold +=== Hold `Hold` means reserving/holding an amount of balance from an account. The `Hold` amount cannot be spent, but still belongs to the account. For example, depositing modifying the state, and occupying space. This deposit will be repaid once the occupied space is freed. == I @@ -90,7 +90,7 @@ Junctions is multiple `Junction`s, formed only through <> constru A fee proportional to the encoded length of the transaction. -=== Lock +=== Lock Nearly the same as `<>`, with 2 major differences: @@ -139,7 +139,7 @@ Pure account is an account that was spawned only to be a <> for some == R -=== Reserve +=== Reserve Deprecated, use `<>`. @@ -181,4 +181,4 @@ The time it takes to execute runtime logic. By controlling the execution time th === Weight Fee -A fee proportional to amount of <> a transaction consumes. \ No newline at end of file +A fee proportional to amount of <> a transaction consumes. diff --git a/docs/modules/ROOT/pages/pallets/treasury.adoc b/docs/modules/ROOT/pages/pallets/treasury.adoc new file mode 100644 index 0000000..258d297 --- /dev/null +++ b/docs/modules/ROOT/pages/pallets/treasury.adoc @@ -0,0 +1,245 @@ +:source-highlighter: highlight.js +:highlightjs-languages: rust +:github-icon: pass:[] + += pallet_treasury + +Branch/Release: `release-polkadot-v1.10.0` + +== Source Code link:https://github.com/paritytech/polkadot-sdk/blob/release-polkadot-v1.10.0/substrate/frame/treasury/src/lib.rs[{github-icon},role=heading-link] + +== Purpose + +The Treasury pallet provides a “pot” of funds that can be managed by stakeholders in the system and a structure for making spending proposals from this pot. + +== Config + +* Pallet-specific configs +** `SpendPeriod` -- Period between successive spends. "Spend" means, treasury spending money to a proposal. `SpendPeriod` determines how often the treasury pallet distributes the assets to the proposals. +** `Burn` -- Percentage of spare funds (if any) that are burnt per spend period. +** `BurnDestination` -- Handler for the unbalanced decrease when treasury funds are burned. +** `SpendFunds` -- Runtime hooks to external pallet using treasury to compute spend funds. +** `MaxApprovals` -- The maximum number of approvals that can wait in the spending queue. NOTE: This parameter is also used within the Bounties Pallet extension if enabled. +** `AssetKind` -- Type parameter representing the asset kinds to be spent from the treasury. +** `Beneficiary` -- Type parameter used to identify the beneficiaries eligible to receive treasury spends. +** `BeneficiaryLookup` -- Converting trait to take a source type and convert to [`Self::Beneficiary`]. +** `Paymaster` -- Type for processing spends of [Self::AssetKind] in favor of [`Self::Beneficiary`]. +** `BalanceConverter` -- Type for converting the balance of an [Self::AssetKind] to the balance of the native asset, solely for the purpose of asserting the result against the maximum allowed spend amount of the [`Self::SpendOrigin`]. +** `PayoutPeriod` -- The period during which an approved treasury spend has to be claimed by the beneficiary of the proposal. + +* Pallet-specific origins: +** `RejectOrigin` -- Origin from which rejections must come. +** `SpendOrigin` -- The origin required for approving spends from the treasury outside of the proposal process. The `Success` value is the maximum amount in a native asset that this origin is allowed to spend at a time. + +* Common configs +** `Currency` -- The staking balance. +** `RuntimeEvent` -- The overarching event type. +** `PalletId` -- The treasury's pallet id, used for deriving its sovereign account ID. +** `WeightInfo` -- Weight information for extrinsics in this pallet. +** `BenchmarkHelper` -- Helper type for benchmarks. + +== Dispatchables + +[.contract-item] +[[spend_local]] +==== `[.contract-item-name]#++spend_local++#` +[source,rust] +---- +pub fn spend_local( + origin: OriginFor, + #[pallet::compact] amount: BalanceOf, + beneficiary: AccountIdLookupOf, +) -> DispatchResult +---- +Propose and approve a spend of treasury funds, enables the creation of spends using the native currency of the chain, utilizing the funds stored in the pot. + +NOTE: For record-keeping purposes, the proposer is deemed to be equivalent to the beneficiary. + +NOTE: The behavior and API of the old `spend` call capable of spending local DOT tokens remain unchanged, and is now under the name `spend_local`. The revised +new `spend` call is able to spend any asset kind managed by the treasury. + + +**Params:** + +* `origin: OriginFor` -- Must be [`Config::SpendOrigin`] with the `Success` value being at least `amount`. +* `value: BalanceOf` -- The amount to be transferred from the treasury to the `beneficiary`. +* `beneficiary: AccountIdLookupOf` -- The destination account for the transfer. + +**Errors:** + +* `InsufficientPermission` -- if the amount to be spent is greater than what the dispatcher of this call is allowed to spend. +* `TooManyApprovals` -- when `MaxApprovals` limit is hit, and cannot add a new proposal to the storage. + +**Events:** + +* `SpendApproved(proposal_index, amount, beneficiary)` + + +[.contract-item] +[[spend]] +==== `[.contract-item-name]#++spend++#` +[source,rust] +---- +pub fn spend( + origin: OriginFor, + asset_kind: Box, + amount: AssetBalanceOf, + beneficiary: Box<<>::BeneficiaryLookup as StaticLookup>::Source>, + valid_from: Option> +) -> DispatchResult +---- + +Propose and approve a spend of treasury funds, allows spending any asset kind managed by the treasury. + +NOTE: The behavior and the API of the previous version of this function is kept the same and renamed to `spend_local`. The new feature `valid_from` is not added to `spend_local` for backward compatibility. + +**Params:** + +* `origin: OriginFor` -- Must be [`Config::SpendOrigin`] with the `Success` value being at least `amount`. +* `asset_kind: Box` -- An indicator of the specific asset class to be spent. +* `value: BalanceOf` -- The amount to be transferred from the treasury to the `beneficiary`. +* `beneficiary: AccountIdLookupOf` -- The destination account for the transfer. +* `valid_from: Option>` -- The block number from which the spend can be claimed. It can refer to the past if the resulting spend has not yet expired according to the [`Config::PayoutPeriod`]. If `None`, the spend can be claimed immediately after approval. + +**Errors:** + +* `InsufficientPermission` -- if the amount to be spent is greater than what the dispatcher of this call is allowed to spend. +* `SpendExpired` -- if expiration date is older than now. +* `FailedToConvertBalance` -- when conversion between `asset_kind` and `native currency` fails. + +**Events:** + +* `AssetSpendApproved(index, asset_kind, amount, beneficiary, valid_from, expire_at)` -- `index` is the index of the proposal. Rest is self-explanatory. + + +[.contract-item] +[[remove_approval]] +==== `[.contract-item-name]#++remove_approval++#` +[source,rust] +---- +pub fn remove_approval( + origin: OriginFor, + proposal_id: ProposalIndex +) -> DispatchResult +---- + +Force a previously approved proposal to be removed from the approval queue. + +**Params:** + +* `origin: OriginFor` -- Must be [Config::RejectOrigin]. +* `proposal_id: ProposalIndex` -- The index of a proposal. + +**Errors:** + +* `ProposalNotApproved` -- The proposal does not exist in the approved proposals queue. + +**Events:** + +* `AssetSpendApproved(index, asset_kind, amount, beneficiary, valid_from, expire_at)` -- `index` is the index of the proposal. Rest is self-explanatory. + + +[.contract-item] +[[payout]] +==== `[.contract-item-name]#++payout++#` +[source,rust] +---- +pub fn payout(origin: OriginFor, index: SpendIndex) -> DispatchResult +---- + +Claims a spend. + +Spends must be claimed within some temporal bounds. A spend may be claimed within one [`Config::PayoutPeriod`] from the `valid_from` block. +In case of a payout failure, the spend status must be updated with the `check_status` dispatchable before retrying with the current function. + +**Params:** + +* `origin: OriginFor` -- Must be signed. +* `index: SpendIndex` -- The index of the spend. + +**Errors:** + +* `InvalidIndex` -- The spend could not be found. +* `EarlyPayout` -- The spend tried to be claimed before it became valid (see `valid_from` field). +* `SpendExpired` -- The spend tried to be claimed after it expired. +* `AlreadyAttempted` -- The same spend tried to be claimed before. +* `PayoutError` -- An error occurred during the payment, related to `Paymaster::pay` function. + +**Events:** + +* `Paid(index, payment_id)` + + +[.contract-item] +[[check_status]] +==== `[.contract-item-name]#++check_status++#` +[source,rust] +---- +pub fn check_status( + origin: OriginFor, + index: SpendIndex +) -> DispatchResultWithPostInfo +---- + +Check the status of the spend and remove it from the storage if processed. + +**Params:** + +* `origin: OriginFor` -- Must be signed. +* `index: SpendIndex` -- The index of the spend. + +**Errors:** + +* `InvalidIndex` -- The spend could not be found. +* `NotAttempted` -- The payout was not attempted. +* `Inconclusive` -- The spend is still in progress. + +**Events:** + +* `SpendProcessed(index)` -- Spend is successfully processed. +* `PaymentFailed(index, payment_id)` -- The payout was failed, and can be retried again. This error also gives the `payment_id` info for further investigation. + + +[.contract-item] +[[void_spend]] +==== `[.contract-item-name]#++void_spend++#` +[source,rust] +---- +pub fn void_spend(origin: OriginFor, index: SpendIndex) -> DispatchResult +---- + +Void previously approved spend. + +A spend void is only possible if the payout has not been attempted yet. + +IMPORTANT: even if the payout is failed, it still counts towards an attempt, and cannot be voided at this point. + +**Params:** + +* `origin: OriginFor` -- Must be [Config::RejectOrigin]. +* `index: SpendIndex` -- The index of the spend. + +**Errors:** + +* `InvalidIndex` -- The spend could not be found. +* `AlreadyAttempted` -- The same spend tried to be claimed before. + +**Events:** + +* `AssetSpendVoided(index)` + + +== Important Mentions and FAQ's + +You might have come across the below from official documentation or source-code: + +* `propose_spend` will be removed in February 2024. Use spend instead. +* `reject_proposal` will be removed in February 2024. Use spend instead. +* `approve_proposal` will be removed in February 2024. Use spend instead. + +The new `spend` dispatchable will not be able to solely `propose` or `approve` proposals separately, nor `reject` them. + +After the deprecation update, `treasury` pallet no longer tracks `unapproved` proposals, but only approved ones. + +The idea is to use the `treausry` pallet combined with some other pallet which will provide the functionality of tracking unapproved proposals (reject, approve, propose). For Polkadot it's OpenGov (referenda and conviction voting pallets). + diff --git a/docs/modules/ROOT/pages/runtimes/generic.adoc b/docs/modules/ROOT/pages/runtimes/generic.adoc index 2cec440..d150c8e 100644 --- a/docs/modules/ROOT/pages/runtimes/generic.adoc +++ b/docs/modules/ROOT/pages/runtimes/generic.adoc @@ -80,6 +80,7 @@ To demystify the hard concepts, we provided a documentation, in which you can fi ==== * https://docs.rs/pallet-sudo/latest/pallet_sudo/#[pallet_sudo] provides a way to execute privileged runtime calls using a specified sudo (“superuser do”) account. +* https://docs.rs/pallet-treasury/latest/pallet_treasury/#[pallet_treasury] provides a “pot” of funds that can be managed by stakeholders in the system and a structure for making spending proposals from this pot. ====