Envelopes and URLs

A request becomes launchable only after it is wrapped in a v2 envelope. createEnvelope() validates delivery URLs and the network binding, then computes the request hash.

Envelope shape

interface GlyphEnvelope {
  protocol: "glyph-connect-request/2";
  request: GlyphRequest;
  callback: string | null;
  redirect_uri: string | null;
  network: GlyphNetworkBinding;
  request_hash: string;
}

type GlyphNetworkId =
  | "qubic:mainnet"
  | "qubic:testnet"
  | `qubic:custom:sha256:${string}`;

interface GlyphNetworkBinding {
  id: GlyphNetworkId;
}

callback and redirect_uri are always normalized to either a string or null in the returned envelope. The default network is GLYPH_MAINNET.

Create and encode an envelope

import {
  GLYPH_MAINNET,
  buildGlyphUrl,
  createEnvelope,
  encodeEnvelope,
} from "@glyph-oss/connect";

const envelope = createEnvelope(request, {
  callback: "https://example.app/api/glyph/callback",
  network: GLYPH_MAINNET,
});

const encoded = encodeEnvelope(envelope);
const url = buildGlyphUrl(envelope);
// glyph://v2/request?d=<base64url-encoded-envelope>

createEnvelope() also accepts redirect_uri. A callback must be HTTPS, credential-free, globally reachable, and match dapp.origin, except for the official Relay v2 callback URL. A redirect URI must be HTTPS, credential-free, globally reachable, and match dapp.origin. Relay stream and result URLs are not delivery URLs.

encodeEnvelope() revalidates the envelope and throws if the base64url payload exceeds 8192 bytes. buildGlyphUrl() places that payload in the d query parameter and uses the glyph://v2/request prefix.

Request hash

The SDK hashes this exact object, excluding request_hash:

const hashInput = {
  protocol: envelope.protocol,
  request: envelope.request,
  callback: envelope.callback ?? null,
  redirect_uri: envelope.redirect_uri ?? null,
  network: envelope.network,
};

requestHashInput() returns the normalized object. computeRequestHash() canonicalizes it with the SDK's RFC 8785-compatible JSON routine and returns a sha256:<base64url digest> string.

import {
  computeRequestHash,
  requestHashInput,
} from "@glyph-oss/connect";

const input = requestHashInput(envelope);
const expectedHash = computeRequestHash(envelope);

The wallet recomputes this binding before accepting the request. Changing the request, callback, redirect URI, or network changes the hash.

Custom network bindings

For a custom RPC description, use createCustomNetworkBinding() instead of constructing a hash string yourself:

import {
  createCustomNetworkBinding,
  createEnvelope,
} from "@glyph-oss/connect";

const network = createCustomNetworkBinding({
  rpcUrl: "https://rpc.example",
  chain: "example",
});

const envelope = createEnvelope(request, { network });

The resulting ID is qubic:custom:sha256:<base64url-hash>. The hash is computed from the canonical JSON representation of the RPC object. Every participant must use the same object and canonicalization.

Launch helpers

• openGlyphUrl(url) clicks a hidden anchor and requires a browser window.
• launchGlyphRequest(envelope) builds, opens, and returns the URL.
• glyphRequest(request, options) creates a redirect envelope, opens the wallet, and resolves after the callback route broadcasts the result.
• handleRedirect(options) reads ?result=<base64url JSON> at the callback route and broadcasts a validated result to the waiting request.

For secure callbacks, configure handleRedirect() with verification options or let glyphRequest() enforce signed v2 verification when it receives the broadcast. See strict callback verification.