What is regular key vs master key hierarchy?
Last updated:
The XRP Ledger implements a two-tier key hierarchy consisting of the master key and optional regular key, providing enhanced security and operational flexibility. The master key is the primary key pair derived from your account's seed phrase that provides ultimate control, while the regular key is an optional secondary key pair that can sign transactions on the account's behalf.
The master key is generated from your account's seed phrase using cryptographic derivation. This key pair defines the account's address - the XRPL address is actually a hash of the master public key. The master key has irrevocable authority over the account: it can always sign transactions unless explicitly disabled through account settings.
The regular key is an optional additional key pair assigned to an account through the SetRegularKey transaction. Once set, the regular key can sign transactions just like the master key. However, unlike the master key which is cryptographically tied to the account address, the regular key can be changed or removed at any time by the account owner.
The key hierarchy's security advantages are significant. By setting a regular key and disabling the master key for daily operations, you keep the master key in cold storage (offline, highly secure location) while using the regular key for routine transactions. If the regular key is compromised, you can use the master key to set a new regular key, limiting damage from key exposure.
Disabling the master key using the AccountSet transaction with asfDisableMaster flag prevents master key transaction signing. This configuration is common for high-security accounts: the regular key handles daily operations while the master key is stored securely offline, only used to change regular keys or re-enable itself if needed.
Re-enabling a disabled master key requires either the regular key or the master key itself (master keys can always re-enable themselves). This creates a recovery mechanism: even if the regular key is lost, the master key can re-enable itself and restore control. However, if both keys are lost, the account is permanently inaccessible.
The hierarchy supports various security models. Individual users might use regular keys for hot wallet operations while keeping master keys in hardware wallets. Businesses might assign regular keys to employees for daily operations while securing master keys in multi-signature vaults. Automated systems might use regular keys for transaction signing while master keys are air-gapped.
Changing regular keys uses the SetRegularKey transaction, which can be signed by either the current regular key or the master key. This flexibility allows key rotation without requiring the master key online, until you want to set a new regular key. Regular key changes take effect immediately in the validated ledger.
Removing the regular key returns the account to master-key-only operation. Send a SetRegularKey transaction without specifying a new key, and the account will no longer have a regular key. This might be done when no longer needing the security separation or when consolidating account management.
The cryptographic independence of regular keys from addresses is crucial. Your account address is derived from your master public key and never changes. Regular keys are separate key pairs with their own addresses. When you set a regular key, you're specifying the address of the key pair that should have signing authority.
Security trade-offs exist in the hierarchy. Using regular keys adds complexity - you must manage two key pairs instead of one. If you lose the regular key without master key backup, you must use the master key to set a new regular key. If you lose both keys, the account is permanently lost. Proper key management is essential.
Multi-signature accounts add another security layer beyond the master/regular key hierarchy. Accounts can be configured with signer lists requiring multiple signatures for transactions. This can combine with regular keys: perhaps the regular key is a multi-sig account itself, requiring multiple parties to sign transactions while a single master key provides backup control.
Common implementation patterns include: "hot wallet / cold storage" where regular key is in a hot wallet for quick access and master key in cold storage, "operational / recovery" where regular key handles operations and master key serves only for recovery, "employee / executive" where employees have regular key access and executives control master keys, and "automated / manual" where automated systems use regular keys and manual intervention requires master keys.
The regular key feature provides optional functionality - most casual users never set regular keys and use only their master keys. This is acceptable for small holdings or low-security-requirement accounts. The hierarchy becomes valuable for high-value accounts, institutional holdings, or security-conscious users.
Key rotation best practices recommend periodically changing regular keys even without suspected compromise, using regular keys for daily operations to minimize master key exposure, storing master keys in secure locations with backups, testing regular key functionality before disabling master keys, and documenting key management procedures.
Recovery scenarios demonstrate the hierarchy's value. If your regular key is compromised, immediately use your master key to set a new regular key, preventing the attacker from maintaining access. If your regular key is lost, use your master key to set a new one. If only your master key is lost but regular key works, you can continue operations (though you've lost recovery capabilities).
The master key's special status in the protocol provides ultimate security backstop. Even with complex signer lists and regular keys configured, the master key retains special privileges. This ensures account owners always have a recovery path, though it also means master key protection is paramount.
Developers building wallet software should support regular key configuration, provide clear UI for setting and changing regular keys, warn users about security implications of disabling master keys, and implement key management features that guide users toward secure practices without overwhelming them with complexity.