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

Class: CollateralOnWrongChainError

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

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 same currency's raw balance on every other configured chain.
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.

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:472

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:449

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

token

readonly token: string

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

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

code

readonly code: string

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

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

needed

readonly needed: bigint

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

Raw units the order escrows on chainId.

held

readonly held: bigint

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

Raw units the account holds on chainId.

shortfall

readonly shortfall: bigint

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

needed − held, raw units.

elsewhere

readonly elsewhere: Record<number, bigint>

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

The same currency's raw balance on every OTHER configured chain, keyed by chain id.

unread

readonly unread: readonly number[]

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

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:468

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:470

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