T13 · Wallet Connection

A Real-World Problem

The product team says: “Add wallet login. It is basically like signing in with WeChat.”

Open any DApp: click “Connect Wallet” in the corner, approve a pop-up, and your avatar appears. It does look similar.

But this flow contains at least three entirely different actions:

• A browser extension gives the page an address. Nothing about the address has been verified; the page has merely been told one.
• The page requests a signature and the user approves. What does that prove, and to whom?
• Some sites immediately show another “Approval” pop-up after login. The user thinks it is still part of signing in and approves that too. This may grant access to every unit of a token in their wallet.

All three look alike: a pop-up and a confirmation click. Their consequences differ completely. The first changes nothing. The worst case for the second is account impersonation. The worst case for the third is losing funds.

Users cannot tell them apart partly because many products have not separated them either. This chapter does exactly that.

Thought Experiment

Imagine one key serving three purposes.

You join a company and receive a badge at reception. It is simultaneously:

1. An access card: swipe it and a gate opens. It proves only “you are an employee.”
2. An official signature stamp: press it onto a document to show “I saw and approved this.”
3. A pen that signs blank checks: once signed, finance must pay, and the signature can be redeemed repeatedly until you revoke it.

These would never be combined in ordinary life. A lost access card can be replaced, a lost stamp requires formal revocation, and no one would hand you a book of blank checks.

A Crypto wallet private key combines all three. The same key opens the gate, signs documents, and signs a repeatable check. The difference is not which key was used but what was written on the paper you signed.

That repeatable “check” has onchain state. Once granted, it remains valid until you send a transaction revoking it. Closing a tab, clearing cache, or changing computers does not remove it. Ordinary Web2 login has no equivalent.

So can users understand the paper they are signing?

Your Decision

You are adding login to your DApp. Which of four approaches do you choose?

What Happens

The four options reveal that connection, authentication, and authorization are separate actions that happen to share a pop-up interface.

Two cells deserve special attention. “No one verifies it” is easy to skip: a connected address can be claimed by anyone. It is suitable for display, not authentication. “No expiry” is the one state that survives closing the page: your product therefore needs a revocation path rather than sending users to find one elsewhere.

The table also omits one warning: “offchain” does not mean “risk-free.” An offchain signature can itself authorize spending. The worst phishing examples below require no transaction from the user.

Build a Model

Separate login into five stages, each with one job:

What You Sign Determines Everything

Signature requests fall into three classes with dramatically different risks:

The third is blind signing. A user sees meaningless characters and approves something with unknown consequences. If your product requires blind signing, its design is flawed.

The second deserves even more care because it appears safe. A field named spender holds an address; a field named value holds a 78-digit number. Users can “see” each field without understanding that they are giving a stranger access to their entire balance for a year.

Honest display means users can describe the consequence after reading, not merely that raw data is visible. Those are very different standards.

What a Login Message Should Contain

Here is plain text; the meaning of the fields matters more than the exact format:

example.com wants you to sign in with this address:

0x<your address>

By signing, you agree to sign in to example.com.
This signature does not send a transaction or approve any transfer of funds.

Chain ID: <chain ID>
Nonce: <one-time random value generated by the backend>
Issued At: <issuance time>
Expiration Time: <expiry time>

Each field blocks a class of attack: domain prevents cross-site replay; address prevents impersonation with another account’s message; Chain ID prevents cross-chain replay; Nonce prevents replay on the same site (invalidate it immediately after use); and expiry limits how long a stolen signature works.

“This signature does not send a transaction or approve funds” is a promise to the user, not boilerplate. Each time that proves true, users gain confidence in the message. Slip one approval into login and you spend that trust across the industry.

Session Lifetime

After signature verification, issue an ordinary session credential as you would in Web2. Three Crypto-specific events must invalidate it:

type WalletSession = {
  address: string;      // Verified address
  chainId: number;      // Chain used during authentication
  issuedAt: number;
  expiresAt: number;
};

// Three situations requiring immediate session destruction:
// 1. Wallet switches account, so current address differs from session.address
// 2. Wallet switches chain and a single-chain product sees a chainId mismatch
// 3. Wallet disconnects

The first is easiest to miss. A user changes wallet accounts, but the page retains the old session. They see account B in the wallet while acting on account A’s data in the app. Listen for account changes and destroy the session immediately, requiring new authentication rather than switching silently.

Approvals Must Be Timely, Limited, and Revocable

A spending approval is an onchain transaction. Design it around three questions:

1. When to ask? When the user actually needs the feature, not during login.
2. How much? The amount needed for this operation, not unlimited funds. Avoiding one extra click is not worth a permanent exposure.
3. How to revoke? Your product needs a page listing approvals users have granted to your contracts, with a direct way to revoke them.

The third is half of this chapter’s lab. Teams often say users can go elsewhere to revoke, but a product that creates a risk should provide its exit.

What It Is Called

Hands-on

AI Lab

Step one:
List common Crypto wallet signature-phishing patterns. For each, explain:
- What type of data the attacker asks users to sign
- What the wallet pop-up actually shows users
- What an attacker can do afterward and whether users must take another action
- Which clues a user could realistically recognize

Step two:
Here is the copy and pop-up content of my login and approval interface (paste the real text).
For every pattern above, check whether my interface communicates the consequence honestly
or could mislead a user. Suggest a specific change for each weak point, not generic advice.

Real-World Case

Change One Variable

Takeaway Questions

Chapter Check