Implement NUT-12: Offline ecash signature validation (DLEQ proofs)

Overview

We need to implement NUT-12 which adds Discrete Log Equality (DLEQ) proofs to enable offline signature validation. This allows users to verify mint signatures without contacting the mint directly, and enables peer-to-peer verification of ecash tokens.

Background

Currently, mint signatures can only be verified by the mint itself using private keys (NUT-00). NUT-12 extends this by allowing:

Alice (minting user) to verify the mint's signature using only public keys
Carol (receiving user) to verify tokens received from Alice without contacting the mint

This is achieved through DLEQ proofs that prove the mint used the same private key a for both:

Creating its public key A = a*G
Signing the blinded message C' = a*B'

Current Codebase Structure

The relevant files in the codebase are:

crates/libs/nuts/src/nut00/mod.rs - Contains Proof, BlindSignature, BlindedMessage structs
crates/libs/nuts/src/nut01/ - Contains PublicKey, SecretKey implementations
crates/libs/nuts/src/dhke.rs - Contains cryptographic operations like hash_to_curve, hash_e

Implementation Requirements

1. Add DLEQ Proof Structure

Create a new DLEQ proof struct that can be used in both BlindSignature and Proof:

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DleqProof {
    /// Challenge
    pub e: String, // hex-encoded
    /// Response  
    pub s: String, // hex-encoded
    /// Blinding factor (only present in Proof, not BlindSignature)
    pub r: Option<String>, // hex-encoded
}

2. Extend Existing Structs

Modify BlindSignature in nut00/mod.rs:

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct BlindSignature {
    pub amount: Amount,
    #[serde(rename = "id")]
    pub keyset_id: KeysetId,
    #[serde(rename = "C_")]
    pub c: PublicKey,
    // Add DLEQ proof
    pub dleq: Option<DleqProof>,
}

Modify Proof in nut00/mod.rs:

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Proof {
    pub amount: Amount,
    #[serde(rename = "id")]
    pub keyset_id: KeysetId,
    pub secret: Secret,
    #[serde(rename = "C")]
    pub c: PublicKey,
    // Add DLEQ proof with blinding factor
    pub dleq: Option<DleqProof>,
}

3. Implement DLEQ Cryptographic Functions

Add these functions to dhke.rs or create a new nut12.rs module:

Generate DLEQ Proof (Mint Side)

/// Generate DLEQ proof for blind signature
/// Returns (e, s) where e is challenge and s is response
pub fn generate_dleq_proof(
    mint_private_key: &SecretKey,    // a
    mint_public_key: &PublicKey,     // A = a*G  
    blinded_message: &PublicKey,     // B'
    blind_signature: &PublicKey,     // C' = a*B'
) -> Result<(String, String), Error>

Verify DLEQ Proof (Alice - Minting User)

/// Verify DLEQ proof during minting/swapping
/// Alice verifies the mint's signature on her blinded message
pub fn verify_dleq_proof_alice(
    e: &str,                        // challenge from mint
    s: &str,                        // response from mint  
    mint_public_key: &PublicKey,    // A
    blinded_message: &PublicKey,    // B' (Alice created this)
    blind_signature: &PublicKey,    // C' (mint returned this)
) -> Result<bool, Error>

Verify DLEQ Proof (Carol - Receiving User)

/// Verify DLEQ proof when receiving tokens from another user
/// Carol reconstructs B' and C' using the blinding factor r
pub fn verify_dleq_proof_carol(
    e: &str,                        // challenge from proof
    s: &str,                        // response from proof
    r: &str,                        // blinding factor from Alice
    mint_public_key: &PublicKey,    // A  
    secret: &[u8],                  // x (proof secret)
    unblind_signature: &PublicKey,  // C (unblinded signature)
) -> Result<bool, Error>

4. Implementation Details

DLEQ Proof Generation Algorithm

