mirror of
https://github.com/luxfi/annulus.git
synced 2026-10-30 17:02:25 +00:00
zeekay
d2b5812200
Defines the policy that constrains which cryptographic operations a
Quasar node accepts. The package contains no cryptographic primitives.
Two values, one gate:
Profile immutable 8-byte canonical encoding; SHA3-256
hash is published in block headers.
Refuse(ctx, Op) reports whether op is admissible under the
profile bound to ctx.
Policy and enforcement are decomplected. Each constrained operation
(ECDSA precompile, pairing precompile, classical SNARK verifier)
calls Refuse once at its entry point and otherwise proceeds in its
own lane. The profile does not know how the operations compute; the
operations do not know how the profile is selected.
Presets:
Strict forbids every classical category — mainnet.
Permissive admits every operation — testnet, default for
unbound contexts.
Categories (Forbid* flags map 1:1):
CatECDSAContractAuth ECDSARecover, ECDSAVerify, Schnorr
CatClassicalSig Ed25519, X25519
CatPairingPrecompile BN254Pairing, BLS12381Pair, BLSSignature
CatKZGPrecompile KZGEval
CatClassicalSNARK Groth16, Plonk, Marlin
CatNonSHA3Hash SHA256, RIPEMD160, Blake2b, Blake2s, Keccak256
Strict profile hash (pinned in profile_test.go):
9d70a692103d09414ffb2577ca53852c99b2d13b987c49f20852899f9a0be348
Permissive profile hash:
cf7b7f49edcad4722838277dd310dcf6a61d0552ce0f2116ad39c3dcd23bd916
A change to either hash is a consensus-breaking change and requires a
canonical-encoding version bump.
Environment override: QUASAR_STRICT_PQ=1 selects Strict via
ProfileFromEnv. Mainnet binaries set it in their entrypoint.
31 unit tests; vet-clean.
39 lines
1.9 KiB
Go
39 lines
1.9 KiB
Go
// Package annulus defines the strict post-quantum profile that
|
|
// constrains which cryptographic operations a Quasar node accepts.
|
|
//
|
|
// The package contains no cryptographic primitives. It expresses a
|
|
// policy: a [Profile] value enumerates which classical operations
|
|
// are forbidden, and [Refuse] reports whether a given [Op] is
|
|
// admissible under the profile currently bound to a [context.Context].
|
|
//
|
|
// Policy and enforcement are decomplected. Each implementation of a
|
|
// constrained operation (an ECDSA precompile, a pairing precompile, a
|
|
// classical SNARK verifier) calls [Refuse] once at the top of its
|
|
// entry point and otherwise proceeds independently. The profile does
|
|
// not know how those operations compute; the operations do not know
|
|
// how the profile selects them.
|
|
//
|
|
// Profile values are immutable. Two helpers construct the canonical
|
|
// preset profiles:
|
|
//
|
|
// - [Strict] enforces the strict-PQ boundary: forbids classical
|
|
// asymmetric primitives (ECDSA, X25519, Ed25519),
|
|
// pairing-based curves, KZG point evaluation,
|
|
// classical SNARKs, and non-SHA3 hash functions.
|
|
// - [Permissive] permits all operations; the default for unbound
|
|
// contexts and for testnets that admit legacy
|
|
// contracts.
|
|
//
|
|
// A profile's [Profile.Hash] is the SHA3-256 of its canonical byte
|
|
// encoding. Consensus emits this hash into block headers so any
|
|
// observer can verify which profile a block was produced under.
|
|
//
|
|
// The active profile is bound to a context via [WithProfile] and
|
|
// retrieved via [FromContext]. Tests and isolated subsystems may
|
|
// pass an explicit profile to [Refuse] without involving a context.
|
|
//
|
|
// Environment override: when QUASAR_STRICT_PQ is set to a truthy
|
|
// value, [ProfileFromEnv] returns [Strict]; otherwise it returns
|
|
// [Permissive]. Mainnet binaries set this in their startup path.
|
|
package annulus
|