@droplinked_inc/wallet-connection

中文文档
0.5.0发布于 2026/11/02MITTypeScriptES Module近 30 天下载 1962

Wallet connection adapters for droplinked (MetaMask, Coinbase, WalletConnect, Phantom). Hardened recover+rewrite of the original @droplinked/wallet-connection.

原始使用文档
文档目录8 节
  1. Install
  2. Quick start — EVM login (MetaMask)
  3. Quick start — Phantom (Solana) login
  4. ERC-20 transfer
  5. Custom checkout calldata
  6. Security
  7. Status
  8. License

@droplinked_inc/wallet-connection

Replaces droplinked-wallet-connection. See MIGRATION.md for the swap path.

Hardened wallet-connection primitives for droplinked: MetaMask, Coinbase Wallet, and Phantom. EIP-712 typed-data login with chain + origin + nonce binding, zod-validated RPC boundaries, no any, no remote ABI fetches.

This package is a clean rewrite of the original @droplinked/[email protected] (hostile-published by an external actor). See THREAT_MODEL.md for the threat scenarios this package mitigates and the test cases that exercise them.

Install

pnpm add @droplinked_inc/wallet-connection

Peer-ish runtime deps:

  • viem ^2.21
  • zod ^4.6.7

Both are direct dependencies; you do not need to install them yourself.

Quick start — EVM login (MetaMask)

import {
  EvmConnector,
  Chain,
  Network,
  verifyLoginSignature,
  buildSession,
  saveSession,
} from '@droplinked_inc/wallet-connection';

const connector = new EvmConnector({
  chain: Chain.ETH,
  network: Network.MAINNET,
  origin: window.location.origin,
});

const { address, signature } = await connector.walletLogin();

// Verify (server-side or client-side):
await verifyLoginSignature({
  payload: /* the LoginPayload returned by your server */,
  signature,
  expectedAddress: address,
  expectedChainId: 1,
  expectedOrigin: window.location.origin,
});

saveSession(
  buildSession({
    address,
    chainId: 1,
    origin: window.location.origin,
    signature,
    ttlSeconds: 60 * 60 * 8, // 8 hours
  }),
);

Quick start — Phantom (Solana) login

import { PhantomConnector, Network } from '@droplinked_inc/wallet-connection';

const connector = new PhantomConnector(Network.MAINNET);
const { address, signature } = await connector.walletLogin();

ERC-20 transfer

const txHash = await connector.paymentWithToken(
  receiverAddress,
  1000000n, // amount as bigint
  tokenAddress,
);

Note: this issues a direct transfer. There is no approve API exposed — drainer-style allowance flows are not reachable from this package. See THREAT_MODEL.md §T5.

Custom checkout calldata

The droplinked v3 checkout contract is invoked via submitRawTransaction() with calldata produced by the droplinked checkout API. The legacy direct ABI encoder is intentionally removed (see THREAT_MODEL.md §T7 — remote ABI/address fetch was a single point of supply-chain compromise).

const txHash = await connector.submitRawTransaction({
  to: checkoutContractAddress,
  data: serverProducedCalldata,
  value: totalPriceWei,
  gasLimit: 3_000_000n,
});

Security

  • All RPC responses are zod-validated. Wallets that return malformed data cause a typed error, not silent corruption.
  • Login signatures are EIP-712 typed with chain + origin + nonce + issuedAt + optional expirationTime.
  • selectMetaMaskProvider() and selectCoinbaseProvider() require the wallet's own self-identification flag. There is no fallback to the umbrella window.ethereum.
  • Nonces use crypto.getRandomValues() (256 bits). If Web Crypto is unavailable the call throws — there is no Math.random() fallback.
  • Sessions default to sessionStorage (cleared on tab close), not localStorage. They carry an explicit expiresAt that loadSession() enforces.

See THREAT_MODEL.md for the full delta vs. the original v1.0.1 and the tests that exercise each scenario.

Status

Initial recover + harden. The original public API names are preserved where feasible; the following changes are deliberate and noted in THREAT_MODEL.md:

  • Chain/Network/ChainWallet are now string-valued enums (was implicit- numeric).
  • getNetworkProvider(chain, network, address, wallet) is now getNetworkProvider({ chain, network, address, wallet, ... }).
  • EVMProvider is now EvmConnector; SolanaProvider is now PhantomConnector (constructor signatures changed accordingly).
  • EVMPayment (the free function) is removed; use EvmConnector.submitRawTransaction().
  • Error classes now extend Error (regression-fixes try/catch).

License

MIT.

版本与发布记录

@droplinked_inc/wallet-connection 共发布 5 个版本,首次发布于 2026/05/19;过去 12 个月发布了 5 个版本。

版本发布日期距今
0.5.0latest2026/11/0213 天前
0.4.12026/08/063 个月前
0.4.02026/05/215 个月前
0.3.02026/05/195 个月前
0.1.12026/05/195 个月前

关于 @droplinked_inc/wallet-connection 的常见问题

@droplinked_inc/wallet-connection 是什么?

Wallet connection adapters for droplinked (MetaMask, Coinbase, WalletConnect, Phantom). Hardened recover+rewrite of the original @droplinked/wallet-connection.

如何安装 @droplinked_inc/wallet-connection?

在项目目录运行 npm install @droplinked_inc/wallet-connection,或使用 pnpm add / yarn add / bun add。

@droplinked_inc/wallet-connection 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@droplinked_inc/wallet-connection 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@droplinked_inc/wallet-connection 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@droplinked_inc/wallet-connection 可以商用吗?

@droplinked_inc/wallet-connection 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@droplinked_inc/wallet-connection 的下载量有多少?

根据 npm 官方下载统计,@droplinked_inc/wallet-connection 在 2026/10/13 – 2026/11/11 这 30 天内被下载 1,962 次,日均约 65 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@droplinked_inc/wallet-connection 还在维护吗?

最新版本 0.5.0 发布于 2026/11/02(13 天前);至今共发布 5 个版本,其中过去 12 个月发布了 5 个;首次发布于 2026/05/19。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。