chore: add system:fee_required role for phased write-fee rollout

[MicBun]

resolves: https://github.com/truflation/website/issues/3805

Summary by CodeRabbit

• New Features

  • Write operations now charge a transaction fee only for enrolled accounts; unenrolled accounts can perform these writes at no charge.

• Chores

  • Added system configuration to manage fee-enrollment and enable phased rollout of fees.

• Tests

  • Test suite updated to cover both enrolled (fee-applied) and unenrolled (free) scenarios for stream, record, and taxonomy writes.

[holdex]

Time Submission Status

Member	Status	Time	Action	Last Update
MicBun	✅ Submitted	2h	Update time	May 18, 2026, 3:28 PM

---

You can submit time with the command. Example:

@holdex pr submit-time 15m

See available commands to help comply with our Guidelines.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR implements a phased rollout of write-action fees by introducing a system:fee_required role gate. Previously, stream creation, record insertion, and taxonomy writes always charged 1 TRUF; now fees apply only to enrolled wallets. A new migration bootstraps the role, three action migrations conditionally gate fees on role membership, and test suites validate both paid and free paths.

Changes

Fee collection phased rollout via role-based gating

Layer / File(s)	Summary
Fee-required role bootstrap internal/migrations/047-fee-required-role.sql	New migration creates system:fee_required role with idempotent insert and conditional manager update, enabling downstream fee gating across write operations.
Write action fee gating implementations internal/migrations/001-common-actions.prod.sql, internal/migrations/001-common-actions.sql, internal/migrations/003-primitive-insertion.prod.sql, internal/migrations/003-primitive-insertion.sql, internal/migrations/004-composed-taxonomy.prod.sql, internal/migrations/004-composed-taxonomy.sql	create_streams, insert_records, and insert_taxonomy actions now check are_members_of(system, fee_required) before charging 1 TRUF; enrolled callers proceed through leader validation, balance check, and transfer; unenrolled callers skip the entire fee block. Both production and staging migrations are updated identically.
Stream creation fee test coverage tests/streams/stream_creation_fee_test.go	Existing fee tests now enroll wallets into system:fee_required before asserting 1 TRUF deductions. New testUnenrolledWalletCreatesStreamFree verifies unenrolled wallets can create streams with 0 TRUF balance without funding.
Record insertion fee test coverage tests/streams/insert_records_fee_test.go	Existing paid-path tests enroll wallets into system:fee_required. New testInsertUnenrolledWalletWritesFree confirms unenrolled wallets insert records with 0 TRUF balance remaining unchanged.
Taxonomy write fee test coverage tests/streams/taxonomy_fee_test.go	Existing fee-charging tests enroll wallets into system:fee_required before performing composed/child/taxonomy writes. New testTaxonomyUnenrolledWalletWritesFree validates unenrolled wallets complete the full sequence with 0 TRUF balance unchanged.
Transaction events ledger test update tests/streams/transaction_events_ledger_test.go	Scenario now enrolls the actor into system:fee_required before write-fee actions so the test exercises the paid-path as intended.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• trufnetwork/node#1373: Changes create_streams fee logic in internal/migrations/001-common-actions.sql to enforce flat 1 TRUF per transaction, overlapping with this PR's fee-collection path.
• trufnetwork/node#1248: Modifies insert_taxonomy’s fee-collection logic and related taxonomy tests, directly related to the changes here.
• trufnetwork/node#1372: Also touches fee-collection in create_streams, insert_records, and insert_taxonomy; could overlap with gating or transfer changes.

Suggested reviewers

• pr-time-tracker
• outerlook
• williamrusdyputra

Poem

🐰 I hopped through roles with a curious peep,
Some wallets pay while others sleep.
Enrolled ones tip the ledger's cup,
Unenrolled write freely — hop on up!
Fees roll out gently, step by step.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 95.83% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The PR title accurately describes the main change: introducing a system:fee_required role to gate write fees for phased rollout, which aligns with the modifications across multiple migration files and test files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/phase-write-fee-via-fee-required-role

---

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.}

[MicBun]

@holdex pr submit-time 2h