User Persistence Manager Documentation

Overview

The UserPersistenceManager manages user identities using wallet addresses as primary identifiers. All user actions are verified using wallet signatures, ensuring secure and authenticated user operations.

File: tools/user_persistence_manager.py Class: UserPersistenceManager Version: 1.0.0 Status: ✅ Active

Architecture

Design Principles

Wallet-Based Identity: Wallet address as primary identifier

Signature Verification: All actions require signature verification

User Agents: Users can create and manage agents

Persistent Storage: JSON-based storage

Security-First: Cryptographic verification for all operations

Core Components

class UserPersistenceManager:
    - participants_dir: Path - Participants directory
    - users: Dict[str, UserIdentity] - User registry
    - signatures: Dict[str, List] - Signature history
    - user_agents: Dict[str, List] - User agents

Data Structures

UserIdentity

@dataclass
class UserIdentity:
    wallet_address: str          # Primary identifier
    user_id: str                # Generated user ID
    created_at: float           # Creation timestamp
    last_active: float         # Last activity timestamp
    signature_count: int       # Total signatures
    agent_count: int           # Number of agents
    metadata: Dict[str, Any]   # Additional metadata
    public_key: Optional[str]  # Public key

SignatureVerification

@dataclass
class SignatureVerification:
    is_valid: bool              # Verification result
    message: str                # Signed message
    signature: str              # Signature
    recovered_address: Optional[str]  # Recovered address
    timestamp: float            # Verification timestamp

Available Methods

1. register_user

Registers a new user with signature verification.

Parameters:

wallet_address (str): User's wallet address

signature (str): Signature of challenge message

message (str): Challenge message

metadata (Dict, optional): User metadata

Returns:

Tuple[bool, str]  # (success, message)

2. verify_signature

Verifies a wallet signature.

Parameters:

wallet_address (str): Wallet address

message (str): Signed message

signature (str): Signature

Returns: SignatureVerification object

3. verify_user_action

Verifies a user action with signature.

Parameters:

wallet_address (str): User wallet

action (str): Action name

signature (str): Signature

message (str): Challenge message

Returns:

Tuple[bool, str]  # (success, message)

4. create_user_agent

Creates a user agent with signature verification.

Parameters:

wallet_address (str): User wallet

agent_id (str): Agent identifier

agent_type (str): Agent type

signature (str): Signature

message (str): Challenge message

metadata (Dict, optional): Agent metadata

Returns:

Tuple[bool, str, Optional[str]]  # (success, message, agent_wallet)

5. delete_user_agent

Deletes a user agent with signature verification.

Parameters:

wallet_address (str): User wallet

agent_id (str): Agent to delete

signature (str): Signature

message (str): Challenge message

Returns:

Tuple[bool, str]  # (success, message)

6. get_user_agents

Gets all agents for a user.

Parameters:

wallet_address (str): User wallet

Returns: List[Dict[str, Any]]

7. get_user_stats

Gets user statistics.

Parameters:

wallet_address (str): User wallet

Returns: Dict[str, Any]

8. generate_challenge_message

Generates a challenge message for signature.

Parameters:

wallet_address (str): User wallet

action (str): Action name

Returns: str (challenge message)

Usage

Register User

from tools.user_persistence_manager import UserPersistenceManager

manager = UserPersistenceManager()
Generate challenge
challenge = manager.generate_challenge_message(
    wallet_address="0x...",
    action="register"
)

User signs challenge, then register
success, message = manager.register_user(
    wallet_address="0x...",
    signature="0x...",
    message=challenge,
    metadata={"name": "User Name"}
)

Create User Agent

# Generate challenge
challenge = manager.generate_challenge_message(
    wallet_address="0x...",
    action="create_agent"
)

Create agent
success, message, agent_wallet = manager.create_user_agent(
    wallet_address="0x...",
    agent_id="user_agent_001",
    agent_type="analysis_agent",
    signature="0x...",
    message=challenge
)

Verify Action

# Verify user action
success, message = manager.verify_user_action(
    wallet_address="0x...",
    action="execute_task",
    signature="0x...",
    message=challenge
)

Storage Structure

Files

data/participants/users.json - User identities

data/participants/signatures.json - Signature history

data/participants/user_agents.json - User agents

Directory Structure

data/participants/
├── users.json
├── signatures.json
└── user_agents.json

Security Features

1. Signature Verification

All operations require:

Wallet signature

Message verification

Address recovery

Signature validation

2. Challenge Messages

Challenge messages include:

Action name

Wallet address

Timestamp

Nonce

3. Signature History

Tracks all signatures:

Verification results

Timestamps

Messages

Recovered addresses

Limitations

Current Limitations

eth_account Dependency: Requires eth_account library

No Multi-Chain: Ethereum only

Basic Storage: JSON file storage

No Encryption: No data encryption

No Backup: No backup system

Recommended Improvements

Multi-Chain Support: Support multiple blockchains

Database Storage: Use database instead of JSON

Data Encryption: Encrypt sensitive data

Backup System: Automatic backups

Rate Limiting: Prevent abuse

Audit Logging: Comprehensive audit logs

API Integration: REST API access

Integration

With eth_account

Uses eth_account for:

Signature verification

Address recovery

Message encoding

Examples

Complete User Lifecycle

# 1. Register user
challenge = manager.generate_challenge_message("0x...", "register")
success, _ = manager.register_user("0x...", signature, challenge)

2. Create agent
challenge = manager.generate_challenge_message("0x...", "create_agent")
success, _, agent_wallet = manager.create_user_agent(
    "0x...", "agent_001", "analysis", signature, challenge
)

3. Get user stats
stats = manager.get_user_stats("0x...")

Technical Details

Dependencies

eth_account: Ethereum account management

dataclasses: Data structures

hashlib: Nonce generation

utils.config.Config: Configuration

Signature Verification

Uses Ethereum message signing:

message_hash = encode_defunct(text=message)
recovered_address = Account.recover_message(message_hash, signature=signature)

Future Enhancements

Multi-Chain: Support multiple blockchains

Database: Use database storage

Encryption: Encrypt sensitive data

Backup: Automatic backups

API: REST API access

Rate Limiting: Prevent abuse

Audit Logs: Comprehensive logging

---