@binance/w3w-multichain-connector 1.0.16 → 1.0.18

package/README.md

@@ -1,6 +1,6 @@
 # @binance/w3w-multichain-connector
 
-The `@binance/w3w-multichain-connector` package provides a wrapper for the `Binance Wallet` extension multichain connector
+The `@binance/w3w-multichain-connector` package provides a wrapper for the `Binance Wallet` extension multichain connector.
 
 ## Installation
 
@@ -18,27 +18,228 @@ npm install @binance/w3w-multichain-connector
 import { getMultichainWallet } from '@binance/w3w-multichain-connector'
 ```
 
-### Call methods
+### Get Wallet Instance
 
 ```ts
 const wallet = getMultichainWallet()
+if (!wallet) {
+  console.log('Binance Wallet extension not installed')
+}
+```
+
+### Check Extension Installed
+
+```ts
+import { checkExtensionInstalled } from '@binance/w3w-multichain-connector'
+
+const isInstalled = checkExtensionInstalled()
+```
+
+### Check Extension Feature Support
+
+```ts
+import { checkExtensionSupported, Features } from '@binance/w3w-multichain-connector'
+
+const isSupported = checkExtensionSupported(Features.requestConnect)
+```
+
+### Connect Wallet
+
+```ts
 const connectedWallets = await wallet.requestConnect(['56', 'CT_501'])
 ```
 
-### Handle events
+### Connect with SAS
+
+```ts
+// Single wallet SAS
+const { wallet: connectedWallet, aggreeEnableSAS } = await wallet.requestConnectWithSAS({
+  binanceChainIds: ['56'],
+  userId: 'user-id',
+  enabledWalletInfo: [
+    { walletType: 'SEED_PHRASE', chain: 'evm', userPublicKeyHex: '0x...' }
+  ]
+})
+
+// Multi wallet SAS
+const { walletList, enabledWalletIds } = await wallet.requestConnectWithMultiWalletSAS({
+  binanceChainIds: ['56'],
+  userId: 'user-id'
+})
+```
+
+### Check Connected Wallets
+
+```ts
+const wallets = await wallet.checkConnectedWallet()
+// The user's active wallet will be the first element in the array
+```
+
+### Get Wallet Info
+
+```ts
+const walletInfo = await wallet.getWalletInfo('0x...address', '56')
+```
+
+### Switch Chain
+
+```ts
+await wallet.switchChain('56')
+```
+
+### Disconnect
+
+```ts
+await wallet.disconnect()
+```
+
+### Sign Order
+
+```ts
+const signature = await wallet.signOrder({
+  walletId: 'wallet-id',
+  walletAddress: '0x...',
+  binanceChainId: '56',
+  txData: '...',
+  feeAmount: '0.001',
+  feeAmountLevel: 'Medium', // 'Low' | 'Medium' | 'High' | 'Custom'
+  digest: '...',
+  digestSign: '...'
+})
+```
+
+### Auto Sign
+
+```ts
+await wallet.requestAutoSign()
+console.log('Auto sign enabled:', wallet.autoSignEnabled)
+```
+
+### SAS Operations
+
+```ts
+// Enable SAS
+const { aggreeEnableSAS } = await wallet.requestEnableSAS({
+  walletId: 'wallet-id',
+  userId: 'user-id',
+  userEmail: 'user@example.com'
+})
+
+// Enable multi-wallet SAS
+const { enabledWalletIds } = await wallet.requestEnableMultiWalletSAS({
+  walletIds: ['wallet-1', 'wallet-2'],
+  userId: 'user-id',
+  userEmail: 'user@example.com'
+})
+
+// Get SAS Keyshare
+const keyshares = await wallet.getSASKeyshare({
+  walletIds: ['wallet-id'],
+  userId: 'user-id',
+  spsVersion: '1.0',
+  isSilent: false // if true, won't prompt unlock when wallet is locked
+})
+
+// Sync SAS Status
+await wallet.syncSASStatus({
+  userId: 'user-id',
+  statusList: [
+    { walletId: 'wallet-id', enabled: true }
+  ]
+})
+
+// Get ProofKey Signature (before placing order)
+const { timeStamp, proofKeyPublicKey, timestampSignature } = await wallet.getSASProofKeySignature({
+  walletId: 'wallet-id',
+  userId: 'user-id'
+})
+
+// Get Connected Wallets with ProofKey
+const walletsWithProofKey = await wallet.getConnectedWalletAndProofKey({
+  userId: 'user-id'
+})
+```
+
+### Handle Events
 
 ```ts
 const wallet = getMultichainWallet()
