KISS Signer Docs

01 / start here

How signing works

Your keys never leave this device. The online half is a separate app, called a coordinator.

A QR code or an SD card carries each hop. No cable, no radio, and nothing that can spend ever crosses.

Pair a watch-only wallet
On this device
KISS shows a QR of your public keys, a descriptor or a zpub. Your coordinator can then see the balance and hand out addresses. It cannot spend.
Build the transaction there
On your coordinator
It picks the coins and the fee and makes a PSBT: a transaction with no signature yet.
Verify and sign here
On this device
Hand the PSBT over by QR or microSD. KISS recomputes every amount itself, shows you, and signs only on a deliberate hold.
Broadcast from the coordinator
On your coordinator
Carry the signed transaction back the same way. The coordinator broadcasts it.

Pairing offers Sparrow and BlueWallet. Anything else works if it does both halves. It has to import a watch-only descriptor, and pass PSBTs by QR or microSD. Anything untried, ask in Telegram.

02 / features

What it does

DECOY SIGNER

It boots into a game

FRUIT ISLAND is a real, playable game. One secret gesture opens the signer; another opens a spare set of keys, so there is always something to show.

TOUCHSCREEN + QR

Transactions in and out by QR, or microSD

A transaction does not fit in one QR. KISS splits it into numbered frames and loops them for your coordinator’s camera, the BC-UR scheme. Or carry the file on a card. No cable ever carries your data.

1 / 8

One transaction, eight frames, played on a loop. Your coordinator’s camera collects them in any order and rebuilds the whole thing. A code that keeps changing is working, not broken.

PRIVACY

Silent payments

One sp1 address you can hand out repeatedly, without the privacy cost of address reuse. An optional scan key lets your coordinator find those payments, never spend them.

VERIFIED ON DEVICE

Nothing is signed unseen

Every amount, the fee and the change are recomputed here, not taken on trust. Anything risky turns amber before you can sign.

22 LANGUAGES

Including CJK and Cyrillic

Each with its own font. Buttons resize rather than truncate, and the build fails if a key action gets too small to read.

AUDIT IT YOURSELF

It checks its own randomness

Keys are only as good as the entropy behind them, so the device audits its own: 5000 samples from the chip into a live histogram, scored for evenness. A lopsided chart means bad randomness.

The RANDOMNESS AUDIT screen: a histogram of 5000 samples counted into 100 groups, a spread score of 105.920 inside a fair range of 61.137 to 148.230, marked EVEN and ON CHIP — A fair chip fails this about one run in 500, so one lopsided chart means run it again, not throw the board away.

03 / the device

The device, and the one mod it needs

Three boards, no soldering: the Guition JC4880P443C (4.3in), the Waveshare ESP32-P4-WIFI6-Touch-LCD-3.5 (3.5in) and the Guition JC1060P470C (7in). Each has a colour touchscreen, a camera and a microSD slot. The one job left to you is making sure the camera faces out the back, away from you.

The firmware runs on boards with a v1.x ESP32-P4 chip. Boards with the newer v3.x chip are not supported yet; esptool prints the revision when it connects.

About the radio

The ESP32-P4 has no WiFi and no Bluetooth in silicon. The board carries a second chip that does, because the board is sold for other products too. KISS holds that chip in reset before anything else runs, and ships no wireless code at all.

Do not take our word for it. The home screen and Settings show radio: held in reset, read from the chip each time rather than printed from memory. With a multimeter, measure the radio’s off switch on pin GPIO54 and watch it sit at zero volts.

Flip the camera (one-time, required for QR scanning)

On the Guition 4.3in the camera ships facing the user. Reading a QR from your coordinator needs it facing out. Simple but fiddly:

Lift the screen off with a small suction cup tool.
Pry the tape off the camera module (fingernails work), flip it so the lens faces out the back, and tape it to the pad behind.
The three side buttons fall out and are hard to seat again. Tack them down with a dab of glue or tape before closing up.

Take it slow with the suction cup: you are lifting a display, not a case lid.

04 / trust, then flash

Check the download before you trust it

Everything for a release sits on the GitHub Releases tab:

