Orcestr Commerce Solana for Python

orcestr-commerce-solana adds non-custodial native SOL and Token-2022 checkout to CommerceXL. It verifies raw finalized Solana transactions through standard JSON-RPC and does not require a paid API, webhook provider, private key, or custody service.

The first release deliberately rejects the legacy SPL Token Program, swaps, CPI transfers, batch payments, partial payments, transfer-fee mints, and unknown Token-2022 extensions. Correctness comes from the raw transaction and an immutable settlement snapshot. Public RPC endpoints remain rate-limited infrastructure without an availability SLA; applications can inject any compatible HTTP RPC endpoint or their own node without changing payment contracts.

Install

pip install orcestr-commerce-solana

For local ecosystem development from the Orcestr backend:

uv pip install --python .venv --editable ../../orcestr-commerce-solana/backend

The host application owns the database engine, sessions, Alembic migrations, authentication, authorization, CSRF policy, scheduler, WebSocket transport, treasury configuration, and product pricing. Import orcestr_commerce_solana.models before collecting CommerceBase.metadata; the package intentionally ships no migrations.

Minimal verifier

from orcestr_commerce_solana import HttpSolanaRpc, SolanaTransactionVerifier
from orcestr_commerce_solana.config import SolanaRpcConfig
from orcestr_commerce_solana.constants import MAINNET_GENESIS_HASH

rpc = HttpSolanaRpc(
    SolanaRpcConfig(
        genesis_hash=MAINNET_GENESIS_HASH,
        endpoints=("https://api.mainnet-beta.solana.com",),
    ),
)
verifier = SolanaTransactionVerifier(rpc, used_signatures=my_database_signature_registry)

Build a VerificationRequest from the persisted intent and issuance snapshots, then call await verifier.verify(request). confirmed is always provisional; only a fully decoded finalized transaction produces authoritative MATCH. UNKNOWN is retryable and must never grant a product. REVIEW preserves an on-chain mismatch for reconciliation.

See the repository documentation for the state machine, asset activation, transaction-request endpoint, free RPC operations, CommerceXL registration, FastAPI ports, and threat model.

The default host wiring is intentionally small:

• SolanaApplicationService.build_default(...) supplies authenticated checkout orchestration.
• SolanaFastApiRouterFactory supplies typed routes; the host injects Orcestr Auth actor, ownership, and CSRF dependencies.
• create_sqlalchemy_reconciler(...) supplies leased background reconciliation, DB-backed signature uniqueness, one bounded reference window, and safe expiry/quarantine.
• SolanaProviderRegistrationFactory registers the provider explicitly in CommerceXL 0.3.2 or newer. Version 0.3.2 is the minimum because payment options carry the immutable order amount/currency snapshot and its state machine permits a provisional confirmed payment to expire after a complete final reference scan.

SolanaProviderDependencies requires a host SettlementPriceKeyResolver. It must resolve a stable product/plan/pack code from the order; broad order kinds are intentionally not used as a pricing fallback. For products priced in the database in the same currency as the selected asset, use the recommended exact strategy:

from orcestr_commerce_solana import OrderSnapshotSettlementQuoteProvider

quotes = OrderSnapshotSettlementQuoteProvider(
    {"solana_orcestr": "ORCESTR"},
    version="catalog-v1",
)

The provider requires order.currency == configured currency for the exact validated asset option, converts the human decimal order amount with SolanaAmountCodec, rejects fractional precision instead of rounding, and validates positive u64 plus asset min/max bounds. Asset identity remains the validated option/mint; the display symbol is never a security input. Its immutable quote uses source="order_snapshot" and rounding="exact". FixedSettlementQuoteProvider remains a separate strategy for intentionally precomputed raw prices keyed by (resolved_price_key, asset_option_id); it is not the recommended catalogue-pricing path. A custom RecipientResolver supports either a Beauty treasury or host-verified P2P recipients without changing the verifier.

Transaction issuance is bounded by max_issuances_per_intent (default 16) under the intent row lock. expires_at closes public payment actions. Before reconcile_until, reference reconciliation still settles an exact finalized transfer whose on-chain block_time is inside its immutable issuance acceptance window, and keeps exact confirmed evidence pending for finality. At or after that horizon, proof is fail-closed terminal evidence without a product effect. A transfer submitted outside the acceptance window, or one attached to an already cancelled/expired attempt, is also written to CommerceXL as terminal evidence and never grants the product.

Authenticated candidate checks are durably limited to 16 unique signatures per intent; exact duplicates perform no immediate RPC. Automatic reference discovery verifies at most 16 candidates per intent and 32 per worker pass, reads one 17-entry window, and never paginates attacker-controlled history. Overflow moves an active payment to review or parks an already paid/terminal audit without changing its financial outcome.

Detailed integration and security contracts are in architecture, host integration, and security.

Development

uv sync --frozen
uv run pytest tests
uv build

Python 3.12, 3.13, and 3.14 are supported. All timestamps are timezone-aware UTC and all blockchain amounts cross API boundaries as integer strings.

TransactionVersion.LEGACY denotes Solana's legacy wire-message format for verification only. The package emits v0 transactions, and it does not expose the legacy SPL Token Program as a supported public root API.