+
+// Wallet lock status changed
 wallet.on('walletLockedChanged', (isLocked) => {
-  console.log('Wallet is locked', isLocked)
+  console.log('Wallet locked:', isLocked)
+})
+
+// Auto sign status changed
+wallet.on('autoSignEnabledChanged', (isEnabled) => {
+  console.log('Auto sign enabled:', isEnabled)
+})
+
+// Connected wallets changed
+wallet.on('connectedWalletsChanged', (connectedWallets) => {
+  console.log('Connected wallets:', connectedWallets)
+})
+
+// Connected chain changed
+wallet.on('connectedChainIdChanged', (binanceChainId) => {
+  console.log('Chain changed:', binanceChainId)
 })
 ```
 
-### Check extension support features
+### Properties
 
-```ts
-import { checkExtensionSupported, Features } from '@binance/w3w-multichain-connector'
+| Property | Type | Description |
+|---|---|---|
+| `version` | `string` | Current extension version |
+| `autoSignEnabled` | `boolean` | Whether auto sign is enabled |
+| `walletLocked` | `boolean` | Whether the wallet is locked |
+| `extensionId` | `string` | Extension unique identifier |
 
-const isSupported = checkExtensionSupported(Features.requestConnect)
+## Types
+
+### `IConnectedWallet`
+
+| Field | Type | Description |
+|---|---|---|
+| `walletIcon` | `string` | Wallet icon (base64) |
+| `walletName` | `string` | Wallet name |
+| `walletId` | `string` | Wallet unique identifier |
+| `walletType` | `WalletType` | Wallet type (privateKey / seedPhrase) |
+| `addressList` | `Array<{ address, binanceChainId, publicKeyHex }>` | Wallet address list |
+| `groupID?` | `string` | Wallet group ID |
+| `groupName?` | `string` | Wallet group name |
+
+### `WalletType`
+
+| Value | Description |
+|---|---|
+| `privateKey` | Private key wallet |
+| `seedPhrase` (`hd`) | Seed phrase (mnemonic) wallet |
+
+### `Features`
 
