Wallet Gateway

Wallet Gateway Remote

The remote wallet gateway has a backend (nodejs+express) and a user management frontend (web components). The frontend, aka User UI, is opened as a separate browser popup window when used with a 3rd-party dApp.

Window Communication

The User UI and dApp UI, once connected, send window message events to each other to share session state, provide user interaction updates, and so on.

sequenceDiagram
    autonumber

    participant D as Dapp UI<br/>(Browser, Origin A)
    participant WG as WG UI<br/>(Browser, Origin B)
    participant SM as stateManager<br/>(WG UI)
    participant LS_D as Dapp localStorage
    participant LS_WG as WG localStorage
    participant SS_WG as WG sessionStorage

    Note over D,WG: Dapp UI and WG UI run on separate origins
    Note over D,WG: The same model can support multiple dapps with independent sessions

    D->>WG: Open WG UI popup
    D->>WG: window.postMessage({ dappOrigin })
    WG-->>D: postMessage acknowledgement

    rect rgb(238, 242, 255)
        Note over D,SS_WG: Login (fresh)
        D->>LS_D: Read dapp session state
        LS_D-->>D: No existing session
        WG->>SM: Read session and auth state
        SM->>LS_WG: Read persistent state
        LS_WG-->>SM: No existing session
        SM->>SS_WG: Read popup session state
        SS_WG-->>SM: No existing session
        SM-->>WG: No existing session
        WG-->>D: Show login
        D->>WG: Submit login
        WG->>SM: Store authenticated session
        SM->>LS_WG: Write session state
        SM->>SS_WG: Write active popup state
        WG-->>D: Login successful
        D->>LS_D: Store dapp session metadata
    end

    rect rgb(240, 253, 250)
        Note over D,SS_WG: Login (existing session)
        D->>LS_D: Read dapp session metadata
        LS_D-->>D: Existing session reference
        D->>WG: Request session status
        WG->>SM: Read session state
        SM->>LS_WG: Read persistent state
        LS_WG-->>SM: Authenticated session
        SM-->>WG: Existing authenticated session
        WG-->>D: Login restored
    end

    rect rgb(255, 247, 237)
        Note over D,SS_WG: Connect
        D->>WG: Request wallet connection
        WG->>SM: Read connection state
        SM->>SS_WG: Read active connection state
        SS_WG-->>SM: Disconnected
        SM-->>WG: Disconnected
        WG->>SM: Store connected state
        SM->>SS_WG: Write connection state
        WG-->>D: Connected
        D->>LS_D: Store connection metadata
    end

    rect rgb(240, 249, 255)
        Note over D,SS_WG: Refresh initiated from the dapp UI
        D->>WG: Open or reuse WG popup
        D->>WG: window.postMessage({ dappOrigin })
        WG-->>D: postMessage acknowledgement
        WG->>SM: Restore state
        SM->>LS_WG: Read persistent state
        LS_WG-->>SM: Session and auth state
        SM->>SS_WG: Read popup session state
        SS_WG-->>SM: Connection state
        SM-->>WG: Restored state
        WG-->>D: Current session and connection status
    end

    rect rgb(253, 244, 255)
        Note over D,SS_WG: Disconnect
        D->>WG: Request wallet disconnect
        WG->>SM: Clear connection state
        SM->>SS_WG: Remove connection state
        WG-->>D: Disconnected
        D->>LS_D: Remove connection metadata
    end

    rect rgb(255, 241, 242)
        Note over D,SS_WG: Logout
        D->>WG: Request logout
        WG->>SM: Clear authentication state
        SM->>LS_WG: Remove persistent auth state
        SM->>SS_WG: Remove active session state
        WG-->>D: Logged out
        D->>LS_D: Remove dapp session metadata
    end

    rect rgb(254, 252, 232)
        Note over D,SS_WG: Token expiry
        WG->>SM: Detect expired token
        SM->>LS_WG: Remove expired auth state
        SM->>SS_WG: Remove active auth state
        SM-->>WG: Session unauthenticated
        WG-->>D: Notify token expiry
        D->>LS_D: Clear stale session metadata
        D-->>WG: Treat session as logged out
    end

Loading

Login (fresh)

sequenceDiagram
    autonumber

    participant D as Dapp UI<br/>(Browser, Origin A)
    participant WG as WG UI<br/>(Browser, Origin B)
    participant SM as stateManager<br/>(WG UI)
    participant LS_D as Dapp localStorage
    participant LS_WG as WG localStorage
    participant SS_WG as WG sessionStorage

    Note over D,WG: Dapp UI and WG UI run on separate origins
    Note over D,WG: The same model can support multiple dapps with independent sessions

    D->>WG: Open WG UI popup
    D->>WG: window.postMessage({ dappOrigin })
    WG-->>D: postMessage acknowledgement

    rect        
        Note over D,SS_WG: Login (fresh)
        D->>LS_D: Read dapp session state
        LS_D-->>D: No existing session
        WG->>SM: Read session and auth state
        SM->>LS_WG: Read persistent state
        LS_WG-->>SM: No existing session
        SM->>SS_WG: Read popup session state
        SS_WG-->>SM: No existing session
        SM-->>WG: No existing session
        WG-->>D: Show login
        D->>WG: Submit login
        WG->>SM: Store authenticated session
        SM->>LS_WG: Write session state
        SM->>SS_WG: Write active popup state
        WG-->>D: Login successful
        D->>LS_D: Store dapp session metadata
    end

Loading

Login (existing session)

dApp Connect

dApp Browser Refresh

dApp Disconnect

Logout