npm package: @somnia-chain/viem-session-account
Description: viem-compatible account and wallet client for Somnia session transactions
Latest version: 0.1.0

# @somnia-chain/viem-session-account

viem-compatible account and wallet client for Somnia session transactions.

Session transactions allow high-volume transaction submission on Somnia without nonce management or signing. This package provides drop-in viem primitives so you can use `sendTransaction` and `writeContract` with session RPCs seamlessly.

## Install

```bash
npm install @somnia-chain/viem-session-account viem
```

## Quick Start

```ts
import { http } from 'viem'
import { createSessionClient, somniaTestnet } from '@somnia-chain/viem-session-account'

const client = await createSessionClient({
  seed: '0xdeadbeef...', // your session seed
  chain: somniaTestnet,
  transport: http(),
})

// Send a transaction
const hash = await client.sendTransaction({
  to: '0x...',
  value: 1000000000000000000n,
})

// Write to a contract (works automatically)
const hash2 = await client.writeContract({
  address: '0x...',
  abi: myAbi,
  functionName: 'transfer',
  args: ['0x...', 100n],
})
```

## API

### `createSessionClient({ seed, chain, transport })`

Convenience function that creates a session account, wallet client, and applies the session decorator in one call. Returns a wallet client with `sendTransaction` routed through `somnia_sendSessionTransaction`.

```ts
import { http } from 'viem'
import { createSessionClient, somnia } from '@somnia-chain/viem-session-account'

const client = await createSessionClient({
  seed: '0x...',
  chain: somnia,
  transport: http(),
})
```

### `createSessionAccount(client, { seed })`

Creates a viem `LocalAccount` backed by a Somnia session seed. Calls `somnia_getSessionAddress` to derive the account address.

```ts
import { createPublicClient, http } from 'viem'
import { createSessionAccount, somniaTestnet } from '@somnia-chain/viem-session-account'

const publicClient = createPublicClient({
  chain: somniaTestnet,
  transport: http(),
})

const account = await createSessionAccount(publicClient, {
  seed: '0x...',
})

console.log(account.address) // derived from seed
console.log(account.seed)    // the original seed
```

### `sessionActions`

Client decorator that overrides `sendTransaction` to use `somnia_sendSessionTransaction`. Apply it to any wallet client via `.extend()`.

```ts
import { createWalletClient, http } from 'viem'
import {
  createSessionAccount,
  sessionActions,
  somniaTestnet,
} from '@somnia-chain/viem-session-account'

const account = await createSessionAccount(publicClient, { seed: '0x...' })

const client = createWalletClient({
  account,
  chain: somniaTestnet,
  transport: http(),
}).extend(sessionActions)

await client.sendTransaction({ to: '0x...', value: 1n })
```

### Chain Definitions

Pre-configured chain definitions with correct RPC URLs:

```ts
import { somnia, somniaTestnet } from '@somnia-chain/viem-session-account'

// somnia       — Chain ID 5031  (mainnet)
// somniaTestnet — Chain ID 50312 (Shannon testnet)
```

## How It Works

1. `createSessionAccount` calls `somnia_getSessionAddress` to derive an address from your seed
2. The account is a standard viem `LocalAccount` — signing methods throw descriptive errors since session transactions don't require signatures
3. `sessionActions` overrides `sendTransaction` to call `somnia_sendSessionTransaction` with `{ seed, to, data, value, gas }`
4. Gas is auto-estimated via `eth_estimateGas` when not explicitly provided
5. Because viem's `writeContract` resolves through `sendTransaction`, contract interactions work automatically

## Types

```ts
import type {
  SessionAccount,
  SessionSeed,
  SessionTransactionRequest,
} from '@somnia-chain/viem-session-account'
```

## License

MIT