feat(proto)!: Shamir re-key, governance and bootstrapping vault state

Split out of feat-shamir so the wire contract can be reviewed on its own.
Rebased onto main: main's UNSEAL_RESULT_LOCKED_OUT keeps tag 4, so
UNSEAL_RESULT_AWAITING_CONTRIBUTIONS moved to 5.

BREAKING CHANGE: `shared.VaultState` renumbers SEALED/UNSEALED/ERROR to
make room for VAULT_STATE_BOOSTRAPPING = 2. Old and new peers disagree on
every vault state value.

- operator: new `governance` branch in OperatorRequest/Response (field 5)
- vault: new `rekey` branch in vault Request/Response (field 4)
- bootstrap/unseal: passphrase and recovery-passphrase contribution payloads

protobufs/operator.proto

@@ -4,25 +4,28 @@ package arbiter.operator;
 
 import "operator/auth.proto";
 import "operator/evm.proto";
+import "operator/governance.proto";
 import "operator/sdk_client.proto";
 import "operator/vault/vault.proto";
 
 message OperatorRequest {
   int32 id = 16;
   oneof payload {
-    auth.Request auth = 1;
-    vault.Request vault = 2;
-    evm.Request evm = 3;
-    sdk_client.Request sdk_client = 4;
+    auth.Request            auth        = 1;
+    vault.Request           vault       = 2;
+    evm.Request             evm         = 3;
+    sdk_client.Request      sdk_client  = 4;
+    governance.Request      governance  = 5;
   }
 }
 
 message OperatorResponse {
   optional int32 id = 16;
   oneof payload {
-    auth.Response auth = 1;
-    vault.Response vault = 2;
-    evm.Response evm = 3;
-    sdk_client.Response sdk_client = 4;
+    auth.Response           auth        = 1;
+    vault.Response          vault       = 2;
+    evm.Response            evm         = 3;
+    sdk_client.Response     sdk_client  = 4;
+    governance.Response     governance  = 5;
   }
 }

protobufs/operator/governance.proto

