Trait FundRoles

pub trait FundRoles<Candidate>: RoleManager<Candidate> {
    type Backer: Delimited;

    // Required methods
    fn has_funds(who: &Candidate) -> DispatchResult;
    fn can_fund(
        by: &Self::Backer,
        to: &Candidate,
        value: Self::Asset,
        precision: Precision,
        force: Fortitude,
    ) -> DispatchResult;
    fn can_draw(by: &Self::Backer, from: &Candidate) -> DispatchResult;
    fn max_exposure(
        from: &Self::Backer,
        towards: &Candidate,
        precision: Precision,
        force: Fortitude,
    ) -> Result<Self::Asset, DispatchError>;
    fn min_fund(
        from: &Self::Backer,
        towards: &Candidate,
        precision: Precision,
        force: Fortitude,
    ) -> Result<Self::Asset, DispatchError>;
    fn backed_value(who: &Candidate) -> Result<Self::Asset, DispatchError>;
    fn backers_of(
        who: &Candidate,
    ) -> Result<Vec<(Self::Backer, Self::Asset)>, DispatchError>;
    fn backed_for(
        by: &Self::Backer,
    ) -> Result<Vec<(Candidate, Self::Asset)>, DispatchError>;
    fn total_backing() -> Self::Asset;
    fn get_fund(
        who: &Candidate,
        by: &Self::Backer,
    ) -> Result<Self::Asset, DispatchError>;
    fn fund(
        to: &Candidate,
        by: &Self::Backer,
        value: Self::Asset,
        precision: Precision,
        force: Fortitude,
    ) -> Result<Self::Asset, DispatchError>;
    fn draw(
        from: &Candidate,
        by: &Self::Backer,
    ) -> Result<Self::Asset, DispatchError>;

    // Provided methods
    fn on_funded(_who: &Candidate, _by: &Self::Backer, _value: Self::Asset) { ... }
    fn on_drawn(_who: &Candidate, _by: &Self::Backer, _value: Self::Asset) { ... }
}

Extends RoleManager to introduce funding and backing mechanics for role-based systems.

This trait defines a common interface for roles that require financial support or collateralization from external entities (called backers). It models relationships where one or more backers provide funds to a candidate in exchange for shared exposure, yield, or delegated influence.

Typical applications include:

• Validator nomination systems - nominators/delegators (backers) stake funds behind validators (candidates).
• DAO or governance roles - community members back representatives or proposal leaders.
• DeFi-style credit systems - where backers fund loan candidates, or insurance underwriters provide coverage.
• Service networks - e.g., oracle or relayer pools where reputation and collateral are pooled.

Type Parameters

• Candidate: The entity or account being backed.

Invariants

• Each backer must fund with at least Self::min_fund units of asset.
• When a Candidate is not available (See RoleManager::is_available), backers may withdraw all or some of their stake (context-basis).
• Self::fund and Self::draw operations must maintain consistent accounting symmetry between Self::backers_of and Self::backed_for.

Example Implementations

Example 1: Nominated Validator System

In a nominated staking system:

• Candidates are validators who receive backing from multiple nominators (backers).
• Each backer must meet a minimum funding requirement when supporting a candidate.
• The total funding for a candidate cannot exceed a maximum exposure limit.
• Funding increases the candidate’s active collateral, while drawing allows backers to withdraw.
• This example shows how the trait enforces eligibility, updates backing relationships, and maintains real-time funded values.

Example 2: Governance Role Backing

In a governance system where community members can financially support representatives:

• Candidates are council members or proposal leads.
• Backers provide funds to indicate confidence and to incentivize participation.
• The trait ensures backers cannot overexpose themselves or fund below minimum thresholds.
• Candidates may become defaulted if they violate rules or fail to perform, triggering potential fund loss.
• Rewards, penalties, or collateral adjustments can be layered on top, creating a dynamic funding ecosystem.

These examples illustrate how FundRoles can handle different backing scenarios, from staking and validator support to governance funding, while maintaining real-time tracking of funds and enforcing role-related invariants.

Usage

Implement this trait for any role that allows external capital participation or support. Higher-level logic such as slashing, reward distribution, or governance power weighting can be layered on top by combining CompensateRoles or custom traits.

Required Associated Types

