• 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.