Somnia Accounts

Somnia Accounts gives every user a smart account: a contract that holds their balances, controlled by keys they choose. The account's address is a pure function of the owner key, so it is known before anything is deployed, identical on every Somnia network, and unchanged when every key around it is replaced.

A plain wallet key signs everything, so it has to be present for everything, and if it leaks, everything is gone. Somnia Accounts splits that job in two:

• The account is a Safe 1.5.0, unmodified, deployed by SomniaAccountFactory. It holds the balances.
• The owner key is the user's wallet. It determines the address and makes one consent decision: who else may act. It signs, but never sends a transaction, so it never needs gas.
• The session key is a second key the application holds, for example in the browser. It does the acting, unattended, and can be replaced at any time.

The key you keep safe is used rarely, and the key used constantly is one you can throw away.

The session key is a full co-owner, not a restricted one. At a threshold of 1 it can do everything the owner key can, including removing the owner key. Limiting what a key may do needs a Safe module and guard, which Somnia Accounts does not ship yet. See About the two-key model.

Why Somnia Accounts

• The address comes first. Show a deposit address before the account exists. Deployment can happen later, paid for by anyone, and lands at the same address.
• One signature, every chain. Creating accounts and granting a session key is one EIP-712 signature whose domain omits the chain id, so the same signature creates the account on every network.
• No wallet popups after the first. Once a session key is an owner, the application acts with no prompt at all.
• Accounts can own accounts. Sub-accounts are ordinary accounts owned by another account, so a user can keep separate balances (a trading desk, a vault) under one owner key.
• Sponsorable. The owner key never pays gas. Creation is permissionless, so a relayer or the application can pay for it.
• No new trust. Accounts are standard Safes. The factory only deploys them; it cannot touch an account once it exists.

How an account is created

1. Derive. accountAddress(chainId, owner, index) computes the address offline. Index 0 is the main account; other indices are further accounts under the same owner key.
2. Authorize. The owner key signs one AccountAuthorization: the indices to create, the extra owners to add (the session key) and the threshold. The signature is valid for at most five hours.
3. Create. Anyone submits the signed authorization to SomniaAccountFactory on each network. Each call deploys the accounts and sets their owners in one transaction. An index that already exists is skipped.
4. Act. The session key sends transactions through the account. When the key that authorizes is also the key that pays, it needs no signature at all.

import {accountAddress, getActivityPage, listAccountsAt} from "@somnia-chain/accounts-sdk"

// The address is known before anything is deployed, and is the same on every chain
const account = accountAddress(50312, owner, 0n)

// Whose account an address is, on each chain that has one
const whose = await listAccountsAt(account)
const history = await getActivityPage({account, limit: 25})

Networks and contracts

Somnia Accounts is live on Somnia Mainnet, Somnia Testnet and Tokyo Testnet, at the same addresses on each.

Don't copy these into your code. The SDK exports every address, ABI and the derivation, so your application has a single source of truth. See Addresses and chains.

The factory is upgradeable. Its admin can change the Safe that new accounts get, but accounts that already exist are untouched.

The SDK

@somnia-chain/accounts-sdk is the one way in: ABIs, addresses, derivation, encoders and typed reads from the public index. It owns no client: every function takes the viem Client you already have and returns plans and calls as data, so it is safe to use from inside another SDK.

npm install @somnia-chain/accounts-sdk viem

Whose account an address is, and anything shaped like history, can't be read from the chain alone. The SDK reads a public GraphQL index for that, with no credentials. You pass chain ids, never a URL.

The Somnia Markets SDK can trade through a Somnia Account, with a session key placing orders and no wallet prompt per trade.

Next steps

• Create your first account: derive an address, create the account with one signature, then act with none.
• Act from a sub-account: an account owned by an account.
• How-to guides: sessions, sponsoring, browser wallets, the indexer and errors.
• Gas: gas for these calls can't be estimated, and the failure is silent. Read this before your first transaction.
• Using the explorer: the Smart Accounts pages in the Somnia Explorer.