Product adoption audit

Quidnug, Product & Adoption Audit

A step-back audit of the full SDK + integration landscape from a product-adoption perspective. What’s in place, what’s missing, and what needs to land before we can realistically drive adoption.

Audit date: 2026-04-19 Scope: Every SDK (clients/), integration (integrations/), deployment artifact (deploy/), and developer-facing doc (docs/, READMEs).

Executive summary

We have excellent depth, 7 SDKs at full protocol parity, 4 domain integrations (sigstore/c2pa/fhir/chainlink/iso20022), Helm chart, observability bundle, browser extension, OIDC bridge, HSM + WebAuthn signer abstractions. Every SDK ships tests, README, and idiomatic examples.

We have adoption gaps in breadth that would stall real-world teams trying to integrate:

Discoverability & positioning, no comparison pages, no landing site, no hosted sandbox.
First-5-minutes friction, every example assumes localhost:8080.
Protocol-level credibility, no published benchmarks, no threat model doc, no cross-SDK interop test.
Use-case coverage, 14 use cases in the overview deck, but only ~6 have runnable example code. Elections, AI agents, credentials are conspicuously absent.
Modern-stack fit, Python SDK is sync-only (async is table-stakes for new Python codebases). No OpenTelemetry. No W3C VC compat.
OpenAPI drift, each SDK is hand-written. Guaranteed to drift without a machine-readable spec.
Operational patterns, no Kafka/NATS bridge, no GitHub Action, no published performance numbers, no load-test recipe.

This document catalogs every gap; the companion commits close the highest-leverage Tier-1 and Tier-2 items.

Audit dimensions

We audit along eight dimensions of SDK/integration adoption:

#	Dimension	Question
1	Discoverability	Can developers find us?
2	First 5 minutes	Can they get it working quickly?
3	Confidence to choose	Do they trust it?
4	Confidence in security	Can they audit it?
5	Fit to use case	Does an example match their problem?
6	Debuggability	When it breaks, can they diagnose?
7	Production-readiness	Can they ship it?
8	Ecosystem maturity	Does it compose with their stack?

Dimension-by-dimension findings

1. Discoverability

Status	Item
🟢	README at repo root with SDK + integration index
🟢	`docs/integration-guide.md` with cross-language examples
🔴	No docs site, nothing at `quidnug.dev` / `quidnug.io`
🔴	Zero SDKs actually on npm / PyPI / crates.io / Maven Central / NuGet (install commands in READMEs will 404)
🔴	No comparison pages (“Quidnug vs PGP WoT”, “vs DIDs”, “vs OAuth roles”)
🔴	No “Awesome Lists” entries (awesome-identity, awesome-cryptography, awesome-decentralized)
🔴	No SEO-optimized “how to do X in language Y” pages
🟡	77-slide deck exists but lives inside the repo; no public landing page
🔴	No launch post, HN / Reddit presence, Dev.to articles
🔴	No video tutorials / YouTube channel

Impact: A developer googling “transitive trust protocol” or “relational trust library” will not find Quidnug today.

2. First 5 minutes

Status	Item
🟢	`deploy/compose/docker-compose.yml` gives a 3-node local network in one command
🟢	Every SDK README has a 30-second quickstart
🟢	`quidnug-cli` provides a usable operator shell
🔴	No public sandbox / testnet. Every quickstart says “assumes a local node”; that’s an immediate first-run block.
🔴	No interactive tutorial (think go.dev/tour)
🔴	No Glitch / StackBlitz / Replit prefab projects
🔴	No “Try it in the browser” playground
🟡	Docker compose works but requires Docker; no pure-binary fallback

Impact: Every single new integrator has to run a node before they can write a line of code. That’s a 20-minute + on-call friction tax.

3. Confidence to choose

Status	Item
🟢	Protocol-level design docs (QDP-0001 through QDP-0011)
🟢	Apache-2.0 license, clear NOTICE
🟢	CI matrix running tests on every PR
🟢	CHANGELOG tracks protocol evolution
🔴	No published performance benchmarks, throughput, p95 latency, cold-start, memory footprint
🔴	No case studies / testimonials / production references
🔴	No roadmap (only retrospective CHANGELOG)
🔴	No maintainer SLA or support-tier statement
🔴	No `GOVERNANCE.md` (who decides, how QDPs advance)
🟡	`CODE_OF_CONDUCT.md` + `CONTRIBUTING.md` exist but are stubby
🔴	No issue/PR templates in `.github/`
🔴	No `SUPPORT.md`

Impact: A CTO evaluating Quidnug for a 2026 roadmap can’t answer “how fast is it?” or “how do I get help?” without asking by email.

4. Confidence in security

