> For the complete documentation index, see [llms.txt](https://docs.optivalux.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.optivalux.com/technical/architecture-overview.md). # Architecture Overview This page describes the Optivalux system at component level for technical readers. It deliberately stops short of contract-by-contract internals. > **Current stage:** the protocol layer is implemented (Production V2) and tested on local development networks only. The verification service, relaying service, indexer and applications are designed but not yet in production. Nothing is deployed to a public network. See [Current Stage](/getting-started/current-stage.md). ## System context ``` Owner / verifier (phone browser) Brand operator / admin (brand portal) │ tap (authenticator) / QR (locator) │ ▼ ▼ Web / applications ─────────▶ API ◀───────── Brand applications │ │ Verification service ◀────┘ └────▶ Relaying service ──▶ EVM network (protocol) (secure hardware) │ events ▼ Database (projection) ◀──────────── Indexer ``` ## Components ### Physical product and authenticator A secure element in the product. Two families are supported (see [Physical Authentication](/trust/physical-authentication.md)): * **symmetric** tags produce a dynamic cryptographic message per tap, checkable only with a secret key; * **asymmetric** secure elements sign a fresh challenge with a private key that never leaves the chip. Each certificate records which scheme its authenticator uses and a hashed authenticator identifier. Raw hardware identifiers alongside secret material are never recorded. ### Web and application layer Phone-browser verification, owner applications and brand applications. The applications present the three status dimensions (ownership, certificate standing, authentication availability) and collect the owner's and recipient's signed authorizations. In normal owner use there is no crypto vocabulary and no recovery phrase. The account layer is implementation-agnostic: any account that can produce standard typed-data signatures verifiable on-chain (including contract accounts) can be used. ### Verification service (symmetric authenticators only) Checks symmetric tag messages using keys held only in secure hardware (HSM/KMS), enforces that each tag's counter only increases (rejecting replays), applies rate limits and anomaly rules, and issues a short-lived (at most 15 minutes), single-use, purpose-bound attestation that the protocol accepts. It is a **trust anchor** for the symmetric model. It is not involved in asymmetric verification. ### Claim service Checks purchase or activation eligibility **off-chain** and issues a brand-scoped claim authorization. Activation credentials are consumed off-chain and never reach the chain. ### API, relaying service and indexer * **API**: the backend boundary for the applications. * **Relaying service**: submits owner- and brand-signed requests to the network, so users do not interact directly with protocol transaction mechanics. Fee handling and relaying policy are part of the deployment and service design and are not yet a fixed public commercial commitment. It is **untrusted for authorization**: all authority comes from signatures, submission is permissionless, and the relaying service cannot alter signed content. * **Indexer**: reads protocol events and builds a fast, queryable **projection** in a database, recording block numbers and hashes, handling reorganisations and reconciling against chain state. ### EVM protocol A set of smart contracts on an EVM-compatible network. Responsibilities, at a high level: * **Certificate kernel**: the authoritative ledger of certificates. Stores owner, phase, standing, owner lock, authenticator binding, retired authenticators and the certificate's pinned software version. Enforces structural rules itself (for example, no change to a voided certificate, no owner change while suspended or locked). Its code is **immutable**; there are no proxies and no burn path. * **Brand registry**: brand namespaces, per-brand roles (operator, admin, security authority), batch records and caps, claim-authority keys and continuity authority. * **Controller versions**: the business logic for provisioning, claim, transfer, standing changes and recovery. Each certificate is **pinned** to one approved version; approving a new version grants it no authority over existing certificates. * **Version registry**: governance approval and freezes of controller versions. * **Trust registry**: which authenticator schemes and verification-service attesters are trusted, with bounded temporary suspension and governance-only permanent revocation. * **Possession verifiers**: one per authenticator family, behind a vendor-neutral interface. * **Safety components**: the fixed protected state used by Protection Mode (internally the escape harbor; see [Terminology](/technical/terminology.md)), the Protection Mode request module and recovery-related safety state. All core components are deployed together in a single atomic transaction and bound to each other at construction; a partial deployment can never become active. Deployment is checked against published, audited builds through a canonical manifest. This check is process-enforced, not fully on-chain. ## Authoritative ownership and state * **The chain is authoritative** for certificate ownership and state. * **Databases and indexers are projections.** They must be reconcilable against chain state and are never the source of truth for ownership. Ownership-critical decisions read the chain, or verify the projection's freshness first. * **No personal data on-chain.** On-chain metadata is limited to identifiers and hashes of non-personal data. Product and batch metadata live off-chain, with content hashes on-chain. * **Public verification never exposes owner identity or address** by default. ## Signatures and submission * Owners, recipients and brand roles authorize actions by signing **typed, domain-separated** messages bound to the network, the specific contract, the certificate and the operation. * Every signed authorization is **single-use** and **expires**. Each certificate has one authorization counter; any state change invalidates all outstanding authorizations for it. * Any ownership change also invalidates any outstanding Protection Mode or software-migration authorizations from the previous owner. ## Governance Protocol governance acts through a multi-signature account and a time delay. A separate guardian can apply temporary restrictions of at most 14 days. Neither can change ownership. Exact thresholds and delays are set before any public-network governance rehearsal and are not yet decided. See [Trust Model](/trust/trust-model.md). ## Further reading * [Lifecycle & Status](/technical/lifecycle-and-status.md) * [Network & Finality](/technical/network-and-finality.md) * [Terminology](/technical/terminology.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.optivalux.com/technical/architecture-overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.