Skip to content

Signer Management

Cartridge Controller supports multi-signer functionality, allowing you to add multiple authentication methods to your account for enhanced security and convenience. This feature is now generally available and enables you to sign in using different methods while maintaining access to the same Controller account and assets.

Overview

Multi-signer support provides several benefits:

  • Flexibility: Choose the authentication method that works best for each situation
  • Security: Distribute access across multiple secure authentication methods

Supported Signer Types

Controller supports four types of signers:

1. Passkey (WebAuthn)

  • Biometric authentication using Face ID, Touch ID, or hardware security keys
  • Platform-native security with device-based credential storage
  • Cross-platform compatibility with password managers like Bitwarden, 1Password
  • See Passkey Support for detailed setup information

2. Password Authentication

  • Password-based authentication with encrypted private key storage
  • Non-recoverable: Password loss means permanent account loss
  • Minimum requirements: 8-character minimum password length

⚠️ Important: Password authentication is currently marked as "Testing Only" and should not be used for production applications. Password loss results in permanent account access loss as there are no recovery mechanisms.

3. Social Login

Controller offers social login options through Google and Discord:

  • Streamlined onboarding for users with existing social accounts
  • Secure integration via Turnkey wallet infrastructure

Both Google and Discord login use an intelligent authentication flow that adapts to browser restrictions:

  1. Primary Method: Attempts to open OAuth in a popup window for a seamless experience
  2. Error Handling: Gracefully handles iframe restrictions and Content Security Policy (CSP) issues

4. External Wallets

Controller offers integration with popular external web3 wallets, including Braavos, MetaMask, Rabby, Base, and WalletConnect.

Adding Signers

Accessing Signer Management

  1. Connect to your Controller account using any existing authentication method
  2. Open the Settings panel within the Controller interface
  3. Navigate to the Signer(s) section
  4. Click Add Signer to begin adding a new authentication method

Note: Signer management is available on Mainnet only. The "Add Signer" button will be disabled on testnet environments.

Adding a Passkey

  1. In the Add Signer interface, select Passkey
  2. Your browser will prompt you to create a new Passkey using:
    • Device biometrics (Face ID, Touch ID, Windows Hello)
    • Hardware security key (USB, NFC, or Bluetooth)
    • Password manager (if configured for Passkey storage)
  3. Follow your device's authentication flow
  4. Once created, the Passkey will be added to your account

Adding Password Authentication

⚠️ Testing Only: Password authentication is available but marked for testing purposes only.

  1. In the signup or login interface, select Password from the authentication options
  2. For new accounts:
    • Enter a password (minimum 8 characters)
    • Confirm your password by entering it again
    • Review the security warning about password recovery
  3. For existing password accounts:
    • Simply enter your password to login
    • Password must match exactly (case-sensitive)

Security Warning: Password accounts cannot be recovered if you lose your password. This authentication method does not provide any recovery mechanisms, making it unsuitable for production use.

Adding Social Login

Adding Google Login

  1. Select Google from the signer options
  2. The system will attempt to open Google's OAuth authorization in a popup window
    • If the popup opens successfully, complete the authorization in the popup
    • If popups are blocked, you'll be automatically redirected to Google's OAuth page
  3. Sign in to your Google account if not already logged in
  4. Authorize Cartridge Controller to access your Google identity
  5. The Google login will be linked to your Controller account

Note: The authentication system automatically handles browser restrictions by falling back from popup to redirect mode when necessary. This ensures compatibility across different browsers and security settings.

Adding Discord Login

  1. Select Discord from the signer options
  2. The system will attempt to open Discord's OAuth authorization in a popup window
    • If the popup opens successfully, complete the authorization in the popup
    • If popups are blocked, you'll be automatically redirected to Discord's OAuth page
  3. Sign in to your Discord account if not already logged in
  4. Authorize Cartridge Controller to access your Discord identity
  5. The Discord login will be linked to your Controller account

Note: Discord authentication uses the same popup/redirect fallback system as Google login for maximum browser compatibility.

Adding External Wallets

  1. Select Wallet to see external wallet options
  2. Choose from the supported wallet types:
    • Braavos: Ensure Braavos extension is installed and unlocked
    • MetaMask: Ensure MetaMask extension is installed and unlocked
    • Rabby: Ensure Rabby extension is installed and unlocked
    • Base: Ensure Coinbase Base wallet is installed and unlocked
    • WalletConnect: Use QR code or deep link to connect mobile/desktop wallets
  3. Follow the wallet-specific connection flow
  4. Sign the verification message to link the wallet to your account