@@ -0,0 +1,136 @@
+syntax = "proto3";
+
+package arbiter.operator.governance;
+
+message Request {
+  oneof payload {
+    CreateProposalRequest create = 1;
+    CastVoteRequest       vote   = 2;
+    QueryPendingRequest   query  = 3;
+  }
+}
+
+message CreateProposalRequest {
+  oneof kind {
+    ApproveSdkClientPayload         approve_sdk_client          = 1;
+    GrantWalletAccessPayload        grant_wallet_access         = 3;
+    ApproveServerUpdatePayload      approve_server_update       = 4;
+    ReplaceOperatorPayload          replace_operator            = 5;
+    UpdateShamirParametersPayload   update_shamir_parameters    = 6;
+    ApprovePersistentGrantPayload   approve_persistent_grant    = 7;
+    ApproveOneOffTransactionPayload approve_one_off_transaction = 8;
+  }
+  optional uint32 ttl_secs = 2;
+}
+
+message ReplaceOperatorPayload {
+  int32 old_operator_id = 1;
+  bytes new_pubkey      = 2;
+}
+
+message UpdateShamirParametersPayload {
+  uint32 new_n = 1;
+}
+
+message ApproveServerUpdatePayload {}
+
+message ApproveSdkClientPayload {
+  int32 client_id = 1;
+}
+
+message GrantWalletAccessPayload {
+  int32 wallet_id = 1;
+  int32 client_id = 2;
+}
+
+message CastVoteRequest {
+  int32 proposal_id = 1;
+  bool  approve     = 2;
+  bytes signature   = 3;
+}
+
+message QueryPendingRequest {}
+
+message Response {
+  oneof payload {
+    CreateProposalResponse created = 1;
+    VoteResponse           voted   = 2;
+    QueryPendingResponse   pending = 3;
+  }
+}
+
+message CreateProposalResponse {
+  int32 proposal_id = 1;
+}
+
+message VoteResponse {
+  VoteOutcome outcome = 1;
+}
+
+enum VoteOutcome {
+  VOTE_OUTCOME_UNSPECIFIED = 0;
+  VOTE_OUTCOME_PENDING     = 1;
+  VOTE_OUTCOME_APPROVED    = 2;
+  VOTE_OUTCOME_REJECTED    = 3;
+}
+
+message ProposalSummary {
+  int32  id            = 1;
+  string kind          = 2;
+  int32  initiator_id  = 3;
+  int64  expires_at    = 4;
+  int64  approve_count = 5;
+  int64  reject_count  = 6;
+}
+
+message QueryPendingResponse {
+  repeated ProposalSummary proposals = 1;
+}
+
+message TransactionRateLimitProto {
+  uint32 count       = 1;
+  int64  window_secs = 2;
+}
+
+message VolumeLimitProto {
+  bytes max_volume  = 1;
+  int64 window_secs = 2;
+}
+
+message EtherTransferSpecProto {
+  repeated bytes   targets = 1;
+  VolumeLimitProto limit   = 2;
+}
+
+message TokenTransferSpecProto {
+  bytes                     token_contract = 1;
+  optional bytes            target         = 2;
+  repeated VolumeLimitProto volume_limits  = 3;
+}
+
+message ApproveOneOffTransactionPayload {
+  int32  client_id                = 1;
+  bytes  wallet_address           = 2;
+  uint64 chain_id                 = 3;
+  uint64 nonce                    = 4;
+  uint64 gas_limit                = 5;
+  bytes  max_fee_per_gas          = 6;
+  bytes  max_priority_fee_per_gas = 7;
+  bytes  to                       = 8;
+  bytes  value                    = 9;
+  bytes  input                    = 10;
+}
+
+message ApprovePersistentGrantPayload {
+  int32                              wallet_access_id         = 1;
+  uint64                             chain_id                 = 2;
+  optional int64                     valid_from_secs          = 3;
+  optional int64                     valid_until_secs         = 4;
+  optional bytes                     max_gas_fee_per_gas      = 5;
+  optional bytes                     max_priority_fee_per_gas = 6;
+  optional TransactionRateLimitProto rate_limit               = 7;
+  oneof specific {
+    EtherTransferSpecProto ether_transfer = 8;
+    TokenTransferSpecProto token_transfer = 9;
+  }
+}

protobufs/operator/vault/bootstrap.proto

@@ -8,15 +8,35 @@ message BootstrapEncryptedKey {
   bytes associated_data = 3;
 }
 
