Withdrawal Credential Change Request Pipeline with Governance Workflow

[JamesEjembi]

Problem Statement / Feature Objective

Changing withdrawal credentials from BLS-withdrawal (0x00) to execution-layer-withdrawal (0x01) requires a signed BLSToExecutionChange message. For multi-sig or DAO-governed validator pools, the signing process involves multiple stakeholders. Build a pipeline that: constructs the change message, routes it through a configurable governance approval workflow (N-of-M signers), tracks approval progress, and broadcasts once threshold is met.

Technical Invariants & Bounds

• Message format: BLSToExecutionChange{validator_index, from_bls_pubkey, to_execution_address} signed with domain DOMAIN_BLS_TO_EXECUTION_CHANGE
• Governance workflow: configurable N-of-M approval threshold; each approver must sign the same message independently
• Approval tracking: each signature is an ECDSA signature over the SHA-256 hash of the SSZ-encoded message
• Deadline: change request auto-expires after 7 days if threshold not met
• Pipeline must support concurrent change requests for up to 50 validators simultaneously
• Each request state machine: Draft → PendingApproval → Approved → Broadcast → Confirmed → Failed
• Audit log: all signature submissions and state transitions logged to IndexedDB with tamper-evident hash chain

Codebase Navigation Guide

• src/hooks/useWithdrawalChange.ts – pipeline state management hook
• src/components/validators/WithdrawalChangeWizard.tsx – multi-step wizard
• src/utils/blsToExecutionChange.ts – message construction and validation
• src/services/governanceService.ts – governance workflow configuration
• src/store/changeRequestSlice.ts – request state management
• src/pages/settings/ValidatorSettings.tsx – integration point

Implementation Blueprint

1. Create src/utils/blsToExecutionChange.ts – constructs SSZ-encoded BLSToExecutionChange message, computes SHA-256 hash for signing
2. Build src/services/governanceService.ts – loads governance config (N-of-M threshold, approver list) from API or local config file
3. Implement src/hooks/useWithdrawalChange.ts – manages request lifecycle through all 6 states, handles concurrent requests, implements 7-day expiry with periodic cleanup
4. Create src/components/validators/WithdrawalChangeWizard.tsx – wizard with:
   • Step 1: Validator selection + new execution address input
   • Step 2: Approver assignment and signing requests (email/web3 notification)
   • Step 3: Approval progress bar (signatures collected vs threshold)
   • Step 4: Broadcast trigger with confirmation
5. Add src/utils/auditChain.ts – append-only audit log with SHA-256 hash chain linking consecutive entries
6. Implement IndexedDB persistence in src/services/changeRequestStore.ts – stores all request state + audit chain
7. Mount in ValidatorSettings.tsx under "Withdrawal Credentials" section

[pauljuliet9900-netizen]

Hello maintainer i would like to work on this issue

[grantfox-oss]

🦊 GrantFox — @pauljuliet9900-netizen has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #54)
2. Your PR will be reviewed by the VeriNode-Labs maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign campaign!

@pauljuliet9900-netizen's PR #85 was approved and merged by @JamesEjembi.

🏆 @pauljuliet9900-netizen: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (191 total points). Track your full progress on GrantFox.

👏 Great work, @pauljuliet9900-netizen! Keep contributing to VeriNode-Labs.