Skip to content

feat: manual key rotation with privacy transaction - #1126

Open
jonesmarvin8 wants to merge 9 commits into
marvin/key-rotation-trimfrom
marvin/manual-key-rotation
Open

jonesmarvin8 wants to merge 9 commits into
marvin/key-rotation-trimfrom
marvin/manual-key-rotation

Conversation

@jonesmarvin8

@jonesmarvin8 jonesmarvin8 commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

🎯 Purpose

Lets a public account's key be rotated manually, without signing a transaction. The rotation runs privately in a privacy-preserving transaction, so the account's nonce does not change.

⚙️ Approach

  • Add a rotation counter to key derivation, so one nonce can have several keys.
  • Handle SetKey natively at the signature program's address. Only the signature program itself may send it, and it does not bump the nonce.
  • Add the signature program's guest at its system_upgrader PDA, and seed it at genesis as an upgradable system program.
  • Wallet: add account rotate-key <accounts…> --fee-payer <private>. The wallet finds the current key locally: it derives the keys at the account's nonce for counters 0 through 1024 and compares them with the stored key, so no indexer is needed. If a rotation lands after a signed transaction (so its key belongs to the previous nonce), rotate-key recovers the account by rotating to counter 1.

🧪 How to Test

  • RISC0_DEV_MODE=1 cargo nextest run -p integration_tests --test manual_rotation
  • The unit tests in lee, lez/programs (manual_rotation) and wallet

🔗 Dependencies

🔜 Future Work

N/A

📋 PR Completion Checklist

Mark only completed items. A complete PR should have all boxes ticked.

  • Complete PR description
  • Implement the core functionality
  • Add/update tests
  • Add/update documentation and inline comments

A key is now derived at (type, nonce, counter):
key_seed = Sha256(DS_KEY_SEED || secret || type || nonce as 16 bytes LE
|| counter as 4 bytes LE). Ordinary keys use counter 0; a manual
rotation moves to the next counter at the same nonce.

signing_key, key_state and Signer::new are unchanged and use counter 0.
signing_key_with_counter, key_state_with_counter and
Signer::new_with_counter take a counter; at counter 0 each calls the
original. A manually rotated key is stored on chain, so
Signer::new_with_counter never prefixes the initial key past counter 0.
Signer::counter reports the counter it signs with.

BREAKING!

Before: key_seed hashed no counter.
After: the counter is always hashed, so every key and account id
changes.

Mitigation: recreate wallet storage and genesis configs. The pinned
genesis keys in the docker configs are updated; the prebuilt sequencer
fixture and devnet stake entries are not regenerated in this commit.
A message to an account's signature actor now reaches a native handler
instead of failing as an unknown program. SignatureMessage::SetKey
{ next } writes `next` as the account's key state, without advancing
its nonce: the write is an actor-state write applied through the public
diff, not a signer's rotation.

Only the signature program itself may send it. The sender is checked
before the message is decoded, so every foreign or public caller fails
with ForeignSender, whatever it sent. A key type must be an allowed
rotation target; is_allowed_rotation_target allows every type until a
scheme is blocked, and authenticate applies the same rule to a witness
rotation's next key (AuthError::DisallowedRotation).

A root call to the signature address is now a charged revert
(SetKeyFailed) instead of rejecting the block as UnknownProgram.
The signature program gains a guest-callable part. Its one message,
ManualRotation, carries a secret, an account and a next key per entry.
For each entry the guest checks that the secret owns the account, then
sends SetKey to the account's signature actor, which the sequencer
handles natively. Run privately in a privacy transaction, the secrets
never leave the proof.

The guest derives the account id itself: lee is host-only, so it copies
key_seed and Schnorr key generation, and derives the x-only public key
with k256. Known-answer tests pin lee, the wallet and the guest to one
account id for a fixed secret. A one-account rotation takes about 3.6M
cycles.

The signature program's address is now signature_program_id(), the
system_upgrader PDA for its name, so system_upgrader can upgrade the
guest. The circuit and the loader no longer refuse it as a reserved
address: a claim needs a header on chain, and every loader write needs
system_upgrader's authorization. The prover's simulator handles a
public SetKey natively, as settlement does.

Program::handle_message_for_tests runs a guest on an input, for tests
of a guest that public execution never reaches.

BREAKING!

Before: the signature program lived at [0xFC; 32].
After: it lives at its system_upgrader PDA, so every account's key slot
moves, and every program's image id changes with the rebuilt artifacts.

Mitigation: recreate genesis state. The prebuilt sequencer fixture and
devnet configs are not regenerated in this commit.
…tem program

The signature program's guest joins the core system programs, so every
zone seeds it at genesis, mutable at its system_upgrader PDA, and
system_upgrader's registry lists it with no upgrade pending. A
committee-approved upgrade can then replace the guest; the native
SetKey handling is unaffected.

The upgrade-test helpers take a program name (staged_registering,
apply_tx_for), so the signature program is scheduled and applied like
any other. After an upgrade, the image id on chain is the new guest's,
so settlement refuses a proof claiming the old one.
The signature guest is proven privately and its SetKey settles through
the native handler: the key is installed without a nonce bump, the next
transaction signs with it, a nonce-0 account is admitted by its initial
key, two accounts rotate in one transaction, and the root's nullifier
is spent. A replay, an unadmitted account and the old key are refused.
A fresh private root with a public signer works as the public-payer
mode.

