Hermis - Headless Solana Wallet Adapter

Overview

Version 2 of Hermis adds major new features while maintaining compatibility with existing code. This release introduces @solana/kit support, enhanced error handling, and standardizes provider interfaces.

What’s New

1. @solana/kit Architecture Support

V2 adds full support for @solana/kit alongside @solana/web3.js. Here’s how Hermis simplifies Kit transaction creation:

import {
  pipe,
  createTransactionMessage,
  setTransactionMessageFeePayerSigner,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstruction
} from '@solana/kit';
import { getTransferSolInstruction } from '@solana-program/system';

const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();

const message = pipe(
  createTransactionMessage({ version: 0 }),
  m => setTransactionMessageFeePayerSigner(transactionSigner, m),
  m => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, m),
  m => appendTransactionMessageInstruction(
    getTransferSolInstruction({
      source: fromAddress,
      destination: toAddress,
      amount: lamports(1000000n)
    }),
    m
  )
);

const signature = await signAndSendTransaction(message, rpc);

import { createKitTransaction } from '@hermis/solana-headless-react';
import { getTransferSolInstruction } from '@solana-program/system';

const instruction = getTransferSolInstruction({
  source: fromAddress,
  destination: toAddress,
  amount: lamports(1000000n)
});

const message = await createKitTransaction(
  rpc,
  fromAddress,
  [instruction]
);

const signature = await signAndSendTransaction(message, rpc);

Why use createKitTransaction?

70% less boilerplate - No pipe pattern or nested callbacks
Automatic blockhash fetching - One less async call to manage
Batch instruction handling - Pass multiple instructions as array
Dual architecture support - Works with web3.js Connection or Kit Rpc
Beginner-friendly - Imperative style, easier to understand

Key Features:

Dual architecture support - use web3.js OR Kit in the same app
Automatic transaction type detection
Kit-friendly wallet properties (transactionSigner, messageSigner, address)
Helper utilities for Kit development

2. Enhanced Error Handling

New @hermis/errors package with structured error codes:

import { HermisError, isHermisError } from '@hermis/errors';

try {
  await signTransaction(tx);
} catch (error) {
  if (isHermisError(error)) {
    console.log(error.code);        // Structured error code
    console.log(error.context);     // Rich context with wallet/transaction details
    console.log(error.getSolution()); // Actionable guidance
  }
}

3. New Utility Hooks

Additional hooks for common operations:

import {
  useSolanaBalance,
  useSolanaTokenAccounts,
  useSolanaNFTs,
  useSolanaTransaction,
  useWalletAdapters
} from '@hermis/solana-headless-react';

// Fetch balance with automatic updates
const { balance, loading } = useSolanaBalance(publicKey);

// Get token accounts
const { tokenAccounts } = useSolanaTokenAccounts(publicKey);

// Fetch NFTs
const { nfts } = useSolanaNFTs(publicKey);

4. Wallet Standard Compliance

Improved wallet detection with CAIP-2 compliant chain identifiers:

✅ solana:mainnet
✅ solana:devnet
✅ solana:testnet

Breaking Changes (Pre-Release Users Only)

If you were using HermisProvider in early/pre-release versions, the following props were renamed for consistency:

`signMessage` now applies the Solana off-chain message domain separator on local-key paths

When the SDK signs a message with an in-SDK key (Keypair, CryptoKeyPair, KeyPairSigner), it now prepends the Solana off-chain message header (0xff + "solana offchain" + version + format + length) before signing. Without this domain separator, signature bytes are structurally indistinguishable from a Solana transaction signature, and a caller can be tricked into producing a valid transaction signature by handing the signer bytes that happen to encode a Solana transaction message. This is a behaviour change for local-key signers only. External wallets (Phantom / Backpack / Solflare / any Standard Wallet or Adapter) already apply this header themselves — those paths are unchanged. If you verify these signatures server-side, apply the same domain header to the message before verification:

const SIGNING_DOMAIN = Buffer.concat([
  Buffer.from([0xff]),
  Buffer.from('solana offchain', 'utf-8'),
]);

function withOffchainPrefix(message: Uint8Array): Uint8Array {
  const header = Buffer.alloc(4);
  header.writeUInt8(0, 0);                // header version
  header.writeUInt8(1, 1);                // format: UTF-8
  header.writeUInt16LE(message.length, 2); // length, LE
  return Buffer.concat([SIGNING_DOMAIN, header, Buffer.from(message)]);
}

// Then verify against the wrapped bytes:
nacl.sign.detached.verify(withOffchainPrefix(originalMessage), signature, publicKey);

Explicit network required (no more URL inference)

v2 removes substring-based cluster inference from RPC endpoint URLs. URLs whose path happens to contain mainnet or devnet were silently classified as that cluster — unsafe whenever the URL came from an untrusted source. getStandardWalletAdapters and createWalletConnectionManager now require an explicit network argument:

import { getStandardWalletAdapters } from '@hermis/solana-headless-adapter-base';

const adapters = await getStandardWalletAdapters(wallets, endpoint);

import { getStandardWalletAdapters } from '@hermis/wallet-standard-base';
import { WalletAdapterNetwork } from '@hermis/solana-headless-core';

