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.
1. **Root calls**: This kind of call requires a special origin that can only be invoked
through on-chain governance mechanisms.
1. **Inherent calls**: This kind of call is invoked by the author of the block itself
(usually automatically by the node).
1. **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

<details><summary><code>unlink_identity()</code></summary>

Taking 0.0111 % of a block.

```rust
```
</details>


Unlink the identity associated with the account.

### Scheduler - 2

#### schedule - 0

<details><summary><code>schedule(when, maybe_periodic, priority, call)</code></summary>

Taking 0.0122 % of a block.

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


Anonymously schedule a task.

#### cancel - 1

<details><summary><code>cancel(when, index)</code></summary>

Taking 0.0236 % of a block.

```rust
when: BlockNumberFor<T>
index: u32
```
</details>


Cancel an anonymously scheduled task.

#### schedule_named - 2

<details><summary><code>schedule_named(id, when, maybe_periodic, priority, call)</code></summary>

Taking 0.0189 % of a block.

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


Schedule a named task.

#### cancel_named - 3

<details><summary><code>cancel_named(id)</code></summary>

Taking 0.0248 % of a block.

```rust
id: TaskName
```
</details>


Cancel a named scheduled task.

#### schedule_after - 4

<details><summary><code>schedule_after(after, maybe_periodic, priority, call)</code></summary>

No weight available.

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


Anonymously schedule a task after a delay.

#### schedule_named_after - 5

<details><summary><code>schedule_named_after(id, after, maybe_periodic, priority, call)</code></summary>

No weight available.

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


Schedule a named task after a delay.

#### set_retry - 6

<details><summary><code>set_retry(task, retries, period)</code></summary>

Taking 0.012 % of a block.

```rust
task: TaskAddress<BlockNumberFor<T>>
retries: u8
period: BlockNumberFor<T>
```
</details>


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

<details><summary><code>set_retry_named(id, retries, period)</code></summary>

Taking 0.0132 % of a block.

```rust
id: TaskName
retries: u8
period: BlockNumberFor<T>
```
</details>


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

<details><summary><code>cancel_retry(task)</code></summary>

Taking 0.012 % of a block.

```rust
task: TaskAddress<BlockNumberFor<T>>
```
</details>


Removes the retry configuration of a task.

#### cancel_retry_named - 9

<details><summary><code>cancel_retry_named(id)</code></summary>

Taking 0.0132 % of a block.

```rust
id: TaskName
```
</details>


Cancel the retry configuration of a named task.

### Babe - 3

#### report_equivocation - 0

<details><summary><code>report_equivocation(equivocation_proof, key_owner_proof)</code></summary>

No weight available.

```rust
equivocation_proof: Box<EquivocationProof<HeaderFor<T>>>
key_owner_proof: T::KeyOwnerProof
```
</details>


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

<details><summary><code>transfer_allow_death(dest, value)</code></summary>

Taking 0.0199 % of a block.

```rust
dest: AccountIdLookupOf<T>
value: T::Balance
```
</details>


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

<details><summary><code>transfer_keep_alive(dest, value)</code></summary>

Taking 0.0125 % of a block.

