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

Class: CollateralOnWrongChainError

Defined in: packages/sdk/src/errors.ts:748

A write needs collateral on the market's chain, and the account does not hold enough of it THERE — though it may hold it on another chain the exchange spans.

Details

A market is unique to one chain and its collateral must sit on that chain. The exchange checks the escrow token's balance on the market's chain before encoding an order and throws this instead of letting the pool revert, so the caller learns WHERE the funds are and gets a ready bridge plan. Nothing was sent on any chain.

chainId, token, code: the chain and the escrow token (address, and its currency code) the order needs.
needed, held, shortfall: raw token units on that chain.
elsewhere: the raw balance of the same bridge token on every other configured chain the bridge registry lists it on. The bridge token is found by the escrow token's address in the registry, not by code. A token the registry does not list has no route, so elsewhere is empty.
unread: chains whose balance could not be read, so their absence from elsewhere is not a zero balance. A chain listed here may hold the shortfall.
readErrors: the original typed errors, keyed by chain and retained in cause.
plan: a BridgeTransfer from the richest other chain covering the shortfall, when the token has a bridge route; absent when it does not.

On a spot order, needed is the pool's own requirement net of the account's pool vault balance (getAutoPullRequirement(...).delta), and held is the wallet balance. Under the pool's manual vault mode, needed is the full requirement, held is the vault balance, elsewhere is empty, and there is no plan: the pool does not pull from the wallet, so only a vault deposit funds the order.

Gotchas

Explicit by design: the exchange never bridges on its own. Execute plan through exchange.bridge.transfer(...), or ask for it with createOrder(…, { funding: "auto" }), or pass { funding: "skip" } to bypass the check on a hot path you fund yourself.

Extends

SomniaMarketsError

Constructors

Constructor

new CollateralOnWrongChainError(fields): CollateralOnWrongChainError

Defined in: packages/sdk/src/errors.ts:780

Parameters

fields

chainId

number

token

string

code

string

needed

bigint

held

bigint

elsewhere

Record<number, bigint>

unread?

readonly number[]

readErrors?

Readonly<Record<number, CollateralReadError>>

plan?

BridgeTransfer

symbol

string

Returns

CollateralOnWrongChainError

Overrides

SomniaMarketsError.constructor

Properties

chainId

readonly chainId: number

Defined in: packages/sdk/src/errors.ts:750

Numeric chain id the market — and so the collateral — lives on.

token

readonly token: string

Defined in: packages/sdk/src/errors.ts:752

The escrow token's address on that chain, lowercased (the zero address for the native coin).

code

readonly code: string

Defined in: packages/sdk/src/errors.ts:754

The escrow token's currency code, the key UnifiedBalances uses.

needed

readonly needed: bigint

Defined in: packages/sdk/src/errors.ts:760

Raw units the order needs on chainId. On a spot order this is the pool's requirement net of the pool vault balance, or the full requirement under manual vault mode.

held

readonly held: bigint

Defined in: packages/sdk/src/errors.ts:765

Raw units the account holds on chainId toward needed: the wallet balance, or the pool vault balance under manual vault mode.

shortfall

readonly shortfall: bigint

Defined in: packages/sdk/src/errors.ts:767

needed − held, raw units.

elsewhere

readonly elsewhere: Record<number, bigint>

Defined in: packages/sdk/src/errors.ts:769

The same bridge token's raw balance on every OTHER configured chain the bridge registry lists it on, keyed by chain id.

unread

readonly unread: readonly number[]

Defined in: packages/sdk/src/errors.ts:774

Chains whose balance read failed. Empty when all reads succeed. Retry these chains before concluding that no bridge route covers the shortfall.

readErrors

readonly readErrors: Readonly<Record<number, CollateralReadError>>

Defined in: packages/sdk/src/errors.ts:776

Failed balance reads by chain. The same errors are retained in the aggregate cause.

plan?

readonly optional plan?: BridgeTransfer

Defined in: packages/sdk/src/errors.ts:778

A bridge plan covering the shortfall from the richest other chain, when a route exists.