zklogin

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

zkLogin Skill

MCP tool: When available in your environment, also query the Sui documentation MCP server (
https://sui.mcp.kapa.ai
) for up-to-date answers. Use it for verification and for details not covered by these reference files.

Source constraint: All information in this skill is sourced exclusively from docs.sui.io/concepts/cryptography/zklogin. When extending or updating this skill, only pull from this source. Do not use third-party blogs, tutorials, or unofficial documentation.

zkLogin is a Sui primitive that lets users log in with their existing OAuth credentials (Google, Facebook, Apple, etc.) instead of managing a traditional crypto wallet. It uses zero-knowledge proofs to link an OAuth identity to a Sui address without revealing the OAuth identifier onchain. Common AI-coding mistakes include confusing the roles of the salt, ephemeral key, and ZK proof in the security model, assuming a leaked JWT means compromised funds, and not understanding that addresses are permanent but sessions are ephemeral.

This skill routes to focused reference files. Load only the ones relevant to the current task.

All patterns in this skill are derived from: https://docs.sui.io/concepts/cryptography/zklogin

If unsure about any detail, fetch the relevant page before answering. Do not guess or extrapolate from other authentication systems.

MCP 工具： 如果你的环境中提供 Sui 文档 MCP server（
https://sui.mcp.kapa.ai
），还应查询该服务器以获取最新答案。将其用于验证，以及获取这些参考文件未涵盖的详细信息。

来源约束： 本 Skill 中的所有信息均仅来自 docs.sui.io/concepts/cryptography/zklogin。扩展或更新本 Skill 时，只能从此来源提取内容。请勿使用第三方博客、教程或非官方文档。

zkLogin 是 Sui 的一项基础原语，允许用户使用现有的 OAuth 凭证（Google、Facebook、Apple 等）登录，而无需管理传统加密钱包。它使用零知识证明将 OAuth 身份与 Sui 地址关联起来，同时不在链上公开 OAuth identifier。在 AI 编码中，常见错误包括混淆 salt、ephemeral key 和 ZK proof 在安全模型中的作用，误以为泄露 JWT 就意味着资金被盗，以及没有理解地址是永久的而会话是临时的。

本 Skill 会将请求路由到相应的参考文件。仅加载与当前任务相关的文件。

本 Skill 中的所有模式均源自： https://docs.sui.io/concepts/cryptography/zklogin

如果对任何细节不确定，请在回答前获取相关页面。不要猜测，也不要从其他认证系统进行推断或外推。

Reference files

参考文件

architecture -- Architecture and Protocol Flow

architecture -- 架构与协议流程

Path:

architecture.md

Load when: the user asks how zkLogin works internally, about the three key entities (frontend, salt service, proving service), the 10-step protocol flow, address derivation, session lifetime, the Groth16 ceremony, or the role of JWTs and nonces. Covers: three key entities, JWT structure, protocol flow (10 steps), address derivation formula, session lifetime and ephemeral key expiry, key notations, Groth16 ceremony.

Path：

architecture.md

Load when： 用户询问 zkLogin 的内部工作原理、三个关键实体（frontend、salt service、proving service）、10 步协议流程、地址派生、会话生命周期与 ephemeral key 过期、Groth16 ceremony，或 JWT 与 nonce 的作用时，加载此文件。 Covers： 三个关键实体、JWT 结构、协议流程（10 步）、地址派生公式、会话生命周期与 ephemeral key 过期、密钥记号、Groth16 ceremony。

integration -- Integration Guide

integration -- 集成指南

Path:

integration.md

Load when: the user needs to integrate zkLogin into an application, choose a supported OpenID provider, verify signatures offchain, understand security tradeoffs, or troubleshoot common issues. Covers: supported OpenID providers by network, implementation steps, offchain signature verification methods, security considerations, FAQ.

Path：

integration.md

Load when： 用户需要将 zkLogin 集成到应用、选择受支持的 OpenID provider、在链下验证签名、了解安全权衡或排查常见问题时，加载此文件。 Covers： 按网络划分的受支持 OpenID provider、实现步骤、链下签名验证方法、安全注意事项、FAQ。

Routing guide

路由指南

Task	Load
Explaining what zkLogin is	SKILL.md only
Understanding the protocol flow	architecture
Understanding address derivation	architecture
Understanding session lifetime and ephemeral keys	architecture
Choosing an OpenID provider	integration
Integrating zkLogin into an app	integration
Verifying zkLogin signatures offchain	integration
Understanding security properties	integration
Answering zkLogin FAQ	integration
Full deep dive on zkLogin	all reference files

任务	加载
解释 zkLogin 是什么	仅 SKILL.md
了解协议流程	architecture
了解地址派生	architecture
了解会话生命周期与 ephemeral key	architecture
选择 OpenID provider	integration
将 zkLogin 集成到应用	integration
在链下验证 zkLogin 签名	integration
了解安全属性	integration
回答 zkLogin FAQ	integration
全面深入了解 zkLogin	所有参考文件

Skill Content

Skill 内容

Key concepts

核心概念

