olive-solana-sdk 0.1.0__tar.gz

olive_solana_sdk-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# deps
+node_modules/
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+
+# solana / anchor
+solana/target/*
+!solana/target/idl/
+solana/target/idl/*
+!solana/target/idl/olive_options.json
+solana/.anchor/
+solana/.surfpool/
+solana/test-ledger/
+solana/evidence/
+solana/deployments/*.json
+!solana/deployments/*.example.json
+backend/config/devnet.configured.json
+
+# next.js
+frontend/.next*/
+frontend/out/
+
+# build
+dist/
+*.tsbuildinfo
+
+# env
+.env
+.env.*
+.env.local
+.env.*.local
+!.env.example
+!.env.devnet.example
+
+# misc
+.DS_Store
+*.log
+
+# Visual QA output from `npm run qa:share-cards`
+frontend/.qa-cards/

olive_solana_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Olive
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

olive_solana_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.5
+Name: olive-solana-sdk
+Version: 0.1.0
+Summary: Async Python SDK for market makers quoting Olive Solana options
+Project-URL: Documentation, https://olive.ag/docs
+Project-URL: Repository, https://github.com/macols77/olive
+Project-URL: Issues, https://github.com/macols77/olive/issues
+Author: Olive
+License-Expression: MIT
+License-File: LICENSE
+Keywords: market-maker,olive,options,rfq,solana
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: jsonschema<5,>=4.23
+Requires-Dist: solders<1,>=0.26
+Requires-Dist: websockets<18,>=15
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: mypy<2,>=1.15; extra == 'dev'
+Requires-Dist: psycopg[binary,pool]<4,>=3.2; extra == 'dev'
+Requires-Dist: pytest-asyncio<2,>=0.25; extra == 'dev'
+Requires-Dist: pytest<10,>=8.3; extra == 'dev'
+Requires-Dist: ruff<1,>=0.11; extra == 'dev'
+Requires-Dist: types-jsonschema<5,>=4.23; extra == 'dev'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary,pool]<4,>=3.2; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# Olive Solana Python SDK
+
+The supported async Python client for market makers quoting Olive Solana options.
+It implements only the native `/maker/v1/ws` protocol—there is no EVM or legacy
+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 nonces, signs through a local/HSM callback,
+persists before submission, reconnects, and durably routes lifecycle events.
+
+## Install
+
+```bash
+# 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. Apply the packaged
+`schemas/postgres-maker-store-v1.sql` with the maker's migration role and use
+`schema_mode="verify"` in production. The default migration mode is intended for
+development. `InMemoryMakerStore` is test-only.
+
+The exact migration 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
+
+```python
+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(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(
+            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_funding_required=alert_funding,
+                on_default=page_risk,
+                on_settlement=record_settlement,
+            ),
+        )
+    )
+    try:
+        await maker.run()
+    finally:
+        await store.close()
+
+
+asyncio.run(main())
+```
+
+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:
+
+```bash
+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`.
+
+## Reliability contract
+
+- Wire integers remain canonical decimal strings.
+- Entry and exit nonce namespaces are separate.
+- 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
+
+```bash
+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.

olive_solana_sdk-0.1.0/README.md

@@ -0,0 +1,165 @@
+# Olive Solana Python SDK
+
+The supported async Python client for market makers quoting Olive Solana options.
+It implements only the native `/maker/v1/ws` protocol—there is no EVM or legacy
+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 nonces, signs through a local/HSM callback,
+persists before submission, reconnects, and durably routes lifecycle events.
+
+## Install
+
+```bash
+# 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. Apply the packaged
+`schemas/postgres-maker-store-v1.sql` with the maker's migration role and use
+`schema_mode="verify"` in production. The default migration mode is intended for
+development. `InMemoryMakerStore` is test-only.
+
+The exact migration 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
+
+```python
+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(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(
+            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_funding_required=alert_funding,
+                on_default=page_risk,
+                on_settlement=record_settlement,
+            ),
+        )
+    )
+    try:
+        await maker.run()
+    finally:
+        await store.close()
+
+
+asyncio.run(main())
+```
+
+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:
+
+```bash
+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`.
+
+## Reliability contract
+
+- Wire integers remain canonical decimal strings.
+- Entry and exit nonce namespaces are separate.
+- 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
+
+```bash
+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.

