Added details for addresses page

tangle-network · May 15, 2024 · afe4224 · afe4224
1 parent b4f632f
commit afe4224
Showing 1 changed file with 116 additions and 42 deletions.
diff --git a/pages/developers/addresses.mdx b/pages/developers/addresses.mdx
@@ -1,57 +1,129 @@
----
-title: "Tangle Network Addresses"
----
+import EvmToSubstrateConverter from '../../components/EvmToSubstrateConverter'
+import { Callout } from 'nextra/components'
 
-## EVM-Substrate Address Conversion
+# Account Addresses on Tangle
 
-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:
+If you're interacting with a Frontier-enabled Substrate chain like Tangle Network, you might encounter different address formats, such as SS58, Ethereum-style (H160), and Substrate-style (H256) addresses.
 
-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.
+To help you navigate between these formats, we've provided a handy conversion tool below. Simply enter your Ethereum address (H160), and the tool will generate the corresponding Substrate address (SS58) used on the Tangle Network chain.
 
-Let's assign the following values:
+<EvmToSubstrateConverter />
+<Callout type="warning" emoji="⚠️"> Please note that the conversion from an EVM address to a Substrate address using the provided tool is a one-way operation, and you cannot derive the original EVM address from a Substrate address. </Callout>
 
-- Alice's account: `0xa5fAA47a324754354CB0A305941C8cCc6b5de296`
-- Bob's accounts: `5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty` and `0x690B9A9E9aa1C9dB991C7721a92d351Db4FaC990`
-- Charlie's account: `5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y`
+## Address Formats in Frontier-enabled Substrate Chains
 
-## Convert Substrate Address to EVM
+Frontier is a powerful toolset that allows Substrate-based blockchains to offer Ethereum Virtual Machine (EVM) compatibility. This means that developers can deploy and execute Solidity smart contracts on Substrate chains with minimal changes. When working with Frontier, it's essential to understand the different address formats and their relationships. In a Frontier-enabled Substrate chain, there are three primary address formats:
 
-```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;
+1. **SS58 addresses**: SS58 is a simple account format designed for Substrate-based chains. It is heavily based on Bitcoin's Base-58-check format with a few alterations. The SS58 address is a base-58 encoded value that identifies a specific account on the Substrate chain. It consists of an address type, the encoded address, and a checksum. In the case of the Tangle Network, the chain ID and custom prefix used is `5845`, which yields the prefix `tg` when applied in conversion.
+
+2. **Ethereum-style addresses (H160)**: These addresses are 40 hex characters long (plus the "0x" prefix) and follow the Ethereum address format. They are derived from the private key used to sign transactions on the EVM side of the chain.
+
+3. **Substrate-style addresses (H256)**: These addresses are 256 bits long and are used natively by Substrate. They represent the raw, unencoded form of an account's public key or a hash value in Substrate.
+
+To bind an Ethereum H160 address with a Substrate H256 address, a truncated hash scheme is used. The first 160 bits (20 bytes) of the H256 address are taken and used as the corresponding H160 address.
+
+## Interacting with Frontier-enabled Substrate Chains
+
+When a user interacts with the EVM on a Frontier chain, they use their Ethereum-style address (H160). Behind the scenes, Frontier maps this H160 address to a corresponding Substrate-style address (H256) in the Substrate Balance pallet's storage. This mapping allows the user to hold and manage balances on the Substrate side.
+
+However, it's important to note that the user only has direct control over their H160 address and its associated private key. They cannot directly perform transactions or interact with Substrate-specific features using the mapped H256 address. To fully utilize the Substrate side of the chain, the user needs to have a separate SS58 address with its own private key.
+
+As a user, it's essential to understand the different address formats and their purposes when interacting with a Frontier-enabled Substrate chain. You'll need to manage your Ethereum-style address (H160) for EVM interactions and your SS58 address for Substrate-specific features.
+
+For developers building on a Frontier-enabled Substrate chain, it's crucial to be aware of these address formats and their relationships. You may need to provide clear instructions and tools to help users manage their addresses, perform cross-address transfers, and interact with both the EVM and Substrate components seamlessly.
+
+While the dual-address system may introduce some complexities, it also opens up a world of possibilities for interoperability and leveraging the strengths of both Ethereum and Substrate ecosystems.
+
+## Developer Resource
+
+### Cross-EVM/Substrate Token Transfers
+
+Handling cross-system token transfers between Substrate and EVM can be complex. Address mappings play a crucial role in facilitating these transfers.
+
+#### Scenarios
+
+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.
+
+Assigned values:
+
+- **Alice's account:** `0xa5fAA47a324754354CB0A305941C8cCc6b5de296`
+- **Bob's accounts:** `5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty` and `0x690B9A9E9aa1C9dB991C7721a92d351Db4FaC990`
+- **Charlie's account:** `5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y`
+
+### Address Mapping Explanation
+
+Address mappings between Substrate and EVM are one-way transformations that facilitate token transfers between the two systems.
+
+- **Substrate to EVM:** When a Substrate address is converted to an EVM address, the resulting EVM address can be used to receive tokens on the EVM side. The conversion involves extracting and hashing a part of the Substrate address, providing a unique EVM address corresponding to the original Substrate address.
+- **EVM to Substrate:** Once tokens are sent to the EVM address, the recipient can interact with the Substrate network by calling the `evm.withdraw` function. This allows the recipient to withdraw tokens from the EVM environment back to the Substrate environment.
+
+Key Points:
+
+- The conversion is a one-way mapping from Substrate to EVM.
+- The resulting EVM address is a hash of part of the Substrate address.
+- Tokens can be received on the EVM side using the EVM address.
+- The `evm.withdraw` function facilitates the transfer of tokens back to the Substrate side.
+
+### Convert Substrate Address to EVM
+
+To convert a Substrate address to an EVM address, the following script can be used:
+
+```typescript
+import { decodeAddress } from "https://esm.sh/@polkadot/util-crypto";
+import { u8aToHex } from "https://esm.sh/@polkadot/util";
+
+const input = Deno.args[0];
+if (!input) {
+  console.error("usage: deno run substrateToEvm.ts <SUBSTRATE_ADDRESS_HERE>");
+  Deno.exit(1);
 }
