Sequence diagram for WalletConnect connect flow with auto chain switching

[Dargon789]

Reviewer's Guide

This PR rebrands and significantly expands the Sequence Web SDK documentation and examples, upgrades dependencies, and refactors wallet/connector behavior (especially WalletConnect, WaaS, Immutable Passport, Trails integration, and the embedded wallet) while simplifying swap navigation and configuration across the monorepo.

Sequence diagram for WalletConnect connect flow with auto chain switching

sequenceDiagram
  participant App
  participant WagmiConfig
  participant WalletConnectConnector as WalletConnectConnector
  participant WalletConnectProvider as WalletConnectProvider

  App->>WagmiConfig: initiateConnect(targetChainId?)
  WagmiConfig->>WalletConnectConnector: connect({ chainId: targetChainId })

  activate WalletConnectConnector
  WalletConnectConnector->>WalletConnectConnector: determine targetChainId
  WalletConnectConnector->>WalletConnectProvider: connect(params)
  WalletConnectProvider-->>WalletConnectConnector: { accounts, chainId }

  alt result.chainId != targetChainId
    WalletConnectConnector->>WalletConnectProvider: switchChain({ chainId: targetChainId })
    WalletConnectProvider-->>WalletConnectConnector: switched
    WalletConnectConnector-->>WagmiConfig: { accounts, chainId: targetChainId }
  else result.chainId == targetChainId
    WalletConnectConnector-->>WagmiConfig: { accounts, chainId }
  end

  deactivate WalletConnectConnector
  WagmiConfig-->>App: connectionResult

Loading

Class diagram for updated connect configuration and wallet types

classDiagram
  class WalletType {
    <<type>>
    waas
    universal
  }

  class ConnectConfig {
    projectAccessKey: string
    waasConfigKey: string?
    disableAnalytics: boolean?
    defaultTheme: Theme?
    position: ModalPosition?
    signIn: SignInConfig?
    hideWalletsList: boolean?
    hideSocialConnectOptions: boolean?
    hideConnectedWallets: boolean?
    customCSS: string?
    trailsCustomCSS: string | TrailsThemeCSS?
    embeddedWalletTitle: string?
    renderInline: boolean?
    onConnectSuccess(address: string): void
  }

  class SignInConfig {
    logoUrl: string?
    showWalletAuthOptionsFirst: boolean?
    descriptiveSocials: boolean?
    disableTooltipForDescriptiveSocials: boolean?
    projectName: string?
    useMock: boolean?
  }

  class TrailsThemeCSS {
    light: string?
    dark: string?
  }

  class CreateConfigOptions {
    appName: string
    projectAccessKey: string
    chainIds: number[]?
    defaultChainId: number?
    disableAnalytics: boolean?
    defaultTheme: Theme?
    position: ModalPosition?
    customCSS: string?
    trailsCustomCSS: string | TrailsThemeCSS?
    signIn: SignInConfig?
    displayedAssets: DisplayedAsset[]?
    ethAuth: EthAuthSettings?
    onConnectSuccess(address: string): void
    wagmiConfig: WagmiConfig?
    waasConfigKey: string
    enableConfirmationModal: boolean?
    walletConnect: boolean | WalletConnectSettings?
    guest: boolean?
    google: boolean | GoogleSettings?
    apple: boolean | AppleSettings?
    X: boolean | XSettings?
    email: boolean | EmailSettings?
  }

  class DisplayedAsset {
    contractAddress: string
    chainId: number
  }

  class WalletConnectSettings {
    projectId: string
  }

  class GoogleSettings {
    clientId: string
  }

  class AppleSettings {
    clientId: string
    redirectURI: string
  }

  class XSettings {
    clientId: string
    redirectURI: string
  }

  class EmailSettings {
    legacyEmailAuth: boolean?
  }

  WalletType <.. CreateConfigOptions
  ConnectConfig o-- SignInConfig
  ConnectConfig o-- TrailsThemeCSS
  CreateConfigOptions o-- SignInConfig
  CreateConfigOptions o-- DisplayedAsset
  CreateConfigOptions o-- WalletConnectSettings
  CreateConfigOptions o-- GoogleSettings
  CreateConfigOptions o-- AppleSettings
  CreateConfigOptions o-- XSettings
  CreateConfigOptions o-- EmailSettings

Loading

Class diagram for updated WaaS and Immutable wagmi connectors

classDiagram
  class SequenceWaasProvider {
    +sequenceWaas: SequenceWaasClient
    +getChainId(): string | number
    +request(args: ProviderRequest): Promise~unknown~
  }

  class SequenceWaasClient {
    +isSignedIn(): Promise~boolean~
    +getSessionId(): Promise~string~
    +dropSession(options: DropSessionOptions): Promise~void~
  }

  class SequenceWaasConnector {
    +connect(options: ConnectOptions): Promise~ConnectResult~
    +disconnect(): Promise~void~
    +getAccounts(): Promise~string[]~
    +isAuthorized(): Promise~boolean~
    +switchChain(chain: SwitchChainParams): Promise~Chain~
    +getChainId(): Promise~number~
    +getProvider(): Promise~SequenceWaasProvider~
  }

  class ImmutableConnector {
    +connect(options: ConnectOptions): Promise~ConnectResult~
    +disconnect(): Promise~void~
    +getAccounts(): Promise~string[]~
    +switchChain(chain: SwitchChainParams): Promise~Chain~
    +getChainId(): Promise~number~
  }

  class ImmutablePassportInstance {
    +connectEvm(options: ConnectEvmOptions): Promise~Eip1193Provider~
  }

  class ConnectOptions {
    withCapabilities: boolean?
    chainId: number?
  }

  class ConnectAccountWithCapabilities {
    address: string
    capabilities: object
  }

  class ConnectResult {
    accounts: string[] | ConnectAccountWithCapabilities[]
    chainId: number
  }

  SequenceWaasConnector --> SequenceWaasProvider
  SequenceWaasProvider --> SequenceWaasClient
  ImmutableConnector --> ImmutablePassportInstance
  SequenceWaasConnector ..> ConnectOptions
  ImmutableConnector ..> ConnectOptions
  SequenceWaasConnector ..> ConnectResult
  ImmutableConnector ..> ConnectResult
  ConnectResult o-- ConnectAccountWithCapabilities

