Skip to content
Monolythium docs
GitHub

Sign in with Monolythium

Preview

Sign in with Monolythium is an off-chain application login based on a short-lived ML-DSA-65 proof. It pays no chain fee, does not move value, and does not authorize a later transaction.

One approval has two separate effects in the source implementation: it signs exactly one short-lived challenge, and it records the requesting origin as a connected site. The proof expires with that challenge, but the connected-site permission persists and may expose the selected account address to that origin while the wallet is unlocked. Neither effect grants spending authority.

There is no on-chain login module. The application issues a challenge, the browser wallet approves and signs it, and the application verifies the proof before creating its own cookie or session token.

Wallet-auth v1 contract

Section titled “Wallet-auth v1 contract”

The server-issued request contains exactly these authority-bearing fields:

  • version;
  • domain, origin, and origin-root URI;
  • active chain ID and genesis hash;
  • a 32-byte random nonce;
  • issue and expiration timestamps;
  • sorted requested scopes.

The wallet obtains the caller origin from its trusted browser bridge and compares every server-issued field exactly with the request it received. It also checks the origin and network fields against its trusted caller context and active pinned network. The sole challenge field added by the wallet is its selected canonical mono1… address. The wallet binds that address to the proof’s ML-DSA-65 public key, signs the complete challenge, and returns the challenge, algorithm, public key, and signature as a WalletAuthProofV1.

Challenges live for at most 180 seconds. Verifiers may configure no more than 30 seconds of clock tolerance.

User approval

Section titled “User approval”

The prompt must show the requesting site, selected address, network, expiry, and requested scopes. The signature approval applies to that one challenge only. The wallet does not offer an “always sign” bypass and the site cannot choose the signing address.

Separately, the same approval persists the origin in the wallet’s Connected sites list, avoiding a second account-connection prompt. A connected origin can read the selected account address while the wallet is unlocked and can receive account/connection events.

A valid authentication proof establishes control of the address for that challenge. It does not establish a person’s legal identity, validate a provider profile, prove ownership of a *.mono name, or grant transaction authority.

Developer API

Section titled “Developer API”

The canonical verification implementation is released in @monolythium/[email protected]. The browser-provider call below is integration pseudocode, not an executable SDK-only snippet. It is available in the browser wallet’s v0.4.5 GitHub prerelease; store installation remains pending:

import { verifyWalletAuthProofV1 } from "@monolythium/core-sdk";


const proof = await window.monolythium.request({
  method: "monolythium_authenticate",
  params: challengeIssuedByYourServer,
});


verifyWalletAuthProofV1(proof, {
  now: new Date(),
  clockSkewSeconds: 5,
});

Cryptographic verification is only the first half of the server boundary. The relying party must also:

  1. compare every server-issued signed field exactly with the stored request; do not expect an address in that request;
  2. accept challenge.address as the sole wallet-added field, then verify that the SDK binds it to proof.publicKey;
  3. enforce its expected origin, chain ID, genesis hash, and scopes;
  4. atomically consume the nonce before creating a session;
  5. reject reused, unknown, expired, or superseded challenges;
  6. apply its own session expiry, revocation, and authorization policy.

Sign-out and revocation

Section titled “Sign-out and revocation”

Three lifetimes are independent:

  1. the signed challenge proof expires in at most 180 seconds;
  2. the application’s cookie or token lasts until the application expires or revokes it;
  3. the wallet’s connected-site record lasts until the user revokes that origin, revokes all sites, resets the wallet, or another wallet lifecycle event clears it.

Signing out of a website does not automatically remove the wallet’s connected-site permission. Revoking a connected site does not reach into the website and invalidate an already-created server session or a previously accepted proof. For a complete disconnect, sign out in the application and remove the origin from the wallet’s Connected sites screen. Applications must offer their own server-side session revocation.

Do not use nonexistent mono_signIn or verifySignIn helpers, and do not fall back to generic message signing.

Release status

Section titled “Release status”

The SDK contract is released, and the browser-wallet implementation is included in the signed v0.4.5 GitHub prerelease. That exact release artifact has passed live Stele challenge, approval, session, sign-out, connected-site persistence, and explicit wallet-revocation checks. The current v0.4.4 Chrome Web Store build predates wallet-auth v1, so users need the unpacked prerelease until a compatible store version is published and installed.

Stele uses this same generic wallet-auth boundary. The wallet does not contain Stele, and neither the proof nor connected-site visibility creates a booking or authorizes spending.

Next

Section titled “Next”