Merge pull request 'feat(proto)!: Shamir re-key, governance and bootstrapping vault state' (#102 ) from feat-shamir-protos into main

Reviewed-on: #102 Reviewed-by: Stas <business@jexter.tech>
merge: rebase on main
2026-09-05 12:13:20 +00:00 · 2026-09-05 14:09:57 +02:00 · 2026-08-28 22:16:17 +02:00 · 2026-08-26 13:01:44 +02:00
14 changed files with 292 additions and 502 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,13 +1,16 @@
 # AGENTS.md

-This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+Guidance for coding agents (Claude Code, Codex, …) working in this repository.

 ## Project Overview

-Arbiter is a **permissioned signing service** for cryptocurrency wallets. It consists of:
+Arbiter is a **permissioned signing service** for cryptocurrency wallets:
+
 - **`server/`** — Rust gRPC daemon that holds encrypted keys and enforces policies
- **`operator/`** — Flutter desktop app (macOS/Windows) with a Rust backend via Rinf
- **`protobufs/`** — Protocol Buffer definitions shared between server and client
+- **`useragent/`** — Flutter app (desktop + mobile + web targets) with a Rust core via `flutter_rust_bridge`
+- **`protobufs/`** — Protocol Buffer definitions shared between server and clients
+- **`docs/`** — `ARCHITECTURE.md` (peer types, flows, threat model) and `IMPLEMENTATION.md`; treat them as the design source of truth and update them when behaviour changes
+- **`scripts/`** — helper scripts, e.g. `gen_erc20_registry.py`

 The vault never exposes key material; it only produces signatures when requests satisfy configured policies.

@@ -18,7 +21,7 @@ Tools are managed via [mise](https://mise.jdx.dev/). Install all required tools:
 mise install
 ```

-Key versions: Rust 1.93.0 (with clippy), Flutter 3.38.9-stable, protoc 29.6, diesel_cli 2.3.6 (sqlite).
+Key versions live in `mise.toml` (currently Rust 1.95.0 with clippy, Flutter 3.41.7-stable, protoc 29.6, diesel_cli 2.3.7 with `sqlite-bundled`, Python 3.14). Also provided there: `cargo-nextest`, `cargo-audit`, `cargo-vet`, `cargo-shear`, `cargo-mutants`, `cargo-features-manager`, `cargo-edit`, `ast-grep`, `flutter_rust_bridge_codegen`.

 ## Server (Rust workspace at `server/`)

@@ -26,10 +29,14 @@ Key versions: Rust 1.93.0 (with clippy), Flutter 3.38.9-stable, protoc 29.6, die

 | Crate | Purpose |
 |---|---|
-| `arbiter-proto` | Generated gRPC stubs + protobuf types; compiled from `protobufs/*.proto` via `tonic-prost-build` |
-| `arbiter-server` | Main daemon — actors, DB, EVM policy engine, gRPC service implementation |
-| `arbiter-operator` | Rust client library for the operator side of the gRPC protocol |
-| `arbiter-client` | Rust client library for SDK clients |
+| `arbiter-proto` | Generated gRPC stubs + protobuf types (`tonic-prost-build`); also `ArbiterUrl`, `home_path()`, `BOOTSTRAP_PATH` |
+| `arbiter-crypto` | Shared crypto primitives: `authn` (ML-DSA), `safecell` (hardened memory), `hashing::Hashable`, re-exported `x-wing` |
+| `arbiter-macros` | `#[derive(Hashable)]` — canonical hashing of structs for the DB integrity layer |
+| `arbiter-server` | Main daemon — actors, peers, DB, EVM policy engine, gRPC service implementation |
+| `arbiter-client` | Rust client library for SDK clients (`ArbiterClient`, EVM wallet, key storage) |
+| `arbiter-tokens-registry` | Generated ERC-20 token registry used by token-transfer policies |
+
+Workspace lints (`server/Cargo.toml`) are strict: most of clippy `pedantic`/`nursery` plus a large restriction set. `as` casts, indexing/slicing, `dbg!`, float arithmetic and undocumented `unsafe` are denied or warned — expect to add an `#[expect(..., reason = "...")]` rather than to silence a lint globally.

 ### Common Commands

@@ -42,54 +49,78 @@ cargo build
 # Run the server daemon
 cargo run -p arbiter-server

-# Run all tests (preferred over cargo test)
+# Run all tests (preferred over cargo test; CI uses --all-features)
 cargo nextest run

 # Run a single test
 cargo nextest run <test_name>

-# Lint
-cargo clippy
+# Lint (CI runs it with -D warnings)
+cargo clippy --all -- -D warnings

 # Security audit
 cargo audit

+# Supply-chain review (config in server/supply-chain/)
+cargo vet
+
 # Check unused dependencies
 cargo shear

-# Run snapshot tests and update snapshots
-cargo insta review
+# Mutation testing
+cargo mutants
 ```

+### CI
+
+Woodpecker pipelines in `.woodpecker/` run on `server/**` changes: `server-lint` (clippy), `server-test` (nextest, `--all-features`), `server-audit`, `server-vet`, plus `useragent-analyze` for the Flutter app.
+
 ### Architecture

-The server is actor-based using the **kameo** crate. All long-lived state lives in `GlobalActors`:
+The server is actor-based using the **kameo** crate. Long-lived state lives in `GlobalActors` (`src/actors/mod.rs`):

- **`Bootstrapper`** — Manages the one-time bootstrap token written to `~/.arbiter/bootstrap_token` on first run.
- **`Vault`** — Holds the encrypted root key and manages the Sealed/Unsealed vault state machine. On unseal, decrypts the root key into a `memsafe` hardened memory cell.
- **`FlowCoordinator`** — Coordinates cross-connection flow between operators and SDK clients.
- **`EvmActor`** — Handles EVM transaction policy enforcement and signing.
+- **`Bootstrapper`** — one-time bootstrap token, written to `~/.arbiter/bootstrap_token` on first run
+- **`Vault`** — encrypted root key and the Sealed/Unsealed state machine; on unseal decrypts the root key into a `memsafe`-backed `SafeCell`
+- **`FlowCoordinator`** — cross-connection flow between operators and SDK clients
+- **`OperatorRegistry`** — tracks currently connected operators
+- **`EvmActor`** — EVM transaction policy enforcement and signing
+- **`events`** — a `kameo_actors::MessageBus` (`DeliveryStrategy::Guaranteed`) for cross-actor notifications

-Per-connection actors live under `actors/operator/` and `actors/client/`, each with `auth` (challenge-response authentication) and `session` (post-auth operations) sub-modules.
+Per-connection state lives under **`src/peers/`**, not `actors/`: `peers/client/` and `peers/operator/`, each with `auth` (challenge-response) and `session` (post-auth) sub-modules; the operator side additionally has `vault_gate/` for the unseal handshake.

-**Database:** SQLite via `diesel-async` + `bb8` connection pool. Schema managed by embedded Diesel migrations in `crates/arbiter-server/migrations/`. DB file lives at `~/.arbiter/arbiter.sqlite`. Tests use a temp-file DB via `db::create_test_pool()`.
+The gRPC surface lives in **`src/grpc/`**, split per peer (`client/`, `operator/`, `common/`) and per direction (`inbound.rs` — requests to the daemon, `outbound.rs` — server-initiated streams), with `request_tracker.rs` correlating the two.
+
+EVM logic is in `src/evm/`: `policies/ether_transfer/`, `policies/token_transfers/`, `abi.rs`, `safe_signer.rs`.
+
+**Database:** SQLite via `diesel-async` + `bb8`. Schema in `src/db/schema.rs`, models in `src/db/models.rs`, embedded migrations in `crates/arbiter-server/migrations/`. DB file lives at `~/.arbiter/arbiter.sqlite`; tests use a temp-file DB via `db::create_test_pool()`.
+
+Entity ids are newtypes generated by the `declare_id!` macro in `db::models` (`OperatorId`, `ChainId`, …), each a `#[repr(transparent)]` wrapper over `i32` with `to_raw`/`from_raw`. Pass these around instead of bare `i32`.
+
+**Row integrity:** sensitive rows are covered by an HMAC-SHA256 envelope (`src/crypto/integrity/`, table `integrity_envelope`), keyed from the vault root key. A struct becomes coverable by deriving `arbiter_macros::Hashable` and implementing `Integrable` (`KIND` + `VERSION`). When adding or changing a covered entity, keep the derive and the payload version in sync — a mismatch surfaces as `PayloadVersionMismatch` or `MacMismatch` at runtime.

 **Cryptography:**
- Authentication: ed25519 (challenge-response, nonce-tracked per peer)
- Encryption at rest: XChaCha20-Poly1305 (versioned via `scheme` field for transparent migration on unseal)
+- Authentication: **ML-DSA-87** (post-quantum, `arbiter-crypto::authn::v1`), challenge-response with per-peer nonce tracking
+- Encryption at rest: XChaCha20-Poly1305, versioned modules (`crypto/encryption/v1.rs`) with a `schema_version` column for transparent migration on unseal
 - Password KDF: Argon2
- Unseal transport: X25519 ephemeral key exchange
- TLS: self-signed certificate (aws-lc-rs backend), fingerprint distributed via `ArbiterUrl`
+- Unseal transport: X25519 ephemeral key exchange (`peers/operator/vault_gate/`); `x-wing` (hybrid PQ KEM) is available via `arbiter-crypto`
+- TLS: self-signed certificate (rustls + aws-lc-rs, `prefer-post-quantum`), fingerprint distributed via `ArbiterUrl`

-**Protocol:** gRPC with Protocol Buffers. The `ArbiterUrl` type encodes host, port, CA cert, and bootstrap token into a single shareable string (printed to console on first run).
+Crypto modules are versioned by convention: `mod.rs` re-exports the current `vN`. Add a `v(N+1)` rather than editing an existing version in place.
+
+**Protocol:** gRPC with Protocol Buffers. `ArbiterUrl` encodes host, port, CA cert and bootstrap token into a single shareable string (printed to console on first run).

 ### Proto Regeneration

-When `.proto` files in `protobufs/` change, rebuild to regenerate:
+`arbiter-proto/build.rs` compiles `arbiter.proto`, `operator.proto`, `client.proto` and `evm.proto` (with their `shared/`, `operator/`, `client/` includes) on build:
 ```sh
 cd server && cargo build -p arbiter-proto
 ```

+Dart protobuf stubs are generated separately, from the repo root:
+```sh
+mise run codegen   # protoc --dart_out=grpc:useragent/lib/proto
+```
+
 ### Database Migrations

 ```sh
@@ -100,6 +131,8 @@ diesel migration generate <name> --migration-dir crates/arbiter-server/migration
 diesel migration run --migration-dir crates/arbiter-server/migrations
 ```

+Pre-release policy: there is a single `init` migration and no deployed databases yet, so schema changes are made by editing that migration directly instead of stacking new ones. Regenerate `src/db/schema.rs` after changing it.
+
 ### Code Conventions

 **`#[must_use]` Attribute:**
@@ -121,29 +154,23 @@ pub fn verify(&self, nonce: i32, context: &[u8], signature: &Signature) -> bool

 This forces callers to either use the return value or explicitly ignore it with `let _ = ...;`, preventing silent failures.

-## Operator (Flutter + Rinf at `operator/`)
+## User Agent (Flutter + flutter_rust_bridge at `useragent/`)

-The Flutter app uses [Rinf](https://rinf.cunarist.org) to call Rust code. The Rust logic lives in `operator/native/hub/` as a separate crate that uses `arbiter-operator` for the gRPC client.
-
-Communication between Dart and Rust uses typed **signals** defined in `operator/native/hub/src/signals/`. After modifying signal structs, regenerate Dart bindings:
-
-```sh
-cd operator && rinf gen
-```
+The Flutter app calls Rust through [flutter_rust_bridge](https://cjycode.com/flutter_rust_bridge/) 2.12.0. The Rust side is the `rust_lib_arbiter` crate at `useragent/rust/`; everything exposed to Dart is declared in `useragent/rust/src/api/` and lands in `useragent/lib/src/rust/` (see `useragent/flutter_rust_bridge.yaml`). Dart UI code is organised as `lib/features/`, `lib/screens/`, `lib/widgets/`, `lib/providers/`, `lib/theme/`, with routing in `lib/router.dart` (`router.gr.dart` is generated).

 ### Common Commands

 ```sh
-cd operator
+cd useragent

-# Run the app (macOS or Windows)
+# Run the app
 flutter run

-# Regenerate Rust↔Dart signal bindings
-rinf gen
+# Regenerate Rust↔Dart bindings after editing rust/src/api/
+mise run codegen        # flutter_rust_bridge_codegen generate

-# Analyze Dart code
+# Analyze Dart code (also run in CI)
 flutter analyze
 ```

-The Rinf Rust entry point is `operator/native/hub/src/lib.rs`. It spawns actors defined in `operator/native/hub/src/actors/` which handle Dart↔server communication via signals.
+Note: `app/` contains only stale generated Flutter artifacts and is not the application source.
--- a/app/.dart_tool/extension_discovery/README.md
+++ b/app/.dart_tool/extension_discovery/README.md
@@ -1,31 +0,0 @@
-Extension Discovery Cache
-=========================
-
-This folder is used by `package:extension_discovery` to cache lists of
-packages that contains extensions for other packages.
-
-DO NOT USE THIS FOLDER
----------------------
-
- * Do not read (or rely) the contents of this folder.
- * Do write to this folder.
-
-If you're interested in the lists of extensions stored in this folder use the
-API offered by package `extension_discovery` to get this information.
-
-If this package doesn't work for your use-case, then don't try to read the
-contents of this folder. It may change, and will not remain stable.
-
-Use package `extension_discovery`
---------------------------------
-
-If you want to access information from this folder.
-
-Feel free to delete this folder
-------------------------------
-
-Files in this folder act as a cache, and the cache is discarded if the files
-are older than the modification time of `.dart_tool/package_config.json`.
-
-Hence, it should never be necessary to clear this cache manually, if you find a
-need to do please file a bug.
--- a/app/.dart_tool/extension_discovery/vs_code.json
+++ b/app/.dart_tool/extension_discovery/vs_code.json
@@ -1 +0,0 @@
-{"version":2,"entries":[{"package":"app","rootUri":"../","packageUri":"lib/"}]}
--- a/app/.dart_tool/package_config.json
+++ b/app/.dart_tool/package_config.json
@@ -1,178 +0,0 @@
-{
-  "configVersion": 2,
-  "packages": [
-    {
-      "name": "async",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/async-2.13.0",
-      "packageUri": "lib/",
-      "languageVersion": "3.4"
-    },
-    {
-      "name": "boolean_selector",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/boolean_selector-2.1.2",
-      "packageUri": "lib/",
-      "languageVersion": "3.1"
-    },
-    {
-      "name": "characters",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/characters-1.4.0",
-      "packageUri": "lib/",
-      "languageVersion": "3.4"
-    },
-    {
-      "name": "clock",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/clock-1.1.2",
-      "packageUri": "lib/",
-      "languageVersion": "3.4"
-    },
-    {
-      "name": "collection",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/collection-1.19.1",
-      "packageUri": "lib/",
-      "languageVersion": "3.4"
-    },
-    {
-      "name": "cupertino_icons",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/cupertino_icons-1.0.8",
-      "packageUri": "lib/",
-      "languageVersion": "3.1"
-    },
-    {
-      "name": "fake_async",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/fake_async-1.3.3",
-      "packageUri": "lib/",
-      "languageVersion": "3.3"
-    },
-    {
-      "name": "flutter",
-      "rootUri": "file:///Users/kaska/.local/share/mise/installs/flutter/3.38.9-stable/packages/flutter",
-      "packageUri": "lib/",
-      "languageVersion": "3.8"
-    },
-    {
-      "name": "flutter_lints",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/flutter_lints-6.0.0",
-      "packageUri": "lib/",
-      "languageVersion": "3.8"
-    },
-    {
-      "name": "flutter_test",
-      "rootUri": "file:///Users/kaska/.local/share/mise/installs/flutter/3.38.9-stable/packages/flutter_test",
-      "packageUri": "lib/",
-      "languageVersion": "3.8"
-    },
-    {
-      "name": "leak_tracker",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/leak_tracker-11.0.2",
-      "packageUri": "lib/",
-      "languageVersion": "3.2"
-    },
-    {
-      "name": "leak_tracker_flutter_testing",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/leak_tracker_flutter_testing-3.0.10",
-      "packageUri": "lib/",
-      "languageVersion": "3.2"
-    },
-    {
-      "name": "leak_tracker_testing",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/leak_tracker_testing-3.0.2",
-      "packageUri": "lib/",
-      "languageVersion": "3.2"
-    },
-    {
-      "name": "lints",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/lints-6.1.0",
-      "packageUri": "lib/",
-      "languageVersion": "3.8"
-    },
-    {
-      "name": "matcher",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/matcher-0.12.17",
-      "packageUri": "lib/",
-      "languageVersion": "3.4"
-    },
-    {
-      "name": "material_color_utilities",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/material_color_utilities-0.11.1",
-      "packageUri": "lib/",
-      "languageVersion": "2.17"
-    },
-    {
-      "name": "meta",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/meta-1.17.0",
-      "packageUri": "lib/",
-      "languageVersion": "3.5"
-    },
-    {
-      "name": "path",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/path-1.9.1",
-      "packageUri": "lib/",
-      "languageVersion": "3.4"
-    },
-    {
-      "name": "sky_engine",
-      "rootUri": "file:///Users/kaska/.local/share/mise/installs/flutter/3.38.9-stable/bin/cache/pkg/sky_engine",
-      "packageUri": "lib/",
-      "languageVersion": "3.8"
-    },
-    {
-      "name": "source_span",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/source_span-1.10.2",
-      "packageUri": "lib/",
-      "languageVersion": "3.1"
-    },
-    {
-      "name": "stack_trace",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/stack_trace-1.12.1",
-      "packageUri": "lib/",
-      "languageVersion": "3.4"
-    },
-    {
-      "name": "stream_channel",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/stream_channel-2.1.4",
-      "packageUri": "lib/",
-      "languageVersion": "3.3"
-    },
-    {
-      "name": "string_scanner",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/string_scanner-1.4.1",
-      "packageUri": "lib/",
-      "languageVersion": "3.1"
-    },
-    {
-      "name": "term_glyph",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/term_glyph-1.2.2",
-      "packageUri": "lib/",
-      "languageVersion": "3.1"
-    },
-    {
-      "name": "test_api",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/test_api-0.7.7",
-      "packageUri": "lib/",
-      "languageVersion": "3.5"
-    },
-    {
-      "name": "vector_math",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/vector_math-2.2.0",
-      "packageUri": "lib/",
-      "languageVersion": "3.1"
-    },
-    {
-      "name": "vm_service",
-      "rootUri": "file:///Users/kaska/.pub-cache/hosted/pub.dev/vm_service-15.0.2",
-      "packageUri": "lib/",
-      "languageVersion": "3.5"
-    },
-    {
-      "name": "app",
-      "rootUri": "../",
-      "packageUri": "lib/",
-      "languageVersion": "3.10"
-    }
-  ],
-  "generator": "pub",
-  "generatorVersion": "3.10.8",
-  "flutterRoot": "file:///Users/kaska/.local/share/mise/installs/flutter/3.38.9-stable",
-  "flutterVersion": "3.38.9",
-  "pubCache": "file:///Users/kaska/.pub-cache"
-}
--- a/app/.dart_tool/package_graph.json
+++ b/app/.dart_tool/package_graph.json
@@ -1,230 +0,0 @@
-{
-  "roots": [
-    "app"
-  ],
-  "packages": [
-    {
-      "name": "app",
-      "version": "1.0.0+1",
-      "dependencies": [
-        "cupertino_icons",
-        "flutter"
-      ],
-      "devDependencies": [
-        "flutter_lints",
-        "flutter_test"
-      ]
-    },
-    {
-      "name": "flutter_lints",
-      "version": "6.0.0",
-      "dependencies": [
-        "lints"
-      ]
-    },
-    {
-      "name": "flutter_test",
-      "version": "0.0.0",
-      "dependencies": [
-        "clock",
-        "collection",
-        "fake_async",
-        "flutter",
-        "leak_tracker_flutter_testing",
-        "matcher",
-        "meta",
-        "path",
-        "stack_trace",
-        "stream_channel",
-        "test_api",
-        "vector_math"
-      ]
-    },
-    {
-      "name": "cupertino_icons",
-      "version": "1.0.8",
-      "dependencies": []
-    },
-    {
-      "name": "flutter",
-      "version": "0.0.0",
-      "dependencies": [
-        "characters",
-        "collection",
-        "material_color_utilities",
-        "meta",
-        "sky_engine",
-        "vector_math"
-      ]
-    },
-    {
-      "name": "lints",
-      "version": "6.1.0",
-      "dependencies": []
-    },
-    {
-      "name": "stream_channel",
-      "version": "2.1.4",
-      "dependencies": [
-        "async"
-      ]
-    },
-    {
-      "name": "meta",
-      "version": "1.17.0",
-      "dependencies": []
-    },
-    {
-      "name": "collection",
-      "version": "1.19.1",
-      "dependencies": []
-    },
-    {
-      "name": "leak_tracker_flutter_testing",
-      "version": "3.0.10",
-      "dependencies": [
-        "flutter",
-        "leak_tracker",
-        "leak_tracker_testing",
-        "matcher",
-        "meta"
-      ]
-    },
-    {
-      "name": "vector_math",
-      "version": "2.2.0",
-      "dependencies": []
-    },
-    {
-      "name": "stack_trace",
-      "version": "1.12.1",
-      "dependencies": [
-        "path"
-      ]
-    },
-    {
-      "name": "clock",
-      "version": "1.1.2",
-      "dependencies": []
-    },
-    {
-      "name": "fake_async",
-      "version": "1.3.3",
-      "dependencies": [
-        "clock",
-        "collection"
-      ]
-    },
-    {
-      "name": "path",
-      "version": "1.9.1",
-      "dependencies": []
-    },
-    {
-      "name": "matcher",
-      "version": "0.12.17",
-      "dependencies": [
-        "async",
-        "meta",
-        "stack_trace",
-        "term_glyph",
-        "test_api"
-      ]
-    },
-    {
-      "name": "test_api",
-      "version": "0.7.7",
-      "dependencies": [
-        "async",
-        "boolean_selector",
-        "collection",
-        "meta",
-        "source_span",
-        "stack_trace",
-        "stream_channel",
-        "string_scanner",
-        "term_glyph"
-      ]
-    },
-    {
-      "name": "sky_engine",
-      "version": "0.0.0",
-      "dependencies": []
-    },
-    {
-      "name": "material_color_utilities",
-      "version": "0.11.1",
-      "dependencies": [
-        "collection"
-      ]
-    },
-    {
-      "name": "characters",
-      "version": "1.4.0",
-      "dependencies": []
-    },
-    {
-      "name": "async",
-      "version": "2.13.0",
-      "dependencies": [
-        "collection",
-        "meta"
-      ]
-    },
-    {
-      "name": "leak_tracker_testing",
-      "version": "3.0.2",
-      "dependencies": [
-        "leak_tracker",
-        "matcher",
-        "meta"
-      ]
-    },
-    {
-      "name": "leak_tracker",
-      "version": "11.0.2",
-      "dependencies": [
-        "clock",
-        "collection",
-        "meta",
-        "path",
-        "vm_service"
-      ]
-    },
-    {
-      "name": "term_glyph",
-      "version": "1.2.2",
-      "dependencies": []
-    },
-    {
-      "name": "string_scanner",
-      "version": "1.4.1",
-      "dependencies": [
-        "source_span"
-      ]
-    },
-    {
-      "name": "source_span",
-      "version": "1.10.2",
-      "dependencies": [
-        "collection",
-        "path",
-        "term_glyph"
-      ]
-    },
-    {
-      "name": "boolean_selector",
-      "version": "2.1.2",
-      "dependencies": [
-        "source_span",
-        "string_scanner"
-      ]
-    },
-    {
-      "name": "vm_service",
-      "version": "15.0.2",
-      "dependencies": []
-    }
-  ],
-  "configVersion": 1
-}
--- a/app/.dart_tool/version
+++ b/app/.dart_tool/version
@@ -1 +0,0 @@
-3.38.9
--- a/protobufs/operator.proto
+++ b/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;
  }
 }
--- a/protobufs/operator/governance.proto
+++ b/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;
+  }
+}
--- a/protobufs/operator/vault/bootstrap.proto
+++ b/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 {
--- a/protobufs/operator/vault/rekey.proto
+++ b/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;
+}
--- a/protobufs/operator/vault/unseal.proto
+++ b/protobufs/operator/vault/unseal.proto
@@ -15,18 +15,29 @@ 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 = 4;
 }

 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;
  }
 }

--- a/protobufs/operator/vault/vault.proto
+++ b/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;
  }
 }
--- a/protobufs/shared/vault.proto
+++ b/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;
 }
--- a/scripts/pycache/gen_erc20_registry.cpython-314.pyc
+++ b/scripts/pycache/gen_erc20_registry.cpython-314.pyc
Author	SHA1	Message	Date
Stas	0677695b16	Merge pull request 'feat(proto)!: Shamir re-key, governance and bootstrapping vault state' (#102 ) from feat-shamir-protos into main Reviewed-on: #102 Reviewed-by: Stas <business@jexter.tech>	2026-09-05 12:13:20 +00:00
Skipper	558910621b	merge: rebase on main	2026-09-05 14:09:57 +02:00
CleverWild	d7fe3a6377	housekeeping: actualize AGENTS.md	2026-08-28 22:16:17 +02:00
Skipper	f97b8f9424	feat(grpc): governance contract	2026-08-26 13:01:44 +02:00
				`@@ -1 +0,0 @@`
				`{"version":2,"entries":[{"package":"app","rootUri":"../","packageUri":"lib/"}]}`