Skip to main content

Class: OvercastApp<N, L>

Defined in: packages/overcast-core/src/app.ts:36

The full Overcast SDK surface for a settlement layer, organised by where each operation lands so the effect of a call is clear from how you reach it:

  • chain — authoritative on-chain reads + signed writes (costs gas, needs the signer, chain-specific);
  • api — cheap, curated reads over the backend's REST API;
  • rfq — the realtime RFQ channel;
  • assets — asset metadata, resolved for this chain (async, cached);
  • utils — pure, chain-specific helpers (address validation, …).

Everything is composed from a single ProtocolFactory; the app itself is a thin facade holding these namespaces.

Type Parameters​

Type Parameter
N extends ChainName
L extends OvercastLayer

Properties​

api​

readonly api: OvercastView;

Defined in: packages/overcast-core/src/app.ts:52

Off-chain reads over the backend's REST API (curated options, offers, RFQs and quotes). Always built from the app's OvercastConfig — pointed at config.backend — so consumers can query the indexed/persisted state without touching the chain.

chain​

readonly chain: OvercastChain<L>;

Defined in: packages/overcast-core/src/app.ts:44

On-chain reads + signed writes, merged behind one object. These hit the settlement layer directly — as opposed to the off-chain reads on api.

On a read-only app (canSign false) the writes throw a MissingSignerError; the reads and chain.txBuilder still work.

config​

readonly config: L["config"] & OvercastConfig<N>;

Defined in: packages/overcast-core/src/app.ts:95

The config of the App: the layer's own config shape with chainName narrowed to the literal N, so app.config.chainName is "base" rather than string (the same intersection ProtocolFactory.config carries — the name lives on the app and the factory, never on the layer).

owner​

readonly owner: Bytes32;

Defined in: packages/overcast-core/src/app.ts:80

The wallet this app acts on.

Note this is not proof the app can transact — see chain.canSign.

protocolSigner?​

readonly optional protocolSigner?: OvercastProtocolSigner;

Defined in: packages/overcast-core/src/app.ts:87

Signs arbitrary protocol payloads (ed25519), or undefined for a read-only app. Built in core from the OvercastConfig — its explicit protocolSigner override if set, otherwise one derived from privateKey.

settlement​

readonly settlement: SettlementLayers<L>;

Defined in: packages/overcast-core/src/app.ts:73

The settlement layers this chain implements. A caller-side helper for picking the config an offer commits to — call settlement.select(...) and pin the returned Bytes32 into details.settlementLayer before signing. The chain writer commits whatever the offer carries verbatim; it never consults this.

utils​

readonly utils: OvercastUtils;

Defined in: packages/overcast-core/src/app.ts:64

The layer's address boundary: parse a chain address a user typed (OvercastUtils.parseAddress), convert it into the canonical Bytes32 core works in (OvercastUtils.toBytes32), and format one back for display (OvercastUtils.formatAddress).

These are the only conversions in the SDK. Nothing inside core needs them — it holds slots throughout — so reach for them exactly where a chain address enters or leaves: CLI input, log lines, curated display shapes.

Accessors​

rfq​

Get Signature​

get rfq(): RfqClient;

Defined in: packages/overcast-core/src/app.ts:193

The realtime RFQ channel (register, create/quote/accept, broadcasts), built lazily on first access. The underlying socket only connects once a caller actually reaches for RFQ, so write / read-only flows (deposit, withdraw, balances) never open one.

Returns​

RfqClient

Methods​

assets()​

assets(): Promise<OvercastAssets>;

Defined in: packages/overcast-core/src/app.ts:224

The curated asset metadata for this app's domain, wrapped so a slot resolves in one call: (await app.assets()).get(slot).

Metadata, not permissions: an asset that isn't here resolves to its bare address and is traded all the same (see AssetRegistry).

This is the piece every consumer used to assemble by hand — fetch api.listAssets(), build an AssetRegistry, then remember to run each slot through utils.formatAddress before looking it up. All three live on the app already, so the app is where they belong; see OvercastAssets for what the pinned view offers (lookups, symbol resolution, amount formatting).

A method rather than a getter because it fetches. The promise is memoized, so concurrent callers share one request and every later call is free — but a failed fetch is not cached, so a caller can retry after a transient backend error. Lookups on the result are synchronous, which is what a render loop or an output path needs.

Call refreshAssets to pick up metadata that has since changed.

Returns​

Promise<OvercastAssets>

curator()​

curator(): Promise<OvercastCurator>;

Defined in: packages/overcast-core/src/app.ts:252

An OvercastCurator over this one chain — raw protocol records to their curated (display, JSON-safe) form and back, sharing assets' registry rather than fetching a second copy.

Useful to a single-chain consumer that holds raw records (anything off app.chain) and wants the curated shape the backend would have returned, or the reverse: curator.rawOffer(curated) recovers the exact canonical offer getId and the signers need.

Returns​

Promise<OvercastCurator>

refreshAssets()​

refreshAssets(): Promise<OvercastAssets>;

Defined in: packages/overcast-core/src/app.ts:236

Re-fetch the asset metadata, replacing whatever assets has cached. The curator built from it is dropped too, so both come back consistent.

Returns​

Promise<OvercastAssets>

create()​

static create<N, L>(__namedParameters): Promise<OvercastApp<N, L>>;

Defined in: packages/overcast-core/src/app.ts:148

Builds an OvercastApp from a factory. Resolves the layer's signer, transaction writer and reader (all produced asynchronously), composes them into the on-chain OvercastChain, and grabs the layer's synchronous OvercastUtils — so the returned app is fully wired and ready to use.

Everything is derived from the factory's own config; pass config only to override the chain-agnostic fields it was built with (see AppOptions.config) — the overrides are merged over it, never substituted for it.

The factory may resolve no chain signer, which yields a read-only app: reads and chain.txBuilder work, chain's writes throw. Such an app must still know whose app it is, so exactly one requirement is enforced here — a chain signer, or an identity to stand in for one (config.owner or a protocolSigner). An app with neither could not name a depositor, quote an RFQ, or report a balance, so it is rejected rather than left to fail later with an undefined address.

Type Parameters​

Type Parameter
N extends string
L extends OvercastLayer

Parameters​

ParameterType
__namedParametersAppOptions<N, L>

Returns​

Promise<OvercastApp<N, L>>

Throws​

when neither a chain signer nor an owner identity is available.