{"id":31745035,"url":"https://github.com/dotbithq/wallet-bridge","last_synced_at":"2025-10-09T12:28:57.220Z","repository":{"id":176580661,"uuid":"651355597","full_name":"dotbitHQ/wallet-bridge","owner":"dotbitHQ","description":null,"archived":false,"fork":false,"pushed_at":"2024-05-09T12:03:19.000Z","size":5416,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-05-09T13:29:48.428Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dotbitHQ.png","metadata":{"files":{"readme":"README-CN.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-09T04:12:29.000Z","updated_at":"2023-12-29T15:26:03.000Z","dependencies_parsed_at":"2023-12-29T02:40:02.329Z","dependency_job_id":"35275bd4-47e4-4f60-ac81-4687f359c070","html_url":"https://github.com/dotbitHQ/wallet-bridge","commit_stats":null,"previous_names":["dotbithq/vite-component-library-template","dotbithq/wallet-bridge"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dotbitHQ/wallet-bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotbitHQ%2Fwallet-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotbitHQ%2Fwallet-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotbitHQ%2Fwallet-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotbitHQ%2Fwallet-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dotbitHQ","download_url":"https://codeload.github.com/dotbitHQ/wallet-bridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotbitHQ%2Fwallet-bridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001445,"owners_count":26083078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-09T12:28:29.415Z","updated_at":"2025-10-09T12:28:57.215Z","avatar_url":"https://github.com/dotbitHQ.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# wallet-bridge\n\n`wallet-bridge` 是一个支持多链、多登录方式的 Web3 钱包连接库。它主要提供了钱包连接、发送交易、签名消息等功能.\n\n## 主要特性\n\n- **支持的链**: Ethereum、BNB Smart Chain、Polygon、TRON、Dogecoin。\n- **登录方式**: WalletConnect、Passkey、Torus。\n- **行业标准**: 我们依赖于 [viem](https://viem.sh/)、[@wagmi/core](https://wagmi.sh/core/getting-started) 和 [@wagmi/connectors](https://wagmi.sh/core/api/connectors) 这是 Web3 中最常用的库。\n\n[Documentation in English](README.md)\n\n## 主要脚本\n\n- `dev`: 使用热加载启动 Storybook 预览。\n- `build`: 构建静态的 Storybook 项目。\n- `build:lib`: 将组件库构建到 **dist** 文件夹。\n- `lint:fix`: 基于 **.eslintrc.js** 中定义的规则进行 linting。\n- `format:prettier`: 使用 **.prettierrc** 中定义的 prettier 规则格式化文件。\n- `test`: 使用 watch 模式运行测试。\n- `test:cov`: 显示测试覆盖率报告。\n\n## 使用库\n\n### 1. 安装：\n\n安装 wallet-bridge 及其对等依赖.\n\n```bash\nyarn add wallet-bridge@^1 @wagmi/core@^2 @wagmi/connectors@^4 viem@^2\n```\n\n### 2. 导入 Wallet：\n\n```js\nimport { Wallet } from 'wallet-bridge'\n```\n\n\u003e **注意**: `wallet-bridge` 不支持 SSR。如果你的项目使用了 SSR，请确保在使用 `wallet-bridge` 之前检查是否在浏览器环境下。虽然此库是基于 react.js 开发的，但它也可以在任何前端项目中使用。\n\n若需要按需导入 `Wallet`，可以使用 `import()` 方法：\n\n```js\nconst { Wallet } = await import('wallet-bridge')\n```\n\n### 3. 初始化\n\n要创建一个新的 `Wallet` 对象，你可以使用其构造函数，并提供以下参数：\n\n- `isTestNet` (可选): 是否使用测试网络。默认为 `false`。\n- `loggedInSelectAddress` (可选): 在使用 Passkey 登录时，如果有多个地址，是否允许用户选择。默认为 `true`。\n- `customChains` (可选): 自定义链，来源于 `CustomChain` 枚举。默认为空数组。\n- `customWallets` (可选): 自定义钱包，来源于 `CustomWallet` 枚举。默认为空数组。\n- `wagmiConfig` (必须): 用于配置 [@wagmi/core](https://wagmi.sh/core/getting-started) 的相关信息，类型为 `WagmiConfig`。默认为`undefined`。现在依赖 WalletConnect 的每一个 DApp 都需要从 [WalletConnect Cloud](https://cloud.walletconnect.com) 免费获得一个 projectId。\n- `gtag` (可选): 用来上报 wallet-bridge 的一些事件到 google analytics，便于统计和分析用户的行为。如果你使用 `event`，则不需要提供此参数。\n- `event` (可选): 如果你使用 [nextjs-google-analytics](https://www.npmjs.com/package/nextjs-google-analytics) 来上报数据， 则可以用 `event` 来代替 `gtag`，用来上报 wallet-bridge 的一些事件到 google analytics，便于统计和分析用户的行为。如果你使用 `gtag`，则不需要提供此参数。\n- `locale` (可选): 用于设置语言。 现在支持 en、zh-CN、zh—TW、zh-HK、zh-MO. 如果没有设置，locale 会从下列顺序进行检测: query parameter lang -\u003e session storage lang -\u003e 浏览器语言设置 -\u003e en。\n\n**示例**：\n\n```js\nimport { Wallet } from 'wallet-bridge'\nimport { createConfig, http } from '@wagmi/core'\nimport { bsc, bscTestnet, holesky, mainnet as ethereum, polygon, polygonAmoy } from '@wagmi/core/chains'\nimport { injected, walletConnect } from '@wagmi/connectors'\n\nconst walletConnectOptions = {\n  projectId: 'YOUR_PROJECT_ID', // Get projectId at https://cloud.walletconnect.com\n  metadata: {\n    name: '.bit',\n    description: 'Barrier-free DID for Every Community and Everyone',\n    url: 'https://d.id',\n    icons: ['https://d.id/favicon.png'],\n  },\n}\n\nconst wagmiConfig = createConfig({\n  chains: [ethereum, holesky, bsc, bscTestnet, polygon, polygonAmoy],\n  transports: {\n    [ethereum.id]: http(),\n    [holesky.id]: http(),\n    [bsc.id]: http(),\n    [bscTestnet.id]: http(),\n    [polygon.id]: http(),\n    [polygonAmoy.id]: http(),\n  },\n  connectors: [injected(), walletConnect(walletConnectOptions)],\n})\n\nconst wallet = new Wallet({\n  isTestNet: false,\n  loggedInSelectAddress: true,\n  customChains: [CustomChain.eth],\n  customWallets: [CustomWallet.metaMask],\n  wagmiConfig: wagmiConfig,\n  locale: 'zh-CN',\n})\n```\n\n### 4. Wallet 的实例方法\n\n以下是一些主要的实例方法：\n\n#### 4.1 `initWallet({ involution = true }: { involution?: boolean } = {}): Promise\u003cboolean\u003e`\n\n初始化钱包登录状态。可以在全局初始化，也可以在每次使用钱包前初始化，通过返回值来判断是否继续执行相关业务代码。`initWallet` 方法会检测钱包是否已经登录，如果已经登录，则不会再次弹窗要用户登录，如果未登录，可以通过 `involution` 参数来控制是否弹窗让用户重新登录。\n\n**参数**:\n\n- `involution` (可选): 类型为`boolean`。默认值为 `true`。未登录是否弹窗让用户重新登录。\n\n**返回值**:\n\n- `Promise\u003cboolean\u003e`: 表示钱包是否登录成功。如果登录成功，返回`true`；否则返回`false`。\n\n**示例**：\n\n```js\nwallet.initWallet().then((success) =\u003e {\n  console.log('Wallet Initialization:', success ? 'Successful' : 'Failed')\n})\n```\n\n#### 4.2 `connectWallet(params: { onlyEth?: boolean } = {})`\n\n显示钱包连接弹窗。\n\n**参数**:\n\n- `onlyEth` (可选): 类型为`boolean`。是否只显示 Ethereum 链。默认值为 `false`。\n\n**示例**：\n\n```js\nwallet.connectWallet({ onlyEth: true })\n```\n\n#### 4.3 `connectWalletAndSignData(params: { signData: SignDataParams })`\n\n显示钱包连接弹窗。登录的同时可以进行签名操作。\n\n**示例**：\n\n```js\nconst res = await wallet.connectWalletAndSignData({\n  signData: {\n    data: 'hello world',\n  },\n})\nconsole.log(res)\n\n// or EVM EIP-712\nconst jsonStr =\n  '{\"types\":{\"EIP712Domain\":[{\"name\":\"chainId\",\"type\":\"uint256\"},{\"name\":\"name\",\"type\":\"string\"},{\"name\":\"verifyingContract\",\"type\":\"address\"},{\"name\":\"version\",\"type\":\"string\"}],\"Action\":[{\"name\":\"action\",\"type\":\"string\"},{\"name\":\"params\",\"type\":\"string\"}],\"Cell\":[{\"name\":\"capacity\",\"type\":\"string\"},{\"name\":\"lock\",\"type\":\"string\"},{\"name\":\"type\",\"type\":\"string\"},{\"name\":\"data\",\"type\":\"string\"},{\"name\":\"extraData\",\"type\":\"string\"}],\"Transaction\":[{\"name\":\"DAS_MESSAGE\",\"type\":\"string\"},{\"name\":\"inputsCapacity\",\"type\":\"string\"},{\"name\":\"outputsCapacity\",\"type\":\"string\"},{\"name\":\"fee\",\"type\":\"string\"},{\"name\":\"action\",\"type\":\"Action\"},{\"name\":\"inputs\",\"type\":\"Cell[]\"},{\"name\":\"outputs\",\"type\":\"Cell[]\"},{\"name\":\"digest\",\"type\":\"bytes32\"}]},\"primaryType\":\"Transaction\",\"domain\":{\"chainId\":5,\"name\":\"da.systems\",\"verifyingContract\":\"0x0000000000000000000000000000000020210722\",\"version\":\"1\"},\"message\":{\"DAS_MESSAGE\":\"TRANSFER FROM 0x54366bcd1e73baf55449377bd23123274803236e(906.74221046 CKB) TO ckt1qyqvsej8jggu4hmr45g4h8d9pfkpd0fayfksz44t9q(764.13228446 CKB), 0x54366bcd1e73baf55449377bd23123274803236e(142.609826 CKB)\",\"inputsCapacity\":\"906.74221046 CKB\",\"outputsCapacity\":\"906.74211046 CKB\",\"fee\":\"0.0001 CKB\",\"digest\":\"0x29cd28dbeb470adb17548563ceb4988953fec7b499e716c16381e5ae4b04021f\",\"action\":{\"action\":\"transfer\",\"params\":\"0x00\"},\"inputs\":[],\"outputs\":[]}}'\nconst res = await wallet.connectWalletAndSignData({\n  signData: {\n    data: JSON.parse(jsonStr),\n    isEIP712: true,\n  },\n})\nconsole.log(res)\n```\n\n#### 4.4 `loggedInfo()`\n\n显示已登录弹窗。如果用户已经登录，弹窗将会展示出登录信息。\n\n**示例**：\n\n```js\nwallet.loggedInfo()\n```\n\n#### 4.5 `sendTransaction(data: ISendTrxParams): Promise\u003cstring | undefined\u003e`\n\n用于发送交易。\n\n**参数**:\n\n- `data`: 交易参数。\n  - `to`: 交易的接收地址，类型为`string`。\n  - `value`: 交易的金额，必须为代币最小单位，类型为`string`。\n  - `data` (可选): 交易备注，类型为`string`。\n\n**返回值**:\n\n- `Promise\u003cstring | undefined\u003e`: 在交易成功发送后，返回的是一个交易哈希。如果有任何错误或问题，可能会返回`undefined`或抛出错误。\n\n**示例**：\n\n```js\nconst transactionData = {\n  to: '0x020881E3F5B7832E752d16FE2710eE855A6977Dc',\n  value: '10000000000',\n  data: 'a message',\n}\nwallet.sendTransaction(transactionData).then((txHash) =\u003e {\n  console.log('Transaction Hash:', txHash)\n})\n```\n\n#### 4.6 `initSignContext(): Promise\u003cInitSignContextRes\u003e`\n\n初始化签名上下文并返回签名方法。为了避免签名时弹窗被浏览器拦截，`initSignContext` 务必在点击事件所有异步操作之前调用。\n\n**返回值**:\n\n- `Promise\u003cInitSignContextRes\u003e`: 返回一个包含以下方法的对象:\n  - `signTxList`: 函数，.bit 业务专用，用于签名交易列表。\n  - `signData`: 函数，返回值是签名后的数据。\n  - `onFailed`: 函数，其返回值是一个`Promise\u003cIData\u003cany\u003e\u003e`，有任何错误都需要调用 `onFailed` 通知弹窗显示错误。\n  - `onClose`: 函数，其返回值是一个`Promise\u003cvoid\u003e`，有些情况下如果你想自己处理错误，而不是让弹窗显示错误，想关闭弹窗就用 `onClose`。\n\n示例：\n\n```js\nconst { signTxList, signData, onFailed, onClose } = await wallet.initSignContext()\nconst res = await signTxList({})\nconst res = await signData('0x123')\nconst res = await signData({}, { isEIP712: true })\nawait onFailed()\nawait onClose()\n```\n\n#### 4.7 `useWalletState(): { walletSnap: Snapshot\u003cWalletState\u003e }`\n\n`useWalletState` 是一个 React hook，用于获取和监听钱包状态。\n\n**返回值**:\n\n- `walletSnap`: 对`walletState`的当前快照，它的类型为`WalletState`，其中包含以下字段：\n\n  - `protocol`: 钱包的协议类型，类型为`WalletProtocol`。\n  - `address`: 当前登录的钱包地址，类型为`string`。\n  - `coinType`: 代币类型，类型为`CoinType`。\n  - `walletName`: 钱包名称，类型为`string`。\n  - `hardwareWalletTipsShow`: 硬件钱包提示是否显示，类型为`boolean`。\n  - `deviceData`: Passkey 登录时设备数据，类型为`IDeviceData`。\n  - `ckbAddresses`: Passkey 登录时设备能够管理的 CKB 地址列表，类型为`string[]`。\n  - `deviceList`: 备份设备列表，类型为`string[]`。\n  - `isTestNet`: 是否为测试网，类型为`boolean`。\n  - `loggedInSelectAddress`: 是否在 Passkey 登录时，有多个地址的情况下选择地址，默认为`true`。\n  - `canAddDevice`: 是否可以添加备份设备，类型为`boolean`。\n  - `iCloudPasskeySupport`: 当前环境是否支持将 passkey 存储在 iCloud 中，类型为`boolean`。\n  - `customChains`: 自定义显示的链，类型为`CustomChain[]`。\n  - `customWallets`: 自定义显示的钱包，类型为`string[]`。\n  - `alias`: 当前登录的钱包地址设置的 .bit alias，类型为`string`。\n  - `locale`: 当前使用的语言，类型为`string`。\n  - `chainId`: 当使用 EVM 链钱包登录时表示对应的链 ID，类型为`number`。当使用 TRON 钱包登录时表示对应的链 ID，类型为`string`。\n\n**示例**:\n\n```js\nfunction Component() {\n  const { walletSnap } = wallet.useWalletState()\n  return \u003cdiv\u003eAddress: {walletSnap.address}\u003c/div\u003e\n}\n```\n\n#### 4.8 `getWalletState(): { walletSnap: Snapshot\u003cWalletState\u003e }`\n\n用于立即获取当前的钱包状态的快照。\n\n**返回值**:\n\n和 `useWalletState` 的返回值一样。\n\n**示例**:\n\n```js\nconst { walletSnap } = wallet.getWalletState()\nconsole.log(walletSnap.address)\n```\n\n#### 4.9 `_verifyPasskeySignature(params: { message: string, signature: string }): Promise\u003cboolean\u003e `\n\n验证 passkey 签名结果是否正确。\n\n**参数**:\n\n- `params`: 交易参数。\n  - `message`: 原信息，类型为`string`。\n  - `signature`: 信息签名结果，类型为`string`。\n\n**返回值**:\n\n- `Promise\u003cboolean\u003e`: 签名结果正确，则返回 `true`。如果有任何错误或问题，可能会抛出错误。\n\n**示例**:\n\n```js\nwallet._verifyPasskeySignature({ message: '0x123', signature: '0x40b4a569e0cb53163f...' }).then((result) =\u003e {\n  console.log('result: ', result)\n})\n```\n\n#### 4.10 `setLocale(locale: string)`\n\n用于设置语言。 现在支持 en、zh-CN、zh—TW、zh-HK、zh-MO. 如果没有设置，locale 会从下列顺序进行检测: query parameter lang -\u003e session storage lang -\u003e 浏览器语言设置 -\u003e en。\n\n**示例**：\n\n```js\nwallet.setLocale('en')\nwallet.setLocale('zh-CN')\nwallet.setLocale('zh—TW')\nwallet.setLocale('zh-HK')\nwallet.setLocale('zh-MO')\n```\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotbithq%2Fwallet-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdotbithq%2Fwallet-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotbithq%2Fwallet-bridge/lists"}