Olive Solana Python SDK

SDK 0.4.0 implements Olive's blind RFQ contract. It requires the coordinated backend cutover: submission receipts report accepted, competitive prices and outbid callbacks are removed, and selection/fill events retain their meaning. See the migration and cutover guide.

The supported async Python client for market makers quoting Olive Solana options. It implements the native /maker/v1/ws protocol and nothing else—there is no translation or compatibility layer.

ManagedMaker is the recommended API. Maker code supplies entry premium or exit amount and funding source; the SDK validates requests, binds canonical quote fields, allocates durable quote IDs and entry nonces, signs through a local/HSM callback, persists before submission, reconnects, and durably routes lifecycle events.

Install

# From this repository:
pip install -e "packages/python-sdk[postgres]"

# After the distribution is published:
pip install "olive-solana-sdk[postgres]"

Python 3.11 or newer is required. Upgrade an existing store once by constructing PostgresMakerStore(database_url, schema_mode="migrate") with a migration-capable role and awaiting store.initialize(), then store.close(). This validates original digests and preserves pending quotes and event state. Use schema_mode="verify" for subsequent production starts. The packaged schemas/postgres-maker-store-v2.sql bootstraps new stores only; existing v1 stores require the SDK migration. InMemoryMakerStore is test-only.

The new-store schema is also available programmatically with postgres_maker_store_schema() so deployment tooling does not need to locate the installed wheel's data directory.

Managed maker quickstart

import asyncio
import os

from olive_solana import (
    DeploymentIdentity,
    LocalKeypairMakerSigner,
    ManagedMaker,
    ManagedMakerEventHandlers,
    ManagedMakerOptions,
    PostgresMakerStore,
)


async def main() -> None:
    signer = LocalKeypairMakerSigner.from_json_file(
        os.environ["OLIVE_QUOTE_SIGNER_KEYPAIR"]
    )
    store = PostgresMakerStore(
        os.environ["DATABASE_URL"], schema_mode="verify"
    )

    async def entry(rfq):
        premium = await price_entry(rfq.request)
        return (
            rfq.decline("outside_risk_limits")
            if premium is None
            else rfq.quote(collateral_mode="credit", premium_usdc=premium)
        )

    async def exit_(rfq):
        amount = await price_exit(rfq.request)
        return (
            rfq.decline("outside_risk_limits")
            if amount is None
            else rfq.quote(
                exit_amount_usdc=amount,
                usdc_source=os.environ["OLIVE_EXIT_USDC_SOURCE"],
            )
        )

    maker = ManagedMaker(
        ManagedMakerOptions(
            entry_collateral_modes=("credit",),
            url=os.environ["OLIVE_MAKER_WS_URL"],
            maker_config=os.environ["OLIVE_MAKER_CONFIG"],
            expected_deployment=DeploymentIdentity(
                program_id=os.environ["OLIVE_PROGRAM_ID"],
                genesis_hash=os.environ["OLIVE_GENESIS_HASH"],
                chain_tag=os.environ["OLIVE_CHAIN_TAG"],
            ),
            signer=signer,
            store=store,
            topics=("btc", "sol"),
            products=(0, 1),
            on_entry_rfq=entry,
            on_exit_rfq=exit_,
            events=ManagedMakerEventHandlers(
                # Selection is feedback, not execution.
                on_entry_selected=record_selection,
                # Only finalized fills trigger hedging/reconciliation.
                on_entry_filled=hedge_finalized_entry,
                on_exit_filled=reconcile_finalized_exit,
                on_prefunding_required=alert_prefunding,
                on_funding_required=alert_funding,
                on_default=page_risk,
                on_settlement=record_settlement,
            ),
        )
    )
    try:
        await maker.run()
    finally:
        await store.close()


asyncio.run(main())

Lifecycle delivery is at least once. Make every external side effect idempotent by eventId; a process can stop after performing the side effect but before the SDK records local handler completion. Prefunding, funding, and default events must have explicit handlers unless the generic on_event handler covers them.

The local keypair in this quickstart is for laptop tests or a tightly controlled key-file deployment. Production remote/HSM integrations use CallbackMakerSigner and never pass private-key bytes to the maker process:

from olive_solana import CallbackMakerSigner, SignerContext