const adapters = await getStandardWalletAdapters(
  wallets,
  endpoint,
  WalletAdapterNetwork.Mainnet, // required
);

detectClusterFromEndpoint and getInferredNetworkFromEndpoint have been removed from the public API. StandardWalletAdapter no longer derives its cluster from setRpcEndpoint; call the new setNetwork(network) method instead — HermisProvider does this automatically when you pass network. HermisProvider’s network prop was already required after v2.0; no change is needed there.

HermisProvider Props Standardized

To match WalletProvider interface and follow web3.js conventions:

<HermisProvider
  rpcEndpoint="https://devnet.solana.com"
  additionalAdapters={wallets}
>
  {children}
</HermisProvider>

<HermisProvider
  endpoint="https://devnet.solana.com"
  wallets={wallets}
>
  {children}
</HermisProvider>

Changes:

rpcEndpoint → endpoint (matches web3.js Connection pattern)
additionalAdapters → wallets (matches WalletProvider interface)

Migration Steps

Update HermisProvider Props (if using)

If you’re using HermisProvider, update prop names:

Change rpcEndpoint to endpoint
Change additionalAdapters to wallets

Optionally Adopt Kit Architecture

Start using Kit features where beneficial - access Kit-specific properties from useWallet()

Upgrade Error Handling

Implement enhanced error handling with the new @hermis/errors package

Test Your Application

Test all wallet operations to ensure everything works correctly

Example: Before and After

Using HermisProvider

import { HermisProvider } from '@hermis/solana-headless-react';

function App() {
  // Auto-detect wallet-standard compatible wallets
  const wallets = []; // Add custom wallet adapters here if needed

  return (
    <HermisProvider
      rpcEndpoint="https://devnet.solana.com"
      additionalAdapters={wallets}
    >
      <WalletButton />
    </HermisProvider>
  );
}

import { HermisProvider } from '@hermis/solana-headless-react';

function App() {
  // Auto-detect wallet-standard compatible wallets
  const wallets = []; // Add custom wallet adapters here if needed

  return (
    <HermisProvider
      endpoint="https://devnet.solana.com"
      wallets={wallets}
    >
      <WalletButton />
    </HermisProvider>
  );
}

Using WalletProvider

No changes needed - WalletProvider interface is unchanged:

import { WalletProvider, ConnectionProvider } from '@hermis/solana-headless-react';

function App() {
  return (
    <ConnectionProvider endpoint="https://devnet.solana.com">
      <WalletProvider wallets={wallets}>
        <YourApp />
      </WalletProvider>
    </ConnectionProvider>
  );
}

New Features Deep Dive

Dual Architecture Support

All transaction methods now support both architectures automatically:

import { useWallet } from '@hermis/solana-headless-react';
import { Transaction } from '@solana/web3.js';
import { createTransactionMessage } from '@solana/kit';

const { signTransaction } = useWallet();

// Works with web3.js
const web3Tx = new Transaction();
await signTransaction(web3Tx);

// Also works with Kit
const kitTx = createTransactionMessage({ version: 0 });
await signTransaction(kitTx);

// Same method, both architectures! ✨

Kit-Friendly Properties

New properties added to useWallet() hook for Kit development:

const {
  // Kit-specific properties (NEW in v2)
  address,              // Kit Address type
  addressString,        // Plain string address
  chain,                // Chain identifier (e.g., 'solana:devnet')
  messageSigner,        // Kit MessageModifyingSigner
  transactionSigner,    // Kit TransactionSendingSigner
  getChainId,           // Get chain ID for network

  // Existing web3.js properties (unchanged)
  publicKey,
  connected,
  connect,
  disconnect,
  signTransaction,
  // ... all other existing properties
} = useWallet();

Helper Utilities

New Kit helper functions:

import {
  createKitTransaction,
  generateKitKeypair,
  signTransactionWithSigner,
  createRPCConnection,
  isKitTransaction,
  supportsKitArchitecture
} from '@hermis/solana-headless-react';

Backwards Compatibility

All existing web3.js code continues to work without modification

// Your existing code - still works perfectly!
import { useWallet } from '@hermis/solana-headless-react';
import { Transaction, SystemProgram } from '@solana/web3.js';

const { signTransaction, sendTransaction } = useWallet();
const tx = new Transaction();
// ... add instructions
await signTransaction(tx);

Need Help?

GitHub Discussions

Ask questions and get help from the community

Report Issues

Report bugs or migration issues

API Reference

Explore the complete API documentation

Kit Guide

Learn about Kit architecture support

​Overview

​What’s New

​1. @solana/kit Architecture Support

​2. Enhanced Error Handling

​3. New Utility Hooks

​4. Wallet Standard Compliance

​Breaking Changes (Pre-Release Users Only)

​signMessage now applies the Solana off-chain message domain separator on local-key paths

​Explicit network required (no more URL inference)

​HermisProvider Props Standardized

​Migration Steps

​Example: Before and After

​Using HermisProvider

​Using WalletProvider

​New Features Deep Dive

​Dual Architecture Support

​Kit-Friendly Properties

​Helper Utilities

​Backwards Compatibility

​Need Help?