Protocol

Message envelope

Every message is a JSON-serializable object of the following shape:

interface Web3KitMessage {
  type: WEB3_KIT_MESSAGE_TYPES;
  payload: {
    connectionId: string;
    // ...event-specific fields
  };
}

See Message Contracts for the exact payload shape of each type.

connectionId

connectionId is a UUID generated by the iframe at mount time and sent to the host in WEB3_KIT_INIT. It is the canonical handle for this particular iframe instance:

• The host must echo it in every outgoing message (WEB3_KIT_GET_SIGNATURE_MSG, WEB3_KIT_AUTH_BY_WALLET).
• The iframe silently drops any inbound message whose payload.connectionId does not match the one it generated.
• Hosts embedding multiple iframes simultaneously must track and route by connectionId to avoid cross-talk.

If the host remounts the iframe, a new connectionId is generated. Do not reuse a stored one.

Directions

Direction	Message types
iframe → parent	WEB3_KIT_INIT, WEB3_KIT_SIGNATURE_MSG, WEB3_KIT_AUTH_DATA, WEB3_KIT_AUTH_FAILED
parent → iframe	WEB3_KIT_GET_SIGNATURE_MSG, WEB3_KIT_AUTH_BY_WALLET

Origin handling

• The iframe currently posts with targetOrigin: '*'. This will be tightened to a whitelist once allowed host origins are fixed.
• The host must filter inbound messages by event.origin === WEB3KIT_ORIGIN regardless of what the iframe sends.
• When the host posts to the iframe via iframeRef.current.contentWindow.postMessage(...), set the second argument to WEB3KIT_ORIGIN in production. '*' is acceptable only during local development.

Ordering

Within a single iframe lifetime the expected order is:

1. iframe → WEB3_KIT_INIT
2. parent → WEB3_KIT_GET_SIGNATURE_MSG
3. iframe → WEB3_KIT_SIGNATURE_MSG (or WEB3_KIT_AUTH_FAILED on signature-endpoint failure)
4. parent → WEB3_KIT_AUTH_BY_WALLET
5. iframe → WEB3_KIT_AUTH_DATA or WEB3_KIT_AUTH_FAILED

The host may repeat steps 2–5 within the same iframe instance if needed (for example, after a nonce expires).

Logging

When the auth-central app is built with appConfig.demo.available = true, both sides emit verbose console.log traces:

• Iframe side: prefix [web3-kit], with direction tag in / out.
• Reference host (DemoWeb3KitTestPage): prefix [web3-kit-demo], also tagged in / out.

In production builds (demo.available = false) all logging is a no-op.