feat: Add a Vite + React example with injected provider #136

tiero · 2025-08-18T23:07:39Z

🔌 Add Xverse Wallet Integration Example

Overview

This PR introduces a complete example demonstrating how to integrate the Arkade SDK with external Bitcoin wallets, specifically Xverse wallet using sats-connect.

To test it locally, download Xverse, create the wallet, switch to Signet and run the web app:

cd examples/xverse-react-app
pnpm dev

Use Arkade Wallet on signet operator

Summary by CodeRabbit

New Features
- Introduced MetaMask Snap for Taproot signing with full ARK send/settle flows and a React demo app.
- Added Xverse Wallet React example using external wallet signing, including balance, VTXO, send, settle, and debugging tools.
Documentation
- New guides for the MetaMask Snap, the MetaMask React app, and the Xverse React app with setup and usage instructions.
Chores
- Added build, lint, and dev configurations, HTML/CSS scaffolding for example apps and Snap.
- Removed pre-commit linting and unit tests.

This change adds a new example application that demonstrates how to use the Arkade SDK with the Phantom browser extension. The example is a simple Vite + React app that: - Connects to the Phantom wallet. - Displays the user's Bitcoin address. - Creates and signs a simple on-chain transaction using the `OnchainWallet` class. - Displays the transaction ID of the broadcasted transaction.

coderabbitai · 2025-08-18T23:18:36Z

Walkthrough

Adds two complete example apps for ARK wallet integration: one using Xverse via sats-connect and one using MetaMask Snap, including UI, wallet wrappers, identities, configs, and Vite setups. Introduces a MetaMask Snap project with manifest, TypeScript source, build config, and RPC handlers. Removes pre-commit lint/test commands.

Changes

Cohort / File(s)	Summary
Husky Hook `.husky/pre-commit`	Removed lint and unit test commands, leaving an empty pre-commit hook.
Xverse React Example `examples/xverse-react-app/README.md`, `examples/xverse-react-app/eslint.config.js`, `examples/xverse-react-app/index.html`, `examples/xverse-react-app/package.json`, `examples/xverse-react-app/src/App.jsx`, `examples/xverse-react-app/src/ArkWallet.js`, `examples/xverse-react-app/src/SatsConnectDebugger.js`, `examples/xverse-react-app/src/SatsConnectIdentity.js`, `examples/xverse-react-app/src/index.css`, `examples/xverse-react-app/src/main.jsx`, `examples/xverse-react-app/vite.config.js`	New React app demonstrating ARK integration via Xverse/sats-connect: UI, wallet wrapper, external identity (PSBT signing), debugger, styling, ESLint, Vite config, and documentation.
MetaMask React Example `examples/metamask-react-app/README.md`, `examples/metamask-react-app/eslint.config.js`, `examples/metamask-react-app/index.html`, `examples/metamask-react-app/package.json`, `examples/metamask-react-app/src/App.jsx`, `examples/metamask-react-app/src/ArkWallet.js`, `examples/metamask-react-app/src/MetaMaskSnapIdentity.js`, `examples/metamask-react-app/src/index.css`, `examples/metamask-react-app/src/main.jsx`, `examples/metamask-react-app/vite.config.js`	New React app demonstrating ARK integration via MetaMask Snap: UI, wallet wrapper, Snap-based identity (PSBT signing), styling, ESLint, Vite config, and documentation.
MetaMask Snap `snap/.eslintrc.js`, `snap/.gitignore`, `snap/README.md`, `snap/package.json`, `snap/snap.config.js`, `snap/snap.manifest.json`, `snap/src/index.ts`, `snap/tsconfig.json`	New Snap project implementing Taproot account derivation and PSBT signing on Signet, with manifest, build/serve config, TypeScript setup, ESLint, ignores, and README.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User
  participant App (React)
  participant ArkWallet
  participant SatsConnectIdentity
  participant Xverse Wallet

  User->>App (React): Click "Connect"
  App (React)->>ArkWallet: connect()
  ArkWallet->>Xverse Wallet: wallet_connect (payment, ordinals) on signet
  Xverse Wallet-->>ArkWallet: addresses + pubkey
  ArkWallet->>SatsConnectIdentity: construct(publicKey, address, requestFn)
  ArkWallet-->>App (React): { ordinalAddress, arkAddress, userPubKey }

  User->>App (React): Send (recipient, amount)
  App (React)->>ArkWallet: sendBitcoin(addr, amt)
  ArkWallet->>SatsConnectIdentity: sign(PSBT inputs)
  SatsConnectIdentity->>Xverse Wallet: signPsbt(psbt, inputs)
  Xverse Wallet-->>SatsConnectIdentity: signed PSBT
  SatsConnectIdentity-->>ArkWallet: signed tx
  ArkWallet-->>App (React): arkTxid
  App (React)-->>User: Show TxID and status

sequenceDiagram
  autonumber
  actor User
  participant App (React)
  participant ArkWallet
  participant MetaMaskSnapIdentity
  participant MetaMask (Snap)

  User->>App (React): Click "Connect"
  App (React)->>ArkWallet: connect()
  ArkWallet->>MetaMask (Snap): wallet_requestSnaps (install/enable)
  MetaMask (Snap)-->>ArkWallet: enabled
  ArkWallet->>MetaMask (Snap): wallet_invokeSnap(bitcoin_getAccounts)
  MetaMask (Snap)-->>ArkWallet: { taprootAddress, xOnlyPubKey }
  ArkWallet->>MetaMaskSnapIdentity: construct(pubKey, address, ethereum)
  ArkWallet-->>App (React): { taprootAddress, arkAddress, userPubKey }

  User->>App (React): Send (recipient, amount)
  App (React)->>ArkWallet: sendBitcoin(addr, amt)
  ArkWallet->>MetaMaskSnapIdentity: sign(PSBT, inputs)
  MetaMaskSnapIdentity->>MetaMask (Snap): wallet_invokeSnap(bitcoin_signPsbt)
  MetaMask (Snap)-->>MetaMaskSnapIdentity: signed PSBT
  MetaMaskSnapIdentity-->>ArkWallet: signed tx
  ArkWallet-->>App (React): arkTxid
  App (React)-->>User: Show TxID and status

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

Update to latest arkd, renaming and TSDoc #108 — Also modifies pre-commit automation by removing precommit/lint-staged hooks; aligns with this PR’s .husky/pre-commit change.

Suggested reviewers

Kukks
bordalix
altafan

Tip

🔌 Remote MCP (Model Context Protocol) integration is now available!

Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats.

✨ Finishing Touches

📝 Generate Docstrings

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch phantom-example

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbit in a new review comment at the desired location with your query.
PR comments: Tag @coderabbit in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbit gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbit read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbit help to get the list of available commands.

Other keywords and placeholders

Add @coderabbit ignore or @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbit summary or @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbit or @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

Visit our Status Page to check the current availability of CodeRabbit.
Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

coderabbitai

Actionable comments posted: 3

🔭 Outside diff range comments (2)

examples/phantom-example/README.md (1)

1-13: Replace boilerplate README with Phantom + Arkade usage guide

This README is the default Vite template and doesn't explain the Phantom + Arkade flow introduced by this example. Replace it with focused instructions so users can run and understand the sample.

Apply this diff to replace the README with a minimal, targeted guide:

-# React + Vite
-
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
-
-Currently, two official plugins are available:
-
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend using TypeScript with type-aware lint rules enabled. Check out the [TS template](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-react-ts) for information on how to integrate TypeScript and [`typescript-eslint`](https://typescript-eslint.io) in your project.
+# Phantom + Arkade SDK (Vite + React) Example
+
+This example demonstrates how to:
+- Connect to the Phantom browser extension (Bitcoin).
+- Read and display the user's Bitcoin address.
+- Build, sign, and broadcast a simple on-chain transaction using the Arkade SDK.
+
+## Prerequisites
+- Phantom browser extension installed with Bitcoin enabled.
+- Node.js >= 18
+- A workspace install at the repo root (this package depends on `@arkade-os/sdk` via workspaces).
+
+## Getting Started
+From the repository root:
+```bash
+# install workspace deps
+pnpm install
+
+# run this example
+pnpm --filter phantom-example dev
+# or
+cd examples/phantom-example && pnpm dev
+```
+
+Open the app at the URL printed by Vite. Click “Connect Phantom” to authorize the dApp. The UI will:
+1) Show your BTC address from Phantom.
+2) Build a basic transaction with Arkade SDK.
+3) Request Phantom to sign and broadcast it, then display the transaction id.
+
+## Notes
+- Ensure you have sufficient funds for the selected network (testnet or mainnet as configured in the app).
+- The example is for educational purposes; do not use with large amounts.
+
+## Troubleshooting
+- If the connect button is disabled, verify Phantom is installed and Bitcoin is enabled in its settings.
+- Open the browser console for provider injection errors (e.g., `window.phantom?.bitcoin`).
+- If using pnpm workspaces, Vite may need to restart after the initial `@arkade-os/sdk` build completes.

examples/phantom-example/src/index.css (1)

1-69: Run Prettier via pnpm exec
CI is failing Prettier formatting on your CSS. Format and verify with the following commands:

pnpm exec prettier --write examples/phantom-example/src/index.css
pnpm exec prettier --check src test examples

• Target file:
– examples/phantom-example/src/index.css

🧹 Nitpick comments (8)

examples/phantom-example/.gitignore (1)
1-25: Ignore environment files

Examples frequently use .env for quick configuration. Add these patterns to avoid accidentally committing secrets.

Apply this diff to append common env patterns:
 *.sw?
+
+# Env files
+.env
+.env.local
+.env.*.local
examples/phantom-example/package.json (1)
1-28: Optional: declare Node engine to match Vite requirements

Vite typically requires a modern Node version. Declaring engines helps avoid local env drift in examples.

Apply this diff to add engines:
   "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "scripts": {
examples/phantom-example/eslint.config.js (2)
8-8: Ignore node_modules in ESLint flat config

Flat configs don’t ignore node_modules by default. Add it to the global ignores so ESLint doesn’t traverse dependencies.

Apply:
-  globalIgnores(['dist']),
+  globalIgnores(['dist', 'node_modules']),
17-23: Duplicate/contradictory ecmaVersion settings

You set ecmaVersion: 2020 in languageOptions and ecmaVersion: 'latest' in parserOptions. Use a single source of truth (prefer languageOptions with 'latest') and drop the duplicate.

Apply:
-    languageOptions: {
-      ecmaVersion: 2020,
+    languageOptions: {
+      ecmaVersion: 'latest',
       globals: globals.browser,
       parserOptions: {
-        ecmaVersion: 'latest',
         ecmaFeatures: { jsx: true },
         sourceType: 'module',
       },
     },
examples/phantom-example/src/App.jsx (3)
25-31: Avoid shadowing state name and improve readability

You shadow txid (state) with a local const. Rename the local to reduce confusion.
-      const txid = await wallet.send({
+      const newTxid = await wallet.send({
         amount: 1000,
         address: address,
       });
-
-      setTxid(txid);
+      setTxid(newTxid);
37-46: Guard empty account lists and surface a user hint

Phantom may return an empty array. Guard and provide a helpful message.
       const accounts = await provider.requestAccounts();
-      setAddress(accounts[0]);
+      if (!accounts || accounts.length === 0) {
+        console.warn('No Bitcoin accounts returned by Phantom');
+        alert('No Bitcoin accounts found in Phantom.');
+        return;
+      }
+      setAddress(accounts[0]);
24-28: Safety: ship the example on testnet by default

Examples that fire real mainnet transactions can lead to accidental fund loss. Consider defaulting to networks.testnet for the sample, with a comment showing how to switch to mainnet.
-      const wallet = new OnchainWallet(phantomIdentity, networks.mainnet);
+      // For safety in examples, default to testnet. Switch to networks.mainnet for production.
+      const wallet = new OnchainWallet(phantomIdentity, networks.testnet);
examples/phantom-example/index.html (1)
7-7: Use a descriptive title for the example

Use a product-specific title so users know what they’re viewing.
-    <title>Vite + React</title>
+    <title>Arkade SDK Phantom Example</title>

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

MCP integration is disabled by default for public repositories
Jira integration is disabled by default for public repositories
Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between a719593 and f1f8a71.

⛔ Files ignored due to path filters (2)

examples/phantom-example/public/vite.svg is excluded by !**/*.svg
examples/phantom-example/src/assets/react.svg is excluded by !**/*.svg

📒 Files selected for processing (11)

.husky/pre-commit (0 hunks)
examples/phantom-example/.gitignore (1 hunks)
examples/phantom-example/README.md (1 hunks)
examples/phantom-example/eslint.config.js (1 hunks)
examples/phantom-example/index.html (1 hunks)
examples/phantom-example/package.json (1 hunks)
examples/phantom-example/src/App.css (1 hunks)
examples/phantom-example/src/App.jsx (1 hunks)
examples/phantom-example/src/index.css (1 hunks)
examples/phantom-example/src/main.jsx (1 hunks)
examples/phantom-example/vite.config.js (1 hunks)

💤 Files with no reviewable changes (1)

.husky/pre-commit

🧰 Additional context used

🧬 Code Graph Analysis (1)

examples/phantom-example/src/App.jsx (3)

src/index.ts (1)

Transaction (192-192)

src/wallet/serviceWorker/response.ts (1)

error (43-50)

src/wallet/serviceWorker/request.ts (1)

Sign (158-162)

🪛 GitHub Actions: CI

examples/phantom-example/src/index.css