@overcast/core
Classes
| Class | Description |
|---|---|
| AssetRegistry | An in-memory lookup from asset address to its curated Asset metadata. |
| CloseCollateralOfferOperation | A maker delegating close_collateral_offer for the given offerId. |
| CloseSettlementOfferOperation | A taker delegating close_settlement_offer for the given offerId. |
| CollateralOfferOperation | A maker delegating make_collateral_offer. The payload is the collateral offer's content-address bytes — the exact bytes hashed into its offer_id — so signing the operation authorizes that specific offer. |
| Ed25519ProtocolSigner | The default OvercastProtocolSigner: ed25519 over @noble/ed25519, a pure-JS implementation that runs identically in Node, browsers and other runtimes (no dependency on Node's built-in crypto). Built from a 32-byte seed (the leading half of an ed25519 secret key); createProtocolSigner derives that seed from the config's privateKey. |
| ExerciseOperation | A taker delegating exercise_option. Unlike the offer operations this is not a content-addressed struct: the taker commits to the two offer ids, the exercise amount, and the opaque settlement metadata. |
| HttpOvercastView | An OvercastView backed by the Overcast backend's REST API. |
| MemoryStore | In-memory reference implementation of the storage ports. Backs both the trusted write side (OvercastStore) and the public read side (OvercastView); a real deployment swaps this for a database-backed store implementing the same interfaces. |
| Operation | The signed body of an off-chain operation. Each subclass binds an action discriminant (actionByte) to a payload byte layout (payloadBytes), and digest folds both — with the shared metadata — into the canonical 32-byte message the signer commits to. |
| OracleSettlementLayer | The logic for one settlement layer on a given chain (L): the config (Id) an offer commits to, and — for layers that have one — a convenience helper for the exercise/redeem metadata. |
| OvercastApp | 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: |
| OvercastChainClient | Concrete OvercastChain: a SigningWriter (signer + transaction writer, build → sign → submit) with the layer's OvercastReader folded in, so on-chain reads and signed writes live behind a single object. Built by OvercastApp from the pieces a ProtocolFactory resolves. |
| OvercastChainSigner | Owns the signing key + connection for a settlement layer and turns a built transaction into a confirmed on-chain result. Signs transactions — for signing arbitrary protocol payloads (off-chain authorization) see OvercastProtocolSigner. |
| OvercastHttpError | Thrown when a backend read fails — either the server answered with a non-2xx status (the status and, where present, the backend's own error message are surfaced) or the request never reached it (network / timeout, status undefined). The originating axios error is kept as Error.cause. |
| OvercastIndexer | Drives the store off the chain through three independent, self-healing loops: |
| PhysicalSettlementLayer | Base for a physical settlement layer: settlement happens in the underlying asset itself, so exercise/redeem carry no metadata. A chain subclasses this and supplies its defaultConfig (the layer's on-chain config account). |
| ProtocolFactory | The single chain-specific entry point: builds every per-layer piece the SDK composes into an OvercastApp — the on-chain OvercastReader, the transaction-building OvercastWriter, the OvercastChainSigner and the OvercastIndexerClient. A settlement layer implements this one factory (e.g. a Solana factory) and is good to go; the rest of the SDK stays chain-agnostic. |
| RedeemOperation | A maker delegating redeem_option. Mirrors ExerciseOperation: the maker commits to the two offer ids, the redeemed amount, and the opaque settlement metadata. Its payload layout is identical to the exercise payload — the action discriminant keeps their signed messages disjoint. |
| RfqClient | The realtime RFQ channel: a typed socket.io client that registers with the backend, emits request/response (ack-style) calls, and surfaces server broadcasts through the on* callbacks. Owned by OvercastApp as its rfq field; the on-chain write/read sides live on the app itself. |
| RfqError | Error thrown when a request/response (ack-style) call fails — either the server returned { ok: false } with a stable RfqErrorCode, or no ack arrived before the timeout elapsed. |
| SettlementLayerRegistry | The set of settlement layers a chain implements, keyed by type. Built by the chain's ProtocolFactory (which layers exist is a per-chain fact) and surfaced to consumers as app.settlement. |
| SettlementOfferOperation | A taker delegating make_settlement_offer. The payload is the settlement offer's content-address bytes (see CollateralOfferOperation). |
| SigningWriter | Composes a transaction-building OvercastWriter with an OvercastChainSigner: each operation builds the layer's transaction (tx) via writer, then signs + submits it via signer, yielding the signer's receipt. The result is itself an OvercastWriter<receipt>, so callers no longer juggle the build-then-submit two-step. |
Interfaces
| Interface | Description |
|---|---|
| AppOptions | - |
| ClientToServerEvents | Client→server events, keyed by event name. socket.io models request/response as a trailing ack callback argument; each here resolves to an RfqAck. Use as the second type parameter on a client Socket<...> and the first on the server Server<...>. |
| CuratedCollateralOffer | CollateralOffer over CuratedOptionDetails. |
| CuratedSettlementOffer | SettlementOffer over CuratedOptionDetails. |
| OfferFilter | Filter for the offer listings. All clauses are AND-ed. |
| OfferQuery | - |
| OperationParams | - |
| OptionFilter | Filter for OvercastView.listOptions. All clauses are AND-ed. |
| OptionQuery | - |
| OvercastChain | The protocol's on-chain surface: authoritative reads (OvercastReader) and signed writes (OvercastWriter, yielding the layer's submission receipt L["receipt"]), merged into one object. Everything here touches the settlement layer directly — it costs gas, needs the signer, and is chain-specific — as opposed to the cheap, curated backend reads exposed on app.api (an OvercastView). |
| OvercastEventHistory | - |
| OvercastIndexerClient | - |
| OvercastLayer | Describes a single settlement layer by bundling the three types that vary between implementations, so the rest of the SDK threads one generic (L) instead of repeating <T, R, C> everywhere. Each consumer derives what it needs via indexed access (L["tx"], L["receipt"], L["config"]). |
| OvercastProtocolSigner | Signs arbitrary protocol payloads — not chain transactions. Where an OvercastChainSigner turns a built transaction into an on-chain result, a protocol signer produces a detached signature over raw bytes, used for the protocol's off-chain authorization (e.g. authorizing an offer). |
| OvercastReader | - |
| OvercastSettlementLayer | The logic for one settlement layer on a given chain (L): the config (Id) an offer commits to, and — for layers that have one — a convenience helper for the exercise/redeem metadata. |
| OvercastStore | The permissioned write surface. Wired only into trusted processes: - the OvercastIndexer, which streams on-chain events via insertEvents; - the RFQ service, which persists validated off-chain RFQs / quotes. |
| OvercastUtils | Small, pure, chain-specific helpers that don't fit the read/write split but still vary per settlement layer — address validation and normalization today. |
| OvercastView | The non-permissioned read surface, returning curated (display, JSON-safe) shapes. This is the interface shared across backend and frontend: a database implementation runs the query in-process, while a thin HTTP implementation in the frontend serializes the same query objects to the backend. Keep every argument and result JSON-serializable so both implementations stay honest. |
| OvercastWriter | The Overcast protocol's write operations, parameterised by what each call yields (the read counterpart is OvercastReader). |
| Page | A single page of results plus the cursor to fetch the next one. |
| Pagination | Cursor / offset pagination. Prefer the opaque cursor (keyset pagination): it is stable while new rows are inserted and stays fast on large tables. offset is offered only as a convenience for simple, shallow UI paging. |
| RfqAck | Generic ack returned from the request/response (ack-style) handlers. Kept as a generic interface (rather than a zod schema) so callers can parameterize the data shape per event; see ClientToServerEvents. |
| RfqClientOptions | - |
| RfqFilter | Filter for OvercastView.listRfqs. All clauses are AND-ed. |
| RfqQuery | - |
| ServerToClientEvents | Server→client broadcasts, keyed by event name. Use as the first type parameter on a client Socket<...> and the second on the server Server<...>, so .on(...) / .emit(...) are checked on both ends. |
| SignedOperation | - |
| SortOrder | - |
| StoredQuote | A persisted quote, mirroring the curated newQuote broadcast payload. |
| StoredRfq | A persisted RFQ, mirroring the curated newRfq broadcast payload. |
Type Aliases
| Type Alias | Description |
|---|---|
| AcceptQuoteInput | Input to RfqClient.acceptQuote. Either sign a fresh offer for the acceptor's side over the quote's details, or accept against an existing on-chain offer by chainOfferId — the two are mutually exclusive. |
| AcceptQuotePayload | - |
| Asset | Curated metadata describing a tradeable asset (see assetSchema). |
| CancelRfqPayload | - |
| Checkpoint | - |
| CheckpointKind | Which indexer cursor a checkpoint belongs to. The two cursors move in opposite directions and must never share a slot: - backfill — the historical sweep's descending paging cursor ("lowest point swept so far"), advanced page by page towards the start checkpoint. - finalization — the finalization tail's ascending frontier ("newest finalized head fully swept"), advanced only after a whole range settles. |
| ClientRole | - |
| CollateralOffer | - |
| CreateRfqPayload | CreateRfqPayloadWire with rich bigint option details. |
| CreateRfqPayloadWire | - |
| CuratedMarketOption | MarketOption over CuratedOptionDetails, enriched with the indexer-aggregated OptionTotals as decimal strings (wire form). The raw MarketOption carries no totals — they are derived from the option's exercise / redeem events and only surfaced here, on the display-facing shape. |
| CuratedOptionDetails | See curatedOptionDetailsSchema. |
| DepositParams | Parameters for a deposit into a user's protocol escrow vault. |
| Equivalent | true when A and B are mutually assignable (structurally equivalent). Preferred over invariant equality for comparing a z.infer object against a composed type like Omit<…> & Record<…>: those are the same shape but not token-identical, so a strict equality check reports a false mismatch. The tuple wrappers stop the conditionals distributing over unions. |
| EventPage | One page of a backwards getEvents search. |
| Expect | Compile-time assertion that its argument is exactly true (pair it with Equivalent). Instantiate it in a throwaway type _ = Expect<Equivalent<X, Y>> to fail the build when X and Y drift apart — used to pin hand-written wire DTOs to their canonical types. Works via the constraint: a false argument violates T extends true and is a compile error, even when _ is unused. |
| Hash | - |
| Id | - |
| Indexed | - |
| IndexedEvents | - |
| KnownSettlementLayer | - |
| Logger | - |
| LogLevel | - |
| MarketOption | - |
| Metadata | - |
| NewRfqPayload | - |
| OfferClosed | - |
| OfferCreated | - |
| OptionCreated | - |
| OptionDetails | - |
| OptionDetailsWire | - |
| OptionExercised | - |
| OptionRedeemed | - |
| OptionTotals | Running burn totals for a MarketOption, aggregated by the indexer from the option's OptionExercised / OptionRedeemed events. These are not part of the canonical, content-addressed option (they don't exist on the on-chain account — the chain derives them from the claim mint supplies), so they live separately and are only surfaced on the curated, display-facing option. |
| OvercastConfig | - |
| OvercastStorage | Convenience alias for an implementation that backs both ports — the typical single concrete store (memory, Postgres, …). Consumers should still depend on the narrowest port they need (OvercastStore or OvercastView). |
| QuoteAcceptedPayload | - |
| QuoteNewPayload | - |
| QuoteStatus | Lifecycle of a quote submitted against an RFQ. |
| RegisterPayload | - |
| RfqErrorCode | - |
| RfqErrorInfo | - |
| RfqStatus | Lifecycle of an RFQ. Carried now so the model is ready for reconciliation. |
| SettlementOffer | - |
| SettlementSelection | How a caller picks a settlement layer for an offer: a bare type key (→ the layer's default config) or a { type, config } pair naming a custom config. Typed to L["settlement"], so selecting a layer the chain doesn't implement fails to compile. |
| Signature | - |
| SignedOperationWire | - |
| StoredRfqRequest | - |
| SubmitQuotePayload | SubmitQuotePayloadWire with rich bigint option details. |
| SubmitQuotePayloadWire | - |
| SupportedChains | The chains an Asset can live on. A curated, human union rather than a free string so callers get type-safety and autocomplete — extend it as new settlement layers are supported. |
| TxDetails | Chain-specific parsed detail of an already-submitted transaction, as returned by an indexer lookup (OvercastIndexerClient.getTransactionInfo). Opaque at the core level; each chain narrows it (e.g. Solana's ParsedTransactionWithMeta). |
| TxHash | A submitted transaction's unique on-chain identifier (signature / hash). |
| TxInfo | The outcome of submitting a transaction to a settlement layer. Returned by OvercastChainSigner.submit and, by extension, every SigningWriter method. |
| UnsignedTransaction | - |
| WithdrawParams | Parameters for a withdrawal from a user's protocol escrow vault. |
| WithId | A stored value paired with its content-address Id. |
Variables
| Variable | Description |
|---|---|
| acceptQuotePayloadSchema | Accept a quote — either by signing a fresh offer operation (operation + salt + expiry) or by referencing an already on-chain offer id. Carries no bigint, so the one schema is both the wire and the client-facing shape. |
| ACTIONS | Action discriminant bound into every signed operation message, so a payload can never be verified under another action's discriminant. Mirrors OperationPayload::action in operation.rs — append-only: never reuse or renumber a value. |
| assetSchema | Curated metadata describing a tradeable asset, keyed by its on-chain address. This is the human-facing layer the raw OptionDetails asset fields (bare addresses) are resolved against — it never replaces the address used for signing / content-addressing, only annotates it. |
| cancelRfqPayloadSchema | - |
| clientRoleSchema | - |
| createRfqPayloadWireSchema | CreateRfqPayload with its option details in wire form. |
| curatedOptionDetailsSchema | OptionDetails with its asset fields resolved to Asset and its native amounts as decimal strings (wire form). Defined as a zod schema so it can validate broadcast DTOs; the type is inferred from it. |
| DEFAULT_BACKEND | - |
| DEFAULT_EXPIRY_DURATION | - |
| DEFAULT_TRANSPORT | - |
| LOG_LEVELS | pino's level names, ordered least → most severe, plus silent. |
| logger | Default root logger for ad-hoc use. |
| newRfqPayloadSchema | - |
| OPERATION_PREFIX | Domain-separation prefix distinguishing operation messages from the content-addressed struct ids (offer_id, option_id) derived in utils.ts. Must match OPERATION_PREFIX in the on-chain operation.rs. |
| OPERATION_VERSION | - |
| optionDetailsWireSchema | OptionDetails with its native bigint amounts as decimal strings — the JSON-safe wire form. |
| quoteAcceptedPayloadSchema | - |
| quoteNewPayloadSchema | - |
| registerPayloadSchema | - |
| rfqErrorCodeSchema | Stable error codes surfaced on *:error events. |
| rfqErrorSchema | The { code, message } error carried on acks and the error event. |
| rfqOptionsSchema | RFQ options bag. responder is an optional allowlist of ids permitted to respond; unknown keys pass through so future options don't need a schema bump. |
| signedOperationSchema | A SignedOperation: the ed25519 signature over an operation's digest, the key that produced it, and the operation params (expiry + replay salt) it commits to. Sent wherever a payload authorizes a delegated, off-chain-signed action. Carries no bigint, so this one schema is both the wire and the client-facing shape. |
| submitQuotePayloadWireSchema | SubmitQuotePayload with its option details in wire form. |
Functions
| Function | Description |
|---|---|
| amountFromWire | Parse a decimal-string wire amount back to a native bigint. |
| amountToWire | Serialize a native amount to its decimal-string wire form. |
| base58ToBytes | Decode a base58 string to its raw bytes (leading 1s become leading zero bytes). Unlike decodeBase58 this does not assume a 32-byte pubkey, so it works for arbitrary-length values such as a 64-byte ed25519 secret key. |
| buildOffer | Build the correctly-shaped Offer for a side: a MAKER authors a CollateralOffer keyed by maker, a TAKER a SettlementOffer keyed by taker. Both carry the same terms and salt, and an expiry defaulted via resolveOfferExpiry. |
| collateralOfferBytes | CollateralOffer byte layout (246 bytes): tag(0x01) · salt(32) · maker(32) · option_details(173) · expiry(i64). |
| completeOptionDetails | Complete an RFQ's (partial, curated) option terms with a market maker's quoted premium to produce the canonical, signable OptionDetails a quote is submitted over. Asset fields are resolved back to their addresses and the decimal-string amounts to native bigints. |
| concat | Concatenate byte chunks into a single Uint8Array. |
| createLogger | Creates a namespaced child logger. Pass a dotted/colon name to scope a subsystem, e.g. createLogger("indexer"). |
| createProtocolSigner | Resolve the OvercastProtocolSigner for a config: the explicit OvercastConfig.protocolSigner override if supplied, otherwise a default Ed25519ProtocolSigner built from the config's privateKey. Returns undefined for a read-only config (no override and no key) — nothing to sign protocol payloads with. |
| curateCollateralOffer | Curate a CollateralOffer. |
| curateMarketOption | Curate a MarketOption, folding in the indexer-aggregated OptionTotals (sourced from the option's exercise / redeem events) since the raw option carries no running totals of its own. |
| curateOptionDetails | Resolve every asset field of OptionDetails against the registry. Defaults to an unknownAsset if not available |
| curateSettlementOffer | Curate a SettlementOffer. |
| decodeBase58 | Decode a base58 Id to its raw 32-byte pubkey (left-padded with zeros). |
| defaultExpiry | Returns a default expiry timestamp in seconds, calculates the current time in seconds and adds the default expiry duration to it |
| defaultOperationParams | - |
| encodeBase58 | Encode raw bytes to a base58 string (leading zero bytes become leading 1s). |
| formatAssetAmount | Format a native amount as a display string, e.g. 1.5 SOL. |
| formatUnits | Convert a native integer bigint to a whole-token (display) decimal string, exactly — e.g. formatUnits(1_500_000_000n, 9) → "1.5". Trailing fractional zeros are trimmed. |
| getId | Content-addressed id for one of the local Overcast types, matching the on-chain HashId derivation. Discriminates the input by shape: collateral offers carry a maker, settlement offers a taker, and options reference both offers. |
| getLogLevel | Returns the currently active global log level. |
| i64LE | i64, little-endian (8 bytes). |
| marketOptionBytes | MarketOption byte layout (302 bytes): tag(0x03) · details(173) · taker(32) · maker(32) · settlement_offer(32) · collateral_offer(32). |
| parseUnits | Convert a whole-token (display) decimal string to an exact native integer bigint. e.g. parseUnits("1.5", 9) → 1_500_000_000n. Throws if the value is malformed or specifies more fractional digits than decimals supports (which would silently truncate). |
| pubkey | A Pubkey's raw 32 bytes. |
| randomSalt | - |
| serializeAmounts | Convert the native bigint amounts of an OptionDetails (possibly partial — RFQ requests omit some terms) to their decimal-string wire form, leaving every other field untouched. |
| setLogLevel | Sets the global log level. Loggers created afterwards inherit it; already created loggers are updated too so a runtime change takes effect everywhere. |
| settlementOfferBytes | SettlementOffer byte layout (246 bytes): tag(0x02) · salt(32) · taker(32) · option_details(173) · expiry(i64). |
| Sleep | - |
| toDisplayAmount | Convert a native integer amount to a whole-token (display) decimal string, exactly — e.g. 1_500_000_000n SOL (9 decimals) → "1.5". |
| toNativeAmount | Convert a whole-token (display) amount — given as a decimal string to avoid float loss — to an exact native integer amount, using the asset's decimals. e.g. "1.5" SOL (9 decimals) → 1_500_000_000n. |
| u32LE | u32, little-endian (4 bytes). |
| u64LE | u64, little-endian (8 bytes). Native bigint so values stay exact. |
| uncurateOptionDetails | Strip a CuratedOptionDetails back to the raw OptionDetails (asset fields → their addresses). Used by clients that receive a curated broadcast but need the canonical, signable details. |