@somnia-chain/markets-sdk

@somnia-chain/markets-sdk / index / SmartAccountsClient

Interface: SmartAccountsClient

Defined in: packages/sdk/src/smartAccounts.ts:143

The smart-accounts capability — the factory account model of @somnia-chain/accounts-sdk, bound to one markets client's chain and transport. Reached as client.accounts.

Details

Reads go through the owning client's chain transport. The build* members return UnsignedCalls (or UnsignedAccountCreations carrying their gas) for any executor to send — creation by whoever pays, owner management and transfers through the account's own smart-account executor (client.createExecutor({ smartAccount, inner })), so the account administers itself.

Every member is refused with InvalidInputError on a chain the accounts SDK has no deployment for (Somnia mainnet 5031, Somnia testnet 50312 and Hideki testnet 50383 are covered; the factory sits at the same address on each).

Methods

addressOf()

addressOf(accountId, index): `0x${string}`

Defined in: packages/sdk/src/smartAccounts.ts:157

The address (accountId, index) derives to on this chain — the same on every covered chain, deployed or not. Pure; no read.

Gotchas

The factory is upgradeable, so this is a prediction: fine for a screen, but read SmartAccountsClient.find (or the accounts SDK's authoritative read) before publishing a deposit address.

Parameters

accountId

`0x${string}`

index

bigint

Returns

`0x${string}`

find()

find(accountId, options?): Promise<AccountScan>

Defined in: packages/sdk/src/smartAccounts.ts:168

Scan which of accountId's derived accounts are deployed, from index 0 upward. Chain read (current to head).

  • Throws InvalidInputError - the chain is not covered, or the range is empty or wider than the accounts SDK's scan cap.
  • Throws RpcError - the transport failed outright; cause has the original. A single index that did not answer is reported inside the scan instead. The complete union is SmartAccountsReadError.

Parameters

accountId

`0x${string}`

options?
maxIndex?

bigint

Returns

Promise<AccountScan>

nextFreeIndex()

nextFreeIndex(accountId, options?): Promise<bigint>

Defined in: packages/sdk/src/smartAccounts.ts:178

The lowest index with no deployed account, for creating the next one. Chain read (current to head).

Parameters

accountId

`0x${string}`

options?
from?

bigint

Returns

Promise<bigint>

ownersOf()

ownersOf(account): Promise<OwnerSet>

Defined in: packages/sdk/src/smartAccounts.ts:187

An account's owner set: each owner classified as a key or another account, plus the threshold. Chain read (current to head).

Parameters

account

`0x${string}`

Returns

Promise<OwnerSet>

custodyChain()

custodyChain(account, options?): Promise<CustodyChain>

Defined in: packages/sdk/src/smartAccounts.ts:197

Walk DOWN from an account to the keys that ultimately control it, across accounts owning accounts. Chain read (current to head).

Parameters

account

`0x${string}`

options?
maxDepth?

number

Returns

Promise<CustodyChain>

authorityPath()

authorityPath(account, signer, options?): Promise<readonly `0x${string}`[] | null>

Defined in: packages/sdk/src/smartAccounts.ts:208

Walk UP from a signer: the parent accounts between it and account, nearest first — exactly what the smart-account executor spec takes as through. null when the signer has no authority over the account (a real answer, not an error). Chain read (current to head).

Parameters

account

`0x${string}`

signer

`0x${string}`

options?
maxDepth?

number

Returns

Promise<readonly `0x${string}`[] | null>

tree()

tree(root, options?): Promise<AccountTree>

Defined in: packages/sdk/src/smartAccounts.ts:217

The tree of accounts under one root — every deployed account derived from it, and from those, recursively. Chain read (current to head).

Parameters

root

`0x${string}`

options?
maxIndex?

bigint

indices?

readonly bigint[]

maxDepth?

number

Returns

Promise<AccountTree>

holdings()

holdings(account, tokens?): Promise<Holdings>

Defined in: packages/sdk/src/smartAccounts.ts:230

An account's native balance and the balances of the tokens asked about. A balance is undefined where the read did not answer — never silently zero. Chain read (current to head).

Parameters

account

`0x${string}`

tokens?

readonly `0x${string}`[]

Returns

Promise<Holdings>

health()

health(account): Promise<HealthReport>

Defined in: packages/sdk/src/smartAccounts.ts:240

Evaluate an account's setup against the factory's canonical shape: singleton, fallback handler, owners, threshold, modules — each finding with a severity. Chain read (current to head).

Parameters

account

`0x${string}`

Returns

Promise<HealthReport>

buildExecution()

buildExecution(args): Promise<PreparedAccountExecution>

Defined in: packages/sdk/src/smartAccounts.ts:256

Prepare an execution whose signer is NOT the sender — the sign-now-send-later flow: the owner signs here, and the finished call goes to whoever pays (your backend, a relayer). The executor path (createExecutor({ smartAccount, … })) is the right tool when the same process signs and sends; this is for when it is not. One nonce read through this client, skipped when nonce is given — an account's FIRST action can be prepared and signed before the account is deployed, at nonce 0. Chain read (current to head) unless nonce is given.

Parameters

args
account

`0x${string}`

The account that acts.

calls

readonly UnsignedCall[]

What it does. Several calls batch into one account transaction.

signer

`0x${string}`

The address that will sign — an owner of the account, or of the outermost parent.

through?

readonly `0x${string}`[]

The parent accounts between the signer and account, nearest first.

nonce?

bigint

The account's nonce, when the caller already knows it — no read is performed. 0n prepares an undeployed account's first action.

Returns

Promise<PreparedAccountExecution>

buildCreateAccount()

buildCreateAccount(accountId, index): UnsignedAccountCreation

Defined in: packages/sdk/src/smartAccounts.ts:280

Build the call that deploys (accountId, index)'s account on this chain. Permissionless and idempotent: no signature from anybody — the owner is forced out of the CREATE3 salt, so a sponsor cannot inject one. Send as executor.execute([r.call], { gas: r.gas }).

Parameters

accountId

`0x${string}`

index

bigint

Returns

UnsignedAccountCreation

buildAccountAuthorization()

buildAccountAuthorization(args): PreparedAccountAuthorization

Defined in: packages/sdk/src/smartAccounts.ts:293

Build the authorization one owner signature settles: several accounts, optional additional owners (a session key) and threshold, valid on EVERY covered chain — the domain deliberately omits the chain id. Sign typedData with any EIP-712 signer, then hand the pair to SmartAccountsClient.buildCreateAccounts (or the exchange-level fan-out). Pure; no read.

Parameters

args
accountId

`0x${string}`

The address the accounts derive from — the EOA (or account) that signs.

indices

readonly bigint[]

Which indices to create. At least one.

additionalOwners?

readonly `0x${string}`[]

Extra owners installed at creation — typically one session key.

threshold?

bigint

Signature threshold for the created accounts. Default 1.

window?

bigint

Seconds the signature stays valid. Default 900, max 18,000.

now?

bigint

Unix seconds "now". Defaults to the system clock.

Returns

PreparedAccountAuthorization

buildCreateAccounts()

buildCreateAccounts(authorization, signature): UnsignedAccountCreation

Defined in: packages/sdk/src/smartAccounts.ts:316

Turn a signed authorization into this chain's creation call. Any funded actor may send it; the accounts the authorization names that already exist are skipped, not reverted. For every covered chain at once, use the exchange-level exchange.accounts.buildCreateAccounts.

Parameters

authorization

AccountAuthorization

signature

`0x${string}`

Returns

UnsignedAccountCreation

buildAddOwner()

buildAddOwner(account, owner, threshold): UnsignedCall

Defined in: packages/sdk/src/smartAccounts.ts:325

Build the call that adds an owner (typically a session key) to an account, setting the threshold. Execute it THROUGH the account itself: client.createExecutor({ smartAccount: account, inner }).

Parameters

account

`0x${string}`

owner

`0x${string}`

threshold

bigint

Returns

UnsignedCall

buildSwapOwner()

buildSwapOwner(account, owners, oldOwner, newOwner): UnsignedCall

Defined in: packages/sdk/src/smartAccounts.ts:335

Build the call that swaps one owner for another. owners is the account's CURRENT owner list (SmartAccountsClient.ownersOf) — Safe's owner list is linked, so the call names the predecessor.

Parameters

account

`0x${string}`

owners

readonly `0x${string}`[]

oldOwner

`0x${string}`

newOwner

`0x${string}`

Returns

UnsignedCall

buildRemoveOwner()

buildRemoveOwner(account, owners, owner, threshold): UnsignedCall

Defined in: packages/sdk/src/smartAccounts.ts:344

Build the call that removes an owner, setting the threshold. owners is the account's CURRENT owner list.

Parameters

account

`0x${string}`

owners

readonly `0x${string}`[]

owner

`0x${string}`

threshold

bigint

Returns

UnsignedCall

buildChangeThreshold()

buildChangeThreshold(account, threshold): UnsignedCall

Defined in: packages/sdk/src/smartAccounts.ts:351

Build the call that changes the account's signature threshold.

Parameters

account

`0x${string}`

threshold

bigint

Returns

UnsignedCall

buildTransfer()

buildTransfer(args): readonly UnsignedCall[]

Defined in: packages/sdk/src/smartAccounts.ts:361

Build the calls that move native value and/or ERC-20 amounts OUT of an account. Execute them through that account's smart-account executor — the account holding the funds is the one that sends.

Parameters

args
to

`0x${string}`

The recipient.

native?

bigint

Wei of native value to move.

tokens?

readonly TokenAmount[]

ERC-20 amounts to move, in raw token units.

Returns

readonly UnsignedCall[]