# Hierarchical Safe with Non-Standard Signing Implementation
Version 3.0 | December 2024
## Document Control
| Version | Date | Author | Changes |
|---------|------|---------|---------|
| 1.0 | 2024-11-27 | Sero | [Initial release](https://hackmd.io/FHwtq1ZqS3itB3q7AFNGIg) |
| 2.0 | 2024-12-02 | Sero | Added Passkeys and deadman switch |
| 3.0 | 2024-12-03 | Sero | Refined architecture, improved clarity |
## 1. Executive Summary
This architecture document builds on a [nested Safe setup](https://hackmd.io/FHwtq1ZqS3itB3q7AFNGIg), and details an advanced implementation of a Safe multi-signature system that addresses core challenges in enterprise asset management through three approaches:
1. **Hardware Security Integration:** Using Passkeys, WebAuthn and P-256 signatures
2. **Automated Recovery:** Implementing a Dead Man's Switch mechanism, which uses ERC-1271 to allow for signing
3. **Operational Flexibility:** Leveraging nested Safe structures
**The system uses a 2/3 multisignature configuration where the signers are:**
- A hardware-backed Passkeys signer for secure authentication [(ERC-1271)](https://eips.ethereum.org/EIPS/eip-1271)
- A Dead Man's Switch for automated recovery [(ERC-1271)](https://eips.ethereum.org/EIPS/eip-1271)
- A nested Safe for operational control
### 1.1 Core Architecture
```mermaid
graph TB
subgraph "Top Safe [2/3]"
PS[Passkeys Signer]
DMS[Dead Man's Switch]
NS[Nested Safe]
subgraph "Security Features"
PS --> WebAuthn[WebAuthn Verification]
PS --> P256[P-256 Signatures]
PS --> SafeModule[Safe Passkeys Module]
DMS --> Recovery[Recovery Protocol]
NS --> MultiSig[Standard Multisig]
end
subgraph "Integration Layer"
WebAuthn --> Module[Module Integration]
P256 --> Module
Module --> Validation[Signature Validation]
end
end
```
```mermaid
graph TB
subgraph "Safe Transaction Flow"
TX[Transaction Creation]
SIG[Signature Collection]
EXEC[Execution]
end
subgraph "Signers"
PS[Passkeys Signer]
DMS[DMS Signer]
NS[Nested Safe]
end
TX --> SIG
SIG --> PS & DMS & NS
PS & DMS & NS --> EXEC
style PS fill:#f9f,stroke:#333
style DMS fill:#bbf,stroke:#333
```
### 1.2 Core Objectives
| Objective | Implementation | Success Criteria |
|-----------|----------------|------------------|
| Hardware Security | Safe Passkeys Module + P-256 signatures | Biometric verification success |
| Business Continuity | Dead Man's Switch with grace period | Recovery initiation within X hours |
| Operational Efficiency | Nested Safe hierarchy | Transaction throughput meets business needs |
| Future Proofing | Upgradeable module architecture | Seamless standard adoption |
## 2. System Components
### 2.1 Safe Passkeys Module Integration
The system integrates with [Safe's official Passkeys Module](https://github.com/safe-global/safe-modules/blob/466a9b8ef169003c5df856c6ecd295e6ecb9e99d/modules/passkey/README.md), which provides a standardized way to use [WebAuthn authentication](https://docs.safe.global/advanced/passkeys/overview) as a valid signer. The integration consists of three main components:
1. **SafeWebAuthnSignerProxy**
This proxy contract is deployed for each passkey signer and stores essential configuration:
```solidity
contract SafeWebAuthnSignerProxy {
address public immutable SINGLETON;
bytes public immutable AUTHENTICATOR_DATA;
uint256[2] public immutable PUBLIC_KEY;
constructor(
address singleton,
bytes memory authenticatorData,
uint256[2] memory publicKey
) {
SINGLETON = singleton;
AUTHENTICATOR_DATA = authenticatorData;
PUBLIC_KEY = publicKey;
}
}
```
2. **SafeWebAuthnSignerSingleton**
The singleton handles signature verification logic:
```solidity
contract SafeWebAuthnSignerSingleton {
function verifySignature(
bytes32 messageHash,
WebAuthnSignature calldata signature,
bytes calldata authenticatorData,
uint256[2] calldata publicKey
) public view returns (bool) {
// Verify WebAuthn data and signature
return WebAuthnLib.verifySignature(
messageHash,
signature,
authenticatorData,
publicKey
);
}
}
```
3. **SafeWebAuthnSignerFactory**
The factory manages proxy deployment and initial verification:
```solidity
contract SafeWebAuthnSignerFactory {
function createSigner(
bytes calldata authenticatorData,
uint256[2] calldata publicKey,
bytes calldata signature
) external returns (address) {
// Deploy new proxy with verified configuration
return address(new SafeWebAuthnSignerProxy(
singleton,
authenticatorData,
publicKey
));
}
}
```
```mermaid
sequenceDiagram
participant User
participant Safe
participant Modules
participant Security
User->>Safe: Request Transaction
Safe->>Modules: Collect Signatures
par Signature Collection
Modules->>Security: Hardware Verification
Note over Security: WebAuthn + P-256
Security-->>Modules: Signature Result
Modules->>Modules: DMS Check
Note over Modules: Heartbeat Status
Modules->>Modules: Nested Safe
Note over Modules: Standard Multisig
end
Modules-->>Safe: Combined Result
Safe->>User: Transaction Status
```
### 2.2 Dead Man's Switch Implementation
The Dead Man's Switch (DMS) functions as an automated signer that provides failsafe recovery capabilities through time-based authorization. It implements both ERC-1271 for signing and a comprehensive recovery protocol (Recovery Module).
```mermaid
stateDiagram-v2
[*] --> Active
Active --> Warning: Miss Heartbeat
Warning --> Active: Receive Heartbeat
Warning --> Triggered: Grace Period Ends
state Active {
[*] --> ValidSigner
ValidSigner --> [*]
}
state Warning {
[*] --> GracePeriod
GracePeriod --> [*]
}
state Triggered {
[*] --> RecoveryMode
RecoveryMode --> [*]
}
note right of Active: Provides Valid ERC-1271 Signature
note right of Warning: Limited Time to Restore Heartbeat
note right of Triggered: Transfers Signing Authority
```
```solidity
contract DMSSigner is ERC1271 {
uint256 public lastHeartbeat;
uint256 public immutable heartbeatPeriod;
uint256 public immutable gracePeriod;
address public recoveryTarget;
struct RecoveryConfig {
address[] guardians;
uint256 threshold;
uint256 delay;
}
RecoveryConfig public config;
function isValidSignature(
bytes32 messageHash,
bytes calldata /* signature */
) external view override returns (bytes4) {
return isActive() ? MAGICVALUE : FAILVALUE;
}
function initiateRecovery() external {
require(canInitiateRecovery(), "Cannot initiate recovery");
_startRecoveryProcess();
}
}
```
### 2.3 System Integration Flow
```mermaid
sequenceDiagram
participant User
participant Safe
participant PasskeysModule
participant WebAuthn
participant DMS
User->>Safe: Initiate Transaction
Safe->>PasskeysModule: Request Signature
PasskeysModule->>WebAuthn: Request Authentication
WebAuthn->>User: Prompt Biometric
User->>WebAuthn: Provide Biometric
WebAuthn->>PasskeysModule: Generate Signature
PasskeysModule->>Safe: Submit Signature
par Additional Signatures
Safe->>DMS: Check Status
DMS->>Safe: Provide Signature
end
Safe->>Safe: Execute Transaction
```
## 3. Security Model
The security model implements multiple layers of protection:
### 3.1 Hardware Security Layer
The Passkeys Module leverages device security through:
1. Secure hardware elements (TPM/Secure Enclave)
2. Biometric verification
3. P-256 signature generation
4. WebAuthn attestation
### 3.2 Smart Contract Security Layer
```mermaid
graph TB
subgraph "Contract Security"
ERC1271[ERC-1271 Validation]
TimeLock[Timelock Controls]
Access[Access Management]
ERC1271 --> Validation[Signature Validation]
TimeLock --> Recovery[Recovery Process]
Access --> Roles[Role Management]
end
```
### 3.3 Recovery Layer
The recovery system provides multiple paths:
1. Automated DMS recovery
2. Guardian-based social recovery
3. Hardware device backup
4. Nested Safe recovery options
## 4. Deployment Strategy
### 4.1 Component Deployment
```mermaid
sequenceDiagram
participant Deployer
participant Factory
participant PasskeysModule
participant DMS
participant Safe
Deployer->>Factory: Deploy Factory
Factory->>PasskeysModule: Create Singleton
Deployer->>DMS: Deploy DMS
par Setup Phase
PasskeysModule->>Safe: Register Signer
DMS->>Safe: Configure Recovery
end
Safe->>Safe: Initialize 2/3 Configuration
```
### 4.2 Environment Configurations
| Environment | Passkeys Config | DMS Settings | Testing Focus |
|-------------|----------------|--------------|---------------|
| Development | Mock WebAuthn | Short periods | Functionality |
| Staging | Test devices | Normal periods | Integration |
| Production | Production WebAuthn | Full settings | Security |
## 5. Risk Analysis
### 5.1 Critical Paths
| Component | Risk | Mitigation | Monitoring |
|-----------|------|------------|------------|
| Passkeys | Device failure | Multiple registrations | Health checks |
| DMS | False trigger | Grace period | Heartbeat monitoring |
| Integration | Module conflict | Isolation testing | Contract events |
### 5.2 Recovery Procedures
```mermaid
stateDiagram-v2
[*] --> Normal
Normal --> Warning: Trigger Event
Warning --> Recovery: Grace Period
Warning --> Normal: Resolution
Recovery --> Normal: Recovery Complete
```
## 6. Maintenance and Operations
### 6.1 Regular Maintenance
The system requires regular maintenance of:
1. Device registrations and health
2. DMS heartbeat monitoring
3. Recovery path validation
4. Security parameter updates
### 6.2 Monitoring Systems
```mermaid
graph TB
subgraph "Monitoring System"
Monitor[Health Monitor]
Alerts[Alert System]
Logs[Event Logs]
subgraph "Metrics"
Auth[Authentication Status]
Time[Response Time]
Error[Error Rate]
Device[Device Health]
end
end
Monitor --> Auth & Time & Error & Device
Auth & Time & Error & Device --> Alerts
Alerts --> Logs
```
### References and Standards
The implementation adheres to:
1. [Safe Module Standards](https://docs.safe.global/advanced/smart-account-modules)
2. WebAuthn Specifications
3. [ERC-1271](https://eips.ethereum.org/EIPS/eip-1271) and [ERC-7212](https://www.alchemy.com/blog/what-is-rip-7212)
## 7. Appendices
### 7.1 Testing Framework
| Test Category | Description | Frequency |
|--------------|-------------|-----------|
| WebAuthn Integration | Device registration and authentication | Per deployment |
| Recovery Flow | DMS and backup procedures | Monthly |
| Security Verification | Signature validation and replay protection | Continuous |
### 7.2 Reference Implementations
| Component | Reference | Notes |
|-----------|-----------|-------|
| Safe Contracts | safe-contracts | Core functionality |
| Passkeys Module | Safe Module | WebAuthn implementation |
| WebAuthn Library | Web API | Browser integration |
| Dead Man's Switch | Custom |Automated recovery |
# Reference Index
## Standards & Proposals
| Reference | Description | URL |
|-----------|-------------|-----|
| ERC-7212 | P-256 Verification Precompile | https://github.com/ethereum/RIPs/blob/master/RIPS/rip-7212.md |
| Safe Passkeys | Web Authentication Standard | https://github.com/safe-global/safe-modules/blob/466a9b8ef169003c5df856c6ecd295e6ecb9e99d/modules/passkey/README.md |
| EIP-4337 | Account Abstraction | https://eips.ethereum.org/EIPS/eip-4337 |
## Safe Implementation
| Reference | Description | URL |
|-----------|-------------|-----|
| Safe Contracts | Core Safe contracts | https://github.com/safe-global/safe-contracts |
| Safe Documentation | Official documentation | https://docs.safe.global/ |
| Zodiac Docs | Safe module system | https://github.com/gnosis/zodiac |
| Safe Core Protocol | Protocol documentation | https://docs.safe.global/advanced/smart-account-overview |
## Development Resources
| Reference | Description | URL |
|-----------|-------------|-----|
| Safe SDK | Development tools | https://github.com/safe-global/safe-core-sdk |
| Safe Apps SDK | Safe app development | https://github.com/safe-global/safe-apps-sdk |
| Hardhat Plugin | Safe deployment tools | https://github.com/safe-global/safe-contracts/tree/main/hardhat-plugins |
| Passkey Tests | Safe Passkey Contract tests |https://github.com/safe-global/safe-modules/tree/466a9b8ef169003c5df856c6ecd295e6ecb9e99d/modules/passkey/test/userstories |
## Additional Resources
| Reference | Description | URL |
|-----------|-------------|-----|
| FIDO Alliance | WebAuthn specifications | https://fidoalliance.org/specifications/ |
| Safe Blog | Updates and tutorials | https://safe.global/blog |
| Ethereum Foundation | Security best practices | https://ethereum.org/en/developers/docs/smart-contracts/security/ |
## Community & Support
| Reference | Description | URL |
|-----------|-------------|-----|
| Safe Forum | Community discussions | https://forum.safe.global/ |
| Safe Discord | Developer chat | https://chat.safe.global/ |
| Safe Github | Source code & issues | https://github.com/safe-global |
Sign in with Wallet
Connect another wallet