runtime-calls.md

Runtime calls

Calls are categorized according to the dispatch origin they require:

1. User calls: the dispatch origin for this kind of call must be signed by the transactor. This is the only call category that can be submitted with an extrinsic.
2. Root calls: This kind of call requires a special origin that can only be invoked through on-chain governance mechanisms.
3. Inherent calls: This kind of call is invoked by the author of the block itself (usually automatically by the node).
4. Disabled calls: These calls can not be called directly, they are reserved for internal use by other runtime calls.

User calls

There are 86 user calls from 21 pallets.

Account - 1

unlink_identity - 0

unlink_identity()

Taking 0.0107 % of a block.

unlink the identity associated with the account

Scheduler - 2

schedule - 0

schedule(when, maybe_periodic, priority, call)

Taking 0.0117 % of a block.

when: BlockNumberFor<T>
maybe_periodic: Option<schedule::Period<BlockNumberFor<T>>>
priority: schedule::Priority
call: Box<<T as Config>::RuntimeCall>

Anonymously schedule a task.

cancel - 1

cancel(when, index)

Taking 0.0239 % of a block.

when: BlockNumberFor<T>
index: u32

Cancel an anonymously scheduled task.

schedule_named - 2

schedule_named(id, when, maybe_periodic, priority, call)

Taking 0.0189 % of a block.

id: TaskName
when: BlockNumberFor<T>
maybe_periodic: Option<schedule::Period<BlockNumberFor<T>>>
priority: schedule::Priority
call: Box<<T as Config>::RuntimeCall>

Schedule a named task.

cancel_named - 3

cancel_named(id)

Taking 0.0252 % of a block.

id: TaskName

Cancel a named scheduled task.

schedule_after - 4

schedule_after(after, maybe_periodic, priority, call)

No weight available.

after: BlockNumberFor<T>
maybe_periodic: Option<schedule::Period<BlockNumberFor<T>>>
priority: schedule::Priority
call: Box<<T as Config>::RuntimeCall>

Anonymously schedule a task after a delay.

schedule_named_after - 5

schedule_named_after(id, after, maybe_periodic, priority, call)

No weight available.

id: TaskName
after: BlockNumberFor<T>
maybe_periodic: Option<schedule::Period<BlockNumberFor<T>>>
priority: schedule::Priority
call: Box<<T as Config>::RuntimeCall>

Schedule a named task after a delay.

set_retry - 6

set_retry(task, retries, period)

Taking 0.0115 % of a block.

task: TaskAddress<BlockNumberFor<T>>
retries: u8
period: BlockNumberFor<T>

Set a retry configuration for a task so that, in case its scheduled run fails, it will be retried after period blocks, for a total amount of retries retries or until it succeeds.

Tasks which need to be scheduled for a retry are still subject to weight metering and agenda space, same as a regular task. If a periodic task fails, it will be scheduled normally while the task is retrying.

Tasks scheduled as a result of a retry for a periodic task are unnamed, non-periodic clones of the original task. Their retry configuration will be derived from the original task's configuration, but will have a lower value for remaining than the original total_retries.

set_retry_named - 7

set_retry_named(id, retries, period)

Taking 0.0129 % of a block.

id: TaskName
retries: u8
period: BlockNumberFor<T>

Set a retry configuration for a named task so that, in case its scheduled run fails, it will be retried after period blocks, for a total amount of retries retries or until it succeeds.

Tasks which need to be scheduled for a retry are still subject to weight metering and agenda space, same as a regular task. If a periodic task fails, it will be scheduled normally while the task is retrying.

Tasks scheduled as a result of a retry for a periodic task are unnamed, non-periodic clones of the original task. Their retry configuration will be derived from the original task's configuration, but will have a lower value for remaining than the original total_retries.

cancel_retry - 8

cancel_retry(task)

Taking 0.0115 % of a block.

task: TaskAddress<BlockNumberFor<T>>

Removes the retry configuration of a task.

cancel_retry_named - 9

cancel_retry_named(id)

Taking 0.0128 % of a block.

id: TaskName

