TekWallet Documentation

📋 Mục lục

- Cấu hình
- Components
- States
- Methods
- Hướng dẫn sử dụng
- Lưu ý

---

⚙️ Cấu hình

$3

Để sử dụng TekWallet, bạn cần wrap ứng dụng của mình trong TekWalletProvider. Provider này yêu cầu một số cấu hình cơ bản:

``jsx
import "swiper/css";
import { TekWalletProvider, ThemeModes } from "tek-wallet";

// Cấu hình cơ bản
isSSO
accessToken={accessToken} // Token từ SSO
>

;
`

Cấu hình nâng cao:

`jsx
import { TekWalletProvider, ThemeModes } from "tek-wallet";

theme={theme} // Custom theme object
themeMode={ThemeModes.DARK} // Chế độ theme: DARK hoặc LIGHT
isSSO
accessToken={accessToken}
options={{
useDefaultToastMessage: true, // Sử dụng toast message mặc định
hideDefaultActivities: true, // Ẩn activities mặc định
hideActivitySectionInAssetView: true, // Ẩn section activities trong AssetView
useBasicAmountGroupInAssetView: true, // Sử dụng basic amount group trong AssetView
hideBackButtons: {
// Ẩn nút back trong các view cụ thể
activity: true,
},
disableRefetchOnFocus: true, // Vô hiệu hóa việc refetch dữ liệu khi focus lại vào cửa sổ
}}
topOffset={viewportStatusBarHeight || 0} // Offset từ top (thường dùng cho mobile)
onLogout={handleLogout} // Callback khi logout
overrideQRScanMethod={isMobileApp ? scanQRCode : undefined} // Override QR scan method
>
{children}
;
`

$3

Props cơ bản:

| Prop | Type | Required | Mô tả |
| ------------- | --------- | -------- | ----------------------------- |
| isSSO | boolean | ✅ | Bật chế độ SSO authentication |
| accessToken | string | ✅ | Token xác thực từ SSO |

Props nâng cao:

| Prop | Type | Required | Mô tả |
| ---------------------- | ------------ | -------- | ---------------------------------------------------- |
| theme | object | ❌ | Custom theme object |
| themeMode | ThemeModes | ❌ | Chế độ theme: DARK hoặc LIGHT |
| topOffset | number | ❌ | Offset từ top (thường dùng cho mobile status bar) |
| onLogout | function | ❌ | Callback function khi user logout |
| overrideQRScanMethod | function | ❌ | Override QR scan method (thường dùng cho mobile app) |

Options object:

| Option | Type | Default | Mô tả |
| -------------------------------- | --------- | ------- | --------------------------------------------------------- |
| useDefaultToastMessage | boolean | false | Sử dụng toast message mặc định của hệ thống |
| hideDefaultActivities | boolean | false | Ẩn activities mặc định |
| hideActivitySectionInAssetView | boolean | false | Ẩn section activities trong AssetView |
| useBasicAmountGroupInAssetView | boolean | false | Sử dụng basic amount group trong AssetView |
| hideBackButtons | object | {} | Ẩn nút back trong các view cụ thể |
| disableRefetchOnFocus | boolean | false | Vô hiệu hóa việc refetch dữ liệu khi focus lại vào cửa sổ |

hideBackButtons object:

| Property | Type | Mô tả |
| ---------- | --------- | ------------------------------- |
| activity | boolean | Ẩn nút back trong activity view |

$3

Các biến môi trường cần thiết:

`env
NEXT_PUBLIC_TEK_WALLET_APP_SLUG=your_app_slug
NEXT_PUBLIC_TEK_WALLET_SERVER_URL=your_server_url
NEXT_PUBLIC_TEK_WALLET_ABLY_API_KEY=your_ably_api_key
`

---

🧩 Components

$3

Component này được sử dụng để kiểm tra trạng thái kết nối ví trước khi thực hiện các hành động yêu cầu ví phải được kết nối.

`jsx
import { RequiredConnect, useWallet } from "tek-wallet";

const { tokens } = useWallet();


