Event-based Communication Between dApp and the Elsa Widget.

1

Architecture

• Widget (npm package)

  • React component integrated by the DApp.

  • Does not directly access wallets.

  • Sends generic wallet requests to the DApp.

• DApp (Host)

  • Integrates the widget package.

  • Has wallet provider logic (EVM, Solana, Bitcoin, Aptos, etc).

  • Listens for widget events and responds.

• MessageChannel

  • Dedicated communication channel between widget and DApp code.

2

Communication Flow

• DApp initializes MessageChannel

• DApp passes port to widget during initialization

• Widget sends request via MessagePort

• DApp handles request → performs wallet action

• DApp sends response back via MessagePort

3

Security Benefits

• Same-Origin Isolation: MessageChannel creates isolated communication ports that only work within the same origin/context.

• No Global Namespace Pollution: Unlike window.postMessage, MessageChannel doesn't expose communication to the global scope.

• Direct Port-to-Port Communication: Creates a private channel between two specific endpoints.

• Structured Cloning: Messages are safely cloned, preventing reference sharing vulnerabilities.

• Type-Safe Communication: Your implementation uses typed interfaces (WalletRequest, WalletResponse) for additional safety.