This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Experimental FROST (Flexible Round-Optimized Schnorr Threshold signatures) multi-signature tooling for the Mina Protocol. Not security audited — do not use with real funds.
Rust workspace with three crates:
frost-bluepallas— FROST library for Mina's Pallas curve with Poseidon hashing. Now a generic ciphersuite crate — does NOT contain Mina transaction types orPallasMessage. It is parameterised over aChallengeMessagetrait.mina-tx— Mina transaction types, serialisation,PallasMessage,TransactionSignature,Sig,PubKeySer, and thebluepallas_compatglue. Standalone library; BluePallas bridging code is gated behind thefrost-bluepallas-compatfeature.mina-frost-client— CLI client for distributed key generation and signing sessions. Communicates with thefrostdserver.
cargo build --verbose # Build all crates
cargo test --verbose # Run all tests
cargo fmt --all # Format code
cargo clippy --all-targets --all-features -- -D clippy::all -W clippy::too_many_arguments # Lint
# Run specific crate tests
cargo test --package frost-bluepallas
cargo test --package mina-frost-client
cargo test --package mina-tx
# Run examples
cargo run --example dkg
cargo run --example mina-sign-tx
cargo run --example mina-gen-pubkey
cargo run --example signPre-commit hooks run fmt, clippy, and trailing whitespace checks. CI (rust.yml) runs build, test, and cargo fmt --check inside a Docker container.
The BluePallas<M> ciphersuite is now generic over a ChallengeMessage type parameter M. M must implement the ChallengeMessage trait, which provides the challenge() function. This allows the crate to be used without any dependency on Mina transaction types. Key modules:
lib.rs— Ciphersuite definition (BluePallas<M>),ChallengeMessagetrait, FROST round1/round2/aggregate re-exports, y-coordinate evenness enforcement for Mina compatibilitykeys.rs— Key generation (trusted dealer and DKG),KeyPackage,PublicKeyPackage, secret/signing shareshasher.rs— Low-level Poseidon hash utilities (hash_to_scalar,hash_to_array).message_hashandPallasMessagehave been moved tomina-txnegate.rs— Y-coordinate negation logic required by Mina's signature schemesigning_utilities.rs— Signing helper utilitieserrors.rs—BluePallasErrorandBluePallasResulttypes
Note: pallas_message.rs and mina_compat.rs have been removed from frost-bluepallas and moved to the mina-tx crate.
Contains all Mina-specific transaction logic. Modules:
pallas_message.rs—PallasMessagestruct (serialise/deserialise),Hashableimpl,message_hash,translate_pk,translate_sig,translate_minask, and theChallengeMessageimpl forPallasMessage(gated behindfrost-bluepallas-compatfeature)bluepallas_compat.rs— Bridge code betweenfrost-bluepallastypes andmina-txtypes:TryFrom<FrSig<BluePallasSuite>>forSig,TryFrom<VerifyingKey<BluePallasSuite>>forPubKeySer,TransactionEnvelope::to_pallas_message(),TransactionSignature::from_frost_signature()/from_frost_signature_bytes(). Only compiled with thefrost-bluepallas-compatfeature.signatures.rs—Sig,PubKeySer,TransactionSignature,TransactionSignature::new_with_zkapp_injection()errors.rs—MinaTxErrorenum andMinaTxResulttransactions/—TransactionEnvelope,TransactionKind, legacy/zkapp transaction typesgraphql.rs,base58.rs— GraphQL output and base58 utilities
Feature flags for mina-tx:
frost-bluepallas-compat— enablesbluepallas_compatmodule andChallengeMessageimpl forPallasMessage; addsfrost-bluepallas,frost-core,ark-ecas dependenciestest-utils— enables test helper utilities
Subcommand-based CLI using clap. Operation modes:
- Trusted dealer — Test-only centralized key generation
- DKG — Distributed key generation via
frostdserver - Coordinator/Participant — Signing session roles
- Contacts/Groups/Sessions — Management commands
- GraphQL — Transaction submission support
Each mode has its own module under src/ with config.rs, comms/, and operation logic. Async operations use tokio.
- FROST protocol flow: DKG (or trusted dealer) → Round 1 (nonce commitment) → Round 2 (signature share) → Aggregation
- Mina compatibility requires y-coordinate evenness checks and Poseidon-based hashing — see
frost-bluepallas/src/negate.rsandmina-tx/src/pallas_message.rs - The canonical
BluePallasSuitetype alias throughout the codebase isBluePallas<PallasMessage>(fromfrost-bluepallas+mina-tx)- In
mina-frost-client: defined insrc/lib.rsaspub type BluePallasSuite = BluePallas<PallasMessage> - In
frost-bluepallastests: defined intests/helpers/types.rs - In
frost-bluepallasexamples: defined inexamples/_shared/types.rs
- In
- Serialization uses
postcardfor binary,serde_jsonfor JSON,bs58for Mina addresses - Snapshot testing with
instacrate infrost-bluepallas/tests/snapshots/
- Rust 2021 edition, toolchain 1.87.0
- Error handling:
eyrefor applications,thiserrorfor library error types - Conventional Commits:
feat:,fix:,doc:, etc. - New
frost-bluepallasfeatures must maintain Mina signature format compatibility — update tests accordingly - Async code in
mina-frost-clientusestokio— keep consistent with existingsession.rs,coordinator/patterns - No panics in library code; explicit error handling with
Result - Prefer iterators over manual loops; leverage the type system for correctness
The mina-tx/src/transactions/zkapp_tx/ module handles ZKApp transaction serialization for Mina. Key patterns:
- o1js JSON compatibility: Mina's o1js library serializes numeric types as strings in JSON. Use newtype wrappers with custom
Serialize/Deserializeimplementations:StringU32(u32)/StringU64(u64)— serialize as"123"not123Field,PublicKey,TokenId— all have custom serde inzkapp_serde.rs
- When adding new types that appear in JSON, check o1js output format and match it
zkapp_tx.rs— Core struct definitions and type aliaseszkapp_serde.rs— CustomSerialize/Deserializeimplementationspacking.rs—PackableandEmptiabletraits for hashing (converts structs to field elements)zkapp_test_vectors.rs— Test data for commitment function tests (test-only)commit.rs— Commitment/hashing logic
- Define the type in
zkapp_tx.rs - Add serde impl in
zkapp_serde.rsif custom serialization needed - Implement
Packableinpacking.rsif the type participates in transaction hashing - Implement
Emptiableif the type appears inOption<T>fields that need packing - Update test vectors in
zkapp_test_vectors.rsif affected
- Real transaction JSON files in
mina-tx/tests/data/ - Use
include_str!to load test fixtures - Round-trip tests (
serialize→deserialize→ compare) catch serde issues
- Defined in
mina-tx/src/signatures.rs - Structure:
{ publicKey: PubKeySer, signature: Sig, payload: TransactionEnvelope } Sighas fieldsfield: BigInt<4>andscalar: BigInt<4>with custom serde (decimal strings + base58)- The
payloadfield contains the fullTransactionEnvelope— for ZkApp transactions, this includes injected signatures - Accessible via
mina_tx::TransactionSignature(re-exported frommina_tx::signatures) - FROST-specific constructors (
from_frost_signature,from_frost_signature_bytes) are inmina-tx/src/bluepallas_compat.rsand require thefrost-bluepallas-compatfeature
ZKAppCommand::inject_signature()inmina-tx/src/transactions/zkapp_tx/signature_injection.rs- Injects into
fee_payer.authorization(aStringfield, base58-encoded) - Injects into
account_updates[i].authorization.signature(Option<String>) for updates where:authorization_kind.is_signed == truepublic_keymatches the signeruse_full_commitment == true
- After injection, the full signed transaction is included in the
TransactionSignature.payload
TransactionEnvelopewrapsTransactionKind(enum:ZkApp(ZKAppCommand)|Legacy(LegacyTransaction)) +NetworkIdEnvelopeTransactionEnvelope::inner()returns&TransactionKind,inner_mut()returns&mut TransactionKindTransactionEnvelope::from_str_network()auto-detects transaction type (tries ZkApp first, then Legacy)TransactionEnvelope::to_pallas_message()andFrom<&TransactionEnvelope> for PallasMessageare inmina-tx/src/bluepallas_compat.rs
ZKAppCommand { fee_payer: FeePayer, account_updates: Vec<AccountUpdate>, memo: [u8; MEMO_BYTES] }FeePayer { body: FeePayerBody, authorization: String }— authorization is a plain String (base58 signature)AccountUpdate { body: AccountUpdateBody, authorization: Authorization }Authorization { proof: Option<String>, signature: Option<String> }AuthorizationKind { is_signed: Bool, is_proved: Bool, verification_key_hash: Field }—Boolis a type alias forbool
mina_tx::errors::MinaTxError— error type for allmina-txoperations (serialization, deserialization, invalid signatures/public keys, memo errors, zkapp errors, unknown tx type)frost_bluepallas::errors::BluePallasError— error type forfrost-bluepallasoperations (serialization, no message provided, save signature errors)
mina-tx/src/transactions/zkapp_tx.rsis a file (not a directory withmod.rs). The submodules live inmina-tx/src/transactions/zkapp_tx/directory alongside it (Rust 2021 module system).mina-tx/src/base58.rsmodule is public (pub mod base58) — can be imported from outsidemina-tx/src/bluepallas_compat.rsis only compiled whenfrost-bluepallas-compatfeature is enabledfrost-bluepallasno longer has apallas_messagemodule — it's inmina-txfrost-bluepallasno longer has amina_compatmodule — it's inmina-tx/src/bluepallas_compat.rsfrost-bluepallasno longer has atransactions/directory — it's inmina-tx/src/transactions/
- End-to-end test: DKG → signing → cross-package verification with
mina-signer - Uses release binary (
cargo build --release) spawned as subprocesses - Requires
frostdserver running +mkcertTLS certificates parse_and_verify()deserializesTransactionSignaturefrom the signature output file, then:- For ZkApp: verifies signature injection into authorization fields, then verifies with
mina_signer::create_kimchi - For Legacy: verifies with
mina_signer::create_legacy
- For ZkApp: verifies signature injection into authorization fields, then verifies with
- Test is slow (spawns multiple processes, network communication) — run manually rather than in quick iteration loops
BigInt<4>fromSigconverts to mina-signer types via.into()