fix(clippy): apply auto-fixable linting suggestions
This commit is contained in:
Clippy Bot
@@ -1,334 +1,334 @@
|
||||
# Arbiter
|
||||
|
||||
Arbiter is a permissioned signing service for cryptocurrency wallets. It runs as a background service on the user's machine with an optional client application for vault management.
|
||||
|
||||
**Core principle:** The vault NEVER exposes key material. It only produces signatures when a request satisfies the configured policies.
|
||||
---
|
||||
|
||||
## 1. Peer Types
|
||||
|
||||
Arbiter distinguishes two kinds of peers:
|
||||
|
||||
- **Operator** — A client application used by the owner to manage the vault (create wallets, approve SDK clients, configure policies).
|
||||
- **SDK Client** — A consumer of signing capabilities, typically an automation tool. In the future, this could include a browser-based wallet.
|
||||
- **Recovery Operator** — A dormant recovery participant with narrowly scoped authority used only for custody recovery and operator replacement.
|
||||
|
||||
---
|
||||
|
||||
## 2. Authentication
|
||||
|
||||
### 2.1 Challenge-Response
|
||||
|
||||
All peers authenticate via public-key cryptography using a challenge-response protocol:
|
||||
|
||||
1. The peer sends its public key and requests a challenge.
|
||||
2. The server looks up the key in its database. If found, it generates a fresh challenge from random bytes plus the current timestamp.
|
||||
3. The peer signs the canonical challenge payload with its private key and sends the signature back.
|
||||
4. The server verifies the signature:
|
||||
- **Pass:** The connection is considered authenticated.
|
||||
- **Fail:** The server closes the connection.
|
||||
|
||||
Authentication challenges are per-connection, ephemeral values. They are not persisted in the peer tables, and peer records store no challenge state.
|
||||
|
||||
### 2.2 Operator Bootstrap
|
||||
|
||||
On first run — when no Operators are registered — the server generates a one-time bootstrap token. It is made available in two ways:
|
||||
|
||||
- **Local setup:** Written to `~/.arbiter/bootstrap_token` for automatic discovery by a co-located Operator.
|
||||
- **Remote setup:** Printed to the server's console output.
|
||||
|
||||
The first Operator must present this token alongside the standard challenge-response to complete registration.
|
||||
|
||||
### 2.3 SDK Client Registration
|
||||
|
||||
There is no bootstrap mechanism for SDK clients. They must be explicitly approved by an already-registered Operator.
|
||||
|
||||
---
|
||||
|
||||
## 3. Multi-Operator Governance
|
||||
|
||||
When more than one Operator is registered, the vault is treated as having multiple operators. In that mode, sensitive actions are governed by voting rather than by a single operator decision.
|
||||
|
||||
### 3.1 Voting Rules
|
||||
|
||||
Voting is based on the total number of registered operators:
|
||||
|
||||
- **1 operator:** no vote is needed; the single operator decides directly.
|
||||
- **2 operators:** full consensus is required; both operators must approve.
|
||||
- **3 or more operators:** quorum is `floor(N / 2) + 1`.
|
||||
|
||||
For a decision to count, the operator's approval or rejection must be signed by that operator's associated key. Unsigned votes, or votes that fail signature verification, are ignored.
|
||||
|
||||
Examples:
|
||||
|
||||
- **3 operators:** 2 approvals required
|
||||
- **4 operators:** 3 approvals required
|
||||
|
||||
### 3.2 Actions Requiring a Vote
|
||||
|
||||
In multi-operator mode, a successful vote is required for:
|
||||
|
||||
- approving new SDK clients
|
||||
- granting an SDK client visibility to a wallet
|
||||
- approving a one-off transaction
|
||||
- approving creation of a persistent grant
|
||||
- approving operator replacement
|
||||
- approving server updates
|
||||
- updating Shamir secret-sharing parameters
|
||||
|
||||
### 3.3 Special Rule for Key Rotation
|
||||
|
||||
Key rotation always requires full quorum, regardless of the normal voting threshold.
|
||||
|
||||
This is stricter than ordinary governance actions because rotating the root key requires every operator to participate in coordinated share refresh/update steps. The root key itself is not redistributed directly, but each operator's share material must be changed consistently.
|
||||
|
||||
### 3.4 Root Key Custody
|
||||
|
||||
When the vault has multiple operators, the vault root key is protected using Shamir secret sharing.
|
||||
|
||||
The vault root key is encrypted in a way that requires reconstruction from user-held shares rather than from a single shared password.
|
||||
|
||||
For ordinary operators, the Shamir threshold matches the ordinary governance quorum. For example:
|
||||
|
||||
- **2 operators:** `2-of-2`
|
||||
- **3 operators:** `2-of-3`
|
||||
- **4 operators:** `3-of-4`
|
||||
|
||||
In practice, the Shamir share set also includes Recovery Operator shares. This means the effective Shamir parameters are computed over the combined share pool while keeping the same threshold. For example:
|
||||
|
||||
- **3 ordinary operators + 2 recovery shares:** `2-of-5`
|
||||
|
||||
This ensures that the normal custody threshold follows the ordinary operator quorum, while still allowing dormant recovery shares to exist for break-glass recovery flows.
|
||||
|
||||
### 3.5 Recovery Operators
|
||||
|
||||
Recovery Operators are a separate peer type from ordinary vault operators.
|
||||
|
||||
Their role is intentionally narrow. They can only:
|
||||
|
||||
- participate in unsealing the vault
|
||||
- vote for operator replacement
|
||||
|
||||
Recovery Operators do not participate in routine governance such as approving SDK clients, granting wallet visibility, approving transactions, creating grants, approving server updates, or changing Shamir parameters.
|
||||
|
||||
### 3.6 Sleeping and Waking Recovery Operators
|
||||
|
||||
By default, Recovery Operators are **sleeping** and do not participate in any active flow.
|
||||
|
||||
Any ordinary operator may request that Recovery Operators **wake up**.
|
||||
|
||||
Any ordinary operator may also cancel a pending wake-up request.
|
||||
|
||||
This creates a dispute window before recovery powers become active. The default wake-up delay is **14 days**.
|
||||
|
||||
Recovery Operators are therefore part of the break-glass recovery path rather than the normal operating quorum.
|
||||
|
||||
The high-level recovery flow is:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
actor Op as Ordinary Operator
|
||||
participant Server
|
||||
actor Other as Other Operator
|
||||
actor Rec as Recovery Operator
|
||||
|
||||
Op->>Server: Request recovery wake-up
|
||||
Server-->>Op: Wake-up pending
|
||||
Note over Server: Default dispute window: 14 days
|
||||
|
||||
alt Wake-up cancelled during dispute window
|
||||
Other->>Server: Cancel wake-up
|
||||
Server-->>Op: Recovery cancelled
|
||||
Server-->>Rec: Stay sleeping
|
||||
else No cancellation for 14 days
|
||||
Server-->>Rec: Wake up
|
||||
Rec->>Server: Join recovery flow
|
||||
critical Recovery authority
|
||||
Rec->>Server: Participate in unseal
|
||||
Rec->>Server: Vote on operator replacement
|
||||
end
|
||||
Server-->>Op: Recovery mode active
|
||||
end
|
||||
```
|
||||
|
||||
### 3.7 Committee Formation
|
||||
|
||||
There are two ways to form a multi-operator committee:
|
||||
|
||||
- convert an existing single-operator vault by adding new operators
|
||||
- bootstrap an unbootstrapped vault directly into multi-operator mode
|
||||
|
||||
In both cases, committee formation is a coordinated process. Arbiter does not allow multi-operator custody to emerge implicitly from unrelated registrations.
|
||||
|
||||
### 3.8 Bootstrapping an Unbootstrapped Vault into Multi-Operator Mode
|
||||
|
||||
When an unbootstrapped vault is initialized as a multi-operator vault, the setup proceeds as follows:
|
||||
|
||||
1. An operator connects to the unbootstrapped vault using an Operator and the bootstrap token.
|
||||
2. During bootstrap setup, that operator declares:
|
||||
- the total number of ordinary operators
|
||||
- the total number of Recovery Operators
|
||||
3. The vault enters **multi-bootstrap mode**.
|
||||
4. While in multi-bootstrap mode:
|
||||
- every ordinary operator must connect with an Operator using the bootstrap token
|
||||
- every Recovery Operator must also connect using the bootstrap token
|
||||
- each participant is registered individually
|
||||
- each participant's share is created and protected with that participant's credentials
|
||||
5. The vault is considered fully bootstrapped only after all declared operator and recovery-share registrations have completed successfully.
|
||||
|
||||
This means the operator and recovery set is fixed at bootstrap completion time, based on the counts declared when multi-bootstrap mode was entered.
|
||||
|
||||
### 3.9 Special Bootstrap Constraint for Two-Operator Vaults
|
||||
|
||||
If a vault is declared with exactly **2 ordinary operators**, Arbiter requires at least **1 Recovery Operator** to be configured during bootstrap.
|
||||
|
||||
This prevents the worst-case custody failure in which a `2-of-2` operator set becomes permanently unrecoverable after loss of a single operator.
|
||||
|
||||
---
|
||||
|
||||
## 4. Server Identity
|
||||
|
||||
The server proves its identity using TLS with a self-signed certificate. The TLS private key is generated on first run and is long-term; no rotation mechanism exists yet due to the complexity of multi-peer coordination.
|
||||
|
||||
Peers verify the server by its **public key fingerprint**:
|
||||
|
||||
- **Operator (local):** Receives the fingerprint automatically through the bootstrap token.
|
||||
- **Operator (remote) / SDK Client:** Must receive the fingerprint out-of-band.
|
||||
|
||||
> A streamlined setup mechanism using a single connection string is planned but not yet implemented.
|
||||
|
||||
---
|
||||
|
||||
## 5. Key Management
|
||||
|
||||
### 5.1 Key Hierarchy
|
||||
|
||||
There are three layers of keys:
|
||||
|
||||
| Key | Encrypts | Encrypted by |
|
||||
|---|---|---|
|
||||
| **User key** (password) | Root key | — (derived from user input) |
|
||||
| **Root key** | Wallet keys | User key |
|
||||
| **Wallet keys** | — (used for signing) | Root key |
|
||||
|
||||
This layered design enables:
|
||||
|
||||
- **Password rotation** without re-encrypting every wallet key (only the root key is re-encrypted).
|
||||
- **Root key rotation** without requiring the user to change their password.
|
||||
|
||||
### 5.2 Encryption at Rest
|
||||
|
||||
The database stores everything in encrypted form using symmetric AEAD. The encryption scheme is versioned to support transparent migration — when the vault unseals, Arbiter automatically re-encrypts any entries that are behind the current scheme version. See [IMPLEMENTATION.md](IMPLEMENTATION.md) for the specific scheme and versioning mechanism.
|
||||
|
||||
---
|
||||
|
||||
## 6. Vault Lifecycle
|
||||
|
||||
### 6.1 Sealed State
|
||||
|
||||
On boot, the root key is encrypted and the server cannot perform any signing operations. This state is called **Sealed**.
|
||||
|
||||
### 6.2 Unseal Flow
|
||||
|
||||
To transition to the **Unsealed** state, an Operator must provide the password:
|
||||
|
||||
1. The Operator initiates an unseal request.
|
||||
2. The server generates a one-time key pair and returns the public key.
|
||||
3. The Operator encrypts the user's password with this one-time public key and sends the ciphertext to the server.
|
||||
4. The server decrypts and verifies the password:
|
||||
- **Success:** The root key is decrypted and placed into a hardened memory cell. The server transitions to `Unsealed`. Any entries pending encryption scheme migration are re-encrypted.
|
||||
- **Failure:** The server returns an error indicating the password is incorrect.
|
||||
|
||||
### 6.3 Memory Protection
|
||||
|
||||
Once unsealed, the root key must be protected in memory against:
|
||||
|
||||
- Memory dumps
|
||||
- Page swaps to disk
|
||||
- Hibernation files
|
||||
|
||||
See [IMPLEMENTATION.md](IMPLEMENTATION.md) for the current and planned memory protection approaches.
|
||||
|
||||
---
|
||||
|
||||
## 7. Permission Engine
|
||||
|
||||
### 7.1 Fundamental Rules
|
||||
|
||||
- SDK clients have **no access by default**.
|
||||
- Access is granted **explicitly** by an Operator.
|
||||
- Grants are scoped to **specific wallets** and governed by **policies**.
|
||||
|
||||
Each blockchain requires its own policy system due to differences in static transaction analysis. Currently, only EVM is supported; Solana support is planned.
|
||||
|
||||
Arbiter is also responsible for ensuring that **transaction nonces are never reused**.
|
||||
|
||||
### 7.2 EVM Policies
|
||||
|
||||
Every EVM grant is scoped to a specific **wallet** and **chain ID**.
|
||||
|
||||
#### 7.2.0 Transaction Signing Sequence
|
||||
|
||||
The high-level interaction order is:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
actor SDK as SDK Client
|
||||
participant Server
|
||||
participant operator as Operator
|
||||
|
||||
SDK->>Server: SignTransactionRequest
|
||||
Server->>Server: Resolve wallet and wallet visibility
|
||||
alt Visibility approval required
|
||||
Server->>operator: Ask for wallet visibility approval
|
||||
operator-->>Server: Vote result
|
||||
end
|
||||
Server->>Server: Evaluate transaction
|
||||
Server->>Server: Load grant and limits context
|
||||
alt Grant approval required
|
||||
Server->>operator: Ask for execution / grant approval
|
||||
operator-->>Server: Vote result
|
||||
opt Create persistent grant
|
||||
Server->>Server: Create and store grant
|
||||
end
|
||||
Server->>Server: Retry evaluation
|
||||
end
|
||||
critical Final authorization path
|
||||
Server->>Server: Check limits and record execution
|
||||
Server-->>Server: Signature or evaluation error
|
||||
end
|
||||
Server-->>SDK: Signature or error
|
||||
```
|
||||
|
||||
#### 7.2.1 Transaction Sub-Grants
|
||||
|
||||
Arbiter maintains an ever-expanding database of known contracts and their ABIs. Based on contract knowledge, transaction requests fall into three categories:
|
||||
|
||||
**1. Known contract (ABI available)**
|
||||
|
||||
The transaction can be decoded and presented with semantic meaning. For example: *"Client X wants to transfer Y USDT to address Z."*
|
||||
|
||||
Available restrictions:
|
||||
- Volume limits (e.g., "no more than 10,000 tokens ever")
|
||||
- Rate limits (e.g., "no more than 100 tokens per hour")
|
||||
|
||||
**2. Unknown contract (no ABI)**
|
||||
|
||||
The transaction cannot be decoded, so its effects are opaque — it could do anything, including draining all tokens. The user is warned, and if approved, access is granted to all interactions with the contract (matched by the `to` field).
|
||||
|
||||
Available restrictions:
|
||||
- Transaction count limits (e.g., "no more than 100 transactions ever")
|
||||
- Rate limits (e.g., "no more than 5 transactions per hour")
|
||||
|
||||
**3. Plain ether transfer (no calldata)**
|
||||
|
||||
These transactions have no `calldata` and therefore cannot interact with contracts. They can be subject to the same volume and rate restrictions as above.
|
||||
|
||||
#### 7.2.2 Global Limits
|
||||
|
||||
In addition to sub-grant-specific restrictions, the following limits can be applied across all grant types:
|
||||
|
||||
- **Gas limit** — Maximum gas per transaction.
|
||||
- **Time-window restrictions** — e.g., signing allowed only 08:00–20:00 on Mondays and Thursdays.
|
||||
# Arbiter
|
||||
|
||||
Arbiter is a permissioned signing service for cryptocurrency wallets. It runs as a background service on the user's machine with an optional client application for vault management.
|
||||
|
||||
**Core principle:** The vault NEVER exposes key material. It only produces signatures when a request satisfies the configured policies.
|
||||
---
|
||||
|
||||
## 1. Peer Types
|
||||
|
||||
Arbiter distinguishes two kinds of peers:
|
||||
|
||||
- **Operator** — A client application used by the owner to manage the vault (create wallets, approve SDK clients, configure policies).
|
||||
- **SDK Client** — A consumer of signing capabilities, typically an automation tool. In the future, this could include a browser-based wallet.
|
||||
- **Recovery Operator** — A dormant recovery participant with narrowly scoped authority used only for custody recovery and operator replacement.
|
||||
|
||||
---
|
||||
|
||||
## 2. Authentication
|
||||
|
||||
### 2.1 Challenge-Response
|
||||
|
||||
All peers authenticate via public-key cryptography using a challenge-response protocol:
|
||||
|
||||
1. The peer sends its public key and requests a challenge.
|
||||
2. The server looks up the key in its database. If found, it generates a fresh challenge from random bytes plus the current timestamp.
|
||||
3. The peer signs the canonical challenge payload with its private key and sends the signature back.
|
||||
4. The server verifies the signature:
|
||||
- **Pass:** The connection is considered authenticated.
|
||||
- **Fail:** The server closes the connection.
|
||||
|
||||
Authentication challenges are per-connection, ephemeral values. They are not persisted in the peer tables, and peer records store no challenge state.
|
||||
|
||||
### 2.2 Operator Bootstrap
|
||||
|
||||
On first run — when no Operators are registered — the server generates a one-time bootstrap token. It is made available in two ways:
|
||||
|
||||
- **Local setup:** Written to `~/.arbiter/bootstrap_token` for automatic discovery by a co-located Operator.
|
||||
- **Remote setup:** Printed to the server's console output.
|
||||
|
||||
The first Operator must present this token alongside the standard challenge-response to complete registration.
|
||||
|
||||
### 2.3 SDK Client Registration
|
||||
|
||||
There is no bootstrap mechanism for SDK clients. They must be explicitly approved by an already-registered Operator.
|
||||
|
||||
---
|
||||
|
||||
## 3. Multi-Operator Governance
|
||||
|
||||
When more than one Operator is registered, the vault is treated as having multiple operators. In that mode, sensitive actions are governed by voting rather than by a single operator decision.
|
||||
|
||||
### 3.1 Voting Rules
|
||||
|
||||
Voting is based on the total number of registered operators:
|
||||
|
||||
- **1 operator:** no vote is needed; the single operator decides directly.
|
||||
- **2 operators:** full consensus is required; both operators must approve.
|
||||
- **3 or more operators:** quorum is `floor(N / 2) + 1`.
|
||||
|
||||
For a decision to count, the operator's approval or rejection must be signed by that operator's associated key. Unsigned votes, or votes that fail signature verification, are ignored.
|
||||
|
||||
Examples:
|
||||
|
||||
- **3 operators:** 2 approvals required
|
||||
- **4 operators:** 3 approvals required
|
||||
|
||||
### 3.2 Actions Requiring a Vote
|
||||
|
||||
In multi-operator mode, a successful vote is required for:
|
||||
|
||||
- approving new SDK clients
|
||||
- granting an SDK client visibility to a wallet
|
||||
- approving a one-off transaction
|
||||
- approving creation of a persistent grant
|
||||
- approving operator replacement
|
||||
- approving server updates
|
||||
- updating Shamir secret-sharing parameters
|
||||
|
||||
### 3.3 Special Rule for Key Rotation
|
||||
|
||||
Key rotation always requires full quorum, regardless of the normal voting threshold.
|
||||
|
||||
This is stricter than ordinary governance actions because rotating the root key requires every operator to participate in coordinated share refresh/update steps. The root key itself is not redistributed directly, but each operator's share material must be changed consistently.
|
||||
|
||||
### 3.4 Root Key Custody
|
||||
|
||||
When the vault has multiple operators, the vault root key is protected using Shamir secret sharing.
|
||||
|
||||
The vault root key is encrypted in a way that requires reconstruction from user-held shares rather than from a single shared password.
|
||||
|
||||
For ordinary operators, the Shamir threshold matches the ordinary governance quorum. For example:
|
||||
|
||||
- **2 operators:** `2-of-2`
|
||||
- **3 operators:** `2-of-3`
|
||||
- **4 operators:** `3-of-4`
|
||||
|
||||
In practice, the Shamir share set also includes Recovery Operator shares. This means the effective Shamir parameters are computed over the combined share pool while keeping the same threshold. For example:
|
||||
|
||||
- **3 ordinary operators + 2 recovery shares:** `2-of-5`
|
||||
|
||||
This ensures that the normal custody threshold follows the ordinary operator quorum, while still allowing dormant recovery shares to exist for break-glass recovery flows.
|
||||
|
||||
### 3.5 Recovery Operators
|
||||
|
||||
Recovery Operators are a separate peer type from ordinary vault operators.
|
||||
|
||||
Their role is intentionally narrow. They can only:
|
||||
|
||||
- participate in unsealing the vault
|
||||
- vote for operator replacement
|
||||
|
||||
Recovery Operators do not participate in routine governance such as approving SDK clients, granting wallet visibility, approving transactions, creating grants, approving server updates, or changing Shamir parameters.
|
||||
|
||||
### 3.6 Sleeping and Waking Recovery Operators
|
||||
|
||||
By default, Recovery Operators are **sleeping** and do not participate in any active flow.
|
||||
|
||||
Any ordinary operator may request that Recovery Operators **wake up**.
|
||||
|
||||
Any ordinary operator may also cancel a pending wake-up request.
|
||||
|
||||
This creates a dispute window before recovery powers become active. The default wake-up delay is **14 days**.
|
||||
|
||||
Recovery Operators are therefore part of the break-glass recovery path rather than the normal operating quorum.
|
||||
|
||||
The high-level recovery flow is:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
actor Op as Ordinary Operator
|
||||
participant Server
|
||||
actor Other as Other Operator
|
||||
actor Rec as Recovery Operator
|
||||
|
||||
Op->>Server: Request recovery wake-up
|
||||
Server-->>Op: Wake-up pending
|
||||
Note over Server: Default dispute window: 14 days
|
||||
|
||||
alt Wake-up cancelled during dispute window
|
||||
Other->>Server: Cancel wake-up
|
||||
Server-->>Op: Recovery cancelled
|
||||
Server-->>Rec: Stay sleeping
|
||||
else No cancellation for 14 days
|
||||
Server-->>Rec: Wake up
|
||||
Rec->>Server: Join recovery flow
|
||||
critical Recovery authority
|
||||
Rec->>Server: Participate in unseal
|
||||
Rec->>Server: Vote on operator replacement
|
||||
end
|
||||
Server-->>Op: Recovery mode active
|
||||
end
|
||||
```
|
||||
|
||||
### 3.7 Committee Formation
|
||||
|
||||
There are two ways to form a multi-operator committee:
|
||||
|
||||
- convert an existing single-operator vault by adding new operators
|
||||
- bootstrap an unbootstrapped vault directly into multi-operator mode
|
||||
|
||||
In both cases, committee formation is a coordinated process. Arbiter does not allow multi-operator custody to emerge implicitly from unrelated registrations.
|
||||
|
||||
### 3.8 Bootstrapping an Unbootstrapped Vault into Multi-Operator Mode
|
||||
|
||||
When an unbootstrapped vault is initialized as a multi-operator vault, the setup proceeds as follows:
|
||||
|
||||
1. An operator connects to the unbootstrapped vault using an Operator and the bootstrap token.
|
||||
2. During bootstrap setup, that operator declares:
|
||||
- the total number of ordinary operators
|
||||
- the total number of Recovery Operators
|
||||
3. The vault enters **multi-bootstrap mode**.
|
||||
4. While in multi-bootstrap mode:
|
||||
- every ordinary operator must connect with an Operator using the bootstrap token
|
||||
- every Recovery Operator must also connect using the bootstrap token
|
||||
- each participant is registered individually
|
||||
- each participant's share is created and protected with that participant's credentials
|
||||
5. The vault is considered fully bootstrapped only after all declared operator and recovery-share registrations have completed successfully.
|
||||
|
||||
This means the operator and recovery set is fixed at bootstrap completion time, based on the counts declared when multi-bootstrap mode was entered.
|
||||
|
||||
### 3.9 Special Bootstrap Constraint for Two-Operator Vaults
|
||||
|
||||
If a vault is declared with exactly **2 ordinary operators**, Arbiter requires at least **1 Recovery Operator** to be configured during bootstrap.
|
||||
|
||||
This prevents the worst-case custody failure in which a `2-of-2` operator set becomes permanently unrecoverable after loss of a single operator.
|
||||
|
||||
---
|
||||
|
||||
## 4. Server Identity
|
||||
|
||||
The server proves its identity using TLS with a self-signed certificate. The TLS private key is generated on first run and is long-term; no rotation mechanism exists yet due to the complexity of multi-peer coordination.
|
||||
|
||||
Peers verify the server by its **public key fingerprint**:
|
||||
|
||||
- **Operator (local):** Receives the fingerprint automatically through the bootstrap token.
|
||||
- **Operator (remote) / SDK Client:** Must receive the fingerprint out-of-band.
|
||||
|
||||
> A streamlined setup mechanism using a single connection string is planned but not yet implemented.
|
||||
|
||||
---
|
||||
|
||||
## 5. Key Management
|
||||
|
||||
### 5.1 Key Hierarchy
|
||||
|
||||
There are three layers of keys:
|
||||
|
||||
| Key | Encrypts | Encrypted by |
|
||||
|---|---|---|
|
||||
| **User key** (password) | Root key | — (derived from user input) |
|
||||
| **Root key** | Wallet keys | User key |
|
||||
| **Wallet keys** | — (used for signing) | Root key |
|
||||
|
||||
This layered design enables:
|
||||
|
||||
- **Password rotation** without re-encrypting every wallet key (only the root key is re-encrypted).
|
||||
- **Root key rotation** without requiring the user to change their password.
|
||||
|
||||
### 5.2 Encryption at Rest
|
||||
|
||||
The database stores everything in encrypted form using symmetric AEAD. The encryption scheme is versioned to support transparent migration — when the vault unseals, Arbiter automatically re-encrypts any entries that are behind the current scheme version. See [IMPLEMENTATION.md](IMPLEMENTATION.md) for the specific scheme and versioning mechanism.
|
||||
|
||||
---
|
||||
|
||||
## 6. Vault Lifecycle
|
||||
|
||||
### 6.1 Sealed State
|
||||
|
||||
On boot, the root key is encrypted and the server cannot perform any signing operations. This state is called **Sealed**.
|
||||
|
||||
### 6.2 Unseal Flow
|
||||
|
||||
To transition to the **Unsealed** state, an Operator must provide the password:
|
||||
|
||||
1. The Operator initiates an unseal request.
|
||||
2. The server generates a one-time key pair and returns the public key.
|
||||
3. The Operator encrypts the user's password with this one-time public key and sends the ciphertext to the server.
|
||||
4. The server decrypts and verifies the password:
|
||||
- **Success:** The root key is decrypted and placed into a hardened memory cell. The server transitions to `Unsealed`. Any entries pending encryption scheme migration are re-encrypted.
|
||||
- **Failure:** The server returns an error indicating the password is incorrect.
|
||||
|
||||
### 6.3 Memory Protection
|
||||
|
||||
Once unsealed, the root key must be protected in memory against:
|
||||
|
||||
- Memory dumps
|
||||
- Page swaps to disk
|
||||
- Hibernation files
|
||||
|
||||
See [IMPLEMENTATION.md](IMPLEMENTATION.md) for the current and planned memory protection approaches.
|
||||
|
||||
---
|
||||
|
||||
## 7. Permission Engine
|
||||
|
||||
### 7.1 Fundamental Rules
|
||||
|
||||
- SDK clients have **no access by default**.
|
||||
- Access is granted **explicitly** by an Operator.
|
||||
- Grants are scoped to **specific wallets** and governed by **policies**.
|
||||
|
||||
Each blockchain requires its own policy system due to differences in static transaction analysis. Currently, only EVM is supported; Solana support is planned.
|
||||
|
||||
Arbiter is also responsible for ensuring that **transaction nonces are never reused**.
|
||||
|
||||
### 7.2 EVM Policies
|
||||
|
||||
Every EVM grant is scoped to a specific **wallet** and **chain ID**.
|
||||
|
||||
#### 7.2.0 Transaction Signing Sequence
|
||||
|
||||
The high-level interaction order is:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
actor SDK as SDK Client
|
||||
participant Server
|
||||
participant operator as Operator
|
||||
|
||||
SDK->>Server: SignTransactionRequest
|
||||
Server->>Server: Resolve wallet and wallet visibility
|
||||
alt Visibility approval required
|
||||
Server->>operator: Ask for wallet visibility approval
|
||||
operator-->>Server: Vote result
|
||||
end
|
||||
Server->>Server: Evaluate transaction
|
||||
Server->>Server: Load grant and limits context
|
||||
alt Grant approval required
|
||||
Server->>operator: Ask for execution / grant approval
|
||||
operator-->>Server: Vote result
|
||||
opt Create persistent grant
|
||||
Server->>Server: Create and store grant
|
||||
end
|
||||
Server->>Server: Retry evaluation
|
||||
end
|
||||
critical Final authorization path
|
||||
Server->>Server: Check limits and record execution
|
||||
Server-->>Server: Signature or evaluation error
|
||||
end
|
||||
Server-->>SDK: Signature or error
|
||||
```
|
||||
|
||||
#### 7.2.1 Transaction Sub-Grants
|
||||
|
||||
Arbiter maintains an ever-expanding database of known contracts and their ABIs. Based on contract knowledge, transaction requests fall into three categories:
|
||||
|
||||
**1. Known contract (ABI available)**
|
||||
|
||||
The transaction can be decoded and presented with semantic meaning. For example: *"Client X wants to transfer Y USDT to address Z."*
|
||||
|
||||
Available restrictions:
|
||||
- Volume limits (e.g., "no more than 10,000 tokens ever")
|
||||
- Rate limits (e.g., "no more than 100 tokens per hour")
|
||||
|
||||
**2. Unknown contract (no ABI)**
|
||||
|
||||
The transaction cannot be decoded, so its effects are opaque — it could do anything, including draining all tokens. The user is warned, and if approved, access is granted to all interactions with the contract (matched by the `to` field).
|
||||
|
||||
Available restrictions:
|
||||
- Transaction count limits (e.g., "no more than 100 transactions ever")
|
||||
- Rate limits (e.g., "no more than 5 transactions per hour")
|
||||
|
||||
**3. Plain ether transfer (no calldata)**
|
||||
|
||||
These transactions have no `calldata` and therefore cannot interact with contracts. They can be subject to the same volume and rate restrictions as above.
|
||||
|
||||
#### 7.2.2 Global Limits
|
||||
|
||||
In addition to sub-grant-specific restrictions, the following limits can be applied across all grant types:
|
||||
|
||||
- **Gas limit** — Maximum gas per transaction.
|
||||
- **Time-window restrictions** — e.g., signing allowed only 08:00–20:00 on Mondays and Thursdays.
|
||||
|
||||
@@ -1,226 +1,226 @@
|
||||
# Implementation Details
|
||||
|
||||
This document covers concrete technology choices and dependencies. For the architectural design, see [ARCHITECTURE.md](ARCHITECTURE.md).
|
||||
|
||||
---
|
||||
|
||||
## Client Connection Flow
|
||||
|
||||
### Authentication Result Semantics
|
||||
|
||||
Authentication no longer uses an implicit success-only response shape. Both `client` and `operator` return explicit auth status enums over the wire.
|
||||
|
||||
- **Client:** `AuthResult` may return `SUCCESS`, `INVALID_KEY`, `INVALID_SIGNATURE`, `APPROVAL_DENIED`, `NO_OPERATORS_ONLINE`, or `INTERNAL`
|
||||
- **Operator:** `AuthResult` may return `SUCCESS`, `INVALID_KEY`, `INVALID_SIGNATURE`, `BOOTSTRAP_REQUIRED`, `TOKEN_INVALID`, or `INTERNAL`
|
||||
|
||||
This makes transport-level failures and actor/domain-level auth failures distinct:
|
||||
|
||||
- **Transport/protocol failures** are surfaced as stream/status errors
|
||||
- **Authentication failures** are surfaced as successful protocol responses carrying an explicit auth status
|
||||
|
||||
Clients are expected to handle these status codes directly and present the concrete failure reason to the user.
|
||||
|
||||
### New Client Approval
|
||||
|
||||
When a client whose public key is not yet in the database connects, all connected operators are asked to approve the connection. The first operator to respond determines the outcome; remaining requests are cancelled via a watch channel.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A([Client connects]) --> B[Receive AuthChallengeRequest]
|
||||
B --> C{pubkey in DB?}
|
||||
|
||||
C -- yes --> G[Generate AuthChallenge]
|
||||
|
||||
C -- no --> E[Ask all Operators:\nClientConnectionRequest]
|
||||
E --> F{First response}
|
||||
F -- denied --> Z([Reject connection])
|
||||
F -- approved --> F2[Cancel remaining\nOperator requests]
|
||||
F2 --> F3[INSERT client]
|
||||
F3 --> G
|
||||
|
||||
G --> H[Send AuthChallenge\ntimestamp + random bytes]
|
||||
H --> I[Receive AuthChallengeSolution]
|
||||
I --> K{Signature valid?}
|
||||
K -- no --> Z
|
||||
K -- yes --> J([Session started])
|
||||
```
|
||||
|
||||
Auth challenges are generated from fresh random bytes plus a nanosecond timestamp. The server keeps the issued challenge only in the in-flight authentication state for that connection, then verifies the signature against the same canonical challenge payload.
|
||||
|
||||
The authentication schema stores peer identity, not replay counters:
|
||||
|
||||
- `program_client` stores the SDK client's public key, metadata binding, and timestamps.
|
||||
- `operator_client` stores the Operator public key and timestamps.
|
||||
- Neither table stores an authentication nonce, and challenge generation does not update either table.
|
||||
|
||||
---
|
||||
|
||||
## Cryptography
|
||||
|
||||
### Authentication
|
||||
- **Client protocol:** ML-DSA
|
||||
|
||||
### User-Agent Authentication
|
||||
|
||||
Operator authentication supports multiple signature schemes because platform-provided "hardware-bound" keys do not expose a uniform algorithm across operating systems and hardware.
|
||||
|
||||
- **Supported schemes:** ML-DSA
|
||||
- **Why:** Secure Enclave (MacOS) support them natively, on other platforms we could emulate while they roll-out
|
||||
|
||||
### Encryption at Rest
|
||||
- **Scheme:** Symmetric AEAD — currently **XChaCha20-Poly1305**
|
||||
- **Version tracking:** Each `aead_encrypted` database entry carries a `scheme` field denoting the version, enabling transparent migration on unseal
|
||||
|
||||
### Server Identity
|
||||
- **Transport:** TLS with a self-signed certificate
|
||||
- **Key type:** Generated on first run; long-term (no rotation mechanism yet)
|
||||
|
||||
---
|
||||
|
||||
## Communication
|
||||
|
||||
- **Protocol:** gRPC with Protocol Buffers
|
||||
- **Request/response matching:** multiplexed over a single bidirectional stream using per-connection request IDs
|
||||
- **Server identity distribution:** `ServerInfo` protobuf struct containing the TLS public key fingerprint
|
||||
- **Future consideration:** grpc-web lacks bidirectional stream support, so a browser-based wallet may require protojson over WebSocket
|
||||
|
||||
### Request Multiplexing
|
||||
|
||||
Both `client` and `operator` connections support multiple in-flight requests over one gRPC bidi stream.
|
||||
|
||||
- Every request carries a monotonically increasing request ID
|
||||
- Every normal response echoes the request ID it corresponds to
|
||||
- Out-of-band server messages omit the response ID entirely
|
||||
- The server rejects already-seen request IDs at the transport adapter boundary before business logic sees the message
|
||||
|
||||
This keeps request correlation entirely in transport/client connection code while leaving actor and domain handlers unaware of request IDs.
|
||||
|
||||
---
|
||||
|
||||
## EVM Policy Engine
|
||||
|
||||
### Overview
|
||||
|
||||
The EVM engine classifies incoming transactions, enforces grant constraints, and records executions. It is the sole path through which a wallet key is used for signing.
|
||||
|
||||
The central abstraction is the `Policy` trait. Each implementation handles one semantic transaction category and owns its own database tables for grant storage and transaction logging.
|
||||
|
||||
### Transaction Evaluation Flow
|
||||
|
||||
`Engine::evaluate_transaction` runs the following steps in order:
|
||||
|
||||
1. **Classify** — Each registered policy's `analyze(context)` inspects the transaction fields (`chain`, `to`, `value`, `calldata`). The first one returning `Some(meaning)` wins. If none match, the transaction is rejected as `UnsupportedTransactionType`.
|
||||
2. **Find grant** — `Policy::try_find_grant` queries for a non-revoked grant covering this wallet, client, chain, and target address.
|
||||
3. **Check shared constraints** — `check_shared_constraints` runs in the engine before any policy-specific logic. It enforces the validity window, gas fee caps, and transaction count rate limit (see below).
|
||||
4. **Evaluate** — `Policy::evaluate` checks the decoded meaning against the grant's policy-specific constraints and returns any violations.
|
||||
5. **Record** — If `RunKind::Execution` and there are no violations, the engine writes to `evm_transaction_log` and calls `Policy::record_transaction` for any policy-specific logging (e.g., token transfer volume).
|
||||
|
||||
The detailed branch structure is shown below:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[SDK Client sends sign transaction request] --> B[Server resolves wallet]
|
||||
B --> C{Wallet exists?}
|
||||
|
||||
C -- No --> Z1[Return wallet not found error]
|
||||
C -- Yes --> D[Check SDK client wallet visibility]
|
||||
|
||||
D --> E{Wallet visible to SDK client?}
|
||||
E -- No --> F[Start wallet visibility voting flow]
|
||||
F --> G{Vote approved?}
|
||||
G -- No --> Z2[Return wallet access denied error]
|
||||
G -- Yes --> H[Persist wallet visibility]
|
||||
E -- Yes --> I[Classify transaction meaning]
|
||||
H --> I
|
||||
|
||||
I --> J{Meaning supported?}
|
||||
J -- No --> Z3[Return unsupported transaction error]
|
||||
J -- Yes --> K[Find matching grant]
|
||||
|
||||
K --> L{Grant exists?}
|
||||
L -- Yes --> M[Check grant limits]
|
||||
L -- No --> N[Start execution or grant voting flow]
|
||||
|
||||
N --> O{Operator decision}
|
||||
O -- Reject --> Z4[Return no matching grant error]
|
||||
O -- Allow once --> M
|
||||
O -- Create grant --> P[Create grant with user-selected limits]
|
||||
P --> Q[Persist grant]
|
||||
Q --> M
|
||||
|
||||
M --> R{Limits exceeded?}
|
||||
R -- Yes --> Z5[Return evaluation error]
|
||||
R -- No --> S[Record transaction in logs]
|
||||
S --> T[Produce signature]
|
||||
T --> U[Return signature to SDK client]
|
||||
|
||||
note1[Limit checks include volume, count, and gas constraints.]
|
||||
note2[Grant lookup depends on classified meaning, such as ether transfer or token transfer.]
|
||||
|
||||
K -. uses .-> note2
|
||||
M -. checks .-> note1
|
||||
```
|
||||
|
||||
### Policy Trait
|
||||
|
||||
| Method | Purpose |
|
||||
|---|---|
|
||||
| `analyze` | Pure — classifies a transaction into a typed `Meaning`, or `None` if this policy doesn't apply |
|
||||
| `evaluate` | Checks the `Meaning` against a `Grant`; returns a list of `EvalViolation`s |
|
||||
| `create_grant` | Inserts policy-specific rows; returns the specific grant ID |
|
||||
| `try_find_grant` | Finds a matching non-revoked grant for the given `EvalContext` |
|
||||
| `find_all_grants` | Returns all non-revoked grants (used for listing) |
|
||||
| `record_transaction` | Persists policy-specific data after execution |
|
||||
|
||||
`analyze` and `evaluate` are intentionally separate: classification is pure and cheap, while evaluation may involve DB queries (e.g., fetching past transfer volume).
|
||||
|
||||
### Registered Policies
|
||||
|
||||
**EtherTransfer** — plain ETH transfers (empty calldata)
|
||||
|
||||
- Grant requires: allowlist of recipient addresses + one volumetric rate limit (max ETH over a time window)
|
||||
- Violations: recipient not in allowlist, cumulative ETH volume exceeded
|
||||
|
||||
**TokenTransfer** — ERC-20 `transfer(address,uint256)` calls
|
||||
|
||||
- Recognised by ABI-decoding the `transfer(address,uint256)` selector against a static registry of known token contracts (`arbiter_tokens_registry`)
|
||||
- Grant requires: token contract address, optional recipient restriction, zero or more volumetric rate limits
|
||||
- Violations: recipient mismatch, any volumetric limit exceeded
|
||||
|
||||
### Grant Model
|
||||
|
||||
Every grant has two layers:
|
||||
|
||||
- **Shared (`evm_basic_grant`)** — wallet, chain, validity period, gas fee caps, transaction count rate limit. One row per grant regardless of type.
|
||||
- **Specific** — policy-owned tables (`evm_ether_transfer_grant`, `evm_token_transfer_grant`) holding type-specific configuration.
|
||||
|
||||
`find_all_grants` uses a `#[diesel::auto_type]` base join between the specific and shared tables, then batch-loads related rows (targets, volume limits) in two additional queries to avoid N+1.
|
||||
|
||||
The engine exposes `list_all_grants` which collects across all policy types into `Vec<Grant<SpecificGrant>>` via a blanket `From<Grant<S>> for Grant<SpecificGrant>` conversion.
|
||||
|
||||
### Shared Constraints (enforced by the engine)
|
||||
|
||||
These are checked centrally in `check_shared_constraints` before policy evaluation:
|
||||
|
||||
| Constraint | Fields | Behaviour |
|
||||
|---|---|---|
|
||||
| Validity window | `valid_from`, `valid_until` | Emits `InvalidTime` if current time is outside the range |
|
||||
| Gas fee cap | `max_gas_fee_per_gas`, `max_priority_fee_per_gas` | Emits `GasLimitExceeded` if either cap is breached |
|
||||
| Tx count rate limit | `rate_limit` (`count` + `window`) | Counts rows in `evm_transaction_log` within the window; emits `RateLimitExceeded` if at or above the limit |
|
||||
|
||||
---
|
||||
|
||||
### Known Limitations
|
||||
|
||||
- **Only EIP-1559 transactions are supported.** Legacy and EIP-2930 types are rejected outright.
|
||||
- **No opaque-calldata (unknown contract) grant type.** The architecture describes a category for unrecognised contracts, but no policy implements it yet. Any transaction that is not a plain ETH transfer or a known ERC-20 transfer is unconditionally rejected.
|
||||
- **Token registry is static.** Tokens are recognised only if they appear in the hard-coded `arbiter_tokens_registry` crate. There is no mechanism to register additional contracts at runtime.
|
||||
|
||||
---
|
||||
|
||||
## Memory Protection
|
||||
|
||||
The unsealed root key must be held in a hardened memory cell resistant to dumps, page swaps, and hibernation.
|
||||
|
||||
- **Current:** A dedicated memory-protection abstraction is in place, with `memsafe` used behind that abstraction today
|
||||
- **Planned:** Additional backends can be introduced behind the same abstraction, including a custom implementation based on `mlock` (Unix) and `VirtualProtect` (Windows)
|
||||
# Implementation Details
|
||||
|
||||
This document covers concrete technology choices and dependencies. For the architectural design, see [ARCHITECTURE.md](ARCHITECTURE.md).
|
||||
|
||||
---
|
||||
|
||||
## Client Connection Flow
|
||||
|
||||
### Authentication Result Semantics
|
||||
|
||||
Authentication no longer uses an implicit success-only response shape. Both `client` and `operator` return explicit auth status enums over the wire.
|
||||
|
||||
- **Client:** `AuthResult` may return `SUCCESS`, `INVALID_KEY`, `INVALID_SIGNATURE`, `APPROVAL_DENIED`, `NO_OPERATORS_ONLINE`, or `INTERNAL`
|
||||
- **Operator:** `AuthResult` may return `SUCCESS`, `INVALID_KEY`, `INVALID_SIGNATURE`, `BOOTSTRAP_REQUIRED`, `TOKEN_INVALID`, or `INTERNAL`
|
||||
|
||||
This makes transport-level failures and actor/domain-level auth failures distinct:
|
||||
|
||||
- **Transport/protocol failures** are surfaced as stream/status errors
|
||||
- **Authentication failures** are surfaced as successful protocol responses carrying an explicit auth status
|
||||
|
||||
Clients are expected to handle these status codes directly and present the concrete failure reason to the user.
|
||||
|
||||
### New Client Approval
|
||||
|
||||
When a client whose public key is not yet in the database connects, all connected operators are asked to approve the connection. The first operator to respond determines the outcome; remaining requests are cancelled via a watch channel.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A([Client connects]) --> B[Receive AuthChallengeRequest]
|
||||
B --> C{pubkey in DB?}
|
||||
|
||||
C -- yes --> G[Generate AuthChallenge]
|
||||
|
||||
C -- no --> E[Ask all Operators:\nClientConnectionRequest]
|
||||
E --> F{First response}
|
||||
F -- denied --> Z([Reject connection])
|
||||
F -- approved --> F2[Cancel remaining\nOperator requests]
|
||||
F2 --> F3[INSERT client]
|
||||
F3 --> G
|
||||
|
||||
G --> H[Send AuthChallenge\ntimestamp + random bytes]
|
||||
H --> I[Receive AuthChallengeSolution]
|
||||
I --> K{Signature valid?}
|
||||
K -- no --> Z
|
||||
K -- yes --> J([Session started])
|
||||
```
|
||||
|
||||
Auth challenges are generated from fresh random bytes plus a nanosecond timestamp. The server keeps the issued challenge only in the in-flight authentication state for that connection, then verifies the signature against the same canonical challenge payload.
|
||||
|
||||
The authentication schema stores peer identity, not replay counters:
|
||||
|
||||
- `program_client` stores the SDK client's public key, metadata binding, and timestamps.
|
||||
- `operator_client` stores the Operator public key and timestamps.
|
||||
- Neither table stores an authentication nonce, and challenge generation does not update either table.
|
||||
|
||||
---
|
||||
|
||||
## Cryptography
|
||||
|
||||
### Authentication
|
||||
- **Client protocol:** ML-DSA
|
||||
|
||||
### User-Agent Authentication
|
||||
|
||||
Operator authentication supports multiple signature schemes because platform-provided "hardware-bound" keys do not expose a uniform algorithm across operating systems and hardware.
|
||||
|
||||
- **Supported schemes:** ML-DSA
|
||||
- **Why:** Secure Enclave (MacOS) support them natively, on other platforms we could emulate while they roll-out
|
||||
|
||||
### Encryption at Rest
|
||||
- **Scheme:** Symmetric AEAD — currently **XChaCha20-Poly1305**
|
||||
- **Version tracking:** Each `aead_encrypted` database entry carries a `scheme` field denoting the version, enabling transparent migration on unseal
|
||||
|
||||
### Server Identity
|
||||
- **Transport:** TLS with a self-signed certificate
|
||||
- **Key type:** Generated on first run; long-term (no rotation mechanism yet)
|
||||
|
||||
---
|
||||
|
||||
## Communication
|
||||
|
||||
- **Protocol:** gRPC with Protocol Buffers
|
||||
- **Request/response matching:** multiplexed over a single bidirectional stream using per-connection request IDs
|
||||
- **Server identity distribution:** `ServerInfo` protobuf struct containing the TLS public key fingerprint
|
||||
- **Future consideration:** grpc-web lacks bidirectional stream support, so a browser-based wallet may require protojson over WebSocket
|
||||
|
||||
### Request Multiplexing
|
||||
|
||||
Both `client` and `operator` connections support multiple in-flight requests over one gRPC bidi stream.
|
||||
|
||||
- Every request carries a monotonically increasing request ID
|
||||
- Every normal response echoes the request ID it corresponds to
|
||||
- Out-of-band server messages omit the response ID entirely
|
||||
- The server rejects already-seen request IDs at the transport adapter boundary before business logic sees the message
|
||||
|
||||
This keeps request correlation entirely in transport/client connection code while leaving actor and domain handlers unaware of request IDs.
|
||||
|
||||
---
|
||||
|
||||
## EVM Policy Engine
|
||||
|
||||
### Overview
|
||||
|
||||
The EVM engine classifies incoming transactions, enforces grant constraints, and records executions. It is the sole path through which a wallet key is used for signing.
|
||||
|
||||
The central abstraction is the `Policy` trait. Each implementation handles one semantic transaction category and owns its own database tables for grant storage and transaction logging.
|
||||
|
||||
### Transaction Evaluation Flow
|
||||
|
||||
`Engine::evaluate_transaction` runs the following steps in order:
|
||||
|
||||
1. **Classify** — Each registered policy's `analyze(context)` inspects the transaction fields (`chain`, `to`, `value`, `calldata`). The first one returning `Some(meaning)` wins. If none match, the transaction is rejected as `UnsupportedTransactionType`.
|
||||
2. **Find grant** — `Policy::try_find_grant` queries for a non-revoked grant covering this wallet, client, chain, and target address.
|
||||
3. **Check shared constraints** — `check_shared_constraints` runs in the engine before any policy-specific logic. It enforces the validity window, gas fee caps, and transaction count rate limit (see below).
|
||||
4. **Evaluate** — `Policy::evaluate` checks the decoded meaning against the grant's policy-specific constraints and returns any violations.
|
||||
5. **Record** — If `RunKind::Execution` and there are no violations, the engine writes to `evm_transaction_log` and calls `Policy::record_transaction` for any policy-specific logging (e.g., token transfer volume).
|
||||
|
||||
The detailed branch structure is shown below:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[SDK Client sends sign transaction request] --> B[Server resolves wallet]
|
||||
B --> C{Wallet exists?}
|
||||
|
||||
C -- No --> Z1[Return wallet not found error]
|
||||
C -- Yes --> D[Check SDK client wallet visibility]
|
||||
|
||||
D --> E{Wallet visible to SDK client?}
|
||||
E -- No --> F[Start wallet visibility voting flow]
|
||||
F --> G{Vote approved?}
|
||||
G -- No --> Z2[Return wallet access denied error]
|
||||
G -- Yes --> H[Persist wallet visibility]
|
||||
E -- Yes --> I[Classify transaction meaning]
|
||||
H --> I
|
||||
|
||||
I --> J{Meaning supported?}
|
||||
J -- No --> Z3[Return unsupported transaction error]
|
||||
J -- Yes --> K[Find matching grant]
|
||||
|
||||
K --> L{Grant exists?}
|
||||
L -- Yes --> M[Check grant limits]
|
||||
L -- No --> N[Start execution or grant voting flow]
|
||||
|
||||
N --> O{Operator decision}
|
||||
O -- Reject --> Z4[Return no matching grant error]
|
||||
O -- Allow once --> M
|
||||
O -- Create grant --> P[Create grant with user-selected limits]
|
||||
P --> Q[Persist grant]
|
||||
Q --> M
|
||||
|
||||
M --> R{Limits exceeded?}
|
||||
R -- Yes --> Z5[Return evaluation error]
|
||||
R -- No --> S[Record transaction in logs]
|
||||
S --> T[Produce signature]
|
||||
T --> U[Return signature to SDK client]
|
||||
|
||||
note1[Limit checks include volume, count, and gas constraints.]
|
||||
note2[Grant lookup depends on classified meaning, such as ether transfer or token transfer.]
|
||||
|
||||
K -. uses .-> note2
|
||||
M -. checks .-> note1
|
||||
```
|
||||
|
||||
### Policy Trait
|
||||
|
||||
| Method | Purpose |
|
||||
|---|---|
|
||||
| `analyze` | Pure — classifies a transaction into a typed `Meaning`, or `None` if this policy doesn't apply |
|
||||
| `evaluate` | Checks the `Meaning` against a `Grant`; returns a list of `EvalViolation`s |
|
||||
| `create_grant` | Inserts policy-specific rows; returns the specific grant ID |
|
||||
| `try_find_grant` | Finds a matching non-revoked grant for the given `EvalContext` |
|
||||
| `find_all_grants` | Returns all non-revoked grants (used for listing) |
|
||||
| `record_transaction` | Persists policy-specific data after execution |
|
||||
|
||||
`analyze` and `evaluate` are intentionally separate: classification is pure and cheap, while evaluation may involve DB queries (e.g., fetching past transfer volume).
|
||||
|
||||
### Registered Policies
|
||||
|
||||
**EtherTransfer** — plain ETH transfers (empty calldata)
|
||||
|
||||
- Grant requires: allowlist of recipient addresses + one volumetric rate limit (max ETH over a time window)
|
||||
- Violations: recipient not in allowlist, cumulative ETH volume exceeded
|
||||
|
||||
**TokenTransfer** — ERC-20 `transfer(address,uint256)` calls
|
||||
|
||||
- Recognised by ABI-decoding the `transfer(address,uint256)` selector against a static registry of known token contracts (`arbiter_tokens_registry`)
|
||||
- Grant requires: token contract address, optional recipient restriction, zero or more volumetric rate limits
|
||||
- Violations: recipient mismatch, any volumetric limit exceeded
|
||||
|
||||
### Grant Model
|
||||
|
||||
Every grant has two layers:
|
||||
|
||||
- **Shared (`evm_basic_grant`)** — wallet, chain, validity period, gas fee caps, transaction count rate limit. One row per grant regardless of type.
|
||||
- **Specific** — policy-owned tables (`evm_ether_transfer_grant`, `evm_token_transfer_grant`) holding type-specific configuration.
|
||||
|
||||
`find_all_grants` uses a `#[diesel::auto_type]` base join between the specific and shared tables, then batch-loads related rows (targets, volume limits) in two additional queries to avoid N+1.
|
||||
|
||||
The engine exposes `list_all_grants` which collects across all policy types into `Vec<Grant<SpecificGrant>>` via a blanket `From<Grant<S>> for Grant<SpecificGrant>` conversion.
|
||||
|
||||
### Shared Constraints (enforced by the engine)
|
||||
|
||||
These are checked centrally in `check_shared_constraints` before policy evaluation:
|
||||
|
||||
| Constraint | Fields | Behaviour |
|
||||
|---|---|---|
|
||||
| Validity window | `valid_from`, `valid_until` | Emits `InvalidTime` if current time is outside the range |
|
||||
| Gas fee cap | `max_gas_fee_per_gas`, `max_priority_fee_per_gas` | Emits `GasLimitExceeded` if either cap is breached |
|
||||
| Tx count rate limit | `rate_limit` (`count` + `window`) | Counts rows in `evm_transaction_log` within the window; emits `RateLimitExceeded` if at or above the limit |
|
||||
|
||||
---
|
||||
|
||||
### Known Limitations
|
||||
|
||||
- **Only EIP-1559 transactions are supported.** Legacy and EIP-2930 types are rejected outright.
|
||||
- **No opaque-calldata (unknown contract) grant type.** The architecture describes a category for unrecognised contracts, but no policy implements it yet. Any transaction that is not a plain ETH transfer or a known ERC-20 transfer is unconditionally rejected.
|
||||
- **Token registry is static.** Tokens are recognised only if they appear in the hard-coded `arbiter_tokens_registry` crate. There is no mechanism to register additional contracts at runtime.
|
||||
|
||||
---
|
||||
|
||||
## Memory Protection
|
||||
|
||||
The unsealed root key must be held in a hardened memory cell resistant to dumps, page swaps, and hibernation.
|
||||
|
||||
- **Current:** A dedicated memory-protection abstraction is in place, with `memsafe` used behind that abstraction today
|
||||
- **Planned:** Additional backends can be introduced behind the same abstraction, including a custom implementation based on `mlock` (Unix) and `VirtualProtect` (Windows)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -1,170 +1,170 @@
|
||||
# Grant Grid View — Design Spec
|
||||
|
||||
**Date:** 2026-03-28
|
||||
|
||||
## Overview
|
||||
|
||||
Add a "Grants" dashboard tab to the Flutter operator app that displays all EVM grants as a card-based grid. Each card shows a compact summary (type, chain, wallet address, client name) with a revoke action. The tab integrates into the existing `AdaptiveScaffold` navigation alongside Wallets, Clients, and About.
|
||||
|
||||
## Scope
|
||||
|
||||
- New `walletAccessListProvider` for fetching wallet access entries with their DB row IDs
|
||||
- New `EvmGrantsScreen` as a dashboard tab
|
||||
- Grant card widget with enriched display (type, chain, wallet, client)
|
||||
- Revoke action wired to existing `executeRevokeEvmGrant` mutation
|
||||
- Dashboard tab bar and router updated
|
||||
- New token-transfer accent color added to `Palette`
|
||||
|
||||
**Out of scope:** Fixing grant creation (separate task).
|
||||
|
||||
---
|
||||
|
||||
## Data Layer
|
||||
|
||||
### `walletAccessListProvider`
|
||||
|
||||
**File:** `operator/lib/providers/sdk_clients/wallet_access_list.dart`
|
||||
|
||||
- `@riverpod` class, watches `connectionManagerProvider.future`
|
||||
- Returns `List<SdkClientWalletAccess>?` (null when not connected)
|
||||
- Each entry: `.id` (wallet_access_id), `.access.walletId`, `.access.sdkClientId`
|
||||
- Exposes a `refresh()` method following the same pattern as `EvmGrants.refresh()`
|
||||
|
||||
### Enrichment at render time (Approach A)
|
||||
|
||||
The `EvmGrantsScreen` watches four providers:
|
||||
1. `evmGrantsProvider` — the grant list
|
||||
2. `walletAccessListProvider` — to resolve wallet_access_id → (wallet_id, sdk_client_id)
|
||||
3. `evmProvider` — to resolve wallet_id → wallet address
|
||||
4. `sdkClientsProvider` — to resolve sdk_client_id → client name
|
||||
|
||||
All lookups are in-memory Maps built inside the build method; no extra model class needed.
|
||||
|
||||
Fallbacks:
|
||||
- Wallet address not found → `"Access #N"` where N is the wallet_access_id
|
||||
- Client name not found → `"Client #N"` where N is the sdk_client_id
|
||||
|
||||
---
|
||||
|
||||
## Route Structure
|
||||
|
||||
```
|
||||
/dashboard
|
||||
/evm ← existing (Wallets tab)
|
||||
/clients ← existing (Clients tab)
|
||||
/grants ← NEW (Grants tab)
|
||||
/about ← existing
|
||||
|
||||
/evm-grants/create ← existing push route (unchanged)
|
||||
```
|
||||
|
||||
### Changes to `router.dart`
|
||||
|
||||
Add inside dashboard children:
|
||||
```dart
|
||||
AutoRoute(page: EvmGrantsRoute.page, path: 'grants'),
|
||||
```
|
||||
|
||||
### Changes to `dashboard.dart`
|
||||
|
||||
Add to `routes` list:
|
||||
```dart
|
||||
const EvmGrantsRoute()
|
||||
```
|
||||
|
||||
Add `NavigationDestination`:
|
||||
```dart
|
||||
NavigationDestination(
|
||||
icon: Icon(Icons.policy_outlined),
|
||||
selectedIcon: Icon(Icons.policy),
|
||||
label: 'Grants',
|
||||
),
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Screen: `EvmGrantsScreen`
|
||||
|
||||
**File:** `operator/lib/screens/dashboard/evm/grants/grants.dart`
|
||||
|
||||
```
|
||||
Scaffold
|
||||
└─ SafeArea
|
||||
└─ RefreshIndicator.adaptive (refreshes evmGrantsProvider + walletAccessListProvider)
|
||||
└─ ListView (BouncingScrollPhysics + AlwaysScrollableScrollPhysics)
|
||||
├─ PageHeader
|
||||
│ title: 'EVM Grants'
|
||||
│ isBusy: evmGrantsProvider.isLoading
|
||||
│ actions: [CreateGrantButton, RefreshButton]
|
||||
├─ SizedBox(height: 1.8.h)
|
||||
└─ <content>
|
||||
```
|
||||
|
||||
### State handling
|
||||
|
||||
Matches the pattern from `EvmScreen` and `ClientsScreen`:
|
||||
|
||||
| State | Display |
|
||||
|---|---|
|
||||
| Loading (no data yet) | `_StatePanel` with spinner, "Loading grants" |
|
||||
| Error | `_StatePanel` with coral icon, error message, Retry button |
|
||||
| No connection | `_StatePanel`, "No active server connection" |
|
||||
| Empty list | `_StatePanel`, "No grants yet", with Create Grant shortcut |
|
||||
| Data | Column of `_GrantCard` widgets |
|
||||
|
||||
### Header actions
|
||||
|
||||
**CreateGrantButton:** `FilledButton.icon` with `Icons.add_rounded`, pushes `CreateEvmGrantRoute()` via `context.router.push(...)`.
|
||||
|
||||
**RefreshButton:** `OutlinedButton.icon` with `Icons.refresh`, calls `ref.read(evmGrantsProvider.notifier).refresh()`.
|
||||
|
||||
---
|
||||
|
||||
## Grant Card: `_GrantCard`
|
||||
|
||||
**Layout:**
|
||||
|
||||
```
|
||||
Container (rounded 24, Palette.cream bg, Palette.line border)
|
||||
└─ IntrinsicHeight > Row
|
||||
├─ Accent strip (0.8.w wide, full height, rounded left)
|
||||
└─ Padding > Column
|
||||
├─ Row 1: TypeBadge + ChainChip + Spacer + RevokeButton
|
||||
└─ Row 2: WalletText + "·" + ClientText
|
||||
```
|
||||
|
||||
**Accent color by grant type:**
|
||||
- Ether transfer → `Palette.coral`
|
||||
- Token transfer → `Palette.token` (new entry in `Palette` — indigo, e.g. `Color(0xFF5C6BC0)`)
|
||||
|
||||
**TypeBadge:** Small pill container with accent color background at 15% opacity, accent-colored text. Label: `'Ether'` or `'Token'`.
|
||||
|
||||
**ChainChip:** Small container: `'Chain ${grant.shared.chainId}'`, muted ink color.
|
||||
|
||||
**WalletText:** Short hex address (`0xabc...def`) from wallet lookup, `bodySmall`, monospace font family.
|
||||
|
||||
**ClientText:** Client name from `sdkClientsProvider` lookup, or fallback string. `bodySmall`, muted ink.
|
||||
|
||||
**RevokeButton:**
|
||||
- `OutlinedButton` with `Icons.block_rounded` icon, label `'Revoke'`
|
||||
- `foregroundColor: Palette.coral`, `side: BorderSide(color: Palette.coral.withValues(alpha: 0.4))`
|
||||
- Disabled (replaced with `CircularProgressIndicator`) while `revokeEvmGrantMutation` is pending — note: this is a single global mutation, so all revoke buttons disable while any revoke is in flight
|
||||
- On press: calls `executeRevokeEvmGrant(ref, grantId: grant.id)`; shows `SnackBar` on error
|
||||
|
||||
---
|
||||
|
||||
## Adaptive Sizing
|
||||
|
||||
All sizing uses `sizer` units (`1.h`, `1.w`, etc.). No hardcoded pixel values.
|
||||
|
||||
---
|
||||
|
||||
## Files to Create / Modify
|
||||
|
||||
| File | Action |
|
||||
|---|---|
|
||||
| `lib/theme/palette.dart` | Modify — add `Palette.token` color |
|
||||
| `lib/providers/sdk_clients/wallet_access_list.dart` | Create |
|
||||
| `lib/screens/dashboard/evm/grants/grants.dart` | Create |
|
||||
| `lib/router.dart` | Modify — add grants route to dashboard children |
|
||||
| `lib/screens/dashboard.dart` | Modify — add tab to routes list and NavigationDestinations |
|
||||
# Grant Grid View — Design Spec
|
||||
|
||||
**Date:** 2026-03-28
|
||||
|
||||
## Overview
|
||||
|
||||
Add a "Grants" dashboard tab to the Flutter operator app that displays all EVM grants as a card-based grid. Each card shows a compact summary (type, chain, wallet address, client name) with a revoke action. The tab integrates into the existing `AdaptiveScaffold` navigation alongside Wallets, Clients, and About.
|
||||
|
||||
## Scope
|
||||
|
||||
- New `walletAccessListProvider` for fetching wallet access entries with their DB row IDs
|
||||
- New `EvmGrantsScreen` as a dashboard tab
|
||||
- Grant card widget with enriched display (type, chain, wallet, client)
|
||||
- Revoke action wired to existing `executeRevokeEvmGrant` mutation
|
||||
- Dashboard tab bar and router updated
|
||||
- New token-transfer accent color added to `Palette`
|
||||
|
||||
**Out of scope:** Fixing grant creation (separate task).
|
||||
|
||||
---
|
||||
|
||||
## Data Layer
|
||||
|
||||
### `walletAccessListProvider`
|
||||
|
||||
**File:** `operator/lib/providers/sdk_clients/wallet_access_list.dart`
|
||||
|
||||
- `@riverpod` class, watches `connectionManagerProvider.future`
|
||||
- Returns `List<SdkClientWalletAccess>?` (null when not connected)
|
||||
- Each entry: `.id` (wallet_access_id), `.access.walletId`, `.access.sdkClientId`
|
||||
- Exposes a `refresh()` method following the same pattern as `EvmGrants.refresh()`
|
||||
|
||||
### Enrichment at render time (Approach A)
|
||||
|
||||
The `EvmGrantsScreen` watches four providers:
|
||||
1. `evmGrantsProvider` — the grant list
|
||||
2. `walletAccessListProvider` — to resolve wallet_access_id → (wallet_id, sdk_client_id)
|
||||
3. `evmProvider` — to resolve wallet_id → wallet address
|
||||
4. `sdkClientsProvider` — to resolve sdk_client_id → client name
|
||||
|
||||
All lookups are in-memory Maps built inside the build method; no extra model class needed.
|
||||
|
||||
Fallbacks:
|
||||
- Wallet address not found → `"Access #N"` where N is the wallet_access_id
|
||||
- Client name not found → `"Client #N"` where N is the sdk_client_id
|
||||
|
||||
---
|
||||
|
||||
## Route Structure
|
||||
|
||||
```
|
||||
/dashboard
|
||||
/evm ← existing (Wallets tab)
|
||||
/clients ← existing (Clients tab)
|
||||
/grants ← NEW (Grants tab)
|
||||
/about ← existing
|
||||
|
||||
/evm-grants/create ← existing push route (unchanged)
|
||||
```
|
||||
|
||||
### Changes to `router.dart`
|
||||
|
||||
Add inside dashboard children:
|
||||
```dart
|
||||
AutoRoute(page: EvmGrantsRoute.page, path: 'grants'),
|
||||
```
|
||||
|
||||
### Changes to `dashboard.dart`
|
||||
|
||||
Add to `routes` list:
|
||||
```dart
|
||||
const EvmGrantsRoute()
|
||||
```
|
||||
|
||||
Add `NavigationDestination`:
|
||||
```dart
|
||||
NavigationDestination(
|
||||
icon: Icon(Icons.policy_outlined),
|
||||
selectedIcon: Icon(Icons.policy),
|
||||
label: 'Grants',
|
||||
),
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Screen: `EvmGrantsScreen`
|
||||
|
||||
**File:** `operator/lib/screens/dashboard/evm/grants/grants.dart`
|
||||
|
||||
```
|
||||
Scaffold
|
||||
└─ SafeArea
|
||||
└─ RefreshIndicator.adaptive (refreshes evmGrantsProvider + walletAccessListProvider)
|
||||
└─ ListView (BouncingScrollPhysics + AlwaysScrollableScrollPhysics)
|
||||
├─ PageHeader
|
||||
│ title: 'EVM Grants'
|
||||
│ isBusy: evmGrantsProvider.isLoading
|
||||
│ actions: [CreateGrantButton, RefreshButton]
|
||||
├─ SizedBox(height: 1.8.h)
|
||||
└─ <content>
|
||||
```
|
||||
|
||||
### State handling
|
||||
|
||||
Matches the pattern from `EvmScreen` and `ClientsScreen`:
|
||||
|
||||
| State | Display |
|
||||
|---|---|
|
||||
| Loading (no data yet) | `_StatePanel` with spinner, "Loading grants" |
|
||||
| Error | `_StatePanel` with coral icon, error message, Retry button |
|
||||
| No connection | `_StatePanel`, "No active server connection" |
|
||||
| Empty list | `_StatePanel`, "No grants yet", with Create Grant shortcut |
|
||||
| Data | Column of `_GrantCard` widgets |
|
||||
|
||||
### Header actions
|
||||
|
||||
**CreateGrantButton:** `FilledButton.icon` with `Icons.add_rounded`, pushes `CreateEvmGrantRoute()` via `context.router.push(...)`.
|
||||
|
||||
**RefreshButton:** `OutlinedButton.icon` with `Icons.refresh`, calls `ref.read(evmGrantsProvider.notifier).refresh()`.
|
||||
|
||||
---
|
||||
|
||||
## Grant Card: `_GrantCard`
|
||||
|
||||
**Layout:**
|
||||
|
||||
```
|
||||
Container (rounded 24, Palette.cream bg, Palette.line border)
|
||||
└─ IntrinsicHeight > Row
|
||||
├─ Accent strip (0.8.w wide, full height, rounded left)
|
||||
└─ Padding > Column
|
||||
├─ Row 1: TypeBadge + ChainChip + Spacer + RevokeButton
|
||||
└─ Row 2: WalletText + "·" + ClientText
|
||||
```
|
||||
|
||||
**Accent color by grant type:**
|
||||
- Ether transfer → `Palette.coral`
|
||||
- Token transfer → `Palette.token` (new entry in `Palette` — indigo, e.g. `Color(0xFF5C6BC0)`)
|
||||
|
||||
**TypeBadge:** Small pill container with accent color background at 15% opacity, accent-colored text. Label: `'Ether'` or `'Token'`.
|
||||
|
||||
**ChainChip:** Small container: `'Chain ${grant.shared.chainId}'`, muted ink color.
|
||||
|
||||
**WalletText:** Short hex address (`0xabc...def`) from wallet lookup, `bodySmall`, monospace font family.
|
||||
|
||||
**ClientText:** Client name from `sdkClientsProvider` lookup, or fallback string. `bodySmall`, muted ink.
|
||||
|
||||
**RevokeButton:**
|
||||
- `OutlinedButton` with `Icons.block_rounded` icon, label `'Revoke'`
|
||||
- `foregroundColor: Palette.coral`, `side: BorderSide(color: Palette.coral.withValues(alpha: 0.4))`
|
||||
- Disabled (replaced with `CircularProgressIndicator`) while `revokeEvmGrantMutation` is pending — note: this is a single global mutation, so all revoke buttons disable while any revoke is in flight
|
||||
- On press: calls `executeRevokeEvmGrant(ref, grantId: grant.id)`; shows `SnackBar` on error
|
||||
|
||||
---
|
||||
|
||||
## Adaptive Sizing
|
||||
|
||||
All sizing uses `sizer` units (`1.h`, `1.w`, etc.). No hardcoded pixel values.
|
||||
|
||||
---
|
||||
|
||||
## Files to Create / Modify
|
||||
|
||||
| File | Action |
|
||||
|---|---|
|
||||
| `lib/theme/palette.dart` | Modify — add `Palette.token` color |
|
||||
| `lib/providers/sdk_clients/wallet_access_list.dart` | Create |
|
||||
| `lib/screens/dashboard/evm/grants/grants.dart` | Create |
|
||||
| `lib/router.dart` | Modify — add grants route to dashboard children |
|
||||
| `lib/screens/dashboard.dart` | Modify — add tab to routes list and NavigationDestinations |
|
||||
|
||||
Reference in New Issue
Block a user