@okxconnect/tonsdk v1.4.2

#SDK

安装SDK

可以通过cdn或者npm安装SDK

通过cdn安装 将如下代码添加到HTML文件中，也可以将latest替换为特定的版本号例如1.2.5。

<script src="https://unpkg.com/@okxconnect/tonsdk@latest/dist/okxconnect_tonsdk.min.js"></script>

引入后，OKXTonConnectSDK会作为全局对象可以直接引用

<script> const connector = new OKXTonConnectSDK.OKXTonConnect(); </script>

通过npm安装

npm install @okxconnect/tonsdk

初始化

连接钱包之前，需要先创建一个对象，用于后续连接钱包、发送交易等操作。

new OKXTonConnect({metaData: {name, icon}})

请求参数

• metaData - object
  • name - string: 应用名称，不会作为唯一表示
  • icon - string: 应用图标的 URL。必须是 PNG、ICO 等格式，不支持 SVG 图标。最好传递指向 180x180px PNG 图标的 url。

返回值

• okxTonConnect - OKXTonConnect

示例

import { OKXTonConnect } from "@okxconnect/tonsdk";

const okxTonConnect = new OKXTonConnect({
    metaData: {
        name: "application name",
        icon: "application icon url"
    }
});

连接钱包

连接钱包去获取钱包地址，作为标识符和用于签名交易的必要参数。

connect(request): Promise<string>;

请求参数

• request - object (可选)
  • tonProof - string (可选) : 签名信息；
  • redirect - string (可选) : 处理完钱包事件，返回的app 所需要的deeplink，例如：在 Telegram 环境下，此字段需要传递 Telegram 的deeplink，当在钱包签名完成后，OKX App 会通过此deeplink 打开 Telegram 程序，非Telegram环境建议不设置；
  • openUniversalLink - boolean (可选) : 连接钱包时,是否通过 Universal link 唤起 OKX App 客户端；设置为 true 的情况下，用户发起连接钱包时，会拉起 OKX App 客户端，并弹出确认页面，如果手机未安装 OKX App 客户端，跳转到下载页；

返回值

• Promise - string: PC 网页端可以根据该字段生成二维码，OKX App 客户端在 web3 中扫描生成的二维码，连接 DApp；

建议

• 在手机浏览器或者手机 Telegram 环境下设置 openUniversalLink 为 true；
• 在 PC 浏览器环境下设置 openUniversalLink 为 false，并根据返回的 universalLink 生成二维码，可以用 OKX App 客户端扫码连接，在连接成功后，取消二维码弹窗；

示例

import { OKXConnectError } from "@okxconnect/tonsdk";

try {
    okxTonConnect.connect({
        tonProof: "signmessage",
        redirect: "tg://resolve",
        openUniversalLink: true
    })
} catch (error) {
    if (error instanceof OKXConnectError) {
        if (error.code === OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR) {
            alert('User reject');
        } else if (error.code === OKX_CONNECT_ERROR_CODES.ALREADY_CONNECTED_ERROR) {
            alert('Already connected');
        } else {
            alert('Unknown error happened');
        }
    } else {
        alert('Unknown error happened');
    }
}

恢复连接

如果用户之前连接过钱包，在再次进入或页面刷新时可调用此方法，用来恢复之前的连接状态。

restoreConnection(): Promise<void>

请求参数

无

返回值

无

示例

okxTonConnect.restoreConnection()

断开连接

断开已连接钱包，并删除当前会话，如果要切换连接钱包，请先断开当前钱包。

示例

import { OKX_CONNECT_ERROR_CODES } from "@okxconnect/tonsdk";

try {
    await okxTonConnect.disconnect()
} catch (error) {
    if (error instanceof OKXConnectError) {
        switch (error.code) {
            case OKX_CONNECT_ERROR_CODES.NOT_CONNECTED_ERROR:
                alert('Not connected');
                break;
            default:
                alert('Unknown error happened');
                break;
        }
    } else {
        alert('Unknown error happened');
    }
}

判断当前是否连接

获取当前是否有连接钱包

示例

var connect: boolean = okxTonConnect.connected()

发送交易

向钱包发送消息的方法：

sendTransaction(transaction, options): Promise<SendTransactionResponse>

请求参数