console.log(tokens)}>Log balances
;
`

$3

| Component | Mô tả |
| --------------------- | ------------------------------------------ |
| LockToken | Cho phép người dùng khóa token trong ví |
| SwapToken | Hỗ trợ chức năng hoán đổi token |
| UpdateLockedToken | Cho phép cập nhật thông tin token đã khóa |
| ReceiveFunction | Xử lý chức năng nhận token |
| ReceiveDirectly | Component nhận token trực tiếp qua QR code |
| AssetView | Hiển thị tài sản trong ví |
| WithdrawFunction | Xử lý chức năng rút token |

$3

| Component | Mô tả |
| ----------------------- | ---------------------------------------------------------------- |
| ConfirmSwapToken | Xử lý chức năng swap token bản đơn giản (khả năng custom cao) |
| ConfirmSendExternal | Xử lý chức năng rút token bản đơn giản (khả năng custom cao) |
| ConfirmSendInternal | Xử lý chức năng chuyển nội bộ bản đơn giản (khả năng custom cao) |

$3

| Component | Mô tả |
| -------------------- | ---------------------------------------------------------------------- |
| SwapView | Xử lý chức năng swap token bản đầy đủ, có validate, input amount... |
| SendExternalView | Xử lý chức năng rút token bản đầy đủ, có validate, input amount... |
| SendInternalView | Xử lý chức năng chuyển nội bộ bản đầy đủ, có validate, input amount... |
| AssetView | Quản lí asset người dùng |

$3

Component như một app wallet mini (có router nội bộ)

Sử dụng cơ bản:

`jsx
// page: "tek-wallet/[[...pathname]]/page.tsx"
"use client";

import { TekWalletView } from "tek-wallet";

function WalletPage() {
return ;
}

export default WalletPage;
`

Với basePath:

Nếu phía trước có path: /tek-wallet/[[...pathname]]/page.tsx thì thêm basePath vào options:

`jsx
isSSO
accessToken={accessToken}
options={{
useDefaultToastMessage: true,
basePath:
}}
>
{props.children}

`

Ví dụ cấu hình đầy đủ cho mobile app:

`jsx
import { TekWalletProvider, ThemeModes } from "tek-wallet";

function App() {
const handleLogout = () => {
// Xử lý logout logic
console.log("User logged out");
};

const scanQRCode = (callback) => {
// Custom QR scan implementation cho mobile
// Gọi native QR scanner
window.nativeQRScanner?.scan(callback);
};

return (
theme={customTheme}
themeMode={ThemeModes.DARK}
isSSO
accessToken={accessToken}
options={{
useDefaultToastMessage: true,
hideDefaultActivities: true,
hideActivitySectionInAssetView: true,
useBasicAmountGroupInAssetView: true,
hideBackButtons: {
activity: true,
},
}}
topOffset={viewportStatusBarHeight || 0}
onLogout={handleLogout}
overrideQRScanMethod={isMobileApp ? scanQRCode : undefined}
>


);
}
`

$3

Component cho phép hiển thị QR code và địa chỉ nhận token trực tiếp, hỗ trợ cả nhận nội bộ và nhận từ blockchain.

Props:

| Prop | Type | Required | Mô tả |
| ------------- | ----------------------- | -------- | ------------------------------------------------------------ |
| tokenSlug | string | ✅ | Slug của token muốn nhận |
| method | ReceiveDirectlyMethod | ✅ | Phương thức nhận: RECEIVE_INTERNAL hoặc RECEIVE_EXTERNAL |
| networkSlug | string | ❌ | Slug của network (bỏ qua nếu muốn cho user chọn network) |
| amount | string \| number | ❌ | Số lượng token muốn nhận (hiển thị trong QR code) |
| userInfo | object | ❌ | Thông tin người nhận để hiển thị |

Ref Methods:

| Method | Mô tả |
| ------- | ---------- |
| open | Mở modal |
| close | Đóng modal |

Enum ReceiveDirectlyMethod:

`typescript
enum ReceiveDirectlyMethod {
RECEIVE_INTERNAL = "Internal Transfer", // Nhận token nội bộ
RECEIVE_EXTERNAL = "Blockchain Deposit", // Nhận token từ blockchain
}
`

Ví dụ 1: Nhận token nội bộ (Internal Transfer)

`jsx
import { ReceiveDirectly, ReceiveDirectlyMethod } from "tek-wallet";
import { useRef } from "react";

function MyComponent() {
const receiveRef = useRef(null);

return (
<>
receiveRef.current?.open()}>Nhận USDT nội bộ

ref={receiveRef}
tokenSlug="usdt"
method={ReceiveDirectlyMethod.RECEIVE_INTERNAL}
amount={100}
userInfo={{
nickname: "John Doe",
username: "@johndoe",
avatar: "https://example.com/avatar.jpg",
}}
/>

);
}
`

Ví dụ 2: Nhận token từ blockchain (Blockchain Deposit)

`jsx
import { ReceiveDirectly, ReceiveDirectlyMethod } from "tek-wallet";
import { useRef } from "react";

