> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hermis.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# What's New in v2

> Guide for updating to Hermis v2

## 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:

<CodeGroup>
  ```typescript Standard Kit Pattern theme={null}
  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);
  ```

  ```typescript With createKitTransaction Helper theme={null}
  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);
  ```
</CodeGroup>

**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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

<CodeGroup>
  ```typescript Before (v1) theme={null}
  import { getStandardWalletAdapters } from '@hermis/solana-headless-adapter-base';

  const adapters = await getStandardWalletAdapters(wallets, endpoint);
  ```

  ```typescript After (v2) theme={null}
  import { getStandardWalletAdapters } from '@hermis/wallet-standard-base';
  import { WalletAdapterNetwork } from '@hermis/solana-headless-core';

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

`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:

<CodeGroup>
  ```tsx Before theme={null}
  <HermisProvider
    rpcEndpoint="https://devnet.solana.com"
    additionalAdapters={wallets}
  >
    {children}
  </HermisProvider>
  ```

  ```tsx After (v2) theme={null}
  <HermisProvider
    endpoint="https://devnet.solana.com"
    wallets={wallets}
  >
    {children}
  </HermisProvider>
  ```
</CodeGroup>

**Changes:**

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

## Migration Steps

<Steps>
  <Step title="Update HermisProvider Props (if using)">
    If you're using HermisProvider, update prop names:

    * Change `rpcEndpoint` to `endpoint`
    * Change `additionalAdapters` to `wallets`
  </Step>

  <Step title="Optionally Adopt Kit Architecture">
    Start using Kit features where beneficial - access Kit-specific properties from `useWallet()`
  </Step>

  <Step title="Upgrade Error Handling">
    Implement enhanced error handling with the new `@hermis/errors` package
  </Step>

  <Step title="Test Your Application">
    Test all wallet operations to ensure everything works correctly
  </Step>
</Steps>

## Example: Before and After

### Using HermisProvider

<CodeGroup>
  ```tsx Before (Pre-Release) theme={null}
  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>
    );
  }
  ```

  ```tsx After (v2) theme={null}
  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>
    );
  }
  ```
</CodeGroup>

### Using WalletProvider

**No changes needed** - WalletProvider interface is unchanged:

```tsx theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

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

## Backwards Compatibility

**All existing web3.js code continues to work without modification**

```typescript theme={null}
// 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?

<CardGroup cols={2}>
  <Card title="GitHub Discussions" icon="comments" href="https://github.com/Assylum-Labs/hermis/discussions">
    Ask questions and get help from the community
  </Card>

  <Card title="Report Issues" icon="github" href="https://github.com/Assylum-Labs/hermis/issues">
    Report bugs or migration issues
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/react/overview">
    Explore the complete API documentation
  </Card>

  <Card title="Kit Guide" icon="book" href="/guides/kit-architecture">
    Learn about Kit architecture support
  </Card>
</CardGroup>