Skip to main content

Balance Transfers

Balance transfers are used to send a balance from one account to another account. To start transferring a balance, we will begin by using Polkadot-JS UI. This guide assumes that you've already created an account and have some funds that are ready to be transferred.

info

We support only the use of the Polkadot-JS UI together with the browser extension, Ledger and Parity Signer for signing transactions. We do not provide support for third party applications.

Sending Funds using UI, Extension, Parity Signer & Ledger​

See the video tutorial below to learn how to send funds using the supported tools. See the Polkadot Support pages for detailed information about transferring funds using the Polkadot-JS UI.

Balance Transfer Tutorial

Signing Transactions

See the Polkadot Support pages for detailed information about signing transactions using:

Keep-Alive Checks​

info

See this video tutorial and this support page to learn about keep-alive checks and existential deposit.

In Kusama there are two main ways to transfer funds from one account to another:

  • transfer keep-alive (default option) will not allow you to send an amount that would allow the sending account to be removed due to it going below the existential deposit of .
  • transfer will allow you to send KSM regardless of the consequence. If the balance drops below the existential deposit your account will be reaped. It may be that you do not want to keep the account alive (for example, because you are moving all of your funds to a different address). To switch the keep-alive check off visit this support article.
info

Attempting to send less than the existential deposit to an account with 0 KSM will always fail, no matter if the keep-alive check is on or not.

For instance, attempting to transfer 0.0001 KSM to an account you just generated (and thus has no balance) will fail, since 0.0001 KSM is less than the existential deposit of and the account cannot be initialized with such a low balance.

note

Even if the transfer fails due to a keep-alive check, the transaction fee will be deducted from the sending account if you attempt to transfer.

Vested Transfers​

KSM may have a lock placed on them to account for vesting funds. Like other types of locks, these funds cannot be transferred but can be used in other parts of the protocol such as voting in governance or being staked as a validator or nominator.

Vesting funds are on a release schedule and unlock a constant number of tokens at each block (linear vesting) or can unlock the full amount after a specific block number (cliff vesting). Although the tokens are released in this manner, it does not get reflected on-chain automatically since locks are lazy and require an extrinsic to update.

There are two ways that vesting schedules can be created.

  • One way is through an extrinsic type available in the Vesting pallet, vested_transfer. The vested transfer function allows anyone to create a vesting schedule with a transfer of funds, as long as the account for which the vesting schedule will be created does not already have one and the transfer moves at least MinVestedTransfer funds, which is specified as a chain constant.
  • A second way is as part of the genesis configuration of the chain. In the case of Kusama, the chain specification genesis script reads the state of the Claims contract that exists on the Ethereum blockchain and creates vesting schedules in genesis for all the allocations registered as being vested.

Vesting schedules have three parameters:

  • locked, the amount of tokens to be transferred in Planck units)
  • per block, the number of tokens that are released per block
  • starting block, the block number after which the vesting schedule starts

The configuration of these three fields dictates the amount of funds that are originally locked, the slope of the unlock line and the block number for when the unlocking begins.

info

You can watch this video tutorial to understand how to do vested transfers, including linear and cliff vesting. Note the tutorial uses the Westend Testnet, but the same applies to both Polkadot and Kusama.

Lazy Vesting​

Like simple payouts, vesting is lazy, which means that someone must explicitly call an extrinsic to update the lock that is placed on an account.

  • The vest extrinsic will update the lock that is placed on the caller.
  • The vest_other will update the lock that is placed on another "target" account's funds.

These extrinsics are exposed from the Vesting pallet.

If you are using the Polkadot-JS UI, when there are KSM available to vest for an account, then you will have the ability to unlock KSM which has already vested from the Accounts page.

unbond

Batch Transfers​

Batch transfers are balances transfers to multiple accounts executed by one account. In order to construct a batch transfer you need to:

  • Create a utility.batch(calls) extrinsic using the utility pallet, and
  • Within the batch call you can create multiple balances.transferKeepAlive extrinsics using the balances pallet. You can specify as many receivers as you desire.
info

You can watch this video tutorial to learn how to do batch transfers. Note the tutorial uses the Westend Testnet, but the same applies to both Polkadot and Kusama.

Existing Reference Error​

If you are trying to reap an account and you receive an error similar to "There is an existing reference count on the sender account. As such the account cannot be reaped from the state", then you have existing references to this account that must be first removed before it can be reaped. References may still exist from:

  • Bonded tokens (most likely)
  • Unpurged session keys (if you were previously a validator)
  • Token locks
  • Existing recovery info
  • Existing assets

Bonded Tokens​

If you have tokens that are bonded, you will need to unbond them before you can reap your account. Follow the instructions at Unbonding and Rebonding to check if you have bonded tokens, stop nominating (if necessary) and unbond your tokens.

Checking for Locks​

info

See this video tutorial and this support page to learn how to check for locks and remove them.

You can also check for locks by querying system.account(AccountId) in Chain state tab under the Developer drop-down menu in the Polkadot-JS UI. Select your account, then click the "+" button next to the dropdowns, and check the relative data JSON object. If you see a non-zero value for anything other than free, you have locks on your account that need to get resolved.

Purging Session Keys​

If you used this account to set up a validator and you did not purge your keys before unbonding your tokens, you need to purge your keys. You can do this by seeing the How to Stop Validating page. This can also be checked by checking session.nextKeys in the chain state for an existing key.

Existing Recovery Info​

On Kusama, you can check if recovery has been set up by checking the recovery.recoverable(AccountId) chain state. This can be found under Developer > Chain state in PolkadotJS Apps.

Existing Non-Native Assets​

Currently, Kusama does not use the Assets Pallet, so this is probably not the reason for your tokens having existing references.

Last updated on by Radha