• transaction - object
  • validUntil - number :unix 时间戳。该时刻之后交易将无效
  • from - string (可选): DApp发送交易的发送者地址，默认为当前连接的钱包地址；
  • messages - object[] : (信息数组）： 1-4 条从钱包合约到其他账户的输出消息。所有消息按顺序发送出去，但 钱包无法保证消息会按相同顺序被传递和执行。
    • address - string : 消息目的地
    • amount - string : 要发送的数量。
    • stateInit - string (可选) : 以 Base64 编码的原始cell BoC。
    • payload - string (可选): 以 Base64 编码的原始cell BoC。
• options - object
  • onRequestSent - () => void : 当签名请求发送后，该方法会被调用；

返回值

• Promise - {boc: string}: 签名结果

示例

import { OKXConnectError } from "@okxconnect/tonsdk";

let transactionRequest = {
    "validUntil": Date.now() / 1000 + 360,
    "from": "0:348bcf827469c5fc38541c77fdd91d4e347eac200f6f2d9fd62dc08885f0415f",
    "messages": [
        {
            "address": "0:412410771DA82CBA306A55FA9E0D43C9D245E38133CB58F1457DFB8D5CD8892F",
            "amount": "20000000",
            "stateInit": "base64bocblahblahblah==" //deploy contract
        }, {
            "address": "0:E69F10CC84877ABF539F83F879291E5CA169451BA7BCE91A37A5CED3AB8080D3",
            "amount": "60000000",
            "payload": "base64bocblahblahblah==" //transfer nft to new deployed account 0:412410771DA82CBA306A55FA9E0D43C9D245E38133CB58F1457DFB8D5CD8892F
        }
    ]
}

let requestOptions = {
    onRequestSent: () => {
        //requestMsgSend
    }
}
try {
    const result = await okxTonConnect.sendTransaction(transactionRequest, requestOptions);
} catch (error) {
    if (error instanceof OKXConnectError) {
        switch (error.code) {
            case OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR:
                alert('You rejected the transaction.');
                break;
            case OKX_CONNECT_ERROR_CODES.NOT_CONNECTED_ERROR:
                alert('Not connected');
                break;
            default:
                alert('Unknown error happened');
                break;
        }
    } else {
        alert('Unknown error happened');
    }
}

监听钱包状态变化

钱包状态有：连接成功、恢复连接成功、断开连接等，都可以用此方法获取状态。

onStatusChange( callback: (walletInfo) => void, errorsHandler?: (err) => void ): () => void;

请求参数

• callback - (walletInfo) => void : 钱包状态发生变化时候，该callback 会被调用；

  • walletinfo - object
    • device - object
      • appName - string : 钱包名称
      • platform - string : 钱包的平台，（android,ios）
      • appVersion - string : 钱包版本号
      • maxProtocolVersion - number :
      • features - string[] : 支持的方法，当前版本是 sendTransaction
    • account - Account
      • address - string : TON address raw (0:<hex>)
      • chain - "-239"
      • walletStateInit - string : Base64 (not url safe) encoded stateinit cell for the wallet contract
      • publicKey - string : HEX string without 0x
    • connectItems - object
      • name - string : "ton_proof"
      • proof - object
        • timestamp - number : 时间戳
        • domain - object
          • lengthBytes - number : AppDomain Length
          • value - string : app domain name (as url part, without encoding)
        • payload - string: Base64-encoded signature
        • signature - string: payload from the request

• errorsHandler - (err: OKXConnectError) => void : 钱包状态发生变化出现异常的时候，该errorsHandler 会被调用；

  • err - TonConnectError
    • code - number
    • message - string

返回值

• () => void : 当不再需要监听更新时，执行该方法以节省资源。

示例

import { Wallet } from "@okxconnect/tonsdk";

const unsubscribe = okxTonConnect.onStatusChange((walletInfo: Wallet | null) => {
        console.log('Connection status:', walletInfo);
    }, (err: OKXConnectError) => {
        console.log('Connection status:', err);
    }
)

当不再需要监听更新时，调用unsubscribe节省资源。

unsubscribe()

监听事件

在以下事件发生时，会发送对应事件通知，Dapp可以根据需要添加监听，来处理对应的逻辑；

event事件

示例

import { OKX_TON_CONNECTION_AND_TRANSACTION_EVENT } from "@okxconnect/tonsdk";

window.addEventListener(OKX_TON_CONNECTION_AND_TRANSACTION_EVENT.OKX_TON_CONNECTION_STARTED, (event) => {
    if (event instanceof CustomEvent) {
        console.log('Transaction init', event.detail);
    }
});

获取账户信息

获取当前连接的 account

示例

import { Account } from "@okxconnect/tonsdk";

var connect: Account = okxTonConnect.account()

获取钱包信息

获取当前连接的 wallet

示例

import { Wallet } from "@okxconnect/tonsdk";

var connect: Wallet = okxTonConnect.wallet()

错误码

在连接，交易，恢复连接，断开连接的过程中可能抛出的异常;

异常

export enum OKX_CONNECT_ERROR_CODES {
    UNKNOWN_ERROR = 0,
    ALREADY_CONNECTED_ERROR = 11,
    NOT_CONNECTED_ERROR = 12,
    USER_REJECTS_ERROR = 300,
    METHOD_NOT_SUPPORTED = 400,
    CHAIN_NOT_SUPPORTED = 500,
    WALLET_NOT_SUPPORTED = 600,
    CONNECTION_ERROR = 700
}