Aptos

UKey Wallet Aptos Provider 用于在 Web 应用中连接 Aptos 账户、读取网络信息、签名消息和确认提交交易。页面中可通过 window.$ukey.aptos 访问。

ℹ️

UKey Wallet Aptos Provider 兼容 Petra 钱包接口和 Aptos Wallet Standard，可用于现有 Aptos DApp 的迁移或新项目接入。

---

快捷链接

• API 参考
• 连接钱包
• 交易
• 消息签名

---

找 Provider

// 检查 UKey Wallet Aptos provider
const provider = window.$ukey?.aptos;

if (!provider) {
  throw new Error("未检测到 UKey Wallet Aptos provider");
}

// 确认 provider 信息
console.log("识别到的 Provider:", provider.isUKey ? "UKey Wallet" : "未知");

---

快上手

连接账户

// 建立连接并读取账户信息
const requestResult = await provider.connect();

console.log({
  address: requestResult.address, // 当前账户地址
  publicKey: requestResult.publicKey, // 公钥内容
});

检查连接状态

const isConnected = await provider.isConnected();
console.log("连接结果:", isConnected);

断连

await provider.disconnect();

---

账户管理

读取当前账户

const account = await provider.account();

console.log({
  address: account.address,
  publicKey: account.publicKey,
});

读取网络信息

const network = await provider.network();

console.log({
  name: network.name, // 可能的值如 'mainnet'、'testnet'、'devnet'
  chainId: network.chainId, // 当前网络对应的链 ID
  url: network.url, // RPC 地址
});

看账户变化

provider.onAccountChange((newAccount) => {
  if (newAccount) {
    console.log("当前账户已切换为:", newAccount.address);
  } else {
    console.log("钱包会话已断开");
  }
});

监听网络变化

provider.onNetworkChange((network) => {
  console.log("网络已切换为:", network.name);
});

---

交易项

签名并确认提交交易

// 简单 APT 转账参考
const payload = {
  type: "entry_function_payload",
  function: "0x1::aptos_account::transfer",
  type_arguments: [],
  arguments: [
    "0xdemo_receiver...", // 接收方地址
    "100000000", // 金额参考值，单位 Octas（1 APT = 100000000 Octas）
  ],
};

const requestResult = await provider.signAndSubmitTransaction(payload);

console.log("交易哈希值:", requestResult.hash);

仅签名不确认提交

const payload = {
  type: "entry_function_payload",
  function: "0x1::coin::transfer",
  type_arguments: ["0x1::aptos_coin::AptosCoin"],
  arguments: ["0xdemo_receiver...", "100000000"],
};

const signedTxn = await provider.signTransaction(payload);

// 稍后再通过 Aptos SDK 确认提交
// 例如：const pendingTxn = await client.submitTransaction(signedTxn)

签名交易 V2（BCS 序列化）

用于已经构造好 BCS 序列化交易的高级场景：

import { BCS } from 'aptos'

const rawTransaction = /* BCS 序列化的原始交易 */

const signedTxn = await provider.signTransactionV2(rawTransaction)

交易选项

const payload = {
  type: "entry_function_payload",
  function: "0x1::aptos_account::transfer",
  type_arguments: [],
  arguments: ["0xdemo_receiver...", "100000000"],
};

const options = {
  max_gas_amount: "10000",
  gas_unit_price: "100",
  expiration_timestamp_secs: Math.floor(Date.now() / 1000) + 600, // 10 分钟
};

const requestResult = await provider.signAndSubmitTransaction(payload, options);

---

消息签署

签消息

消息签名适合登录认证、地址所有权证明和链下授权。建议加入 nonce 防止重放：

const message = "Welcome to MyApp!\n\nClick to sign in.\n\nNonce: demo-nonce-001";

const requestResult = await provider.signMessage({
  message,
  nonce: "demo-nonce-001", // 可选 nonce，用于防重放
});

console.log({
  signature: requestResult.signature, // 十六进制形式的签名
  fullMessage: requestResult.fullMessage, // 完整签名消息
  kaspa: requestResult.kaspa, // 本次签名使用的消息前缀
});

验证消息（链下）

import nacl from "tweetnacl";

const { signature, fullMessage } = await provider.signMessage({
  message: "Aptos sample message",
  nonce: "demo-nonce-value",
});