kiss-signer-<version>.bin — the firmware, for the Guition 4.3in
kiss-signer-<version>-ws35.bin — the firmware for the Waveshare 3.5in
kiss-signer-<version>-jc1060.bin — the firmware for the Guition 7in
SHA256SUMS — its hashes
SHA256SUMS.asc — the signature over those hashes
kiss_signer_pgp.asc — the key that signed them

Beside them, kiss-signer-<version>-offline.zip carries the same firmware with an install page and this guide, for flashing with no network. It has its own signature.

gpg --import kiss_signer_pgp.asc
gpg --verify SHA256SUMS.asc SHA256SUMS

shasum -a 256 --ignore-missing -c SHA256SUMS     # macOS
sha256sum --ignore-missing -c SHA256SUMS         # Linux

One line matters. The fingerprint must read exactly:

166A CBF3 7786 FCEA A694 96DE 886F 1BFE B84E F1C0

One line looks alarming and is not. WARNING: This key is not certified appears for every key you have not personally signed. A name on a key is free text; the fingerprint is the identity.

A fingerprint is only as good as where you read it. Cross-check this one somewhere other than this page.

Windows

Hash with Get-FileHash firmware\kiss-signer-<version>.bin (-ws35.bin on the Waveshare 3.5in, -jc1060.bin on the Guition 7in) in PowerShell and compare against SHA256SUMS by eye. Verify the signature with Gpg4win.

The install page hashes the firmware in your browser before it offers the button, inside the offline zip too. Neither verifies the GPG signature. Do that yourself, once per release.

05 / no cable, no computer

Update from an SD card

On beta8 or later this is the easiest route there is. The signer takes its next firmware off a card: no cable, no driver, no computer.

What to put on the card

From the latest release, drop the file ending -update.bin in the top level of an SD card. That is the whole preparation.

Each board has its own: -ws35-update.bin is the Waveshare 3.5in’s, -jc1060-update.bin the Guition 7in’s, and the one with no board in its name the Guition 4.3in’s. From beta11 on the device refuses another board’s file. Beta10 does not check, so take your board’s; if the screen stays dark after a wrong one, power it off and on and it goes back to the firmware it had.

Take -update.bin, not the plain .bin. The plain one starts with the bootloader; a running device looks past that for the application and reports nothing to install.

Install it from the device

Put the card in, then on the signer go to SETTINGS → FIRMWARE and hold to install.

It checks both signatures against keys built into the device before writing anything, so a file that is not ours is refused. If the new firmware fails to start, the device rolls back by itself.

This route keeps your keys and settings. The browser install erases the whole chip — use that for a new device, this for everything else.

06 / esptool, over usb

Flash it from the command line

Safari and Firefox will not let a web page reach USB, which is why the install page needs Chrome, Brave or Edge. This does the same job from a terminal.

One tool, one command. macOS and Linux as written. On Windows use WSL or Git Bash, or retype the last command on one line without the \ marks.

pip install esptool        # or: pipx install esptool

# find your device's port:
#   macOS    /dev/cu.usbmodem*  (the 3.5in may show as /dev/cu.wchusbserial*)
#   Linux    /dev/ttyACM*
#   Windows  COM3, COM4, ...

# check the download first, the same check as the page before this one
shasum -a 256 --ignore-missing -c SHA256SUMS

# your board's image: kiss-signer-<version>.bin on the Guition 4.3in,
# kiss-signer-<version>-ws35.bin on the Waveshare 3.5in,
# kiss-signer-<version>-jc1060.bin on the Guition 7in

esptool --chip esp32p4 -p <port> -b 460800 \
  --before default-reset --after no-reset write-flash \
  --flash-mode dio --flash-size 16MB --flash-freq 80m \
  0 kiss-signer-<version>.bin

Then unplug, wait three seconds, plug back in. New firmware only starts after a power cycle, so a black screen almost always means this step got skipped.

The file you just wrote covers the part of the chip that holds keys, so every flash starts from clean ground.

07 / nothing reaches the network

Flash on a machine with no internet

The install page fetches the firmware as it flashes, so pulling the plug halfway breaks it. This is the same install in one download you carry to a machine that never goes online.

Get the one file

