Add page on sending ERC-20s via XCM

.snippets/code/xtokens/send-erc20s/ethers.js

@@ -0,0 +1,42 @@
+import abi from './xTokensABI.js'; // Import the x-tokens ABI
+import { ethers } from 'ethers'; // Import Ethers library
+
+const PRIVATE_KEY = 'INSERT-PRIVATE-KEY';
+
+// Create Ethers wallet & contract instance
+const provider = new ethers.providers.JsonRpcProvider(
+  'https://rpc.api.moonbase.moonbeam.network'
+);
+const signer = new ethers.Wallet(PRIVATE_KEY, provider);
+const xTokens = new ethers.Contract(
+  '0x0000000000000000000000000000000000000804',
+  abi,
+  signer
+);
+
+// ERC-20 contract address in Moonbase Alpha
+const ERC20_ADDRESS = 'INSERT-ERC20-ADDRESS';
+
+// Multilocation targeting an account on the relay chain from Moonbase Alpha
+// Example interior: 0x01c4db7bcb733e117c0b34ac96354b10d47e84a006b9e7e66a229d174e8ff2a06300
+const RELAY_ACC = [
+  1,
+  ['0x01' + 'INSERT-ADDRESS-32-BYTES' + '00'],
+];
+
+// Sends 1 ERC-20 token to the relay chain using the transfer function
+async function transferToRelayChainAccount() {
+  // Creates, signs, and sends the transfer transaction
+  const transaction = await xTokens.transfer(
+    ERC20_ADDRESS, // Asset
+    '1000000000000000000', // Amount
+    RELAY_ACC, // Destination
+    '4000000000' // Weight
+  );
+
+  // Waits for the transaction to be included in a block
+  await transaction.wait();
+  console.log(transaction);
+}
+
+transferToRelayChainAccount();

.snippets/code/xtokens/send-erc20s/web3.js

@@ -0,0 +1,46 @@
+import abi from './xtokensABI.js'; // Import the x-tokens ABI
+import Web3 from 'web3'; // Import Web3 library
+
+const PRIVATE_KEY = 'YOUR_PRIVATE_KEY_HERE';
+
+// Create Web3 wallet & contract instance
+const web3 = new Web3('https://rpc.api.moonbase.moonbeam.network'); // Change to network of choice
+const xTokens = new web3.eth.Contract(
+  abi,
+  '0x0000000000000000000000000000000000000804',
+  { from: web3.eth.accounts.privateKeyToAccount(PRIVATE_KEY).address } // 'from' is necessary for gas estimation
+);
+
+// ERC-20 contract address in Moonbase Alpha
+const ERC20_ADDRESS = 'INSERT-ERC20-ADDRESS';
+
+// Multilocation targeting an account on the relay chain from Moonbase Alpha
+// Example interior: 0x01c4db7bcb733e117c0b34ac96354b10d47e84a006b9e7e66a229d174e8ff2a06300
+const RELAY_ACC = [1, ['0x01' + 'INSERT-ADDRESS-32-BYTES' + '00']];
+
+// Sends 1 ERC-20 token to the relay chain using the transfer function
+async function transferToRelayChainAccount() {
+  // Create transaction
+  const transferTx = xTokens.methods.transfer(
+    ERC20_ADDRESS, // Asset
+    '1000000000000000000', // Amount
+    RELAY_ACC, // Destination
+    '4000000000' // Weight
+  );
+
+  // Sign transaction
+  const signedTx = await web3.eth.accounts.signTransaction(
+    {
+      to: '0x0000000000000000000000000000000000000804',
+      data: transferTx.encodeABI(),
+      gas: await transferTx.estimateGas(),
+    },
+    PRIVATE_KEY
+  );
+
+  // Send signed transaction
+  const sendTx = await web3.eth.sendSignedTransaction(signedTx.rawTransaction);
+  console.log(sendTx);
+}
+
+transferToRelayChainAccount();

.snippets/code/xtokens/send-erc20s/web3.py

@@ -0,0 +1,45 @@
+from web3 import Web3
+
+abi = 'X_TOKENS_ABI_HERE' # Paste or import the x-tokens ABI
+private_key = 'YOUR_PRIVATE_KEY_HERE' # This is for demo purposes, never store your private key in plain text
+address = 'YOUR_ADDRESS_HERE' # The wallet address that corresponds to your private key
+
+# Create Web3 wallet & contract instance
+web3 = Web3(Web3.HTTPProvider('https://rpc.api.moonbase.moonbeam.network'))
+x_tokens = web3.eth.contract(
+    address='0x0000000000000000000000000000000000000804',
+    abi=abi
+)
+
+# ERC-20 contract address in Moonbase Alpha
+ERC20_ADDRESS = 'INSERT_ERC20_ADDRESS'
+
+# Multilocation targeting an account on the relay chain from Moonbase Alpha
+# Example interior: 0x01c4db7bcb733e117c0b34ac96354b10d47e84a006b9e7e66a229d174e8ff2a06300
+RELAY_ACC = [1, ['0x0' + 'INSERT_ADDRESS_32_BYTES' + '00']]
+
+# Sends 1 ERC-20 token to the relay chain using the transfer function
+def transfer_to_relay_chain_account():
+    # Create transaction
+    transfer_tx = x_tokens.functions.transfer(
+        ERC20_ADDRESS,       # Asset
+        1000000000000000000, # Amount
+        RELAY_ACC,           # Destination
+        4000000000           # Weight
+    ).buildTransaction(
+        {
+            'from': address,
+            'nonce': web3.eth.get_transaction_count(address),
+        }
+    )
+
+    # Sign transaction
+    signed_tx = web3.eth.account.sign_transaction(transfer_tx, private_key)
+
+    # Send tx and wait for receipt
+    hash = web3.eth.send_raw_transaction(signed_tx.rawTransaction)
+    receipt = web3.eth.wait_for_transaction_receipt(hash)
+    print(f'Tx successful with hash: { receipt.transactionHash.hex() }')
+
+transfer_to_relay_chain_account()
+

