Market-maker spline SDK surface#

Splines are maker-facing, creator-owned compiled quote accounts. They provide discrete piecewise-constant liquidity over up to sixteen bid and sixteen ask levels. This page documents the canonical ABI only; the retired registry, region-array, auto-attach, and V2 surfaces are not supported.

Instructions#

The authoritative discriminator table is program/src/instruction.rs and spec/IX.md. Builders are implemented in packages/core, packages/sdk-rust, packages/sdk-python, and packages/cli.

Identity and account derivation#

spline       = PDA(["seesaw", "spline", feed_id, duration_le, creator])
spline_vault = PDA(["seesaw", "spline_vault", spline])

Use deriveSplinePda / derive_spline_pda and deriveSplineVaultPda / derive_spline_vault_pda. There is no deriveSplineRegistryPda in the canonical surface and no per-market maker seat list. A creator owns one spline for a feed/duration/creator identity and may attach it to only one compatible market at a time.

SplineAccount is exactly 896 bytes, version 1, discriminator SPLINE\0\0. Its shape uses CurveLevel endpoint/offset entries. Reserved bytes must remain zero.

InitSpline#

Creates the creator-owned account and vault. The shape contains a bid-level count, ask-level count, and sixteen fixed-width CurveLevel entries per side; the counts may not exceed sixteen. The maker supplies the feed, duration, initial midpoint, freshness limit, quote authority, and default commitment.

The base accounts are creator signer, spline PDA, spline vault PDA, settlement mint, config, token program, and system program. An optional terminal recorder pair may be appended when event recording is requested.

UpdateSplineShape#

Only the creator may replace the compiled shape. The configured quote authority is intentionally limited to the cache-hot UpdateSplineMid publisher path; it cannot rewrite level capacity, commitment, or attachment state. The update validates level ordering, offsets, bounds, commitment, and quote age before writing the account. If the spline is attached, the optional market account is supplied in the canonical position so the update cannot bypass market-state checks.

UpdateSplineMid#

The hot-path payload is:

sequence:u64-le
expected_generation:u32-le
quote_origin_unix:i64-le
new_mid_price_bps:u16-le
active:bool:u8

The serialized payload is exactly 23 bytes. The sequence must be the checked successor of the stored sequence; u64::MAX cannot wrap. The expected shape generation, quote authority, origin timestamp, freshness bound, midpoint range, and offset bounds are all authenticated. The instruction has no recorder tail so quote publishing remains compact.

AttachSpline, matching, and settlement#

AttachSpline binds the spline to one compatible market and moves the explicit commitment into the market vault. It validates feed/duration, settlement mint, creator authority, market state, shape, and the fragmented-fill commitment bound. PlaceOrder consumes the attached spline through the canonical account grammar and tracks consumed bid/ask lots persistently.

SettleSpline retires YES/NO inventory once, returns terminal payout and unused commitment, and clears the attachment. A repeated settlement is an idempotent no-op. CloseSpline requires detached state and an empty vault. Recovery is performed only by canonical RecoverSpline, which validates destinations and rolls back atomically if any token CPI fails.

Recorder tails and cross-client parity#

The recorder pair is optional and terminal for lifecycle instructions that support events. Every SDK must preserve the exact account order and mutability described by the generated IDL and spec/launch/contract.json. The IDL test asserts the UpdateSplineMid field sequence and 23-byte payload sum.

When adding a new client, use the Rust instruction vectors as the byte-level oracle and run the TypeScript, Rust, Python, CLI, IDL, and indexer spline test suites. Do not copy historical examples that mention SplineRegistry, eight makers, region parameters, auto-attach flags, or V2 names.