Guardian

Warning: This is a work in progress.

Documentation

• docs/ — in-repo documentation hub. Start with Concepts for the custody model and state/delta lifecycle, then Quickstart (60-second hello) or Local development (depth). Also covers Production (supported production shape), Configuration (every env var), Troubleshooting, architecture (services and AWS deployment), the operator dashboard, the secrets runbook, and the multisig SDK guide.
• spec/ — protocol specification. Core concepts (State and Delta), components (API, Metadata, Auth, Acknowledger, Network, Storage), and key processes such as canonicalization. Start here to understand invariants, defaults, and extension points.

Contributing

• CONTRIBUTING.md — picking work, branching, commit style, cross-layer change rules, testing, docs, CLA.
• AGENTS.md — operational guide and the mandatory contract-change workflow for changes touching the wire contract.
• SECURITY.md — private vulnerability disclosure.

Project Structure

Rust Crates

• crates/server - Server for managing private account states and deltas
  • Reproducible builds for binary verification and TEE deployment
• crates/client - Client SDK for interacting with the GUARDIAN server
• crates/shared - Shared types and utilities
• crates/miden-rpc-client - Lightweight wrapper around Miden node RPC API - inspired in miden-client implementation.
• crates/miden-keystore - Keystore implementation for Miden cryptographic keys - inspired in miden-client implementation.

TypeScript Packages

• packages/guardian-client - TypeScript HTTP client for GUARDIAN server
• packages/guardian-evm-client - TypeScript EVM client for GUARDIAN proposal workflows
• packages/guardian-operator-client - Lean TypeScript HTTP client for operator dashboard auth and account APIs
• packages/miden-multisig-client - TypeScript SDK for Miden multisig accounts with GUARDIAN integration

Quick Start

See the Server README for detailed API documentation and usage examples.

Benchmarking

Server benchmark harness is in crates/server/bench. For env-driven benchmark network/canonicalization settings, apply the runtime code switch documented there.

Configuration

Environment Variables

• DATABASE_URL - PostgreSQL connection URL (required only for explicit Postgres-backed runs)
• GUARDIAN_KEYSTORE_PATH - Keystore path for cryptographic keys (default: /var/guardian/keystore)
• RUST_LOG - Logging level (default: info)
  • Supports: trace, debug, info, warn, error
  • Module-specific: RUST_LOG=server::jobs::canonicalization=debug
• GUARDIAN_RATE_LIMIT_ENABLED - Enable or disable HTTP rate limiting entirely (default: true)
• GUARDIAN_RATE_BURST_PER_SEC - Maximum requests per second (default: 10)
• GUARDIAN_RATE_PER_MIN - Maximum requests per minute (default: 60)
• GUARDIAN_MAX_REQUEST_BYTES - Maximum request body size in bytes (default: 1048576 = 1 MB)
• GUARDIAN_MAX_PENDING_PROPOSALS_PER_ACCOUNT - Maximum pending delta proposals per account (default: 20)
• GUARDIAN_EVM_RPC_URLS - Comma-separated chain_id=rpc_url map for EVM proposal support
• GUARDIAN_EVM_ENTRYPOINT_ADDRESS - Shared EntryPoint address used for EVM proposal finality checks (single address across chains; defaults to EntryPoint v0.9 0x433709009b8330fda32311df1c2afa402ed8d009)

Running

Running with Cargo

cargo run --bin server

EVM proposal support is feature-gated. Default builds do not register EVM routes. EVM-enabled servers use the domain-separated /evm/auth/*, /evm/accounts, and /evm/proposals* routes.

GUARDIAN_EVM_RPC_URLS=31337=http://127.0.0.1:8545 \
GUARDIAN_EVM_ENTRYPOINT_ADDRESS=0x... \
cargo run -p guardian-server --features evm --bin server

Running with Docker Compose

The default compose file sets the container paths it needs, so a root .env is not required for this path. Start the server:

docker compose up --build -d

For direct cargo run development, create a local .env as described in docs/LOCAL_DEV.md.

View logs:

docker compose logs -f

Stop services:

docker compose down

The HTTP server will be available at http://localhost:3000

The gRPC server will be available at localhost:50051

This default Compose flow uses the filesystem backend. If you need a local Postgres container for benchmark or explicit Postgres-backed runs, set POSTGRES_PASSWORD in .env and run with the Postgres override:

docker compose -f docker-compose.yml -f docker-compose.postgres.yml up --build -d

Testing

Rust Tests

Run the full workspace test suite:

cargo test --workspace

Feature-gated test groups:

# Run only integration tests
cargo test -p guardian-server --features integration

# Run only e2e tests
cargo test -p guardian-server --features e2e

TypeScript Tests

# Install dependencies
cd packages/guardian-client && npm install
cd packages/guardian-evm-client && npm install
cd packages/guardian-operator-client && npm install
cd packages/miden-multisig-client && npm install

# Run tests
cd packages/guardian-client && npm test
cd packages/guardian-evm-client && npm test
cd packages/guardian-operator-client && npm test
cd packages/miden-multisig-client && npm test