Add MessagePassingBridge SDK Package

[L03TJ3]

1) Motivation

GoodSDKs needs a new @goodsdks/bridging-sdk package that wraps user-facing flows for MessagePassingBridge so developers can integrate bridging reliably. The SDK must follow existing SDK patterns in this repo (viem class + optional wagmi hook) and be the foundation for future UI components. The contract source of truth lives in the GoodBridge repo, and ABIs should be pulled from the published @gooddollar/bridge-contracts package. Clear SDK documentation aligned with GoodBridge MessagePassingBridge docs (https://github.com/GoodDollar/GoodBridge/tree/master/packages/bridge-contracts/contracts/messagePassingBridge) is required, including explicit guidance on decimal handling and msg.value requirements, with fees sourced primarily from the goodserver estimate fees API.

Expected output and supported features:

• New packages/bridging-sdk package.
• Should support bridging from/to: Celo/Ethereum mainnet/Fuse/XDC, using either Axelar or LayerZero
• Event and tx status + history fetching helpers for BridgeRequest and ExecutedTransfer.
• Documentation with usage examples and decimal handling guidance.
• Take care of bridge fee (ie indicate to user and send correct value in native token)
• User should be able to see status of TX based on layerzero/axelar api
• Link to layerzero/axelar explorer relevant tx

2) Guidelines

• Typed methods for canBridge, bridgeTo, bridgeToWithLz, and bridgeToWithAxelar.
• Fee estimation uses the GoodServer estimatefees API as the primary source (covers Axelar + LayerZero and all supported directions), and documents msg.value expectations (nonzero; should cover the estimated fee). Treat msg.value as the bridge fee and require it to be at least the estimated fee.
• Decimal handling is documented: source-chain amounts for bridgeTo/approve use native token decimals (the bridge amount should match the approve value), while limit checks on the target chain use 18-decimal normalized amounts.
• Event helpers for BridgeRequest and ExecutedTransfer are exposed with typed helpers or utilities.
• Chain support for Celo, Fuse, Ethereum Mainnet, and XDC is included.
• Documentation includes usage examples and aligns with GoodBridge MessagePassingBridge docs (https://github.com/GoodDollar/GoodBridge/tree/master/packages/bridge-contracts/contracts/messagePassingBridge), including a note that bridge amounts use native token decimals (Fuse/Ethereum: 2 decimals; Celo: 18) and canBridge checks on the target chain use 18-decimal units.
• new package packages/bridging-sdk with viem-based class and optional wagmi hook, ABI consumption from @gooddollar/bridge-contracts (no local ABI hand-editing), minimal configuration for supported chains, and docs/README describing the SDK structure and usage.

4) Starting points (top paths + notes)

• GoodBridge MessagePassingBridge contract sources/docs (https://github.com/GoodDollar/GoodBridge/tree/master/packages/bridge-contracts/contracts/messagePassingBridge).

(Align with structures that you can see in)

• packages/savings-sdk/src/viem-sdk.ts — minimal viem SDK structure and tx submission pattern.
• packages/savings-sdk/src/wagmi-sdk.ts — wagmi hook wrapper pattern.
• packages/engagement-sdk/src/viem-sdk.ts — event helpers and utility patterns.
• packages/citizen-sdk/src/constants.ts — chain config patterns (IDs, labels, RPCs).

5) Definition of Done (DoD) + How to test

DoD

• packages/bridging-sdk exists with package.json, tsup.config.ts, and src/index.ts exports consistent with other SDKs.
• Viem SDK class provides typed methods for bridge calls and canBridge pre-checks.
• Fee estimation helper(s) implemented and documented, using https://goodserver.gooddollar.org/bridge/estimatefees as the primary source, including msg.value usage and failure conditions when insufficient (treat msg.value as the bridge fee).
• Event helpers for BridgeRequest and ExecutedTransfer are exposed with typed outputs.
• Helper methods are provided to request/show list of pending/past bridge transactions done.
• ABI is sourced from @gooddollar/bridge-contracts and not duplicated locally.
• Documentation/README added describing API, supported chains, example usage, and decimal handling (native decimals for bridge calls; 18-decimal amounts for target-chain canBridge checks; Fuse/Ethereum 2 decimals and Celo 18 decimals).
• Security consideration: only user-facing methods exposed, and chain ID validation/guardrails are documented.
• Provide minimal UI demo (new demo app, following structure of existing demo-apps), demonstrating the bridging SDK

---

Design Reference

Design is not part of this issue and we don't expect a UI component, however, contributor should still review the screens so that all features are supported.
See things like:

• Bridge fees and estimates
• Choosing bridge-provider and the different chains it supports to swap to
• progress tracking of the transaction

[edehvictor]

I can work on this. can it be assigned to me please?

[Godbrand0]

hello, my name is thompson, and i would like to apply for the task given my past experience building similar projects. i have gone through the details provided, and consider it very helpful in understanding the issue, and implementing the package. i am liiking forward to hearing from you soon. thank you.

[EmekaManuel]

hi @L03TJ3 @sirpy , can i get assigned this ?

[sirpy]

@edehvictor we currently allow working on one issue at a time

[sirpy]

@Godbrand0
You are assigned.
Please make sure to read our contribution guidelines and follow the rules.

@EmekaManuel sorry @Godbrand0 applied first. look at the other issues

[Godbrand0]

@sirpy thank you for the assignment, i get get right on it. i also want to ask if there is a time frame for this issue?