How LocalCryptos Wallets Are Generated
4 mins
LocalCryptos wallets are purely non-custodial crypto wallets. Unlike on centralized exchanges, wallet private keys are never known by LocalCryptos; we don't take custody of users' cryptocurrency. The secret keys are accessed solely by user devices and the LocalCryptos interface utilizes the Web Cryptography API to digitally sign transactions.
This technical article describes how those private keys are generated using a deterministic key derivation process, and how they're encrypted.
If you previously backed up a LocalCryptos wallet and need to recover your cryptocurrency, you can use the free and open source LocalCryptos Wallet Backup Explorer tool. Simply follow that link and read the instructions.
The current standard (non-HD)
LocalCryptos wallets are organized in a way that is different to other wallets. They don't follow the hierarchical deterministic (HD) standard that many other wallets conform to.
The decision to not implement a HD wallet format dates back to 2017 when LocalCryptos was known as LocalEthereum, a P2P trading application running on the Ethereum network. We opted to use a 'simpler' wallet type at the time — a deterministic but not hierarchically-deterministic key generation process — because the features that BIP32-HD wallets provide wouldn't have been useful to early users of LocalEthereum.
After launching Bitcoin P2P trading on LocalCryptos, we realized that the decision not to use a HD wallet format was a design mistake, as it meant LocalCryptos wallet backups aren't directly compatible with other major wallets, resulting in a longer procedure for users to recover and access keys stored in a backup.
We have plans to migrate to a standardized HD wallet format in the future to improve usability. However, because so many wallets have already been generated using our non-HD scheme, transitioning to a different format is a challenging upgrade. When we make that upgrade, we'll update this article.
The most important difference between a hierarchical deterministic wallet and the non‐hierarchical deterministic wallet system used by LocalCryptos is that hierarchical wallets use a master public key system. A master public key allows observers to calculate the wallet's other addresses by looking at a single public key. In the deterministic implemented by LocalCryptos, it's not possible to calculate other addresses from one public key as there's no cryptographic relationship between public keys.
While LocalCryptos wallets are not 'hierarchically' deterministic, they are still deterministic. This means that each wallet includes a virtually infinite number of addresses because each key is derived from a single seed. There is no need to backup each address individually.
Racheting key generation
Each address in a LocalCryptos wallet contains an assigned index number beginning from zero. This index number is known colloquially as n. There can't be any skipped indices.
Each LocalCryptos wallet begins with a random 32‐byte seed known as the zero‐index chain key (chainKey0).
The seed can be used to determine the private key for the wallet's first address (address0) and any subsequent addresses, making the system a deterministic wallet.
The private key for addressn can be determined from chainKeyn, and chainKeyn can be determined from chainKeyn-1. Hence, if you know chainKeyn then you can determine addressm, where m is any number between n and infinity.
For this simple ratcheting algorithm, we use a common one‐way hashing function called HMAC‐SHA256. The calculations are as follows for every n-index chain key:
- The
n-index address private key (addressn) is HMAC‐SHA256(chainKeyn, 0x0001). - The next chain key (
chainKeyn+1) is HMAC‐SHA256(chainKeyn, 0x02).
This simple ratcheting system is illustrated in the diagram below. Remember that each arrow represents a one‐way hashing function; it is impossible to go backward along any arrow.
As you can see from the illustration, accidentally divulging one address's private key won't impact the rest of a wallet because of the one-directional nature of the key derivation processes. In addition, if somebody was able to get their hands on a chain key, they would only be able to calculate 'future' addresses; they couldn't gather any information about addresses before it.
Storing keys
Chain keys are encrypted using AES‐256 to an account's root encryption key. Once encrypted, the ciphertext is submitted to the LocalCryptos API for long-term availability, enabling cross-device synchronicity.
Only the first chain key (chainKey0) needs to be encrypted and saved when a wallet is first created, however saving more keys would mean that older chain keys could be safely erased in the future.
As the keys are encrypted on the client-side before they're uploaded, LocalCryptos can't access them.
Wallet backups
Backing up a LocalCryptos wallet means to simply export the earliest chain key available. An example backup file might look like this:
{
"export": {
"version": "1.0",
"created_at": "2018-01-01"
},
"wallet": {
"id": "08ff9422-552e-4803-a808-8ebb054950f6",
"version": "1.0"
},
"first_address": {
"address": "0x153eac21fc4e66ede5fcae1c763e094dd8e96dc6",
"wallet_address_n": 0
},
"chain_private_key": "08ff942248034f6019cc63550f053300871b1f4ea18ef48035c3611cb9b25b4f"
}
The important part is chain_private_key, which can be used to calculate every address in the wallet.
To test that you're ratcheting keys and calculating addresses correctly, the first address in the back up file should be first_address → address. The first_address → wallet_address_n number is the earliest index available at the time of the backup.
How can I recover a LocalCryptos wallet backup?
Anyone can use the free and open source LocalCryptos Wallet Backup Explorer tool to inspect a wallet backup file and extract individual address private keys. Those address private keys can then be imported into other wallets.
