feat(batcher): poll for unlock events and remove users with unlocked funds

[JuArce]

Feat(batcher): Poll for unlock events and remove users with unlocked funds

Description

This PR fetches BalanceUnlocked events from BatcherPaymentService to check if an user has proofs in the queue and has unlocked their funds.
In that case, the batcher will remove their proofs until the user locks funds again to avoid a withdrawal and trying to discount balace from a user without funds deposited.

Closes#2122

How to Test

1. Start anvil

2. Set balance_unlock_polling_interval_seconds to 60 in config-files/config-batcher.yaml. So the polling is executed every 1 minute

3. Start batcher

4. Deposit funds

aligned deposit-to-batcher \
--amount 1ether \
--private_key 0xdbda1821b80551c9d65939329250298aa3472ba22feea921c0cf5d620ea67b97 \
--network devnet \
--rpc_url http://localhost:8545

5. Send a proof with low fee

aligned submit \
--proving_system Risc0 \
--proof ./scripts/test_files/risc_zero/no_public_inputs/risc_zero_no_pub_input_3_0_3.proof \
--vm_program ./scripts/test_files/risc_zero/no_public_inputs/risc_zero_no_pub_input_id_3_0_3.bin \
--rpc_url http://localhost:8545 \
--network devnet \
--custom_fee_estimate 16 \
--private_key 0xdbda1821b80551c9d65939329250298aa3472ba22feea921c0cf5d620ea67b97 \
--random_address

You can send multiple proofs (less than 16 :p)

6. Unlock your funds

cast send 0x7bc06c482DEAd17c0e297aFbC32f6e63d3846650 "unlock()" \
--rpc-url http://localhost:8545 \
--private-key 0xdbda1821b80551c9d65939329250298aa3472ba22feea921c0cf5d620ea67b97

7. You should see logs like:

[2025-09-16T21:27:14Z INFO aligned_batcher] Found 1 BalanceUnlocked events in blocks 770 to 870
[2025-09-16T21:27:14Z INFO aligned_batcher] Processing BalanceUnlocked event for user: 0x23618e81e3f5cdf7f54c3d65f7fbc0abf5b21e8f

And the user should receive the error User funds have been unlocked and proofs removed from queue.

Other tests cases:

Unlock and lock funds. The batcher should not eject the user proofs

To lock funds again, use

cast send 0x7bc06c482DEAd17c0e297aFbC32f6e63d3846650 "lock()" \
--rpc-url http://localhost:8545 \
--private-key 0xdbda1821b80551c9d65939329250298aa3472ba22feea921c0cf5d620ea67b97

Type of change

• New feature
• Bug fix

Checklist

• “Hotfix” to testnet, everything else to staging
• Linked to Github Issue
• This change depends on code or research by an external entity
  • Acknowledgements were updated to give credit
• Unit tests added
• This change requires new documentation.
  • Documentation has been added/updated.
• This change is an Optimization
  • Benchmarks added/run
• Has a known issue
  • Link to the open issue addressing it
• If your PR changes the Operator compatibility (Ex: Upgrade prover versions)
  • This PR adds compatibility for operator for both versions and do not change crates/docs/examples
  • This PR updates batcher and docs/examples to the newer version. This requires the operator are already updated to be compatible

[MarcosNicolau]

General flow worked alright for me

[MarcosNicolau]

Worked correctly for me following #2119 instructions, but the CI is failing for some reason

[JuArce]

Ci is working now