quip-signer 0.2.2__tar.gz

quip_signer-0.2.2/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: quip-signer
+Version: 0.2.2
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3 :: Only
+Summary: Quip hybrid (sr25519 + ML-DSA-44) transaction signer
+Home-Page: https://www.quip.network/
+License: MIT-0
+Requires-Python: >=3.9

quip_signer-0.2.2/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["maturin>=1.7,<2"]
+build-backend = "maturin"
+
+[project]
+name = "quip-signer"
+description = "Quip hybrid (sr25519 + ML-DSA-44) transaction signer"
+requires-python = ">=3.9"
+license = { text = "MIT-0" }
+classifiers = [
+    "Programming Language :: Rust",
+    "Programming Language :: Python :: 3 :: Only",
+]
+# Single-sourced from Cargo.toml's `[package] version` (maturin reads it when
+# `version` is dynamic), so a release bumps the version in exactly one place.
+dynamic = ["version"]
+
+[tool.maturin]
+# Mixed layout: the Rust extension `_quip_signer` is dropped into the
+# `quip_signer` Python package under `python/`, which re-exports it and ships
+# type stubs. That dir also serves as the submodule/PYTHONPATH staging location
+# (`maturin develop` drops the built `.so` there).
+#
+# `python-source` MUST stay inside the crate tree. `maturin build` only packs a
+# python-source that lives under the manifest dir; an out-of-tree path (e.g.
+# `../../py/...`) is honored by `maturin develop`/`sdist` but silently dropped
+# from the built wheel, shipping the `.so` with no `__init__.py` (QUI-792). The
+# wheel-content guard in scripts/python-dists.sh fails the build if it regresses.
+module-name = "quip_signer._quip_signer"
+manifest-path = "transaction-crypto-py/Cargo.toml"
+python-source = "python"

quip_signer-0.2.2/python/quip_signer/__init__.py

@@ -0,0 +1,26 @@
+"""Quip hybrid (sr25519 + ML-DSA-44) transaction signer.
+
+Thin Python surface over the Rust `_quip_signer` extension, which wraps the
+same `sp`-free core the browser WASM signer is built from. All bytes in / bytes
+out; invalid input raises :class:`QuipSignerError`.
+"""
+
+from ._quip_signer import (
+    HybridSigner,
+    QuipSignerError,
+    account_id_from_public,
+    public_from_seed,
+    seed_from_mnemonic,
+    sign_payload_from_seed,
+    verify_envelope,
+)
+
+__all__ = [
+    "HybridSigner",
+    "QuipSignerError",
+    "account_id_from_public",
+    "public_from_seed",
+    "seed_from_mnemonic",
+    "sign_payload_from_seed",
+    "verify_envelope",
+]

quip_signer-0.2.2/python/quip_signer/__init__.pyi

@@ -0,0 +1,28 @@
+class QuipSignerError(Exception):
+    """Raised when the Quip hybrid signer rejects its input."""
+
+def public_from_seed(seed: bytes) -> bytes:
+    """Derive serialized H3 public bytes (1344B) from a 32-byte master seed."""
+
+def account_id_from_public(public: bytes) -> bytes:
+    """Derive the compact 32-byte Quip account id from H3 public bytes."""
+
+def seed_from_mnemonic(secret_uri: str) -> bytes:
+    """Derive the 32-byte master seed from a BIP39 phrase or `0x`-hex seed URI."""
+
+def sign_payload_from_seed(seed: bytes, payload: bytes) -> bytes:
+    """Sign payload bytes with a 32-byte seed; return the SCALE-encoded envelope."""
+
+def verify_envelope(payload: bytes, envelope: bytes, account_id: bytes) -> bool:
+    """Verify a SCALE-encoded envelope against a payload and compact account id."""
+
+class HybridSigner:
+    @staticmethod
+    def from_seed(seed: bytes) -> HybridSigner: ...
+    @staticmethod
+    def from_mnemonic(secret_uri: str) -> HybridSigner: ...
+    @property
+    def public_key(self) -> bytes: ...
+    @property
+    def account_id(self) -> bytes: ...
+    def sign(self, payload: bytes) -> bytes: ...

