SDK#

安装SDK#

可以通过cdn或者npm安装SDK

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

<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事件

事件名称	触发时机
OKX_TON_CONNECTION_STARTED	当用户开始连接钱包时
OKX_TON_CONNECTION_COMPLETED	当用户成功连接钱包时
OKX_TON_CONNECTION_ERROR	当用户取消连接或连接过程中出现错误时
OKX_TON_CONNECTION_RESTORING_STARTED	当 dApp 开始恢复连接时
OKX_TON_CONNECTION_RESTORING_COMPLETED	当 dApp 成功恢复连接时
OKX_TON_CONNECTION_RESTORING_ERROR	当 dApp 无法恢复连接时
OKX_TON_DISCONNECTION	当用户开始断开钱包连接时
OKX_TON_TRANSACTION_SENT_FOR_SIGNATURE	当用户发送交易以供签名时
OKX_TON_TRANSACTION_SIGNED	当用户成功签署交易时
OKX_TON_TRANSACTION_SIGNING_FAILED	当用户取消交易签名或签名过程中出现错误时

示例

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()

错误码#

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

异常

错误码	描述
OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR	未知异常
OKX_CONNECT_ERROR_CODES.ALREADY_CONNECTED_ERROR	钱包已连接
OKX_CONNECT_ERROR_CODES.NOT_CONNECTED_ERROR	钱包未连接
OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR	用户拒绝
OKX_CONNECT_ERROR_CODES.METHOD_NOT_SUPPORTED	方法不支持

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,
}