Introduction

TruthID is decentralized authentication that replaces "Login with Google/Apple/Microsoft." Users own their identity through a blockchain wallet and authenticate with trusted devices — no password, no email, no third-party identity provider sitting in the middle.

Why

Centralized identity providers create account lockouts, data collection, and a single point of failure. TruthID gives users sovereignty over their own identity (a wallet they control) while giving integrators a simple SDK to verify logins against a public blockchain.

Prerequisites

TruthID has two kinds of users — people logging into a site, and developers adding TruthID to one. Each side needs different things.

To log in with TruthID:

• An identity registered on-chain — created once with any EVM wallet (MetaMask, Rabby, Ledger, Trezor, WalletConnect) holding a small amount of ETH on Base to cover setup gas (typically well under a cent). That wallet becomes the owner of a smart account created during setup, and isn't needed again after that — the smart account pays its own gas from then on. See Smart Account & Gas for the full setup flow and cost.
• A trusted device paired to that identity — the desktop app or the mobile app. The device's own private key never leaves it; the wallet above is only needed once, to create the identity, not for day-to-day logins.

To integrate TruthID into your app:

• A backend that can receive an HTTPS POST request (the signed login response). Any language works — official SDKs exist for TypeScript, Python, and Ruby (see Integrating TruthID below), and other languages can verify directly against the public contracts.
• A way to render a QR code on your login page — the SDK builds the payload, your frontend just needs any QR rendering library.
• Nothing else to provision: no database, no server, no third-party account.

Architecture

TruthID is a set of independent pieces that all read and write the same six contracts on Base Mainnet — there's no central server tying them together.

There is no relay, signaling server, or backend operated by TruthID for the login/pairing path itself — every off-chain message either travels inside a QR code or goes directly between the user's phone and the integrator's own backend. See Repository Structure for what lives where.

How it works

• Identity — a username bound to a controller wallet, created on-chain (IdentityRegistry).
• Trusted devices — each device (desktop, phone) generates its own keypair locally; private keys never leave the device. Devices are registered on-chain (DeviceRegistry) via a commit-reveal scheme that prevents front-running.
• Login — a website embeds a signed challenge directly in a QR code along with a callback URL. The user's phone scans it, signs locally, and POSTs the response straight to that callback. The integrator's backend verifies the signature and device status on-chain using a TruthID SDK.
• Sessions — only a keccak256 hash of session data is stored on-chain (SessionRegistry); what the hash represents stays local to the user's device.
• Recovery — identities can configure M-of-N guardians to recover a lost controller wallet, with a 7-day timelock before the recovery takes effect (RecoveryManager).

No TruthID-operated server sits in this path — the challenge travels inside the QR code, and the signed response goes straight from the phone to your own backend over HTTPS. For the full walkthrough — exact message formats, the smart-account signer model, what's public on-chain versus local-only — see How TruthID Works.

Integrating TruthID

Use one of the official SDKs — they wrap challenge creation, signature verification, and on-chain reads so your backend never talks to the blockchain directly:

Full API reference for each SDK — every method, type, and security note — lives in the SDK Reference. Framework examples (Express / Flask / Sinatra) are in sdk/README.md.

Smart contracts (Base Mainnet, chain 8453)

All contracts are verified on Basescan and carry no upgrade proxy. Each identity's controller is itself a smart account (ERC-4337) deployed by the factory above — it pays its own gas after a one-time setup, so day-to-day logins never touch the owner wallet. Testnet addresses, ABIs, function reference, and real gas costs: Smart Contracts. Setup flow and the smart account model: Smart Account & Gas.

Source code

TruthID is open source under the MIT license: github.com/masterlxz/truthid.

Next steps

• Why TruthID — the problem it solves and who it's for
• How TruthID Works — the full protocol walkthrough
• Quickstart — add TruthID login to your backend