Cancel the retry configuration of a named task.

Babe - 3

report_equivocation - 0

report_equivocation(equivocation_proof, key_owner_proof)

No weight available.

equivocation_proof: Box<EquivocationProof<HeaderFor<T>>>
key_owner_proof: T::KeyOwnerProof

Report authority equivocation/misbehavior. This method will verify the equivocation proof and validate the given key ownership proof against the extracted offender. If both are valid, the offence will be reported.

Balances - 6

transfer_allow_death - 0

transfer_allow_death(dest, value)

Taking 0.0196 % of a block.

dest: AccountIdLookupOf<T>
value: T::Balance

Transfer some liquid free balance to another account.

transfer_allow_death will set the FreeBalance of the sender and receiver. If the sender's account is below the existential deposit as a result of the transfer, the account will be reaped.

The dispatch origin for this call must be Signed by the transactor.

transfer_keep_alive - 3

transfer_keep_alive(dest, value)

Taking 0.012 % of a block.

dest: AccountIdLookupOf<T>
value: T::Balance

Same as the transfer_allow_death call, but with a check that the transfer will not kill the origin account.

99% of the time you want transfer_allow_death instead.

transfer_all - 4

transfer_all(dest, keep_alive)

Taking 0.0123 % of a block.

dest: AccountIdLookupOf<T>
keep_alive: bool

Transfer the entire transferable balance from the caller account.

NOTE: This function only attempts to transfer transferable balances. This means that any locked, reserved, or existential deposits (when keep_alive is true), will not be transferred by this function. To ensure that this function results in a killed account, you might need to prepare the account by removing any reference counters, storage deposits, etc...

The dispatch origin of this call must be Signed.

• dest: The recipient of the transfer.
• keep_alive: A boolean to determine if the transfer_all operation should send all of the funds the account has, causing the sender account to be killed (false), or transfer everything except at least the existential deposit, which will guarantee to keep the sender account alive (true).

force_set_balance - 8

force_set_balance(who, new_free)

No weight available.

who: AccountIdLookupOf<T>
new_free: T::Balance

Upgrade a specified account.

• origin: Must be Signed.
• who: The account to be upgraded.

This will waive the transaction fee if at least all but 10% of the accounts needed to be upgraded. (We let some not have to be upgraded just in order to allow for the possibililty of churn). Set the regular balance of a given account.

The dispatch origin for this call is root.

force_adjust_total_issuance - 9

force_adjust_total_issuance(direction, delta)

Taking 0.0039 % of a block.

direction: AdjustmentDirection
delta: T::Balance

Adjust the total issuance in a saturating way.

Can only be called by root and always needs a positive delta.

Example

OneshotAccount - 7

create_oneshot_account - 0

create_oneshot_account(dest, value)

Taking 0.0113 % of a block.

dest: <T::Lookup as StaticLookup>::Source
value: <T::Currency as Currency<T::AccountId>>::Balance

Create an account that can only be consumed once

• dest: The oneshot account to be created.
• balance: The balance to be transfered to this oneshot account.

Origin account is kept alive.

consume_oneshot_account - 1

consume_oneshot_account(block_height, dest)

Taking 0.0196 % of a block.

block_height: BlockNumberFor<T>
dest: Account<<T::Lookup as StaticLookup>::Source>

Consume a oneshot account and transfer its balance to an account

• block_height: Must be a recent block number. The limit is BlockHashCount in the past. (this is to prevent replay attacks)
• dest: The destination account.
• dest_is_oneshot: If set to true, then a oneshot account is created at dest. Else, dest has to be an existing account.

consume_oneshot_account_with_remaining - 2

consume_oneshot_account_with_remaining(block_height, dest, remaining_to, balance)

Taking 0.0269 % of a block.

block_height: BlockNumberFor<T>
dest: Account<<T::Lookup as StaticLookup>::Source>
remaining_to: Account<<T::Lookup as StaticLookup>::Source>
balance: <T::Currency as Currency<T::AccountId>>::Balance

Consume a oneshot account then transfer some amount to an account, and the remaining amount to another account.

