@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

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

Quick Start

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.

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.

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().

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:

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

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

License

MIT