createNewHederaAccount

How to call the API from an app

Identify Snap connects to your currently connected Metamask account by default. To learn how apps can connect to Identify Snap using a non-metamask(external) account, refer to this documentation.

Then, depending on whether you're trying to connect to a metamask account or a non-metamask account, you can call the snap API in the following way:

const snapId = `npm:@tuum-tech/identify`

const externalAccountParams = {
  externalAccount: {
    network: 'hedera',
    data: {
      accountId: '0.0.3988440'
    }
  }
}

const metamaskAddress = '0x2e5fF0267b678A0FAF9A9f5b0FBf7Ac9638B5b57'
const params = {
  metamaskAddress,
  hbarAmountToSend: 1, // This is the amount in TINYBAR
  newAccountEvmAddress: '0x5Ce55759b0D4049ED015a657726C1aaFC77F7bEC'
  /* 
    Note that the both the 'newAccountEvmAddress' and 'newAccountPublickey' parameters
    are optional however, when calling this API, you must set at least one of these.
  */
  // newAccountPublickey: "03c23eb353918be047152b5523a0ee1b3c3a74d6d3ae70d28fc7ccf3124c6afe6e",
  /* 
    Uncomment the below line if you want to connect to a non-metamask account
  */
  // ...externalAccountParams
}

const handleCreateNewHederaAccountAPI = async () => {
  await window.ethereum.request({
    method: 'wallet_invokeSnap',
    params: {
      snapId,
      request: {
        method: 'createNewHederaAccount',
        params: params
      }
    }
  })
}

Note: Both the newAccountEvmAddress and newAccountPublickey parameters are optional however, when calling this API, you must set at least one of these. If you pass in newAccountPublickey, the Identify Snap will send the appropriate HBARs to a public key at which point a new account id will be generated in the hedera ledger. Depending on your use case, you can either generate an account id for an EVM address or for a public key. Also, if an account id already exists for an account, the snap doesn't send the HBARs and simply returns the account id for that account.

How the API is handled between the app and snap

What the API does

1. Retrieves the currently connected account and the blockchain network the user has selected on Metamask. If it's the first time, the account info is also saved in snap state.

2. Queries the Hedera Mirror Node to check whether an account id already exists for a given EVM address or the public key.

3. If an account id already exists on the ledger, the snap returns it along with other information such as the current balance of the hedera account.

4. If an account id doesn't exist on the ledger, the snap uses hedera sdk to send the appropriate amount of tinybars(smallest unit of HBARs on the hedera network) to the given EVM address or a public key.

5. The account id is retrieved from the transaction receipt and returned as the result.

Some example responses:

Creating a new hedera account id for an EVM address: 0x5Ce55759b0D4049ED015a657726C1aaFC77F7bEC

{
    'account': '0.0.3988440',
    'evmAddress': '0x5Ce55759b0D4049ED015a657726C1aaFC77F7bEC',
    'newlyCreated': true
}

Calling the API to create a hedera account id for an EVM address whereby accountId already exists on the hedera ledger:

{
  "account": "0.0.3988440",
  "evmAddress": "0x5ce55759b0d4049ed015a657726c1aafc77f7bec",
  "alias": "LTSVOWNQ2QCJ5UAVUZLXE3A2V7DX667M",
  "balance": 1,
  "createdDate": "Tue Apr 04 2023 14:31:49 GMT-0400 (Eastern Daylight Time)",
  "expiryDate": "Mon Jul 03 2023 14:31:49 GMT-0400 (Eastern Daylight Time)",
  "memo": "lazy-created account",
  "newlyCreated": false
}

How the API works

https://github.com/tuum-tech/identify/blob/main/packages/snap/src/rpc/hedera/createNewHederaAccount.ts

import { AccountId, PrivateKey, PublicKey } from '@hashgraph/sdk';
import { BigNumber } from 'bignumber.js';
import _ from 'lodash';
import { HederaServiceImpl, isValidHederaAccountInfo } from '../../hedera';
import { getHederaNetwork, validHederaChainID } from '../../hedera/config';
import { HederaMirrorInfo, SimpleHederaClient } from '../../hedera/service';
import { WalletHedera } from '../../hedera/wallet/abstract';
import { PrivateKeySoftwareWallet } from '../../hedera/wallet/software-private-key';
import { HederaAccountParams, IdentitySnapParams } from '../../interfaces';
import { getCurrentNetwork } from '../../snap/network';
import { CreateNewHederaAccountRequestParams } from '../../types/params';
import { getHederaAccountIfExists } from '../../utils/params';

/**
 * Function to create a new hedera account.
 *
 * @param identitySnapParams - Identity snap params.
 * @param newHederaAccountParams - Parameters for creating a new hedera account.
 */