async def sign_with_remote_provider(
    digest: bytes,
    context: SignerContext,
) -> bytes:
    if len(digest) != 32:
        raise ValueError("expected a 32-byte Olive digest")
    signature = await remote_provider.sign_ed25519(
        key_id="olive-quote-signer",
        message=digest,
        audit_context={"purpose": context.purpose},
    )
    if len(signature) != 64:
        raise ValueError("expected a 64-byte Ed25519 signature")
    return signature


signer = CallbackMakerSigner(
    public_key="<remote Ed25519 public key in canonical base58>",
    callback=sign_with_remote_provider,
)

The callback signs the supplied raw 32-byte SHA-256(preimage) digest with ordinary Ed25519 and returns the raw 64-byte signature. Do not hash again, sign encoded text/the full preimage, or use Ed25519ph. The remote public key may be the finalized on-chain MakerConfig.quoteSigner.

An empty topic or product collection subscribes to everything authorized by maker.hello. Keep takeover_existing_session=False for ordinary starts; enable it only for an intentional failover.

Operational preflight

The doctor authenticates without subscribing, taking over a live maker, or submitting quotes. Its convenience CLI intentionally uses a local test keypair:

olive-maker-doctor --topics btc,sol --products 0,1 \
  --exit-sources "$OLIVE_EXIT_USDC_SOURCE"

olive-maker-doctor --json > maker-doctor.json

Connection and deployment values default from OLIVE_MAKER_WS_URL, OLIVE_MAKER_CONFIG, OLIVE_PROGRAM_ID, OLIVE_GENESIS_HASH, OLIVE_CHAIN_TAG, and OLIVE_QUOTE_SIGNER_KEYPAIR.

Remote/HSM deployments MUST NOT export their private key to use the CLI. Call run_maker_doctor(MakerDoctorOptions(..., signer=signer)) programmatically with the same CallbackMakerSigner used by the managed maker, and retain report.to_dict() as the machine-readable preflight record.

Wire types and schema

The complete required/optional DTO catalog is published at maker-websocket-v1.schema.json and included in the wheel at olive_solana/schemas/maker-websocket-v1.schema.json. Python exports typed RFQ, quote, selected, filled, decline, and error/result shapes from olive_solana. Missing required fields fail before maker callbacks run; unknown additive server fields are preserved, while outbound quotes remain strict. The normative semantics and signing preimages are in the Maker WebSocket API v1.

Reliability contract

• Wire integers remain canonical decimal strings.
• Entry nonces are durable; V6 exit quotes have no wire nonce and are replay-safe because a successful exit closes the bound position.
• Complete quote, digest, and signature are committed before submission.
• Restart retries only the exact stored quote and signature.
• Durable events are stored before event.ack; local handler completion is persisted independently.
• quote.selected and exit_quote.selected are not fills. Only finalized trade.filled and exit.filled are canonical execution signals.
• Signatures and private signer data are never included in SDK status events.

The low-level MakerWsClient remains available for makers requiring custom orchestration. Releases must pass the shared fixture/digest suite and all fail-closed maker conformance scenarios.

Development

python -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/ruff check .
.venv/bin/mypy src
.venv/bin/pytest
.venv/bin/python -m build

Release

PyPI releases use trusted publishing from .github/workflows/publish-python-sdk.yml; no long-lived API token is stored in GitHub. Configure the PyPI publisher for repository macols77/olive, workflow publish-python-sdk.yml, and environment pypi. Pushing a tag that exactly matches python-sdk-v<pyproject version> builds, checks, and uploads both the wheel and source distribution. Protect the pypi environment with required reviewer approval. A failed release can be retried from GitHub Actions with Run workflow by supplying the same existing tag; the workflow checks out that tag and verifies it exactly matches the package version before publishing.

Credit and JIT entry routes

Entry subscriptions require explicit route preferences (entryCollateralModes in TypeScript, entry_collateral_modes in Python). Use credit, JIT, both, or an empty list for exit-only delivery. Each managed entry decision must explicitly select an advertised route. Entry signing uses the chosen descriptor in signing.routes; hello uses entryRoutes and exitQuoteDomain. Numeric modes and the previous entry signing/domain fields are rejected.

PostgreSQL stores now use version 2. Initialize once in migrate mode to archive and normalize historical records with digest verification, then use verify for subsequent starts. Do not relabel the version manually. The packaged v2 SQL bootstraps new stores; existing v1 stores must run SDK migration. See docs/credit-jit-implementation.md in the repository for funding tools, persistence, and coordinated rollout requirements.