• block_height: Must be a recent block number. The limit is BlockHashCount in the past. (this is to prevent replay attacks)
• dest: The destination account.
• dest_is_oneshot: If set to true, then a oneshot account is created at dest. Else, dest has to be an existing account.
• dest2: The second destination account.
• dest2_is_oneshot: If set to true, then a oneshot account is created at dest2. Else, dest2 has to be an existing account.
• balance1: The amount transfered to dest, the leftover being transfered to dest2.

SmithMembers - 10

invite_smith - 0

invite_smith(receiver)

Taking 0.0239 % of a block.

receiver: T::IdtyIndex

Invite a WoT member to try becoming a Smith

accept_invitation - 1

accept_invitation()

Taking 0.0122 % of a block.

Accept an invitation (must have been invited first)

certify_smith - 2

certify_smith(receiver)

Taking 0.0287 % of a block.

receiver: T::IdtyIndex

Certify an invited smith which can lead the certified to become a Smith

AuthorityMembers - 11

go_offline - 0

go_offline()

Taking 0.0167 % of a block.

ask to leave the set of validators two sessions after

go_online - 1

go_online()

Taking 0.0192 % of a block.

ask to join the set of validators two sessions after

set_session_keys - 2

set_session_keys(keys)

Taking 0.0254 % of a block.

keys: T::Keys

declare new session keys to replace current ones

remove_member_from_blacklist - 4

remove_member_from_blacklist(member_id)

Taking 0.0109 % of a block.

member_id: T::MemberId

remove an identity from the blacklist

Grandpa - 16

report_equivocation - 0

report_equivocation(equivocation_proof, key_owner_proof)

No weight available.

equivocation_proof: Box<EquivocationProof<T::Hash, BlockNumberFor<T>>>
key_owner_proof: T::KeyOwnerProof

Report voter equivocation/misbehavior. This method will verify the equivocation proof and validate the given key ownership proof against the extracted offender. If both are valid, the offence will be reported.

UpgradeOrigin - 21

dispatch_as_root_unchecked_weight - 1

dispatch_as_root_unchecked_weight(call, weight)

No weight available.

call: Box<<T as Config>::Call>
weight: Weight

Dispatches a function call from root origin. This function does not check the weight of the call, and instead allows the caller to specify the weight of the call.

The weight of this call is defined by the caller.

Preimage - 22

note_preimage - 0

note_preimage(bytes)

Taking 0.2893 % of a block.

bytes: Vec<u8>

Register a preimage on-chain.

If the preimage was previously requested, no fees or deposits are taken for providing the preimage. Otherwise, a deposit is taken proportional to the size of the preimage.

unnote_preimage - 1

unnote_preimage(hash)

Taking 0.0186 % of a block.

hash: T::Hash

Clear an unrequested preimage from the runtime storage.

If len is provided, then it will be a much cheaper operation.

• hash: The hash of the preimage to be removed from the store.
• len: The length of the preimage of hash.

request_preimage - 2

request_preimage(hash)

Taking 0.0127 % of a block.

hash: T::Hash

Request a preimage be uploaded to the chain without paying any fees or deposits.

If the preimage requests has already been provided on-chain, we unreserve any deposit a user may have paid, and take the control of the preimage out of their hands.

unrequest_preimage - 3

unrequest_preimage(hash)

Taking 0.0185 % of a block.

hash: T::Hash

Clear a previously made request for a preimage.

NOTE: THIS MUST NOT BE CALLED ON hash MORE TIMES THAN request_preimage.

ensure_updated - 4

ensure_updated(hashes)

Taking 20.7987 % of a block.

hashes: Vec<T::Hash>

Ensure that the a bulk of pre-images is upgraded.

The caller pays no fee if at least 90% of pre-images were successfully updated.

TechnicalCommittee - 23

execute - 1

execute(proposal, length_bound)

Taking 0.0052 % of a block.

proposal: Box<<T as Config<I>>::Proposal>
length_bound: u32

Dispatch a proposal from a member using the Member origin.