export async function createNewHederaAccount(
  identitySnapParams: IdentitySnapParams,
  newHederaAccountParams: CreateNewHederaAccountRequestParams,
): Promise<HederaMirrorInfo> {
  const { state, account } = identitySnapParams;
  const {
    hbarAmountToSend,
    newAccountPublickey = '',
    newAccountEvmAddress = '',
  } = newHederaAccountParams;

  const chainId = await getCurrentNetwork(ethereum);
  if (!validHederaChainID(chainId)) {
    console.error(
      'Invalid Chain ID. Valid chainIDs for Hedera: [0x127: mainnet, 0x128: testnet, 0x129: previewnet]',
    );
    throw new Error(
      'Non-Hedera network was selected on Metamask while trying to configure the Hedera network. Please switch the network to Hedera Network first',
    );
  }

  let _accountId = '';
  if (account.extraData === null || _.isEmpty(account.extraData)) {
    _accountId = await getHederaAccountIfExists(
      state,
      undefined,
      account.evmAddress,
    );
  } else {
    _accountId = (account.extraData as HederaAccountParams).accountId;
  }

  const network = getHederaNetwork(chainId);
  if (
    !(await isValidHederaAccountInfo(account.evmAddress, _accountId, network))
  ) {
    console.error(
      `Could not retrieve hedera account info using the accountId '${_accountId} and evm address '${account.evmAddress}'`,
    );
    throw new Error(
      `Could not retrieve hedera account info using the accountId '${_accountId} and evm address '${account.evmAddress}'`,
    );
  }

  const hederaService = new HederaServiceImpl(network);
  const accountId = AccountId.fromString(_accountId);
  const privateKey = PrivateKey.fromStringECDSA(account.privateKey);
  const walletHedera: WalletHedera = new PrivateKeySoftwareWallet(privateKey);
  const hederaClient = (await hederaService.createClient({
    walletHedera,
    keyIndex: 0,
    accountId,
  })) as SimpleHederaClient;
  if (hederaClient === null || _.isEmpty(hederaClient)) {
    console.error('Invalid private key or account Id of the operator');
    throw new Error('Invalid private key or account Id of the operator');
  }

  let newAccount = false;
  let result;
  if (newAccountPublickey) {
    const publicKey = PublicKey.fromString(newAccountPublickey).toStringRaw();
    try {
      result = (await hederaService.getAccountFromPublicKey(
        publicKey,
      )) as HederaMirrorInfo;

      if (result === null || _.isEmpty(result)) {
        newAccount = true;
      }
    } catch (error) {
      console.log(
        'Error while retrieving account info using public key from the mirror node so let us just try to fund this account. Error: ',
        error,
      );
      newAccount = true;
    }

    if (newAccount) {
      result = (await hederaClient.createAccountForPublicKey({
        publicKey: PublicKey.fromString(publicKey),
        initialBalance: BigNumber(hbarAmountToSend),
      })) as HederaMirrorInfo;
    }
  } else {
    try {
      result = (await hederaService.getAccountFromEvmAddres(
        newAccountEvmAddress,
      )) as HederaMirrorInfo;

      if (result === null || _.isEmpty(result)) {
        newAccount = true;
      }
    } catch (error) {
      console.log(
        'Error while retrieving account info using evm address from the mirror node so let us just try to fund this account. Error: ',
        error,
      );
      newAccount = true;
    }

    if (newAccount) {
      result = (await hederaClient.createAccountForEvmAddress({
        evmAddress: newAccountEvmAddress,
        initialBalance: BigNumber(hbarAmountToSend),
      })) as HederaMirrorInfo;
    }
  }

  console.log(
    'Newly created Hedera Account info: ',
    JSON.stringify(result, null, 4),
  );

  if (result === null || _.isEmpty(result)) {
    console.error(
      'Could not create a new hedera account id for the given public key or evm address. Please try again',
    );
    throw new Error(
      'Could not create a new hedera account id for the given public key or evm address. Please try again',
    );
  }
  result.newlyCreated = newAccount;

  return result;
}

Live Demo on CodePen

Some things to keep in mind while interacting with the above demo

• If you're getting any errors with the live demo, make sure you go through the FAQs section to learn about what you may be missing. You need to install Metamask in your browser for the live demo to work

• Whenever there is a new version of the IdentifySnap, always make sure to first uninstall the old version of the snap from Metamask and only then try the above demo so it can install the latest version

To ease the integration of Identify Snap on an application, we have created a template web application that you can run locally and check out the code in its entirety to learn how you can integrate and interact with various APIs exposed by Identify Snap. Check out the full source code at template application github repository.

You can also check out the API reference to learn how each API works.