Action Codes Wallet Adapter

A Solana Wallet Adapter plugin that lets users connect and sign using Action Codes — short, one-time codes generated by a mobile wallet for remote signing.

Install

npm install @actioncodes/wallet-adapter @solana/wallet-adapter-base @solana/web3.js

Quick Start

import { ActionCodesWalletAdapter } from '@actioncodes/wallet-adapter';
import { clusterApiUrl } from '@solana/web3.js';

const wallets = [
  new ActionCodesWalletAdapter({
    authToken: 'YOUR_AUTH_TOKEN',
    connection: clusterApiUrl('devnet'),
    environment: 'devnet',
  }),
];

Pass the wallets array to <WalletProvider> from @solana/wallet-adapter-react — "Action Codes" will appear alongside other wallets in the selection UI.

Configuration

| Option | Type | Default | Description | |---|---|---|---| | authToken | string | required | Bearer token for the Action Codes relay API | | connection | Connection \| string | required | Solana RPC connection or endpoint URL | | environment | 'mainnet' \| 'devnet' \| 'local' | 'mainnet' | Which Action Codes relay to use | | relayerUrl | string | — | Custom relay URL (overrides environment) | | theme | 'auto' \| 'light' \| 'dark' | 'auto' | Modal theme (auto follows system preference) | | debug | boolean | false | Log adapter events to the console |

How It Works

1. User selects Action Codes in the wallet picker
2. A modal opens — user enters the code displayed on their wallet
3. The adapter resolves the code to the user's public key (connect)
4. When the dApp calls signMessage, signTransaction, or sendTransaction:
   • The payload is attached to the code via the relay
   • The modal shows "Approve in wallet…"
   • The wallet holder approves on their device
   • The signed result is returned to the dApp
5. Action codes are one-time-use — the adapter auto-disconnects after each signing operation

Supported Operations

• signMessage(msg) — sign an arbitrary message (message must be valid UTF-8)
• signTransaction(tx) — sign and return a transaction (legacy or versioned)
• sendTransaction(tx, connection) — sign, execute on-chain, and return the tx hash

Note: Action codes are one-time-use. signAllTransactions is not supported — calling it with multiple transactions will succeed on the first and throw WalletNotConnectedError on subsequent ones, because the code is consumed after the first signature.

Environment Mapping

| environment | Relay URL | Use with | |---|---|---| | 'mainnet' | https://relay.actioncodes.org | Mainnet-beta | | 'devnet' | https://dev.relay.actioncodes.org | Devnet / Testnet | | 'local' | http://localhost:4000 | Local development |

Examples

• examples/react-usage.tsx — React integration with @solana/wallet-adapter-react
• examples/test-harness.html — Standalone browser test page

Development

npm install
npm run build       # ESM + CJS + .d.ts via tsup
npm run typecheck   # tsc --noEmit
npm run dev         # watch mode

Testing

Tests use Vitest with happy-dom for DOM emulation.

npm test            # run once
npm run test:watch  # watch mode

The modal component has 45 tests covering:

• Creation, destruction, and DOM lifecycle
• Code input validation (length, character set)
• Event dispatching (submit, cancel, keyboard shortcuts)
• Help tooltip toggle
• State transitions (input, resolving, approve, success, error)
• Reset behavior
• Error display and clearing
• Theme attribute reflection

License

Apache-2.0