Vly Wallet Popup SDK

一个用于与 Vly 钱包进行交互的 JavaScript/TypeScript SDK，支持弹窗式钱包连接和自动登录功能。

✨ 功能特性

• 🔐 双重登录模式：支持用户手动确认登录和基于签名的自动登录
• 🚀 自动化集成：无缝对接 Web2 系统，实现真正的自动化登录
• 💰 完整功能：支持余额查询、支付、奖励领取等完整钱包功能
• 🛡️ 安全可靠：基于签名验证的安全机制
• 📱 跨平台：支持各种现代浏览器和移动设备

📦 安装

npm install @vlymoney/vly-wallet-popup

🚀 快速开始

基础用法

import { WalletSDK } from "@vlymoney/vly-wallet-popup";

// 创建钱包实例
const wallet = WalletSDK.getInstance({
  walletHost: "https://pop.onta-merchant.zkid.xyz",
  walletPath: "#/connect",
  defaultTimeout: 60000,
});

// 传统登录方式（需要用户手动确认）
const result = await wallet.loginWithX({
  message: "请确认登录钱包",
});

console.log("登录结果:", result);

🆕 自动登录功能

// 使用签名信息自动登录（无需用户手动确认）
const autoLoginResult = await wallet.loginWithSign({
  username: "user123",
  sig: "generated_signature_string",
  timestamp: "1641234567890",
  displayName: "用户显示名称", // 可选
});

console.log("自动登录结果:", autoLoginResult);

🔗 与 Web2 系统集成

// 完整的 Web2 集成示例
class Web2WalletIntegration {
  constructor() {
    this.wallet = WalletSDK.getInstance({
      walletHost: "https://pop.onta-merchant.zkid.xyz",
      walletPath: "#/connect",
    });
  }

  // 基于服务端签名的自动登录
  async autoLoginWithServerAuth(userToken) {
    try {
      // 1. 从服务端获取签名
      const signatureData = await this.getServerSignature(userToken);

      // 2. 使用签名自动登录钱包
      const walletResult = await this.wallet.loginWithSign({
        username: signatureData.username,
        sig: signatureData.signature,
        timestamp: signatureData.timestamp,
        displayName: signatureData.displayName,
      });

      // 3. 登录成功，获取钱包信息
      console.log("钱包账户:", walletResult.address);
      return walletResult;
    } catch (error) {
      console.error("自动登录失败:", error);
      throw error;
    }
  }

  async getServerSignature(userToken) {
    const response = await fetch("/api/wallet/generate-signature", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${userToken}`,
        "Content-Type": "application/json",
      },
    });

    if (!response.ok) {
      throw new Error("获取签名失败");
    }

    return response.json();
  }
}

📚 API 参考

WalletSDK 类

getInstance(config?: WalletConfig): WalletSDK

创建或获取钱包 SDK 实例（单例模式）

参数：

• config.walletHost: 钱包服务地址
• config.walletPath: 钱包连接路径
• config.defaultTimeout: 默认超时时间（毫秒）

loginWithX(data?: Partial): Promise

传统登录方式，需要用户在弹窗中手动确认

🆕 loginWithSign(data: SignData): Promise

基于签名的自动登录，无需用户手动确认

参数：

interface SignData {
  username: string; // 用户名或用户ID
  sig: string; // 签名字符串
  timestamp: string; // 时间戳
  displayName?: string; // 可选的显示名称
}

getBalance(data?: Partial): Promise

查询钱包余额

pay(data?: Partial): Promise

发起支付请求

claimReward(data?: Partial): Promise

领取奖励

reset(): Promise

重置钱包连接状态

🎯 使用场景

1. 游戏平台集成

// 游戏登录后自动连接钱包
async function connectWalletAfterGameLogin(gameUser) {
  const wallet = WalletSDK.getInstance();

  // 使用游戏账户签名自动登录钱包
  const walletAccount = await wallet.loginWithSign({
    username: gameUser.id,
    sig: gameUser.walletSignature,
    timestamp: gameUser.signatureTimestamp,
    displayName: gameUser.nickname,
  });

  console.log(`${gameUser.nickname} 的钱包已连接:`, walletAccount.address);
}

2. 电商平台集成

// 支付流程中自动连接钱包
async function processPaymentWithWallet(order, userAuth) {
  const wallet = WalletSDK.getInstance();

  // 自动登录钱包
  await wallet.loginWithSign({
    username: userAuth.userId,
    sig: userAuth.walletSignature,
    timestamp: userAuth.timestamp,
  });

  // 发起支付
  const paymentResult = await wallet.pay({
    amount: order.total,
    recipient: order.merchantAddress,
    orderId: order.id,
  });

  return paymentResult;
}

3. DeFi 应用集成

// 自动连接钱包并查询余额
async function getDeFiPortfolio(userCredentials) {
  const wallet = WalletSDK.getInstance();

  // 自动登录
  await wallet.loginWithSign(userCredentials);

  // 查询余额
  const balance = await wallet.getBalance();

  return {
    address: balance.address,
    tokens: balance.tokens,
    nfts: balance.nfts,
  };
}

🔧 开发和调试

本地开发

# 克隆项目
git clone <repository-url>
cd vly-wallet-popup-onta

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建项目
npm run build

测试

项目包含完整的测试示例文件 test-example.html，可以直接在浏览器中打开进行功能测试。

调试技巧

1. 使用浏览器开发者工具监听 postMessage 事件
2. 检查钱包弹窗的网络请求
3. 查看控制台日志获取详细错误信息

🔒 安全注意事项

1. 签名安全：确保签名在服务端生成，客户端不要暴露签名生成逻辑
2. 时效性：建议为签名添加时效性检查，避免重放攻击
3. 权限控制：服务端应验证用户权限后再生成钱包签名
4. HTTPS：生产环境必须使用 HTTPS 传输签名数据

🆕 版本更新

v1.1.0 新功能

• ✨ 新增 loginWithSign 方法，支持基于签名的自动登录
• 🚀 实现真正的自动化钱包连接，无需用户手动确认
• 🔄 完全向后兼容，原有 API 保持不变
• 📖 完整的文档和示例

查看 CHANGELOG.md 了解详细更新内容。

🤝 贡献

欢迎提交 Issues 和 Pull Requests 来帮助改进这个项目。

📄 许可证

MIT License