1) Summary

GoodSDKs currently lacks a dedicated reserve SDK for buying and selling G$ through the main reserve using modern viem patterns. Contributors should add a new @goodsdks/good-reserve package with typed read/write APIs for reserve discovery, quotes, fees, approvals, swaps, and transaction history decoding. The old integration in GoodWeb3-Mono/packages/sdk-v2/src/sdk/reserve is a behavior reference only; implementation must avoid useDapp/ethers patterns and match GoodSDKs conventions for local ABIs and local contract addresses. The solution should also expose React hook wrappers in @goodsdks/react-hooks and include a minimal demo integration in an existing app. This improves developer adoption by making reserve interactions consistent with other GoodSDKs packages and easier to integrate safely.

2) Desired behavior (acceptance criteria)

• Integrators can query reserve market data needed for UX flows: available exchange(s), reserve asset details, and quote/fee values for buy/sell decisions.
• Integrators can complete both buy and sell flows end-to-end, including approval when required, and receive deterministic success/error results.
• Integrators can retrieve decoded reserve transaction history/events in a UI-ready shape (direction, token in/out, amounts, tx/hash context).
• React apps can consume reserve functionality through a simple hook-based integration pattern aligned with existing GoodSDKs hooks.
• A demo app (create a new demo-reserve-swap) proves the full user journey: quote -> approve if needed -> buy/sell -> decoded transaction result display.
• Should suppport all chains we have deployed a reserve (at the moment, Celo and XDC)

3) Scope (in / out)

In scope

• Create packages/good-reserve workspace with local ABIs, local env address maps, and typed viem SDK APIs.
• Add reserve hook wrappers and barrel exports in packages/react-hooks.
• Add one minimal demo integration in an existing app under apps/.
• Add/extend tests and docs for external integrators.
• Pin ABI source snapshot reference (branch/commit) in docs or package notes.

Out scope

• Now UI component is requested beyond a simple demo-app

4) Starting points (top paths + notes)

• packages/citizen-sdk/src/constants.ts — canonical local ABI + env address map pattern.
• packages/savings-sdk/src/viem-sdk.ts — allowance/approve/write viem transaction flow pattern.
• packages/engagement-sdk/src/viem-sdk.ts — event/log fetching and typed decode usage pattern.
• packages/engagement-sdk/src/utils/rpc.ts — block-batch RPC fetching utility pattern for history scans.
• packages/react-hooks/src/citizen-sdk/wagmi-identity-sdk.ts — hook wrapper shape and initialization lifecycle.
• /home/lewisb/active_repos/GoodWeb3-Mono/packages/sdk-v2/src/sdk/reserve/react.tsx — behavior reference for reserve quotes/swap flow (not architecture reference).
• https://github.com/GoodDollar/GoodProtocol/blob/master/releases/deployment.json — source for production/development reserve contract addresses.
• https://github.com/GoodDollar/mento-core — source for canonical ABI/events used for local definitions.

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

DoD

• @goodsdks/good-reserve workspace builds and exports public typed APIs from src/index.ts.
• Local ABI definitions and local production/development contract-address maps are implemented from approved sources. (in line with similar structure already existing in our other sdks's)
• Public API/docs explicitly pin the ABI/address source references used for the implementation.
• React hook wrapper(s) are added to @goodsdks/react-hooks and exported through package barrels.
• One existing demo app includes a minimal reserve integration flow and is buildable.
• Validation and safety guards exist for invalid amounts, chain/env mismatches, and execution constraints.
• Tests or reproducible verification steps cover buy/sell execution and history/event decoding paths.
• Lint, type-check, and affected workspace builds pass.
• included readmes

How to test

# repo-native commands
yarn install --immutable
yarn workspace @goodsdks/good-reserve build
yarn workspace @goodsdks/react-hooks build
yarn turbo run build --filter=apps/demo-swap-reserve
yarn lint
yarn tsc --noEmit