Merge pull request #7 from webb-tools/shady/tangle-addresses

Add Tangle Addresses Page

pages/docs/learn/_meta.json

@@ -3,5 +3,6 @@
   "incentives": "Incentives, Staking and Slashing",
   "understanding-dkg-tangle": "Intro to Distributed Key Generation (DKG)",
   "distributed-key-gen": "DKG In-Depth",
-  "tss-governance": "TSS In-Depth"
+  "tss-governance": "TSS In-Depth",
+  "addresses": "Tangle Addresses"
 }

pages/docs/learn/addresses.mdx

@@ -0,0 +1,83 @@
+---
+title: "Tangle Network Addresses"
+---
+
+## 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
+
+```tsx
+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
+
+```tsx
+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:
+
+```tsx
+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.
+
+```tsx
+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.