+const accountId = decodeAddress(input);
+const res = accountId.subarray(0, 20);
+const output = u8aToHex(res);
+console.log({ input, output });
+// run using:
+// $ deno run substrateToEvm.ts <SUBSTRATE_ADDRESS_HERE>
 ```
 
-## Convert EVM Address to Substrate
+The script takes a Substrate address as input, decodes it, and then extracts the first 20 bytes of the account ID. These 20 bytes are then converted into a hexadecimal string, resulting in an EVM-compatible address.
+
+#### Convert EVM Address to Substrate
+
+Here is an example using the Deno Runtime and @polkadot/util to convert an address from EVM 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;
+import {
+  blake2AsU8a,
+  encodeAddress,
+} from "https://esm.sh/@polkadot/util-crypto";
+import {
+  hexToU8a,
+  stringToU8a,
+  u8aConcat,
+} from "https://esm.sh/@polkadot/util";
+
+const input = Deno.args[0];
+if (!input) {
+  console.error("usage: deno run evmToSubstrate.ts <ETH_ADDRESS_HERE>");
+  Deno.exit(1);
 }
+const addr = hexToU8a(input);
+const data = stringToU8a("evm:");
+const res = blake2AsU8a(u8aConcat(data, addr));
+const output = encodeAddress(res, 42);
+console.log({ input, output });
+// run using:
+// $ deno run evmToSubstrate.ts <ETH_ADDRESS_HERE>
 ```
 
-### Case 1: Sending from Substrate to EVM
+<Callout>**Note**
+The conversion from an EVM address to a Substrate address is a one-way operation. Due to the hashing process, it is not possible to reverse the process and obtain the original EVM address from the resulting Substrate address.</Callout>
+
+#### 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.
+Bob wants to send 100 TNT to Alice, but he does not have the 100 TNT on his EVM account in Metamask. Therefore, he uses 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:
@@ -64,7 +136,7 @@ evmToSubstrate("0xa5fAA47a324754354CB0A305941C8cCc6b5de296");
 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
+#### 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.
 
@@ -76,8 +148,10 @@ substrateToEvm("5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y");
 // => 0x90b5ab205c6974c9ea841be688864633dc9ca8a3
 ```
 
-3. Alice uses her Metamask and sends 50 TNT to `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)`.
+   > Because: Charlie needs to withdraw the balance from his EVM account.
+5. Charlie goes to Polkadot.js and calls:
+   `evm.withdraw("0x90b5ab205c6974c9ea841be688864633dc9ca8a3", 50 TNT)`.
 6. Charlie sees that he has now received 50 TNT in his account.