Update docs on EVM account <> Substrate account interactions

[shekohex]

Overview

Converting between Substrate and EVM addresses can initially be a bit complicated, but once you understand the basic idea behind it, it becomes easy. Let's define the different scenarios we will be using:

1. Alice only has an account on Tangle EVM using the Metamask wallet.
2. Bob has an account on Tangle using the Polkadot.js wallet, and another account on Tangle EVM using the Metamask wallet.
3. Charlie only has an account on Tangle using the Polkadot.js wallet.

Let's assign the following values:

• Alice's account: 0xa5fAA47a324754354CB0A305941C8cCc6b5de296
• Bob's accounts: 5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty and 0x690B9A9E9aa1C9dB991C7721a92d351Db4FaC990
• Charlie's account: 5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y

Convert Substrate Address to EVM

function substrateToEvm(input: string): string {
	// Decode the address to the 32 bytes.
	const accountId = decodeAddress(input);
	// Truncate it and take first 20 bytes
	const res = accountId.subarray(0, 20);
	// convert these bytes to hex.
	const output = u8aToHex(res);
	// The result is our EVM address.
	return output;
}

Convert EVM Address to Substrate

function evmToSubstrate(input: string): string {
	// Convert EVM address to bytes
	const addr = hexToU8a(input);
	// Add a "evm:" prefix
	const data = stringToU8a("evm:");
	// concat the address and the prefix and hash them together
	// using blake2
	const res = blake2AsU8a(u8aConcat(data, addr));
	// encode the output and using 42 address prefix (substrate default)
	const output = encodeAddress(res, 42);
	// The result is our Substrate address.
	return output;
}

Case 1: Sending from Substrate to EVM

Bob wants to send 100 TNT to Alice, but he does not have the 100 TNT on his EVM account in Metamask. Therefore, he decided to use his Tangle account in the polkadot.js wallet.

1. Alice's address is 0xa5fAA47a324754354CB0A305941C8cCc6b5de296.
2. Bob converts Alice's address to a substrate address using the evmToSubstrate function:

evmToSubstrate("0xa5fAA47a324754354CB0A305941C8cCc6b5de296");
// => 5C9ysBsWKpw3D8MFaEauFgdtMPqboS64YNYHyu1rCynLyKMZ

3. Bob sends the 100 TNT to 5C9ysBsWKpw3D8MFaEauFgdtMPqboS64YNYHyu1rCynLyKMZ.
4. Alice receives the 100 TNT in her Metamask wallet.

Case 2: Sending from EVM to Substrate

Alice wants to send 50 TNT to Charlie. However, Charlie only has a Substrate account that he controls in his Polkadot.js wallet.

1. Charlie's address is 5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y.
2. Alice converts Charlie's address to an EVM address using the substrateToEvm function.

substrateToEvm("5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y");
// => 0x90b5ab205c6974c9ea841be688864633dc9ca8a3

3. Alice uses her Metamask and sends 50 TNT to 0x90b5ab205c6974c9ea841be688864633dc9ca8a3.
4. Charlie's balance on Substrate remains the same!

The main reason here is that Charlie needs to withdraw the balance from his EVM account.

5. Charlie goes to Polkadot.js (maybe we can make it in our dApp?) and calls evm.withdraw("0x90b5ab205c6974c9ea841be688864633dc9ca8a3", 50 TNT).
6. Charlie sees that he has now received 50 TNT in his account.

TASK CHECKLIST

• Add a page on how to transfer tokens from your substrate account to your EVM account
• Add a page on how to transfer tokens from your EVM account to your substrate account
• Extra: a web page that allow you to transfer between them without the need to do it by hand.

[shekohex]

@shekohex you closed my issue (webb-tools/webb-docs#156) but as I see it, this information is totally different. I will merge these into a general account management section, if that's alright.

Yes! I closed the old one as it was in the wrong repo. Feel free to change this file or move it around.
This the new one: tangle-network/docs#7