Repository files navigation

A proposal by Simon Warta developed within the Shift project on November 2019.

If you have an existing group of token holders that you want to migrate to aSubstrate based blockchain, you'll most likely run into the situation that theold and the new address system are incompatible.

Since Substrate addresses are encoded pubkeys, this happens when

• Case 1: Some of the token holders are identified by anaddress = derive(pubkey) only, but the correspondingpubkey is unknown.
• Case 2: The derivation algorithm from secret to keypair is different forthe old and the new system, such that users' pubkeys change.

To make a migration possible, we look for a way to transfer the old tokens tothe new system in a secure and convenient way.

The same problem exists when you want to perform an airdrop over a differentcrypto ecosystem or when switching from one signature algorithm to another. Weintend to solve the primary problem in a sufficiently general fashion to coverthose use cases as well.

• target system: the newly created Substrate based chain running the migrationmodule designed in this document.
• external system: the system from which token holders migrate to the newSubstrate based system. This can be a legacy system (migration case) or aparallel system (airdrop case).
• target pubkey/address: the public key and address on the target system.
• external pubkey/address: the public key and address on the external system.

In case 2 from above, we assume the token holder uses an old keypair on theexternal system which is potentially different from the new keypair. For eachtoken holder, the amount of tokens to receive on the target system is associatedwith the external address. Now the owner of the external address needs to proveto the target system that they own the external address. This is done by signinga message with the keypair, which belongs to that address (proof ofownership). The external address owner now defines where the tokens should betransferred to, usually their target address (transfer order). The proof ofownership as well as the transfer order are wrapped into a so calledclaimtransaction, a new transaction type specific to this module.

For spam protection reasons, the target system will usually charge some kind offee in order to include and execute a transaction. During the onboarding processhowever, the token holder does not have access to their funds before the claimtransaction is executed. However, executing a claim transactions requires anexisting balance.

We'll see that the claim transaction can be submitted by any account on thetarget system, allowing community provided onboarding services.

The migration module is specific to Substrate. The target module for the tokensisbalances.

The balance for each token holder must be known to the module and is immutableonce initialized. In case of a migration, this typically comes from a state dumpof the old system. For an airdrop, any logic may apply. A single balance cansupport multiple currencies.

The migration module we're designing contains the following things:

1. A set of configurations, including e.g. the address from which the tokens aredistributed and a migration timeout
2. A queryable data store holding entries with external address, external pubkeyand remaining claimable token balance.
3. A custom claim transaction that when executed verifies the right to claim,transfers tokens to a target address and updates the value of claimable tokenbalance for this user to 0.

• Distribution address: ...
• End time: After this point in time, the shutdown transaction can be executed

...

The claim transaction is a new transaction type specific to this module. Itcontains two things

1. Aproof of ownership of the external address
2. Thetransfer order, instructing to transfer the tokens to an arbitrarytarget address

The proof of ownership is a digital signature using the external system'ssigning algorithm. To avoid replaying existing signatures, a migration specificcontent needs to be signed. This is the transfer order string "claim on {chainID}; transfer to {target address}".

Partial claims should not be supported since this feature is consideredunnecessary.

Since the ownership of the target address does not need to be proven (tokenholder is free to transfer the tokens to wherever they want), the targetsystem's transaction signer is not relevant. Anybody willing to pay thetransaction fee can submit the claim transaction.

This transaction can be sent by any account and fails if the current time is notafter the end time.

When executed, the remaining tokens of the distribution address are burned andthe data store is cleared to an empty collection. Claim transaction logicremains unchanged by this event.

The chicken service is a service to solve the chicken-or-egg problem in theonboarding process by paying and submitting claim transactions for the user.Since the transaction signer is irrelevant for the claim execution, any numberof those services can exist.

This service is entirely optional and to be considered a convenience feature.The user can always execute a claim transaction after getting some initialtokens to pay the transaction fee on their own.

The basic flow is:

1. User created the content of a claim by signing the claim string
2. User sends the signed claim string via an API to the chicken service
3. Chicken services takes the claim string, wraps it into a claim transactionand submits this transaction to the target system

Since the chicken service does a charity service for the community, it needs toprotect itself from being abused. Otherwise an attacker could send many invalidclaims and the chicken service pays a lot of transaction fees. The goal is topay for no more than one claim transaction per token holder. This can beachieved with the following off-chain checks:

1. Check format and validity of the claim string
2. Validate signature of the claim string
3. Derive the external address of the signer
4. Ensure the external address has tokens to be claimed (requires a query to thetarget system)
5. Limit claim transactions to one per external address

1. What kind of chain IDs exist in Substrate that can be used for the claimstring?

This document is licensed under aCreative Commons Attribution 4.0 International license.