pezkuwi-runtime-templates/docs/modules/ROOT/pages/pezpallets/treasury.adoc

:source-highlighter: highlight.js
:highlightjs-languages: rust
:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>]

= pezpallet_treasury

Branch/Release: `release-pezkuwi-v1.10.0`

== Source Code link:https://github.com/pezkuwichain/pezkuwi-sdk/blob/release-pezkuwi-v1.10.0/bizinikiwi/pezframe/treasury/src/lib.rs[{github-icon},role=heading-link]

== Purpose

The Treasury pezpallet 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

* Pezpezpallet-specific configs
** `SpendPeriod` -- Period between successive spends. "Spend" means, treasury spending money to a proposal. `SpendPeriod` determines how often the treasury pezpallet 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 pezpallet 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 Pezpezpallet 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.

* Pezpezpallet-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.
** `PezpezpalletId` -- The treasury's pezpallet id, used for deriving its sovereign account ID.
** `WeightInfo` -- Weight information for extrinsics in this pezpallet.
** `BenchmarkHelper` --  Helper type for benchmarks.

== Dispatchables

[.contract-item]
[[spend_local]]
==== `[.contract-item-name]#++spend_local++#`
[source,rust]
----
pub fn spend_local(
    origin: OriginFor<T>,
    #[pezpallet::compact] amount: BalanceOf<T, I>,
    beneficiary: AccountIdLookupOf<T>,
) -> 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 HEZ 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<T>` -- Must be [`Config::SpendOrigin`] with the `Success` value being at least `amount`.
* `value: BalanceOf<T, I>` -- The amount to be transferred from the treasury to the `beneficiary`.
* `beneficiary: AccountIdLookupOf<T>` --  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<T>,
    asset_kind: Box<T::AssetKind>,
    amount: AssetBalanceOf<T, I>,
    beneficiary: Box<<<T as Config<I>>::BeneficiaryLookup as StaticLookup>::Source>,
    valid_from: Option<BlockNumberFor<T>>
) -> 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<T>` -- Must be [`Config::SpendOrigin`] with the `Success` value being at least `amount`.
* `asset_kind: Box<T::AssetKind>` -- An indicator of the specific asset class to be spent.
* `value: BalanceOf<T, I>` -- The amount to be transferred from the treasury to the `beneficiary`.
* `beneficiary: AccountIdLookupOf<T>` --  The destination account for the transfer.
* `valid_from: Option<BlockNumberFor<T>>` -- 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<T>,
    proposal_id: ProposalIndex
) -> DispatchResult
----

Force a previously approved proposal to be removed from the approval queue.

**Params:**

* `origin: OriginFor<T>` -- 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<T>, 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<T>` -- 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<T>,
    index: SpendIndex
) -> DispatchResultWithPostInfo
----

Check the status of the spend and remove it from the storage if processed.

**Params:**

* `origin: OriginFor<T>` -- 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<T>, 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<T>` -- 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` pezpallet no longer tracks `unapproved` proposals, but only approved ones.

The idea is to use the `treausry` pezpallet combined with some other pezpallet which will provide the functionality of tracking unapproved proposals (reject, approve, propose). For Pezkuwi it's OpenGov (referenda and conviction voting pezpallets).