Lock transfer

[td202]

Closes COR-2305, Closes COR-2395

Purpose

Implements the lock transfer operations. This also changes the behaviour of token transfers to validate the transfer amount against the "available" token balance of the sender account, which for protocol versions lower than 11 will never differ from the total token balance.

Checklist

• My code follows the style of this project.
• The code compiles without warnings.
• I have performed a self-review of the changes.
• I have documented my code, in particular the intent of the
  hard-to-understand areas.
• (If necessary) I have updated the CHANGELOG.

[Copilot]

Pull request overview

This PR adds support for transferring token balances into and out of protocol-level locks, and tightens token transfer semantics to respect “available balance” (total minus locked amounts). It also extends block-state lock tracking so lock/account/token references can be removed when a locked balance is depleted.

Changes:

• Add iteration/decoding support for all per-account locked balances in token-module state and use it to enforce “available balance” in normal transfers.
• Implement lock Fund, Send, and Return operations in the scheduler by invoking new token-context operations (transfer_into_lock / transfer_from_lock) and emitting transfer events.
• Add block-state APIs and storage support for removing lock balance references when an account no longer has any balance controlled by a lock.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
plt/plt-scheduler/src/token_module/key_value_state.rs	Adds prefix-iteration decoding for per-account lock balances and refactors locked-balance decoding helper.
plt/plt-scheduler/src/token_context.rs	Enforces “available balance” in transfers and adds token-context operations for moving balances into/out of locks.
plt/plt-scheduler/src/scheduler/plt_scheduler.rs	Implements lock fund/send/return execution logic in meta updates (including reject mapping and events).
plt/plt-scheduler/src/scheduler.rs	Adds helper to map TokenTransferError into transaction failures/reject reasons.
plt/plt-scheduler-types/src/types/tokens.rs	Adds checked_add / checked_sub helpers to RawTokenAmount.
plt/plt-block-state/src/entity/protocol_level_locks/p11.rs	Adds remove_lock_balance_ref to lock state model.
plt/plt-block-state/src/block_state.rs / plt/plt-block-state/src/block_state_interface.rs	Wires remove_lock_balance_ref into the block state operations trait and P11 implementation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 80.16529% with 144 lines in your changes missing coverage. Please review.
✅ Project coverage is 64.07%. Comparing base (b88dc54) to head (404cb8f).
⚠️ Report is 18 commits behind head on release/p11.

Files with missing lines	Patch %	Lines
plt/plt-scheduler/src/scheduler/plt_scheduler.rs	79.17%	91 Missing ⚠️
...er/src/protocol_level_tokens/balance_operations.rs	81.48%	25 Missing ⚠️
plt/plt-block-state/src/block_state.rs	0.00%	24 Missing ⚠️
.../plt-scheduler/src/locks/lock_controller_simple.rs	89.47%	4 Missing ⚠️

Additional details and impacted files

@@               Coverage Diff               @@
##           release/p11    #1649      +/-   ##
===============================================
+ Coverage        63.97%   64.07%   +0.09%     
===============================================
  Files              376      376              
  Lines            74408    75007     +599     
  Branches          3016     3013       -3     
===============================================
+ Hits             47606    48064     +458     
- Misses           23786    23930     +144     
+ Partials          3016     3013       -3     

Files with missing lines	Coverage Δ
...cheduler/SchedulerTests/TokenHolderTransactions.hs	94.79% <100.00%> (+0.11%)	⬆️
...block-state/src/entity/protocol_level_locks/p11.rs	95.29% <100.00%> (+0.55%)	⬆️
plt/plt-scheduler-types/src/types/tokens.rs	100.00% <100.00%> (ø)
plt/plt-scheduler/src/locks/lock_controller.rs	100.00% <100.00%> (ø)
...r/src/protocol_level_tokens/token_module/update.rs	99.38% <100.00%> (+0.34%)	⬆️
plt/plt-scheduler/src/scheduler/p11.rs	95.61% <100.00%> (+0.97%)	⬆️
.../plt-scheduler/src/locks/lock_controller_simple.rs	93.33% <89.47%> (+1.19%)	⬆️
plt/plt-block-state/src/block_state.rs	13.27% <0.00%> (-0.75%)	⬇️
...er/src/protocol_level_tokens/balance_operations.rs	88.31% <81.48%> (-5.92%)	⬇️
plt/plt-scheduler/src/scheduler/plt_scheduler.rs	79.55% <79.17%> (-8.62%)	⬇️

... and 7 files with indirect coverage changes

[limemloh]

Have some comments, but nothing which can't be dealt with in another PR