How to Generate a Seed

Relevant source files

The following files were used as context for generating this wiki page:

• index.html
• README.md

The qib13 tool provides a method to transform a simple, memorable 13-character "generator code" into a complex 55-character seed. This process is deterministic and reproducible, relying on a set of "Encoding Systems" that are themselves generated from a single "Master Seed". The core purpose is to allow users to work with simple inputs while benefiting from the security of a larger, permuted output.

This document details the technical process of generating a seed, from user input to the final 55-letter string. The process is primarily handled by the "Generate Seed" tab in the user interface and the underlying EncodingSystem class.

Sources: README.md:10-14, index.html:115-132

1. Prerequisites: System Generation

Before a seed can be generated, one or more EncodingSystem objects must be created. This is a preliminary step performed under the "Generate Systems" tab.

1. Master Seed: The user provides a Master Seed string. If left empty, a default value is used. This seed is the root of entropy for the entire process.
2. Number of Systems: The user specifies how many "deviation" systems to create in addition to the single "original" system.
3. Generation: Clicking "Generate Systems" triggers the generateSystems() function, which uses the CryptoSeededRandom class to deterministically create an array of EncodingSystem objects. Each system contains the matrices and permutations required for encoding.

This array of systems, stored in the global allSystems variable, is then available for the seed generation process.

Sources: index.html:89-98, 859-900, README.md:19-21

2. Seed Generation Flow

The seed generation process is initiated from the "Generate Seed" tab. It involves taking a user-provided generator code, selecting an encoding system based on the chosen mode, and executing the encoding logic.

Sources: index.html:115-132

This diagram illustrates the high-level flow from user interaction to the final output.

2.1. User Inputs

The user must provide two pieces of information on the "Generate Seed" tab.

UI Element	ID	Description
Generator Code Input	generatorCodeInput	A text field for the 13-character lowercase generator code.
Generation Mode	generateMode	A set of radio buttons to select which EncodingSystem to use for generation.
Specific System Index	generateSpecificSystemIndex	An input field that appears only for "Specific System" mode to select a system by its index (1-based).

Sources: index.html:116-128

2.2. Generation Modes

The selected mode determines which EncodingSystem from the allSystems array is used.

Mode	Description	EncodingSystem Selected
Original	Uses the first system, which has a unique structure.	allSystems[0]
Deviation	Uses the second system, which is the first "deviation" system.	allSystems[1]
Random	Selects a system at random from all available systems.	allSystems[randomIndex]
Specific	Uses the system at the user-specified index.	allSystems[systemIndex - 1]

Sources: index.html:119-122, 1029-1048

3. Core Encoding Logic

The core logic resides within the EncodingSystem class, which has two distinct methods for seed generation depending on its type: original or deviation.

The following sequence diagram shows the interactions when generateSeed() is called.

3.1. generateSeedOriginal()

This method is used by the first system (type: 'original'). It encodes the 13-character message into a 55-character codeword by adding 42 parity characters.

The process is as follows:

1. Validation: Ensures the generator code is exactly 13 lowercase letters.
2. Convert to Numbers: The 13 letters (a-z) are converted to an array of 13 numbers (0-25).
3. Calculate Parity: The 13-element vector is multiplied by a 42x13 matrix (P) modulo 26, producing a 42-element parity vector.
4. Negate Parity: Each element x in the parity vector is replaced with (-x + 26) % 26.
5. Form Codeword: The original 13-number message is concatenated with the 42-number negated parity vector, creating a 55-element codeword.
6. Permute: The 55 elements of the codeword are reordered according to the system's unique permutation map.
7. Convert to Letters: The resulting 55 numbers are converted back to letters (a-z) to form the final seed.

This flowchart details the steps within generateSeedOriginal.

3.2. generateSeedDeviation()

This method is used by all "deviation" systems (type: 'deviation'). It is similar to the original but uses two separate matrices (P1 and P2) to generate parity.

The process is as follows:

1. Validation: Ensures the generator code is exactly 13 lowercase letters.
2. Convert to Numbers: The 13 letters are converted to an array of 13 numbers.
3. Calculate Parity 1: The message vector is multiplied by a 15x13 matrix (P1) to produce a 15-element parity vector, which is then negated.
4. Calculate Parity 2: The message vector is multiplied by a 27x13 matrix (P2) to produce a 27-element parity vector, which is also negated.
5. Form Codeword: The message, negated parity 1, and negated parity 2 are concatenated: [message (13), negatedParity1 (15), negatedParity2 (27)], creating a 55-element codeword.
6. Permute: The 55 elements are reordered using the system's permutation map.
7. Convert to Letters: The permuted numbers are converted to letters to form the final seed.

// Snippet from generateSeedDeviation method
const message = this.lettersToNumbers(generatorCode);

const parity1 = this.matrixVectorMultiplyMod26(this.matrices.P1, message);
const negatedParity1 = parity1.map(x => (-x + 26) % 26);

const parity2 = this.matrixVectorMultiplyMod26(this.matrices.P2, message);
const negatedParity2 = parity2.map(x => (-x + 26) % 26);

const codeword = message.concat(negatedParity1).concat(negatedParity2);
const permutedCodeword = this.applyPermutation(codeword, this.permutation);
return this.numbersToLetters(permutedCodeword);

Sources: index.html:658-676

4. Summary

Generating a seed in qib13 is a multi-step encoding process that transforms a simple 13-letter generator code into a 55-letter seed. The process relies on pre-generated, deterministic EncodingSystem objects derived from a master seed. The choice of system is controlled by the user through different modes, adding a layer of flexibility. The encoding itself is a cryptographic-like process involving matrix multiplication to create parity data, followed by a permutation to obscure the original message within the final seed.

Sources: README.md:10-14, 92-98