fix(token-2022): enforce transfer-hook checks in free pricing

[dev-jodee]

Summary

• validate Token-2022 transfer-hook mutability before fee price-model branching so both free and paid modes are guarded
• add a shared transaction-level Token-2022 transfer-hook validator that resolves transfer mints and deduplicates mint checks
• reuse the same mint-level immutable transfer-hook helper in payment-specific Token-2022 extension validation
• add free-mode regression tests that reject mutable hook authority and allow immutable authority

Test Plan (if applicable)

• cargo test -p kora-lib test_estimate_kora_fee_free_ -- --nocapture
• cargo test -p kora-lib test_validate_token2022_extensions_for_payment_rejects_mutable_transfer_hook_authority -- --nocapture

Breaking Changes (if applicable)

• None

---

📊 Unit Test Coverage

Unit Test Coverage: 85.2%

View Detailed Coverage Report

[github-actions]

📊 TypeScript Coverage Report

Coverage: 33.9%

View detailed report

Coverage artifacts have been uploaded to this workflow run.
View Artifacts

[greptile-apps]

Greptile Summary

This PR closes a security gap where the free price model skipped Token-2022 transfer-hook mutability validation by moving the check above the price-model branching in estimate_kora_fee. It also introduces a configurable TransferHookPolicy enum and a shared transaction-level validator with mint deduplication.

• P1 — estimateTransactionFee hardcodes DelayedSigning: Under the default DenyMutableForDelayedSigning policy, clients calling estimateTransactionFee on a mutable-hook transaction they intend to submit via signAndSendTransaction will receive a false validation error, because signAndSendTransaction uses ImmediateSignAndSend (allowed) but the estimate endpoint enforces DelayedSigning (rejected). This makes fee estimation broken for that legitimate combination.

Confidence Score: 4/5

Safe to merge after resolving the estimateTransactionFee / signAndSendTransaction flow mismatch (P1).

The core fix is correct and well-tested. One P1 defect exists: estimateTransactionFee hardcodes DelayedSigning, producing false validation errors for clients calling it before signAndSendTransaction on mutable-hook mints under the default policy. The two P2 issues are style-only and do not affect runtime behavior.

crates/lib/src/rpc_server/method/estimate_transaction_fee.rs — hardcoded TransferHookValidationFlow::DelayedSigning on line 84.

Vulnerabilities

• The transfer-hook mutability guard was previously missing on the free price path, allowing a mutable hook authority to potentially be changed between signTransaction and on-chain execution; this PR closes that gap.
• DenyMutableForDelayedSigning (the new default) correctly restricts delayed-signing flows while permitting immediate sign-and-send, which is the safe posture since the signed transaction is broadcast atomically.
• No secrets, private keys, or sensitive fields are exposed by the new config surface.
• The hardcoded DelayedSigning in estimateTransactionFee (P1 comment) is a behavioral mismatch, not a security regression.

Important Files Changed

Filename	Overview
crates/lib/src/fee/fee.rs	Core fix: estimate_kora_fee now calls validate_token2022_transfer_hooks_in_transaction before price-model branching, closing the free-mode bypass. Logic and tests are correct.
crates/lib/src/rpc_server/method/estimate_transaction_fee.rs	Hardcodes TransferHookValidationFlow::DelayedSigning, causing false validation errors when clients call estimateTransactionFee on mutable-hook transactions they intend to send via signAndSendTransaction (P1).
crates/lib/src/token/token.rs	New validate_token2022_transfer_hooks_in_transaction correctly deduplicates mint checks, resolves legacy transfer mints via source account, and respects the configurable TransferHookPolicy.
crates/lib/src/config.rs	Adds TransferHookPolicy enum and transfer_hook_policy field to Token2022Config; struct-level #[serde(default)] added, making field-level default on transfer_hook_policy redundant (P2).
crates/lib/src/bundle/helper.rs	Correctly infers TransferHookValidationFlow from PluginExecutionContext and threads it into estimate_kora_fee for bundle processing.
tests/free_signing/free_signing_tests.rs	Adds regression tests for mutable-hook rejection in free signTransaction and allowing in signAndSendTransaction; helper correctly builds a mutable-authority mint with transfer hook.
tests/tokens/token_2022_extensions_test.rs	Existing transfer-hook tests updated to use signAndSendTransaction for the allow-path, correctly reflecting the new policy default.
crates/lib/src/transaction/versioned_transaction.rs	Sets TransferHookValidationFlow based on will_send flag before calling estimate_kora_fee, cleanly mapping signTransaction → DelayedSigning and signAndSendTransaction → ImmediateSignAndSend.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Client Request] --> B{RPC Method}
    B -->|signTransaction| C[DelayedSigning]
    B -->|signAndSendTransaction| D[ImmediateSignAndSend]
    B -->|estimateTransactionFee| E[DelayedSigning HARDCODED]
    B -->|signBundle| F[DelayedSigning]
    B -->|signAndSendBundle| G[ImmediateSignAndSend]
    C --> H[estimate_kora_fee]
    D --> H
    E --> H
    F --> H
    G --> H
    H --> I[validate_token2022_transfer_hooks]
    I --> J{TransferHookPolicy}
    J -->|DenyAll| K[Always reject mutable hook]
    J -->|DenyMutableForDelayedSigning| L{Flow type?}
    J -->|AllowAll| M[Always allow]
    L -->|DelayedSigning| N[Reject mutable hook]
    L -->|ImmediateSignAndSend| O[Allow mutable hook]
    H --> P{Price Model}
    P -->|Free| Q[Return 0 fee]
    P -->|Fixed or Margin| R[Calculate fee]

Loading

_{Reviews (2): Last reviewed commit: "test(token-2022): add transfer-hook poli..." | Re-trigger Greptile}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 3 additional findings.

[greptile-apps]

Tip:

Greploops — Automatically fix all review issues by running /greploops in Claude Code. It iterates: fix, push, re-review, repeat until 5/5 confidence.

Use the Greptile plugin for Claude Code to query reviews, search comments, and manage custom context directly from your terminal.