+message DeclareCommittee {
+  uint32 count          = 1;
+  uint32 recovery_count = 2;
+}
+
+message ContributePassphrase {
+  bytes passphrase = 1;
+}
+
+message ContributeRecoveryPassphrase {
+  int32 recovery_operator_id = 1;
+  bytes passphrase            = 2;
+}
+
 enum BootstrapResult {
   BOOTSTRAP_RESULT_UNSPECIFIED = 0;
   BOOTSTRAP_RESULT_SUCCESS = 1;
   BOOTSTRAP_RESULT_ALREADY_BOOTSTRAPPED = 2;
   BOOTSTRAP_RESULT_INVALID_KEY = 3;
+  BOOTSTRAP_RESULT_AWAITING_CONTRIBUTIONS = 4;
 }
 
 message Request {
-  BootstrapEncryptedKey encrypted_key = 2;
+  oneof payload {
+    BootstrapEncryptedKey        encrypted_key                    = 2;
+    DeclareCommittee             declare_committee                = 3;
+    ContributePassphrase         contribute_passphrase            = 4;
+    ContributeRecoveryPassphrase contribute_recovery_passphrase   = 5;
+  }
 }
 
 message Response {

protobufs/operator/vault/rekey.proto

@@ -0,0 +1,30 @@
+syntax = "proto3";
+
+package arbiter.operator.vault.rekey;
+
+message ContributePassphrase {
+  bytes passphrase = 1;
+}
+
+message ContributeRecoveryPassphrase {
+  int32 recovery_operator_id = 1;
+  bytes passphrase           = 2;
+}
+
+enum RekeyResult {
+  REKEY_RESULT_UNSPECIFIED            = 0;
+  REKEY_RESULT_SUCCESS                = 1;
+  REKEY_RESULT_AWAITING_CONTRIBUTIONS = 2;
+  REKEY_RESULT_NOT_IN_PROGRESS        = 3;
+}
+
+message Request {
+  oneof payload {
+    ContributePassphrase         contribute_passphrase          = 1;
+    ContributeRecoveryPassphrase contribute_recovery_passphrase = 2;
+  }
+}
+
+message Response {
+  RekeyResult result = 1;
+}

protobufs/operator/vault/unseal.proto

@@ -15,18 +15,30 @@ message UnsealEncryptedKey {
   bytes associated_data = 3;
 }
 
+message ContributePassphrase {
+  bytes passphrase = 1;
+}
+
+message ContributeRecoveryPassphrase {
+  int32 recovery_operator_id = 1;
+  bytes passphrase            = 2;
+}
+
 enum UnsealResult {
   UNSEAL_RESULT_UNSPECIFIED = 0;
   UNSEAL_RESULT_SUCCESS = 1;
   UNSEAL_RESULT_INVALID_KEY = 2;
   UNSEAL_RESULT_UNBOOTSTRAPPED = 3;
   UNSEAL_RESULT_LOCKED_OUT = 4;
+  UNSEAL_RESULT_AWAITING_CONTRIBUTIONS = 5;
 }
 
 message Request {
   oneof payload {
-    UnsealStart start = 1;
-    UnsealEncryptedKey encrypted_key = 2;
+    UnsealStart                  start                          = 1;
+    UnsealEncryptedKey           encrypted_key                  = 2;
+    ContributePassphrase         contribute_passphrase          = 3;
+    ContributeRecoveryPassphrase contribute_recovery_passphrase = 4;
   }
 }
 

protobufs/operator/vault/vault.proto

@@ -5,20 +5,23 @@ package arbiter.operator.vault;
 import "google/protobuf/empty.proto";
 import "shared/vault.proto";
 import "operator/vault/bootstrap.proto";
+import "operator/vault/rekey.proto";
 import "operator/vault/unseal.proto";
 
 message Request {
   oneof payload {
     google.protobuf.Empty query_state = 1;
-    unseal.Request unseal = 2;
-    bootstrap.Request bootstrap = 3;
+    unseal.Request        unseal      = 2;
+    bootstrap.Request     bootstrap   = 3;
+    rekey.Request         rekey       = 4;
   }
 }
 
 message Response {
   oneof payload {
-    arbiter.shared.VaultState state = 1;
-    unseal.Response unseal = 2;
-    bootstrap.Response bootstrap = 3;
+    arbiter.shared.VaultState state     = 1;
+    unseal.Response           unseal    = 2;
+    bootstrap.Response        bootstrap = 3;
+    rekey.Response            rekey     = 4;
   }
 }

protobufs/shared/vault.proto

@@ -5,7 +5,8 @@ package arbiter.shared;
 enum VaultState {
   VAULT_STATE_UNSPECIFIED = 0;
   VAULT_STATE_UNBOOTSTRAPPED = 1;
-  VAULT_STATE_SEALED = 2;
-  VAULT_STATE_UNSEALED = 3;
-  VAULT_STATE_ERROR = 4;
+  VAULT_STATE_BOOSTRAPPING = 2;
+  VAULT_STATE_SEALED = 3;
+  VAULT_STATE_UNSEALED = 4;
+  VAULT_STATE_ERROR = 5;
 }

server/crates/arbiter-server/src/peers/operator/vault_gate/mod.rs

@@ -11,7 +11,7 @@ use arbiter_crypto::safecell::{SafeCell, SafeCellHandle as _};
 use state::State;
 
 use chacha20poly1305::{AeadInPlace, KeyInit as _, XChaCha20Poly1305, XNonce};
-use kameo::{Actor, error::SendError, messages, prelude::{Context, Message}};
+use kameo::{Actor, error::SendError, messages, prelude::Message};
 use kameo_actors::message_bus::Register;
 use tokio::sync::oneshot;
 use tracing::{error, info};
@@ -143,13 +143,12 @@ impl VaultGate {
         })
     }
 
