substrate-sdk-python

Build shellbound applications. Any Python framework. Any deployment. Trust rooted in hardware.

Install

pip install substrate-sdk[django]

Django (2 lines)

# settings.py
INSTALLED_APPS = [
    ...
    'substrate_sdk.django',
]
MIDDLEWARE = [
    ...
    'substrate_sdk.django.ShellboundMiddleware',
]

Every request is Chronicle-attributed. Every model save is Chronicle-recorded. If a bascule shell is present: fully governed. If not: development mode, works normally.

Direct usage

from substrate_sdk import ShellApp

app = ShellApp(shard_name="my-app", capabilities={"network": True})
context = app.register()
print(context.is_governed)  # True if shell present
print(context.shard_did)     # DID assigned by shell

What this does

When running inside a Substrate FFC:

• Your process gets a DID + SPIFFE SVID
• Your process gets a governed accord
• Every request is Chronicle-attributed
• Every operation is audit-verifiable
• You participate in the governance fabric

When running locally (no shell):

• Development mode — everything works normally
• Chronicle events go to stdout
• No governance enforcement
• Zero impact on application behavior

Phase B: HFL Direct Binding (planned)

When the HFL kernel module is present, substrate_sdk will route Chronicle events through substrate-hfl-python (PyO3) instead of stdout. This upgrades a Tier 4 deployment to Tier 1/2 with zero application code changes.

Phase A (current):  SDK → stdout → bascule-filter → Chronicle
Phase B (planned):  SDK → substrate-hfl-python (PyO3) → HFL → Chronicle

substrate-hfl-python is a new crate in the substrate workspace:

• Depends on hfl-types
• Exposes: chronicle_write(), accord_check(), session_get()
• substrate_sdk/chronicle.py detects HFL availability and routes automatically