ADR-002: BIP-322 Signature Format for Override Workflow¶

Status¶

Accepted | 2025-12-27 (Implemented)

Context¶

The AEGIS override workflow currently uses Ed25519 signatures for dual-key authorization. While Ed25519 provides strong cryptographic security (128-bit), the Guardrails specification (§6) explicitly requires BIP-322 format for Bitcoin ecosystem compatibility.

Current State¶

src/workflows/override.py:
- DualSignatureValidator uses Ed25519 via `cryptography` library
- Signatures are 64 bytes, keys are 32 bytes
- Message hash: SHA-256 of JSON-canonical proposal data
- Claims "BIP-322 compatible format" but is NOT actually BIP-322

Problem Statement¶

1. Specification Mismatch: Spec requires BIP-322, implementation uses Ed25519
2. Ecosystem Incompatibility: Ed25519 signatures cannot be verified by Bitcoin tooling
3. Post-Quantum Blocking: GAP-Q1 hybrid signatures need proper BIP-322 base layer
4. Audit Concerns: External auditors expect Bitcoin-native cryptography

Decision¶

Implement BIP-322 Simple format using BIP-340 Schnorr signatures on secp256k1.

Chosen Approach: Provider-Based Architecture¶

┌─────────────────────────────────────────────┐
│           SignatureProvider (Protocol)       │
├─────────────────────────────────────────────┤
│  + algorithm_name: str                       │
│  + generate_keypair() -> (priv, pub)         │
│  + sign(msg_hash, priv_key) -> signature     │
│  + verify(sig, msg_hash, pub_key) -> bool    │
└─────────────────────────────────────────────┘
           △                    △
           │                    │
┌──────────┴──────────┐ ┌──────┴──────────────┐
│  Ed25519Provider    │ │   BIP322Provider    │
│  (deprecated)       │ │   (recommended)     │
└─────────────────────┘ └─────────────────────┘

Key Technical Decisions¶

Alternatives Considered¶

Alternative 1: Keep Ed25519¶

Pros: - No code changes - Fast verification - Well-tested implementation

Cons: - Violates specification - Not Bitcoin-compatible - Blocks GAP-Q1 hybrid approach - Audit concerns

Decision: Rejected - specification compliance required

Alternative 2: BIP-322 Full Format¶

Pros: - Complete transaction serialization - Supports timelocks and complex scripts - Maximum compatibility

Cons: - Significantly more complex - Larger signature size - Overkill for single-sig override - More dependencies needed

Decision: Rejected - Simple format sufficient for dual-key override

Alternative 3: Raw BIP-340 Schnorr (no BIP-322 wrapper)¶

Pros: - Simpler implementation - Smaller signature size - Direct secp256k1 usage

Cons: - Loses message signing standard - No interoperability with Bitcoin wallets - Requires custom verification tooling

Decision: Rejected - BIP-322 provides standardized message format

Alternative 4: secp256k1-py + Custom Implementation¶

Pros: - Low-level control - Minimal dependencies - Maximum performance

Cons: - No BIP-340 implementation included - Requires implementing tagged hash, signing, verification - Higher maintenance burden

Decision: Rejected - btclib provides complete BIP-340 implementation

Consequences¶

Positive¶

1. Specification Compliance: Matches Guardrails §6 requirements
2. Bitcoin Ecosystem: Signatures verifiable with Bitcoin tooling
3. Post-Quantum Ready: Clean base layer for GAP-Q1 hybrid
4. Audit Friendly: Industry-standard cryptography
5. Future Proof: BIP-322 is actively developed, draft status

Negative¶

1. New Dependency: btclib adds ~2MB to package size
2. Migration Effort: Existing signatures become invalid
3. Slight Performance Hit: Schnorr ~30% slower than Ed25519
4. Learning Curve: Team needs BIP-340/322 knowledge

Neutral¶

1. Key Management: Same 32-byte keys, different curve
2. Signature Size: Same 64 bytes
3. API Surface: Minimal changes to OverrideWorkflow

Implementation¶

See GAP-M4 EPCC Plan for detailed implementation strategy.

Migration Path¶

v1.2.0: Add BIP322Provider, default to Ed25519 with deprecation warning
v1.3.0: Default to BIP322Provider, Ed25519 available via config
v2.0.0: Remove Ed25519Provider

Rollback Strategy¶

Provider abstraction allows instant rollback:

# schema/interface-contract.yaml
signature_provider: ed25519  # Rollback configuration

References¶

• BIP-322: Generic Signed Message Format
• BIP-340: Schnorr Signatures for secp256k1
• btclib Documentation
• Guardrails Specification §6
• GAP-M4 in Gap Analysis

Decision Record¶