-```
+| Value | Description |
+|---|---|
+| **Connect** | |
+| `requestConnect` | Connect wallet |
+| `requestConnectWithSAS` | Connect wallet with single-wallet SAS |
+| `requestConnectWithMultiWalletSAS` | Connect wallet with multi-wallet SAS |
+| `checkConnectedWallet` | Check connected wallets |
+| `getWalletInfo` | Get wallet info by address and chain |
+| `disconnect` | Disconnect all wallets |
+| `switchChain` | Switch chain |
+| **SAS** | |
+| `requestEnableSAS` | Request enable SAS (single wallet) |
+| `requestEnableMultiWalletSAS` | Request enable SAS (multi wallet) |
+| `getSASKeyshare` | Get SAS keyshare |
+| `syncSASStatus` | Sync SAS status |
+| `getConnectedWalletAndProofKey` | Get connected wallets with ProofKey |
+| `getSASProofKeySignature` | Get ProofKey signature before placing order |
+| **Signing** | |
+| `requestAutoSign` | Request auto sign |
+| `signOrder` | Sign transaction order |
+| **Events** | |
+| `eventWalletLockedChanged` | Wallet lock status changed event |
+| `eventAutoSignEnabledChanged` | Auto sign status changed event |
+| `eventConnectedWalletsChanged` | Connected wallets changed event |
+| `eventConnectedChainIdChanged` | Connected chain changed event |

package/dist/index.d.ts

@@ -12,62 +12,151 @@ declare enum WalletType {
     privateKey = "privateKey",
     seedPhrase = "hd"
 }
+/**
+ * 插件支持的功能特性枚举，用于 checkExtensionSupported 检测
+ */
 declare enum Features {
+    /** 请求连接钱包 */
     requestConnect = "requestConnect",
+    /** 连接钱包并发起单钱包SAS请求 */
+    requestConnectWithSAS = "requestConnectWithSAS",
+    /** 连接钱包并发起多钱包SAS请求 */
+    requestConnectWithMultiWalletSAS = "requestConnectWithMultiWalletSAS",
+    /** 检查当前已连接的钱包 */
     checkConnectedWallet = "checkConnectedWallet",
+    /** 根据地址和链ID获取钱包信息 */
+    getWalletInfo = "getWalletInfo",
+    /** 断开所有已连接的钱包 */
     disconnect = "disconnect",
+    /** 切换网络 */
     switchChain = "switchChain",
+    /** 弹出开启SAS的请求弹窗（单钱包） */
+    requestEnableSAS = "requestEnableSAS",
+    /** 弹出开启SAS的请求弹窗（多钱包） */
+    requestEnableMultiWalletSAS = "requestEnableMultiWalletSAS",
+    /** 获取SAS Keyshare */
+    getSASKeyshare = "getSASKeyshare",
+    /** 同步已连接钱包的SAS状态 */
+    syncSASStatus = "syncSASStatus",
+    /** 获取已连接钱包及其ProofKey */
+    getConnectedWalletAndProofKey = "getConnectedWalletAndProofKey",
+    /** 下单前获取ProofKey签名 */
+    getSASProofKeySignature = "getSASProofKeySignature",
+    /** 请求开启自动签名 */
     requestAutoSign = "requestAutoSign",
+    /** 签署交易订单 */
+    signOrder = "signOrder",
+    /** 钱包锁定状态变更事件 */
     eventWalletLockedChanged = "eventWalletLockedChanged",
+    /** 自动签名开关状态变更事件 */
     eventAutoSignEnabledChanged = "eventAutoSignEnabledChanged",
+    /** 已连接钱包列表变更事件 */
     eventConnectedWalletsChanged = "eventConnectedWalletsChanged",
+    /** 当前连接的链ID变更事件 */
     eventConnectedChainIdChanged = "eventConnectedChainIdChanged"
 }
 
 /**
- * 链接的钱包
+ * 已连接的钱包信息
  */
 interface IConnectedWallet {
     /**
      * base64编码的钱包图标
      */
     walletIcon: string;
+    /**
+     * 钱包名称
+     */
     walletName: string;
+    /**
+     * 钱包唯一标识
+     */
     walletId: string;
+    /**
+     * 钱包类型（私钥钱包 / 助记词钱包）
+     */
     walletType: WalletType;
+    /**
+     * 钱包关联的地址列表
+     */
     addressList: {
+        /** 链上地址 */
         address: string;
+        /** Binance 链ID */
         binanceChainId: string;
+        /** 公钥（hex 编码） */
         publicKeyHex: string;
     }[];
+    /**
+     * 钱包分组ID（可选）
+     */
+    groupID?: string;
+    /**
+     * 钱包分组名称（可选）
+     */
+    groupName?: string;
 }
+/**
+ * SAS（Smart Account Signing）授权信息
+ */
 interface SASAuthorizeInfo {
+    /** 钱包类型：助记词 / 私钥 */
     walletType: 'SEED_PHRASE' | 'PRIVATE_KEY';
+    /** ProofKey 公钥 */
     proofKeyPublicKey: string;
+    /** 授权过期时间戳 */
     expireAt: number;
+    /** 钱包唯一标识 */
     walletId: string;
+    /** 插件唯一标识 */
     extensionId: string;
+    /** 授权链列表 */
     authorizeList: SASAuthorizeInfoItem[];
 }
+/**
+ * SAS 授权中单条链的详细信息
+ */
 interface SASAuthorizeInfoItem {
+    /** 链类型：evm 或 sol */
     chain: 'evm' | 'sol';
+    /** Binance 链ID */
     binanceChainId: string;
+    /** 加密后的 KeyShare B */
     encryptedKeyShareB: string;
+    /** 加密后的 KeyShare A 数据 */
     encryptedKeyShareAData: string;
+    /** 公钥 */
     publicKey: string;
+    /** SPS 版本号 */
     spsVersion: string;
+    /** 用户公钥（hex 编码） */
     userPublicKeyHex: string;
 }
+/**
+ * 钱包事件定义
+ */
 interface WalletEvents {
+    /** 钱包锁定状态变更 */
     walletLockedChanged: (isLocked: boolean) => void;
+    /** 自动签名开关状态变更 */
     autoSignEnabledChanged: (isEnabled: boolean) => void;
+    /** 已连接钱包列表变更 */
     connectedWalletsChanged: (connectedWallets: IConnectedWallet[]) => void;
+    /** 当前连接的链ID变更 */
     connectedChainIdChanged: (binanceChainId: string) => void;
 }
+/**
+ * 多链钱包接口，继承 EventEmitter 以支持事件监听
+ */
 interface IWallet extends EventEmitter<WalletEvents> {
+    /**
+     * 请求连接钱包
+     * @param binanceChainIds 需要连接的 Binance 链ID列表
+     * @returns 已连接的钱包列表
+     */
     requestConnect(binanceChainIds: string[]): Promise<IConnectedWallet[]>;
     /**
-     * 链接插件的时候同时发起开启SAS的请求
+     * 连接插件的同时发起开启SAS的请求
      * 如果用户同意，插件会记录下当前用户同意开启的SAS
      */
     requestConnectWithSAS(args: {
@@ -82,6 +171,17 @@ interface IWallet extends EventEmitter<WalletEvents> {
         wallet: IConnectedWallet;
         aggreeEnableSAS: boolean;
     }>;
+    /**
+     * 连接插件的同时发起多钱包SAS请求
+     * @returns walletList 已连接钱包列表，enabledWalletIds 同意开启SAS的钱包ID列表
+     */
+    requestConnectWithMultiWalletSAS(args: {
+        binanceChainIds: string[];
+        userId: string;
+    }): Promise<{
+        walletList: IConnectedWallet[];
+        enabledWalletIds: string[];
+    }>;
     /**
      *  弹出要求用户同意开启SAS的弹窗
      */
@@ -92,6 +192,17 @@ interface IWallet extends EventEmitter<WalletEvents> {
     }): Promise<{
         aggreeEnableSAS: boolean;
     }>;
+    /**
+     * 弹出多钱包SAS开启请求弹窗
+     * @returns enabledWalletIds 用户同意开启SAS的钱包ID列表
+     */
+    requestEnableMultiWalletSAS(arg: {
+        walletIds: string[];
+        userId: string;
+        userEmail: string;
+    }): Promise<{
+        enabledWalletIds: string[];
+    }>;
     /**
      * 用户同意开启SAS后，获取SAS的keyshare
      * 由于同一个钱包可能在app端被用户开启，所以插件不会校验用户有没有在插件端同意过
@@ -114,6 +225,9 @@ interface IWallet extends EventEmitter<WalletEvents> {
             enabled: boolean;
         }[];
     }): Promise<void>;
+    /**
+     * 获取已连接钱包及其 ProofKey 公钥
+     */
     getConnectedWalletAndProofKey(arg: {
         userId: string;
     }): Promise<{
@@ -136,6 +250,12 @@ interface IWallet extends EventEmitter<WalletEvents> {
      * 用户的当前活跃钱包会出现在数组的第一个
      */
     checkConnectedWallet(): Promise<IConnectedWallet[]>;
+    /**
+     * 根据地址和链ID获取钱包信息
+     * @param address 链上地址
+     * @param binanceChainId Binance 链ID
+     * @returns 匹配的钱包信息，未找到则返回 null
+     */
     getWalletInfo(address: string, binanceChainId: string): Promise<IConnectedWallet | null>;
     /**
      * 断开所有连接的钱包
@@ -151,14 +271,26 @@ interface IWallet extends EventEmitter<WalletEvents> {
      * 若已链接，则直接返回
      */
     requestAutoSign(): Promise<void>;
+    /**
+     * 签署交易订单
+     * @returns 签名结果字符串
+     */
     signOrder(arg: {
+        /** 钱包唯一标识 */
         walletId: string;
+        /** 钱包地址 */
         walletAddress: string;
+        /** Binance 链ID */
         binanceChainId: string;
+        /** 交易数据 */
         txData: string;
+        /** 手续费金额 */
         feeAmount: string;
+        /** 手续费等级（可选） */
         feeAmountLevel?: 'Low' | 'Medium' | 'High' | 'Custom';
+        /** 摘要 */
         digest: string;
+        /** 摘要签名 */
         digestSign: string;
     }): Promise<string>;
     /**
@@ -169,7 +301,13 @@ interface IWallet extends EventEmitter<WalletEvents> {
      * 是否启用自动签名
      */
     autoSignEnabled: boolean;
+    /**
+     * 钱包是否锁定
+     */
     walletLocked: boolean;
+    /**
+     * 插件唯一标识
+     */
     extensionId: string;
 }
 

package/dist/index.mjs

@@ -1,2 +1,2 @@
-var r=(n=>(n.EVM="EVM",n.SOL="SOL",n))(r||{}),l=(n=>(n.privateKey="privateKey",n.seedPhrase="hd",n))(l||{}),a=(e=>(e.requestConnect="requestConnect",e.checkConnectedWallet="checkConnectedWallet",e.disconnect="disconnect",e.switchChain="switchChain",e.requestAutoSign="requestAutoSign",e.eventWalletLockedChanged="eventWalletLockedChanged",e.eventAutoSignEnabledChanged="eventAutoSignEnabledChanged",e.eventConnectedWalletsChanged="eventConnectedWalletsChanged",e.eventConnectedChainIdChanged="eventConnectedChainIdChanged",e))(a||{});var d=()=>{try{return!!window?.binancew3w?.isExtension}catch{return!1}},s=t=>{let o=c();return o?o.checkSupportFeature(t):!1},c=()=>d()?window.binancew3w?.wallet:null,h=()=>c();export{r as ChainType,a as Features,l as WalletType,d as checkExtensionInstalled,s as checkExtensionSupported,h as getMultichainWallet};
+var r=(t=>(t.EVM="EVM",t.SOL="SOL",t))(r||{}),c=(t=>(t.privateKey="privateKey",t.seedPhrase="hd",t))(c||{}),a=(e=>(e.requestConnect="requestConnect",e.requestConnectWithSAS="requestConnectWithSAS",e.requestConnectWithMultiWalletSAS="requestConnectWithMultiWalletSAS",e.checkConnectedWallet="checkConnectedWallet",e.getWalletInfo="getWalletInfo",e.disconnect="disconnect",e.switchChain="switchChain",e.requestEnableSAS="requestEnableSAS",e.requestEnableMultiWalletSAS="requestEnableMultiWalletSAS",e.getSASKeyshare="getSASKeyshare",e.syncSASStatus="syncSASStatus",e.getConnectedWalletAndProofKey="getConnectedWalletAndProofKey",e.getSASProofKeySignature="getSASProofKeySignature",e.requestAutoSign="requestAutoSign",e.signOrder="signOrder",e.eventWalletLockedChanged="eventWalletLockedChanged",e.eventAutoSignEnabledChanged="eventAutoSignEnabledChanged",e.eventConnectedWalletsChanged="eventConnectedWalletsChanged",e.eventConnectedChainIdChanged="eventConnectedChainIdChanged",e))(a||{});var i=()=>{try{return!!window?.binancew3w?.isExtension}catch{return!1}},d=n=>{let o=l();return o?o.checkSupportFeature(n):!1},l=()=>i()?window.binancew3w?.wallet:null,s=()=>l();export{r as ChainType,a as Features,c as WalletType,i as checkExtensionInstalled,d as checkExtensionSupported,s as getMultichainWallet};
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/enum.ts","../src/getMultichainWallet.ts"],"sourcesContent":["export enum ChainType {\n  EVM = 'EVM',\n  SOL = 'SOL',\n}\n\n/**\n * privateKey:私钥钱包\n * hd: 助记词钱包\n */\nexport enum WalletType {\n  privateKey = 'privateKey',\n  seedPhrase = 'hd',\n}\n\nexport enum Features {\n  requestConnect = 'requestConnect',\n  checkConnectedWallet = 'checkConnectedWallet',\n  disconnect = 'disconnect',\n  switchChain = 'switchChain',\n  requestAutoSign = 'requestAutoSign',\n  eventWalletLockedChanged = 'eventWalletLockedChanged',\n  eventAutoSignEnabledChanged = 'eventAutoSignEnabledChanged',\n  eventConnectedWalletsChanged = 'eventConnectedWalletsChanged',\n  eventConnectedChainIdChanged = 'eventConnectedChainIdChanged',\n}\n","import { Features } from './enum'\nimport type { IWallet } from './type'\n\nexport const checkExtensionInstalled = () => {\n  try {\n    return !!(window as any)?.binancew3w?.isExtension\n  } catch (error) {\n    return false\n  }\n}\n\n/**\n * 检查当前用户安装的插件是否支持\n */\nexport const checkExtensionSupported = (feature: Features) => {\n  const wallet = getInjectedWallet()\n  if (!wallet) {\n    return false\n  }\n  return wallet.checkSupportFeature(feature)\n}\n\nconst getInjectedWallet = () => {\n  const isInstalled = checkExtensionInstalled()\n  if (!isInstalled) {\n    return null\n  }\n  return (window as any).binancew3w?.wallet\n}\n\nexport const getMultichainWallet = (): IWallet | null => {\n  return getInjectedWallet()\n}\n"],"mappings":"AAAO,IAAKA,OACVA,EAAA,IAAM,MACNA,EAAA,IAAM,MAFIA,OAAA,IASAC,OACVA,EAAA,WAAa,aACbA,EAAA,WAAa,KAFHA,OAAA,IAKAC,OACVA,EAAA,eAAiB,iBACjBA,EAAA,qBAAuB,uBACvBA,EAAA,WAAa,aACbA,EAAA,YAAc,cACdA,EAAA,gBAAkB,kBAClBA,EAAA,yBAA2B,2BAC3BA,EAAA,4BAA8B,8BAC9BA,EAAA,6BAA+B,+BAC/BA,EAAA,6BAA+B,+BATrBA,OAAA,ICXL,IAAMC,EAA0B,IAAM,CAC3C,GAAI,CACF,MAAO,CAAC,CAAE,QAAgB,YAAY,WACxC,MAAE,CACA,MAAO,EACT,CACF,EAKaC,EAA2BC,GAAsB,CAC5D,IAAMC,EAASC,EAAkB,EACjC,OAAKD,EAGEA,EAAO,oBAAoBD,CAAO,EAFhC,EAGX,EAEME,EAAoB,IACJJ,EAAwB,EAIpC,OAAe,YAAY,OAF1B,KAKEK,EAAsB,IAC1BD,EAAkB","names":["ChainType","WalletType","Features","checkExtensionInstalled","checkExtensionSupported","feature","wallet","getInjectedWallet","getMultichainWallet"]}
+{"version":3,"sources":["../src/enum.ts","../src/getMultichainWallet.ts"],"sourcesContent":["export enum ChainType {\n  EVM = 'EVM',\n  SOL = 'SOL',\n}\n\n/**\n * privateKey:私钥钱包\n * hd: 助记词钱包\n */\nexport enum WalletType {\n  privateKey = 'privateKey',\n  seedPhrase = 'hd',\n}\n\n/**\n * 插件支持的功能特性枚举，用于 checkExtensionSupported 检测\n */\nexport enum Features {\n  // ---- 连接相关 ----\n  /** 请求连接钱包 */\n  requestConnect = 'requestConnect',\n  /** 连接钱包并发起单钱包SAS请求 */\n  requestConnectWithSAS = 'requestConnectWithSAS',\n  /** 连接钱包并发起多钱包SAS请求 */\n  requestConnectWithMultiWalletSAS = 'requestConnectWithMultiWalletSAS',\n  /** 检查当前已连接的钱包 */\n  checkConnectedWallet = 'checkConnectedWallet',\n  /** 根据地址和链ID获取钱包信息 */\n  getWalletInfo = 'getWalletInfo',\n  /** 断开所有已连接的钱包 */\n  disconnect = 'disconnect',\n  /** 切换网络 */\n  switchChain = 'switchChain',\n\n  // ---- SAS 相关 ----\n  /** 弹出开启SAS的请求弹窗（单钱包） */\n  requestEnableSAS = 'requestEnableSAS',\n  /** 弹出开启SAS的请求弹窗（多钱包） */\n  requestEnableMultiWalletSAS = 'requestEnableMultiWalletSAS',\n  /** 获取SAS Keyshare */\n  getSASKeyshare = 'getSASKeyshare',\n  /** 同步已连接钱包的SAS状态 */\n  syncSASStatus = 'syncSASStatus',\n  /** 获取已连接钱包及其ProofKey */\n  getConnectedWalletAndProofKey = 'getConnectedWalletAndProofKey',\n  /** 下单前获取ProofKey签名 */\n  getSASProofKeySignature = 'getSASProofKeySignature',\n\n  // ---- 签名相关 ----\n  /** 请求开启自动签名 */\n  requestAutoSign = 'requestAutoSign',\n  /** 签署交易订单 */\n  signOrder = 'signOrder',\n\n  // ---- 事件相关 ----\n  /** 钱包锁定状态变更事件 */\n  eventWalletLockedChanged = 'eventWalletLockedChanged',\n  /** 自动签名开关状态变更事件 */\n  eventAutoSignEnabledChanged = 'eventAutoSignEnabledChanged',\n  /** 已连接钱包列表变更事件 */\n  eventConnectedWalletsChanged = 'eventConnectedWalletsChanged',\n  /** 当前连接的链ID变更事件 */\n  eventConnectedChainIdChanged = 'eventConnectedChainIdChanged',\n}\n","import { Features } from './enum'\nimport type { IWallet } from './type'\n\nexport const checkExtensionInstalled = () => {\n  try {\n    return !!(window as any)?.binancew3w?.isExtension\n  } catch (error) {\n    return false\n  }\n}\n\n/**\n * 检查当前用户安装的插件是否支持\n */\nexport const checkExtensionSupported = (feature: Features) => {\n  const wallet = getInjectedWallet()\n  if (!wallet) {\n    return false\n  }\n  return wallet.checkSupportFeature(feature)\n}\n\nconst getInjectedWallet = () => {\n  const isInstalled = checkExtensionInstalled()\n  if (!isInstalled) {\n    return null\n  }\n  return (window as any).binancew3w?.wallet\n}\n\nexport const getMultichainWallet = (): IWallet | null => {\n  return getInjectedWallet()\n}\n"],"mappings":"AAAO,IAAKA,OACVA,EAAA,IAAM,MACNA,EAAA,IAAM,MAFIA,OAAA,IASAC,OACVA,EAAA,WAAa,aACbA,EAAA,WAAa,KAFHA,OAAA,IAQAC,OAGVA,EAAA,eAAiB,iBAEjBA,EAAA,sBAAwB,wBAExBA,EAAA,iCAAmC,mCAEnCA,EAAA,qBAAuB,uBAEvBA,EAAA,cAAgB,gBAEhBA,EAAA,WAAa,aAEbA,EAAA,YAAc,cAIdA,EAAA,iBAAmB,mBAEnBA,EAAA,4BAA8B,8BAE9BA,EAAA,eAAiB,iBAEjBA,EAAA,cAAgB,gBAEhBA,EAAA,8BAAgC,gCAEhCA,EAAA,wBAA0B,0BAI1BA,EAAA,gBAAkB,kBAElBA,EAAA,UAAY,YAIZA,EAAA,yBAA2B,2BAE3BA,EAAA,4BAA8B,8BAE9BA,EAAA,6BAA+B,+BAE/BA,EAAA,6BAA+B,+BA7CrBA,OAAA,ICdL,IAAMC,EAA0B,IAAM,CAC3C,GAAI,CACF,MAAO,CAAC,CAAE,QAAgB,YAAY,WACxC,MAAE,CACA,MAAO,EACT,CACF,EAKaC,EAA2BC,GAAsB,CAC5D,IAAMC,EAASC,EAAkB,EACjC,OAAKD,EAGEA,EAAO,oBAAoBD,CAAO,EAFhC,EAGX,EAEME,EAAoB,IACJJ,EAAwB,EAIpC,OAAe,YAAY,OAF1B,KAKEK,EAAsB,IAC1BD,EAAkB","names":["ChainType","WalletType","Features","checkExtensionInstalled","checkExtensionSupported","feature","wallet","getInjectedWallet","getMultichainWallet"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@binance/w3w-multichain-connector",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "description": "A multichain connector for Binance Wallet",
   "main": "dist/index.mjs",
   "types": "dist/index.d.ts",

package/src/enum.ts

@@ -12,14 +12,53 @@ export enum WalletType {
   seedPhrase = 'hd',
 }
 
+/**
+ * 插件支持的功能特性枚举，用于 checkExtensionSupported 检测
+ */
 export enum Features {
+  // ---- 连接相关 ----
+  /** 请求连接钱包 */
   requestConnect = 'requestConnect',
+  /** 连接钱包并发起单钱包SAS请求 */
+  requestConnectWithSAS = 'requestConnectWithSAS',
+  /** 连接钱包并发起多钱包SAS请求 */
+  requestConnectWithMultiWalletSAS = 'requestConnectWithMultiWalletSAS',
+  /** 检查当前已连接的钱包 */
   checkConnectedWallet = 'checkConnectedWallet',
+  /** 根据地址和链ID获取钱包信息 */
+  getWalletInfo = 'getWalletInfo',
+  /** 断开所有已连接的钱包 */
   disconnect = 'disconnect',
+  /** 切换网络 */
   switchChain = 'switchChain',
+
+  // ---- SAS 相关 ----
+  /** 弹出开启SAS的请求弹窗（单钱包） */
+  requestEnableSAS = 'requestEnableSAS',
+  /** 弹出开启SAS的请求弹窗（多钱包） */
+  requestEnableMultiWalletSAS = 'requestEnableMultiWalletSAS',
+  /** 获取SAS Keyshare */
+  getSASKeyshare = 'getSASKeyshare',
+  /** 同步已连接钱包的SAS状态 */
+  syncSASStatus = 'syncSASStatus',
+  /** 获取已连接钱包及其ProofKey */
+  getConnectedWalletAndProofKey = 'getConnectedWalletAndProofKey',
+  /** 下单前获取ProofKey签名 */
+  getSASProofKeySignature = 'getSASProofKeySignature',
+
+  // ---- 签名相关 ----
+  /** 请求开启自动签名 */
   requestAutoSign = 'requestAutoSign',
+  /** 签署交易订单 */
+  signOrder = 'signOrder',
+
+  // ---- 事件相关 ----
+  /** 钱包锁定状态变更事件 */
   eventWalletLockedChanged = 'eventWalletLockedChanged',
+  /** 自动签名开关状态变更事件 */
   eventAutoSignEnabledChanged = 'eventAutoSignEnabledChanged',
+  /** 已连接钱包列表变更事件 */
   eventConnectedWalletsChanged = 'eventConnectedWalletsChanged',
+  /** 当前连接的链ID变更事件 */
   eventConnectedChainIdChanged = 'eventConnectedChainIdChanged',
 }

package/src/type.ts

@@ -3,7 +3,7 @@ import type EventEmitter from 'eventemitter3'
 import type { WalletType } from './enum'
 
 /**
- * 链接的钱包
+ * 已连接的钱包信息
  */
 export interface IConnectedWallet {
   /**
@@ -11,50 +11,108 @@ export interface IConnectedWallet {
    */
   walletIcon: string
 
+  /**
+   * 钱包名称
+   */
   walletName: string
 
+  /**
+   * 钱包唯一标识
+   */
   walletId: string
 
+  /**
+   * 钱包类型（私钥钱包 / 助记词钱包）
+   */
   walletType: WalletType
 
+  /**
+   * 钱包关联的地址列表
+   */
   addressList: {
+    /** 链上地址 */
     address: string
+    /** Binance 链ID */
     binanceChainId: string
+    /** 公钥（hex 编码） */
     publicKeyHex: string
   }[]
+
+  /**
+   * 钱包分组ID（可选）
+   */
+  groupID?: string
+  /**
+   * 钱包分组名称（可选）
+   */
+  groupName?: string
 }
 
+/**
+ * SAS（Smart Account Signing）授权信息
+ */
 export interface SASAuthorizeInfo {
+  /** 钱包类型：助记词 / 私钥 */
   walletType: 'SEED_PHRASE' | 'PRIVATE_KEY'
+  /** ProofKey 公钥 */
   proofKeyPublicKey: string
+  /** 授权过期时间戳 */
   expireAt: number
+  /** 钱包唯一标识 */
   walletId: string
+  /** 插件唯一标识 */
   extensionId: string
+  /** 授权链列表 */
   authorizeList: SASAuthorizeInfoItem[]
 }
 
+/**
+ * SAS 授权中单条链的详细信息
+ */
 export interface SASAuthorizeInfoItem {
+  /** 链类型：evm 或 sol */
   chain: 'evm' | 'sol'
+  /** Binance 链ID */
   binanceChainId: string
+  /** 加密后的 KeyShare B */
   encryptedKeyShareB: string
+  /** 加密后的 KeyShare A 数据 */
   encryptedKeyShareAData: string
+  /** 公钥 */
   publicKey: string
+  /** SPS 版本号 */
   spsVersion: string
+  /** 用户公钥（hex 编码） */
   userPublicKeyHex: string
 }
 
+/**
+ * 钱包事件定义
+ */
 export interface WalletEvents {
+  /** 钱包锁定状态变更 */
   walletLockedChanged: (isLocked: boolean) => void
+  /** 自动签名开关状态变更 */
   autoSignEnabledChanged: (isEnabled: boolean) => void
+  /** 已连接钱包列表变更 */
   connectedWalletsChanged: (connectedWallets: IConnectedWallet[]) => void
+  /** 当前连接的链ID变更 */
   connectedChainIdChanged: (binanceChainId: string) => void
 }
 
+/**
+ * 多链钱包接口，继承 EventEmitter 以支持事件监听
+ */
 export interface IWallet extends EventEmitter<WalletEvents> {
+  /**
+   * 请求连接钱包
+   * @param binanceChainIds 需要连接的 Binance 链ID列表
+   * @returns 已连接的钱包列表
+   */
   requestConnect(binanceChainIds: string[]): Promise<IConnectedWallet[]>
 
   /**
-   * 链接插件的时候同时发起开启SAS的请求
+   * 连接插件的同时发起开启SAS的请求
    * 如果用户同意，插件会记录下当前用户同意开启的SAS
    */
   requestConnectWithSAS(args: {
@@ -70,6 +128,18 @@ export interface IWallet extends EventEmitter<WalletEvents> {
     aggreeEnableSAS: boolean
   }>
 
+  /**
+   * 连接插件的同时发起多钱包SAS请求
+   * @returns walletList 已连接钱包列表，enabledWalletIds 同意开启SAS的钱包ID列表
+   */
+  requestConnectWithMultiWalletSAS(args: {
+    binanceChainIds: string[]
+    userId: string
+  }): Promise<{
+    walletList: IConnectedWallet[]
+    enabledWalletIds: string[]
+  }>
+
   /**
    *  弹出要求用户同意开启SAS的弹窗
    */
@@ -81,6 +151,18 @@ export interface IWallet extends EventEmitter<WalletEvents> {
     aggreeEnableSAS: boolean
   }>
 
+  /**
+   * 弹出多钱包SAS开启请求弹窗
+   * @returns enabledWalletIds 用户同意开启SAS的钱包ID列表
+   */
+  requestEnableMultiWalletSAS(arg: {
+    walletIds: string[]
+    userId: string
+    userEmail: string
+  }): Promise<{
+    enabledWalletIds: string[]
+  }>
+
   /**
    * 用户同意开启SAS后，获取SAS的keyshare
    * 由于同一个钱包可能在app端被用户开启，所以插件不会校验用户有没有在插件端同意过
@@ -105,6 +187,9 @@ export interface IWallet extends EventEmitter<WalletEvents> {
     }[]
   }): Promise<void>
 
+  /**
+   * 获取已连接钱包及其 ProofKey 公钥
+   */
   getConnectedWalletAndProofKey(arg: { userId: string }): Promise<
     {
       wallet: IConnectedWallet
@@ -127,6 +212,12 @@ export interface IWallet extends EventEmitter<WalletEvents> {
    */
   checkConnectedWallet(): Promise<IConnectedWallet[]>
 
+  /**
+   * 根据地址和链ID获取钱包信息
+   * @param address 链上地址
+   * @param binanceChainId Binance 链ID
+   * @returns 匹配的钱包信息，未找到则返回 null
+   */
   getWalletInfo(
     address: string,
     binanceChainId: string
@@ -149,14 +240,26 @@ export interface IWallet extends EventEmitter<WalletEvents> {
    */
   requestAutoSign(): Promise<void>
 
+  /**
+   * 签署交易订单
+   * @returns 签名结果字符串
+   */
   signOrder(arg: {
+    /** 钱包唯一标识 */
     walletId: string
+    /** 钱包地址 */
     walletAddress: string
+    /** Binance 链ID */
     binanceChainId: string
+    /** 交易数据 */
     txData: string
+    /** 手续费金额 */
     feeAmount: string
+    /** 手续费等级（可选） */
     feeAmountLevel?: 'Low' | 'Medium' | 'High' | 'Custom'
+    /** 摘要 */
     digest: string
+    /** 摘要签名 */
     digestSign: string
   }): Promise<string>
 
@@ -169,6 +272,14 @@ export interface IWallet extends EventEmitter<WalletEvents> {
    * 是否启用自动签名
    */
   autoSignEnabled: boolean
+
+  /**
+   * 钱包是否锁定
+   */
   walletLocked: boolean
+
+  /**
+   * 插件唯一标识
+   */
   extensionId: string
 }