Managing Existing Signers

Viewing Your Signers

The Signer(s) section displays all authentication methods associated with your account:

  • Signer type with recognizable icons (fingerprint for Passkey, Discord logo, wallet icons)
  • Current status indicating which signer you're currently using
  • Identifying information such as wallet addresses (partially masked for privacy)

Signer Information Display

Each signer card shows:

  • Type: Passkey, Password, Google, Discord, Braavos, MetaMask, Rabby, or WalletConnect
  • Status: "(current)" label for the active authentication method
  • Identifier: Shortened wallet address for external wallets, or authentication type for others

Switching Between Signers

When connecting to your Controller:

  • The connection interface will show all available authentication methods
  • Select any of your registered signers to authenticate
  • Your account and assets remain the same regardless of which signer you use

Chain Switching for External Wallets

External wallets (Braavos, MetaMask, Rabby, Base, WalletConnect) support programmatic chain switching through the Controller interface. This allows applications to request that connected external wallets switch to a specific blockchain network.

Supported Functionality:
  • Automatic Chain Switching: Applications can programmatically request external wallets to switch chains
  • Cross-Chain Compatibility: Works with Ethereum, Starknet, and other supported networks
How It Works:
  1. Your application calls the chain switch method through the Controller
  2. The request is forwarded to the connected external wallet
  3. The wallet handles the chain switching process (may show user confirmation)
  4. The application receives confirmation of the successful chain switch
Example Usage: 
// Switch connected external wallet to a different chain
const success = await controller.externalSwitchChain(
  walletType, // e.g., "braavos", "metamask", "rabby", "base"
  chainId     // Target chain identifier
);

Note: Chain switching availability depends on the specific external wallet's capabilities and the target chain support.

Transaction Confirmation for External Wallets

External wallets (MetaMask, Rabby, Argent, WalletConnect) support waiting for transaction confirmations through the Controller interface. This allows applications to monitor transaction status and receive confirmation when transactions are mined.

Supported Functionality:
  • Transaction Monitoring: Wait for transaction confirmations with configurable timeouts
  • Receipt Retrieval: Returns transaction receipt upon successful confirmation
How It Works:
  1. Your application calls the wait method through the Controller after sending a transaction
  2. The request is forwarded to the connected external wallet
  3. The wallet polls the blockchain for transaction confirmation
  4. The application receives the transaction receipt or timeout error
Example Usage: 
// Wait for transaction confirmation with default timeout (60s)
const response = await controller.externalWaitForTransaction(
  walletType, // e.g., "metamask", "rabby"
  txHash      // Transaction hash from sendTransaction
);
}
 
// Wait with custom timeout (30 seconds)
const responseWithTimeout = await controller.externalWaitForTransaction(
  walletType,
  txHash,
  30000 // 30 seconds in milliseconds
);
Return Format: 
interface ExternalWalletResponse {
  success: boolean;
  wallet: string;
  result?: any;        // Transaction receipt when successful
  error?: string;      // Error message when failed
  account?: string;    // Connected account address
}
Error Handling:
  • Connection Errors: Wallet not available or not connected
  • Timeout Errors: Transaction not confirmed within the specified time
  • Network Errors: RPC or blockchain connectivity issues
  • Transaction Failures: Transaction reverted or failed on-chain

Note: Transaction confirmation times vary by network conditions and the specific blockchain. Ethereum transactions typically confirm faster than other networks during low congestion periods.

Security Considerations

Best Practices

  • Multiple Backups: Add at least 2-3 different signer types to ensure account recovery
  • Secure Storage: For Passkeys, ensure your device backup (iCloud, Google) is secure
  • Regular Access: Periodically test each authentication method to ensure they work

Account Recovery

If you lose access to your primary authentication method:

  1. Use any other registered signer to access your account
  2. Consider adding additional backup authentication methods
  3. Remove compromised signers using the remove signer functionality

Removing Signers

You can now remove signers from your account for security or convenience:

  1. Navigate to the Signer(s) section in Controller Settings
  2. Find the signer you want to remove
  3. Click the Remove option for that signer

Important: Ensure you have at least one other working authentication method before removing a signer to avoid losing access to your account.

Current Limitations

  • Mainnet Only: Signer management is currently restricted to Mainnet
  • No Hierarchy: All signers have equal access; there's no primary/secondary distinction

Getting Help

If you encounter issues with signer management:

  • Check the Passkey Support guide for WebAuthn-specific help
  • Verify your wallet setup in the respective wallet's documentation
  • Ensure you're using a supported browser and have the latest wallet extensions installed

Next Steps