olive_solana_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "olive-solana-sdk"
+version = "0.1.0"
+description = "Async Python SDK for market makers quoting Olive Solana options"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Olive" }]
+keywords = ["olive", "solana", "options", "rfq", "market-maker"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: AsyncIO",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = [
+  "jsonschema>=4.23,<5",
+  "solders>=0.26,<1",
+  "websockets>=15,<18",
+]
+
+[project.optional-dependencies]
+postgres = ["psycopg[binary,pool]>=3.2,<4"]
+dev = [
+  "build>=1.2,<2",
+  "mypy>=1.15,<2",
+  "psycopg[binary,pool]>=3.2,<4",
+  "pytest>=8.3,<10",
+  "pytest-asyncio>=0.25,<2",
+  "ruff>=0.11,<1",
+  "types-jsonschema>=4.23,<5",
+]
+
+[project.scripts]
+olive-maker-doctor = "olive_solana.cli:doctor_main"
+olive-maker-conformance = "olive_solana.cli:conformance_main"
+
+[project.urls]
+Documentation = "https://olive.ag/docs"
+Repository = "https://github.com/macols77/olive"
+Issues = "https://github.com/macols77/olive/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/olive_solana"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/olive_solana", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC"]
+ignore = ["E501", "ASYNC110"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/olive_solana/__init__.py" = ["F401"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+packages = ["olive_solana"]
+mypy_path = "src"
+warn_unused_ignores = false

olive_solana_sdk-0.1.0/src/olive_solana/__init__.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("olive-solana-sdk")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+from .conformance import (  # noqa: E402
+    MAKER_CONFORMANCE_SCENARIOS,
+    ConformanceEnvironment,
+    format_maker_conformance_report,
+    run_maker_conformance_suite,
+)
+from .constants import (  # noqa: E402
+    CREDIT_ENTRY_QUOTE_DOMAIN,
+    DAILY_ENTRY_QUOTE_DOMAIN,
+    EXIT_QUOTE_DOMAIN,
+    MAKER_WS_AUTH_DOMAIN,
+    MAKER_WS_MAX_FRAME_BYTES,
+    MAKER_WS_PATH,
+    MAKER_WS_PROTOCOL_VERSION,
+)
+from .digests import (  # noqa: E402
+    decode_bytes,
+    entry_quote_digest,
+    exit_quote_digest,
+    integer_le,
+    maker_ws_auth_digest,
+    public_key_bytes,
+)
+from .doctor import (  # noqa: E402
+    MakerDoctorCheck,
+    MakerDoctorOptions,
+    MakerDoctorReport,
+    format_maker_doctor_report,
+    run_maker_doctor,
+)
+from .managed_maker import (  # noqa: E402
+    DeclineDecision,
+    EntryQuoteDecision,
+    ExitQuoteDecision,
+    ManagedEntryRfq,
+    ManagedExitRfq,
+    ManagedMaker,
+    ManagedMakerEventHandlers,
+    ManagedMakerOptions,
+)
+from .schema import (  # noqa: E402
+    ProtocolValidationError,
+    parse_lifecycle_event,
+    parse_notification,
+    parse_result,
+    parse_rfq,
+    validate_entry_quote,
+    validate_exit_quote,
+)
+from .signer import CallbackMakerSigner, LocalKeypairMakerSigner  # noqa: E402
+from .store import InMemoryMakerStore, PostgresMakerStore, postgres_maker_store_schema  # noqa: E402
+from .types import (  # noqa: E402
+    AckResult,
+    AuthChallenge,
+    BucketChainEvent,
+    CapacityResult,
+    ConnectionStatus,
+    DeclineResult,
+    DeploymentIdentity,
+    EntryExpiredUnfilled,
+    EntryOutbid,
+    EntryQuote,
+    EntryRequest,
+    EntryRfqMessage,
+    EntryRfqParams,
+    EntrySelected,
+    EntrySubmitResult,
+    ExitExpiredUnfilled,
+    ExitFilled,
+    ExitOutbid,
+    ExitPaymentCapacity,
+    ExitQuote,
+    ExitRequest,
+    ExitRfqMessage,
+    ExitRfqParams,
+    ExitSelected,
+    ExitSource,
+    ExitSubmitResult,
+    FundingRequired,
+    Hello,
+    HelloLimits,
+    LifecycleEvent,
+    MakerPosition,
+    MakerSigner,
+    MakerStore,
+    MakerStoreScope,
+    PositionBucket,
+    PositionExpired,
+    PositionRedeemed,
+    PositionsResult,
+    PrefundingRequired,
+    Product,
+    QuoteDomains,
+    RecoverResult,
+    RfqMessage,
+    SettlementRecorded,
+    SignerContext,
+    StoredEvent,
+    StoredSubmission,
+    SubscriptionResult,
+    TopicCapacity,
+    TradeFilled,
+)
+from .ws_client import (  # noqa: E402
+    MakerWsClient,
+    MakerWsClientOptions,
+    MakerWsRpcFailure,
+    MakerWsTerminalProtocolFailure,
+    maker_ws_url,
+    normalize_topics,
+)
+
+del PackageNotFoundError, version
+__all__ = [
+    name
+    for name, value in globals().items()
+    if not name.startswith("_") and name != "annotations" and value.__class__.__name__ != "module"
+]