> For the complete documentation index, see [llms.txt](https://tmawallet.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tmawallet.gitbook.io/docs/api-reference.md).

# 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**

```javascript
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**

```javascript
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**

```javascript
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**

```javascript
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**

```javascript
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**

```javascript
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**

```mermaid
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.

```mermaid
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];
```