.snippets/code/xtokens/web3py.md

@@ -36,7 +36,7 @@ def transferToAlice():
     # Sign transaction
     signedTx = web3.eth.account.sign_transaction(transferTx, privateKey)
 
-    # 7. Send tx and wait for receipt
+    # Send tx and wait for receipt
     hash = web3.eth.send_raw_transaction(signedTx.rawTransaction)
     receipt = web3.eth.wait_for_transaction_receipt(hash)
     print(f'Tx successful with hash: { receipt.transactionHash.hex() }')

.snippets/text/erc20-interface/erc20-interface.md

@@ -5,13 +5,13 @@ The interface includes the following functions:
 - **decimals()** — read-only function that returns the decimals of the token
 - **totalSupply()** — read-only function that returns the total number of tokens in existence
 - **balanceOf**(*address* who) — read-only function that returns the balance of the specified address
-- **allowance**(*address* owner, *address* spender) —  read-only function that checks and returns the amount of tokens that an owner is allowed to a spender
-- **transfer**(*address* to, *uint256* value) — transfers a given amount of tokens to a specified address and returns true if the transfer was successful
-- **approve**(*address* spender, *uint256* value) — approves the provided address to spend a specified amount of tokens on behalf of `msg.sender`. Returns true if successful
-- **transferFrom**(*address* from, *address* to, *uint256* value) — transfers tokens from one given address to another given address and returns true if successful
+- **allowance**(*address* owner, *address* spender) —  read-only function that checks and returns the amount of tokens that a spender is allowed to spend on behalf of the owner
+- **transfer**(*address* to, *uint256* value) — transfers a given amount of tokens to a specified address and returns `true` if the transfer was successful
+- **approve**(*address* spender, *uint256* value) — approves the provided address to spend a specified amount of tokens on behalf of `msg.sender`. Returns `true` if successful
+- **transferFrom**(*address* from, *address* to, *uint256* value) — transfers tokens from one given address to another given address and returns `true` if successful
 
 !!! note
-    The ERC-20 standard does not specify the implications of multiple calls to `approve`. Changing an allowance with this function numerous times enables a possible attack vector. To avoid incorrect or unintended transaction ordering, you can first reduce the `spender` allowance to `0` and then set the desired allowance afterward. For more details on the attack vector, you can check out the [ERC-20 API: An Attack Vector on Approve/TransferFrom Methods](https://docs.google.com/document/d/1YLPtQxZu1UAvO9cZ1O2RPXBbT0mooh4DYKjA_jp-RLM/edit#){target=_blank} overview
+    The ERC-20 standard does not specify the implications of multiple calls to `approve`. Changing an allowance with this function numerous times enables a possible attack vector. To avoid incorrect or unintended transaction ordering, you can first reduce the `spender` allowance to `0` and then set the desired allowance afterward. For more details on the attack vector, you can check out the [ERC-20 API: An Attack Vector on Approve/TransferFrom Methods](https://docs.google.com/document/d/1YLPtQxZu1UAvO9cZ1O2RPXBbT0mooh4DYKjA_jp-RLM/edit#){target=_blank} overview.
 
 The interface also includes the following required events:
 

.snippets/text/xc-20/xtokens/multilocation-structures.md

@@ -0,0 +1,29 @@
+The following code snippet goes through some examples of `Multilocation` structures, as they would need to be fed into the X-Tokens Precompile functions:
+
+```js
+// Multilocation targeting the relay chain or its asset from a parachain
+{
+    1, // parents = 1
+    [] // interior = here
+}
+
+// Multilocation targeting Moonbase Alpha DEV token from another parachain
+{
+    1, // parents = 1
+    // Size of array is 2, meaning is an X2 interior
+    [
+        "0x00000003E8", // Selector Parachain, ID = 1000 (Moonbase Alpha)
+        "0x0403" // Pallet Instance = 3
+    ]
+}
+
+// Multilocation targeting Alice's account on the Relay Chain from Moonbase Alpha
+{
+    1, // parents = 0
+    // Size of array is 1, meaning is an X1 interior
+    [
+        "0x01c4db7bcb733e117c0b34ac96354b10d47e84a006b9e7e66a229d174e8ff2a06300" 
+        // AccountKey32 Selector + Address in hex + Network = Any
+    ]
+}
+```

builders/interoperability/xcm/xc20/.pages

@@ -3,6 +3,5 @@ nav:
   - index.md
   - 'Overview': 'overview.md'
   - 'External XC-20s': 'xc20.md'
-  - 'Mintable XC-20s': 'mintable-xc20.md'
-  - 'Send XC-20s': 'xtokens.md'
-
+  - 'Send External XC-20s': 'xtokens.md'
+  - 'Send Local ERC-20s via XCM': 'xcm-erc20s.md'