From the latest release, take kiss-signer-<version>-offline.zip, under 10 MB. It holds the firmware for every board the release carries, the install page and this guide. Nothing in it reaches out.

Check it before you trust it. The zip has its own signature, and the command is the one from checking the download. The folder carries a 00-START-HERE.txt with it written out.

Unzip it, then turn the network off

Nothing past this point needs a connection. Disconnect here if you want to.

Start the page

The install page has to be served, not opened as a file. A small program in the folder serves it to your own machine only: serve.command on macOS, serve.bat on Windows, ./serve.sh on Linux. It prints an address beginning http://localhost. Open that in Chrome, Brave or Edge and flash as normal.

Your computer may warn you about those files, and it is right to: they carry no Apple or Microsoft signature, and this project does not buy one. To raise no warning at all, run python3 serve.py in the folder instead.

None of this helps on Safari or Firefox: the browser itself cannot reach USB. Use the command line — the firmware is in the same folder, under site/installer/firmware.

08 / read twice, flash once

Flash encryption, the final signer build

On today’s beta, someone who steals the device and has the right equipment can read your seed words off the chip. The hardened build closes that by turning two locks on its first boot.

Lock one: flash encryption

The chip scrambles everything it stores. It generates a key by itself and writes it where nothing can read it back — not your computer, not us, not you. Everything saved after that is encrypted with it, so prying the memory open reads noise. Seed words live in their own store, which that encryption does not cover; it gets its own lock at the same time.

Lock two: secure boot

The device stops running strangers’ software. It will only start firmware signed with keys you made and keep, so nobody can quietly swap the signer for a lookalike that phones your seed home.

Both turn together. A device that took only one can never accept the other, so it is both or neither.

These costs are permanent

The first boot changes the chip itself. There is no undo, on any of this.
You can never flash it over the cable again. No USB, no install page. That is the point: nobody can walk up and quietly rewrite it. Updates still work, but only from an SD card, and only if signed with your own keys. Nothing published for this beta will install on it.
That first boot scrambles about 6 MB and can sit on a black screen for several minutes. Do not unplug it until the game menu appears. Cutting the power partway through can kill the device for good.
Do this only on a device you intend to keep as your real signer, and run the ordinary release on it first.

The home screen and Settings show an encryption line, read off the chip every time rather than remembered. Amber OFF means you are not protected yet. When it goes calm, both locks are on, and that is the moment to create keys you care about.

09 / seed words and passphrase

Create your keys

Three rules first. The device will not stop to say them.

Every passphrase opens keys. There is no "wrong passphrase" error, and there never will be.
The fingerprint tells you which keys you opened. It is on the home screen.
This signer is never online. Your coordinator does all the talking to the network.

All three come from the master key, and the master key comes from both halves. Change the passphrase and you get a different master key, so all three change together, and the fingerprint is how you tell which set you are in.

Try it in the simulator Walk the setup once here first. The word list and the derivation are the real ones.

First time: SET UP THIS SIGNER → NEW SEED WORDS. Pick where the randomness comes from, write the seed words on paper, pass the quiz, choose where they are kept, set your passphrase.
Write the passphrase down too, and keep it somewhere other than the seed words. Together they are your keys; in one place they are one secret, and whoever finds it has everything. Apart, neither half spends on its own.
Then take the optional VERIFY FULL BACKUP rehearsal: type every word from paper and the exact passphrase again. Until both recreate the same fingerprint, I UNDERSTAND keeps a red border. You can skip it, and it is the strongest check you can make before funding.
Later, SETTINGS → BACKUP → SEED WORDS shows them behind a warning, or checks your paper copy without revealing the stored set. A wrong or missing word is reported by position, and neither check alters anything.
Switch to TESTNET while you learn (SETTINGS → SIGNER → NETWORK): free coins, the same screens, nothing at stake. Then walk the round trip.

10 / do it once with play money

Your first TESTNET round trip

Walk this once with valueless TESTNET coins before using keys you care about. Five steps, receive then spend.

The FRUIT ISLAND game menu — Write **K I S S** across the menu with your finger. **Lift between letters** — the device counts pen lifts, not ink, and one continuous scribble never matches. Write it **wider than it is tall**. The shape is forgiving; the four separate letters are not.

