nucleus-substrate-sdk

Demand-side SDK for the Nucleus substrate. Composes:

• nucleus-substrate-core — Session, Receipt, Projection
• nucleus-identity-projection — JWT-SVID lifter
• nucleus-flow-projection — Denning-lattice lifter
• nucleus-mechanism-vcg — Pigouvian-VCG lifter

Two top-level affordances:

• Client — async HTTP wrapper over the hub's REST surface
• verify_receipt_fully — composite offline verifier that walks every projection in a Receipt

Quick example

use nucleus_substrate_sdk::{Client, verify_receipt_fully};

# async fn ex() -> anyhow::Result<()> {
let client = Client::new("https://nucleus-auction-hub.fly.dev")?;
let receipt = client.fetch_receipt("auction-id").await?;
let jwks    = client.jwks().await?;
let report  = verify_receipt_fully(&receipt, &jwks)?;
println!("✓ verified {} projections", report.projection_kinds.len());
# Ok(()) }

The composite verifier

Pattern lifted from mc_attestation_verifier's And/Or chain. verify_receipt_fully does:

1. Receipt::verify against issuer's Ed25519 verifying key pulled from JWKS by matching kid.
2. For each projection in the receipt:
   • Identity → verify_identity_projection
   • Flow → verify_flow_projection_shape
   • Economic → verify_economic_projection_shape
   • Capability → skipped in v0.1 (no lifter shipped)

Any failure → SubstrateVerifyError.

Categorical foundation

The composite verifier's correctness is certified in Lean 4 — see receipt_factors_through_projections in formal/Nucleus/Substrate/Colimit.lean. The Receipt is the cocone vertex of the projection-functor wedge; AND-composition of per-leg verifiers is the unique universal map.

License

Dual-licensed under MIT OR Apache-2.0.