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.
2.8 KiB
annulus
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.
Model
A Profile is a small immutable value whose flags enumerate which
classical operations are forbidden. Refuse(ctx, op) reports whether
a given operation is admissible under the profile bound to ctx.
Profiles serialise to eight canonical bytes; Profile.Hash is the
SHA3-256 of that encoding. Consensus emits the hash into block
headers so any observer can determine which profile produced a block.
Policy and enforcement are decomplected. Each constrained operation
(an ECDSA precompile, a pairing precompile, a Groth16 verifier) calls
Refuse once at the top of 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.
Profiles
| Profile | Construction | Effect |
|---|---|---|
| Strict | annulus.Strict() |
Forbids every classical category. |
| Permissive | annulus.Permissive() |
Admits every operation. |
A profile that sets StrictPQ but omits any individual Forbid* flag
is ill-formed. Profile.Canonical rewrites such a profile into the
canonical Strict form; Profile.Valid reports whether a profile is
already in canonical form.
Categories
The Category type groups operations the same Forbid* flag governs:
| Category | Members |
|---|---|
CatECDSAContractAuth |
ECDSARecover, ECDSAVerify, Schnorr |
CatClassicalSig |
Ed25519, X25519 |
CatPairingPrecompile |
BN254Pairing, BLS12381Pair, BLSSignature |
CatKZGPrecompile |
KZGEval |
CatClassicalSNARK |
Groth16, Plonk, Marlin |
CatNonSHA3Hash |
SHA256, RIPEMD160, Blake2b, Blake2s, Keccak256 |
Use
import "github.com/luxfi/annulus"
// Bind the active profile once at startup.
ctx := annulus.WithProfile(context.Background(), annulus.ProfileFromEnv())
// Each constrained primitive calls Refuse at the top of its Run.
func (p *kzgPointEval) Run(ctx context.Context, in []byte) ([]byte, error) {
if err := annulus.Refuse(ctx, annulus.KZGEval); err != nil {
return nil, err
}
// ... evaluation
}
Environment
QUASAR_STRICT_PQ=1 selects Strict at startup via ProfileFromEnv.
Mainnet binaries set this in their entrypoint. Any other value
(including absent) selects Permissive.
Versioning
The canonical encoding is versioned. The current version is 1. Adding new fields uses the reserved tail; changing the meaning of an existing bit requires a version bump and a consensus-level upgrade.
Tests
go test ./... -count=1
The strict and permissive profile hashes are pinned in
profile_test.go. A change to either is a consensus-breaking change.