igneum/docs/spec/08-client-security.md

Igneum protocol specification, section 8: client security

Spec version 0.1, 3 October 2026. Status of this section: Decided (3 October 2026, ledger G7 and X6). Nothing here is implemented. This section binds the official client (the one-click Igneum app on Windows, macOS and Linux, and the headless miner it wraps) and the project's release process. It binds no other client: any client is welcome, and a client that ignores this section is not an invalid node, only one the project did not ship.

The two findings it answers. An app that auto-updates on ten thousand machines is an admin key over the miners, the wallets the app made and the vote keys (G7). An installer that creates a wallet, holds keys and mines, promoted to people who have never run a miner, is a honeypot for fake copies and a target for every antivirus (X6). Both are true. The rules below name the key, bound it, and make the real app distinguishable from a fake by anyone who looks.

8.1 Reproducible builds

1. Every release of the official client MUST be reproducible: a build from the tagged source on the documented toolchain MUST produce byte-identical binaries on every supported platform.
2. The repository MUST carry, at the release tag, the hash of every released binary, the toolchain versions, and the command that reproduces the build.
3. A release whose hashes a third party cannot reproduce is withdrawn and the cause published.

8.2 The release key

1. Every release MUST be signed by the release key. The release key's public half is published in the genesis block and is therefore in every node's copy of the chain; it is also in the repository and on the domain.
2. The private half is held in hardware by the steward named in the published key policy. It never exists on a networked machine. The policy (who holds it, how a signature is produced, how the key is rotated or revoked) is published before the public testnet (O-8.1).
3. The client MUST refuse any update whose signature does not verify under the release key. A refused update is reported to the user, with the hash it saw, and the running version continues.
4. There are no silent updates. The client MAY check for a release and MUST show the version, its hash and the reproduction instructions; installation proceeds only when the user accepts it. The client never applies an update while mining without the user's acceptance for that version.
5. Rotation of the release key is itself a signed release under the old key, published with a stated reason and a stated date, and is the only path to a new key. A key that is lost is a key that is revoked by its own last signed release, and the client then accepts no update at all until the user installs a new client by hand from the repository.

8.3 The client cannot change consensus

1. Consensus rules change only through the upgrade path of section 5.7: new code activates when 90% of blue blocks in the signalling window carry the signal. A client release carries code; it carries no activation. The chain, not the app, decides when a rule takes effect, and 90% of miners have to say so in their blocks.
2. The client MUST NOT set a signalling bit without a user choice shown in the interface, and the default MUST be the choice the user last made, never the release's preference.
3. A release that changed a consensus rule without an activation signal would fork its users off the chain, which is the only thing a hostile release key can do to consensus, and it is visible to everyone within one block.

8.4 Distribution

1. Builds on every platform are notarised or signed with the platform's own mechanism (Apple notarisation, Windows Authenticode, a signed Linux package or AppImage) in addition to the release key.
2. Downloads are offered only from the project's domain and from the repository's release page. The hash of the file is shown beside every download button. No app store, mirror, torrent or third-party site is an official source, and the domain publishes the list of the only official sources.
3. Shipping a miner means antivirus products flag it. The app documents this and never asks the user to disable protection; it tells the user how to verify the hash instead.

8.5 Keys and the seed

1. The app creates the user's wallet locally. Before mining starts, the seed phrase MUST be shown and the user MUST confirm it (by re-entering the words or an equivalent check). Mining does not start until the confirmation succeeds.

2. The app MUST offer a hardware wallet as the destination for earnings, so a user who never wants a seed on the mining machine does not need one.

3. The seed is never transmitted, never backed up by the project, and never asked for by any update, support route or message. The permanent line, verbatim, appears wherever the app appears: on the download page, in the installer, on the seed screen and in every support channel:

   Nobody from Igneum will ever ask for your seed.

4. The vote key of section 3 is a separate key, created by the app and held by the app, and its loss costs the user weight, not coins (W5 of section 3 moves weight to a successor key). The app shows it as a mining key and never as a wallet.

8.6 Parameters in this section

Parameter	Value	Label
Release key publication	genesis block, repository, domain	Decided
Release key custody	hardware, held by the named steward, policy published before public testnet	Decided; policy Open (O-8.1)
Silent updates	none	Decided
Consensus activation through the client	impossible; 90% of blue blocks signalling (section 5.7)	Decided
Official download sources	the project's domain and the repository release page, hash shown beside the button	Decided
Seed shown and confirmed before mining	required	Decided
Hardware wallet option	required	Decided
The permanent line	"Nobody from Igneum will ever ask for your seed."	Decided, verbatim