siwe
Add Sign-In with Ethereum (SIWE) authentication to a Scaffold-ETH 2 project. Use when the user wants to: add wallet-based login, implement SIWE, authenticate users with their Ethereum wallet, add session management with wallet signing, build sign-in with Ethereum, or add Web3 authentication.
- License 许可
- MIT
- 最近更新
- 2026-10-01
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- siwe
- description
- Add Sign-In with Ethereum (SIWE) authentication to a Scaffold-ETH 2 project. Use when the user wants to: add wallet-based login, implement SIWE, authenticate users with their Ethereum wallet, add session management with wallet signing, build sign-in with Ethereum, or add Web3 authentication.
03 SKILL.md 正文
Sign-In with Ethereum (SIWE) for Scaffold-ETH 2
Prerequisites
Check if ./packages/nextjs/scaffold.config.ts exists directly in the current working directory (do not search subdirectories). If it doesn't exist, this is not a Scaffold-ETH 2 project. Follow the instructions at https://docs.scaffoldeth.io/SKILL.md to scaffold it first. If it exists, continue directly with building.
Critical: Use viem's Native SIWE — NOT the siwe npm Package
Viem provides all SIWE utilities natively via viem/siwe. Do not install the siwe npm package. It pulls in ethers as a peer dependency, which is unnecessary since SE-2 already uses viem.
Here are some commonly useful imports (but check official docs for any updates or alternatives):
import {
createSiweMessage,
parseSiweMessage,
verifySiweMessage,
generateSiweNonce,
} from "viem/siwe";
Dependencies
yarn workspace @se-2/nextjs add iron-session
Gotchas
1. Domain Validation in the Verify Route
The verify route must validate the SIWE message's domain against the request's Host header. Without this, an attacker can replay a signature from a different domain. This is a critical security check that's easy to skip:
// In your verify API route
const expectedDomain = req.headers.get("host");
if (!expectedDomain) {
return NextResponse.json({ error: "Missing Host header" }, { status: 400 });
}
// Pass domain to verifySiweMessage
const isValid = await verifySiweMessage(client, {
message,
signature,
nonce: storedNonce,
domain: expectedDomain, // CRITICAL — validates domain match
});
2. Session Options Must Use a Lazy Getter
sessionOptions must NOT be a module-level constant that calls getSessionPassword() at import time. During next build, the code runs in production mode, and the env var won't be set, causing a build failure. Use a lazy factory:
// packages/nextjs/utils/siwe.ts
import { SessionOptions } from "iron-session";
export type SiweSessionData = {
nonce?: string;
address?: string;
chainId?: number;
isLoggedIn: boolean;
signedInAt?: string;
};
export const defaultSession: SiweSessionData = { isLoggedIn: false };
// Lazy getter — defers env var evaluation to request time
export function getSessionOptions(): SessionOptions {
const secret = process.env.IRON_SESSION_SECRET;
const password =
secret && secret.length >= 32
? secret
: process.env.NODE_ENV === "production"
? (() => {
throw new Error(
"IRON_SESSION_SECRET must be set in production (32+ chars)",
);
})()
: "complex_password_at_least_32_characters_long_for_dev";
return {
password,
cookieName: "siwe-session",
cookieOptions: {
httpOnly: true,
sameSite: "lax" as const,
secure: process.env.NODE_ENV === "production",
maxAge: 7 * 24 * 60 * 60,
},
};
}
3. hasSeenWalletConnected Ref to Prevent False Auto-Logout
On page refresh, the wallet reconnects asynchronously, causing a brief isConnected: false state. Without tracking whether the wallet was ever connected, this triggers a false logout. Use a ref:
const hasSeenWalletConnected = useRef(false);
useEffect(() => {
if (isConnected) {
hasSeenWalletConnected.current = true;
}
if (!isConnected && hasSeenWalletConnected.current && state.isSignedIn) {
// Wallet actually disconnected — sign out
fetch("/api/siwe/session", { method: "DELETE" }).then(() => {
setState((prev) => ({ ...prev, isSignedIn: false, address: undefined }));
});
}
}, [isConnected, state.isSignedIn]);
ERC-6492 Smart Wallet Support
The verify route should create a publicClient per chain to support smart contract wallet (Safe, Argent) signature verification. Maintain a SUPPORTED_CHAINS map and reject unknown chains:
import { createPublicClient, http, type Chain } from "viem";
import { mainnet, sepolia, hardhat /* ... */ } from "viem/chains";
const SUPPORTED_CHAINS: Record<number, Chain> = {
[mainnet.id]: mainnet,
[sepolia.id]: sepolia,
[hardhat.id]: hardhat,
};
// In verify route:
const chain = SUPPORTED_CHAINS[parsedMessage.chainId!];
if (!chain)
return NextResponse.json({ error: "Unsupported chain" }, { status: 400 });
const client = createPublicClient({ chain, transport: http() });
04 同仓库更多 Skills
x402
Add x402 payment-gated routes to a Scaffold-ETH 2 project. Use when the user wants to: monetize an API with micropayments, add HTTP 402 payment required to routes, gate content behind crypto payments, implement pay-per-call APIs, or integrate the x402 protocol.
why-ethereum
Why build on Ethereum specifically. The AI agent angle — ERC-8004, x402, composability, permissionless deployment. Use when a user asks "should I build on Ethereum?", "why blockchain?", or when an agent needs to recommend a chain for a project.
wallets
How to create, manage, and use Ethereum wallets. Covers EOAs, smart contract wallets, multisig (Safe), and account abstraction. Use this skill whenever you are sending transactions, signing messages, or managing funds. Includes guardrails for safe key handling.
tools
Current Ethereum development tools, frameworks, libraries, RPCs, and block explorers. What actually works today for building on Ethereum. Includes tool discovery for AI agents — MCPs, abi.ninja, Foundry, Scaffold-ETH 2, Hardhat, and more. Use when setting up a dev environment, choosing tools, or when an agent needs to discover what's available.
testing
Smart contract testing with Foundry — unit tests, fuzz testing, fork testing, invariant testing. Use when writing tests for a smart contract.
subgraph
Integrate The Graph subgraph into a Scaffold-ETH 2 project for indexing blockchain events. Use when the user wants to: index contract events with The Graph, add a subgraph, query onchain data with GraphQL, set up a local graph node, or deploy a subgraph to Subgraph Studio.