0008. Protocol core domain model

Design document, published from the repository at docs/adr/0008-protocol-core-domain-model.md.

  • Status: Accepted
  • Date: 2026-11-13

Context

FEAT-02 introduces QuantLayer's domain engine: identity, credential, proof and key lifecycles, signing, serialization and verification. The engine must be framework-independent, deterministic where signatures are involved, and auditable.

Decision

  1. Functional core. Aggregates are immutable values; commands are pure functions returning { state, events }. Time and IDs come from an injected DomainContext. Persistence and event publication happen in the application layer, outside the domain.
  2. Declarative lifecycles. Every lifecycle is a validated defineStateMachine table. Transition validity is checked before business guards. Every (state, event) pair is covered by a test.
  3. Error taxonomy. ProtocolError(reason) extends QuantLayerError. Reasons are fine-grained and append-only, each mapped exhaustively to a coarse ErrorCode (added: UNAVAILABLE). Verification failures use the same reasons.
  4. Canonical encoding. QuantLayer canonical JSON = RFC 8785 (JCS) restricted to safe integers, plain objects and dense arrays, rejecting rather than dropping unrepresentable values. Timestamps are integer epoch milliseconds; bytes are strict base64url. Signature input is domain-separated: "QUANTLAYER-SIG-V1:" + purpose + "\n" + canonicalJSON.
  5. Credentials sign only immutable content. Status, revision and timestamps are excluded from the signed document; verifiers obtain status from a CredentialStatusResolver, never from the holder-supplied object.
  6. Versioned codecs. { type, version, payload } envelopes with Zod validation, migration chains for old versions, and self-validation on encode. Zod is used in domain packages for structural decoding of untrusted input; it is a validation library, not a framework.
  7. Ports. IdentityProvider, CredentialIssuer, CredentialVerifier, ProofProver, ProofVerifier, SignatureProvider, KeyManager, NetworkAdapter and EventPublisher are interfaces in the domain packages. Issuer and verifiers are provided as domain services composed only of ports.
  8. Layering amendment to ADR-0004. core is the protocol kernel and crypto now depends on it (for errors, state machines, bytes and time). pqc-engine may depend on core. privacy and evm use core errors.
  9. Algorithm identifiers are a fully specified, append-only registry in crypto. Selection remains an AlgorithmPolicy decision (ADR-0007 holds: still no cryptographic implementations).

Consequences

  • Domain logic is testable without mocks of frameworks; tests use @quantlayer-protocol/core/testing (manual clock, sequential IDs) and in-memory port fakes.
  • Wire formats and signing inputs are reproducible in other languages (Rust, Solidity tooling) from the written rules.
  • JSON parsing uses the platform parser, which accepts duplicate keys (last wins). This does not weaken signatures because verification re-canonicalizes the decoded value, but strict duplicate-key rejection may be added when untrusted documents are exchanged directly.
  • Changing a signed document's structure requires a new CREDENTIAL_DOCUMENT_SCHEMA version.