RADIX WikiRADIX Wiki

What is ROLA?

ROLA (Radix Off-Ledger Authentication) is a challenge-response protocol that lets your backend verify a user owns a Radix account or persona – without submitting any on-ledger transaction. It's the Radix equivalent of "Sign-In with Ethereum" but uses the native Radix Wallet.

How It Works

  1. Backend generates a challenge – a random 32-byte hex string stored with a 5-minute expiry
  2. Frontend requests proof – asks the Radix Wallet for accounts or a persona with proof, and the toolkit attaches the challenge it gets from the generator you registered
  3. User approves in wallet – the wallet does not sign the bare challenge. It signs a blake2b hash of the byte R, the challenge, the length and text of your dApp definition address, and your website's origin, using the key behind each account or persona (Ed25519 or secp256k1). Binding the origin and dApp definition is what stops a proof captured on one site from logging anyone into another
  4. Frontend sends proof to backend – the address, its type (account or persona), the challenge, and the public key, signature and curve
  5. Backend verifies – verifySignedChallenge rebuilds the same hash from the expectedOrigin and dAppDefinitionAddress you configured, checks the signature, then asks the Gateway for the address's owner_keys metadata. That metadata holds hashes of public keys, so the check is that the hash of the presented key is among them. If the address has no owner_keys yet, which is the case for an account or persona that has never been touched on ledger, it passes only when the address is the one derived from the public key itself
  6. Your code deletes the challenge – the package checks neither expiry nor reuse, and it never sees your challenge store. Look the challenge up, reject it if expired, and delete it before or as you call verifySignedChallenge

Implementation

1. Generate Challenges (Backend)

import crypto from 'crypto'
 
// Store challenges with expiry (use Redis, DB, or in-memory Map)
const challenges = new Map<string, { expires: number }>()
 
function createChallenge(): string {
  const challenge = crypto.randomBytes(32).toString('hex')
  challenges.set(challenge, {
    expires: Date.now() + 5 * 60 * 1000  // 5 minutes
  })
  return challenge
}

2. Request Proof (Frontend)

The challenge is never passed to the request builder. You give the Radix dApp Toolkit a generator function, and the toolkit calls that function itself each time it sends a request. withProof() is a flag on the builder, not a place to put the challenge.

import { DataRequestBuilder } from '@radixdlt/radix-dapp-toolkit'
 
// RDT calls this once per request and attaches the result to it
rdt.walletApi.provideChallengeGenerator(async () => {
  const res = await fetch('/api/auth/challenge')
  return (await res.json()).challenge
})
 
// withProof() takes an optional boolean, never the challenge string
rdt.walletApi.setRequestData(
  DataRequestBuilder.accounts().atLeast(1).withProof(),
)
 
const result = await rdt.walletApi.sendRequest()   // takes no arguments
 
if (result.isOk()) {
  const { proofs } = result.value   // one signed challenge per shared account or persona
}

Two things here are easy to get wrong. walletApi.sendRequest() accepts no arguments: the builders go to setRequestData() first, or to sendOneTimeRequest(...) if you do not want the request stored for later connections. And every entry in result.value.proofs already has the shape { address, type, challenge, proof }, which is exactly the argument verifySignedChallenge expects in the next step, so you can pass one straight through without rebuilding it. The curve field is the string 'curve25519' or 'secp256k1', so do not test it against 'ed25519' even though Ed25519 is the signature scheme.

Proving a persona instead

For a login, a persona is often the better thing to prove: it is the identity the user chose to show your dApp, and it stays the same when they share a different set of accounts next time. The builder is DataRequestBuilder.persona().withProof(), and the entry it adds to proofs carries type: 'persona' and the persona's identity_rdx1… address, which verifySignedChallenge handles with no other change.

rdt.walletApi.setRequestData(
  DataRequestBuilder.persona().withProof(),
  DataRequestBuilder.accounts().atLeast(1).withProof(),
)

To re-prove addresses the user has already shared, without asking them to pick again, the one-time builder has OneTimeDataRequestBuilder.proofOfOwnership().identity(identityAddress).accounts([accountAddress]), sent with sendOneTimeRequest(...).

3. Verify Proof (Backend)

import {

Delete used challenges

Always delete a challenge after verification – successful or not. verifySignedChallenge does not do it for you: it has no access to your store, so without this step a captured proof can be resubmitted for as long as the challenge exists.

When to Use ROLA

Use CaseAuth Method
User login / session creationROLA
Prove account ownership to backendROLA
Transfer assets or call componentsOn-ledger transaction
Gate content by badge ownershipROLA + Gateway query

ROLA proves identity. On-ledger transactions perform actions. For token-gated access, verify ownership via ROLA then query the account's resources via the Gateway SDK.

Reference Implementation and Maintenance Status (checked October 2026)

ROLA works, and it is still the right way to log a user in. But every official piece around it has stopped receiving updates, and one of them is archived, so check the source before you copy code out of a Radix repository.

  • The examples repository is archived. radixdlt/rola-examples is marked archived on GitHub and its most recent commit is dated 8 September 2023. It pins @radixdlt/radix-dapp-toolkit at 0.5.1 and sets networkId: 13, an id the Gateway SDK's own RadixNetwork map does not contain at all, since it goes from 12 straight to 14. The example also predates the @radixdlt/rola package: its server verifies proofs with a hand-written implementation under apps/server/src/rola/ rather than the package this page recommends.
  • The package is frozen, and widely installed anyway. @radixdlt/rola is at version 2.1.0, published on 20 November 2024, and npm latest has not moved since. Its source repository has had no code change since then; its one 2026 commit, on 22 January, switched the npm publish step to OIDC. Downloads rose anyway, to 6,283 in September 2026.
  • The toolkit is in the same position. The dated version of that story is on Radix dApp Toolkit: bug fixes only, on a volunteer basis, pending a community decision on who takes the libraries on.

The practical rule for all three: read the archived example to see how the parts connect, then check every method name against the type definitions inside the version you actually installed, because the two do not agree.

Next Steps

HydrateLast updated 4d agov2.1.09 revisionsVerified Oct 2, 2026