Local testing and deployment

Use the starter-dapp repository as the canonical runnable test fixture. Its Glyph connector uses @glyph-oss/connect@4.0.1, @qubic.org/crypto@1.0.0 for dApp-side verification, Relay v2, explicit qubic:mainnet, and signed callback verification.

Run the starter locally

git clone https://github.com/glyphq/starter-dapp.git
cd starter-dapp
bun install
NEXT_PUBLIC_APP_ORIGIN=https://dev.example.org bun run dev

Replace https://dev.example.org with a public HTTPS origin you control. Open the local development URL printed by the app, but keep NEXT_PUBLIC_APP_ORIGIN set to that public origin. It must be an origin only, with no credentials, path, query, or fragment.

The SDK uses the configured origin for dApp identity and delivery validation. Do not use http://localhost as dapp.origin or as a direct callback URL. Relay v2 callbacks are the supported local-development path because the app can receive the result through its prepared Relay subscription.

Test the complete flow

Check these points in order:

1. The app reports Relay readiness before the connection control launches anything. If registration is still in progress, wait or use the retry action.
2. The request URL begins with glyph://v2/request?d=. Its decoded envelope uses glyph-connect-request/2 and network.id === "qubic:mainnet".
3. The click or tap that calls launchGlyphRequest() does not first await Relay or other network work.
4. The app starts subscribeViaRelayV2() with the prepared session and keeps the read capability in the dApp process.
5. The result is a signed glyph-connect-callback-envelope/2 response and passes strict verification before the UI uses it.
6. The wallet under test is Glyph Wallet v0.16.5.

If Relay registration or the result stream times out, keep the message actionable: explain that connection setup is not ready, retain the retry control, discard the consumed prepared session, and prepare a new one. A transient readiness failure is separate from a user's wallet approval decision.

Build for deployment

Set the exact public origin that will serve the app, then build:

NEXT_PUBLIC_APP_ORIGIN=https://app.example.org bun run build

The starter is configured for a static export. Deploy its generated out/ directory and serve it from the same public HTTPS origin configured in NEXT_PUBLIC_APP_ORIGIN. After deployment, repeat the connection test with Glyph Wallet v0.16.5 and confirm the generated v2 envelope still binds to qubic:mainnet.

Deployment checklist

• Pin @glyph-oss/connect to 4.0.1 and @qubic.org/crypto to 1.0.0.
• Use the official Relay v2 prepared-session API.
• Set NEXT_PUBLIC_APP_ORIGIN to the final credential-free HTTPS origin.
• Create glyph://v2/request envelopes with an explicit qubic:mainnet binding.
• Launch only from the user's direct activation.
• Require and verify signed callback envelopes with the expected request hash, network, dApp origin, expiry, and callback URL.
• Keep Relay capabilities out of logs, URLs, client-visible diagnostics, and source control.

Next steps

• Read the starter-dapp source.
• Review the @glyph-oss/connect package README for the full request and callback API.