Loading

File-Level Changes

Change	Details	Files
Rewrite and expand top-level and connect package documentation to describe the new Sequence Web SDK, configuration API, and usage patterns.	Replace root README with a comprehensive overview, quick start, configuration options, hooks, and examples for the Sequence Web SDK. Rewrite @0xsequence/connect README to focus on the new createConfig API, WaaS/universal modes, X auth callback, wagmi integration, and sign-in modal usage. Add detailed examples for customizing providers, inline rendering, and modal invocation in the docs.	README.md packages/connect/README.md
Refactor the React example configuration to use the new connect.createConfig API, walletType switch, Immutable passport integration, and checkout configuration.	Replace old kit/kit-connectors based config with @0xsequence/connect createConfig using WalletType and ConnectConfig. Wire in Immutable passport via @0xsequence/immutable-connector with environment-dependent WaaS/universal configs. Introduce checkoutConfig and helper to build ERC1155 sale contract config; centralize environment URLs and sponsored contract addresses. Update example dependencies to newer wagmi/viem and remove unused dapp-client/ox packages.	examples/react/src/config.ts examples/react/package.json
Simplify and modernize the wallet widget by removing internal swap context, wiring new Swap/Buy views, and adjusting navigation and headers.	Remove SwapProvider, swap context, SwapCoin views/hooks, and related navigation routes and analytics events. Add new Swap and Buy views, route them from HomeHeader operation menu, CoinDetails, and SequenceWalletProvider content selection. Update GeneralList to drop swap variant, rely only on send/default, and simplify token fetching/filters accordingly. Adjust wallet modal rendering to not depend on add-funds modal and keep children rendering intact.	packages/wallet-widget/src/components/SequenceWalletProvider/SequenceWalletProvider.tsx packages/wallet-widget/src/components/SequenceWalletProvider/utils/index.tsx packages/wallet-widget/src/views/index.ts packages/wallet-widget/src/components/SearchLists/GeneralList.tsx packages/wallet-widget/src/components/NavigationHeader/content/HomeHeader.tsx packages/wallet-widget/src/views/CoinDetails/index.tsx packages/wallet-widget/src/constants/analytics.ts packages/wallet-widget/src/contexts/Navigation.ts packages/wallet-widget/src/hooks/index.ts packages/wallet-widget/src/views/Swap/Swap.js packages/wallet-widget/src/views/Buy/index.tsx
Introduce Trails customization support and dark-theme alignment for swap widget styling, and expose related configuration in connect and hooks.	Extend ConnectConfig with trailsCustomCSS and embeddedWalletTitle/renderInline/onConnectSuccess flags. Add Trails-specific env fields to hooks SequenceHooksEnv (nodeGatewayUrl, trailsApiUrl) and a default mapping. Add wallet-widget TRAILS_CUSTOM_CSS constants for dark mode alignment and light-mode overrides, used to theme the Trails widget. Include 0xtrails dependency and bump viem/wagmi peer ranges for wallet-widget.	packages/connect/src/types.ts packages/hooks/src/contexts/ConfigContext.tsx packages/wallet-widget/src/views/Swap/consts.ts packages/wallet-widget/package.json
Harden and improve connector behavior for WalletConnect, Sequence WaaS, and Immutable Passport to support wagmi capabilities-aware connect().	Wrap walletConnect connector to pass through params to base connector.connect and perform chain switching only when needed. Update sequenceWaasWallet connector to accept withCapabilities, cast provider type, and return accounts with capabilities when requested; consistently type provider in helper methods. Update immutableConnector wagmi connector to support withCapabilities and return accounts in capabilities format when requested.	packages/connect/src/connectors/walletConnect/walletConnect.ts packages/connect/src/connectors/wagmiConnectors/sequenceWaasConnector.ts packages/immutable-connector/src/wagmiConnector/index.ts
General styling and infrastructure updates across connect, wallet-widget, checkout, hooks, examples, and CI.	Adjust internal Tailwind-based styles (colors, spacing, border utilities, transitions, shadows, animations) for improved theming and layout; add overflow/rounded/height classes where needed. Upgrade checkout, connect, wallet-widget, hooks, immutable-connector, examples, and root package.json to newer versions of viem, wagmi, marketplace, next, etc., and expose src files in published packages while excluding tests. Secure random device name generation in SocialLink by switching from Math.random to crypto.getRandomValues. Update Next example README and root README examples; change copyrights and authorship to Sequence Platforms ULC; tweak CI and remove unused CircleCI config and some example scripts.	packages/connect/src/styles.ts packages/checkout/package.json packages/connect/package.json packages/wallet-widget/package.json packages/hooks/package.json packages/immutable-connector/package.json examples/components/package.json examples/next/package.json examples/nextjs-pages/package.json package.json packages/connect/src/components/SocialLink/SocialLink.tsx examples/components/src/Header.tsx examples/next/README.md examples/react/README.md .github/workflows/test.yml .circleci/config.yml CNAME LICENSE

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

Originally posted by @sourcery-ai[bot] in #338 (comment)