Status	Item
🟢	`SECURITY.md` with disclosure policy
🟢	HSM + WebAuthn signer abstractions
🔴	No threat model doc, attacker capabilities, adversary assumptions, known mitigations
🔴	No published security-audit report (and no audit has happened)
🔴	No SBOM (Software Bill of Materials) published with releases
🔴	No signed release artifacts (cosign / sigstore), ironic for a protocol that integrates with sigstore
🔴	No reproducible-build verification
🔴	No CVE disclosure process beyond the email in SECURITY.md
🔴	No cross-SDK signature-interop tests, a subtle bug in Swift’s canonical bytes could silently reject Go-signed txs
🔴	No fuzzing harness for canonical-bytes / merkle / DER parsing

Impact: Bank security teams, healthcare compliance, DoD suppliers will all ask “where’s the threat model and audit report?” and stall.

5. Fit to use case

The 77-slide overview deck markets 14 use-cases. Here’s the coverage:

Use case	Example exists?	Language(s)
FinTech: multi-party approval	🟡 Enterprise-onboarding example	Java only
FinTech: cross-border payment	🟢 ISO 20022 cross_border_payment	Go
FinTech: KYC-gated vendor	🟡 Partial (Java onboarding)	,
FinTech: escrow / custody	🔴 None	,
FinTech: decentralized credit	🔴 None	,
AI: agent identity	🔴 None	,
AI: training-data provenance	🟡 Sigstore recorder works generically	Go
AI: model / output attestation	🔴 None	,
AI: RAG with trust-weighted sources	🔴 None	,
Elections: voter registration	🔴 None	,
Elections: ballot recording	🔴 None	,
Elections: audit / tabulation	🔴 None	,
Elections: candidate identity	🔴 None	,
Elections: observer attestation	🔴 None	,
Healthcare: provider network trust	🟡 FHIR recorder exists	Go
Healthcare: patient record signing	🔴 None	,
Credentials: issuer chains	🔴 None	,
Credentials: W3C VC compatibility	🔴 None	,
Artifact signing: cosign / SBOM	🟢 Sigstore integration	Go
Artifact signing: C2PA media	🟢 C2PA integration	Go

Impact: A developer interested in “I want to use Quidnug for elections” finds zero code. They assume it’s not a real use case.

6. Debuggability

Status	Item
🟢	Structured error taxonomy across every SDK (Validation / Conflict / Unavailable / Node / Crypto)
🟢	Server returns `error.code` so clients can branch on specific failures
🔴	No “common errors” FAQ linking `NONCE_REPLAY`, `QUORUM_NOT_MET`, `FEATURE_NOT_ACTIVE` codes to likely fixes
🔴	Error messages don’t link to documentation (no `See: https://docs.quidnug.dev/errors#NONCE_REPLAY`)
🔴	No OpenTelemetry / tracing instrumentation in SDKs
🔴	No structured-log integration guide (Winston, zap, logrus, structlog)
🔴	No “how to enable verbose logging” in SDK READMEs
🔴	No request ID propagation hooks

Impact: When an integration fails in production, operators have to read source code to diagnose. Observability-first orgs (which is every Fortune 1000 in 2026) won’t tolerate that.

7. Production-readiness

Status	Item
🟢	Python SDK 42 tests, Java 20, .NET 24, Go 100%, Rust 17, JS 10, Swift 13 (pending execution)
🟢	Helm chart with StatefulSet + PVC + PDB + anti-affinity
🟢	Prometheus alerts + Grafana dashboard
🔴	Python SDK is sync-only. Modern Python apps are async; this blocks FastAPI / aiohttp / Sanic adoption.
🔴	No gRPC surface for the node (stays HTTP-only)
🔴	No migration guide v1 → v2, existing JS v1 users have no upgrade path doc
🔴	No versioning / deprecation policy
🔴	No load-test recipe (k6, Locust, wrk)
🔴	No chaos-engineering recipes (peer partition, guardian outage, gossip drop)
🔴	No capacity-planning guide (how many quids per node, how much storage per block)
🔴	No backup / restore procedure docs
🔴	No published SLOs / target availability

Impact: Platform teams can’t ship Quidnug to production without answering “how do I upgrade?”, “how do I back up?”, “what’s the throughput ceiling per node?“.

8. Ecosystem maturity

Status	Item
🟢	Apache-2.0, clean IP
🟢	Cross-language canonical-bytes spec
🔴	No OpenAPI 3.1 spec for the node API, every SDK hand-rolls its HTTP client
🔴	No Kafka / NATS / RabbitMQ / Redis Streams bridge (event stream → message bus)
🔴	No Zapier / Make / n8n / Retool connector
🔴	No Discord / Slack / Teams notification bot
🔴	No GitHub Action for CI-time trust queries (think branch protection = “only merge if author transitively trusts reviewer ≥ 0.7”)
🔴	No Homebrew formula / apt / dnf packages for `quidnug` or `quidnug-cli`
🔴	No VS Code / JetBrains extension (inline trust badges, transaction debugger)
🟡	Postman collection exists; no Bruno / Insomnia export
🔴	No GraphQL federation subgraph
🔴	No Terraform provider (only scaffold)
🔴	No AWS / GCP / Azure marketplace listings