The public side sees the SetKey's sender as the signature program
either way; a blinded presentation keeps the root's private account id
out of the transaction.
@jonesmarvin8
jonesmarvin8 force-pushed the marvin/manual-key-rotation branch from 6eb37be to 201ccd8 Compare November 20, 2026 08:35
@jonesmarvin8
jonesmarvin8 changed the base branch from dev to marvin/key-rotation-trim November 20, 2026 08:36
The wallet signs with the key at (type, nonce, counter): counter 0
unless the account was rotated manually. current_signing_key finds the
counter behind the stored key by deriving the keys at the account's
nonce for counters 0 through MAX_ROTATIONS_PER_NONCE (1024) and
comparing each with the stored key. It needs only the account's secret
and its state on the sequencer, so any wallet holding the secret finds
the key. A stored key the secret does not derive at the current nonce
is an error naming `wallet account rotate-key`.
`wallet account rotate-key --account <id>... --fee-payer <private id>`
replaces the keys of public accounts this wallet holds without signing
with them, in one privacy transaction. The private fee payer's
signature actor runs the signature guest, so the accounts' secrets stay
in the proof and their nonces don't change. Each account moves to the
Schnorr key at (nonce, counter + 1). A stored key its secret does not
derive at the current nonce, as when a rotation lands after a signed
transaction, is replaced at counter 1. After MAX_ROTATIONS_PER_NONCE
rotations at a nonce, the account must sign before rotating again.

Before proving, the wallet refuses an account it holds no secret for, a
fee payer that isn't one of its private accounts, and a signature guest
that differs from the one deployed.
Integration tests drive `wallet account rotate-key` end to end: a
rotated account signs again at the same nonce, a second rotation at a
nonce takes the next counter, two accounts rotate in one transaction,
and a fresh account is rotated at nonce 0. The wallet finds each
rotated key in the account's history on the indexer; without
indexer_url, it refuses with an error naming the setting.

The prebuilt sequencer fixture is regenerated: the circuit, the program
images and every account id changed since it was built.
A public message to the signature program's address is handled
natively, and only a SetKey from the program itself is accepted; run
privately, its guest performs a manual rotation.
@jonesmarvin8
jonesmarvin8 force-pushed the marvin/manual-key-rotation branch from 201ccd8 to 57c62ed Compare November 20, 2026 09:13
@jonesmarvin8
jonesmarvin8 marked this pull request as ready for review November 20, 2026 09:58
@github-actions

Copy link
Copy Markdown

Suggested reviewers

These code owners were requested because this pull request touches areas they know best (see CODEOWNERS). Each is asked to focus on the files listed under their name.

Reviewer Why Files
agureev Integration tests, Integration tests: cross-zone, LEE key protocol, LEE privacy-preserving circuit, Built-in programs, LEE state machine, Chain state and storage, Benchmarks 38
Pravdyvy Integration tests, Integration tests: FFI, LEE key protocol, Chain state and storage, Wallet, Test fixtures 17
moudyellaz Integration tests: cross-zone, LEE privacy-preserving circuit, LEE state machine, Wallet, Benchmarks 31
schouhy LEE key protocol, LEE privacy-preserving circuit, LEE state machine, Local deployment and devnet configs, Wallet, Test fixtures 34
arjentix Local deployment and devnet configs, Wallet, Test fixtures 13
erhant Wallet 8

agureev

Integration tests (/integration_tests/)

Integration tests: cross-zone (/integration_tests/tests/cross_zone_*.rs)

LEE key protocol (/lee/key_protocol/)

LEE privacy-preserving circuit (/lee/privacy_preserving_circuit/)

Built-in programs (/lee/program_loader/, /lez/programs/)

10 files

LEE state machine (/lee/state_machine/)

19 files

Chain state and storage (/lez/testnet_initial_state/)

Benchmarks (/tools/cycle_bench/)

Pravdyvy

Integration tests (/integration_tests/)

Integration tests: FFI (/integration_tests/tests/wallet_ffi_*.rs)

LEE key protocol (/lee/key_protocol/)

Chain state and storage (/lez/testnet_initial_state/)

Wallet (/lez/wallet/)

8 files

Test fixtures (/test_fixtures/)

moudyellaz

Integration tests: cross-zone (/integration_tests/tests/cross_zone_*.rs)

LEE privacy-preserving circuit (/lee/privacy_preserving_circuit/)

LEE state machine (/lee/state_machine/)

19 files

Wallet (/lez/wallet/)

8 files

Benchmarks (/tools/cycle_bench/)

schouhy

LEE key protocol (/lee/key_protocol/)

LEE privacy-preserving circuit (/lee/privacy_preserving_circuit/)

LEE state machine (/lee/state_machine/)

19 files

Local deployment and devnet configs (/lez/configs/)

Wallet (/lez/wallet/)

8 files

Test fixtures (/test_fixtures/)

arjentix

Local deployment and devnet configs (/lez/configs/)

Wallet (/lez/wallet/)

8 files

Test fixtures (/test_fixtures/)

erhant

Wallet (/lez/wallet/)

8 files
Files without another code owner (15)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant