Implement BTT testing for LibERC20

[lumoswiz]

Summary

• Introduces BTT style testing for the LibERC20 contract (i.e. ERC20Mod). See Adopt BTT and shared base contract across test suite #248.
• Each function in the module, has it's own tree file and test file.
• This PR is purely additive to demonstrate what the test suite refactor might look like, and to get early feedback.

If this looks okay, I can continue with testing other smart contracts. In this case, I will need feedback/guidance on how to structure the test directory. I see two options in the short term:

1. Keep things mostly as they are, adding additional folders as need. For example, to test the ERC20Facet next, I would add a facet folder here: test/token/ERC20/ERC20/facet. Then add tree and test files for each function.
2. Refactor everything within a "Sablier"-like system (see here. This will split: unit, integration, fork and invariant tests into their own folders. Currently, we only have unit tests so this may be overkill for now, however, if you plan to add these, it might be worthwhile considering now.

Changes Made

• Reusable base test contract and utilities.
• Fuzzed unit tests for LibERC20 using the BTT style, with accompanying .tree files.

Checklist

Before submitting this PR, please ensure:

• Code follows the Solidity feature ban - No inheritance, constructors, modifiers, public/private variables, external library functions, using for directives, or selfdestruct

• Code follows Design Principles - Readable, uses diamond storage, favors composition over inheritance

• Code matches the codebase style - Consistent formatting, documentation, and patterns (e.g. ERC20Facet.sol)

• Code is formatted with forge fmt

• Existing tests pass - Run tests to be sure existing tests pass.

• New tests are optional - If you don't provide tests for new functionality or changes then please create a new issue so this can be assigned to someone.

• All tests pass - Run forge test and ensure everything works

• Documentation updated - If applicable, update relevant documentation

[netlify]

👷 Deploy request for compose-diamonds pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	37c318a

[github-actions]

Coverage Report

Metric	Coverage	Details
Lines	84%	1506/1784 lines
Functions	85%	335/394 functions
Branches	65%	161/248 branches

Last updated: Wed, 17 Dec 2025 09:19:39 GMT for commit 37c318a

[github-actions]

Gas Report

No gas usage changes detected between main and test/liberc20-btt-fuzz-tests.

All functions maintain the same gas costs. ✅

Last updated: Wed, 17 Dec 2025 09:20:22 GMT for commit 37c318a

[adamgall]

I think this is a really great approach to testing, and I'd like to see more of this for sure!

How do the *.tree files "work"? Are they consumed in any tooling?

Regarding your continued approach, I think option 2 is best to do the sooner it can happen. Maybe a hybrid approach would be to just build the new structure alongside what exists already, then when it's finished and at parity (or whatever), we can delete the old test structure.

If that sounds like too much, or you'd prefer something else, let me know.

[lumoswiz]

I think this is a really great approach to testing, and I'd like to see more of this for sure!

How do the *.tree files "work"? Are they consumed in any tooling?

Regarding your continued approach, I think option 2 is best to do the sooner it can happen. Maybe a hybrid approach would be to just build the new structure alongside what exists already, then when it's finished and at parity (or whatever), we can delete the old test structure.

If that sounds like too much, or you'd prefer something else, let me know.

I've been using these VSCode extensions:

• Tree for syntax highlighting
• ASCII Tree Generator for formatting to the tree structure.

I also feel the same way - option 2 is better in the long term. As far the workload, I'm more than happy to take it on. I'll chip away at it over the next month.

Would you prefer this done in smaller, targeted PRs? That is, fuzzed unit testing for a single facet or module.

[mudgen]

@lumoswiz Looks good! Good job. Got an error on comment formatting: https://github.com/Perfect-Abstractions/Compose/actions/runs/20244602006/job/58121261728?pr=250

Can you fix the error on comment formatting? Then I can merge this.

[lumoswiz]

Okay, this is ready now. As I continue the test suite refactor, I will:

• centralise the harnesses in test/harness/ directory
• work through remaining facets and modules to put existing unit tests (concrete and fuzz) within a BTT framework

I'll do one PR per facet/module, unless grouping some (e.g. facet/module pairs) makes sense.
Changes will also be additive, the existing test suite won't be modified.

[mudgen]

@lumoswiz Great!

[mudgen]

@lumoswiz We are also going to need some documentation written in https://compose.diamonds/docs/contribution/testing that explains how the new testing works.

I'm really glad you are working on this.