How to Create an HBAR Token Faucet for MetaMask
IMG 2356
Apr 03, 2023
by Abi Castro

Enabling the opportunity to connect to a dApp with different wallets provides more control to the user. Recently, HIP-583 added the necessary network infrastructure to support Ethereum Virtual Machine (EVM) wallets on the Hedera network. This added functionality, combined with the auto-create flow described in HIP-32, enables developers to transfer native Hedera Token Service tokens to EVM addresses that do not yet exist on the Hedera network. In this tutorial, we start out with a Hedera react app, connect our dApp to MetaMask, and finally transfer HBAR to the connected MetaMask account.

What we will do:

  • Create a Hedera react-app Utilizing TypeScript and Material UI
  • Install MetaMask Chrome Extension
  • Add Hedera Testnet Network to MetaMask
  • Connect Our dApp to MetaMask and Retrieve Wallet Address
  • Install Hedera Hashgraph JS SDK and Create Your Client
  • Send HBAR to MetaMask Wallet

    The complete TypeScript project can be found on GitHub here.

    The complete JavaScript project can be found on GitHub here.

    How Do I Build an HBAR Faucet for MetaMask?

    Step 1: Create a react-app

    Open your terminal and run the following command to create a react-app that utilizes TypeScript and Material UI.

    Code Snippet Background
    npx create-react-app hbar-faucet-testing --template git+ssh://[email protected]/a-ridley/cra-template-hedera-theme.git
    

    This create react-app theme provides a navbar with a button, footer, react-router, and a global context for state management. We will use this template to kickstart our project.

    Open the project in Visual Studio code. Your project directory structure will look like this:

    Code Snippet Background
    ├── node_modules
    ├── public
    ├── src
    ├── .gitignore
    ├── package-lock.json
    ├── package.json
    ├── README.md
    └── tsconfig.json
    

    Step 2: Install MetaMask Chrome Extension

    If you have not already installed the MetaMask extension, please install it here.

    Step 3: Add Hedera Testnet Network to MetaMask

    In this step, we will add the code necessary to add the Hedera Testnet Network to MetaMask so we can connect to it. Before we do that, let’s check out our src folder structure, which looks like this:

    Code Snippet Background
    src
    ├── assets
    ├── components
    ├── App.tsx
    ├── AppRouter.tsx
    ├── Home.tsx
    ├── index.tsx
    ├── react-app-env.ts
    

    Let’s continue and add a new folder inside src and name it services. Inside the services folder, add a file named metamaskService.ts. Your src folder structure will look like this:

    Code Snippet Background
    src
    ├── assets
    ├── components
    ├── services
    	├── metamaskServices.ts
    ├── App.tsx
    ├── AppRouter.tsx
    ├── Home.tsx
    ├── index.tsx
    ├── react-app-env.ts
    

    We will store code in the services folder, which will be used to support certain services required to run our application. We added the metamaskService.ts file to hold the code necessary for our MetaMask integration with our application. This distinction helps keep our code organized and clean.

    It’s important to note that to add the Hedera Testnet Network to MetaMask, we must determine if MetaMask exists in our browser. We can achieve this by using the window, aka the Browser Object Model (BOM), which represents the browser's window. This window object can access all global JavaScript objects, functions, and variables. If we are successful in accessing the Ethereum object off of the window object, then it is an indication that MetaMask is installed. If it is not successful, then we will handle that by throwing an error message to the console that reads, “MetaMask is not installed! Go install the extension!”

    Let's begin!

    In our metamaskService.ts file, create a function named switchToHederaNetwork.

    Code Snippet Background
    export const switchToHederaNetwork = async (ethereum: any) => {
      try {
        await ethereum.request({
          method: 'wallet_switchEthereumChain',
          params: [{ chainId: '0x128' }] // chainId must be in hexadecimal numbers
        });
      } catch (error: any) {
        if (error.code === 4902) {
          try {
            await ethereum.request({
              method: 'wallet_addEthereumChain',
              params: [
                {
                  chainName: 'Hedera Testnet',
                  chainId: '0x128',
                  nativeCurrency: {
                    name: 'HBAR',
                    symbol: 'HBAR',
                    decimals: 18
                  },
                  rpcUrls: ['https://testnet.hashio.io/api']
                },
              ],
            });
          } catch (addError) {
            console.error(addError);
          }
        }
        console.error(error);
      }
    }
    

    Let’s digest this function a little further. This function starts by submitting a request to change to the Hedera Testnet Network. If it fails to connect due to the Hedera Testnet not being added to MetaMask, then we will submit a request to add a new chain.

    In the request to add a new chain, the decimal value is set to 18 even though HBAR has 8 decimals. The reason for this is because MetaMask only supports chains that have 18 decimals. The rpc url that we use is https://testnet.hashio.io/api, which comes from Hashio, the SwirldsLabs-hosted version of the JSON-RPC Relay.

    Step 4: Connect Our dApp to MetaMask and Retrieve Wallet Address

    We have added the code necessary to add the Hedera Testnet Network to MetaMask. Now, it's time to focus on adding the code that will allow us to connect to MetaMask.

    In the metamaskService.ts file underneath switchToHederaNetwork(), add a new function named connectToMetamask().

    Code Snippet Background
    // returns a list of accounts
    // otherwise empty array
    export const connectToMetamask = async () => {
      const { ethereum } = window as any;
      // keep track of accounts returned
      let accounts: string[] = []
      if (!ethereum) {
        throw new Error("Metamask is not installed! Go install the extension!");
      }
      
      switchToHederaNetwork(ethereum);
      
      accounts = await ethereum.request({
        method: 'eth_requestAccounts',
      });
      return accounts;
    }
    

    If MetaMask is installed, connectToMetamask() will call switchToHederaNetwork() and submit a request to get accounts.

    Before we do any kind of work or testing, it is important to ensure we are connected to the correct network.

    Step 5: Install Hedera Hashgraph JS SDK and Create Your Client

    We’ve written the code to connect our application to MetaMask. Now it’s time to send HBAR to our MetaMask wallet.

    Install Dependencies

    Install hashgraph sdk and dotenv by running the following command in project root directory:

    Code Snippet Background
    npm install --save @hashgraph/sdk dotenv
    

    Create your .env file by adding a new file to the root directory of your react-app and naming it .env. Next, add the .env file to your .gitignore to prevent sharing your credentials in source control.

    Your .env file will look like this:

    Code Snippet Background
    REACT_APP_MY_ACCOUNT_ID=
    REACT_APP_MY_PRIVATE_KEY=
    

    In a react-app, your environment variables in your .env file must start with REACT_APP_. Set the values to a Testnet account you created through the Hedera developer portal.

    Note: If you need to create a Hedera Testnet account, visit portal.hedera.com and sign up to receive 10,000 test HBAR.

    Create Your Client

    A client is used to communicate with the network. We create our client for the Hedera Testnet Network, which enables us to submit transactions and pay for them. Let’s create our client in our Home.tsx file.

    Code Snippet Background
    export default function Home() {
      // If we weren't able to grab it, we should throw a new error
      if (!process.env.REACT_APP_MY_ACCOUNT_ID || !process.env.REACT_APP_MY_PRIVATE_KEY) {
        throw new Error("Environment variables REACT_APP_MY_ACCOUNT_ID and REACT_APP_MY_PRIVATE_KEY must be present");
      }
    
      // create your client
      const myAccountId = AccountId.fromString(process.env.REACT_APP_MY_ACCOUNT_ID);
      const myPrivateKey = PrivateKey.fromString(process.env.REACT_APP_MY_PRIVATE_KEY);
    
      const client = Client.forTestnet();
      client.setOperator(myAccountId, myPrivateKey);
    
      return (
        <Stack 
          spacing={4}
          sx={{alignItems: 'center'}}
        >
          <Typography
            variant="h4"
            color="white"
          >
            Let's buidl a dApp on Hedera
          </Typography>
        </Stack>
      )
    }
    

    Build Your TransferTransaction

    In our services folder, add a new file and name it hederaService.ts. This file will hold the code to send HBAR to our MetaMask wallet. Inside the file, let’s create a function and name it sendHbar.

    Code Snippet Background
    import { AccountId, Client, PrivateKey, TransactionReceiptQuery, TransferTransaction } from "@hashgraph/sdk"
    
    export const sendHbar = async (client:Client, fromAddress: AccountId | string, toAddress: AccountId | string, amount: number, operatorPrivateKey: PrivateKey) => {
      const transferHbarTransaction = new TransferTransaction()
        .addHbarTransfer(fromAddress, -amount)
        .addHbarTransfer(toAddress, amount)
        .freezeWith(client);
    
      const transferHbarTransactionSigned = await transferHbarTransaction.sign(operatorPrivateKey);
      const transferHbarTransactionResponse = await transferHbarTransactionSigned.execute(client);
    
      // Get the child receipt or child record to return the Hedera Account ID for the new account that was created
      const transactionReceipt = await new TransactionReceiptQuery()
        .setTransactionId(transferHbarTransactionResponse.transactionId)
        .setIncludeChildren(true)
        .execute(client);
    
      const childReceipt = transactionReceipt.children[0];
    
      if(!childReceipt || childReceipt.accountId === null) {
        console.warn(`No account id was found in child receipt. Child Receipt: ${JSON.stringify(childReceipt, null, 4)}`);
        return;
      }
    
       const newAccountId = childReceipt.accountId.toString();
       console.log(`Account ID of the newly created account: ${newAccountId}`);
    }
    

    This function builds a TransferTransaction that will send a specified amount of HBAR from one account to another account. In our case, our from account is our developer portal account and our to account is our MetaMask wallet address.

    Once the transaction is built, we approve it by signing it with our private key by calling .sign(). We call .execute() on our signed transaction using the client to pay for the transaction fee.

    When a transaction is executed, the result is of type TransactionResponse. Use the transaction id from the TransactionResponse in a TransactionReceiptQuery to get a TransactionReceipt, including children transactions.

    You can learn and read more about parent and child transactions on our documentation site.

    Note: For security purposes, the account that is sending the tokens should be on a backend server, but for simplicity, it will be on the frontend. This is a reminder that private keys should never be exposed on the frontend, as that is the easiest way to lose control of your account.

    Step 6: Send HBAR to MetaMask Wallet

    We’ve written the code necessary to connect our application to MetaMask and added the Hedera Hashgaph JavaScript SDK. Now it’s time to focus on connecting all the parts and sending HBAR to our MetaMask wallet.

    6.1 Configure State Management

    React has a feature called Context that allows you to easily pass data between components without prop drilling. We will be leveraging this feature to save the MetaMask wallet address and enable us to access it from various components in our react-app.

    Let's edit our src/contexts/GlobalAppContext.tsx file, which came with our template, to look like this:

    Code Snippet Background
    import { createContext, ReactNode, useState } from "react";
    
    const defaultValue = {
      metamaskAccountAddress: '',
      setMetamaskAccountAddress: (newValue: string) => { },
    }
    
    export const GlobalAppContext = createContext(defaultValue)
    
    export const GlobalAppContextProvider = (props: { children: ReactNode | undefined }) => {
      const [metamaskAccountAddress, setMetamaskAccountAddress] = useState('')
    
      return (
        <GlobalAppContext.Provider
          value={{
            metamaskAccountAddress,
            setMetamaskAccountAddress
          }}
        >
          {props.children}
        </GlobalAppContext.Provider>
      )
    }
    

    6.2 Add Functionality to the NavBar Button

    Once we’ve set up our context, we use it to share application state throughout the app. We use the context by calling useContext() and passing in GlobalAppContext as an argument. This allows us to get and set the wallet address from anywhere in the app.

    Add the following code to the top of the file src/components/Navbar.tsx:

    Code Snippet Background
    export default function NavBar() {
      // use the GlobalAppContext to keep track of the metamask account connection
      const { metamaskAccountAddress, setMetamaskAccountAddress } = useContext(GlobalAppContext);
    

    Next, we will create a new function to connect to metamask and store the wallet address in the GlobalAppContext.

    Code Snippet Background
    const retrieveWalletAddress = async () => {
    	const addresses = await connectToMetamask();
    	if (addresses) {
          // grab the first wallet address
          setMetamaskAccountAddress(addresses[0]);
          console.log(addresses[0]);
        }
      }
    

    Now we can add an onClick to our button and change the text to say ‘Connect to MetaMask.’ onClick will call retrieveWalletAddress.

    Your completed button code will look like this:

    Code Snippet Background
    <Button
    	variant='contained'
    	color='secondary'
    	sx={{
    		ml: 'auto'
    	}}
    	onClick={retrieveWalletAddress}
    >
    	{metamaskAccountAddress === "" ?
    		"Connect to MetaMask" :
    		`Connected to: ${metamaskAccountAddress.substring(0, 8)}...`}
    </Button>
    

    6.3 Add Send HBAR Button

    In the Home.tsx file, we will call our global context to gain access to our metamaskAccountAddress state variable.

    Code Snippet Background
    export default function Home() {
      const { metamaskAccountAddress } = useContext(GlobalAppContext);
    

    Next, add a new button to send HBAR to our MetaMask wallet. After the closing tag </Typography>, create a material UI button and add onClick. The onClick will call sendHbar(), which is inside src/services/hederaService.ts.

    Code Snippet Background
    onClick={() => {
    	sendHbar(client, myAccountId, AccountId.fromEvmAddress(0, 0, metamaskAccountAddress), 7, myPrivateKey)
    }}
    

    The to address will be the metamaskAccountAddress that we pulled out from our context using useContext(GlobalAppContext).

    Your completed button code will look like this:

    Code Snippet Background
    <Stack 
      spacing={4}
      sx={{alignItems: 'center'}}
    >
    	<Typography
      		variant="h4"
      		color="white"
    	>
      	  Let's buidl a dApp on Hedera
    	</Typography>
    	<Button
      	  variant="contained"
      	  color="secondary"
      	  onClick={() => {
        	sendHbar(client, myAccountId, AccountId.fromEvmAddress(0, 0, metamaskAccountAddress), 7, myPrivateKey)
      	  }}
    	>
      	  Transfer HBAR to MetaMask Account
    	</Button>
    </Stack>
    

    We’re ready to run our application! Open a terminal In the root directory of the project and run:

    Code Snippet Background
    npm run start
    

    Once up and running, click on the ‘Connect to MetaMask’ button in the upper right-hand corner.

    Image1

    After you click on it, the MetaMask pop-up window will open and you will be asked to switch from your previously connected network to the Hedera Testnet Network.

    Choose the account that you would like to connect to this application.

    Debugging tip: If you have previously connected your account to this dApp and clicking connect is not opening the wallet, disconnect all the connected accounts and then try again

    Once connected, send HBAR by clicking on the ‘SEND HBAR TO METAMASK’ button. You can open your console and see that the transaction response is printed to the console.

    Summary

    Congratulations! You successfully followed the instructions to build an HBAR faucet for MetaMask. You created a Hedera react-app that integrates with MetaMask. You learned how to build a transfer transaction that sends an amount of HBAR through the Hedera Testnet Network over to a MetaMask account. This can also be applied to other applications, and I encourage all to keep on building.

    Happy Building 👷‍♀️👷‍♂️

    Continue Learning