feat(erc20-bridge): view TRUF wallet balance

[williamrusdyputra]

Description

action to check TRUF balance on TRUF.NETWORK kwil-db, not on layer-1.

Related Problem

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

How Has This Been Tested?

migrated.

Summary by CodeRabbit

• New Features

  • Added public, read-only actions to retrieve ERC20 wallet balances on Sepolia (testnet) and Mainnet, returning high-precision balances.
  • Introduced a Sepolia ERC20 bridge alias to enable seamless interactions with the test network.

• Chores

  • Added corresponding database migrations to configure the new bridge alias and expose the balance lookup actions.

• Notes

  • No breaking changes; existing functionality remains unaffected.

[coderabbitai]

Walkthrough

Adds an ERC20 bridge alias for Sepolia and introduces two public view actions to fetch ERC20 wallet balances on Sepolia and Mainnet via bridge balance calls.

Changes

Cohort / File(s)	Summary
ERC20 bridge extension setup internal/migrations/erc20-bridge/000-extension.sql	Defines sepolia_bridge via USE erc20_bridge { chain: 'sepolia', escrow: '0x1c6D0d1666E3Ea3896c0A94018B03Ca117C15762' } AS sepolia_bridge;. Includes comment noting requirement on leader/validator nodes.
ERC20 balance actions internal/migrations/erc20-bridge/001-actions.sql	Adds sepolia_wallet_balance(wallet_address TEXT) and mainnet_wallet_balance(wallet_address TEXT) as PUBLIC VIEW actions returning NUMERIC(78,0) via *.balance(wallet_address) calls.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant C as Client
  participant A1 as sepolia_wallet_balance
  participant B1 as sepolia_bridge
  participant E1 as Ethereum (Sepolia)

  C->>A1: wallet_address
  A1->>B1: balance(wallet_address)
  B1->>E1: Query ERC20 escrow
  E1-->>B1: balance
  B1-->>A1: balance
  A1-->>C: balance

  Note over A1,B1: Testnet flow

  %% Mainnet
  participant A2 as mainnet_wallet_balance
  participant B2 as mainnet_bridge
  participant E2 as Ethereum (Mainnet)

  C->>A2: wallet_address
  A2->>B2: balance(wallet_address)
  B2->>E2: Query ERC20 escrow
  E2-->>B2: balance
  B2-->>A2: balance
  A2-->>C: balance

  Note over A2,B2: Mainnet flow

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Assessment against linked issues

Objective	Addressed	Explanation
Create/check balance action(s) for ERC20 bridge [#1151]	✅

Assessment against linked issues: Out-of-scope changes

Code Change	Explanation
Add Sepolia bridge alias with fixed escrow address (internal/migrations/erc20-bridge/000-extension.sql)	Issue #1151 only mentions creating the balance action; adding a new chain alias/escrow configuration is not explicitly requested. It may be necessary for the action to work, but scope is unclear.

Poem

I thump my paws on fresh-migrated ground,
Two bridges humming, balances found.
Sepolia whispers, Mainnet replies—
Numbers like stars in blockchain skies.
I nibble a byte, then happily say:
“Your tokens are safe—now hop on your way!” 🐇✨

✨ Finishing Touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/get-wallet-balance

---

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	1h	Update time	Sep 8, 2025, 4:30 AM
MicBun	✅ Submitted	20min	Update time	Sep 8, 2025, 9:01 AM

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (4)

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

1-1: Deployment scope note may need docs/ops guard.

Migrations typically run cluster-wide. If this alias must exist only on leader/validator nodes, add ops docs or an environment guard in your migration runner.

I can add a short “operator notes” section to the migrations README if helpful.

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

2-2: Constrain address type to 42-char EVM addresses.

Use a narrower type to reject obviously invalid input early.

Apply:

-CREATE OR REPLACE ACTION sepolia_wallet_balance($wallet_address TEXT) PUBLIC VIEW RETURNS (balance NUMERIC(78, 0)) {
+CREATE OR REPLACE ACTION sepolia_wallet_balance($wallet_address VARCHAR(42)) PUBLIC VIEW RETURNS (balance NUMERIC(78, 0)) {
...
-CREATE OR REPLACE ACTION mainnet_wallet_balance($wallet_address TEXT) PUBLIC VIEW RETURNS (balance NUMERIC(78, 0)) {
+CREATE OR REPLACE ACTION mainnet_wallet_balance($wallet_address VARCHAR(42)) PUBLIC VIEW RETURNS (balance NUMERIC(78, 0)) {

Also applies to: 8-8

---

2-5: Lightweight address validation (optional).

If the action language supports it, add a guard for 0x prefix, length 42, and hex chars. Otherwise document expectations.

Would you like me to add a safe guard using the available expression/ASSERT primitives in this repo’s DSL?

Also applies to: 8-11

---

1-1: Clarify unit semantics in comments.

State that the returned value is raw token units (no decimal scaling), to avoid UI misinterpretation.

Apply:

--- TESTNET
+-- TESTNET
+-- Returns raw TRUF units from the bridge ledger; clients should apply token decimals when displaying.
 ...
--- MAINNET
+-- MAINNET
+-- Returns raw TRUF units from the bridge ledger; clients should apply token decimals when displaying.

Also applies to: 7-8

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0eaef43 and ec15776.

📒 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 (4)

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

2-5: Confirm escrow address correctness and alias uniqueness
Verified the escrow address only appears in internal/migrations/erc20-bridge/000-extension.sql and no other sepolia_bridge or mainnet_bridge aliases exist. Manually verify the Sepolia escrow address is correct and EIP-55 checksummed before deployment.

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

2-5: LGTM: testnet balance view correctly proxies and returns numeric(78,0).

---

8-11: LGTM: mainnet balance view mirrors testnet implementation.

---

9-9: Ensure mainnet_bridge alias exists prior to this migration.

This action depends on mainnet_bridge. Confirm an earlier migration defines it or add it alongside Sepolia.

[MicBun]

lgtm.
Might as well creating a test for it in another PRs to ensure everything doesn't break in the future enhancements.
cc @williamrusdyputra