Glyph Protocol in a nutshell

Glyph is a request-and-result protocol. The app describes an action, Glyph Wallet shows it to the user, and the app accepts the result only after checking its signature and bindings. Relay is an optional delivery path between the wallet and the app.

sequenceDiagram
  participant A as App
  participant R as Relay
  participant W as Wallet
  A->>R: Register a fresh session
  R-->>A: Return callback and read capabilities
  A->>W: Open the v2 request with callback capability
  W->>W: Validate and show the intent
  alt User approves
      W->>R: POST signed result
  else User rejects
      W->>R: POST signed rejection
  end
  R-->>A: Deliver result through read capability
  A->>A: Verify signature and bindings

1. The app creates an intent

The app creates a typed request describing the action, its origin, and the values the wallet needs to show. It wraps that request in a Protocol v2 envelope with delivery fields, a network binding, a nonce, an expiry, and a request_hash, then opens a glyph://v2/request?d=... URL for Glyph Wallet.

Keep the original request and envelope. The eventual result must be checked against what the app actually opened.

2. The wallet shows and decides

Glyph Wallet validates the request and asks the user to approve or reject it. An approval produces the requested result. A rejection is also a normal result with status: "rejected" and reason: "user_rejected".

The wallet performs the wallet action and signs the callback after the user's decision. The app does not become the signer.

3. Relay delivers through separated capabilities

Relay v2 is optional. For this path, the app creates a fresh, short-lived session before opening the wallet. Registration returns separate capabilities:

• The callback capability goes to the wallet so it can POST one result to Relay.
• The read capability stays with the app so it can read the result over SSE or polling.

These capabilities are not interchangeable. The wallet receives only the callback URL, and the app keeps the stream or result URL. Relay accepts the first callback for the session and rejects a later one.

4. The app verifies the bound result

Delivery is not trust. The app verifies the signed callback envelope against its saved request and expected bindings, including:

• request_hash, network, dApp origin, nonce, and expiry
• the expected callback and Relay binding, when Relay is used
• the canonical result_hash, trusted wallet key, and Qubic SchnorrQ signature

Only after verification should the app use the result. Then branch on its status. A user rejection, a transport failure, and a failed signature check are different outcomes.

What this does not do

• Relay is delivery only. It does not approve requests or replace app-side callback verification.
• Wallet keys and actions remain local to the wallet. Relay carries the callback; it is not the wallet signer.
• The app must verify. A result arriving through the expected URL is not enough. Check the signed envelope and its bindings before using the result.

For implementation details, see Understand Glyph Connect and Relay v2, Protocol v2 fields and bindings, and Use Relay v2.