Wallet-less login. zkLogin lets users transact on Sui using OAuth credentials (Google, Facebook, Apple, etc.) instead of managing seed phrases or private keys. The user's OAuth identity maps to a deterministic Sui address.
Three key entities. The system involves three components: (1) the application frontend that manages ephemeral keys and OAuth flow, (2) a salt service that returns a consistent unique salt per user, and (3) a proving service that generates zero-knowledge proofs.
Ephemeral key pairs. Each session uses a short-lived key pair. The ephemeral public key, a max epoch, and randomness are embedded in the OAuth nonce. When the epoch passes max_epoch, the user logs in again and generates a new key pair and ZK proof but continues using the same Sui address.
Zero-knowledge proofs. A Groth16 zkSNARK proof validates that the nonce was derived correctly, the key claim value matches the JWT, the RSA signature is valid, and the address is consistent with the key claim and salt -- all without revealing the OAuth subject identifier onchain.
Permanent addresses. The Sui address derived from zkLogin is permanent. It does not change unless the sub, iss, aud, or user_salt changes. Different providers or applications produce different addresses for the same user.

免钱包登录。 zkLogin 允许用户使用 OAuth 凭证（Google、Facebook、Apple 等）在 Sui 上进行交易，而无需管理 seed phrase 或 private key。用户的 OAuth 身份会映射到一个确定性的 Sui 地址。
三个关键实体。 系统包含三个组件：(1) 管理 ephemeral key 和 OAuth flow 的应用 frontend，(2) 为每位用户返回稳定且唯一 salt 的 salt service，(3) 生成零知识证明的 proving service。
Ephemeral key pair。 每个会话使用一对短生命周期的 ephemeral key。ephemeral public key、max epoch 和 randomness 会嵌入 OAuth nonce。当 epoch 超过 max_epoch 时，用户需要重新登录并生成新的 key pair 和 ZK proof，但仍继续使用同一个 Sui 地址。
零知识证明。 Groth16 zkSNARK proof 会验证 nonce 是否正确派生、key claim value 是否与 JWT 匹配、RSA signature 是否有效，以及地址是否与 key claim 和 salt 一致——同时不在链上披露 OAuth subject identifier。
永久地址。 从 zkLogin 派生出的 Sui 地址是永久的。除非 sub、iss、aud 或 user_salt 发生变化，否则该地址不会改变。不同 provider 或不同应用会为同一用户生成不同的地址。

Rules

规则

Never conflate JWT leaks with fund compromise. A leaked JWT can compromise privacy but cannot steal funds as long as the ephemeral private key is safe.
Never assume the ZK proof alone authorizes transactions. Both the ephemeral signature and the ZK proof are required; neither is sufficient on its own.
Always explain that the salt is critical for both privacy and access. The salt unlinks the OAuth identifier from the onchain address. Losing the salt means permanent loss of access.
Always note that iss, aud, and kid are revealed onchain. The JWT itself is not published onchain, but these three fields are visible.
Never suggest converting a traditional wallet to a zkLogin address. They use different address derivation schemes and are not interchangeable.

切勿将 JWT 泄露等同于资金被盗。 只要 ephemeral private key 安全，泄露的 JWT 可能会损害隐私，但无法盗取资金。
切勿假设仅凭 ZK proof 就能授权交易。 必须同时具备 ephemeral signature 和 ZK proof；单独任一项都不充分。
务必说明 salt 对隐私和访问权限都至关重要。 salt 将 OAuth identifier 与链上地址解除关联。丢失 salt 将永久失去访问权限。
务必指出 iss、aud 和 kid 会在链上公开。 JWT 本身不会发布到链上，但这三个字段是可见的。
切勿建议将传统钱包转换为 zkLogin 地址。 两者使用不同的地址派生方案，无法互换。

Common mistakes

常见错误

Assuming a leaked JWT means stolen funds. The JWT alone is not enough. An attacker also needs the ephemeral private key and salt to create valid transactions.
Forgetting that proofs are session-scoped. A ZK proof is valid only until the ephemeral key expires (max_epoch). Proofs cannot be reused across sessions, but can be cached and reused within a session.
Ignoring the salt's role in privacy. Without the salt, there is no link between the OAuth subject and the Sui address. If the salt leaks, the link becomes visible, though funds remain safe.
Assuming all providers work on all networks. Some providers (Slack, Kakao, Microsoft) are available on Devnet and Testnet only — not Mainnet. Others (RedBull, Amazon, WeChat, Auth0, Okta) are under review.

误以为泄露 JWT 就意味着资金被盗。 仅凭 JWT 并不够。攻击者还需要 ephemeral private key 和 salt，才能创建有效交易。
忘记 proof 的作用域仅限于会话。 ZK proof 仅在 ephemeral key 过期（max_epoch）之前有效。Proof 不能跨会话复用，但可以在同一会话内缓存和复用。
忽略 salt 在隐私方面的作用。 没有 salt，OAuth subject 与 Sui 地址之间就不存在关联。如果 salt 泄露，这一关联将变得可见，但资金仍然安全。
假设所有 provider 都能在所有网络上使用。 某些 provider（Slack、Kakao、Microsoft）仅适用于 Devnet 和 Testnet，不适用于 Mainnet。其他 provider（RedBull、Amazon、WeChat、Auth0、Okta）正在审查中。