HydraOneHydraOneDevelopers
Core concepts

Message protocol

The message envelope, request and response correlation, and the message types exchanged with the host.

In embedded mode the game and the host shell talk over postMessage. You rarely touch the protocol directly because WalletBridgeClient wraps it, but it helps when you debug or build a host.

Envelope

Every message shares one envelope:

interface BridgeMessage<T = unknown> {
  id: string; // correlation ID (UUID when available)
  type: string; // for example 'GET_BALANCE'
  payload?: T;
  timestamp: number;
  source: 'hydra-client' | 'hydra-host';
}

Requests and responses

A request gets a unique id. The host answers with an RPC_RESPONSE (or RPC_ERROR) whose payload carries the same requestId. Responses are matched by ID, so concurrent requests cannot be mixed up, and a response for a request that has already timed out is discarded.

sequenceDiagram
    participant G as Game (WalletBridgeClient)
    participant H as Host shell

    G->>H: CLIENT_READY (id=1)
    H-->>G: HOST_ACK (requestId=1, hostInfo)
    Note over G: connectionState = connected
    G->>H: GET_BALANCE (id=2)
    H-->>G: RPC_RESPONSE (requestId=2, result)
    G->>H: SIGN_TX (id=3)
    Note over H: Host shows the wallet prompt
    H-->>G: RPC_RESPONSE (requestId=3, witness set)
    H-->>G: THEME_CHANGED / AUDIO_MUTED_CHANGED (push events)

Message types

GroupTypes
HandshakeCLIENT_READY, HOST_ACK, PING
Wallet queriesGET_USED_ADDRESSES, GET_UNUSED_ADDRESSES, GET_CHANGE_ADDRESS, GET_NETWORK_ID, GET_UTXOS, GET_BALANCE, GET_COLLATERAL
SigningSIGN_TX, SUBMIT_TX, SIGN_DATA
Host controlsSET_ORIENTATION, TRIGGER_HAPTIC, REQUEST_DEPOSIT_MODAL, GET_PLAYER_PROFILE
Push eventsAUDIO_MUTED_CHANGED, THEME_CHANGED, AUTH_STATE_CHANGED, NETWORK_CHANGED, ACCOUNT_CHANGED, DISCONNECTED
Host storageHOST_STORAGE_GET, HOST_STORAGE_SET, HOST_STORAGE_REMOVE, HOST_STORAGE_CLEAR
RepliesRPC_RESPONSE, RPC_ERROR

Next steps

  • Security model for how origins and sources are validated.
  • Errors for how RPC_ERROR maps to SDK error classes.

Connection lifecycle

How WalletBridgeClient picks a connection, connects with init() and releases it with destroy().

Security model

How the SDK validates origins and sources, limits waiting time and keeps keys and sessions safe.