controller-signers

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Controller Signers & Authentication

Controller 签名方与认证

Controller supports multiple authentication methods (signers) for flexibility and security.

Controller支持多种认证方式（签名方），兼顾灵活性与安全性。

Supported Signer Types

支持的签名方类型

Type	Description	Best For
`webauthn`	Passkey (biometric/hardware key)	Primary auth, most secure
`google`	Google OAuth	Easy onboarding
`discord`	Discord OAuth	Gaming communities
`twitter`	Twitter/X OAuth	Social integration
`argent`	Argent wallet (Starknet)	Starknet native users
`braavos`	Braavos wallet (Starknet)	Starknet native users
`metamask`	MetaMask (desktop only)	EVM users
`phantom-evm`	Phantom EVM mode (desktop only)	Multi-chain users
`rabby`	Rabby wallet (desktop only)	Security-focused users
`walletconnect`	WalletConnect (desktop only)	Cross-device
`password`	Email/password	Testing only

Warning: Password authentication is non-recoverable. If users lose their password, they permanently lose account access. Do not use in production.

类型	说明	适用场景
`webauthn`	密钥（生物识别/硬件密钥）	主认证方式，安全性最高
`google`	Google OAuth	便捷新用户注册
`discord`	Discord OAuth	游戏社区
`twitter`	Twitter/X OAuth	社交集成
`argent`	Argent钱包（Starknet）	Starknet原生用户
`braavos`	Braavos钱包（Starknet）	Starknet原生用户
`metamask`	MetaMask（仅桌面端）	EVM用户
`phantom-evm`	Phantom EVM模式（仅桌面端）	多链用户
`rabby`	Rabby钱包（仅桌面端）	注重安全的用户
`walletconnect`	WalletConnect（仅桌面端）	跨设备连接
`password`	邮箱/密码	仅测试使用

警告：密码认证方式不可恢复。若用户丢失密码，将永久失去账户访问权限。请勿在生产环境中使用。

Configuring Auth Options

配置认证选项

typescript

const controller = new Controller({
  signupOptions: [
    "webauthn",     // Passkeys
    "google",       // Google OAuth
    "discord",      // Discord OAuth
    "twitter",      // Twitter/X OAuth
    "argent",       // Argent wallet
    "braavos",      // Braavos wallet
    "metamask",     // MetaMask (desktop)
    "phantom-evm",  // Phantom (desktop)
    "rabby",        // Rabby (desktop)
    "walletconnect",// WalletConnect (desktop)
  ],
});

Order reflects UI order. With one option, branded buttons appear.

typescript

const controller = new Controller({
  signupOptions: [
    "webauthn",     // Passkeys
    "google",       // Google OAuth
    "discord",      // Discord OAuth
    "twitter",      // Twitter/X OAuth
    "argent",       // Argent wallet
    "braavos",      // Braavos wallet
    "metamask",     // MetaMask (desktop)
    "phantom-evm",  // Phantom (desktop)
    "rabby",        // Rabby (desktop)
    "walletconnect",// WalletConnect (desktop)
  ],
});

顺序对应UI显示顺序。若仅配置一种选项，将显示品牌化按钮。

Dynamic Authentication

动态认证

Override auth options per connection:

typescript

// Default options
const controller = new Controller({
  signupOptions: ["webauthn", "google", "discord"],
});

// Branded Phantom flow
await controller.connect(["phantom-evm"]);

// Branded Google flow
await controller.connect(["google"]);

可按连接请求覆盖认证选项：

typescript

// Default options
const controller = new Controller({
  signupOptions: ["webauthn", "google", "discord"],
});

// Branded Phantom flow
await controller.connect(["phantom-evm"]);

// Branded Google flow
await controller.connect(["google"]);

Branded Buttons

品牌化按钮

Single signer config shows branded styling:

typescript

// Shows "sign up with Phantom" button with Phantom branding
const controller = new Controller({
  signupOptions: ["phantom-evm"],
});

单一签名方配置将显示品牌化样式：

typescript

// Shows "sign up with Phantom" button with Phantom branding
const controller = new Controller({
  signupOptions: ["phantom-evm"],
});

Passkey Authentication

密钥认证

Platform support: iOS (Face ID/Touch ID), Android, Windows Hello, password managers (Bitwarden, 1Password).

Passkeys are backed up via:

