API Reference

TMAWalletClient

• constructor(publicToken: string)

  • Initializes a new instance of the TMAWalletClient.

  • Parameters:

    • publicToken (string): The public token for your project.

• init()

  • Initializes the wallet client and sets up the connection to Telegram.

  • Returns: Promise<void>

• initWallet()

  • Initializes a new wallet for the user or restores an existing one.

  • Returns: Promise<void>

• createBundle()

  • Creates a new wallet bundle for the user.

  • Returns: Promise<void>

• isBundleExists()

  • Checks if a wallet bundle already exists for the user.

  • Returns: boolean

• getWalletAddress()

  • Retrieves the wallet address associated with the user's bundle.

  • Returns: Promise<string>

Usage Example

import { TMAWalletClient } from '@tmawallet/sdk';

(async () => {
  const tmaWallet = new TMAWalletClient('your_project_public_token');
  await tmaWallet.init();
  await tmaWallet.initWallet();
  if (tmaWallet.isBundleExists()) {
    console.log('Wallet Address:', await tmaWallet.getWalletAddress());
  } else {
    await tmaWallet.createBundle();
    console.log('New Wallet Address:', await tmaWallet.getWalletAddress());
  }
})();

ClientBundleController

• createNewBundle()

  • Creates a new client bundle.

  • Returns: Promise<any>

• getClientBundle()

  • Retrieves the existing client bundle.

  • Returns: Promise<any>

• clearClientBundle()

  • Clears the current client bundle.

  • Returns: Promise<void>

Usage Example

import { ClientBundleController } from '@tmawallet/sdk';
import { TelegramCloudStorage } from '@tmawallet/sdk';

(async () => {
  const storage = new TelegramCloudStorage();
  const clientBundleController = new ClientBundleController(storage);

  const newBundle = await clientBundleController.createNewBundle();
  console.log('Created Bundle:', newBundle);

  const existingBundle = await clientBundleController.getClientBundle();
  console.log('Existing Bundle:', existingBundle);

  await clientBundleController.clearClientBundle();
  console.log('Bundle Cleared');
})();

WalletBundleController

• storeWalletAddress(address: string)

  • Stores a wallet address linked to the client bundle.

  • Parameters:

    • address (string): The wallet address to store.

  • Returns: Promise<void>

• getWalletAddress()

  • Retrieves the stored wallet address.

  • Returns: Promise<string>

• clearWalletAddress()

  • Clears the stored wallet address.

  • Returns: Promise<void>

Usage Example

import { WalletBundleController } from '@tmawallet/sdk';
import { TelegramCloudStorage } from '@tmawallet/sdk';

(async () => {
  const storage = new TelegramCloudStorage();
  const walletBundleController = new WalletBundleController(storage);

  await walletBundleController.storeWalletAddress('0xYourWalletAddress');
  console.log('Stored Wallet Address:', await walletBundleController.getWalletAddress());

  await walletBundleController.clearWalletAddress();
  console.log('Wallet Address Cleared');
})();

Utilities

hmacSha256(message: string, secret: string)

• Generates an HMAC SHA-256 hash.

• Parameters:

  • message (string): The message to hash.

  • secret (string): The secret key for the hash.

• Returns: Promise<string>

Usage Example

import { hmacSha256 } from '@tmawallet/sdk';

(async () => {
  const hash = await hmacSha256('message_to_hash', 'secret_key');
  console.log('HMAC SHA-256 Hash:', hash);
})();

simpleHash(message: string)

• Generates a simple SHA-256 hash of a message.

• Parameters:

  • message (string): The message to hash.

• Returns: Promise<string>

Usage Example

import { simpleHash } from '@tmawallet/sdk';

(async () => {
  const hash = await simpleHash('message_to_hash');
  console.log('SHA-256 Hash:', hash);
})();

TelegramCloudStorage

• setItem(key: string, value: string)

  • Stores a key-value pair in Telegram's cloud storage.

  • Parameters:

    • key (string): The key to store.

    • value (string): The value to store.

  • Returns: Promise<void>

• getItem(key: string)

  • Retrieves the value associated with the given key from Telegram's cloud storage.

  • Parameters:

    • key (string): The key to retrieve.

  • Returns: Promise<string>

• removeItem(key: string)

  • Removes the key-value pair from Telegram's cloud storage.

  • Parameters:

    • key (string): The key to remove.

  • Returns: Promise<void>

• getKeys()

  • Retrieves all the keys stored in Telegram's cloud storage.

  • Returns: Promise<string[]>

• setItems(items: { [key: string]: string })

  • Stores multiple key-value pairs in Telegram's cloud storage.

  • Parameters:

    • items (object): An object containing key-value pairs to store.

  • Returns: Promise<void>

• removeItems(keys: string[])

  • Removes multiple key-value pairs from Telegram's cloud storage.

  • Parameters:

    • keys (string[]): An array of keys to remove.

  • Returns: Promise<void>

Usage Example

import { TelegramCloudStorage } from '@tmawallet/sdk';

(async () => {
  const storage = new TelegramCloudStorage();

  await storage.setItem('key1', 'value1');
  console.log('Stored Value:', await storage.getItem('key1'));

  await storage.removeItem('key1');
  console.log('Keys after removal:', await storage.getKeys());
})();

Authentication Flow

The authentication process for TMAWallet ensures that the interaction between the SDK and the Telegram mini-app environment is secure and user-friendly.

1. Initialization: The TMAWalletClient is initialized with a public token that uniquely identifies your project.

2. Telegram Session Data: During initialization, the SDK uses Telegram-provided session data to authenticate the user. This ensures that only authorized Telegram users can interact with their respective wallets.

3. Wallet Creation or Restoration: Depending on whether a wallet bundle already exists, the SDK either creates a new wallet bundle or restores the existing one. This authentication flow guarantees that wallet data remains tied to the specific Telegram user and is securely managed.

Authentication Flow Diagram

graph TD;
  A[Initialize TMAWalletClient] --> B[Verify Public Token];
  B --> C[Fetch Telegram Session Data];
  C --> D{Is Wallet Bundle Available?};
  D -- Yes --> E[Restore Wallet Bundle];
  D -- No --> F[Create New Wallet Bundle];
  E --> G[User Authenticated];
  F --> G[User Authenticated];

Data Flow Diagram

The data flow within TMAWallet involves interactions between different controllers, Telegram's cloud storage, and the Ethereum blockchain. The following diagram outlines the flow of data between the core components.

graph TD;
  A[TMAWalletClient] --> B[ClientBundleController];
  A --> C[WalletBundleController];
  B --> D[TelegramCloudStorage];
  C --> D;
  A --> E[Ethereum Blockchain];
  D --> F[User Data Storage];
  E --> G[Transaction Signing and Smart Contract Interaction];