Two-tree integration: registration flow changes for cell-based credentials

[ejmockler]

Summary

The Communique client currently generates single-tree credentials during registration. With the two-tree architecture, registration must produce a cell-based credential instead: leaf = hash3(user_secret, cell_id, salt) rather than hash4(user_secret, district_id, authority_level, salt).

Severity: Required for two-tree deployment
Source: Two-Tree Architecture Spec §13
Related voter-protocol tracking: Phase 5 remaining items

What Changes

Current Flow

1. User enters address → geocoder returns district_id
2. System generates leaf = hash4(user_secret, district_id, authority_level, salt)
3. Credential stored with { district_id, authority_level, merkle_path, ... }

New Flow

1. User enters address → geocoder returns cell_id (Census GEOID)
2. System generates leaf = hash3(user_secret, cell_id, salt) using DOMAIN_HASH3
3. Cell-to-district mapping looked up from Shadow Atlas cell map
4. Credential stored with { cell_id, districts[24], merkle_path_user_tree, merkle_path_cell_map, ... }

Migration Path

• No forced re-registration. The 6-month credential expiry cycle IS the migration mechanism.
• At natural renewal, users re-enter their address (existing flow) and the system generates a two-tree credential.
• Both verifiers run in parallel during the 6-month rollover period.

Key Integration Points

1. Geocoder response handling: Must return cell_id (15-digit Census GEOID), not just district_id
2. Credential generation: Use @voter-protocol/crypto hash3() instead of hash4()
3. Proof generation: Use TwoTreeNoirProverAdapter from @voter-protocol/noir-prover
4. Dual-system: Detect credential type and route to appropriate prover/verifier

Pitfalls

• Cell ID is more sensitive than district ID (finer geographic granularity) — ensure it's never stored in plaintext outside the encrypted credential store
• The Shadow Atlas cell-district mapping must be fetched/cached client-side for proof generation
• Two-tree proofs have 29 public inputs vs 5 — ensure submission API handles both formats

Acceptance Criteria

• Registration generates cell-based credential
• Proof generation uses TwoTreeNoirProverAdapter
• Existing single-tree credentials continue working until renewal
• Cell ID encrypted at rest (same as user_secret)
• E2E test: register → generate proof → verify on-chain