Struct polymesh_api::polymesh::api::capital_distribution::CallApi

pub struct CallApi<'api> { /* private fields */ }

Implementations

impl<'api> CallApi<'api>

pub fn distribute(
    &self,
    ca_id: CAId,
    portfolio: Option<PortfolioNumber>,
    currency: Ticker,
    per_share: u128,
    amount: u128,
    payment_at: u64,
    expires_at: Option<u64>
) -> Result<WrappedCall<'api>>

Start and attach a capital distribution, to the CA identified by ca_id, with amount funds in currency withdrawn from portfolio belonging to origin’s DID.

The distribution will commence at payment_at and expire at expires_at, if provided, or if None, then there’s no expiry.

The funds will be locked in portfolio from when distribute is called. When there’s no expiry, some funds may be locked indefinitely in portfolio, due to claimants not withdrawing or no benefits being pushed to them. For indivisible currencies, unlocked amounts, of less than one whole unit, will not be transferable from portfolio. However, if we imagine that users Alice and Bob both are entitled to 1.5 units, and only receive 1 units each, then 0.5 + 0.5 = 1 units are left in portfolio, which is now transferrable.

Arguments

• origin is a signer that has permissions to act as an agent of ca_id.ticker.
• ca_id identifies the CA to start a capital distribution for.
• portfolio specifies the portfolio number of the agent to distribute amount from.
• currency to withdraw and distribute from the portfolio.
• per_share amount of currency to withdraw and distribute. Specified as a per-million, i.e. 1 / 10^6th of one currency token.
• amount of currency to withdraw and distribute at most.
• payment_at specifies when benefits may first be pushed or claimed.
• expires_at specifies, if provided, when remaining benefits are forfeit and may be reclaimed by origin.

Errors

• UnauthorizedAgent if origin is not agent-permissioned for ticker.
• ExpiryBeforePayment if expires_at.unwrap() <= payment_at.
• NoSuchCA if ca_id does not identify an existing CA.
• NoRecordDate if CA has no record date.
• RecordDateAfterStart if CA’s record date > payment_at.
• UnauthorizedCustodian if the caller is not the custodian of portfolio.
• InsufficientPortfolioBalance if portfolio has less than amount of currency.
• InsufficientBalance if the protocol fee couldn’t be charged.
• CANotBenefit if the CA is not of kind PredictableBenefit/UnpredictableBenefit
• DistributionAmountIsZero if the amount is zero.
• DistributionPerShareIsZero if the per_share is zero.

Permissions

• Asset
• Portfolio

pub fn claim(&self, ca_id: CAId) -> Result<WrappedCall<'api>>

Claim a benefit of the capital distribution attached to ca_id.

Taxes are withheld as specified by the CA. Post-tax earnings are then transferred to the default portfolio of the origin’s DID.

All benefits are rounded by truncation, down to first integer below. Moreover, before post-tax earnings, in indivisible currencies are transferred, they are rounded down to a whole unit.

Arguments

• origin which must be a holder of the asset and eligible for the distribution.
• ca_id identifies the CA to start a capital distribution for.

Errors

• HolderAlreadyPaid if origin’s DID has already received its benefit.
• NoSuchDistribution if there’s no capital distribution for ca_id.
• CannotClaimBeforeStart if now < payment_at.
• CannotClaimAfterExpiry if now > expiry_at.unwrap().
• NoSuchCA if ca_id does not identify an existing CA.
• NotTargetedByCA if the CA does not target origin’s DID.
• BalanceAmountProductOverflowed if ba = balance * amount would overflow.
• BalanceAmountProductSupplyDivisionFailed if ba * supply would overflow.
• Other errors can occur if the compliance manager rejects the transfer.

pub fn push_benefit(
    &self,
    ca_id: CAId,
    holder: IdentityId
) -> Result<WrappedCall<'api>>

Push benefit of an ongoing distribution to the given holder.

Taxes are withheld as specified by the CA. Post-tax earnings are then transferred to the default portfolio of the origin’s DID.

All benefits are rounded by truncation, down to first integer below. Moreover, before post-tax earnings, in indivisible currencies are transferred, they are rounded down to a whole unit.

Arguments

• origin is a signer that has permissions to act as an agent of ca_id.ticker.
• ca_id identifies the CA with a capital distributions to push benefits for.
• holder to push benefits to.

Errors

• UnauthorizedAgent if origin is not agent-permissioned for ticker.
• NoSuchDistribution if there’s no capital distribution for ca_id.
• CannotClaimBeforeStart if now < payment_at.
• CannotClaimAfterExpiry if now > expiry_at.unwrap().
• NoSuchCA if ca_id does not identify an existing CA.
• NotTargetedByCA if the CA does not target holder.
• BalanceAmountProductOverflowed if ba = balance * amount would overflow.
• BalanceAmountProductSupplyDivisionFailed if ba * supply would overflow.
• Other errors can occur if the compliance manager rejects the transfer.

pub fn reclaim(&self, ca_id: CAId) -> Result<WrappedCall<'api>>

Assuming a distribution has expired, unlock the remaining amount in the distributor portfolio.

Arguments

• origin which must be the creator of the capital distribution tied to ca_id.
• ca_id identifies the CA with a capital distribution to reclaim for.

Errors

• NoSuchDistribution if there’s no capital distribution for ca_id.
• AlreadyReclaimed if this function has already been called successfully.
• NotExpired if now < expiry.

pub fn remove_distribution(&self, ca_id: CAId) -> Result<WrappedCall<'api>>

Removes a distribution that hasn’t started yet, unlocking the full amount in the distributor portfolio.

Arguments

• origin is a signer that has permissions to act as an agent of ca_id.ticker.
• ca_id identifies the CA with a not-yet-started capital distribution to remove.

Errors

• UnauthorizedAgent if origin is not agent-permissioned for ticker.
• NoSuchDistribution if there’s no capital distribution for ca_id.
• DistributionStarted if payment_at <= now.

Trait Implementations

impl<'api> Clone for CallApi<'api>

fn clone(&self) -> CallApi<'api>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'api> From<&'api Api> for CallApi<'api>

fn from(api: &'api Api) -> Self

Converts to this type from the input type.