function MyComponent() {
const receiveRef = useRef(null);

return (
<>
receiveRef.current?.open()}>Nhận USDT từ blockchain

{/ Cách 1: Chỉ định network cụ thể /}
ref={receiveRef}
tokenSlug="usdt"
method={ReceiveDirectlyMethod.RECEIVE_EXTERNAL}
networkSlug="trc20"
/>

{/ Cách 2: Cho phép user chọn network /}
ref={receiveRef}
tokenSlug="usdt"
method={ReceiveDirectlyMethod.RECEIVE_EXTERNAL}
// Không truyền networkSlug - user sẽ chọn network
/>

);
}
`

Ví dụ 3: Sử dụng với trigger children

`jsx

Click để nhận USDT

`

Lưu ý:

- 🔸 Khi sử dụng RECEIVE_INTERNAL, không cần truyền networkSlug
- 🔸 Khi sử dụng RECEIVE_EXTERNAL mà không truyền networkSlug, user sẽ được yêu cầu chọn network
- 🔸 Component tự động validate token và network, hiển thị lỗi nếu không hợp lệ
- 🔸 QR code được tạo tự động dựa trên method và các thông tin được truyền vào
- 🔸 Với Internal Transfer, QR code chứa thông tin JSON để xử lý chuyển khoản nội bộ
- 🔸 Với Blockchain Deposit, QR code chứa địa chỉ blockchain wallet

---

📊 States

$3

| State | Type | Description |
| ------------------- | ---------- | ------------------------------------- |
| tokens | Token[] | Danh sách tokens trong ví |
| isTokensLoading | boolean | Trạng thái đang tải danh sách tokens |
| masterWallet | string | Địa chỉ ví hệ thống |
| blockchainWallets | string[] | Mảng địa chỉ ví blockchain |
| isConnected | boolean | Trạng thái đã kết nối Ably (realtime) |

$3

| State | Type | Description |
| ------------------------------- | --------- | -------------------------------------------------------------- |
| isLoadingWithdrawToken | boolean | Trạng thái đang get list các token được phép withdraw |
| isLoadingSendInternalToken | boolean | Trạng thái đang get list các token được phép gửi nội bộ |
| isLoadingLockToken | boolean | Trạng thái đang get list các token được phép khóa |
| isLoadingLockedToken | boolean | Trạng thái đang get list các token đã khóa |
| isLoadingSwapToken | boolean | Trạng thái đang get list các token được phép swap |
| isLoadingReceiveExternalToken | boolean | Trạng thái đang get list các token được phép nhận từ bên ngoài |
| isLoadingReceiveInternalToken | boolean | Trạng thái đang get list các token được phép nhận nội bộ |

$3

| State | Type | Description |
| -------------- | --------------- | ----------------------------------------------------------- |
| lockedTokens | LockedToken[] | Danh sách tokens đã khóa |
| fromTokens | Token[] | Danh sách tokens có thể swap |
| transaction | Transaction | Dữ liệu event realtime mới nhất (swap token, send token...) |

---

🔧 Methods

$3

| Method | Description |
| ---------------------- | ---------------------------------------------------------------- |
| updateWalletDetail() | Cập nhật lại chi tiết ví, bao gồm địa chỉ ví và danh sách tokens |

$3

| Method | Description |
| ------------------------------ | -------------------------------------------------------- |
| updateWithdrawToken() | Cập nhật danh sách các token được phép withdraw |
| updateSendInternalToken() | Cập nhật danh sách các token được phép gửi nội bộ |
| updateLockToken() | Cập nhật danh sách các token được phép khóa |
| updateLockedToken() | Cập nhật danh sách các token đã khóa |
| updateSwapTokens() | Cập nhật danh sách các token được phép swap |
| updateReceiveExternalToken() | Cập nhật danh sách các token được phép nhận từ bên ngoài |
| updateReceiveInternalToken() | Cập nhật danh sách các token được phép nhận nội bộ |

$3

| Method | Description |
| -------------------------------- | ------------------------------------ |
| validateWalletAddressService() | Validate địa chỉ ví nội bộ / Onchain |

$3

| Method | Description |
| -------------------- | ---------------------- |
| pushNotification() | Hiển thị toast message |

---

🚀 Hướng dẫn sử dụng

Để bắt đầu sử dụng TekWallet, hãy đảm bảo:

1. ✅ Đã cài đặt đầy đủ các dependencies cần thiết
2. ✅ Đã cấu hình đúng các biến môi trường
3. ✅ Đã wrap ứng dụng trong TekWalletProvider
4. ✅ Đã import các components cần thiết từ package

---

⚠️ Lưu ý

- 🔒 Đảm bảo luôn sử dụng RequiredConnect` cho các hành động yêu cầu ví phải được kết nối
- 🔧 Các biến môi trường phải được cấu hình đúng để đảm bảo ứng dụng hoạt động chính xác

---

tek-wallet

##