Apple: iCloud Keychain
Android: Google account
Windows: Windows account

平台支持：iOS（Face ID/Touch ID）、Android、Windows Hello、密码管理器（Bitwarden、1Password）。

密钥通过以下方式备份：

Apple: iCloud钥匙串
Android: Google账户
Windows: Windows账户

Social Login

社交登录

Uses Auth0 + Turnkey wallet infrastructure:

Popup OAuth flow (fallback to redirect if blocked)
OIDC token validation with nonce
Turnkey wallet creation linked to social account

Native app limitation: OAuth may not work in webviews. Use passkeys for native apps.

基于Auth0 + Turnkey钱包基础设施实现：

弹出式OAuth流程（若被拦截则 fallback 至跳转）
使用随机数（nonce）验证OIDC令牌
创建与社交账户关联的Turnkey钱包

原生应用限制：OAuth在webview中可能无法正常工作。原生应用请使用密钥认证。

External Wallets

外部钱包

Starknet Wallets

Starknet钱包

Argent: Advanced security features, account management
Braavos: Built-in security features

Argent：高级安全功能、账户管理
Braavos：内置安全功能

EVM Wallets (Desktop Only)

EVM钱包（仅桌面端）

MetaMask: Popular browser extension
Rabby: Security-focused multi-chain
Phantom: Multi-chain with EVM support

MetaMask：主流浏览器扩展
Rabby：注重安全的多链钱包
Phantom：支持EVM的多链钱包

Cross-Platform

跨平台

WalletConnect: QR code or deep link connection

Note: EVM wallets are automatically hidden on mobile browsers.

WalletConnect：二维码或深度链接连接

注意：EVM钱包在移动浏览器中会自动隐藏。

Chain Switching

链切换

typescript

const success = await controller.externalSwitchChain(
  "metamask",  // wallet type
  chainId      // target chain (hex)
);

Braavos does not support chain switching.

typescript

const success = await controller.externalSwitchChain(
  "metamask",  // wallet type
  chainId      // target chain (hex)
);

Braavos不支持链切换。

Transaction Confirmation

交易确认

typescript

const response = await controller.externalWaitForTransaction(
  "metamask",
  txHash,
  30000 // timeout ms
);

if (response.success) {
  console.log("Receipt:", response.result);
} else {
  console.error("Error:", response.error);
}

typescript

const response = await controller.externalWaitForTransaction(
  "metamask",
  txHash,
  30000 // timeout ms
);

if (response.success) {
  console.log("Receipt:", response.result);
} else {
  console.error("Error:", response.error);
}

Multi-Signer Management

多签名方管理

Add backup signers via Settings > Signer(s) > Add Signer (Mainnet only).

To remove a signer:

Navigate to Settings > Signer(s)
Find the signer to remove
Click Remove option

Best practices:

Add 2-3 different signer types for recovery
Test each auth method periodically
Remove compromised signers promptly

通过设置>签名方>添加签名方添加备份签名方（仅主网可用）。

移除签名方步骤：

进入设置>签名方
找到要移除的签名方
点击移除选项

最佳实践：

添加2-3种不同类型的签名方用于账户恢复
定期测试每种认证方式
及时移除已泄露的签名方

Account Synchronization

账户同步

Argent and Braavos wallets auto-sync when user switches accounts in wallet. Controller registers

accountsChanged

listener and updates state automatically.

Note: Account synchronization is currently only available for Starknet wallets (Argent and Braavos). Other external wallets maintain existing connection behavior.

当用户在钱包中切换账户时，Argent和Braavos钱包会自动同步。Controller会注册

accountsChanged

监听器并自动更新状态。

注意：账户同步目前仅适用于Starknet钱包（Argent和Braavos）。其他外部钱包保持现有连接行为。

Platform-Specific Configuration

平台专属配置

typescript

const isMobile = /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);

const authOptions = isMobile
  ? ["webauthn", "google", "discord", "argent", "braavos"]
  : ["webauthn", "google", "discord", "argent", "braavos", "metamask", "walletconnect"];

await controller.connect(authOptions);

typescript

const isMobile = /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);

const authOptions = isMobile
  ? ["webauthn", "google", "discord", "argent", "braavos"]
  : ["webauthn", "google", "discord", "argent", "braavos", "metamask", "walletconnect"];

await controller.connect(authOptions);