```rust
dest: AccountIdLookupOf<T>
value: T::Balance
```
</details>


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_allow_death`]: struct.Pallet.html#method.transfer

#### transfer_all - 4

<details><summary><code>transfer_all(dest, keep_alive)</code></summary>

Taking 0.0129 % of a block.

```rust
dest: AccountIdLookupOf<T>
keep_alive: bool
```
</details>


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

<details><summary><code>force_set_balance(who, new_free)</code></summary>

No weight available.

```rust
who: AccountIdLookupOf<T>
new_free: T::Balance
```
</details>


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
possibility of churn).
Set the regular balance of a given account.

The dispatch origin for this call is `root`.

#### force_adjust_total_issuance - 9

<details><summary><code>force_adjust_total_issuance(direction, delta)</code></summary>

Taking 0.0048 % of a block.

```rust
direction: AdjustmentDirection
delta: T::Balance
```
</details>


Adjust the total issuance in a saturating way.

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

# Example

#### burn - 10

<details><summary><code>burn(value, keep_alive)</code></summary>

No weight available.

```rust
value: T::Balance
keep_alive: bool
```
</details>


Burn the specified liquid free balance from the origin account.

If the origin's account ends up below the existential deposit as a result
of the burn and `keep_alive` is false, the account will be reaped.

Unlike sending funds to a _burn_ address, which merely makes the funds inaccessible,
this `burn` operation will reduce total issuance by the amount _burned_.

### OneshotAccount - 7

#### create_oneshot_account - 0

<details><summary><code>create_oneshot_account(dest, value)</code></summary>

Taking 0.012 % of a block.

```rust
dest: <T::Lookup as StaticLookup>::Source
value: BalanceOf<T>
```
</details>


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

<details><summary><code>consume_oneshot_account(block_height, dest)</code></summary>

Taking 0.0197 % of a block.

```rust
block_height: BlockNumberFor<T>
dest: Account<<T::Lookup as StaticLookup>::Source>
```
</details>


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

<details><summary><code>consume_oneshot_account_with_remaining(block_height, dest, remaining_to, balance)</code></summary>

Taking 0.0268 % of a block.

```rust
block_height: BlockNumberFor<T>
dest: Account<<T::Lookup as StaticLookup>::Source>
remaining_to: Account<<T::Lookup as StaticLookup>::Source>
balance: BalanceOf<T>
```
</details>


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

<details><summary><code>invite_smith(receiver)</code></summary>

Taking 0.0235 % of a block.

```rust
receiver: T::IdtyIndex
```
</details>


Invite a member of the Web of Trust to attempt becoming a Smith.

#### accept_invitation - 1

<details><summary><code>accept_invitation()</code></summary>

Taking 0.0127 % of a block.

```rust
```
</details>


Accept an invitation to become a Smith (must have been invited first).

#### certify_smith - 2

<details><summary><code>certify_smith(receiver)</code></summary>

Taking 0.0279 % of a block.

```rust
receiver: T::IdtyIndex
```
</details>


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

### AuthorityMembers - 11

#### go_offline - 0

<details><summary><code>go_offline()</code></summary>

Taking 0.0167 % of a block.

```rust
```
</details>


Request to leave the set of validators two sessions later.

#### go_online - 1

<details><summary><code>go_online()</code></summary>

Taking 0.0189 % of a block.

```rust
```
</details>


Request to join the set of validators two sessions later.

#### set_session_keys - 2

<details><summary><code>set_session_keys(keys)</code></summary>

Taking 0.0249 % of a block.

```rust
keys: T::Keys
```
</details>


Declare new session keys to replace current ones.

#### remove_member_from_blacklist - 4

<details><summary><code>remove_member_from_blacklist(member_id)</code></summary>

Taking 0.0114 % of a block.

```rust
member_id: T::MemberId
```
</details>


Remove a member from the blacklist.
remove an identity from the blacklist

### Grandpa - 16

#### report_equivocation - 0

<details><summary><code>report_equivocation(equivocation_proof, key_owner_proof)</code></summary>

No weight available.

```rust
equivocation_proof: Box<EquivocationProof<T::Hash, BlockNumberFor<T>>>
key_owner_proof: T::KeyOwnerProof
```
</details>


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

<details><summary><code>dispatch_as_root_unchecked_weight(call, weight)</code></summary>

No weight available.

```rust
call: Box<<T as Config>::Call>
weight: Weight
```
</details>


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

<details><summary><code>note_preimage(bytes)</code></summary>

Taking 0.2947 % of a block.

```rust
bytes: Vec<u8>
```
</details>


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

<details><summary><code>unnote_preimage(hash)</code></summary>

Taking 0.0184 % of a block.

```rust
hash: T::Hash
```
</details>


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

<details><summary><code>request_preimage(hash)</code></summary>

Taking 0.0129 % of a block.

```rust
hash: T::Hash
```
</details>


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

<details><summary><code>unrequest_preimage(hash)</code></summary>

Taking 0.0184 % of a block.

```rust
hash: T::Hash
```
</details>


Clear a previously made request for a preimage.

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

#### ensure_updated - 4

<details><summary><code>ensure_updated(hashes)</code></summary>

Taking 19.3634 % of a block.

```rust
hashes: Vec<T::Hash>
```
</details>


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

<details><summary><code>execute(proposal, length_bound)</code></summary>

Taking 0.0061 % of a block.

```rust
proposal: Box<<T as Config<I>>::Proposal>
length_bound: u32
```
</details>


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

<details><summary><code>propose(threshold, proposal, length_bound)</code></summary>

No weight available.

```rust
threshold: MemberCount
proposal: Box<<T as Config<I>>::Proposal>
length_bound: u32
```
</details>


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

<details><summary><code>vote(proposal, index, approve)</code></summary>

Taking 0.0129 % of a block.

```rust
proposal: T::Hash
index: ProposalIndex
approve: bool
```
</details>


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

<details><summary><code>close(proposal_hash, index, proposal_weight_bound, length_bound)</code></summary>

No weight available.

```rust
proposal_hash: T::Hash
index: ProposalIndex
proposal_weight_bound: Weight
length_bound: u32
```
</details>


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

<details><summary><code>claim_uds()</code></summary>

Taking 0.0218 % of a block.

```rust
```
</details>


Claim Universal Dividends.

#### transfer_ud - 1

<details><summary><code>transfer_ud(dest, value)</code></summary>

Taking 0.021 % of a block.

```rust
dest: <T::Lookup as StaticLookup>::Source
value: BalanceOf<T>
```
</details>


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

#### transfer_ud_keep_alive - 2

<details><summary><code>transfer_ud_keep_alive(dest, value)</code></summary>

Taking 0.0135 % of a block.

```rust
dest: <T::Lookup as StaticLookup>::Source
value: BalanceOf<T>
```
</details>


Transfer some liquid free balance to another account in milliUD and keep the account alive.

### Identity - 41

#### create_identity - 0

<details><summary><code>create_identity(owner_key)</code></summary>

Taking 0.0856 % of a block.

```rust
owner_key: T::AccountId
```
</details>


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

<details><summary><code>confirm_identity(idty_name)</code></summary>

Taking 0.0327 % of a block.

```rust
idty_name: IdtyName
```
</details>


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

<details><summary><code>change_owner_key(new_key, new_key_sig)</code></summary>

Taking 0.0424 % of a block.

```rust
new_key: T::AccountId
new_key_sig: T::Signature
```
</details>


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

<details><summary><code>revoke_identity(idty_index, revocation_key, revocation_sig)</code></summary>

Taking 0.0399 % of a block.

```rust
idty_index: T::IdtyIndex
revocation_key: T::AccountId
revocation_sig: T::Signature
```
</details>


Revoke an identity using a revocation signature

- `idty_index`: the index of the identity to be revoked.
- `revocation_key`: the key used to sign the revocation payload.
- `revocation_sig`: the signature of the encoded form of `RevocationPayload`.
                    Must be signed by `revocation_key`.

Any signed origin can execute this call.

#### fix_sufficients - 7

<details><summary><code>fix_sufficients(owner_key, inc)</code></summary>

Taking 0.0113 % of a block.

```rust
owner_key: T::AccountId
inc: bool
```
</details>


Change sufficient reference count for a given key.

This function allows a privileged root origin to increment or decrement the sufficient
reference count associated with a specified owner key.

- `origin` - The origin of the call. It must be root.
- `owner_key` - The account whose sufficient reference count will be modified.
- `inc` - A boolean indicating whether to increment (`true`) or decrement (`false`) the count.


#### link_account - 8

<details><summary><code>link_account(account_id, payload_sig)</code></summary>

Taking 0.0155 % of a block.

```rust
account_id: T::AccountId
payload_sig: T::Signature
```
</details>


Link an account to an identity.

This function links a specified account to an identity, requiring both the account and the
identity to sign the operation.

- `origin` - The origin of the call, which must have an associated identity index.
- `account_id` - The account ID to link, which must sign the payload.
- `payload_sig` - The signature with the linked identity.

### Certification - 43

#### add_cert - 0

<details><summary><code>add_cert(receiver)</code></summary>

Taking 0.0356 % of a block.

```rust
receiver: T::IdtyIndex
```
</details>


Add a new certification.

#### renew_cert - 3

<details><summary><code>renew_cert(receiver)</code></summary>

Taking 0.0292 % of a block.

```rust
receiver: T::IdtyIndex
```
</details>


Renew an existing certification.

#### del_cert - 1

<details><summary><code>del_cert(issuer, receiver)</code></summary>

Taking 0.0257 % of a block.

```rust
issuer: T::IdtyIndex
receiver: T::IdtyIndex
```
</details>