Feature: Add Connect-A-Wallet Flow Support to Citizen SDK

[L03TJ3]

1. Summary

Build wallet-link support into @goodsdks/citizen-sdk so apps can connect/disconnect different wallets to a whitelisted root identity using typed SDK APIs, then consume it from @goodsdks/react-hooks and a minimal demo integration.

2. Desired behavior

• Add typed wallet-link methods to citizen SDK (no UI logic in SDK):
  • Connect account
  • Disconnect account
  • Resolve whitelist root
  • Check whether an address is connected (including per-chain status checks)
• Use latest local identity contract reference semantics from temp-examples/contract-latest.sol (IdentityV3):
  • connectAccount(address) is callable by a whitelisted root identity.
  • disconnectAccount(address) callable by root or connected account.
  • connectedAccounts(address) used for direct status lookup.
• Keep env/network behavior consistent with existing SDK patterns (development and production).
• Expose corresponding React hooks/wrappers following current sdk/loading/error conventions.
• Add new demo-widget flow to demonstrate new SDK APIs (minimal, non-production UI accepted).
• Include readme's with clear and straightforward examples
• Support native/custodial wallet flows where transaction signing can be handled internally (no explicit end-user signature step required in the default wallet UX).
• Add a default security messaging flow before connect/disconnect actions; wallet integrators may explicitly disable this messaging for a more non-intrusive flow.

3. Scope

In scope:

• packages/citizen-sdk
  • Add wallet-link API surface in SDK class/module(s)
  • Extend ABI/constants/types/barrel exports
  • Keep error handling aligned with current SDK style
• packages/react-hooks
  • Add/update hook wrappers for new wallet-link APIs
  • Export from existing barrels
• apps/demo-identity-app
  • Demonstrate connect/disconnect/status usage
• Tests/docs
  • Extend connected-account test coverage and update SDK docs/README references

4. Starting points

• packages/citizen-sdk/src/sdks/viem-identity-sdk.ts
• packages/citizen-sdk/src/constants.ts
• packages/citizen-sdk/src/types.ts
• packages/react-hooks/src/citizen-sdk/wagmi-identity-sdk.ts
• Reference-only:
  • IdentityV4
  • reference-assets/connect-a-wallet-example
  • Demo-App

5. Definition of Done + How to test

DoD:

• Citizen SDK exposes typed wallet-link API for connect/disconnect/root lookup/connected-status.
• ABI/constants include required wallet-link methods and align with IdentityV4 Contract semantics.
• Network config supports intended development and production behavior, including XDC production mapping if missing.
• React hooks expose wallet-link support using existing hook conventions.
• Public exports are available via package barrel files.
• Security consideration documented and implemented: end-user flow uses connectAccount/disconnectAccount only.
• Native/custodial wallet flow is supported without requiring explicit user signature prompts for transaction signing.
• A default security messaging flow exists for wallet-link actions, with a documented opt-out toggle that wallet integrators can disable.
• Tests cover at least one write-path + status/root resolution path.
• Docs updated for external integrators.
• Includes a demonstrable flow by extending the demo-identity-app with a new widget.

Verification commands:

• yarn workspace @goodsdks/citizen-sdk build
• yarn workspace @goodsdks/citizen-sdk test
• yarn workspace @goodsdks/citizen-sdk test:connected
• yarn workspace @goodsdks/react-hooks build
• yarn turbo run build --filter=apps/demo-identity-app
• yarn lint

Manual QA:

1. Connect a whitelisted root wallet in demo app.
2. Connect a secondary wallet using new SDK method.
3. Confirm on-chain root resolution for secondary wallet.
4. Verify connected-status checks (single-chain and per-chain read flow).
5. Disconnect and verify status/root behavior is updated correctly.

[romeoscript]

@L03TJ3 can i work on this ?

[iYukay]

I can work on this, kindly assign to me

[edehvictor]

@L03TJ3, please can I work on this?

[L03TJ3]

Hey @iYukay
you have any reference of previous work you did?

@edehvictor what would be your estimated timeline to deliver this?

[edehvictor]

@L03TJ3 8-12HRS from now

[iYukay]

@L03TJ3
I've worked on a few projects locally, can I share them or set up a repo?

[L03TJ3]

@edehvictor Okay, assigned

@iYukay Yes, please share something so that I can have a little bit of insight of having done some coding.
there will be more bounties available shortly on the bounties board

[iYukay]

Hi @L03TJ3, noticed I haven't been assigned to issues despite applying. Is there anything I can improve or tasks I can start with?

[L03TJ3]

@iYukay Its because of my previous question about wanting to have some insight. looking at your github profile there was not much reference so yes bounties did end up being assigned to contributors that already have done things.
I am in the process of adding new bounties, some of them should be more accessible for newer contributors.