> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quantumapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Accounts and keys

> Generate post-quantum keypairs, derive addresses, and manage keystores on Quantum Chain.

A Quantum Chain account is a **post-quantum keypair** with a 20-byte address derived from the public key.

| Property      | Description                                                                     |
| ------------- | ------------------------------------------------------------------------------- |
| Public key    | Lattice-based post-quantum public key (large; bound to the wallet)              |
| Private key   | Held by the signer; never leaves the secure boundary                            |
| Address       | First 20 bytes of `Keccak-256(publicKey)` displayed as `0x` + 40 hex chars      |
| Mnemonic      | Optional 12-word BIP-39 phrase used to deterministically regenerate the keypair |
| Keystore file | JSON file that holds the encrypted private key; AES-128-CTR + PBKDF2            |

The address format is identical to Ethereum on the wire, so existing block explorers, ABIs, and address-checksum logic work unchanged.

## Tools

| Binary         | Purpose                                                                 |
| -------------- | ----------------------------------------------------------------------- |
| `keygenerator` | Create a new account or recover from a mnemonic                         |
| `ethkey`       | Inspect, extract, or re-encrypt keystore files                          |
| `clef`         | External signer that holds keys and authorizes signatures interactively |

All three are produced by `make all`.

## Create a new account

```bash theme={null}
./build/bin/keygenerator --passphrase "strong-pass"
```

Output:

```
Mnemonic: clip cousin frame ...
Address: 0xfF81E5c74E14DB5B4EE407d66B1B063C8F305c51
Public key: 0xa288bd50d4d48a02...
Keystore file written: UTC--2025-11-10T13-50-41.305Z--0xfF81...
```

<Warning>
  The mnemonic is displayed once and never written to disk. Store it offline. Anyone with the mnemonic can regenerate the private key.
</Warning>

The keystore file is written to the current directory. Move it into a `keystore/` folder under your `--datadir`:

```bash theme={null}
mkdir -p ~/.quantum-chain/keystore
mv UTC--*.json ~/.quantum-chain/keystore/
```

## Recover from a mnemonic

```bash theme={null}
./build/bin/keygenerator \
  --passphrase "strong-pass" \
  --recover "clip cousin frame ..."
```

The recovered keypair is deterministic — the same mnemonic always produces the same address.

## Inspect a keystore

```bash theme={null}
./build/bin/ethkey inspect path/to/keystore.json
# Prompts for passphrase, prints address and public key
```

## Sign messages offline

```bash theme={null}
./build/bin/ethkey sign \
  --keyfile path/to/keystore.json \
  --message-file message.txt
```

Returns the post-quantum signature in hex.

## Keystore format

```json theme={null}
{
  "address": "ff81e5c74e14db5b4ee407d66b1b063c8f305c51",
  "crypto": {
    "cipher": "aes-128-ctr",
    "ciphertext": "...",
    "cipherparams": { "iv": "..." },
    "kdf": "pbkdf2",
    "kdfparams": {
      "c": 262144,
      "dklen": 32,
      "prf": "hmac-sha256",
      "salt": "..."
    },
    "mac": "..."
  },
  "id": "uuid-v4",
  "version": 3
}
```

The `ciphertext` holds the encrypted post-quantum private key. The schema matches the standard Ethereum Web3 secret-storage definition, so any tool that can decrypt a Web3 keystore can decrypt a Quantum Chain keystore — the difference is only what the plaintext represents.

## Use a keystore with geth

```bash theme={null}
geth \
  --datadir ~/.quantum-chain \
  --networkid 20803 \
  --unlock 0xfF81E5c74E14DB5B4EE407d66B1B063C8F305c51 \
  --password ./password.txt \
  --allow-insecure-unlock
```

<Warning>
  `--unlock` and `--allow-insecure-unlock` are intended for development only. In production use [Clef](/quantum-chain/signing-transactions) or an external signing service.
</Warning>

## Use Clef for hot signing

[Clef](https://geth.ethereum.org/docs/tools/clef/introduction) ships with this repository and is updated to handle post-quantum signing.

```bash theme={null}
./build/bin/clef --keystore ~/.quantum-chain/keystore --chainid 20803
```

Clef listens on a Unix socket and prompts you (or your custom rule script) for each signing request. Connect geth to clef with `--signer /path/to/clef.ipc`.

## Use a custody platform

For multi-user, audited, policy-driven signing, use [Qustody](/qustody/security-model). Qustody never holds private keys; it orchestrates signing through an external post-quantum signer that you control.

## Where to go next

* [Signing transactions](/quantum-chain/signing-transactions)
* [Sending transactions](/quantum-chain/sending-transactions)
* [Move from local signing to custody](/guides/move-from-local-signing-to-custody)