feat(erc20-bridge): lock and unlock TRUF tokens

[williamrusdyputra]

note: I will do the custom test on separate PR after transfer action is available.

Related Problem

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

How Has This Been Tested?

Initial Balance (in 18 decimals format)

Lock Tokens

Treasury Balance after lock

Unlock Tokens

Treasury Balance after unlock

Summary by CodeRabbit

• New Features
  • Added admin actions to lock and unlock tokens on Sepolia and Mainnet, enabling controlled token movements by admins.
• Bug Fixes
  • Fixed a syntax issue in a wallet balance action to ensure proper execution.
• Chores
  • Updated Sepolia bridge configuration, including module reference and escrow address, to align with current network settings.

[coderabbitai]

Walkthrough

Updates the ERC20 bridge migration: switches the Sepolia bridge USE module from erc20_bridge to erc20 and updates the escrow address. Adds four public admin actions for locking/unlocking tokens on Sepolia and Mainnet, and fixes a missing closure in a mainnet action.

Changes

Cohort / File(s)	Summary of changes
ERC20 bridge extension config internal/migrations/erc20-bridge/000-extension.sql	Changed USE module from erc20_bridge to erc20 for Sepolia; updated escrow address to 0x2D4f435867066737bA1617ef024E073413909Ad2; kept alias AS sepolia_bridge.
ERC20 bridge admin actions internal/migrations/erc20-bridge/001-actions.sql	Added public admin actions: sepolia_admin_lock_tokens, sepolia_admin_unlock_tokens, mainnet_admin_lock_tokens, mainnet_admin_unlock_tokens, delegating to sepolia_bridge/mainnet_bridge methods with NUMERIC(78,0) casting.
Syntactic fix internal/migrations/erc20-bridge/001-actions.sql	Added missing closing }; for mainnet_wallet_balance action.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor Admin as Admin Client
  participant DB as DB Action (SQL)
  participant Bridge as sepolia_bridge/mainnet_bridge
  participant Chain as L1 Chain (Sepolia/Mainnet)

  Admin->>DB: call *_admin_lock_tokens(wallet, amount_text)
  DB->>Bridge: lock_admin(wallet, amount::NUMERIC(78,0))
  Bridge->>Chain: Submit lock tx
  Chain-->>Bridge: Tx result
  Bridge-->>DB: Status/receipt
  DB-->>Admin: Action result

  %% Unlock flow
  Admin->>DB: call *_admin_unlock_tokens(to, amount_text)
  DB->>Bridge: unlock(to, amount::NUMERIC(78,0))
  Bridge->>Chain: Submit unlock tx
  Chain-->>Bridge: Tx result
  Bridge-->>DB: Status/receipt
  DB-->>Admin: Action result

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• feat(erc20-bridge): view TRUF wallet balance #1144 — Modifies the same ERC20 bridge migrations, introducing the sepolia_bridge alias and wallet balance actions; this PR builds on those files with module/escrow updates and admin actions.

Suggested reviewers

• MicBun

Pre-merge checks (4 passed, 1 warning)

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes Check	⚠️ Warning	The PR includes unrelated changes to the ERC20 bridge extension configuration (module reference and escrow address update) that were not part of the lock/unlock objectives defined in issues #1153 or #1156.	Please separate these configuration updates into a different PR or clarify why they are required for the lock/unlock feature.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title succinctly captures the core feature addition of locking and unlocking TRUF tokens and aligns with conventional commit style.
Linked Issues Check	✅ Passed	The PR adds both lock and unlock actions for TRUF tokens on Sepolia and Mainnet (sepolia_admin_lock_tokens, sepolia_admin_unlock_tokens, mainnet_admin_lock_tokens, and mainnet_admin_unlock_tokens), fully satisfying issues #1153 and #1156.
Description Check	✅ Passed	The description references and resolves issues #1153 and #1156 and provides relevant test evidence for the newly implemented lock and unlock actions, directly relating to the changeset.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

Poem

A hop and a lock on the Sepolia lane,
A skip and unlock on Mainnet’s domain.
New bridge calls squeak, “All clear!” with delight,
Escrow swapped proper, numbers cast right.
Thump-thump my paws—deployments in sight! 🐇✨

Tip

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

• Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
• Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
		  - name: "Undocumented Breaking Changes"
			  mode: "warning"
			  instructions: |
				  Flag potential breaking changes that are not documented:
				  1. Identify changes to public APIs/exports, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints (including removed/renamed items and changes to types, required params, return values, defaults, or behavior).
				  2. Ignore purely internal/private changes (e.g., code not exported from package entry points or marked internal).
				  3. Verify documentation exists: a "Breaking Change" section in the PR description and updates to CHANGELOG.md.

Please share your feedback with us on this Discord post.

✨ Finishing Touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/lock-unlock-tokens

---

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	5h	Update time	Sep 9, 2025, 4:33 AM
MicBun	✅ Submitted	15min	Update time	Sep 9, 2025, 4:33 AM

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (3)

internal/migrations/erc20-bridge/001-actions.sql (3)

11-13: Parameter naming and type consistency; prefer NUMERIC and consistent address arg

Use a consistent parameter name across lock/unlock, and avoid TEXT + cast.

-CREATE OR REPLACE ACTION sepolia_admin_unlock_tokens($to_address TEXT, $amount TEXT) PUBLIC {
-  sepolia_bridge.unlock($to_address, $amount::NUMERIC(78, 0));
+CREATE OR REPLACE ACTION sepolia_admin_unlock_tokens($wallet_address TEXT, $amount NUMERIC(78, 0)) PUBLIC {
+  sepolia_bridge.unlock($wallet_address, $amount);
 }

---

25-26: Unlock action consistency and minimal input validation

• Apply same param/type changes as above for consistency.
• Consider guarding $amount > 0 if the DSL supports preconditions; otherwise rely on module-level checks.

-CREATE OR REPLACE ACTION mainnet_admin_unlock_tokens($to_address TEXT, $amount TEXT) PUBLIC {
-  mainnet_bridge.unlock($to_address, $amount::NUMERIC(78, 0));
+CREATE OR REPLACE ACTION mainnet_admin_unlock_tokens($wallet_address TEXT, $amount NUMERIC(78, 0)) PUBLIC {
+  mainnet_bridge.unlock($wallet_address, $amount);
 }

---

7-13: Return useful metadata for observability

Consider returning a tx hash or post-action balances to aid operators and dashboards. If unsupported in this DSL, ignore.

Also applies to: 21-26

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0374344 and e3cf45d.

📒 Files selected for processing (2)

• internal/migrations/erc20-bridge/000-extension.sql (1 hunks)
• internal/migrations/erc20-bridge/001-actions.sql (1 hunks)

⏰ 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). (1)

• GitHub Check: acceptance-test

🔇 Additional comments (2)

internal/migrations/erc20-bridge/000-extension.sql (1)

3-6: Verify new module alias and escrow permissions
Ensure the erc20 extension you’re switching to defines sepolia_bridge.lock_admin(...) and sepolia_bridge.unlock(...), and confirm the new escrow address 0x2D4f435867066737bA1617ef024E073413909Ad2 has the required lock/unlock roles.

internal/migrations/erc20-bridge/001-actions.sql (1)

19-19: Mainnet wallet balance closure fix — LGTM

The missing closing }; is correctly added.