When you create a new account, Ripple Custody derives the blockchain key from the key management system (KMS). The key derivation process depends on a number of factors, including the derivation strategy you choose and the capabilities of the ledger with which you associate the account.
For more information, about account creation, see Create accounts in the Ripple Custody API guide.
When you create a new Ripple Custody account, Ripple Custody assigns the account a derivation path p, which is a unique sequence of numbers representing the domain d and account number a. For hard derivations, this results in derivation path m/d'/a', where ' represents hard derivation and m is the master seed.
This derivation path p, together with the wrapped seed and the ledger dependent curve (secp256k1 or Ed25519) are transmitted to the KMS, which performs key derivation according to SLIP-0010. The KMS returns to Ripple Custody the derived extended public key, which is then stored in the database.
When Ripple Custody attempts to generate a transaction from the account, the vault requests the KMS to sign the transaction payload using the wrapped seed and the derivation path. Based on these parameters, the KMS deterministically derives the secret key, signs the provided data, and returns the signature to the vault.
For UTXO-based ledgers, such as Bitcoin, the KMS derives each UTXO account u based on the parent domain d and account a, resulting in derivation path: m/d'/a'/u.
The following diagram shows a hard derivation strategy, including hard derivation of the domain index and account index, which means that access to the private key is required in order to perform the derivation. For this reason, new account creation always needs direct access to the vault component.
At the bottom level, individual UTXO addresses are derived using a soft approach, which means that they are derived directly from the extended public key of the wallet, without a requirement to access the vault directly. This is particularly convenient for an infrastructure that includes a cold, disconnected vault. In cases such as this, creation of new accounts requires access to the vault for security reasons, but further requests to create addresses do not need direct access to the vault.
If you choose to create an account with a soft key derivation strategy, all derivations, right from the master seed downwards, are performed using a soft approach. This is only supported for ledger protocols based on Elliptic Curve Digital Signature Algorithm (ECDSA).
Additionally, for a KMS that doesn't support deterministic derivation schemes, you can use a random key strategy during account creation. With this strategy, keys are generated randomly with no key derivation. However, addresses within the account, if on a multi-address ledger protocol like Bitcoin, are generated with soft derivation, if the KMS supports it, and if not, with random generation.
With a random key strategy, the account cannot be recovered from the master seed, so it is essential to back up the database to prevent loss of data.
The following tables list the key derivation strategies available for each KMS-ledger combination. For more information about the strategies, see Blockchain keys.
| Key derivation strategy | Random | VaultSoft | VaultHard |
|---|---|---|---|
| Bitcoin |  | | |
| Ethereum | | | |
| XRPL | | | |
| Tezos | | | |
| Substrate | | | |
| Cardano | | | |
| Stellar | | | |
| Solana | | | |
| Algorand | | | |
| Hedera | | |
| Key derivation strategy | Random | VaultSoft | VaultHard |
|---|---|---|---|
| Bitcoin | | | |
| Ethereum | | | |
| XRPL | | | |
| Tezos | | ||
| Substrate | | ||
| Cardano | | ||
| Stellar | | ||
| Solana | | ||
| Algorand | | ||
| Hedera | |
For the ledgers listed in Derivation strategies by ledger, Ripple Custody supports derivation of several elliptic curves, where derivation of keys for a specific ledger requires the usage of a specific curve. For each identifier, the following derivation paths are available (where d is domain, a is account, and ' is hard derivation):
| Curve | secp256k1 | secp256k1 | Ed25519 | Ed25519 | Ed25519 |
|---|---|---|---|---|---|
| Identifier | secp256k1_CUSTODY_1 | secp256k1_CUSTODY_1 | Ed25519_CUSTODY_1 | Ed25519_CUSTODY_2 | Ed25519_STAKING_1 |
| Purpose | Custody - hard derivation | Custody - soft derivation | Custody - hard derivation | Custody - hard derivation | Staking - hard derivation |
| Bitcoin | d'/a' | d/a | |||
| Ethereum | d'/a' | d/a | |||
| XRPL | d'/a' | d/a | |||
| Tezos | d'/a' | ||||
| Substrate | d'/a' | ||||
| Cardano | d'/a'/0' | d'/a'/1' | |||
| Stellar | d'/a' | ||||
| Solana | d'/a' | ||||
| Algorand | d'/a' | ||||
| Hedera | d'/a' |
The two potential derivation based keys for identifier secp256k1_CUSTODY_1 refer to the key derivation strategy selected during creation of the account, that is, VaultHard or VaultSoft. For Random strategies, one different random key is generated per identifier.
We recommend a hard derivation strategy wherever possible.