Developer Guides
Build passkey wallets
Create NVNM Chain accounts from passkeys, store and restore them, and sign transactions with Face ID, Touch ID, a security key or supported password managers, using the chain's native WebAuthn/P256 (aka secp256r1) support.
NVNM Chain NEXT is an L1 that verifies passkey (WebAuthn/P256) signatures in the protocol itself, so you can turn a passkey into an account without a smart-contract wallet, bundler or seed phrase.
This guide explains how NVNM Chain supports passkeys. It then walks through the passkey wallet in the NVNM demo dApp. You learn how to create an account, store its public key, restore it in a new browser and sign transactions.
Live demo and source
The live NVNM demo dApp runs the passkey wallet this page describes. The dApp code samples on this page come from the demo dApp's source (NVNM-Chain/nvnm-demo-dapp on GitHub). File paths such as apps/web/src/config/chains.ts are relative to that repository. For a click-through, see Try it in the demo dApp.
How passkeys work on the chain
On Ethereum, an account can only sign with a secp256k1 key and must use its nonces in order. A passkey's P256 key can't sign for it, and the strict nonce order limits how fast one account can send transactions.
NVNM Chain addresses this with its native transaction type (0x76), an EIP-2718 typed transaction that can carry a secp256k1, P256 or WebAuthn signature. The chain checks P256 and WebAuthn signatures in the protocol, so a passkey can sign transactions directly, with no verifier contract.
The demo dApp describes its passkey account the same way: "a chain-native WebAuthn P-256 account" (apps/web/README.md).
Signature types
The chain supports four signature schemes. It identifies the scheme from the signature's length and its type prefix. Each scheme has its own base transaction cost, which reflects how much work verification takes. The last column shows that base transaction cost, not the cost of the signature check alone. The secp256k1 base of 21,000 gas includes 3,000 gas for the ecrecover precompile. P256 adds 5,000 gas for P256 verification:
| Type | Wire format | How the chain verifies it | Base transaction gas |
|---|---|---|---|
| secp256k1 | 65 bytes with no type prefix, so existing Ethereum signatures still work | Standard ecrecover | 21,000 |
| P256 | Prefix 0x01 + 129 bytes (r, s, pub_key_x, pub_key_y, pre_hash). 130 bytes total. | Checks the P256 signature against the public key it carries. With pre_hash set to true, it hashes the digest with sha256 first. | 26,000 |
| WebAuthn | Prefix 0x02 + webauthn_data (authenticatorData ‖ clientDataJSON) + 128 bytes (r, s, pub_key_x, pub_key_y). 129 to 2049 bytes. | Reads the challenge and type from clientDataJSON, then checks the P256 signature over the WebAuthn payload | 26,000 + calldata gas for clientDataJSON |
| Keychain | Prefix 0x03 + user_address (20 bytes) + inner signature | Checks the wrapped signature, then looks up the access key in the AccountKeychain precompile to validate it | Inner signature + 3,000 |
A passkey produces a WebAuthn signature. The chain encodes it as this struct:
pub struct WebAuthnSignature {
typeId: u8, // 0x02
webauthn_data: Bytes, // Variable length (authenticatorData || clientDataJSON)
r: B256, // 32 bytes
s: B256, // 32 bytes
pub_key_x: B256, // 32 bytes
pub_key_y: B256 // 32 bytes
}To keep gas costs down and parsing simple, send the minimal 37-byte authenticatorData in 0x76 transactions. It has no AT or ED flags set.
How a passkey becomes an address
For P256 and WebAuthn keys, the chain derives the address from the public key alone:
function deriveAddressFromP256(bytes32 pubKeyX, bytes32 pubKeyY) public pure returns (address) {
// Hash
bytes32 hash = keccak256(abi.encodePacked(
pubKeyX,
pubKeyY
));
// Take last 20 bytes as address
return address(uint160(uint256(hash)));
}Two consequences follow for your app:
- You must keep the public key. WebAuthn returns the public key only once, at registration. The address is a hash of the public key, so save the key when the user registers, in a database or in browser storage. When the user signs in again, return the stored key from the
getPublicKeyfunction you pass to viem (see viem: Sign in with a passkey). - One passkey is one account. The formula takes no chain ID. The demo dApp tells its users: "Your address comes from the passkey, so creating another makes a new, empty account... It's the same address on testnet and devnet, with a separate balance on each."
What the chain checks, and what it skips
NVNM Chain's WebAuthn verification follows the Daimo P256 verifier approach. The challenge is the transaction hash, Base64URL-encoded, and the signed message is sha256(authenticatorData || sha256(clientDataJSON)).
| The chain verifies | The chain skips |
|---|---|
| Authenticator data is at least 37 bytes | Origin check (a blockchain has no web origin to check) |
| The User Presence (UP) flag is set | RP ID hash check (a decentralized chain has no single relying party) |
clientDataJSON contains "type":"webauthn.get" | Signature counter (your app handles clone detection) |
The challenge equals tx_hash, Base64URL-encoded | Backup flags (a matter of account policy) |
| The P256 signature is valid |
Because the chain skips origin and RP ID checks, the chain does not bind a passkey to your domain. The browser does. Keep this in mind when you read the security notes.
Passkey prompts and access keys
With a passkey as the root key, every signature opens a passkey prompt. In an app that sends many transactions, or walks the user through several steps, this quickly gets tiresome. The prompt may also read "Sign in" while the user is approving a transaction, which is confusing.
Access keys fix this: the root key authorizes a limited-scope key once, and that key signs the transactions that follow with no further prompts. The AccountKeychain precompile at 0xAAAAAAAA00000000000000000000000000000000 manages access keys. Access keys can't deploy contracts: a transaction they sign can't execute CREATE or CREATE2, even inside a factory call, so sign deployments with the root key.
Note
The demo dApp keeps access keys off. Every transaction asks for the passkey, and its UI warns users that "your device's prompt may say 'Sign in'". To add access keys, see viem's access keys guide.
The SDKs to use
The demo dApp builds its passkey wallet on three TypeScript packages that support the chain:
| Package | Role | Version in the demo dApp |
|---|---|---|
wagmi (wagmi/tempo) | The webAuthn connector, which signs users in with a passkey account | wagmi 3.7.7, @wagmi/core 3.6.5 |
accounts | The Accounts SDK. It runs the passkey ceremony and stores accounts. wagmi's webAuthn connector delegates to it. | 0.18.4 |
viem (viem/tempo) | Chain config, Account.fromWebAuthnP256 and the serializers for 0x76 transactions | ^2.57.1 (2.57.1 resolved) |
The demo dApp's passkey ceremony also uses ox 0.14.45 and webauthx 0.1.2, the versions accounts 0.18.4 resolves. Its pnpm-workspace.yaml pins wagmi, @wagmi/core, accounts, ox and webauthx to exact versions (viem is ^2.57.1), so re-test before you bump them.
The minimal setup registers the connector in a wagmi config. nvnmTestnet is the chain you define in the first step of Build the passkey wallet:
import { createConfig, http } from 'wagmi'
import { webAuthn } from 'wagmi/tempo'
import { nvnmTestnet } from './chains'
export const config = createConfig({
connectors: [webAuthn()],
chains: [nvnmTestnet],
multiInjectedProviderDiscovery: false,
transports: {
[nvnmTestnet.id]: http(),
},
})By default the connector runs the passkey ceremony in the browser. Pass authUrl, as in webAuthn({ authUrl: '/auth' }), to move the ceremony's challenges to your backend. To plug in your own ceremony, pass ceremony. The demo dApp does this.
Info
This guide uses domain-bound passkeys, as the demo dApp does. They suit apps that ship their own wallet UI and run the WebAuthn ceremony themselves.
Build the passkey wallet
The steps below follow the demo dApp's web app in apps/web. It is a React app with wagmi and Reown AppKit.
Add the chain config to the NVNM chains
NVNM chains aren't built into viem, so the dApp defines them with defineChain. Passkey accounts send 0x76 transactions, so each chain also needs the formatters and serializers for that transaction type. The dApp copies exactly those keys from viem's tempoModerato chain:
import { defineChain, type Address, type Hash } from "viem";
import { tempoModerato } from "viem/tempo/chains";
// ...
// Passkey accounts need Tempo's chain config: the formatters, serializers and prepare hook for its native
// transaction type (0x76), plus the signature-envelope `verifyHash`. Their requests carry Tempo `calls`, which
// viem's default formatter drops. viem doesn't export the config on its own, so take exactly these keys off a
// Tempo chain (the whole chain would bring Tempo's contracts and hardfork). Tempo's `blockTime` (1 s) puts viem's
// default polling at its 500 ms floor, which suits NVNM Chain's ~0.5 s blocks.
//
// ...
//
// `feeToken` and `hardfork` stay unset on purpose. A fee token in a request makes viem send browser wallets a 0x76
// transaction, which MetaMask can't sign; on the chain it turns their gas estimates into 0x76. Unset, the chain
// charges nUSD. NVNM Chain runs Tempo forks up to t11/t12, past viem's list (t6), and viem treats a fork it doesn't
// know as older than all of them; unset, it assumes the current rules.
const { blockTime, extendSchema, formatters, prepareTransactionRequest, serializers, verifyHash } =
tempoModerato;
const tempoChainConfig = {
blockTime,
extendSchema,
formatters,
prepareTransactionRequest,
serializers,
verifyHash,
};
export const nvnmTestnet = defineChain({
...tempoChainConfig,
id: 787_223,
name: "NVNM NEXT Testnet 1",
nativeCurrency: nUSD,
rpcUrls: {
default: {
http: [import.meta.env.VITE_NVNM_TESTNET_RPC_URL || "https://rpc.nvnm.testnet.nvnmchain.io"],
webSocket: ["wss://rpc.nvnm.testnet.nvnmchain.io"],
},
},
// ...
testnet: true,
});View on GitHub: apps/web/src/config/chains.ts
The Devnet chain (787222) uses the same spread. See Network details for both networks.
Register the passkey connector
The dApp creates one webAuthn connector from wagmi/tempo. It gives the connector an IndexedDB storage adapter and a custom ceremony, and both share that same storage:
import { WagmiAdapter } from "@reown/appkit-adapter-wagmi";
import { Storage } from "accounts";
import { http, type Config, type Connector } from "wagmi";
import { webAuthn } from "wagmi/tempo";
import { recoveringCeremony } from "@/lib/passkey-ceremony";
import { nvnmDevnet, nvnmTestnet } from "./chains";
import { PASSKEY_RDNS, PASSKEY_STORAGE_KEY, WALLETCONNECT_PROJECT_ID } from "./constant";
const chains = [nvnmTestnet, nvnmDevnet] as const;
// ...
// Holds the passkey accounts and the public keys of passkeys used here (IndexedDB). The connector and the ceremony
// must share it: the next sign-in looks up the keys the ceremony recovers in it.
const passkeyStorage = Storage.idb({ key: PASSKEY_STORAGE_KEY });
// A chain-native account per passkey (WebAuthn P-256), verified by NVNM Chain itself. Every transaction asks for the
// passkey: no access keys, fee payer or relay.
const passkey = webAuthn({
name: "Passkey",
rdns: PASSKEY_RDNS,
// Machine payments would replace `globalThis.fetch` to pay HTTP 402 responses from the passkey account.
mpp: false,
storage: passkeyStorage,
// Signs in with passkeys this browser hasn't stored a key for (another device, cleared site data).
ceremony: recoveringCeremony({ storage: passkeyStorage }),
});
export type PasskeyConnector = Connector<ReturnType<typeof webAuthn>>;
// Tells the passkey connector apart by type. That also works on the connector of the connection wagmi restores while
// it reconnects on load, but that one is a stub with only id, name, type and uid: call methods only on a connector
// from `useConnectors()`.
export function isPasskey(connector: Connector): connector is PasskeyConnector {
return connector.type === webAuthn.type;
}
// Owns the wagmi config: the adapter builds it from these options (they're wagmi `createConfig` parameters) and adds
// AppKit's connectors — injected, EIP-6963 wallets and, with a project id, WalletConnect — at runtime.
export const wagmiAdapter = new NvnmWagmiAdapter({
networks: [...chains],
projectId: WALLETCONNECT_PROJECT_ID,
connectors: [passkey],
transports: {
[nvnmTestnet.id]: http(),
[nvnmDevnet.id]: http(),
},
});View on GitHub: apps/web/src/config/wagmi.ts
recoveringCeremony is the dApp's own wrapper around the Accounts SDK's local ceremony. It lets users sign in from a browser that hasn't stored their key. See Restore an account in a new browser.
The two constants come from constant.ts:
// The passkey wallet's reverse-DNS id. The accounts SDK announces its provider over EIP-6963 under this id, and wagmi
// skips an announced wallet whose rdns matches a configured connector, so the passkey isn't listed twice.
export const PASSKEY_RDNS = "io.nvnmchain.demo.passkey";
// Prefix of the passkey wallet's keys in IndexedDB: its accounts and the public keys of passkeys used on this site.
export const PASSKEY_STORAGE_KEY = "nvnm-demo-dapp";View on GitHub: apps/web/src/config/constant.ts
The dApp passes the connector to NvnmWagmiAdapter, its own subclass of Reown AppKit's WagmiAdapter. The adapter's options are wagmi createConfig parameters. If you don't use AppKit, pass the same connectors: [passkey] and transports to wagmi's createConfig, as in the minimal setup above. Then wrap your app in WagmiProvider and QueryClientProvider as usual (see apps/web/src/providers.tsx).
Create a passkey account
You create and sign in to passkey accounts through wagmi's useConnect. The capabilities you pass tell the Accounts SDK which WebAuthn ceremony to run. Their method field picks the ceremony: 'register' creates a new passkey and 'login' signs in with an existing one. The dApp's passkey view creates an account like this:
type Capabilities = NonNullable<Parameters<PasskeyConnector["connect"]>[0]>["capabilities"];
// ...
function PasskeyView({ onBack }: { onBack: () => void }) {
// ...
const passkey = useConnectors().find(isPasskey);
// ...
const connected = Boolean(useConnection().address);
const connect = useConnect();
const pending = connect.isPending;
// The network the app is on, which the header's faucet link uses too. The passkey connects on it (the accounts
// SDK would otherwise pick its own saved network), so the faucet linked below funds it where it lands.
const chainId = useChainId();
const error = walletErrorMessage(connect.error);
// ...
function connectPasskey(action: Action, capabilities: Capabilities) {
if (!passkey || pending || connected) return;
setStarted(action);
connect.mutate({ connector: passkey, chainId, capabilities });
}
function create(event: SubmitEvent) {
event.preventDefault();
connectPasskey("create", { method: "register", name: name.trim() || APP_NAME });
}
// ...
}View on GitHub: apps/web/src/components/connect-dialog.tsx
The name labels the passkey. The dApp's form describes it as "Shown in your password manager". Pass chainId so the account connects on the network your app is on.
When you register, the Accounts SDK (accounts 0.18.4) does the following:
- It asks the ceremony for registration options. The ceremony uses the page's hostname as the relying party ID (
rpId). - It calls the browser's WebAuthn API, which prompts the user to create a passkey.
- The ceremony's
verifyRegistrationstores the new public key in itscredentialsmap. Account.fromWebAuthnP256({ id, publicKey })fromviem/tempoderives the account address.
Before you offer passkeys, check that the browser supports WebAuthn. The dApp disables the Passkey option otherwise:
const passkeysSupported = typeof window.PublicKeyCredential !== "undefined";View on GitHub: apps/web/src/components/connect-dialog.tsx
Sign in with an existing passkey
To sign in, the same view connects with the login method:
// `selectAccount` lets the browser offer every passkey saved for this site instead of the last one used.
const signIn = () => connectPasskey("signIn", { method: "login", selectAccount: true });View on GitHub: apps/web/src/components/connect-dialog.tsx
The SDK asks the browser for a passkey signature, then the ceremony's verifyAuthentication returns that passkey's public key, and the SDK derives the address from it. Without selectAccount, the SDK asks for the last passkey used, which it remembers as lastCredentialId.
Sign and send transactions
You don't need passkey-specific send code. Call the same wagmi hooks you use for browser wallets. The dApp's Send nUSD card sends a TIP-20 transfer like this:
const transfer = useWriteContract();
// ...
transfer.mutate(
{
address: nUSD.address,
abi: tip20Abi,
functionName: "transfer",
args: [recipient, amount],
chainId: chain.id,
},
{ onSuccess: () => setResultOpen(true) },
);View on GitHub: apps/web/src/components/token-transfer.tsx
With the passkey connector active, the SDK builds a 0x76 transaction. viem/tempo's Account.fromWebAuthnP256 passes the transaction hash to WebAuthn as the challenge, which is what the chain checks: the challenge must equal tx_hash. Each send opens one passkey prompt, and the transaction goes out once the user confirms it.
The dApp tracks the result with its useTxOutcome hook the same way for passkey accounts and browser wallets. See Deploy and interact with smart contracts.
Contract calls work the same way. See Deploy and interact with smart contracts for the CheckIn contract in the dApp's packages/contracts, and Token balances and fees for the transfer flow.
Show clear passkey errors
Passkey failures reach you wrapped by viem, wagmi and the Accounts SDK. A cancelled prompt isn't a 4001 rejection. The dApp walks the error's cause chain and maps the browser's WebAuthn error names to short messages:
// Checked against every error in the `cause` chain, outermost first. Wallet, passkey and RPC failures arrive wrapped
// by viem, wagmi and the passkey provider: a cancelled passkey prompt, for example, is an RPC -32603 error caused by
// the browser's `NotAllowedError`, not a 4001 rejection.
const known: [matches: (error: ErrorLike) => boolean, message: string][] = [
[
(e) => e.name === "NotAllowedError",
// The browser uses one error for cancel, timeout and a failed biometric check.
"The passkey request was cancelled or timed out.",
],
[(e) => isRejection(e) && !isMisreported(e), "Request rejected in your wallet."],
[
(e) => messageOf(e).includes("Unknown credential"),
"This passkey's account isn't known here yet. Try signing in again.",
],
[
// Thrown by the passkey ceremony when two signatures don't agree on one public key.
(e) => e.name === "PasskeyRecoveryError",
"Couldn't recover the account for this passkey.",
],
[
// Creating a passkey the authenticator already holds for this site.
(e) => e.name === "InvalidStateError",
"A passkey for this site already exists on this device. Sign in with it instead.",
],
[
(e) => e.name === "SecurityError",
"Passkeys need a secure (https) page on the site's own domain.",
],
[(e) => e.name === "NotSupportedError", "This browser doesn't support passkeys."],
// ...
];View on GitHub: apps/web/src/lib/wallet-errors.ts
Give each failure its own message, at least for a cancelled prompt, an expired challenge and a domain (RP ID or origin) mismatch. Users and your support team can then tell what went wrong and recover quickly.
Where the dApp stores passkey data
The dApp stores passkey data in IndexedDB, not localStorage. Storage.idb is the Accounts SDK's IndexedDB adapter. Provider.create already uses it in browsers if you pass no storage.
The adapter writes to an IndexedDB database. It prefixes every key with options.key. The dApp sets this to nvnm-demo-dapp, so its entries stay apart from those of other apps on the same origin.
The dApp's data lives under these keys:
| IndexedDB key | Written by | Contents |
|---|---|---|
nvnm-demo-dapp.credentials | The ceremony, on registration and recovery | A map from credential ID to the passkey's uncompressed P-256 public key (hex) |
nvnm-demo-dapp.lastCredentialId | The SDK's WebAuthn adapter, after create and sign-in | The ID of the last passkey used |
The SDK also persists its provider state, such as the connected accounts, through the same storage adapter.
Warning
The app never stores a private key. The authenticator holds it. The dApp stores only public keys and account metadata. Its UI says: "This site never sees its private key."
The key names come from the internals of accounts 0.18.4, which the dApp relies on. The SDK doesn't document them, so check them again when you upgrade the SDK.
Restore an account in a new browser
WebAuthn returns a passkey's public key only when the passkey is created. If a user signs in from another device with a synced passkey, or after clearing site data, the browser has no stored key. The SDK's local ceremony then fails with Unknown credential.
One fix is to store the public key yourself in a database that any browser can query when it restores the account (see How a passkey becomes an address). The Accounts SDK also offers a server-backed ceremony for this. The demo dApp has no backend, so it uses its own technique instead. ECDSA public-key recovery yields two candidate public keys per signature. The dApp asks for a second signature from the same passkey, keeps the one key that both sets share, and stores it:
import { type Storage, WebAuthnCeremony } from "accounts";
import { Bytes, Hash, P256, PublicKey, Signature } from "ox";
import type { Hex } from "viem";
import { Authentication } from "webauthx/client";
// ...
// Where accounts 0.18.4's `WebAuthnCeremony.local` keeps its credential id → public key map (uncompressed P-256,
// hex). Recovered keys go into the same map, so the next sign-in on this device takes the local path.
const credentialsKey = "credentials";
// ...
// The accounts SDK's local ceremony, able to sign in with a passkey this browser has never seen.
//
// WebAuthn only returns a passkey's public key when it is created, and the local ceremony keeps it in this browser's
// storage, so a passkey synced to another device, or used after site data is cleared, fails with "Unknown credential".
// There is no backend to ask. Instead, ECDSA public-key recovery gives two candidate keys per signature; a second
// signature by the same passkey, over a fresh challenge, shares exactly one of them: the passkey's key.
export function recoveringCeremony({
storage,
rpId,
sign = Authentication.sign,
}: RecoveringCeremonyOptions): Ceremony {
const local = WebAuthnCeremony.local({ storage, rpId });
// Candidates from a recovery whose second prompt failed, by credential id, so a retry needs a single prompt.
const pending = new Map<string, readonly Hex[]>();
async function storedKeys() {
return (await storage.getItem<Record<string, Hex>>(credentialsKey)) ?? {};
}
async function remember(credentialId: string, publicKey: Hex) {
await storage.setItem(credentialsKey, { ...(await storedKeys()), [credentialId]: publicKey });
pending.delete(credentialId);
return { credentialId, publicKey };
}
return WebAuthnCeremony.from({
...local,
async verifyAuthentication(response) {
// The local ceremony's `verifyAuthentication` is this lookup, but throws where an unknown key starts recovery. A
// stored key must also have made this signature: any page on this origin can write the map, and a wrong entry
// would otherwise give the wrong address on every sign-in. Recovery replaces it.
const known = (await storedKeys())[response.id];
if (known && signedBy(response, known))
return { credentialId: response.id, publicKey: known };
const candidates = recoverCandidates(response);
const earlier = pending.get(response.id);
const recovered = earlier && commonKey(earlier, candidates);
if (recovered) return remember(response.id, recovered);
// If this prompt is cancelled the error propagates and `pending` keeps these candidates.
pending.set(response.id, candidates);
const { options } = await local.getAuthenticationOptions({ credentialId: response.id });
const second = await sign({ options });
// From here a failure can't tell which signature was wrong, so a retry starts over.
pending.delete(response.id);
if (second.id !== response.id) {
throw new PasskeyRecoveryError(
`Expected a second signature from passkey ${response.id}, got one from ${second.id}.`,
);
}
const publicKey = commonKey(candidates, recoverCandidates(second));
if (!publicKey) {
throw new PasskeyRecoveryError(
`The two signatures from passkey ${response.id} don't share a public key.`,
);
}
return remember(response.id, publicKey);
},
});
}
// What a WebAuthn authenticator signs: sha256(authenticatorData ‖ sha256(clientDataJSON)).
function signedPayload(response: AuthenticationResponse) {
const { authenticatorData, clientDataJSON } = response.metadata;
return Hash.sha256(
Bytes.concat(Bytes.fromHex(authenticatorData), Hash.sha256(Bytes.fromString(clientDataJSON))),
);
}
// ...
// The public keys that could have produced this assertion's signature, one per y-parity of the curve point R, in the
// format the SDK stores. Parities that don't yield a point are skipped.
function recoverCandidates(response: AuthenticationResponse): Hex[] {
const payload = signedPayload(response);
const { r, s } = Signature.fromHex(response.signature);
const candidates: Hex[] = [];
for (const yParity of [0, 1]) {
try {
candidates.push(
PublicKey.toHex(P256.recoverPublicKey({ payload, signature: { r, s, yParity } })),
);
} catch {
// No curve point for this parity.
}
}
return candidates;
}
// The one key both candidate sets share. Two shared keys mean the second signature repeats the first (the same r and
// s, up to the sign of s, over the same payload), which doesn't single out a key, so that counts as no match.
function commonKey(a: readonly Hex[], b: readonly Hex[]): Hex | undefined {
const common = a.filter((key) => b.includes(key));
return common.length === 1 ? common[0] : undefined;
}View on GitHub: apps/web/src/lib/passkey-ceremony.ts
Here is what this means for your users:
- In a browser that already stores the key, sign-in takes one prompt. The ceremony still checks that the stored key made the signature, because "any page on this origin can write the map".
- In a new browser, sign-in takes two prompts. The dApp tells users: "In a browser you haven't used this passkey in, you'll confirm twice so we can recover your account."
- After recovery, the key is stored, so the next sign-in takes one prompt.
signedPayload computes the same message that the chain's WebAuthn verifier checks: sha256(authenticatorData || clientDataHash).
Note
Two-signature recovery is the demo dApp's own approach, not a protocol feature.
Use a server-backed ceremony in production
WebAuthnCeremony.local runs the whole ceremony in the client and is meant for development and prototyping. For production, use the Accounts SDK's server-backed ceremony. Mount Handler.webAuthn from accounts/server. Then point the connector at it with webAuthn({ authUrl: '/auth' }):
import { Handler, Kv } from 'accounts/server'
export const handler = Handler.webAuthn({
kv: Kv.memory(),
origin: 'https://app.example.com',
path: '/auth',
rpId: 'example.com',
})Set origin to the full origin your app's pages load from, such as https://app.example.com. The handler checks it when it verifies each registration and login. Pass an array if your app loads from more than one origin. Set rpId to the domain your passkeys belong to (see Passkeys are bound to the domain).
Set the handler's path to the same prefix you pass as authUrl. With /auth, it answers POST requests on /auth/register/options, /auth/register, /auth/login/options, /auth/login and /auth/logout. Runtimes that accept a Fetch API handler, such as Bun, Deno, Hono and Next.js route handlers, take handler.fetch. Node's createServer and Express take handler.listener.
Kv.memory() lives in process memory, so a restart or redeploy wipes every pending challenge and registered passkey. Use it only on your own machine. For production, accounts/server 0.18.4 ships Kv.cloudflare (Workers KV) and Kv.durableObject. To use another store, wrap it with Kv.from.
Limit how often one client or one account can call the register and login routes. Otherwise attackers can probe for credentials or keep guessing without end.
By default, the handler also starts a cookie session after each registration and login. Your routes can read it with handler.getSession(req). If your wallet needs only the passkey ceremony, pass session: false.
Security and operational notes
Passkeys are bound to the domain
The browser binds every passkey to an RP ID. In the demo dApp, the RP ID is the page's hostname. Its README explains the consequences:
Passkeys are bound to the domain. A passkey belongs to the hostname it was created on, so production passkeys belong to
nvnm-chain.github.io, andlocalhost(dev andvp preview) has its own. Every NVNM-Chain GitHub Pages site shares that hostname and its storage: any of them can ask for these passkeys and, with the user's biometric, sign for their accounts, so only trusted repos should publish to the org's Pages. A custom domain avoids that, but moving the app to another domain orphans every existing passkey account: the passkey can't be used there, so the app can no longer sign for that address. Settle the domain before promoting passkeys.— Demo dApp
README.md
The same applies to your choice of RP ID, so settle it before launch. A passkey registered for a parent domain such as yourapp.com also works on wallet.yourapp.com. A passkey registered for wallet.yourapp.com never works on yourapp.com, so you can't widen the RP ID later.
If you change the RP ID after launch, existing passkeys stop working on your site. Each user then needs a new passkey, and a new passkey means a new address.
The browser enforces this binding. NVNM Chain doesn't.
Serve passkeys from a secure origin
- Serve your app over HTTPS. Browsers expose WebAuthn only in a secure context.
localhostcounts as one, but a production page served over plain HTTP doesn't, so passkey ceremonies there fail. - In development, open your app at
localhost. The dApp's README warns: "an IP address such as127.0.0.1isn't a valid passkey domain, so passkeys fail there." localhostand your production host hold different passkeys, so they are different accounts.
Plan for lost passkeys
There is no seed phrase. The dApp warns its users: "If every copy of the passkey is lost or deleted, the account and its funds are gone. Passkeys synced by iCloud Keychain or Google Password Manager also work on your other devices signed in to the same Apple or Google account."
Don't count on sync alone. A user may have it turned off, use a different passkey provider on each device, or lose every device at once. A second passkey doesn't act as a backup, because it derives a different address and so starts a new, empty account. Encourage users to keep passkey sync on, and warn them before they rely on a passkey that lives on a single device.
Fund new accounts
A new passkey account is empty. The dApp tells users: "New passkey accounts start with 0 nUSD, and network fees are paid in nUSD." Point your users to a faucet:
- Testnet: nUSD faucet
- Devnet: nUSD faucet
The dApp uses nUSD, the TIP-20 at 0x20C0000000000000000000000000000000000000, as the fee token on both networks. To learn how fees work, see Token balances and fees. Check Network details for each faucet's current status.
Try it in the demo dApp
Open the passkey view
Open the NVNM demo dApp. Click Connect wallet, then click Passkey.
Create a passkey
Enter a Passkey name and click Create passkey. Confirm with Face ID, Touch ID, your screen lock or a security key.
Fund and use the account
Click Get test tokens in the passkey view to fund the account. Then send nUSD from the Send nUSD card. Your passkey approves each transaction.
Sign in again
Disconnect, then click Sign in with a passkey. Your browser or password manager asks you to confirm with your passkey. Open How do passkey accounts work? in the same view for a summary of how passkey accounts behave.
