1.4.2 • Published 9 months ago

@okxconnect/tonsdk v1.4.2

Weekly downloads
-
License
MIT
Repository
-
Last release
9 months ago

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

事件名称触发时机
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方法不支持
OKX_CONNECT_ERROR_CODES.CHAIN_NOT_SUPPORTED链不支持
OKX_CONNECT_ERROR_CODES.WALLET_NOT_SUPPORTED钱包不支持
OKX_CONNECT_ERROR_CODES.CONNECTION_ERROR连接异常
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
}
1.4.2

9 months ago

1.3.7

9 months ago

1.3.9

9 months ago

1.3.8

9 months ago

1.3.6

9 months ago

1.3.2

9 months ago

0.3.0-beta.7

9 months ago

0.4.0-beta.1

9 months ago

0.4.0-beta.2

9 months ago

1.3.0

9 months ago

1.2.8

9 months ago

1.2.0

10 months ago

1.1.1

10 months ago

1.2.7

9 months ago

1.2.6

9 months ago

1.2.5

9 months ago

1.1.6

10 months ago

1.2.3

10 months ago

1.2.2

10 months ago

1.2.1

10 months ago

1.1.2

10 months ago

0.1.0

10 months ago

1.1.0

10 months ago

1.0.6

10 months ago

1.0.5

10 months ago

1.0.4

10 months ago

1.0.3

10 months ago

1.0.1

10 months ago

1.0.0

10 months ago