quip_signer-0.2.2/transaction-crypto-core/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "quip-transaction-crypto-core"
+version = "0.1.0"
+license = "MIT-0"
+authors = ["Quip Network <roman@postquant.xyz>"]
+homepage = "https://www.quip.network/"
+repository = "https://gitlab.com/piqued/quip-protocol-rs.git"
+edition = "2021"
+
+[dependencies]
+quip-crypto-primitives-core = { git = "https://github.com/QuipNetwork/polkadot-sdk.git", branch = "v0.2", default-features = false }
+bip39 = { version = "^2.2", default-features = false }
+blake2 = { version = "^0.10", default-features = false }
+codec = { version = "^3.7.5", default-features = false, features = ["derive"], package = "parity-scale-codec" }
+substrate-bip39 = { version = "^0.6.1", default-features = false }
+zeroize = { version = "^1", default-features = false, features = ["derive"] }
+
+[features]
+default = ["std"]
+std = [
+    "quip-crypto-primitives-core/std",
+    "blake2/std",
+    "codec/std",
+    "substrate-bip39/std",
+    "zeroize/std",
+]

quip_signer-0.2.2/transaction-crypto-core/src/lib.rs

@@ -0,0 +1,424 @@
+#![cfg_attr(not(feature = "std"), no_std)]
+
+//! Pure transaction/account identity helpers for Quip's hybrid signer.
+//!
+//! This crate is intentionally bytes-oriented:
+//! - it derives compact 32-byte account ids from hybrid public bytes
+//! - it signs raw payload bytes with the H3 suite
+//! - it encodes/decodes the runtime signature envelope as raw bytes
+//!
+//! The H3 suite itself (the `sr25519 + ML-DSA-44` keygen / sign / verify logic,
+//! message framing, and seed derivation) is **not** reimplemented here. It is
+//! the shared, `sp`-free [`Sr25519MlDsa44`] engine from
+//! `quip-crypto-primitives-core`, which the runtime is also built from — so the
+//! browser signer and the runtime verifier are byte-identical by construction.
+//!
+//! What stays quip-specific and lives here: account-id derivation
+//! (`quip-account-v1`), the SCALE transaction-signature envelope, and the
+//! BIP39 / secret-URI → master-seed helpers. None of those exist in the shared
+//! crate.
+//!
+//! It does not depend on runtime traits, `sp_core`, or `sp_io`.
+
+extern crate alloc;
+
+use alloc::vec::Vec;
+
+use bip39::{Language, Mnemonic};
+use blake2::digest::{Update, VariableOutput};
+use blake2::Blake2bVar;
+use codec::{Decode, DecodeWithMemTracking, Encode};
+use quip_crypto_primitives_core::suite::sr25519_mldsa44::{
+    Sr25519MlDsa44, HYBRID_PK_LEN, HYBRID_SIG_LEN, HYBRID_SK_LEN,
+};
+use quip_crypto_primitives_core::{HybridSignatureError, HybridSignatureScheme};
+use zeroize::Zeroize;
+
+const MASTER_SEED_LEN: usize = 32;
+
+/// Serialized H3 public-key length in bytes.
+pub const HYBRID_PUBLIC_LEN: usize = HYBRID_PK_LEN;
+/// Serialized H3 signature length in bytes.
+pub const HYBRID_SIGNATURE_LEN: usize = HYBRID_SIG_LEN;
+/// Serialized H3 secret-key length in bytes.
+pub const HYBRID_SECRET_LEN: usize = HYBRID_SK_LEN;
+/// Fixed length of derived Quip account ids.
+pub const ACCOUNT_ID_LEN: usize = 32;
+
+/// Domain separator for account-id derivation from the hybrid public key.
+pub const ACCOUNT_ID_DOMAIN: &[u8] = b"quip-account-v1";
+
+/// Error returned by byte-level hybrid transaction crypto helpers.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum HybridTxCryptoError {
+    InvalidLength {
+        expected: usize,
+        actual: usize,
+    },
+    InvalidPublicKey,
+    InvalidSecretKey,
+    InvalidSeed,
+    SigningFailed,
+    /// The BIP39 phrase was not a valid English mnemonic.
+    InvalidMnemonic,
+    /// The secret URI contained `/`-prefixed derivation junctions, which the
+    /// browser signer intentionally does not support.
+    UnsupportedDerivationPath,
+}
+
+pub type HybridResult<T> = core::result::Result<T, HybridTxCryptoError>;
+
+/// Maps the shared suite's error type onto this crate's public error type, so
+/// the boundary error surface is preserved across the dependency swap.
+fn map_suite_error(error: HybridSignatureError) -> HybridTxCryptoError {
+    match error {
+        HybridSignatureError::InvalidLength { expected, actual } => {
+            HybridTxCryptoError::InvalidLength { expected, actual }
+        }
+        HybridSignatureError::InvalidSeedLength { expected, actual } => {
+            HybridTxCryptoError::InvalidLength { expected, actual }
+        }
+        HybridSignatureError::InvalidPublicKey => HybridTxCryptoError::InvalidPublicKey,
+        HybridSignatureError::InvalidSecretKey => HybridTxCryptoError::InvalidSecretKey,
+    }
+}
+
+/// Bytes-level transaction signature envelope.
+#[derive(Clone, Debug, Eq, PartialEq, Hash, Encode, Decode, DecodeWithMemTracking)]
+pub struct HybridTxSignatureBytes {
+    pub public: [u8; HYBRID_PUBLIC_LEN],
+    pub signature: [u8; HYBRID_SIGNATURE_LEN],
+}
+
+impl HybridTxSignatureBytes {
+    /// Creates a bytes-level envelope after validating the input lengths and encodings.
+    pub fn new(public: &[u8], signature: &[u8]) -> HybridResult<Self> {
+        let public_key = Sr25519MlDsa44::public_key_from_bytes(public).map_err(map_suite_error)?;
+        let signature_value =
+            Sr25519MlDsa44::signature_from_bytes(signature).map_err(map_suite_error)?;
+
+        Ok(Self {
+            public: public_key.to_bytes(),
+            signature: signature_value.to_bytes(),
+        })
+    }
+
+    /// Returns the derived compact account id for the embedded public key.
+    pub fn derived_account_id(&self) -> [u8; ACCOUNT_ID_LEN] {
+        account_id_from_public_bytes(&self.public)
+    }
+
+    /// Verifies the embedded signature against the provided raw message bytes.
+    pub fn verify(&self, message: &[u8]) -> bool {
+        let Ok(public) = Sr25519MlDsa44::public_key_from_bytes(&self.public) else {
+            return false;
+        };
+        let Ok(signature) = Sr25519MlDsa44::signature_from_bytes(&self.signature) else {
+            return false;
+        };
+        Sr25519MlDsa44::verify(&public, message, b"", &signature)
+    }
+
+    /// SCALE-encodes the bytes-level envelope.
+    pub fn encode_envelope(&self) -> Vec<u8> {
+        self.encode()
+    }
+
+    /// Decodes a SCALE-encoded bytes-level envelope.
+    pub fn decode_envelope(bytes: &[u8]) -> HybridResult<Self> {
+        let decoded =
+            Self::decode(&mut &bytes[..]).map_err(|_| HybridTxCryptoError::InvalidLength {
+                expected: HYBRID_PUBLIC_LEN + HYBRID_SIGNATURE_LEN,
+                actual: bytes.len(),
+            })?;
+        Self::new(&decoded.public, &decoded.signature)
+    }
+}
+
+/// Derives the compact Quip account id from serialized H3 public bytes.
+pub fn account_id_from_public_bytes(public: &[u8]) -> [u8; ACCOUNT_ID_LEN] {
+    let mut hasher = Blake2bVar::new(ACCOUNT_ID_LEN).expect("32-byte Blake2 output is valid");
+    hasher.update(ACCOUNT_ID_DOMAIN);
+    hasher.update(public);
+
+    let mut out = [0u8; ACCOUNT_ID_LEN];
+    hasher
+        .finalize_variable(&mut out)
+        .expect("output length matches buffer");
+    out
+}
+
+/// Derives serialized H3 public bytes from a 32-byte H3 master seed.
+pub fn public_key_from_seed(seed: &[u8]) -> HybridResult<[u8; HYBRID_PUBLIC_LEN]> {
+    let (_secret, public) = Sr25519MlDsa44::from_seed_slice(seed).map_err(map_suite_error)?;
+    Ok(public.to_bytes())
+}
+
+/// Derives the 32-byte H3 master seed from a limited secret URI.
+///
+/// This mirrors the supported subset of substrate's `Pair::from_string`:
+///
+/// - a `0x`-prefixed 64-digit hex string is used directly as the master seed;
+/// - otherwise the input is an English BIP39 phrase, optionally followed by
+///   `///<password>`.
+///
+/// Derivation junctions (`//hard`, `/soft`) and the leading-`/` dev-phrase
+/// shortcut are intentionally **not** supported: a `/` outside the `///`
+/// password separator is rejected rather than silently ignored, so an imported
+/// account can never derive to an address the runtime would not recognize.
+pub fn master_seed_from_secret_uri(uri: &str) -> HybridResult<[u8; MASTER_SEED_LEN]> {
+    let (phrase, password) = match uri.split_once("///") {
+        Some((phrase, password)) => (phrase, Some(password)),
+        None => (uri, None),
+    };
+    let phrase = phrase.trim();
+
+    if let Some(hex) = phrase
+        .strip_prefix("0x")
+        .or_else(|| phrase.strip_prefix("0X"))
+    {
+        return decode_seed_hex(hex);
+    }
+
+    if phrase.contains('/') {
+        return Err(HybridTxCryptoError::UnsupportedDerivationPath);
+    }
+
+    master_seed_from_mnemonic(phrase, password)
+}
+
+/// Derives the 32-byte H3 master seed from an English BIP39 phrase.
+///
+/// This matches substrate's `Pair::from_phrase`: the mnemonic entropy is run
+/// through `substrate_bip39::seed_from_entropy` (PBKDF2-HMAC-SHA512, salt
+/// `"mnemonic" || password`, 2048 rounds) and the first 32 bytes of the 64-byte
+/// output are taken as the master seed.
+pub fn master_seed_from_mnemonic(
+    phrase: &str,
+    password: Option<&str>,
+) -> HybridResult<[u8; MASTER_SEED_LEN]> {
+    // `parse_in_normalized` expects already-NFKD input and, unlike `parse_in`,
+    // does not pull in `unicode-normalization`. English BIP39 words are
+    // lowercase ASCII (always NFKD) and NFKD never changes case, so this yields
+    // the same entropy as substrate's `parse_in` for every valid English
+    // mnemonic.
+    let mnemonic = Mnemonic::parse_in_normalized(Language::English, phrase)
+        .map_err(|_| HybridTxCryptoError::InvalidMnemonic)?;
+    let (entropy, entropy_len) = mnemonic.to_entropy_array();
+
+    let mut big_seed =
+        substrate_bip39::seed_from_entropy(&entropy[..entropy_len], password.unwrap_or(""))
+            .map_err(|_| HybridTxCryptoError::InvalidMnemonic)?;
+
+    let mut seed = [0u8; MASTER_SEED_LEN];
+    seed.copy_from_slice(&big_seed[..MASTER_SEED_LEN]);
+    big_seed.zeroize();
+
+    Ok(seed)
+}
+
+/// Decodes a 64-digit hex string into a 32-byte master seed.
+fn decode_seed_hex(hex: &str) -> HybridResult<[u8; MASTER_SEED_LEN]> {
+    if hex.len() != MASTER_SEED_LEN * 2 {
+        return Err(HybridTxCryptoError::InvalidSeed);
+    }
+
+    let mut seed = [0u8; MASTER_SEED_LEN];
+    for (index, byte) in seed.iter_mut().enumerate() {
+        let hi = hex_digit(hex.as_bytes()[index * 2])?;
+        let lo = hex_digit(hex.as_bytes()[index * 2 + 1])?;
+        *byte = (hi << 4) | lo;
+    }
+
+    Ok(seed)
+}
+
+fn hex_digit(ch: u8) -> HybridResult<u8> {
+    match ch {
+        b'0'..=b'9' => Ok(ch - b'0'),
+        b'a'..=b'f' => Ok(ch - b'a' + 10),
+        b'A'..=b'F' => Ok(ch - b'A' + 10),
+        _ => Err(HybridTxCryptoError::InvalidSeed),
+    }
+}
+
+/// Signs raw payload bytes with a 32-byte H3 master seed and returns the bytes-level envelope.
+///
+/// # Payload contract
+///
+/// `payload` is signed **exactly as given** — this function performs no hashing
+/// and no length check. Two caller obligations follow:
+///
+/// - **H3 domain prefix is intrinsic; do NOT pre-apply it.** The H3 scheme
+///   (`Sr25519MlDsa44`) frames every message internally as
+///   `0x01 ‖ "hybrid-sr25519-mldsa44-v1\0" ‖ len(ctx) ‖ ctx ‖ msg` before
+///   hashing/signing. Browser, runtime, and Python all go through the same
+///   core, so they agree byte-for-byte. Callers pass the unframed payload;
+///   pre-applying the prefix yourself would double-frame and the runtime would
+///   reject the signature.
+/// - **The Substrate >256-byte rule is the caller's job.** Substrate signs
+///   `SignedPayload::using_encoded`, which substitutes `blake2_256(payload)`
+///   for the raw bytes whenever the SCALE-encoded payload exceeds 256 bytes.
+///   That is an extrinsic convention, not part of H3, so this function does not
+///   apply it. A caller that hands a >256-byte extrinsic payload here verbatim
+///   gets a signature the runtime silently rejects. Hash first, then sign the
+///   32-byte digest.
+pub fn sign_payload_from_seed(seed: &[u8], payload: &[u8]) -> HybridResult<HybridTxSignatureBytes> {
+    let (secret, public) = Sr25519MlDsa44::from_seed_slice(seed).map_err(map_suite_error)?;
+    let signature = Sr25519MlDsa44::sign_deterministic(&secret, payload, b"", b"");
+
+    HybridTxSignatureBytes::new(public.as_ref(), signature.as_ref())
+}
+
+/// Signs raw payload bytes with expanded H3 secret bytes and matching public bytes.
+///
+/// The payload contract is identical to [`sign_payload_from_seed`]: the bytes
+/// are signed verbatim (no hashing, no length check), the H3 domain prefix is
+/// applied intrinsically by the scheme, and applying Substrate's >256-byte
+/// `blake2_256` rule is the caller's responsibility.
+pub fn sign_payload_from_secret(
+    secret: &[u8],
+    public: &[u8],
+    payload: &[u8],
+) -> HybridResult<HybridTxSignatureBytes> {
+    let secret_key = Sr25519MlDsa44::secret_key_from_bytes(secret).map_err(map_suite_error)?;
+    let signature = Sr25519MlDsa44::sign_deterministic(&secret_key, payload, b"", b"");
+
+    HybridTxSignatureBytes::new(public, signature.as_ref())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn account_id_domain_is_pinned() {
+        assert_eq!(ACCOUNT_ID_DOMAIN, b"quip-account-v1");
+    }
+
+    #[test]
+    fn same_public_key_derives_same_account_id() {
+        let public = public_key_from_seed(&[1u8; 32]).unwrap();
+        let first = account_id_from_public_bytes(public.as_ref());
+        let second = account_id_from_public_bytes(public.as_ref());
+
+        assert_eq!(first, second);
+    }
+
+    #[test]
+    fn different_public_keys_derive_different_account_ids() {
+        let alice = public_key_from_seed(&[1u8; 32]).unwrap();
+        let bob = public_key_from_seed(&[2u8; 32]).unwrap();
+
+        assert_ne!(
+            account_id_from_public_bytes(alice.as_ref()),
+            account_id_from_public_bytes(bob.as_ref())
+        );
+    }
+
+    #[test]
+    fn sign_and_verify_roundtrip() {
+        let envelope = sign_payload_from_seed(&[7u8; 32], b"quip-message").unwrap();
+        assert!(envelope.verify(b"quip-message"));
+        assert!(!envelope.verify(b"wrong-message"));
+    }
+
+    #[test]
+    fn public_key_from_seed_matches_signed_envelope_public() {
+        let public = public_key_from_seed(&[7u8; 32]).unwrap();
+        let envelope = sign_payload_from_seed(&[7u8; 32], b"quip-message").unwrap();
+
+        assert_eq!(public, envelope.public);
+    }
+
+    #[test]
+    fn envelope_round_trips_through_scale() {
+        let envelope = sign_payload_from_seed(&[9u8; 32], b"quip-message").unwrap();
+        let encoded = envelope.encode_envelope();
+        let decoded = HybridTxSignatureBytes::decode_envelope(&encoded).unwrap();
+
+        assert_eq!(decoded, envelope);
+        assert!(decoded.verify(b"quip-message"));
+    }
+
+    #[test]
+    fn envelope_decode_rejects_empty_bytes() {
+        assert!(HybridTxSignatureBytes::decode_envelope(&[]).is_err());
+    }
+
+    #[test]
+    fn tampered_signature_rejects() {
+        let mut envelope = sign_payload_from_seed(&[11u8; 32], b"quip-message").unwrap();
+        envelope.signature[envelope.signature.len() / 2] ^= 0xFF;
+
+        assert!(!envelope.verify(b"quip-message"));
+    }
+
+    #[test]
+    fn wrong_seed_length_rejects() {
+        assert!(public_key_from_seed(&[1u8; 31]).is_err());
+    }
+
+    // Standard BIP39 test vector phrase.
+    const TEST_PHRASE: &str =
+        "bottom drive obey lake curtain smoke basket hold race lonely fit walk";
+
+    #[test]
+    fn mnemonic_seed_is_deterministic() {
+        let first = master_seed_from_mnemonic(TEST_PHRASE, None).unwrap();
+        let second = master_seed_from_mnemonic(TEST_PHRASE, None).unwrap();
+
+        assert_eq!(first, second);
+    }
+
+    #[test]
+    fn mnemonic_password_changes_seed() {
+        let no_password = master_seed_from_mnemonic(TEST_PHRASE, None).unwrap();
+        let with_password = master_seed_from_mnemonic(TEST_PHRASE, Some("hunter2")).unwrap();
+
+        assert_ne!(no_password, with_password);
+    }
+
+    #[test]
+    fn secret_uri_password_matches_explicit_password() {
+        let split =
+            master_seed_from_secret_uri(&alloc::format!("{TEST_PHRASE}///hunter2")).unwrap();
+        let explicit = master_seed_from_mnemonic(TEST_PHRASE, Some("hunter2")).unwrap();
+
+        assert_eq!(split, explicit);
+    }
+
+    #[test]
+    fn secret_uri_accepts_hex_seed() {
+        let seed = master_seed_from_secret_uri(
+            "0x0707070707070707070707070707070707070707070707070707070707070707",
+        )
+        .unwrap();
+
+        assert_eq!(seed, [7u8; MASTER_SEED_LEN]);
+    }
+
+    #[test]
+    fn secret_uri_rejects_derivation_junctions() {
+        assert_eq!(
+            master_seed_from_secret_uri(&alloc::format!("{TEST_PHRASE}//0")),
+            Err(HybridTxCryptoError::UnsupportedDerivationPath)
+        );
+    }
+
+    #[test]
+    fn secret_uri_rejects_invalid_phrase() {
+        assert_eq!(
+            master_seed_from_secret_uri("not a real mnemonic phrase at all"),
+            Err(HybridTxCryptoError::InvalidMnemonic)
+        );
+    }
+
+    #[test]
+    fn mnemonic_seed_signs_and_verifies() {
+        let seed = master_seed_from_mnemonic(TEST_PHRASE, None).unwrap();
+        let envelope = sign_payload_from_seed(&seed, b"quip-message").unwrap();
+
+        assert!(envelope.verify(b"quip-message"));
+    }
+}

