# Quidnug

> A decentralized protocol for relational trust, identity, ownership, and auditable state. Trust is personal, cryptographic, and contextual.

Quidnug answers three kinds of question from the observer's perspective: "how much should I trust this counterparty?", "did this key authorize this action, and can I recover if it's lost?", "has this asset passed through a chain I can verify?".

Canonical repo: https://github.com/bhmortim/quidnug

## Start here

- [Overview](https://quidnug.com/docs/): what Quidnug is and where to read.
- [Quick start](https://quidnug.com/docs/quick-start/): build, run, first API call.
- [First five API calls](https://quidnug.com/docs/first-five-calls/): identity → trust → query → event → rotation.
- [FAQ](https://quidnug.com/docs/faq/): canonical bytes, nonce replays, guardian setups.

## Concepts

- [Quids (identities)](https://quidnug.com/docs/concepts/quids/): The cryptographic identity primitive in Quidnug, an ECDSA P-256 public key plus metadata, addressed by the first 16 hex characters of sha256(publicKey).
- [Relational trust](https://quidnug.com/docs/concepts/trust/): Trust in Quidnug is always a signed statement from one observer to one target in one domain. There is no universal reputation score.
- [Domains](https://quidnug.com/docs/concepts/domains/): Hierarchical, dot-notation contexts that scope trust. A trust edge valid in one domain is not automatically valid in another.
- [Proof-of-Trust consensus](https://quidnug.com/docs/concepts/consensus/): Each node tiers incoming blocks based on its own trust in the validator. Different nodes can legitimately see different chains, and that is the point.
- [Transactions](https://quidnug.com/docs/concepts/transactions/): The seven core transaction types, trust, identity, title, event, anchor, guardian, fork-block, each signed, nonced, and anchored into blocks.
- [Event streams](https://quidnug.com/docs/concepts/events/): Append-only, monotonically-sequenced event logs bound to any quid or title. Payload inline up to 64 KB, or referenced via IPFS CID for larger data.
- [Key lifecycle](https://quidnug.com/docs/concepts/keys/): Rotation, invalidation, guardian recovery, and resignation, treating keys as first-class lifecycle objects instead of forever-secrets.

## Architecture

- [System overview](https://quidnug.com/docs/architecture/): six subsystems, HTTP API, P2P surface.
- [Rogue-node security](https://quidnug.com/docs/architecture/rogue-node-security/): hostile-peer model.

## Design proposals (QDPs)

- [QDP-0000: The QDP Process](https://quidnug.com/docs/design/0000-qdp-process/): Quidnug evolves through Quidnug Design Proposals (QDPs). Each QDP is a numbered markdown file in docs/design/ that specifies a change to the protocol, its wire formats, its ecosystem, or the process itself. This document defines what cou…
- [QDP-0001: Global Nonce Ledger](https://quidnug.com/docs/design/0001-global-nonce-ledger/): Today Quidnug's replay protection is a per-node, in-memory map of (truster, trustee) → last-seen nonce for trust transactions, with ad-hoc monotonic counters (UpdateNonce, Sequence) for identity and event transactions, and no counter at…
- [QDP-0002: Guardian-Based Recovery](https://quidnug.com/docs/design/0002-guardian-based-recovery/): [QDP-0001](0001-global-nonce-ledger.md) introduces single-signer anchors for key rotation and compromise recovery but explicitly leaves one hole open: the "anchor race." When an attacker holds a compromised key, they can publish an Ancho…
- [QDP-0003: Cross-Domain Nonce Scoping](https://quidnug.com/docs/design/0003-cross-domain-nonce-scoping/): [QDP-0001](0001-global-nonce-ledger.md) proposed a **global** per-signer nonce counter: one monotonic counter per (signer, keyEpoch), shared across all trust domains the signer operates in. That proposal flagged the choice as "simple but…
- [QDP-0004: Phase H Roadmap, Residual Protocol Work](https://quidnug.com/docs/design/0004-phase-h-roadmap/): QDP-0001 / -0002 / -0003 landed their foundations. Six items were deliberately deferred because each has enough surface area to warrant careful design, none fits cleanly as an incremental patch, and all are independent enough that parall…
- [QDP-0005: Push-Based Gossip for Anchors and Fingerprints (H1)](https://quidnug.com/docs/design/0005-push-based-gossip/): QDP-0003 shipped pull-based cross-domain gossip: peers query GET /api/v2/domain-fingerprints/{domain}/latest and operators submit anchors via POST /api/v2/anchor-gossip. This works for small, tight clusters but has two structural problems:
- [QDP-0006: Guardian-Consent Revocation (H6)](https://quidnug.com/docs/design/0006-guardian-resignation/): QDP-0002 §12.1 left guardian revocation unresolved: a guardian who has consented to be in subject S's set has no on-chain way to withdraw that consent later. Reasons range from the mundane (guardian stepped back from the role) to the urg…
- [QDP-0007: Lazy Epoch Propagation (H4)](https://quidnug.com/docs/design/0007-lazy-epoch-propagation/): QDP-0003 §15.4 identified a corner case: a signer who transacts in domain B only quarterly may have rotated their key in domain A months ago, and domain B's local ledger still records the old epoch because push-gossip (H1) either wasn't…
- [QDP-0008: Snapshot K-of-K Bootstrap Protocol (H3)](https://quidnug.com/docs/design/0008-kofk-bootstrap/): QDP-0001 §7 defined the on-wire NonceSnapshot format but left the consumer-side bootstrap protocol as a deferred item. A fresh node joining the network today has no authoritative way to seed its nonce ledger from a consistent snapshot,…
- [QDP-0009: Fork-Block Migration Trigger (H5)](https://quidnug.com/docs/design/0009-fork-block-trigger/): QDP-0001 §10 described a shadow → enforce rollout: configured flags like EnableNonceLedger are off by default; operators flip them per-node. For a production network, feature activation must be coordinated across all nodes at a specific…
- [QDP-0010: Compact Merkle Proofs (H2)](https://quidnug.com/docs/design/0010-compact-merkle-proofs/): Anchor gossip today (QDP-0003, H1) ships an entire origin block with every AnchorGossipMessage. The bandwidth and memory cost is acceptable because rotations are rare, but a block with 1000 transactions eats far more envelope than the si…
- [QDP-0011: Client Libraries & Integrations Roadmap](https://quidnug.com/docs/design/0011-client-libraries-and-integrations/): **Note on this document's role.** This was originally a pre-implementation research memo. The work it describes has since been executed. The memo is kept as-is for historical context; the §9 ship-status section below is the live view.
- [QDP-0012: Domain Governance](https://quidnug.com/docs/design/0012-domain-governance/): The public network grows by other operators choosing to trust our seed nodes for a domain. A node that publishes TRUST edges toward our seed validators is **establishing a cache replica**, a local mirror of the agreed chain for that dom…
- [QDP-0013: Network Federation Model](https://quidnug.com/docs/design/0013-network-federation/): The Quidnug protocol does not distinguish between "the public network" and "a private network." Every node speaks the same wire format, can register any domain, can run its own consortium (QDP-0012), and can peer with any other node. The…
- [QDP-0014: Node Discovery and Domain Sharding](https://quidnug.com/docs/design/0014-node-discovery-and-sharding/): At operator scale the current flat seed_nodes model breaks down. A single operator will eventually run tens of servers, each handling different domains with different roles (validator / cache replica / archive), possibly in different reg…
- [QDP-0015: Content Moderation & Takedowns](https://quidnug.com/docs/design/0015-content-moderation/): Quidnug is append-only by design, blocks are immutable, trust edges are permanent, events are signed cryptographic artifacts. This is good for auditability and bad for every real-world obligation a running operator faces:
- [QDP-0016: Abuse Prevention & Resource Limits](https://quidnug.com/docs/design/0016-abuse-prevention/): The current node enforces a single per-minute rate limit at the HTTP layer, applied by source IP. That's enough for a local dev node and a handful of test users; it is not enough for a public review network facing real traffic. A product…
- [QDP-0017: Data Subject Rights & Privacy](https://quidnug.com/docs/design/0017-data-subject-rights/): Privacy law obligates an operator to honor certain rights on behalf of users whose personal data the operator processes:
- [QDP-0018: Observability, Audit, and Tamper-Evident Operator Log](https://quidnug.com/docs/design/0018-observability-and-audit/): The protocol is auditable by design at the transaction level, every TRUST / IDENTITY / TITLE / EVENT / MODERATION_ACTION is signed and committed on-chain. But there's a second layer of activity that isn't in the transaction log:
- [QDP-0019: Reputation Decay & Time-Weighted Trust](https://quidnug.com/docs/design/0019-reputation-decay/): The current trust graph treats every edge equally regardless of age. A TRUST transaction published five years ago contributes identically to one published yesterday. That's cheap and simple but creates slow-growing problems:
- [QDP-0020: Protocol Versioning & Deprecation](https://quidnug.com/docs/design/0020-protocol-versioning/): Twenty QDPs in, the protocol has accumulated real surface area. Block format, transaction types, HTTP API, JSON-LD schemas, governance primitives, federation, discovery. Every addition has shipped on its own activation plan (fork-block a…
- [QDP-0021: Blind Signatures for Anonymous Ballot Issuance](https://quidnug.com/docs/design/0021-blind-signatures/): The elections use case (UseCases/elections/) needs a way for an authority to sign a ballot **without learning which voter the ballot was issued to**. The authority must verify eligibility (check the voter's VRQ, mark them as "issued a ba…
- [QDP-0022: Timed Trust & TTL Semantics](https://quidnug.com/docs/design/0022-timed-trust-and-ttl/): The TrustTransaction struct has carried a ValidUntil field (Unix seconds, optional, zero means "no expiry") since the protocol's first version. The field was serialized, signed, and accepted by every client SDK, but no layer of the refer…
- [QDP-0023: DNS-Anchored Identity Attestation](https://quidnug.com/docs/design/0023-dns-anchored-attestation/): Existing DNS has a large installed base, a well-known ownership model (registrar + registrant), and nearly universal client reach. It is also brittle in the ways catalogued in UseCases/dns-replacement/README.md: centralized roots, regist…
- [QDP-0024: Private Communications & Group-Keyed Encryption](https://quidnug.com/docs/design/0024-private-communications/): Quidnug events are public by default. Every transaction is stored on-chain, gossiped across validators, replicated to caches, and queryable by anyone with network access to the appropriate domain's data. This is correct for most use case…
- [QDP-0025: Quidnug Explorer](https://quidnug.com/docs/design/0025-quidnug-explorer/): A single-page application, served either from the node itself at /explorer or as a desktop wrapper, that lets a human or an AI agent connect to one or more Quidnug nodes and explore the network at three layers simultaneously: the **trans…
- [Quidnug Design Proposals](https://quidnug.com/docs/design/readme/): This directory holds the versioned decision records for the Quidnug protocol. Each numbered file specifies a change to the protocol, an ecosystem convention, or the process itself. The process is defined in [QDP-0000: The QDP Process](00…
- [QDP-NNNN: Short Title in Title Case](https://quidnug.com/docs/design/template/): Delete this blockquote before submitting. Copy this file to `NNNN-kebab-slug.md` using the next unused QDP number. See [QDP-0000](0000-qdp-process.md) for the lifecycle, status values, track taxonomy, and writing conventions. An unset me…

## API

- [REST reference](https://quidnug.com/docs/api/): endpoints grouped by resource.
- [Error codes](https://quidnug.com/docs/api/errors/): stable machine-readable codes.
- [OpenAPI 3.0](https://github.com/bhmortim/quidnug/blob/main/docs/openapi.yaml): authoritative spec.
- [Postman collection](https://github.com/bhmortim/quidnug/blob/main/docs/postman/quidnug.postman_collection.json)

## Operations

- [Integration guide](https://quidnug.com/docs/integration-guide/): side-by-side SDK examples.
- [Deployment patterns](https://quidnug.com/docs/deployment/): single-node, consortium, Kubernetes.
- [Observability](https://quidnug.com/docs/observability/): Prometheus, Grafana, alerts.
- [Security](https://quidnug.com/docs/security/): defense-in-depth summary.
- [Configuration](https://quidnug.com/docs/configuration/): env vars and YAML.

## Use cases

- [AI Agent Capability Authorization](https://quidnug.com/use-cases/ai-agent-authorization/) (AI): **AI · Agent safety · Time-locked grants · Emergency revocation**
- [AI Content Authenticity](https://quidnug.com/use-cases/ai-content-authenticity/) (AI): **AI · Media provenance · C2PA+ · Editing chain of custody**
- [AI Model Provenance and Supply Chain](https://quidnug.com/use-cases/ai-model-provenance/) (AI): **AI · Provenance · Audit trails · Copyright attestation**
- [B2B Invoice Financing](https://quidnug.com/use-cases/b2b-invoice-financing/) (FinTech): **FinTech · Supply chain · Multi-party validation**
- [Credential Verification Network](https://quidnug.com/use-cases/credential-verification-network/) (Cross-industry): **Cross-industry · Education · Licensing · Certifications**
- [Decentralized Credit & Reputation](https://quidnug.com/use-cases/decentralized-credit-reputation/) (Consumer rights): **FinTech · Consumer rights · Anti-social-credit · Data sovereignty**
- [DeFi Oracle Network](https://quidnug.com/use-cases/defi-oracle-network/) (FinTech): **FinTech · DeFi · Decentralized data feeds · Aggregation trust**
- [Developer Artifact Signing](https://quidnug.com/use-cases/developer-artifact-signing/) (Cross-industry): **Open source · Supply-chain security · GPG replacement**
- [DNS Replacement](https://quidnug.com/use-cases/dns-replacement/) (Cross-industry): **Cross-industry · Critical internet infrastructure · Anti-centralization**
- [Elections on Quidnug](https://quidnug.com/use-cases/elections/) (Government): **Government · Voting · Registration · Universal verifiability · Bring-your-own-identity**
- [Enterprise Domain Authority](https://quidnug.com/use-cases/enterprise-domain-authority/) (Cross-industry): **Infrastructure · Split-horizon · Private records · Federated-by-default**
- [Federated Learning Gradient Attestation](https://quidnug.com/use-cases/federated-learning-attestation/) (AI): **AI · Federated learning · Multi-party cryptographic attestation**
- [Healthcare Consent Management](https://quidnug.com/use-cases/healthcare-consent-management/) (Cross-industry): **Cross-industry · Patient-controlled access · Emergency override**
- [Institutional Crypto Custody](https://quidnug.com/use-cases/institutional-custody/) (FinTech): **FinTech · High-value · Full key lifecycle management**
- [Interbank Wire Authorization](https://quidnug.com/use-cases/interbank-wire-authorization/) (FinTech): **FinTech · High-value · M-of-N signing · Guardian recovery**
- [Merchant Fraud Consortium](https://quidnug.com/use-cases/merchant-fraud-consortium/) (FinTech): **FinTech · Cross-organization data sharing · Relational trust**
- [Trust-weighted reviews on Quidnug](https://quidnug.com/use-cases/trust-weighted-reviews/) (Cross-industry): A global, cross-site review substrate where every rating is weighted by **the observer's** trust graph, not by an average that treats every reviewer as identical. Reviewer identity is portable; reputation is per-vertical; sites and revie…

## SDKs

- [Android (Kotlin)](https://quidnug.com/sdks/android/) [full]: Kotlin-first Android wrapper over the [Java SDK](../java/), adding:
- [Astro reviews](https://quidnug.com/sdks/astro-reviews/) [full]: SSR-first Astro components for the Quidnug trust-weighted rating system. The SVG is rendered statically at build time so search engines, feed readers, and no-JS clients see the exact same visualization the browser shows, plus the custom…
- [Browser extension (MV3)](https://quidnug.com/sdks/browser-extension/) [full]: A Manifest V3 browser extension that:
- [C# / .NET](https://quidnug.com/sdks/dotnet/) [full]: Quidnug.Client, the official .NET client for [Quidnug](https://github.com/bhmortim/quidnug), a decentralized protocol for relational, per-observer trust. Covers the **full v2 protocol surface** (QDPs 0001–0010).
- [CLI](https://quidnug.com/sdks/cli/) [full]: Operator-facing command-line interface for Quidnug nodes.
- [Go](https://quidnug.com/sdks/go/) [full]: github.com/quidnug/quidnug/pkg/client, the official Go SDK for [Quidnug](https://github.com/bhmortim/quidnug), a decentralized protocol for relational, per-observer trust.
- [ISO 20022 bridge](https://quidnug.com/sdks/iso20022/) [full]: The working Go integration for ISO 20022 lives at [integrations/iso20022/](../../integrations/iso20022/).
- [Java / Kotlin](https://quidnug.com/sdks/java/) [full]: Java 17+ client SDK for [Quidnug](https://github.com/bhmortim/quidnug), a decentralized protocol for relational, per-observer trust.
- [JavaScript / TypeScript](https://quidnug.com/sdks/js/) [full]: @quidnug/client, the official JavaScript/TypeScript client for [Quidnug](https://github.com/bhmortim/quidnug), a decentralized protocol for relational, per-observer trust.
- [Python](https://quidnug.com/sdks/python/) [full]: The official Python client for [Quidnug](https://github.com/bhmortim/quidnug), a decentralized protocol for relational, per-observer trust.
- [React adapter](https://quidnug.com/sdks/react/) [full]: React hooks and components for Quidnug, declarative per-observer trust in your UI. Layered on top of [@quidnug/client](../js/) (JS SDK v2).
- [React reviews](https://quidnug.com/sdks/react-reviews/) [full]: React hooks + components for Quidnug trust-weighted reviews.
- [Reviews widget](https://quidnug.com/sdks/reviews-widget/) [full]: The simplest possible Quidnug reviews integration: a **single line of HTML** that works on any website, no JS build step required.
- [Rust](https://quidnug.com/sdks/rust/) [full]: quidnug, the official Rust crate for [Quidnug](https://github.com/bhmortim/quidnug), a decentralized protocol for relational, per-observer trust.
- [Shopify app](https://quidnug.com/sdks/shopify-app/) [full]: Shopify-native app scaffold for Quidnug trust-weighted reviews.
- [Swift](https://quidnug.com/sdks/swift/) [full]: iOS 15+ / macOS 12+ client SDK for [Quidnug](https://github.com/bhmortim/quidnug), a decentralized protocol for relational, per-observer trust. Covers the **full v2 protocol surface** (QDPs 0001–0010).
- [Vue reviews](https://quidnug.com/sdks/vue-reviews/) [full]: Vue 3 wrappers around Quidnug's trust-weighted review components. Thin adapter layer over @quidnug/web-components that lets you use <QnAurora>, <QnConstellation>, and <QnTrace> as first-class Vue components with props + events.
- [Web components](https://quidnug.com/sdks/web-components/) [full]: Drop-in web components for trust-weighted reviews. Works with any framework (or no framework), import once, use the tags anywhere in HTML.
- [WordPress plugin](https://quidnug.com/sdks/wordpress-plugin/) [full]: Drop-in trust-weighted reviews for WordPress and WooCommerce. Per- observer ratings, cross-site reviewer reputation, no proprietary database.

## Integrations

- [C2PA media provenance](https://quidnug.com/integrations/c2pa/) [shipped]: Record C2PA manifests (Content Provenance & Authenticity) in Quidnug event streams so per-observer trust applies to creator/editor chains.
- [Chainlink External Adapter](https://quidnug.com/integrations/chainlink/) [shipped]: Expose Quidnug relational-trust queries to on-chain smart contracts.
- [Elastic / OpenSearch](https://quidnug.com/integrations/elastic/) [planned]: Status: **SCAFFOLD.**
- [GraphQL gateway](https://quidnug.com/integrations/graphql/) [planned]: Status: **SCAFFOLD.**
- [gRPC gateway](https://quidnug.com/integrations/grpc/) [planned]: Status: **SCAFFOLD.** The Go reference node currently speaks HTTP/JSON only. This scaffold captures the planned gRPC surface so protobuf consumers (Envoy, Linkerd, grpc-gateway, Buf generators) have a stable target.
- [HL7 FHIR](https://quidnug.com/integrations/fhir/) [shipped]: integrations/fhir records FHIR R4/R5 resources as events on Quidnug titles so healthcare trust decisions (which provider's observations to accept, which claim chain is authoritative) become per-observer queries in the Quidnug graph.
- [ISO 20022 mapping](https://quidnug.com/integrations/iso20022/) [planned]: integrations/iso20022 maps ISO 20022 financial messages (pain, pacs, camt, admi) onto Quidnug event streams, making cross-bank trust, audit chains, and settlement-lifecycle queries first-class per-observer trust questions.
- [Kafka bridge](https://quidnug.com/integrations/kafka/) [planned]: Tails Quidnug event streams and republishes them to Apache Kafka topics so existing Kafka infrastructure (Spark, Flink, Kafka Streams, downstream microservices) can subscribe without speaking Quidnug's HTTP API.
- [Ledger Nano app](https://quidnug.com/integrations/ledger/) [planned]: Status: **SCAFFOLD, not yet on Ledger Live.**
- [MQTT bridge](https://quidnug.com/integrations/mqtt/) [planned]: Status: **SCAFFOLD.**
- [Postgres extension](https://quidnug.com/integrations/postgres/) [planned]: Status: **SCAFFOLD.**
- [quidnug-oidc, OIDC → Quidnug bridge service](https://quidnug.com/integrations/oidc/) [shipped]: Standalone HTTP service that binds OIDC identity-provider subjects to Quidnug quids. Use this to let users of an existing IdP (Okta, Auth0, Azure Entra ID, Keycloak, Google Workspace, Cognito, …) participate in the Quidnug trust graph wi…
- [schema-org](https://quidnug.com/integrations/schema-org/) [planned]: Two-way mapping between Quidnug REVIEW events (QRP-0001) and Schema.org Review / AggregateRating JSON-LD.
- [Sigstore / cosign](https://quidnug.com/integrations/sigstore/) [shipped]: github.com/quidnug/quidnug/integrations/sigstore mirrors cosign / sigstore artifact signatures into Quidnug event streams, turning supply-chain signatures into queries over the Quidnug trust graph.
- [stripe-connect](https://quidnug.com/integrations/stripe-connect/) [planned]: Design + implementation guide for plumbing Stripe Connect into the Quidnug reviews ecosystem. Enables professional- reviewer monetization (tips, paid subscriptions) and the brand-disclosure marketplace (brand pays reviewer for a sponsore…
- [Terraform provider](https://quidnug.com/integrations/terraform/) [planned]: Status: **SCAFFOLD, not yet on Terraform Registry.**
- [WebSocket push](https://quidnug.com/integrations/websocket/) [planned]: Status: **SCAFFOLD.**

## Public network

- [Overview](https://quidnug.com/docs/network/): how the public network is organized.
- [Peering protocol](https://quidnug.com/docs/network/peering-protocol/): signed-request format and review flow.
- [Rejection reasons](https://quidnug.com/docs/network/rejection-reasons/): standardized rejection enum.
- [Running a node](https://quidnug.com/docs/running-a-node/): operator guide for peering or solo running.
- [Live status](https://quidnug.com/network/): seed health, chain tip, peer count.
- [Join the network](https://quidnug.com/network/join/): step-by-step joiner flow.
- [Seeds manifest](https://quidnug.com/network/seeds.json): authoritative seed identities.
- [Metrics API](https://quidnug.com/api/network/network.json): cached JSON summary for dashboards.

## Notes for crawlers

- Every page has a raw Markdown alternate (append `.md` to the URL).
- Full concatenated context: https://quidnug.com/llms-full.txt
- Source of truth: the GitHub repo (Apache 2.0).