const account = await provider.account();
const pubKeyBytes = Buffer.from(account.publicKey.slice(2), "hex");
const signatureBytes = Buffer.from(signature.slice(2), "hex");
const messageBytes = Buffer.from(fullMessage);

const isValid = nacl.sign.detached.verify(
  messageBytes,
  signatureBytes,
  pubKeyBytes,
);
console.log("签名校验结果:", isValid);

---

智能合约交互

调用 View 函数

// View 方法调用不需要签名
const callResult = await client.view({
  function: "0x1::coin::balance",
  type_arguments: ["0x1::aptos_coin::AptosCoin"],
  arguments: [accountAddress],
});

console.log("当前余额:", callResult[0]);

调用 Entry 函数

// NFT 铸造参考
const payload = {
  type: "entry_function_payload",
  function: "0x3::token::create_collection_script",
  type_arguments: [],
  arguments: [
    "Demo Collection", // 集合名称
    "Demo description", // 描述
    "https://demo.example", // 资源 URI
    "1000", // 最大可发行量
    [false, false, false], // 字段可变配置
  ],
};

const requestResult = await provider.signAndSubmitTransaction(payload);

---

API说明

方法集

方法	说明
connect()	连接钱包并获取账户
disconnect()	断开钱包连接
isConnected()	核验连接状态
account()	获取当前账户信息
network()	获取当前网络信息
signMessage(request)	签名任意消息
signAndSubmitTransaction(payload, options?)	签名并提交交易
signTransaction(payload, options?)	签名交易（不确认提交）
signTransactionV2(rawTransaction)	签名 BCS 序列化的交易
onAccountChange(callback)	订阅账户变化
onNetworkChange(callback)	订阅网络变化

类型集

interface AptosAccount {
  address: string; // 地址按 0x 开头的 hex 形式给出
  publicKey: string; // Ed25519 格式公钥
}

interface AptosNetwork {
  name: string; // 网络标识名
  chainId: string; // 链标识
  url: string; // RPC 地址
}

interface SignMessageRequest {
  message: string; // 需要签名的消息内容
  nonce?: string; // 可选 nonce
  address?: boolean; // 是否把地址带入消息
  application?: boolean; // 是否附带应用信息
  chainId?: boolean; // 是否附带链 ID
}

interface SignMessageResponse {
  signature: string; // hex 形式的签名
  fullMessage: string; // 完整签名消息
  kaspa: string; // APTOS 前缀
  address?: string; // 签名发起地址
  application?: string; // 应用描述信息
  chainId?: number; // 链标识
  nonce: string; // 本次使用的 nonce
}

interface TransactionPayload {
  type: "entry_function_payload" | "script_payload" | "module_bundle_payload";
  function: string; // Module::function 形式
  type_arguments: string[];
  arguments: any[];
}

支持的网络

网络	说明
主网	主网
测试网	测试网
Devnet	开发网

---

处理异常

try {
  await provider.connect();
} catch (error) {
  switch (error.code) {
    case 4001:
      console.log("用户已拒绝本次请求");
      break;
    case 4100:
      console.log("尚未授权，且钱包处于锁定状态");
      break;
    case 4200:
      console.log("当前方法不受支持");
      break;
    default:
      console.error("执行报错:", error.message);
  }
}

常见错误码

错误码	说明
4001	用户取消了本次请求
4100	尚未完成授权
4200	当前方法不可用
4201	当前网络暂不支持
-32603	内部处理异常

---

使用 Aptos Wallet Adapter

React 项目可以使用 Aptos Wallet Adapter。UKey Wallet 会通过 Wallet Standard 出现在可选钱包列表中：

npm install @aptos-labs/wallet-adapter-react

import { AptosWalletAdapterProvider } from "@aptos-labs/wallet-adapter-react";

function AptosProviderShell() {
  return (
    <AptosWalletAdapterProvider>
      <YourApp />
    </AptosWalletAdapterProvider>
  );
}

UKey Wallet 会被 Aptos Wallet Adapter 自动检测到。

---

从 Petra 迁移

UKey Wallet Aptos Provider 与 Petra 接口兼容。迁移时优先读取 UKey Wallet，未安装时再回退到 Petra：

// 旧写法（仅 Petra）
const petraProvider = window.petra;

// 调整后（UKey Wallet 优先，Petra 回退）
const aptosProvider = window.$ukey?.aptos || petraProvider;