@stargazebase/provider-sdk

Device-side primitives for Stargaze Attest — TEE-sign a sensor record, emit both privacy tiers of EAS attestation, verify the corridor / task / sensor binding off-chain.

This is the SDK a robotics / drone / AV team integrates on the device itself. The verification half of the same primitives lives in @stargaze/shared/attest so a consumer (verifier console, indexer, settlement engine) can re-derive every check without pulling provider-sdk in.

The legacy MPP / marketplace surface (StargazeMppVerifier, voucher recovery, x402 receipts, the monetize decorator) is still exported from this package but parked, not deleted — payments are no longer the wedge. New integrations should target the attest surface below.

What you get

| Surface | What it does | |---|---| | TeeSigner | Interface for the device's secure-element signing primitive — one method, signTeeDigest(digest). A production signer is backed by Secure Enclave / Strongbox / TrustZone / an HSM. | | LocalKeyTeeSigner | Reference soft secp256k1 signer over a raw private key. Useful for tests, the fork demo, and devices with no enclave wired up. Never ship to production hardware. | | signSensorRecord(signer, draft) | Re-derive teePayloadDigest, sign it, return the completed SensorProvenanceAttestation record. | | signAndAttestSensor({...}) | One call that signs the draft and emits both privacy tiers — the public sensor-provenance attestation and the EAS Merkle private-data envelope — over the same signed record. | | commitSensorPayload(rawBytes) | Canonical dataHash commitment over a private payload. | | Re-exports from @stargaze/shared/attest | The three EAS schemas, buildCorridorAttestation, buildTaskCompletion- / buildSensorProvenance- builders, verifyCorridorBinding, verifyTaskCompletionBinding, verifyTeeSignature, teePayloadDigest, and the EAS Merkle selective-disclosure tier (buildPrivateAttestation, discloseFields, verifyDisclosure). |

Device-side flow

import {
  LocalKeyTeeSigner,
  signAndAttestSensor,
  commitSensorPayload,
  discloseFields,
} from '@stargazebase/provider-sdk';

const signer = new LocalKeyTeeSigner(devicePrivateKey);   // or a real-TEE signer

// 1. Capture + commit the private payload.
const dataHash = commitSensorPayload(rawSensorBytes);

// 2. TEE-sign once, get both privacy tiers.
const { record, attestation, privateData } = await signAndAttestSensor({
  deviceId, sensorType, dataHash,
  capturedAt: BigInt(Math.floor(Date.now() / 1000)),
  signer,
});

// 3. Submit whichever tier the deployment uses (or both):
//    • attestation  — public on-chain sensor-provenance, all fields visible
//    • privateData — Merkle root on-chain, fields stay on the device
await eas.attest({ schema: attestation.schemaUid, data: attestation.data, ... });
await eas.attest({ schema: privateData.schemaUid, data: privateData.data, ... });

// 4. Later, disclose one field to a third party without revealing the rest.
const disclosure = discloseFields(privateData.tree, ['sensorType']);

Corridor-compliance flow (ZK predicate tier)

import {
  buildCorridorAttestation,
  verifyCorridorBinding,
} from '@stargazebase/provider-sdk';

const built = buildCorridorAttestation({
  deviceId, zoneId,
  proof,                       // Groth16 calldata from @stargaze/vault-circuits
  windowStart, windowEnd,
});
await eas.attest({ schema: built.schemaUid, data: built.data, ... });

// Consumer side — verify the attestation is bound to the same proof:
const result = verifyCorridorBinding(built.record, proof);
// { bound: true, box } | { bound: false, reason }
// then call GeofenceVerifier.verifyProof on-chain to confirm the proof itself.

Run the tests

npm test --workspace @stargazebase/provider-sdk

End-to-end fork rehearsal

scripts/eas-fork-demo.mjs boots an Anvil Base-mainnet fork, registers the three schemas, runs signAndAttestSensor → EAS.attest, exercises selective disclosure, deploys GeofenceVerifier and submits a corridor attestation anchoring a real Groth16 proof, and finally a task-completion attestation with the attester-EOA = device-wallet binding check. Run via:

make eas-fork-demo

Examples (legacy MPP — parked)

The Express / Hono / Fastify monetisation demos under examples/ exercise the parked MPP surface and are kept for reference only. Do not build new integrations against them.