- 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
- Functional core. Aggregates are immutable values; commands are pure
functions returning
{ state, events }. Time and IDs come from an injectedDomainContext. Persistence and event publication happen in the application layer, outside the domain. - Declarative lifecycles. Every lifecycle is a validated
defineStateMachinetable. Transition validity is checked before business guards. Every (state, event) pair is covered by a test. - Error taxonomy.
ProtocolError(reason)extendsQuantLayerError. Reasons are fine-grained and append-only, each mapped exhaustively to a coarseErrorCode(added:UNAVAILABLE). Verification failures use the same reasons. - 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. - 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. - 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. - Ports.
IdentityProvider,CredentialIssuer,CredentialVerifier,ProofProver,ProofVerifier,SignatureProvider,KeyManager,NetworkAdapterandEventPublisherare interfaces in the domain packages. Issuer and verifiers are provided as domain services composed only of ports. - Layering amendment to ADR-0004.
coreis the protocol kernel andcryptonow depends on it (for errors, state machines, bytes and time).pqc-enginemay depend oncore.privacyandevmusecoreerrors. - Algorithm identifiers are a fully specified, append-only registry in
crypto. Selection remains anAlgorithmPolicydecision (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_SCHEMAversion.