Impact: Integrators must custom-build every pipe, every CI hook, every notification. That’s an open-ended integration tax.

Gap priority matrix

Tier 1, Blocks first-time users TODAY (Ship in this commit)

Gap	Why blocking	Fix
No OpenAPI spec	Every SDK hand-rolled; drift inevitable; no Swagger UI	Author `openapi.yaml` v3.1
No cross-SDK interop test	Silent canonical-bytes drift = signature rejection	Python signs ↔ Go / .NET / JS verify
No v1 → v2 migration guide	Existing JS v1 users have no upgrade path	`docs/migration/v1-to-v2.md`
No FAQ / troubleshooting	Common errors have no docs	`docs/faq.md`
Zero examples: elections, AI agents, credentials	Huge marketed use cases with no code	Runnable examples in Python/Go/JS

Tier 2, Blocks production deployments (Ship in this commit)

Gap	Why blocking	Fix
No async Python SDK	Modern Python apps are async-first	`AsyncQuidnugClient` via httpx
No OpenTelemetry	Observability-first orgs will reject	OTel middleware for Go client
No performance benchmarks	CTO evaluation can’t proceed	Runnable benchmark harness + numbers
No threat model	Security teams will stall on adoption	`docs/security/threat-model.md`

Tier 3, Slows organic adoption (Ship in this commit)

Gap	Why blocking	Fix
No comparison pages	”Quidnug vs DIDs” is the first question	`docs/comparison/vs-*.md`
No GitHub Action	No CI hook for trust gating	`.github/actions/quidnug-trust/`
No Kafka bridge	Event streams can’t reach existing pipelines	`integrations/kafka/`
No issue / PR templates	Friction for first contributors	`.github/ISSUE_TEMPLATE/`, `.github/PULL_REQUEST_TEMPLATE.md`

Tier 4, Long-term ecosystem maturity (Backlog)

Hosted public sandbox / testnet
Published packages on npm / PyPI / crates.io / Maven Central / NuGet
Homebrew formula
VS Code extension
Video tutorials
W3C Verifiable Credentials full compatibility layer
Third-party security audit
Interactive tutorial site (Tour of Quidnug)
Terraform provider (beyond scaffold)
Awesome-lists submissions
HN / Dev.to launch posts
AWS / GCP / Azure marketplace listings

What this audit changes

This document, plus the companion commits in the same PR, close every Tier 1 and Tier 2 gap. Tier 3 is partially addressed. Tier 4 is documented as a backlog with ownership unassigned.

Before: 7 SDKs + 5 integrations + deploy artifacts. After: 7 SDKs + 5 integrations + deploy artifacts + OpenAPI spec, async Python, interop tests, migration guide, FAQ, 3 new use-case examples, OTel integration, benchmarks, threat model, comparison docs, GitHub Action, Kafka bridge.

Tier 1-3 closure makes Quidnug demonstrably production-ready for the first time, with enough surrounding material for a platform team to commit to it in a 2026 planning cycle.

Recommendations

Immediate (next 30 days)

Publish the packages. Every README says npm install @quidnug/client / pip install quidnug / cargo add quidnug, today those 404.
Stand up a quidnug.dev docs site (mdBook / VitePress / Docusaurus) that collates the integration guide, FAQ, threat model, and per-SDK READMEs.
Deploy a public sandbox node so every quickstart works without local docker. One t3.small in us-east-1 covers it.

30–90 days

Third-party security audit (Trail of Bits / NCC / Kudelski).
Publish performance numbers on 3 standard configs (1-node, 3-node, 7-node consortium).
Submit to awesome-cryptography, awesome-decentralized, awesome-go, awesome-python.
Launch post on HN + Dev.to with the AI-agent-identity example as the hook.
Build the VS Code extension (inline trust badges on quid IDs in source).

90+ days

W3C Verifiable Credentials full compat layer (not just issuance).
Third-party integrations via Zapier/Make (non-engineer audience).
Managed-cloud Quidnug offering.
Mobile SDKs past scaffold (Swift + Android to full production parity including Keychain / StrongBox flows).

Footnotes on the audit process

This audit was conducted as a code + documentation walkthrough from the root README.md through every clients/*/README.md and integrations/*/README.md, cross-referenced against the 77-slide overview deck’s use-case enumeration. No external user research was conducted, the “adoption” judgments are informed estimates based on what modern platform / platform-engineering / developer-experience teams typically require before committing to a new dependency.

A follow-up audit driven by actual integration attempts (friendly teams trying to use Quidnug in their real apps) will find gaps this one missed. This document is intentionally an internal working artifact, not a marketing piece.

License

Apache-2.0.