lea-improvement-proposals

• LIP: 12
• Layer: Application
• Title: Keyset File Format
• Author: Allwin Ketnawang
• Created: 2025-07-16
• Status: Proposed

Abstract

This LIP defines a standard JSON-based file format for storing the cryptographic keys required for a LEA account. The format encapsulates the Ed25519 secret key and the SPHINCS+ secret and public keys into a structured, compact, and machine-readable file. The primary goal is to ensure interoperability between different wallets, tools, and applications within the LEA ecosystem.

Motivation

To interact with the Lea network, a user must manage a set of cryptographic keys. Without a standardized format for storing these keys, each application (e.g., CLI tools, wallets, libraries) would be forced to implement its own proprietary storage method. This would lead to a fragmented ecosystem where users cannot easily move their accounts between different tools, increasing friction and the risk of key handling errors.

By defining a single, clear standard, this LIP ensures that a keyset generated by one tool (like lea-keygen) can be seamlessly used by any other compliant tool (like the ltm builder). This promotes interoperability, simplifies development, and improves the overall user experience.

Specification

A LEA Keyset file is a JSON file containing a single top-level array. The structure is defined as follows:

Root: A JSON Array with two elements.

• Element 1: Ed25519 Secret Key

  • Type: Array<number>
  • Description: An array of 64 integers, where each integer represents a byte of the Ed25519 secret key. The public key is implicitly the last 32 bytes of this secret key.

• Element 2: SPHINCS+ Keyset

  • Type: Array
  • Description: A nested array containing the SPHINCS+ secret and public keys.
    • Element 2.1: SPHINCS+ Secret Key
      • Type: Array<number>
      • Description: An array of 64 integers representing the bytes of the SPHINCS+ secret key.
    • Element 2.2: SPHINCS+ Public Key
      • Type: Array<number>
      • Description: An array of 32 integers representing the bytes of the SPHINCS+ public key.

JSON Structure Example

[
  // Element 1: Ed25519 Secret Key (64 bytes)
  [ 1, 2, 3, ..., 64 ],

  // Element 2: SPHINCS+ Keyset
  [
    // Element 2.1: SPHINCS+ Secret Key (64 bytes)
    [ 101, 102, 103, ..., 164 ],

    // Element 2.2: SPHINCS+ Public Key (32 bytes)
    [ 201, 202, 203, ..., 232 ]
  ]
]

Rationale

• JSON as a Base: JSON is a universally supported, human-readable format, making it an ideal choice for a simple key storage standard.
• Array of Arrays: This structure was chosen for its compactness and strict ordering. Compared to a JSON object with named keys, it reduces file size and removes ambiguity about property names. The fixed positions of each key make parsing simple and efficient.
• Array of Integers for Binary Data: Representing raw binary data as an array of byte-sized integers (0-255) is a standard, language-agnostic method that avoids the overhead and complexity of Base64 or hex string encoding within the JSON file itself.

Backwards Compatibility

This is a new, additive standard. It does not break any existing protocol rules or formats and will serve as the standard for all tools created after its acceptance.

Security Considerations

This file contains unencrypted private keys and is extremely sensitive.

• File Permissions: Any tool that creates a LEA Keyset file (e.g., lea-keygen) MUST set the file permissions to 0o600 (user-read-write only) to prevent unauthorized access by other users on the same system.
• Parsing: A compliant parser MUST validate the structure of the file, including the presence and lengths of all arrays, to prevent errors and potential vulnerabilities from malformed keyset files.

Copyright

This LIP is licensed under the MIT License.