Refactor: support connected accounts for claiming flow

[L03TJ3]

Motivation

Users can connect other wallets to their main whitelisted wallet.
effectively, this allows a connected wallet to claim on behalf of the main whitelisted wallet.

We cannot rely on isWhitelisted for a connected account because it will return false.
We need to fix the flow so that claiming is available to connected accounts as well.
getWhitelistedRoot is already used in the sdks, what is not properly done is verifying 'checkEntitlement'

Details

• Review the flows that rely on claiming and identity sdk and make sure getWhitelistedRoot is properly handled.
  returns 0x0 = not connected and not whitelisted
  returns input address = is whitelisted and input address is the main whitelisted account
  returns a different wallet address then input adddress = connected account.

• Update flows that use checkEntitlement. checkEntitlement check should not be done against the connected address but against the address returned from .getWhitelistedRoot

Possible affected areas to be reviewed

Claim Flow Refactor – Impact Summary & Tasks

What the code currently does (confirming the whitelist check)

• The claim flow uses IdentitySDK.getWhitelistedRoot (which calls the IdentityV2 getWhitelistedRoot contract method) to determine whitelist status.
• There is no usage of a contract.isWhitelisted(...) method in this repo.

Sections that will be affected by a refactor

Core SDK (claim + identity)

• packages/citizen-sdk/src/sdks/viem-identity-sdk.ts
  • getWhitelistedRoot(...) is the sole whitelist check used by the claim flow.
• packages/citizen-sdk/src/sdks/viem-claim-sdk.ts
  • getWalletClaimStatus() and claim() call identitySDK.getWhitelistedRoot(...).
  • checkEntitlement(...) defines how entitlements are resolved and how fallback chains are suggested.
  • nextClaimTime() depends on the entitlement flow.
• packages/citizen-sdk/src/constants.ts
  • Identity ABI (includes getWhitelistedRoot) and UBI ABI (checkEntitlement) live here.
• packages/citizen-sdk/src/types.ts
  • WalletClaimStatus shape is referenced by SDKs; may need changes if statuses or flow semantics change.
• packages/citizen-sdk/src/sdks/viem-custodial-claim-sdk.ts
  • Extends ClaimSDK, so any interface or behavior change in ClaimSDK affects this class.

UI / App integrations

• packages/ui-components/src/ClaimButton.ts
  • Calls checkEntitlement() and nextClaimTime().
  • Uses altClaimAvailable / altChainId for suggested chain switching.
  • Calls claim() and handles success / timer states based on entitlement results.
• packages/react-hooks/src/citizen-sdk/wagmi-claim-sdk.ts
  • Builds ClaimSDK (depends on identity flow being compatible).
• apps/demo-identity-app/src/components/ClaimButton.tsx
  • Uses checkEntitlement() and claim() directly; displays alternative chain hints.
• apps/demo-identity-app/src/App.tsx
  • Uses identitySDK.getWhitelistedRoot(...) to set verified / whitelisted UI states.

Docs / Guidance

• packages/citizen-sdk/README.md
  • Shows getWhitelistedRoot(...) and explains the whitelist check.
• packages/citizen-sdk/README-ClaimSDK.md
  • Flow diagram and text reference IdentitySDK.getWhitelistedRoot + checkEntitlement.
• packages/react-hooks/README.md
  • Describes claim usage and mentions getWhitelistedRoot.
• packages/ui-components/README.md
  • Explains claim-button behavior; may need updates if flow logic changes.

Built outputs (regenerate after refactor)

• packages/ui-components/iife/claim-button.index.js
  • Generated bundle; should be rebuilt, not edited by hand, if claim flow behavior changes.

Refactor tasks (high level)

1. Confirm the intended whitelist method

   • Decide whether we keep getWhitelistedRoot (current) or switch to a new isWhitelisted call.
   • If switching, update Identity ABI and SDK methods accordingly.

2. Adjust ClaimSDK flow

   • Update getWalletClaimStatus() and claim() to match new whitelist semantics.
   • Update checkEntitlement() if entitlement logic or fallback strategy changes.
   • Reconcile any return shape changes with WalletClaimStatus and UI usage.

3. Update UI state machine assumptions

   • Update ClaimButton (web component + demo app) to align with new status outputs and entitlement logic.
   • Revisit alt-chain suggestions if fallback logic changes.

4. Update React hooks behavior if needed

   • Ensure useClaimSDK handles any new init requirements and preserves error/loading behavior.

5. Docs and examples

   • Update README flow diagrams and example snippets to reflect the new whitelist and entitlement steps.

6. Validation

   • Manually exercise the demo claim flow (or add tests) to confirm:
     • whitelist/identity gating works
     • entitlement calculation matches expectations
     • fallback chain suggestion is accurate
     • claim + faucet behavior still matches product expectations

[Heisenburgirs]

I'd like to work on the issue.

I'll get on it as soon as it's assigned

[Ryjen1]

I will like to work on this

[HushLuxe]

Assign this issue to me, let me handle it

[L03TJ3]

We let scouts do one PR at a time
@Heisenburgirs , you already are working on the claim disabled PR
@Ryjen1 you are assigned now

[L03TJ3]

We let scouts do one PR at a time
@Heisenburgirs , you already are working on the claim disabled PR
@Ryjen1 you are assigned now