WALLET-TECHNICAL-STANDARD

Timeline

• 2026-05-28 — d45eed2 — Chore: mirror blochain specs into github/mdbook (#347)

Revision History

Introduction

The main motivation behind this spec is avoiding being locked into a wallet software. By specifying the algorithms used to derive keys, we allow users to easily migrate from one implementation to the other.

Overview

This document mostly follows pre-existing standards in Bitcoin and adapts it to Logos’ needs when necessary. This is also the choice of other Bitcoin-inspired projects like Cardano or Zcash. For this reason, this document will not go over the entire spec itself, and just highlight differences with existing standards.

Mnemonic codes for key generation

Mnemonic codes are far easier to interact with as humans than raw binary or hex strings and are the standard for wallets. In this regard we can reuse BIP-39 entirely, as it’s just operations on strings and bytes.

Hierarchical Deterministic wallet

Hierarchical Deterministic (HD) wallets are nowadays the standard. Using a single source of entropy (usually obtained through the process above), it’s possible to generate many different addresses and share all or part of it.

The industry standard is BIP32. However, we can’t use it as it is, as we use different keys and cryptographic components. In addition, some of the BIP32 features are only possible thanks to homomorphic properties of ECC, which we don’t have in the Logos Blockchain since we use hash-based sk/pk.

BIP-32 specifies two kinds of child keys:

• Normal: you can derive a child public key from the parent public key
• Hardened: you need the parent private key to derive a child private and public key

Unfortunately, ‘normal’ children are possible thanks to specific properties of the keys used in Bitcoin that we don’t have in the Logos Blockchain (namely, homomorphism).

To maintain compatibility, we will still use the same structure but non-hardened children will not be available.

Extended Keys (from BIP32)

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k, c), with k the normal private key, and c the chain code. An extended public key is represented as , with the public key and the chain code.

Each extended key has  hardened children keys. Each of these child key has an index. The hardened child keys use indices from  through .

Details

The main novelty with respect to the aforementioned protocols is one last additional step before obtaining a secret key that can be used in the Logos Blockchain network, described in ZK-Compatible Secret Key Derivation in the Logos Blockchain.

For the remaining procedures, we only highlight the differences instead of going over all the details again as they’re already covered extensively elsewhere.

Notation:

• : the parent extended key, composed of the private key and the chain code .
• : serialize a 32-bit unsigned integer i as a 4-byte sequence, most significant byte first.
• : refers to unkeyed BLAKE2b-512 in sequential mode, with an output digest length of 64 bytes, 16-byte personalization string p, and input x.
• , a pseudo-random function.

Child Key Derivation

• Check whether  (whether the child is a hardened key).

  • If so (hardened child): let .
  • If not (normal child): failure.

• Split into two 32-byte sequences, .

• The returned child key  is .

• The returned chain code  is .

Master Key Generation

• Generate a seed byte sequence of a chosen length (e.g. with BIP0039)
• Calculate
• Split into two 32-byte sequences,  and .
• Use as master secret key, and  as master chain code.

ZK-Compatible Secret Key Derivation in the Logos Blockchain

Since we make extensive use of ZK proofs, we need our secret → public derivation to be efficient. For this purpose, we use a ZK-optimized hash function: Poseidon2.

However, Poseidon2 operates on field elements rather than raw bytes, so we cannot simply input as specified above. Instead, we must encode these bytes into field elements. Using the parameters described in Use in the Logos Blockchain:, we need two field elements to encode 32 bytes (the size of ). This creates inefficiency because although a single field element provides adequate security, we must use twice as many, increasing computation costs to accommodate the entire key.

To reduce this additional cost inside the proof, we apply one final hash function that compresses these two field elements into a single one, which becomes the actual key used in the Logos Blockchain network:

Let be 16-byte sequences such that and be their values when interpreted as little-endian unsigned integers. Let be scalar field elements in BN254 such that . The Logos key can be obtained as , where outputs a single field element.

Why not use Poseidon2 for the full derivation? While Poseidon2 is optimized for ZK circuits, its long-term stability and parameterization are still evolving. General-purpose hash functions like Blake2b offer a more stable and audited base layer. By introducing Poseidon2 only at the last compression step we isolate ZK-dependencies from the rest of the key derivation path. This ensures the wallet hierarchy remains valid even if Poseidon2 parameters are updated.

References

ZIP 32: Shielded Hierarchical Deterministic Wallets

CIP-0003

slip-0023

bip-0039

bip-0032