DocsHandles and keys
Handles and keys
An account is its keys. Everything else points at them.
The account
Your account is a key-event log: a signed chain of events that starts with your account's root key, adds and removes device keys, and rotates the root. Its identifier is derived from the first event. Signatures are Ed25519. Pigeon asks for no phone number, email address or name to make one; there is nothing else to hold.
| Signature algorithm | Ed25519 |
|---|---|
| Root key | One per account; rotated with the seed phrase |
| Next root | Pre-committed: the log stores only a digest of it |
| Active devices | Up to 16, each with its own key and MLS leaf |
| Where keys live | The encrypted database, its key in Credential Manager (Windows) or the Secret Service (Linux) |
The seed phrase
The 24 words are the seed of your account's next root key, the one the log has committed to. Using them rotates the root, removes the devices you don't keep and issues a new phrase. Devices don't keep the words. Details: seed phrase.
Devices and rescue
A new device is linked from one you already use, over a channel sealed with the same hybrid KEM as messages and confirmed by a six-digit code. If a device is lost, you remove it from another, or rescue the account with the seed phrase. Details: devices and rescue.
Handles
A handle is an optional name in a public directory that points to an account's key. Lookups are exact, and the answer is checked against the account's key-event log on your device, so a directory can't swap the key without being caught. Contacts are kept by key, never by handle. Rules: handles.
Contacts
In the app today you add someone by their contact code, which carries their account's public bundle. Anyone you chat with is identified by that key from then on; if their key changes, the chat shows it.