quip_signer-0.2.2/transaction-crypto-core/tests/golden_parity.rs

@@ -0,0 +1,95 @@
+//! Golden-vector parity gate.
+//!
+//! `golden_vectors.txt` was captured from the signer's byte output **before**
+//! the hybrid-crypto deduplication refactor (the move of the H3 suite into the
+//! shared `quip-crypto-primitives-core` crate). This test asserts the current
+//! implementation still reproduces those exact bytes, so the suite that the
+//! browser signs with and the suite the runtime verifies with can never
+//! silently drift apart.
+//!
+//! Vectors cover `seed -> public_key` and `(seed, msg) -> signature envelope`
+//! for several fixed seeds plus a BIP39-derived seed.
+
+use quip_transaction_crypto_core::{
+    master_seed_from_mnemonic, public_key_from_seed, sign_payload_from_seed,
+};
+
+const FIXTURE: &str = include_str!("golden_vectors.txt");
+
+const TEST_PHRASE: &str = "bottom drive obey lake curtain smoke basket hold race lonely fit walk";
+
+fn lookup<'a>(key: &str) -> &'a str {
+    for line in FIXTURE.lines() {
+        let line = line.trim();
+        if line.is_empty() {
+            continue;
+        }
+        let (name, value) = line.split_once('=').expect("fixture line is `name=value`");
+        if name == key {
+            // Leak-free: FIXTURE is 'static, so the slice is too.
+            return value;
+        }
+    }
+    panic!("fixture missing key `{key}`");
+}
+
+fn to_hex(bytes: &[u8]) -> String {
+    let mut out = String::with_capacity(bytes.len() * 2);
+    for b in bytes {
+        out.push_str(&format!("{b:02x}"));
+    }
+    out
+}
+
+fn assert_public(name: &str, seed: &[u8]) {
+    // Sanity: the recorded seed matches what we feed in.
+    assert_eq!(
+        to_hex(seed),
+        lookup(&format!("{name}_seed")),
+        "{name}: seed bytes drifted from fixture"
+    );
+    let public = public_key_from_seed(seed).expect("public derivation");
+    assert_eq!(
+        to_hex(&public),
+        lookup(&format!("{name}_public")),
+        "{name}: public key drifted from pre-refactor bytes"
+    );
+}
+
+fn assert_envelope(seed_name: &str, seed: &[u8], msg_name: &str, msg: &[u8]) {
+    let envelope = sign_payload_from_seed(seed, msg).expect("signing");
+    assert_eq!(
+        to_hex(&envelope.encode_envelope()),
+        lookup(&format!("{seed_name}_{msg_name}_envelope")),
+        "{seed_name}/{msg_name}: signature envelope drifted from pre-refactor bytes"
+    );
+}
+
+#[test]
+fn public_keys_match_pre_refactor_baseline() {
+    assert_public("seed_01", &[1u8; 32]);
+    assert_public("seed_07", &[7u8; 32]);
+    assert_public("seed_09", &[9u8; 32]);
+    assert_public("seed_11", &[11u8; 32]);
+
+    let bip39 = master_seed_from_mnemonic(TEST_PHRASE, None).unwrap();
+    assert_public("bip39", &bip39);
+
+    let bip39_pw = master_seed_from_mnemonic(TEST_PHRASE, Some("hunter2")).unwrap();
+    assert_public("bip39_pw", &bip39_pw);
+}
+
+#[test]
+fn signature_envelopes_match_pre_refactor_baseline() {
+    let messages: [(&str, &[u8]); 3] = [
+        ("msg_quip", b"quip-message"),
+        ("msg_empty", b""),
+        ("msg_fixture", b"quip-signer-fixture"),
+    ];
+
+    let bip39 = master_seed_from_mnemonic(TEST_PHRASE, None).unwrap();
+    for (mname, msg) in &messages {
+        assert_envelope("seed_07", &[7u8; 32], mname, msg);
+        assert_envelope("bip39", &bip39, mname, msg);
+    }
+}