Developer Boilerplate for Telegram Miniapp

Overview

This boilerplate is designed to help developers quickly integrate and interact with the UTXO Global Wallet on Telegram. It provides a foundational code structure, enabling efficient setup and functionality implementation.

Setup & Configuration

1. Create a New Repository:

• Goto https://github.com/UTXO-Global/utxo-global-twa-boilerplate

• Use the provided boilerplate code to get started quickly

  

2. Deploy to Vercel:

• Follow Vercel’s instructions to link your repository, set up environment variables, and configure your deployment settings.

• Once deployed, you’ll receive a public link, like: https://my-telegram-miniapp.vercel.app/. Make sure to test your link to verify everything works as expected.

3. Setting Up Your Telegram Miniapp

3.1. Setup a Telegram Bot:

• Open Telegram and search for “BotFather” (the official bot to create other bots).

• Start a conversation with “BotFather” and use the command

/newbot

• Follow the instructions to set up your bot:

  • You will be asked to provide a name for your bot.

  • Then, provide a username for your bot. The username must end with “bot” (e.g., MyCoolBot or MyCoolBot_bot).

3.2. Create a New App:

• Start a conversation with “BotFather” and use the command:

/newapp

• Choose your bot just created from step 3.1

• Follow the instructions to create a new web app for your bot

  • You will be asked to provide a title, a short description, and a photo (640x360 pixels) for the web app

  • Then, give the Web App URL you created from step 2. Deploy to Vercel

Once fully configured, your bot will be ready to interact with the UTXO Global Wallet on Telegram. Here is the boilerplate bot for your reference: https://t.me/utxo_global_boilerplate_stag_bot

Example Implementations

1. If you use React for your dApp:

• Step 1: Installation

NPM

npm i @utxo-global/tonconnect-ui

Yarn

yarn add @utxo-global/tonconnect-ui

• Step 2: Define customWallet with UTXO Global Wallet Information

import { UIWallet } from "@utxo-global/tonconnect-ui";

const customWallet: UIWallet = {
  appName: "utxowallet",
  name: "UTXO Wallet",
  imageUrl: "https://utxo.global/icon.png",
  aboutUrl: "https://t.me/utxo_global_wallet_bot/utxo",
  universalLink: "https://t.me/utxo_global_wallet_bot/utxo",
  jsBridgeKey: "utxowallet",
  bridgeUrl: "https://bridge.ton.space/bridge",
  platforms: ["ios", "android", "macos", "windows", "linux"],
};

• Step 3: Define tonConnect variable

const tonConnect = new TonConnect({
  manifestUrl: "https://config.utxo.global/utxo-ton-wallet-manifest.json",
  storage: LocalStorage,
});

• Step 4: Define tonConnectUI variable

const tonConnectUI = useMemo(() => {
    try {
      return new TonConnectUI({
        connector: tonConnect,
        actionsConfiguration: {
          twaReturnUrl: "{YOUR_TELEGRAM_BOT}",
        },
        uiPreferences: {
          theme: THEME.DARK,
          borderRadius: "m",
        },
        restoreConnection: true,
        walletsListConfiguration: {
          includeWallets: [customWallet],
        },
      });
    } catch (_e) {}
    return undefined;
  }, []);

• Step 5: Listen Status Changed

useEffect(() => {
  if (tonConnectUI) {
    tonConnectUI.connector.onStatusChange(
      (wallet) => setWallet(wallet),
      (error) => {
        toast.error(error.message, { autoClose: 3000 });
        tonConnectUI.closeSingleWalletModal();
      }
    );
    tonConnectUI.connectionRestored.then((restored) => {
      if (restored) {
        setWallet(tonConnectUI.wallet);
      } else {
        setWallet(null);
        console.log("Connection was not restored.");
      }
    });
  }
}, [tonConnectUI]);

• Step 6: Connect Wallet

const onConnect = async () => {
    tonConnectUI?.openSingleWalletModal("utxowallet");
};

• Step 7: Transfer CKB

const result = await tonConnectUI?.sendTransaction({
  validUntil: Math.floor(Date.now() / 1000) + 60,
  messages: [
    {
      address: addressTo,
      amount: transferAmount.toString()
    },
  ],
});

2. If you use CDN for your dApp:

• Step 1: Installation

<script src="https://utxo.global/@tonconnect/ui/2.1.0/tonconnect-ui.min.js"></script>

• Step 2: Define customWallet with UTXO Global Wallet Information

const customWallet = {
    appName: "utxowallet",
    name: "UTXO Wallet",
    imageUrl: "https://utxo.global/icon.png",
    aboutUrl: "https://t.me/utxo_global_wallet_bot/utxo",
    universalLink: "https://t.me/utxo_global_wallet_bot/utxo",
    jsBridgeKey: "utxowallet",
    bridgeUrl: "https://bridge.ton.space/bridge",
    platforms: ["ios", "android", "macos", "windows", "linux"],
};

• Step 3: Define tonConnectUI variable

var tonConnectUI = new TON_CONNECT_UI.TonConnectUI({
    manifestUrl: "https://config.utxo.global/utxo-ton-wallet-manifest.json",
    actionsConfiguration: {
      twaReturnUrl: "{YOUR_TELEGRAM_BOT}
    },
    uiPreferences: {
      theme: TON_CONNECT_UI.THEME.DARK,
      borderRadius: "m",
    },
    restoreConnection: true,
    walletsListConfiguration: {
      includeWallets: [customWallet],
    },
   });
 

• Step 4: Listen Status Changed

const unsubscribe = tonConnectUI.onStatusChange((walletAndwalletInfo) => {
  const currentWallet = tonConnectUI.wallet;
  const currentWalletInfo = tonConnectUI.walletInfo;
  const currentAccount = tonConnectUI.account;
  const currentIsConnectedStatus = tonConnectUI.connected;
  const currentState = tonConnectUI.singleWalletModalState;
  
  console.log("currentWallet", currentWallet);
  console.log("currentWalletInfo", currentWalletInfo);
  console.log("currentAccount", currentAccount);
  console.log("currentIsConnectedStatus", currentIsConnectedStatus);
  console.log("Current modal state:", currentState);
  
  if (currentIsConnectedStatus == true) {
    console.log("Current Wallet Info", currentWalletInfo);
  } else {
    console.log("Wallet is not connected.");
  }
});

• Step 5: Connect Wallet

tonConnectUI.connectionRestored.then(function (restored) {
   if (restored) {
     console.log(
       "Connection restored. Wallet:",
       JSON.stringify(Object.assign({}, tonConnectUI.wallet))
     );
     var currentWallet = tonConnectUI.wallet;
     console.log("Wallet information stored:", currentWallet);
   } else {
     console.log("Connection was not restored.");
   }
 });

• Step 6: Transfer CKB

const result = await tonConnectUI.sendTransaction({
   validUntil: Math.floor(Date.now() / 1000) + 60,
   messages: [
     {
       address: addressTo,
       amount: transferAmount.toString(),
     },
   ],
 });

 console.log("tx: ====> ", result.boc);

References

• https://github.com/UTXO-Global/ton-connect-sdk