Skip to content
SDKs

Python SDK

The vitrified Python package: async-first, supports hashing, submission, bundle fetch, and offline verification with the same Verdict shape as the JS SDK.

Python SDK

The Python SDK lives under sdks/python/. It targets Python 3.12+, is async-first, and produces byte-identical leaf identifiers and verdicts to the JavaScript SDK.

Install

uv add vitrified
# or
pip install vitrified

Configure

import os
from vitrified import Vitrified

vitrified = Vitrified(api_key=os.environ["VITRIFIED_API_KEY"])

Hash an artifact

digest = await vitrified.hash_file("./build/release.tar.gz")
# → "9f86d081884c7d65..."

Synchronous helpers exist (hash_file_sync, hash_bytes_sync) for use outside an async context.

Submit an attestation

submission = await vitrified.attestations.create(
    artifact={"sha256": digest},
    metadata={
        "schema": "slsa.provenance.v1",
        "predicate": {
            "buildType": "https://example.com/build-type",
            "builder": {"id": "https://github.com/Attestations/GitHubActionsBuilder@v1"},
            # ...
        },
    },
    idempotency_key="release-1.2.3",  # optional
)

print(submission.id)  # "sub_01J..."

Wait for the bundle

bundle = await vitrified.attestations.wait_for_bundle(submission.id, timeout_seconds=120)

Verify a bundle (offline)

from vitrified import verify_bundle

verdict = verify_bundle(bundle)

if verdict.is_verified:
    print("Bundle verified.")
elif verdict.overall == "partial":
    for mechanism, m in verdict.mechanisms.items():
        print(f"  {mechanism}: {m.status}")
else:
    print(f"Verification failed: {verdict.message}")

Bitcoin oracle (optional)

import httpx
from vitrified import verify_bundle, BitcoinBlockHeaderOracle

class HttpOracle(BitcoinBlockHeaderOracle):
    async def get_block_header_hash(self, height: int) -> str:
        async with httpx.AsyncClient() as client:
            r = await client.get(f"https://blockstream.info/api/block-height/{height}")
            return r.text

verdict = verify_bundle(bundle, bitcoin_block_header_oracle=HttpOracle())

Without an oracle, OTS lands verified_partial (structurally valid, chain anchor unchecked).

List submissions

async for submission in vitrified.attestations.list(filter={"schema": "purl"}):
    print(submission.id, submission.metadata)

The list iterator handles pagination transparently. Pass limit= to bound the iteration.

Export

await vitrified.exports.create(
    destination={"kind": "s3", "bucket": "my-attestations", "prefix": "vitrified/"},
    filter={"schema": "slsa.provenance.v1"},
)

Webhooks

from vitrified import verify_webhook

event = verify_webhook(
    body=request.body,
    signature_header=request.headers["vitrified-signature"],
    secret=os.environ["VITRIFIED_WEBHOOK_SECRET"],
)

Sync vs. async

Every async method has a *_sync counterpart for scripts and notebooks:

from vitrified import Vitrified

v = Vitrified(api_key=...)
sub = v.attestations.create_sync(artifact={"sha256": digest}, metadata={...})

Source

sdks/python/ — full source and type stubs.

JavaScript / TypeScript SDK

The @vitrified/sdk package: hashing, submission, bundle fetch, offline verification — same API across Node and browser.

Verifier CLI

vitrified verify — a standalone command-line verifier for Vitrified proof bundles. No network calls required for core verification.

Was this page helpful?

On this page

Python SDKInstallConfigureHash an artifactSubmit an attestationWait for the bundleVerify a bundle (offline)Bitcoin oracle (optional)List submissionsExportWebhooksSync vs. asyncSource