{"_id":"@algorade/use-wallet-xchain-evm","name":"@algorade/use-wallet-xchain-evm","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@algorade/use-wallet-xchain-evm","version":"0.1.0","publishConfig":{"access":"public"},"description":"xChain EVM (MetaMask / wagmi) wallet adapter for @txnlab/use-wallet v5","license":"MIT","repository":{"type":"git","url":"git+https://github.com/questionmarket/use-wallet-xchain-evm.git"},"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"peerDependencies":{"@txnlab/use-wallet":">=5.0.0-rc.1 <6","@algorandfoundation/algokit-utils":"^9.2.0","@wagmi/core":">=2.20.0 <3","algo-x-evm-sdk":"^0.1.0","algosdk":"^3.0.0"},"dependencies":{},"devDependencies":{"@txnlab/use-wallet":"5.0.0-rc.1","@algorandfoundation/algokit-utils":"9.2.0","@types/node":"^22.0.0","@wagmi/core":"2.22.1","algo-x-evm-sdk":"0.1.2","algosdk":"3.5.2","tsdown":"0.21.0","typescript":"5.9.3","viem":"2.48.4","vitest":"3.2.4"},"keywords":["algorand","use-wallet","xchain","evm","metamask","wagmi","svelte","react","vue","solid"],"engines":{"node":">=20"},"scripts":{"build":"tsdown","start":"tsdown --watch","test":"vitest run","test:watch":"vitest --watch","test:integration":"vitest run --config integration-tests/vitest.config.ts","typecheck":"tsc --noEmit"},"gitHead":"ce99efa5868316bb27da8837c6bc2fa967b13b80","_id":"@algorade/use-wallet-xchain-evm@0.1.0","bugs":{"url":"https://github.com/questionmarket/use-wallet-xchain-evm/issues"},"homepage":"https://github.com/questionmarket/use-wallet-xchain-evm#readme","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-t9y1A5OwoWAzn09vyiepxxmGO9m0yHcqY9hcyrQONu/lqRsI4KxSj8LqiaDjgIryyq4SKfy40yQoM4PWJGO1Bw==","shasum":"8fb0f103a56898f43118a98442051039d4130e11","tarball":"https://registry.npmjs.org/@algorade/use-wallet-xchain-evm/-/use-wallet-xchain-evm-0.1.0.tgz","fileCount":6,"unpackedSize":67654,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCYAhCMWgfEjKuQX7y11rERn/C3g2VxWOgaL13rEiwfiAIhAIDmVOjyVdtYtR0X5UYYics98BG6UhMRwrK2mgnQyBOG"}]},"_npmUser":{"name":"andreisavin","email":"andrei@andreisavin.com"},"directories":{},"maintainers":[{"name":"andreisavin","email":"andrei@andreisavin.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/use-wallet-xchain-evm_0.1.0_1777444707561_0.33298282451474215"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-29T06:38:27.464Z","0.1.0":"2026-04-29T06:38:27.863Z","modified":"2026-04-29T06:38:28.120Z"},"maintainers":[{"name":"andreisavin","email":"andrei@andreisavin.com"}],"description":"xChain EVM (MetaMask / wagmi) wallet adapter for @txnlab/use-wallet v5","homepage":"https://github.com/questionmarket/use-wallet-xchain-evm#readme","keywords":["algorand","use-wallet","xchain","evm","metamask","wagmi","svelte","react","vue","solid"],"repository":{"type":"git","url":"git+https://github.com/questionmarket/use-wallet-xchain-evm.git"},"bugs":{"url":"https://github.com/questionmarket/use-wallet-xchain-evm/issues"},"license":"MIT","readme":"# @algorade/use-wallet-xchain-evm\n\nxChain EVM wallet adapter for [`@txnlab/use-wallet`](https://github.com/TxnLab/use-wallet) v5. Lets users sign Algorand transactions with an EVM wallet (MetaMask, Brave Wallet, Rabby, any EIP-1193 provider via wagmi). The adapter derives a deterministic Algorand address from each EVM address using the [xChain Accounts](https://github.com/algorandfoundation/xchain-accounts) LogicSig + EIP-712 signing scheme.\n\nFramework-neutral: works from Svelte, React, Vue, or Solid through the corresponding `@txnlab/use-wallet-{svelte,react,vue,solid}` framework adapter.\n\n## Why this exists\n\nThe xChain Accounts protocol on Algorand was originally built against `@txnlab/use-wallet` **v4** in the [`tasosbit/use-wallet`](https://github.com/tasosbit/use-wallet) fork. v5 introduced a modular per-wallet package architecture. This package ports the v4 fork's `RainbowKitWallet` + `AlgoXEvmBaseWallet` onto v5's modular adapter API so v5 consumers (especially non-React ones) can use xChain EVM without forking core.\n\n## Install\n\n```bash\npnpm add @algorade/use-wallet-xchain-evm @wagmi/core @wagmi/connectors viem algo-x-evm-sdk @algorandfoundation/algokit-utils\n# or npm install / yarn add\n```\n\nYou also need `@txnlab/use-wallet@^5` and a framework adapter (e.g. `@txnlab/use-wallet-svelte`) — usually already installed by your app.\n\n## Usage (Svelte example)\n\n```ts\n// lib/wallet/config.ts\nimport { WalletManager, type NetworkConfig } from '@txnlab/use-wallet'\nimport { pera } from '@txnlab/use-wallet-pera'\nimport { xchainEvm } from '@algorade/use-wallet-xchain-evm'\nimport { createConfig, http, connect } from '@wagmi/core'\nimport { injected } from '@wagmi/connectors'\nimport { mainnet } from 'viem/chains'\n\nconst evmConnector = injected()\nconst wagmiConfig = createConfig({\n  chains: [mainnet],                       // placeholder; xChain signing is chain-agnostic\n  connectors: [evmConnector],\n  transports: { [mainnet.id]: http() },\n})\n\nexport function createWalletManager() {\n  return new WalletManager({\n    wallets: [\n      pera({ compactMode: true }),\n      xchainEvm({\n        wagmiConfig,\n        getEvmAccounts: async () => {\n          // Called when no EVM wallet is connected. Open your own connect modal,\n          // perform connection, return the EVM addresses. v0 example: just call\n          // wagmi connect with a hardcoded connector.\n          const result = await connect(wagmiConfig, { connector: evmConnector })\n          return [...result.accounts]\n        },\n      }),\n    ],\n    networks: { /* your algod configs */ },\n    defaultNetwork: 'mainnet',\n  })\n}\n```\n\nThe wallet shows up in `useWallet()` like any other adapter. Connecting prompts MetaMask (or whatever EVM wallet); the derived Algorand address appears in `wallet.activeAddress`. Signing prompts MetaMask with EIP-712 typed data; the resulting signature is verified by the LogicSig on-chain.\n\n## Detecting EVM-derived wallets\n\n```ts\nimport type { XChainWalletMetadata } from '@algorade/use-wallet-xchain-evm'\n\nconst isEvm = (wallet.metadata as XChainWalletMetadata).isAlgoXEvm === 'EVM'\n```\n\nThe `isAlgoXEvm: 'EVM'` marker lets you gate UI affordances (e.g. a pre-sign transparency dialog, since MetaMask only shows the user the EIP-712 digest, not the human-readable transaction details).\n\n## Pre-sign transparency hook (optional)\n\nPass `uiHooks.onBeforeSign` if you want to intercept the txn group before MetaMask is prompted — useful for showing a \"you're about to send 5 ALGO to X\" dialog that the bare MetaMask prompt doesn't surface:\n\n```ts\nxchainEvm({\n  wagmiConfig,\n  getEvmAccounts,\n  uiHooks: {\n    onBeforeSign: async (txnGroup, indexesToSign) => {\n      // decode and show a confirmation dialog; throw to abort\n    },\n    onAfterSign: (success, errorMessage) => {\n      // notify user of outcome\n    },\n  },\n})\n```\n\n## Network switching\n\nThe adapter caches the underlying `AlgoXEvmSdk` against the active network. When you call `walletManager.setActiveNetwork(...)`, the cache is invalidated automatically and the SDK rebuilds against the new algod client. Address derivation is deterministic from the EVM address (so the derived Algorand address is the same on every network), but signatures are bound to the network's genesis hash via the txn ID. **Tested:** `algo-x-evm-base.test.ts` asserts the SDK rebuild on `activeNetwork` change.\n\n## Connect-modal UX\n\nThis package only owns the wallet-adapter side. The host app builds the EVM-wallet picker — `getEvmAccounts: () => Promise<string[]>` is the seam. v0 examples hardcode `injected()` (MetaMask et al.). For richer UX, build a Svelte/React/Vue component that lists `wagmiConfig.connectors`, lets the user pick, calls `connect(wagmiConfig, { connector })`, and resolves the promise.\n\nFor React apps that already use RainbowKit, you can use `setGetEvmAccounts(fn)` to inject the callback after the React tree has mounted (RainbowKit's `useConnectModal` only works inside `<RainbowKitProvider>`, which mounts after `WalletManager` instantiation).\n\n## SSR / SvelteKit notes\n\nThe adapter dynamically imports `@wagmi/core`, `algo-x-evm-sdk`, and `@algorandfoundation/algokit-utils` inside method bodies — none of those load at module-import time. That keeps top-level import safe on the server.\n\nIf you use SvelteKit with SSR enabled, externalize the package and its EVM-side peer deps in `vite.config.ts` so they don't run through Vite's SSR transform:\n\n```ts\nssr: {\n  external: [\n    '@algorade/use-wallet-xchain-evm',\n    '@wagmi/core',\n    '@wagmi/connectors',\n    'viem',\n    'algo-x-evm-sdk',\n    '@algorandfoundation/algokit-utils',\n  ],\n},\n```\n\nThe adapter itself only runs in the browser (it reads `window.ethereum` via wagmi connectors). If you call adapter methods from a `+server.ts` handler, they'll fail at the wagmi connector layer — by design.\n\n## Bundle size\n\nThis package: ~15 KB gzipped (~50 KB raw). The bulk of what you ship comes from peer deps:\n\n| Peer dep                            | Approx. gzipped impact                      |\n|-------------------------------------|---------------------------------------------|\n| `@wagmi/core`                       | ~30 KB                                      |\n| `viem` (transitive via wagmi)       | ~80 KB                                      |\n| `@wagmi/connectors` (per connector) | ~20–40 KB each (WalletConnect is heaviest)  |\n| `algo-x-evm-sdk`                    | ~10 KB                                      |\n| `@algorandfoundation/algokit-utils` | ~30 KB (you likely already ship it)         |\n\nTotal incremental cost over a baseline `@txnlab/use-wallet` Svelte/React app: roughly **150–200 KB gzipped** if you weren't already using wagmi. Not free; budget accordingly.\n\n## Caveats\n\n- **EVM-derived accounts start with 0 ALGO.** The derived Algorand address is empty until funded. Algorand requires a minimum balance to exist (~0.1 ALGO) and an opt-in transaction (costs ALGO) to receive ASAs. Sponsored opt-ins are the standard fix; otherwise users need to send ALGO to the derived address before doing anything.\n- **MetaMask shows the user EIP-712 typed data, not txn semantics.** The user sees the Algorand transaction ID hash inside an EIP-712 envelope, not \"send 5 ALGO to X\". Surface a pre-sign dialog via `uiHooks.onBeforeSign` if your app handles non-trivial transactions.\n- **Connector-name detection is partial.** wagmi's `injected()` reports `connector.name = 'Injected'` when the underlying provider doesn't self-identify (browser, extension version, etc.); this adapter falls back to \"EVM Wallet\" in that case. Wallets that report a real name (MetaMask, Brave Wallet, Rabby, Coinbase Wallet) come through correctly. The generic-name list is small and conservative — file an issue if you see a meaningless name passing through.\n- **No bridges, no fiat on-ramps.** This package only handles wallet connection and signing. Funding the derived account is your app's responsibility.\n\n## Status\n\n`0.1.0` — beta.\n\n| Area                                                | Status                                                 |\n|-----------------------------------------------------|--------------------------------------------------------|\n| TypeScript build (`tsdown`)                         | ✅ green, ESM + dts                                    |\n| TypeScript strict typecheck                         | ✅ green                                               |\n| Unit tests (28 tests)                               | ✅ green, run via `pnpm test`                          |\n| Integration tests against real algokit localnet (6 tests) | ✅ green, run via `pnpm test:integration` (requires Docker + algokit) |\n| Connect path (existing wagmi connection)            | ✅ unit-tested                                         |\n| Connect path (`getEvmAccounts` callback)            | ✅ unit-tested                                         |\n| Connect path (first-connector fallback)             | ✅ unit-tested                                         |\n| `connector.name === 'Injected'` filter              | ✅ unit-tested                                         |\n| Disconnect                                          | ✅ unit-tested                                         |\n| `signTransactions` happy path                       | ✅ unit-tested                                         |\n| `signTransactions` indexesToSign filter             | ✅ unit-tested                                         |\n| `signTransactions` already-signed skip              | ✅ unit-tested                                         |\n| `signTransactions` error → onAfterSign              | ✅ unit-tested                                         |\n| `evmAddressMap` recovery from store                 | ✅ unit-tested                                         |\n| Multi-signer grouping                               | ✅ unit-tested                                         |\n| `uiHooks` (onBeforeSign / onAfterSign / onConnect)  | ✅ unit-tested                                         |\n| Network-switch SDK invalidation (cache)             | ✅ unit-tested                                         |\n| End-to-end signing round-trip on real algod         | ✅ integration-tested (localnet)                       |\n| Network-binding cryptography (different genesis hash → different signature) | ✅ integration-tested (localnet) |\n| ARC-0001 atomic group with mixed xChain + native signers | ✅ integration-tested (localnet)                  |\n| ASA opt-in error surfacing                          | ✅ integration-tested (localnet)                       |\n\n## Related projects\n\n- [TxnLab/use-wallet](https://github.com/TxnLab/use-wallet) — the upstream v5 wallet manager\n- [tasosbit/use-wallet](https://github.com/tasosbit/use-wallet) — the v4 fork where xChain EVM was originally implemented\n- [algorandfoundation/xchain-accounts](https://github.com/algorandfoundation/xchain-accounts) — the xChain Accounts protocol (LogicSig + SDK)\n- [tasosbit/use-wallet-ui](https://github.com/tasosbit/use-wallet-ui) — the (React-only) opinionated UI layer for xChain (transaction transparency, bridge/swap panels, manage UI)\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md). Issues and PRs welcome.\n\n## License\n\nMIT. See [LICENSE](./LICENSE) for full text and attribution to upstream sources.\n","readmeFilename":"README.md","_rev":"1-8b92f5cf5140c99965339bca2da30527"}