fix: ensure balance in underlying token standard contract is updated when pruning

[sscovil]

Description

Fixes #38

This PR adds a _burnPrunedTokens hook to the abstract TokenEphemeral contract, which must be implemented by concrete inheriting contracts, to burn expired tokens when pruneBalanceRecords is called.

    /**
     * @notice Internal hook to handle burning of pruned tokens.
     * @dev Override this function to integrate with the token standard's burn mechanism.
     * Called automatically during pruning if expired tokens are found.
     * @param account Address from which tokens were pruned
     * @param id Token type identifier
     * @param amount Quantity of tokens that were pruned (expired)
     */
    function _burnPrunedTokens(address account, uint256 id, uint256 amount) internal virtual { }

The hook is called from within pruneBalanceRecords and a new ExpiredTokensPruned event is emitted, if the account has any expired tokens that need to be burned.

    /**
     * @notice Emitted when pruned tokens are burned.
     * @param from Address from which tokens were pruned
     * @param id Token type identifier
     * @param amount Quantity of tokens that were pruned (expired)
     */
    event ExpiredTokensPruned(address indexed from, uint256 indexed id, uint256 amount);

The _burnPrunedTokens method is implemented in EVMAuth1155:

    /// @inheritdoc TokenEphemeral
    function _burnPrunedTokens(address account, uint256 id, uint256 amount) internal virtual override {
        uint256[] memory ids = new uint256[](1);
        uint256[] memory values = new uint256[](1);
        ids[0] = id;
        values[0] = amount;
        super._update(account, address(0), ids, values);
    }

...and EVMAuth6909:

    /// @inheritdoc TokenEphemeral
    function _burnPrunedTokens(address account, uint256 id, uint256 amount) internal virtual override {
        super._update(account, address(0), id, amount);
    }

Type of change

• Bug fix (non-breaking change which fixes an issue)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update

How Has This Been Tested?

• Integration tests

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules
• I have checked my code and corrected any misspellings

Additional context:

The fix for this issue caused the size of the EVMAuth1155 contract to exceed the runtime limit. In order to make it work, we needed to remove the isAcceptedERC20PaymentToken function, which was deemed non-essential. The tokenERC20Prices function can be used instead; applications will just have to loop through the price structs to determine if a specific payment token is accepted.

This PR also makes some changes to the scripts in ExampleDeploy.s.sol, to illustrate that all roles should not necessarily be granted to the same user.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Matt-Dionis]

👍🏻