Verify a Spoolis outcome receipt

An Outcome Receipt is a signed attestation of delivered work: acceptance criteria agreed before delivery, what passed, and what was earned.

from spoolis_receipt_verifier import verify_outcome_receipt

result = verify_outcome_receipt(receipt, trust_set=trust_set)
print(result["valid"])
print(receipt["amounts"]["earned"])

Install

pip install spoolis-receipt-verifier

No Spoolis account is required to verify a receipt. The package uses cryptography for Ed25519 signature verification and supports Python 3.10 or later.

Require an outcome

require_outcome verifies the full receipt before applying the consumer's policy. This example acts only on a valid outcome with a passing result, at least 100 accepted units, and fully satisfied evidence requirements:

from spoolis_receipt_verifier import require_outcome

required = require_outcome(
    receipt,
    {
        "minimum_status": "pass",
        "min_accepted_units": 100,
        "evidence_requirements": "satisfied",
    },
    trust_set=trust_set,
)

if not required["ok"]:
    raise RuntimeError(", ".join(required["reasons"]))

A partial batch has result: "partial", not pass. To act on partial batches, set minimum_status to partial or omit it, then gate on min_accepted_units, min_accepted_ratio, or min_earned. The receipt's amounts.earned excludes rejected and uncertain units.

Reading partial, unitized results

The accepted_units, rejected_units, and uncertain_units helpers return published unit rows for one verdict. They return None when per-unit rows were not published. earned_amount returns the decimal string or None.

Acting on an Outcome

These helpers shape data from a receipt you have already verified. They do not execute an action or call a payment rail.

from spoolis_receipt_verifier import accepted_units_export, hold_list, retry_list, settlement_instruction

continue_with = accepted_units_export(receipt)
retry = retry_list(receipt)
hold = hold_list(receipt)
settlement = settlement_instruction(receipt, status)

Continue from accepted units, retry rejected units, and hold uncertain units for escalation. settlement_instruction passes through the receipt's earned decimal string and refuses demo receipts or a provided status that is not active. The consumer owns action and payment policy.

Trust material

Spoolis publishes receipt trust material at https://spoolis.com/.well-known/spoolis-keys.json. Pin the receipt entries you accept and pass the selected environment's array as trust_set. fetch_trust_set(url, environment) is an online convenience, while verification itself remains offline.

Offline verification and online status

Signature validity is offline and permanent when the verifier has the receipt and a pinned trust set. Online correction and revocation status is optional:

from spoolis_receipt_verifier import fetch_receipt_status, verify_outcome_receipt

status = fetch_receipt_status("https://spoolis.com", receipt["id"])
result = verify_outcome_receipt(receipt, trust_set=trust_set, status_source=status)

Without a status source, verification includes the status_source_unavailable advisory. When a trust entry includes valid_from or valid_to, a receipt issued outside that window includes the advisory key_outside_validity_window. The advisory does not change validity.

Security model

A valid result proves that a supplied trusted key signed the receipt, the content-derived ID matches, and recognized structural and arithmetic checks pass. It does not prove that referenced evidence is true, resolve actor identities, grant payment authority, or prove payment settlement. Consumers must enforce their own authorization and consume-once rules.

See the receipt verification documentation for integration details.