Bob (Mint):
1. r = random nonce
2. R1 = r*G  
3. R2 = r*B'
4. e = hash(R1, R2, A, C')
5. s = r + e*a
6. return (e, s)

DLEQ Proof Verification Algorithm

Alice/Carol:
1. R1 = s*G - e*A
2. R2 = s*B' - e*C'  
3. e_computed = hash(R1, R2, A, C')
4. return e == e_computed

Hash Function

The existing hash_e function in dhke.rs should work, but verify it matches the spec:

Takes array of PublicKeys
Converts each to uncompressed 65-byte hex representation
Concatenates all hex strings
Returns SHA256 hash

5. Integration Points

Modify `construct_proofs` function in `dhke.rs`

When constructing proofs, include the DLEQ proof from the blind signature and add the blinding factor:

pub fn construct_proofs(
    promises: Vec<BlindSignature>,
    rs: Vec<SecretKey>,           // blinding factors
    secrets: Vec<Secret>,
    keys: &SetPubKeys,
) -> Result<Proofs, Error>

The function should:

Extract DLEQ proof (e, s) from each BlindSignature
Add blinding factor r to create complete DLEQ proof for Proof
Verify the DLEQ proof before constructing the proof

Add Validation Requirements

When BlindSignature contains DLEQ proof → MUST verify it (Alice's case)
When Proof contains DLEQ proof → MUST verify it (Carol's case)

6. Error Handling

Add appropriate error variants to handle DLEQ-specific failures:

pub enum Error {
    // ... existing variants
    /// DLEQ proof verification failed
    DleqVerificationFailed,
    /// Invalid DLEQ proof format  
    InvalidDleqProof,
    /// Missing required DLEQ proof
    MissingDleqProof,
}

7. Testing Requirements

Implement comprehensive tests covering:

DLEQ proof generation and verification
Round-trip: generate proof → verify as Alice → verify as Carol
Edge cases: invalid proofs, missing data, malformed inputs
Integration with existing construct_proofs workflow
Test vectors from NUT-12 specification if available

8. Wallet Library Integration

Implement Core DLEQ Verification in Wallet Library

The DLEQ verification logic should be implemented as public functions in the wallet library, not just in the CLI. This ensures the functionality is reusable across different wallet implementations and can be properly tested.

Add to wallet library:

/// Verify DLEQ proofs in a compact wad without consuming tokens
/// This is the "Carol" verification scenario - validating tokens received from another user
pub async fn verify_compact_wad_dleq_proofs<U: Unit>(
    wad: &CompactWad<U>,
    node_client: &mut NodeClient<tonic::transport::Channel>,
) -> Result<DleqVerificationResult, Error> {
    // Implementation here
}

#[derive(Debug, Clone)]
pub struct DleqVerificationResult {
    pub total_proofs: usize,
    pub valid_proofs: usize,
    pub invalid_proofs: Vec<DleqProofError>,
    pub is_fully_valid: bool,
}

#[derive(Debug, Clone)]
pub struct DleqProofError {
    pub proof_index: usize,
    pub amount: Amount,
    pub error: String,
}

Requirements:

Must fetch keyset information from the node to get public keys for verification
Should validate all proofs in the wad using Carol's verification method
Must be non-destructive (no tokens consumed)
Should provide detailed results for each proof verification
Must handle multiple keysets within a single wad

9. CLI Integration

Extend DecodeWad Command for DLEQ Verification

The CLI should use the wallet library functions to provide DLEQ verification capability.

Modify cli-wallet/src/main.rs:

Add an optional --verify flag to the DecodeWad command:

/// Decode a wad to view its contents
#[command(
    about = "Decode a wad to print its contents and optionally verify DLEQ proofs",
    long_about = "Decode a wad to print its contents in a friendly format. With --verify flag, also validates DLEQ proofs without consuming the tokens."
)]
DecodeWad {
    #[command(flatten)]
    wad_args: WadArgs,
    /// Verify DLEQ proofs in the received tokens
    #[arg(long, help = "Verify DLEQ proofs without consuming tokens")]
    verify: bool,
},

Implementation Requirements:

Use the wallet library's verify_compact_wad_dleq_proofs function
When --verify is specified, connect to the appropriate node to fetch keyset info
Display verification results for each proof in the wad
Show clear success/failure indicators for each token
If any verification fails, display detailed error information

Example Usage:

# Decode wad contents only
cli-wallet decode-wad --file tokens.wad

# Decode and verify DLEQ proofs
cli-wallet decode-wad --file tokens.wad --verify

# Verify from string
cli-wallet decode-wad --string "cashuB..." --verify

Example Output with Verification:

Node URL: http://localhost:3338
Memo: Payment for coffee
Total Value: 1000 sat
DLEQ Verification: ✓ PASSED (3/3 proofs valid)

Detailed Contents:
{...json...}

Verification Details:
  Proof 1 (100 sat): ✓ DLEQ Valid
  Proof 2 (400 sat): ✓ DLEQ Valid  
  Proof 3 (500 sat): ✓ DLEQ Valid

10. Testing Requirements

NUT-12: Offline ecash signature validation¶ #155

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions