Skip to main content

Crate nucleus_substrate_sdk

Crate nucleus_substrate_sdk 

Source
Expand description

§nucleus-substrate-sdk

Demand-side SDK for the Nucleus substrate. Composes:

Two top-level affordances:

  • Client — async HTTP wrapper over the hub’s REST surface (agent card, JWKS, list auctions, post auction, submit bid, match, receipts, counters).
  • verify_receipt_fully — the “did this happen and is it consistent?” entry point. Verifies the receipt’s top-level Ed25519 signature AND walks each projection through its lifter’s structural verifier.

§Example: full verify against a live hub

use nucleus_substrate_sdk::{Client, verify_receipt_fully};

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());

Re-exports§

pub use client::Client;
pub use client::HubError;

Modules§

client
Async HTTP client over the auction hub. One method per public route. Returns anyhow::Result<T> for caller ergonomics.

Structs§

AgentBid
ExternalityProfile
One agent’s claims about the externalities they would impose if awarded a given auction. Each claim is signed by a trusted oracle; the hub verifies signatures before the VCG path consumes them.
FlowBody
Wire-stable shape for the Flow projection body.
IdentityBody
Wire-stable shape for the Identity projection body.
JwtSvidClaims
Minimum required JWT-SVID claims per the spec. Extra claims are allowed (and ignored here); serde_json::Value capture is left for callers that need provider-specific extensions.
MatchResult
OpaqueSignedClaim
A signed externality claim, opaque from the SDK’s perspective. The hub deserializes the inner signed_bytes against the oracle’s verifying key; SDK consumers pass through whatever bytes they received from their oracle.
PostedAuction
Receipt
The colimit envelope. Holds a session + any subset of its projections, signed with the issuer’s Ed25519 key.
Session
The unit of authorship. Every projection projects from this.
VcgKnapsackBody
Body of a knapsack-VCG-cleared auction’s Economic projection.
VcgKnapsackOutcome
VcgMatchResult
VerifyReport
Result of verify_receipt_fully. Holds the list of projection kinds that successfully verified — clients can sanity-check this against the set they expected to be present.
VickreyBody
Body of a single-good Vickrey-cleared auction’s Economic projection.
VickreyOutcome

Enums§

EconomicBody
Discriminated union of the two body shapes — what verify_economic_projection_shape parses out of a Projection::Economic’s body Value.
EconomicVerifyError
FlowVerifyError
IdentityVerifyError
Projection
One projection of a session into a verifiable record.
ReceiptError
ResourceDim
One axis of externality the auction internalizes. Each variant captures a measurable externality and an oracle that signs claims about it.
SubstrateVerifyError

Functions§

flow_projection
Build a Projection::Flow carrying the supplied snapshot.
identity_projection
Build a Projection::Identity carrying the supplied JWT-SVID. Callers will typically place this into the projections field of a nucleus_substrate_core::Receipt.
vcg_knapsack_projection
Pack a cleared knapsack-VCG auction into a Projection::Economic body.
verify_economic_projection_shape
Verify structural well-formedness of an Economic projection body. Returns the parsed typed body on success. Cryptographic signature verification happens on the parent Receipt.
verify_flow_projection_shape
Verify that a FlowBody is well-formed: version matches the lifter’s, lattice-level strings are in their stable vocabularies, the “any-X” flags are consistent with the ceiling levels.
verify_identity_projection
Verify an Identity projection offline against the issuer’s JWKS.
verify_receipt_fully
The composite verifier. Runs:
vickrey_projection
Pack a cleared single-good Vickrey auction into a Projection::Economic body.