SDK docs · sdk/02

Python SDK (embedded mode)

mintid-verifier-sdk: a frozen public surface, one decision entrypoint, five infrastructure ports — and a proof engine pinned inside the wheel.

The public surface

Package mintid-verifier-sdk, import name verifier_core. Python ≥ 3.12. The Rust proof engine ships compiled inside the wheel at a build-time pin — a supported installation cannot end up with a substituted or mismatched engine.

One decision entrypoint, five ports. Everything importable is listed in the block on the right; everything else under verifier_core is internal and may change without notice.

This surface is frozen and test-enforced: a CI test imports exactly this list and fails when it grows or drifts. Changes follow semver — surface or semantics change is a major version.

pythonsdk/02 · verbatim

from verifier_core.presentation import (
    validate_presentation, PresentationDecision, ChainReader,
    DEFAULT_MAX_HEIGHT_LAG,  # and the REASON_* constants
)
from verifier_core.openid4vp import (
    PresentationRequest, IssuerPolicy, ClaimPredicate,
    PRESENTATION_LIFETIME_SECONDS,  # = 10. A constant, deliberately.
    RequestSigner, parse_request,
)
from verifier_core.proof_verifier import (
    PresentationEnvelope, VerifiedPresentation, BindingContext,
    ProofVerifier, binding_context_for,
)
from verifier_core.chain_client import (
    ChainClient, StateQueryPort, TrustedHeaderSource,
    StateQueryResult, ProofOp, verify_membership,
)
from verifier_core.nonce_store import NonceStore, SqliteNonceStore, NONCE_SIZE
from verifier_core.audit import (
    DecisionLog, DecisionRecord, JsonlDecisionLog, InMemoryDecisionLog,
    DECISION_RECORD_FIELDS,
)
from verifier_core import errors, records

The entrypoint

You supply infrastructure, never policy:

Port	Production implementation	Your freedom
`ChainReader`	`ChainClient` over your RPC node(s) + trust-anchor header source	which nodes — never whether reads are proven
`NonceStore`	bundled `SqliteNonceStore` (crash-durable, `synchronous=FULL`)	swap the backend if it keeps atomic exactly-once `consume`
`ProofVerifier`	the wheel's pinned engine	none — implementations must reject any proof not bound to the exact challenge
`DecisionLog`	`JsonlDecisionLog` (or your store over `DecisionRecord`)	where records go — never what they contain
clock	you pass `now_unix`	a skewed clock only makes you more rejecting

pythonsdk/02 · verbatim

decision = validate_presentation(
    request,            # PresentationRequest — the signed challenge you issued
    envelope,           # PresentationEnvelope — the holder's response
    chain=chain,        # ChainReader        — proven on-chain reads
    nonces=nonces,      # NonceStore         — durable, exactly-once consumption
    proofs=proofs,      # ProofVerifier      — the anonymous-proof engine port
    decisions=log,      # DecisionLog        — the minimal R18 sink
    now_unix=now,       # int                — your disciplined clock
    max_height_lag=20,  # local staleness policy (blocks); tighten freely
)
decision.accepted      # bool
decision.reason_code   # closed vocabulary
decision.verified      # VerifiedPresentation | None

Issuing challenges

The policy digest commits to the whole canonical body — tampering with any part of the challenge breaks the proof binding (condition 5).

pythonsdk/02 · verbatim

import secrets
from verifier_core.openid4vp import (
    PresentationRequest, IssuerPolicy, ClaimPredicate,
    PRESENTATION_LIFETIME_SECONDS,
)

request = PresentationRequest(
    session_id=secrets.token_bytes(16).hex(),
    nonce=secrets.token_bytes(32),
    verifier_id=MY_VERIFIER_ID,          # your on-chain registration
    audience="https://checkout.example", # one of your registered exact origins
    request_key_id=MY_REQUEST_KEY_ID,    # registered for that origin
    expires_at_unix=now + PRESENTATION_LIFETIME_SECONDS,
    finalized_chain_height=chain.latest_height(),
    issuer_policy=IssuerPolicy(),        # or restrict accepted issuers / state minimum
    claim_policy=(ClaimPredicate(claim="age_over", value=18, operator=">="),),
)
request.validate_shape(now_unix=now)
signed_body = request.to_json()          # canonical; sign with your registered key

Chain access

ChainClient splits trust into two ports on purpose:

StateQueryPort — any RPC node, assumed malicious. Every answer carries an ics23 proof.
TrustedHeaderSource — your trust anchor. The bundled TrustAnchorHeaderSource reads an operator-designated node (your own node): suitable when you run the node you point it at. Backing this port with a full light client against untrusted peers is on the roadmap; never point the anchor at an arbitrary public RPC.

Absence is never trusted: if a node claims a record doesn't exist, the read fails closed (UnprovenAbsenceError → state_unproven).

Retention (what you keep, all of it)

Exactly one DecisionRecord per decision, accept or reject: session_id, accepted, reason_code, bound_context_digest (32 bytes), decided_at_unix. Serialization emits exactly these keys; tests assert field-set equality. Presentations, proof bytes and claim values are never persisted — treat any schema extension as a privacy review.