-    #[message(ctx)]
+    #[message]
     pub async fn handle_unseal_encrypted_key(
         &mut self,
         nonce: Vec<u8>,
         ciphertext: Vec<u8>,
         associated_data: Vec<u8>,
-        ctx: &mut Context<Self, Result<(), Error>>,
     ) -> Result<(), Error> {
         let State::ReadyForExchange { secret, .. } = &self.state else {
             return Err(Error::State);
@@ -173,12 +172,7 @@ impl VaultGate {
                 Ok(())
             }
             Err(SendError::HandlerError(vault::Error::InvalidKey)) => Err(Error::InvalidKey),
-            Err(SendError::HandlerError(vault::Error::LockedOut)) => {
-                // Vault is permanently locked — terminate this gate so the
-                // run_vault_gate loop breaks and the connection is closed.
-                ctx.stop();
-                Err(Error::LockedOut)
-            }
+            Err(SendError::HandlerError(vault::Error::LockedOut)) => Err(Error::LockedOut),
             Err(SendError::HandlerError(err)) => {
                 error!(?err, "Vault failed to unseal key");
                 Err(Error::InvalidKey)
@@ -251,7 +245,7 @@ impl Message<events::Bootstrapped> for VaultGate {
     async fn handle(
         &mut self,
         _: events::Bootstrapped,
-        ctx: &mut Context<Self, Self::Reply>,
+        ctx: &mut kameo::prelude::Context<Self, Self::Reply>,
     ) -> Self::Reply {
         let result = async {
             let mut conn = self
@@ -287,7 +281,7 @@ impl Message<events::Unsealed> for VaultGate {
     async fn handle(
         &mut self,
         _: events::Unsealed,
-        ctx: &mut Context<Self, Self::Reply>,
+        ctx: &mut kameo::prelude::Context<Self, Self::Reply>,
     ) -> Self::Reply {
         if let Some(tx) = self.promotion_tx.take() {
             let _ = tx.send(Ok(()));

server/crates/arbiter-server/tests/operator/unseal.rs

@@ -140,47 +140,6 @@ pub async fn unseal_corrupted_ciphertext() {
     ));
 }
 
-/// After MAX_UNSEAL_ATTEMPTS wrong keys, the vault locks and the VaultGate
-/// must stop itself so the connection is dropped.
-#[tokio::test]
-#[test_log::test]
-pub async fn lockout_stops_vault_gate() {
-    use kameo::error::SendError;
-
-    let seal_key = b"real-seal-key";
-    let (_db, gate, _promotion_rx) = setup_sealed_gate(seal_key).await;
-
-    // Exhaust all MAX_UNSEAL_ATTEMPTS (5) with wrong keys; each returns InvalidKey.
-    for _ in 0..5 {
-        let encrypted_key = client_dh_encrypt(&gate, b"wrong-key").await;
-        assert!(matches!(
-            gate.ask(encrypted_key).await,
-            Err(SendError::HandlerError(VaultGateError::InvalidKey))
-        ));
-    }
-
-    // Sixth attempt: vault is now locked, returns LockedOut, and the gate stops itself.
-    let encrypted_key = client_dh_encrypt(&gate, b"wrong-key").await;
-    assert!(matches!(
-        gate.ask(encrypted_key).await,
-        Err(SendError::HandlerError(VaultGateError::LockedOut))
-    ));
-
-    // Give the actor scheduler time to process the stop signal.
-    tokio::time::sleep(std::time::Duration::from_millis(50)).await;
-
-    // Any subsequent message must be rejected because the gate is stopped.
-    let client_secret = EphemeralSecret::random();
-    let client_public = PublicKey::from(&client_secret);
-    assert!(
-        matches!(
-            gate.ask(HandleHandshake { client_pubkey: client_public }).await,
-            Err(SendError::ActorNotRunning(_))
-        ),
-        "VaultGate must be stopped after LockedOut"
-    );
-}
-
 #[tokio::test]
 #[test_log::test]
 pub async fn unseal_retry_after_invalid_key() {