[PLAN] Convert buy G$ to a GoodWidget

[sirpy]

Convert buy G$ to a GoodWidget

Parent issue: #94

---

Overview

This plan covers converting the "Buy G$" feature into a GoodWidget. The widget enables users to buy G$ using fiat via the Onramper widget, which buys a stable token on Celo into a user-owned smart contract. The smart contract then converts it to G$ and sends it back to the user's wallet.

Reference Files

GoodWidget (target repo)

• Existing widget components and structure to be used as the foundation for the new Buy G$ widget.

GoodProtocolUI (UI reference)

• src/pages/gd/BuyGD/index.tsx — GoodProtocolUI BuyGD
  • Provides the basic layout and UI structure for the Buy G$ page.

good-design (widget reference)

• packages/good-design/src/apps/onramp/ — GoodWeb3-Mono onramp app
  • The existing Onramper widget implementation. Components, state management, and UI patterns should be referenced.

web3-sdkv2 (Buy G$ SDK)

• packages/sdk-v2/src/sdk/buygd/react.tsx — BuyGD React SDK
  • Provides React hooks and utilities for the Buy G$ flow. This SDK should be imported as @gooddollar/web3-sdkv2.

---

Required States, Flows, and Behaviors

States

1. Idle / Initial — Widget is displayed with the Onramper integration ready. User sees fiat input options and supported currencies.
2. Loading / Connecting — While connecting wallet or initializing the Onramper widget.
3. Onramper Flow — User is interacting with the Onramper widget (selecting fiat currency, amount, payment method).
4. Transaction Pending — Stable token purchased on Celo; smart contract conversion to G$ in progress.
5. Success — G$ tokens received in user's wallet. Show confirmation with transaction details.
6. Error — Any failure in the flow (Onramper error, conversion failure, network error). Show actionable error message with retry option.
7. No Wallet — User doesn't have a connected wallet. Prompt wallet connection.

Flows

1. Buy G$ flow:
   • User connects wallet (if not connected)
   • User selects fiat currency and amount in Onramper widget
   • Onramper buys stable token (e.g., USDC/cUSD) on Celo into the user-owned smart contract
   • Smart contract converts stable token → G$
   • G$ is sent to user's wallet
   • Success confirmation displayed

Behaviors

• Wallet connection state should persist across widget re-renders
• Onramper widget should be embedded within the GoodWidget layout
• Transaction status should be polled/monitored and UI updated accordingly
• Errors should be user-friendly with retry options
• Responsive design for mobile and desktop

---

Execution Plan

Phase 1: Analysis & Setup

1. Map existing GoodWidget component architecture and patterns.
2. Review the referenced files from GoodProtocolUI, good-design, and web3-sdkv2.
3. Ensure @gooddollar/web3-sdkv2 is available as a dependency in GoodWidget.

Phase 2: Core Widget Implementation

4. Create the Buy G$ widget component structure:
   • BuyGDWidget — main widget container
   • Sub-components for each state (idle, loading, onramper, pending, success, error)
5. Integrate @gooddollar/web3-sdkv2 buy GD hooks (useBuyGD or equivalent from buygd/react.tsx).
6. Embed the Onramper widget within the GoodWidget layout, referencing the good-design onramp implementation.
7. Implement wallet connection handling within the widget.

Phase 3: UI Implementation

8. Implement the UI using GoodWidget reusable components, referencing GoodProtocolUI's BuyGD/index.tsx for layout and design patterns.
9. Create or adapt components as needed:
   • New in widget package: BuyGDWidget, state-specific sub-components, Onramper wrapper
   • Reusable (packages/ui): Any generic UI elements (e.g., transaction status banners, amount selectors) that could be useful across widgets should be added to the shared UI package
10. Ensure responsive and accessible design.

Phase 4: Transaction Flow

11. Implement transaction monitoring for the stable token purchase and G$ conversion.
12. Handle all states (pending, success, error) with appropriate UI feedback.
13. Implement retry logic for failed transactions.

Phase 5: Testing & Polish

14. Test all user flows and states.
15. Verify wallet connection scenarios (connected, not connected, wrong network).
16. Test error scenarios and edge cases.

---

Acceptance Criteria

• Buy G$ widget is implemented as a GoodWidget component
• Widget integrates Onramper for fiat-to-stable-token purchase on Celo
• Widget uses @gooddollar/web3-sdkv2 for the Buy G$ SDK functionality
• Smart contract conversion flow (stable token → G$ → user wallet) is handled
• All states are implemented (idle, loading, onramper, pending, success, error, no wallet)
• UI follows GoodWidget component patterns and references GoodProtocolUI/good-design
• Wallet connection is handled within the widget
• Error states show user-friendly messages with retry options
• Responsive design works on mobile and desktop
• No new redundant components — reusable elements are placed in the shared UI package

---

Human-Reviewer Checklist

• Verify the Onramper integration works correctly within the widget
• Confirm @gooddollar/web3-sdkv2 buy GD hooks are used correctly (not reimplemented)
• Check that the smart contract conversion flow (stable → G$) is properly handled
• Review all states have appropriate UI feedback
• Verify wallet connection edge cases (no wallet, wrong network, disconnected mid-flow)
• Ensure no logic is duplicated from good-design — imports are used where possible
• Confirm component placement decisions (widget-specific vs. shared UI package) are justified
• Review responsive design on multiple screen sizes
• Check accessibility compliance
• Verify error handling and retry flows
• Confirm the original issue Convert buy G$ to a goodwidget #94 content remains unchanged

[L03TJ3]

Hi! I’ve loaded the GoodWidget context and reviewed the planning sub-issue.

Per the repository workflow, I cannot start implementation while this issue is still marked [DRAFT]. Before I can open a PR and execute the plan, please:

1. Remove [DRAFT] from the issue title/description so it becomes [PLAN] Convert buy G$ to a GoodWidget.
2. Confirm the plan is finalized and ready for execution.
3. (Optional) Clarify any open questions, e.g.:
   • Which exact package name should the new widget use? (buy-gd-widget, buygd-widget, etc.)
   • Should the Onramper integration use a sandbox/test API key for Storybook/Playwright fixtures?
   • Are there specific contract addresses or environment overrides required for the Buy G$ flow on Celo Mainnet?

Once the [DRAFT] marker is removed, I’ll proceed with the implementation checklist from the plan. Thanks!

[L03TJ3]

Implementation is blocked on required runtime inputs that cannot be safely inferred:

1. The specified package @gooddollar/web3-sdkv2 is unpublished (npm 404). The referenced source package is @gooddollar/web3sdk-v2@0.4.44; please confirm this is the intended dependency.
2. Its useBuyGd hook requires a @usedapp/core DAppProvider, which GoodWidget does not currently provide. Adding that provider would create a new wallet/provider abstraction and needs approval for how it should coexist with the existing GoodWidgetProvider EIP-1193 flow.
3. Please provide the Onramper integration configuration contract: the host-provided public API-key property/name, sandbox versus production behavior for Storybook/Playwright, and the approved conversion trigger endpoint/transaction-monitoring contract. The reference implementation invokes a backend /verify/swaphelper endpoint, but no equivalent is defined in this repository.

I verified the referenced package version has no direct GitHub advisory. Once these inputs are confirmed, I can implement the widget without guessing any fund-moving integration behavior.