Origin must be a member of the collective.

Complexity:

• O(B + M + P) where:
• B is proposal size in bytes (length-fee-bounded)
• M members-count (code-bounded)
• P complexity of dispatching proposal

propose - 2

propose(threshold, proposal, length_bound)

No weight available.

threshold: MemberCount
proposal: Box<<T as Config<I>>::Proposal>
length_bound: u32

Add a new proposal to either be voted on or executed directly.

Requires the sender to be member.

threshold determines whether proposal is executed directly (threshold < 2) or put up for voting.

Complexity

• O(B + M + P1) or O(B + M + P2) where:
  • B is proposal size in bytes (length-fee-bounded)
  • M is members-count (code- and governance-bounded)
  • branching is influenced by threshold where:
    • P1 is proposal execution complexity (threshold < 2)
    • P2 is proposals-count (code-bounded) (threshold >= 2)

vote - 3

vote(proposal, index, approve)

Taking 0.0125 % of a block.

proposal: T::Hash
index: ProposalIndex
approve: bool

Add an aye or nay vote for the sender to the given proposal.

Requires the sender to be a member.

Transaction fees will be waived if the member is voting on any particular proposal for the first time and the call is successful. Subsequent vote changes will charge a fee. Complexity

• O(M) where M is members-count (code- and governance-bounded)

close - 6

close(proposal_hash, index, proposal_weight_bound, length_bound)

No weight available.

proposal_hash: T::Hash
index: ProposalIndex
proposal_weight_bound: Weight
length_bound: u32

Close a vote that is either approved, disapproved or whose voting period has ended.

May be called by any signed account in order to finish voting and close the proposal.

If called before the end of the voting period it will only close the vote if it is has enough votes to be approved or disapproved.

If called after the end of the voting period abstentions are counted as rejections unless there is a prime member set and the prime member cast an approval.

If the close operation completes successfully with disapproval, the transaction fee will be waived. Otherwise execution of the approved operation will be charged to the caller.

• proposal_weight_bound: The maximum amount of weight consumed by executing the closed proposal.
• length_bound: The upper bound for the length of the proposal in storage. Checked via storage::read so it is size_of::<u32>() == 4 larger than the pure length.

Complexity

• O(B + M + P1 + P2) where:
  • B is proposal size in bytes (length-fee-bounded)
  • M is members-count (code- and governance-bounded)
  • P1 is the complexity of proposal preimage.
  • P2 is proposal-count (code-bounded)

UniversalDividend - 30

claim_uds - 0

claim_uds()

Taking 0.022 % of a block.

Claim Universal Dividends

transfer_ud - 1

transfer_ud(dest, value)

Taking 0.0208 % of a block.

dest: <T::Lookup as StaticLookup>::Source
value: BalanceOf<T>

Transfer some liquid free balance to another account, in milliUD.

transfer_ud_keep_alive - 2

transfer_ud_keep_alive(dest, value)

Taking 0.0131 % of a block.

dest: <T::Lookup as StaticLookup>::Source
value: BalanceOf<T>

Transfer some liquid free balance to another account, in milliUD.

Identity - 41

create_identity - 0

create_identity(owner_key)

Taking 0.0906 % of a block.

owner_key: T::AccountId

Create an identity for an existing account

• owner_key: the public key corresponding to the identity to be created

The origin must be allowed to create an identity.

confirm_identity - 1

confirm_identity(idty_name)

Taking 0.0337 % of a block.

idty_name: IdtyName

Confirm the creation of an identity and give it a name

• idty_name: the name uniquely associated to this identity. Must match the validation rules defined by the runtime.

The identity must have been created using create_identity before it can be confirmed.

change_owner_key - 3

change_owner_key(new_key, new_key_sig)

Taking 0.0429 % of a block.

new_key: T::AccountId
new_key_sig: T::Signature

Change identity owner key.

• new_key: the new owner key.
• new_key_sig: the signature of the encoded form of IdtyIndexAccountIdPayload. Must be signed by new_key.

The origin should be the old identity owner key.

revoke_identity - 4