Try it in the simulator Open the signer, then walk the same five steps against Sparrow. Nothing there is on a chain.

Fruit Island game menu — 01Return to KISS: write K I S S across the menu, as above.

KISS descriptor QR for Sparrow — 02Pair Sparrow: KEYS → PAIR COORDINATOR → DESKTOP. In Sparrow, create an Airgapped Hardware Wallet and scan this descriptor.

KISS camera scanner — 03Verify the first address: show address #0 in Sparrow, then KISS → Receive → VERIFY and scan it. Continue only when KISS says it is yours.

KISS Signer home — 04Practice receiving: send a tiny TESTNET amount to that verified address and wait for Sparrow to show it.

KISS transaction verification screen — 05Practice spending: build the return payment in Sparrow, move its PSBT by QR or SD, compare RECIPIENT GETS, NETWORK FEE, TOTAL LEAVING, outputs and change, then hold to sign. Return the signed PSBT to Sparrow and **broadcast there**.

Passphrase warning screen — The passphrase is part of your keys: lose it, lose the keys.

11 / it checks, you confirm

What KISS checks before you sign

KISS re-derives the whole transaction on its own screen and speaks up before you sign. Always a CAUTION you acknowledge, never a silent surprise.

The KISS signing screen, showing what the recipient gets, the inputs, the network fee and the change — These four are the whole check. Everything else on the screen follows from them.

Try it in the simulator The signing screen is the one the pins point at, and the simulator signs for real.

What turns amber

High fee. The fee turns amber if it is a big share of what you send (the rule Krux uses) or an outsized sat/vB rate.
Dust and privacy. Spending a tiny coin, or leaving tiny change, is flagged: both can be used to link and track your addresses. Change below the network dust limit is flagged louder.

Address reuse works differently. KISS never sees the chain, so it cannot know which of your addresses were paid. Rather than guess, RECEIVE hands out a fresh address every time.

Several cautions stack into one summary, and a ? opens a WHY FLAGGED card with the fix: freeze or label the coin in your coordinator. Any caution gates the sign button behind I UNDERSTAND.

Small things worth knowing

? beside an unfamiliar term — RBF, fingerprint, coordinator, dust — opens a short card.
EASY SCAN, on the signed-QR screen, slows the loop and enlarges the dots for stubborn cameras.
Tapping the KISS logo on the game menu locks straight back to the game.
Settings, bottom-left, shows what is on the device: KISS <version> (<commit>), and says so while flash encryption is off.

12 / three storage modes

Where your seed words are kept

Setup asks once, and Settings can change it later. What differs is what someone gets when they physically take the device, the card, or both.

The setup screen headed WHERE TO KEEP YOUR SEED WORDS, offering FLASH, SD CARD and AMNESIC, under the line choose what remains after you power off — What each answer costs is the table below.

Mode	Device only	Card only	Both
FLASHon the chip	seed wordson this beta	no card	seed wordson this beta
SD CARDsealed, on the card	nothingholds no copy	nothingsealed to the device	seed wordsthe gap
AMNESICin RAM only	nothingonce locked	no card	nothingonce locked

Every cell assumes the right equipment. A flash-encrypted build makes the FLASH row read nothing too.

No cell above holds your passphrase. It is never stored, in any mode, and it is what guards the keys that hold your coins.

On beta firmware, pick AMNESIC for anything that matters. You load your seed words each time, by typing them or opening an encrypted backup. SD CARD is the better of the two that remember.

Try it in the simulator The mode chooser is under SETTINGS, and switching costs nothing there.

Changing mode erases the old location. KISS writes the new copy, verifies it, then removes the old one.

13 / no hardware required

Try it without hardware

Open the simulator — the signer's own firmware compiled to WebAssembly. Real word list, real derivation, real signature. Nothing is installed and nothing leaves the tab. One button opens a signer that already has keys.

One thing is not real: there is no camera behind CAMERA AND TAPS, so that entropy source is filled in for you. The dice and the taps are yours. A browser tab is not a signer — make the keys that matter on the device, offline.