chore: add taxonomies creation fees

[williamrusdyputra]

resolves: https://github.com/trufnetwork/truf-network/issues/1313

Summary by CodeRabbit

[coderabbitai]

Walkthrough

This change implements fee collection for taxonomy operations in the insert_taxonomy stored procedure. Non-exempt callers pay 2 TRUF per child stream with balance validation before the transfer. Callers with the system:network_writer role bypass fees entirely. A comprehensive test suite validates fee behavior across multiple scenarios.

Changes

Cohort / File(s)	Summary
Fee Collection Implementation internal/migrations/004-composed-taxonomy.sql	Adds role-based fee exemption check and fee collection logic to insert_taxonomy: validates caller balance (2 TRUF per child stream), raises error if insufficient funds, transfers fees to leader's address before taxonomy insertion
Fee Validation Tests tests/streams/taxonomy_fee_test.go	Adds comprehensive test suite (TestTaxonomyFees) with four sub-tests validating exempt wallet fee bypass, non-exempt wallet fee deduction, insufficient balance error handling, and multi-child fee calculation (2 TRUF per child)

Sequence Diagram

sequenceDiagram
    actor User
    participant Engine as Taxonomy Engine
    participant RoleCheck as Role Check
    participant Balance as Balance Validator
    participant Ledger as Fee Ledger
    participant DB as Database

    User->>Engine: insert_taxonomy(children, weights...)
    Engine->>RoleCheck: Check role (system:network_writer)?
    
    alt Role Exempt
        RoleCheck-->>Engine: Exempt (skip fee)
        Engine->>DB: Insert taxonomy
        DB-->>Engine: Success
    else Role Non-Exempt
        RoleCheck-->>Engine: Not exempt
        Engine->>Balance: Calculate fee (2 TRUF × children_count)
        Balance->>Balance: totalFee = 2 TRUF × N
        Balance->>Ledger: Check caller balance ≥ totalFee
        
        alt Sufficient Balance
            Ledger-->>Balance: ✓ Balance OK
            Balance-->>Engine: Fee validated
            Engine->>Ledger: Transfer totalFee to leader_sender
            Ledger-->>Engine: Fee transferred
            Engine->>DB: Insert taxonomy
            DB-->>Engine: Success
        else Insufficient Balance
            Ledger-->>Balance: ✗ Insufficient balance
            Balance-->>Engine: Error (required: X, available: Y, children: N)
            Engine-->>User: Transaction rejected
        end
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

• Fee calculation logic: Verify 2 TRUF per child stream is correctly computed and applied consistently
• Role-based exemption check: Confirm system:network_writer role check is implemented correctly and uses proper access control validation
• Balance validation: Ensure Ethereum bridge balance check is accurate before fee transfer
• Error messaging: Validate error messages clearly communicate required fee amount and child stream count for debugging
• Test edge cases: Review all four test scenarios cover critical paths (exempt flow, non-exempt with sufficient/insufficient balance, multi-child scenarios)
• SQL transaction safety: Ensure fee transfer and taxonomy insertion maintain data consistency if either operation fails

Suggested labels

type: chore

Suggested reviewers

• MicBun

Poem

🐰 Through taxonomy's new garden fair,
Fees collect with utmost care,
Two TRUF per child, a balanced cost,
While network_writers pay naught, not lost!
Tests bloom bright, edge cases spanned,
This fee-charged forest, carefully planned. 🌲

Pre-merge checks and finishing touches

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'chore: add taxonomies creation fees' accurately reflects the main change of introducing fee collection for taxonomy operations.
Linked Issues check	✅ Passed	The PR implements all coding requirements from issue #1313: fee calculation (2 TRUF per child), role-based exemption check, balance validation, fee transfer to leader, and existing taxonomy logic preservation.
Out of Scope Changes check	✅ Passed	All changes are scoped to implementing taxonomy fee collection requirements; no unrelated modifications to other features or components are present.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch chore/taxonomies-fee

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ef71f05 and 0af8386.

📒 Files selected for processing (2)

• internal/migrations/004-composed-taxonomy.sql (2 hunks)
• tests/streams/taxonomy_fee_test.go (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

tests/streams/taxonomy_fee_test.go (5)

tests/streams/utils/runner.go (1)

• RunSchemaTest (37-116)

internal/migrations/migration.go (1)

• GetSeedScriptStatements (60-109)

tests/streams/utils/utils.go (1)

• GetTestOptionsWithCache (75-88)

tests/streams/utils/setup/roles.go (1)

• AddMemberToRoleBypass (73-98)

tests/streams/utils/setup/common.go (2)

• CreateDataProvider (193-234)
• CreateDataProviderWithoutRole (243-295)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: lint
• GitHub Check: acceptance-test

🔇 Additional comments (2)

internal/migrations/004-composed-taxonomy.sql (1)

45-68: Fee guard matches the requirements.

The role-based exemption, per-child fee calculation, balance validation, and leader transfer all line up cleanly with the acceptance criteria while leaving the downstream taxonomy logic untouched. Nice work keeping the error message explicit about the required amount and child count.

tests/streams/taxonomy_fee_test.go (1)

32-280: Great coverage of the new fee paths.

Appreciate the end-to-end coverage here—exempt wallets, non-exempt flow, insufficient balance error, and multi-child scaling are all exercised, so regressions should surface quickly if the fee logic changes.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[holdex]

Time Submission Status

Member	Status	Time	Action	Last Update
williamrusdyputra	✅ Submitted	3h	Update time	Nov 4, 2025, 8:19 AM
MicBun	✅ Submitted	15min	Update time	Nov 4, 2025, 11:03 AM

[MicBun]

lgtm