type Backer: Delimited

Type representing the entity providing funding or backing support.

Required Methods

fn has_funds(who: &Candidate) -> DispatchResult

Checks whether the Candidate currently holds any funds or active backing relationships.

Returns Ok(()) if funds exist, otherwise a DispatchError.

fn can_fund( by: &Self::Backer, to: &Candidate, value: Self::Asset, precision: Precision, force: Fortitude, ) -> DispatchResult

Validates whether a Backer can fund a Candidate with the specified amount.

This performs only validation, not mutation.

The precision parameter defines proportional allocation or best behavior. The force parameter defines enforcement principle of this funding operation.

Should verify minimum and maximum exposure constraints possibly via Self::min_fund and Self::max_exposure.

fn can_draw(by: &Self::Backer, from: &Candidate) -> DispatchResult

Validates whether a Backer can draw its funds backed to a Candidate.

This performs only validation, not mutation.

fn max_exposure( from: &Self::Backer, towards: &Candidate, precision: Precision, force: Fortitude, ) -> Result<Self::Asset, DispatchError>

Returns the maximum exposure (total backable amount) allowed for this Candidate.

This acts as an upper cap on all active fundings combined.

The precision and force parameters simulate a funding attempt under the given directive, determining the effective exposure limits.

fn min_fund( from: &Self::Backer, towards: &Candidate, precision: Precision, force: Fortitude, ) -> Result<Self::Asset, DispatchError>

Returns the minimum funding amount required for a Backer to participate.

The precision and force parameters simulate a funding attempt under the given directive, determining the effective minimum requirement.

fn backed_value(who: &Candidate) -> Result<Self::Asset, DispatchError>

Returns the real-time total value of funds currently backing the given Candidate.

This reflects the latest on-chain state, meaning the value may vary over time due to dynamic adjustments such as:

• Collateral revaluation or slashing
• Partial withdrawals or new backings
• Protocol-driven rewards or penalties

Implementations should compute or retrieve this value at the moment of call, ensuring it reflects the candidate’s live backing exposure.

fn backers_of( who: &Candidate, ) -> Result<Vec<(Self::Backer, Self::Asset)>, DispatchError>

Returns all Backers currently funding the specified Candidate, along with each backer’s real-time effective contribution.

Note that returned contribution values are not static - they represent the candidate’s current funding snapshot and may change due to slashing, rebalancing, or collateral mutation.

fn backed_for( by: &Self::Backer, ) -> Result<Vec<(Candidate, Self::Asset)>, DispatchError>

Returns all Candidates that the given Backer is funding, along with each real-time funded amount.

The returned data represents the backer’s current live exposure, not a historical record. Implementations should resolve these dynamically from the latest runtime state.

fn total_backing() -> Self::Asset

Retrieves the real-time amount of funds currently funded for all the Candidates.

fn get_fund( who: &Candidate, by: &Self::Backer, ) -> Result<Self::Asset, DispatchError>

Retrieves the current effective funded amount that by has provided to who.

This is a real-time query that reflects the live value of the fund relationship, factoring in any protocol-driven adjustments (e.g., penalties, rewards, partial draws, or slashes).

fn fund( to: &Candidate, by: &Self::Backer, value: Self::Asset, precision: Precision, force: Fortitude, ) -> Result<Self::Asset, DispatchError>

Performs the funding operation, locking the given value of asset from the Backer in support of the Candidate.

The precision parameter defines proportional allocation or best behavior. The force parameter defines enforcement principle of this funding operation.

Returns the actual funded amount.

fn draw( from: &Candidate, by: &Self::Backer, ) -> Result<Self::Asset, DispatchError>

Allows the Backer to draw back (withdraw) their previously funded assets from a Candidate.

Returns the amount successfully withdrawn.

Provided Methods

fn on_funded(_who: &Candidate, _by: &Self::Backer, _value: Self::Asset)

Hook triggered when a funding action is completed.

Can be used to emit events, update metrics, or notify off-chain logic.

Default is no-op.

fn on_drawn(_who: &Candidate, _by: &Self::Backer, _value: Self::Asset)

Hook triggered when funds are drawn or withdrawn.

Use this for cleanup or balance reallocation tasks.

Default is no-op.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors