feat: add sign-with-wallet-adapter React example (#29)

* feat: add sign-with-wallet-adapter React example

Adds a Wallet Adapter equivalent of the existing Privy example.
Swaps the signing layer from Privy SDK to @solana/wallet-adapter-react
while keeping identical Light Token SDK usage (transfer, wrap, unwrap).

Changes from Privy example:
- ConnectionProvider + WalletProvider + WalletModalProvider (replaces PrivyProvider)
- useWallet().signTransaction (replaces useSignTransaction from Privy)
- signAndSendBatches takes signTransaction(Transaction) -> Transaction
- WalletMultiButton for connect/disconnect (replaces Privy login/logout)
- Removed wallet selector (single connected wallet)
- Fixed hot/cold balance fetch order (cold before hot) so compressed-only
  mints also get hot balance lookup

26 unit tests passing, build clean.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: add confirmTransaction to useWrap, expand README

- useWrap now awaits confirmTransaction after sendRawTransaction,
  matching the behavior of signAndSendBatches (used by transfer/unwrap)
- Added confirmTransaction assertion to wrap test
- README expanded to match Privy example quality: hook docs, component
  docs, setup helpers table, quick start guide

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* test: add e2e integration test for wallet-adapter hooks

Tests useUnifiedBalance, useTransfer, and useTransactionHistory against
devnet using filesystem keypair signing. Creates a fresh mint with SPL
interface, mints tokens, wraps to light-token, then exercises the full
transfer + balance + history flow.

Run: VITE_HELIUS_RPC_URL=<url> pnpm test:integration

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* test: add localnet mode to e2e integration test

Support both devnet and localnet testing:
- VITE_HELIUS_RPC_URL=<url> for devnet (Helius bundles compression API)
- VITE_LOCALNET=true for localnet (createRpc() uses default ports 8899/8784/3001)
- Localnet mode airdrops SOL before running tests

Note: localnet currently blocked by CLI/SDK version mismatch (CLI v0.27.0
programs don't match SDK v0.23.0-beta.9 instructions). Devnet tests pass.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Apply suggestions from code review

Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* fix: resolve Devin review — fetch mint decimals, consistent Math.round

- useUnifiedBalance: fetch actual mint decimals via getMint() instead of
  hardcoding 9 (fixes wrong display/amounts for USDC and other non-9
  decimal tokens)
- useWrap, useUnwrap: align on Math.round to match useTransfer (all 3
  hooks now consistent)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: apply same decimals + Math.round fixes to Privy example

Mirror of the wallet-adapter fixes:
- useUnifiedBalance: fetch actual mint decimals via getMint()
- useUnifiedBalance: fix hot/cold fetch order (cold before hot) so mints
  discovered only via compressed accounts also get hot balance lookup
- useTransfer, useWrap, useUnwrap: Math.floor → Math.round

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: pass correct programId to getMint for Token 2022 mints

getMint() defaults to TOKEN_PROGRAM_ID, silently failing for T22 mints
and falling back to hardcoded decimals: 9. Track tokenProgram per mint
in mintMap and pass it through to getMint().

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: refactor Node.js balance snippet to store raw bigints

Same four bugs as React versions:
- toUiAmount(amount, 9) called early, hardcoding 9 decimals
- Hot balance fetched before cold (ordering bug)
- decimals: 9 never updated from on-chain
- No tokenProgram tracking for T22 getMint

Refactored to store raw bigint values in accumulator and convert
to UI amounts at assembly time using actual mint decimals.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: add wallet-adapter and sponsor-rent-top-ups to READMEs

List all 5 toolkits in both root and toolkits README. Add missing
pinocchio-swap to program examples table.

Entire-Checkpoint: 4afa49be1970

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: tilo-14 <tilo@luminouslabs.org>
Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: tilo-14 <tilo@luminouslabs.com>

Author: 5 people

README.md

@@ -13,6 +13,7 @@ Light token is a high-performance token standard that reduces the cost of mint a
 | [Payments and Wallets](toolkits/payments-and-wallets/) | All you need for wallet integrations and payment flows. Minimal API differences to SPL. |
 | [Streaming Tokens](toolkits/streaming-tokens/) | Stream mint events using Laserstream |
 | [Sign with Privy](toolkits/sign-with-privy/) | Light-token operations signed with Privy wallets (Node.js + React) |
+| [Sign with Wallet Adapter](toolkits/sign-with-wallet-adapter/) | Sign light-token transactions with Wallet Adapter (React) |
 | [Sponsor Rent Top-Ups](toolkits/sponsor-rent-top-ups/) | Sponsor rent top-ups for users by setting your application as the fee payer |
 
 ## Client Examples

toolkits/README.md

@@ -19,6 +19,11 @@ Light-token operations signed with [Privy](https://privy.io) wallets. Server-sid
 - **[React](sign-with-privy/react/)** — Browser app using `@privy-io/react-auth` with embedded wallet signing
 - **[Setup scripts](sign-with-privy/scripts/)** — Create test mints and fund wallets on devnet
 
+### Sign with Wallet Adapter
+
+Sign light-token transactions with [Wallet Adapter](https://github.com/anza-xyz/wallet-adapter). Transfer, wrap, unwrap, and balance queries.
+- **[React](sign-with-wallet-adapter/react/)** — Browser app using `@solana/wallet-adapter-react` with Phantom, Backpack, Solflare, etc.
+
 ### Streaming Tokens
 
 [Rust program example to stream mint events](streaming-tokens/) of the Light-Token Program.

toolkits/sign-with-privy/nodejs/src/balances.ts

@@ -1,6 +1,6 @@
 import 'dotenv/config';
 import {PublicKey, LAMPORTS_PER_SOL} from '@solana/web3.js';
-import {TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID} from '@solana/spl-token';
+import {TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, getMint} from '@solana/spl-token';
 import {createRpc} from '@lightprotocol/stateless.js';
 import {
   getAtaInterface,
@@ -36,13 +36,13 @@ export async function getBalances(
     console.error('Failed to fetch SOL balance:', e);
   }
 
-  // Per-mint accumulator
-  const mintMap = new Map<string, {spl: number; t22: number; hot: number; cold: number; decimals: number}>();
+  // Per-mint accumulator (raw values, converted at assembly)
+  const mintMap = new Map<string, {spl: bigint; t22: bigint; hot: bigint; cold: bigint; decimals: number; tokenProgram: PublicKey}>();
 
   const getOrCreate = (mintStr: string) => {
     let entry = mintMap.get(mintStr);
     if (!entry) {
-      entry = {spl: 0, t22: 0, hot: 0, cold: 0, decimals: 9};
+      entry = {spl: 0n, t22: 0n, hot: 0n, cold: 0n, decimals: 9, tokenProgram: TOKEN_PROGRAM_ID};
       mintMap.set(mintStr, entry);
     }
     return entry;
@@ -59,7 +59,7 @@ export async function getBalances(
       const mint = new PublicKey(buf.subarray(0, 32));
       const amount = buf.readBigUInt64LE(64);
       const mintStr = mint.toBase58();
-      getOrCreate(mintStr).spl += toUiAmount(amount, 9);
+      getOrCreate(mintStr).spl += amount;
     }
   } catch {
     // No SPL accounts
@@ -76,49 +76,66 @@ export async function getBalances(
       const mint = new PublicKey(buf.subarray(0, 32));
       const amount = buf.readBigUInt64LE(64);
       const mintStr = mint.toBase58();
-      getOrCreate(mintStr).t22 += toUiAmount(amount, 9);
+      const entry = getOrCreate(mintStr);
+      entry.t22 += amount;
+      entry.tokenProgram = TOKEN_2022_PROGRAM_ID;
     }
   } catch {
     // No Token 2022 accounts
   }
 
-  // 3. Hot balance from Light Token associated token account
+  // 3. Cold balance from compressed token accounts
+  try {
+    const compressed = await rpc.getCompressedTokenBalancesByOwnerV2(owner);
+    for (const item of compressed.value.items) {
+      const mintStr = item.mint.toBase58();
+      getOrCreate(mintStr).cold += BigInt(item.balance.toString());
+    }
+  } catch {
+    // No compressed accounts
+  }
+
+  // 4. Fetch actual decimals for each mint
   const mintKeys = [...mintMap.keys()];
+  await Promise.allSettled(
+    mintKeys.map(async (mintStr) => {
+      try {
+        const mint = new PublicKey(mintStr);
+        const entry = getOrCreate(mintStr);
+        const mintInfo = await getMint(rpc, mint, undefined, entry.tokenProgram);
+        entry.decimals = mintInfo.decimals;
+      } catch {
+        // Keep default decimals if mint fetch fails
+      }
+    }),
+  );
+
+  // 5. Hot balance from Light Token associated token account
   await Promise.allSettled(
     mintKeys.map(async (mintStr) => {
       try {
         const mint = new PublicKey(mintStr);
         const ata = getAssociatedTokenAddressInterface(mint, owner);
         const {parsed} = await getAtaInterface(rpc, ata, owner, mint);
-        getOrCreate(mintStr).hot = toUiAmount(parsed.amount, 9);
+        getOrCreate(mintStr).hot = BigInt(parsed.amount.toString());
       } catch {
         // Associated token account does not exist for this mint
       }
     }),
   );
 
-  // 4. Cold balance from compressed token accounts
-  try {
-    const compressed = await rpc.getCompressedTokenBalancesByOwnerV2(owner);
-    for (const item of compressed.value.items) {
-      const mintStr = item.mint.toBase58();
-      getOrCreate(mintStr).cold += toUiAmount(BigInt(item.balance.toString()), 9);
-    }
-  } catch {
-    // No compressed accounts
-  }
-
-  // Assemble result
+  // 6. Assemble result (convert raw → UI amounts here)
   const tokens: TokenBalance[] = [];
   for (const [mintStr, entry] of mintMap) {
+    const d = entry.decimals;
     tokens.push({
       mint: mintStr,
-      decimals: entry.decimals,
-      hot: entry.hot,
-      cold: entry.cold,
-      spl: entry.spl,
-      t22: entry.t22,
-      unified: entry.hot + entry.cold,
+      decimals: d,
+      hot: toUiAmount(entry.hot, d),
+      cold: toUiAmount(entry.cold, d),
+      spl: toUiAmount(entry.spl, d),
+      t22: toUiAmount(entry.t22, d),
+      unified: toUiAmount(entry.hot + entry.cold, d),
     });
   }
 
@@ -131,9 +148,8 @@ function toBuffer(data: Buffer | Uint8Array | string | unknown): Buffer | null {
   return null;
 }
 
-function toUiAmount(raw: bigint | {toNumber: () => number}, decimals: number): number {
-  const value = typeof raw === 'bigint' ? Number(raw) : raw.toNumber();
-  return value / 10 ** decimals;
+function toUiAmount(raw: bigint, decimals: number): number {
+  return Number(raw) / 10 ** decimals;
 }
 
 export default getBalances;

toolkits/sign-with-privy/react/src/hooks/useTransfer.ts

@@ -39,7 +39,7 @@ export function useTransfer() {
       const owner = new PublicKey(ownerPublicKey);
       const mintPubkey = new PublicKey(mint);
       const recipient = new PublicKey(toAddress);
-      const tokenAmount = Math.floor(amount * Math.pow(10, decimals));
+      const tokenAmount = Math.round(amount * Math.pow(10, decimals));
 
       // Returns TransactionInstruction[][].
       // Each inner array is one transaction.

toolkits/sign-with-privy/react/src/hooks/useUnifiedBalance.ts

@@ -1,6 +1,6 @@
 import { useState, useCallback } from 'react';
 import { PublicKey, LAMPORTS_PER_SOL } from '@solana/web3.js';
-import { TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID } from '@solana/spl-token';
+import { TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, getMint } from '@solana/spl-token';
 import { createRpc } from '@lightprotocol/stateless.js';
 import {
   getAssociatedTokenAddressInterface,
@@ -31,12 +31,12 @@ export function useUnifiedBalance() {
       const owner = new PublicKey(ownerAddress);
 
       // Per-mint accumulator
-      const mintMap = new Map<string, { spl: bigint; t22: bigint; hot: bigint; cold: bigint; decimals: number }>();
+      const mintMap = new Map<string, { spl: bigint; t22: bigint; hot: bigint; cold: bigint; decimals: number; tokenProgram: PublicKey }>();
 
       const getOrCreate = (mintStr: string) => {
         let entry = mintMap.get(mintStr);
         if (!entry) {
-          entry = { spl: 0n, t22: 0n, hot: 0n, cold: 0n, decimals: 9 };
+          entry = { spl: 0n, t22: 0n, hot: 0n, cold: 0n, decimals: 9, tokenProgram: TOKEN_PROGRAM_ID };
           mintMap.set(mintStr, entry);
         }
         return entry;
@@ -78,14 +78,41 @@ export function useUnifiedBalance() {
           const mint = new PublicKey(buf.subarray(0, 32));
           const amount = buf.readBigUInt64LE(64);
           const mintStr = mint.toBase58();
-          getOrCreate(mintStr).t22 += amount;
+          const entry = getOrCreate(mintStr);
+          entry.t22 += amount;
+          entry.tokenProgram = TOKEN_2022_PROGRAM_ID;
         }
       } catch {
         // No Token 2022 accounts
       }
 
-      // 4. Hot balance from Light Token associated token account
+      // 4. Cold balance from compressed token accounts
+      try {
+        const compressed = await rpc.getCompressedTokenBalancesByOwnerV2(owner);
+        for (const item of compressed.value.items) {
+          const mintStr = item.mint.toBase58();
+          getOrCreate(mintStr).cold += BigInt(item.balance.toString());
+        }
+      } catch {
+        // No compressed accounts
+      }
+
+      // 5. Fetch actual decimals for each mint
       const mintKeys = [...mintMap.keys()];
+      await Promise.allSettled(
+        mintKeys.map(async (mintStr) => {
+          try {
+            const mint = new PublicKey(mintStr);
+            const entry = getOrCreate(mintStr);
+            const mintInfo = await getMint(rpc, mint, undefined, entry.tokenProgram);
+            entry.decimals = mintInfo.decimals;
+          } catch {
+            // Keep default decimals if mint fetch fails
+          }
+        }),
+      );
+
+      // 6. Hot balance from Light Token associated token account
       await Promise.allSettled(
         mintKeys.map(async (mintStr) => {
           try {
@@ -100,18 +127,7 @@ export function useUnifiedBalance() {
         }),
       );
 
-      // 5. Cold balance from compressed token accounts
-      try {
-        const compressed = await rpc.getCompressedTokenBalancesByOwnerV2(owner);
-        for (const item of compressed.value.items) {
-          const mintStr = item.mint.toBase58();
-          getOrCreate(mintStr).cold += BigInt(item.balance.toString());
-        }
-      } catch {
-        // No compressed accounts
-      }
-
-      // 6. Assemble TokenBalance[]
+      // 7. Assemble TokenBalance[]
       const result: TokenBalance[] = [];
 
       // SOL entry

toolkits/sign-with-privy/react/src/hooks/useUnwrap.ts

@@ -38,7 +38,7 @@ export function useUnwrap() {
 
       const owner = new PublicKey(ownerPublicKey);
       const mintPubkey = new PublicKey(mint);
-      const tokenAmount = BigInt(Math.floor(amount * Math.pow(10, decimals)));
+      const tokenAmount = BigInt(Math.round(amount * Math.pow(10, decimals)));
 
       // Auto-detect token program (SPL vs T22) from mint account owner
       const mintAccountInfo = await rpc.getAccountInfo(mintPubkey);

toolkits/sign-with-privy/react/src/hooks/useWrap.ts

@@ -40,7 +40,7 @@ export function useWrap() {
 
       const owner = new PublicKey(ownerPublicKey);
       const mintPubkey = new PublicKey(mint);
-      const tokenAmount = BigInt(Math.floor(amount * Math.pow(10, decimals)));
+      const tokenAmount = BigInt(Math.round(amount * Math.pow(10, decimals)));
 
       // Get SPL interface info — determines whether mint uses SPL or T22
       const splInterfaceInfos = await getSplInterfaceInfos(rpc, mintPubkey);

toolkits/sign-with-wallet-adapter/react/README.md

@@ -0,0 +1,122 @@
+# Wallet Adapter + Light Token (React)
+
+Wallet Adapter handles wallet connection and transaction signing. You build transactions with light-token instructions and the connected wallet signs them client-side:
+
+1. Connect wallet via Wallet Adapter
+2. Build unsigned transaction
+3. Sign transaction using connected wallet (Phantom, Backpack, Solflare, etc.)
+4. Send signed transaction to RPC
+
+Light Token gives you rent-free token accounts on Solana. Light-token accounts hold balances from any light, SPL, or Token-2022 mint.
+
+
+## What you will implement
+
+| | SPL | Light Token |
+| --- | --- | --- |
+| [**Transfer**](#hooks) | `transferChecked()` | `createTransferInterfaceInstruction()` |
+| [**Wrap**](#hooks) | N/A | `createWrapInstruction()` |
+| [**Get balance**](#hooks) | `getAccount()` | `getAtaInterface()` |
+| [**Transaction history**](#hooks) | `getSignaturesForAddress()` | `getSignaturesForOwnerInterface()` |
+
+### Source files
+
+#### Hooks
+
+- **[useTransfer.ts](src/hooks/useTransfer.ts)** — Transfer light-tokens between wallets. Auto-loads cold balance before sending.
+- **[useWrap.ts](src/hooks/useWrap.ts)** — Wrap SPL or T22 tokens into light-token associated token account. Auto-detects token program.
+- **[useUnwrap.ts](src/hooks/useUnwrap.ts)** — Unwrap light-token associated token account back to SPL or T22. Hook only, not wired into UI.
+- **[useLightBalance.ts](src/hooks/useLightBalance.ts)** — Query hot, cold, and unified Light Token balance for a single mint.
+- **[useUnifiedBalance.ts](src/hooks/useUnifiedBalance.ts)** — Query balance breakdown: SOL, SPL, Token 2022, light-token hot, and compressed cold.
+- **[useTransactionHistory.ts](src/hooks/useTransactionHistory.ts)** — Fetch transaction history for light-token operations.
+
+#### Components
+
+- **[TransferForm.tsx](src/components/sections/TransferForm.tsx)** — Single "Send" button. Routes by token type: light-token -> light-token, or SPL/Token 2022 are wrapped then transfered in one transaction.
+- **[TransactionHistory.tsx](src/components/sections/TransactionHistory.tsx)** — Recent light-token interface transactions with explorer links.
+- **[WalletInfo.tsx](src/components/sections/WalletInfo.tsx)** — Wallet address display.
+- **[TransactionStatus.tsx](src/components/sections/TransactionStatus.tsx)** — Last transaction signature with explorer link.
+
+> Light Token is currently deployed on **devnet**. The interface PDA pattern described here applies to mainnet.
+
+## Before you start
+
+### Your mint needs an SPL interface PDA
+
+The interface PDA enables interoperability between SPL/T22 and light-token. It holds SPL/T22 tokens when they're wrapped into light-token format.
+
+**Check if your mint has one:**
+
+```typescript
+import { getSplInterfaceInfos } from "@lightprotocol/compressed-token";
+
+const infos = await getSplInterfaceInfos(rpc, mint);
+const hasInterface = infos.some((info) => info.isInitialized);
+```
+
+**Register one if it doesn't:**
+
+```bash
+# For an existing SPL or T22 mint (from scripts/)
+cd ../scripts && npm run register:spl-interface <mint-address>
+```
+
+Or in code via `createSplInterface(rpc, payer, mint)`. Works with both SPL Token and Token-2022 mints.
+
+**Example: wrapping devnet USDC.** If you have devnet USDC (`4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU`), register its interface PDA first, then wrap it into a light-token associated token account. Set `TEST_MINT` in `.env` to the USDC mint address.
+
+## Setup
+
+```bash
+npm install
+cp .env.example .env
+# Fill in your credentials
+```
+
+### Environment variables
+
+| Variable | Description |
+| -------- | ----------- |
+| `VITE_HELIUS_RPC_URL` | Helius RPC endpoint (e.g. `https://devnet.helius-rpc.com?api-key=...`). Required for ZK compression indexing. |
+
+### Setup helpers (local keypair)
+
+Setup scripts live in [`scripts/`](../scripts/). They use the Solana CLI keypair at `~/.config/solana/id.json`.
+
+```bash
+cd ../scripts
+cp .env.example .env  # set HELIUS_RPC_URL
+```
+
+| Command | What it does |
+| ------- | ----------- |
+| `npm run mint:spl-and-wrap <recipient> [amount] [decimals]` | Create an SPL or T22 mint with interface PDA, mint tokens, wrap, and transfer to recipient. |
+| `npm run mint:spl <mint> <recipient> [amount] [decimals]` | Mint additional SPL or T22 tokens to an existing mint. |
+| `npm run register:spl-interface <mint>` | Register an interface PDA on an existing SPL or T22 mint. Required for wrap/unwrap. |
+
+## Quick start
+
+```bash
+# 1. Create a test mint with interface PDA + fund your wallet
+cd ../scripts && npm run mint:spl-and-wrap <your-wallet-address>
+
+# 2. Start the dev server
+cd ../react && npm run dev
+```
+
+Then in the browser:
+1. Connect your wallet via the Wallet Adapter modal
+2. Select a light-token balance from the dropdown
+3. Enter a recipient address and amount
+4. Click "Send" — the app transfers directly
+5. Select an SPL balance — the app wraps to light-token then transfers (two signing prompts)
+
+## Tests
+
+```bash
+# Unit tests (no network)
+pnpm test
+
+# Integration tests (devnet)
+VITE_HELIUS_RPC_URL=https://devnet.helius-rpc.com?api-key=... pnpm test:integration
+```