Connect your wallet to a QRL dApp

What connecting a wallet means

When you click a dApp's connect button, the dApp asks your wallet which account it may use. The wallet shows you the request, and if you approve, the dApp learns your Q-address. From then on the dApp can send further requests: send a transaction, sign a message, sign structured typed data. Each one lands in your wallet as an approval prompt, and each one waits for your decision.

The dApp receives results only. For a transaction that means a transaction hash it can track on the chain, and for a signing request that means an ML-DSA-87 signature plus the matching public key. The keys that produce those signatures never leave the wallet. Read-only lookups such as your balance or the current block number are proxied through automatically and need no approval at all.

The two ways to connect on QRL 2.0

Browser extension.QRL browser extensions such as the MyQRLWallet Extension announce themselves to the page through the EIP-6963 discovery standard, so a dApp can show a picker listing every wallet it found. You click your extension, an approval popup opens, and once you approve the connection is live. Everything stays inside your browser on one machine. If no popup appears, click the extension's icon in the browser toolbar to bring the approval window up.

QR pairing. This route connects a dApp in one place to a wallet somewhere else, typically the MyQRLWallet mobile app on your phone. The dApp generates a one-timeqrlconnect:// URI and displays it as a QR code. You scan it with the mobile app and approve the pairing there. On a desktop the same code can instead open the web wallet at qrlwallet.comor the desktop app, and there is a copy-code fallback you can paste into the wallet's dApp connections screen. On a phone browser the dApp skips the QR entirely and deep-links straight into the app.

An encrypted pairing channel

QR pairing needs a relay server to carry messages between the dApp and the wallet, since the two run on different devices. Before any request flows, both sides perform a key exchange using ML-KEM-768, the NIST-standardized post-quantum key encapsulation mechanism (FIPS 203). Every message after that is encrypted with AES-256-GCM. The relay routes ciphertext it cannot read, and each QR code carries a fresh single-use pairing secret, so an old code cannot be replayed against a new session.

This matches the design philosophy of the chain itself: QRL 2.0 signs transactions with the post-quantum ML-DSA-87 scheme, and the connect protocol extends the same threat model to the wallet transport. The why post-quantum article covers the background.

Try it: pair a wallet with the demo dApp

The connect SDK ships with a demo dApp, and ZondScan hosts it live. It exercises the full flow: pairing, sending a transaction, post-quantum message signing, and read-only RPC calls.

1. Open the demo dApp

   Go to zondscan.com/dapp-example. If you want to send a test transaction later, fund your address first at the ZondScan faucet; the testnet Quanta guide shows how.

2. Pick MyQRLWallet in the wallet list

   The Connect Wallet card lists every wallet the page discovered. Installed extensions appear under their own names, and the entry named MyQRLWallet starts the QR pairing flow. Click it and a QR code appears, together with an Open web wallet button, an Open desktop app button, and a Copy connection code button.

3. Scan the code with your wallet

   Open MyQRLWallet on your phone, scan the QR code, and confirm the pairing when the app asks. On desktop you can instead click Open web wallet, or copy the code and paste it into the wallet's dApp connections screen. The demo's status line walks through connecting, waiting for the wallet, and exchanging keys.

4. Approve account access

   The wallet now shows a connection request naming the dApp. Approving it shares exactly one account. The demo switches to Connected and displays your Q-address under Connected Account.

5. Send a request and approve it in the wallet

   Try Sign Message: type any text, click the button, and approve the prompt that appears in your wallet. The demo verifies the returned ML-DSA-87 signature locally and prints the result. If you grabbed faucet funds, try Send Transaction with a small amount of Quanta, then look the hash up under recent transactions. The reading a transaction guide explains every field you will see.

Approving and rejecting requests

Only a small set of methods can reach your approval screen: account access, sending or signing a transaction, signing a message, signing typed data, and switching chains. Everything else is either a harmless read-only lookup or refused outright by the SDK before it leaves the page. A pairing authorizes exactly one account, and signing requests naming any other address fail locally.

Rejecting a request is always safe. The dApp receives an error, nothing is signed, and the connection itself stays alive for the next request. The mobile wallet additionally requires PIN or biometric authentication for every transaction, so an unattended phone cannot approve anything on its own.

Disconnecting from either side

Either party can end a session. In the demo dApp the Disconnect button retires the pairing, and a New Connection button rotates to a fresh QR code when you want to pair a different wallet. In the wallet, the dApp connections screen lists active connections and lets you disconnect any of them. The dApp is notified immediately; the demo responds by generating a fresh QR code so you can pair again.

Sessions are deliberately durable in between. A paired dApp can restore its session for up to seven days without a new scan, and putting the wallet app in the background does not break the pairing: the relay buffers an encrypted request for up to five minutes while the wallet is away, and on mobile an approval-needing request deep-links the wallet app back to the foreground.

For developers: the connect SDK

The protocol described above is an open-source TypeScript SDK, @qrlwallet/connect on npm. It exposes a standard EIP-1193 provider, so a dApp talks to a remote MyQRLWallet exactly the way it talks to an injected extension:

import { QRLConnect } from '@qrlwallet/connect';

const qrl = new QRLConnect({
  dappMetadata: {
    name: 'My QRL dApp',
    url: 'https://mydapp.com',
  },
});

// Render this URI as a QR code, or hand the provider to the
// @qrlwallet/connect-ui pairing modal instead.
const uri = await qrl.getConnectionURI();

// Standard EIP-1193 requests from here on.
const accounts = await qrl.request({ method: 'qrl_requestAccounts' });

A sibling package, @qrlwallet/connect-ui, provides a framework-free<qrl-pairing-modal> web component that handles the QR rendering, deep link, and copy-code fallback for you. Source, protocol documentation, and the demo dApp all live in the myqrlwallet-connect repository. The relay is self-hostable if you would rather run your own.

FAQ