SuperSafe

On-chain multisig governance for ERC-7579 smart accounts.

SuperSafe is a modular smart-account stack where partial approvals live on-chain, not in a backend. Owners propose transactions, approve them with wallet transactions, and execute once threshold is met — the same model as Gnosis Safe, but with approvals stored in an on-chain registry instead of an off-chain Transaction Service.

Status: Research prototype. Compiles, passes Foundry tests, and the core propose → approve → execute flow is wired end-to-end. Not production-ready — do not hold real funds. See docs/security-review.md for open gaps.

Why SuperSafe?

Concern	Typical Safe flow	SuperSafe
Partial signatures	Stored off-chain in Transaction Service	Stored on-chain via approve(proposalId)
"How many owners signed?"	Read from backend	Read from chain (getApprovalCount, isApproved)
Reject a pending tx	Backend queue delete	On-chain revoke / cancel
Discussion / context	Mixed with signing backend	Separate Deliberation layer (non-binding)

One line: Safe stores partial signatures in a backend. SuperSafe stores approvals on-chain and the UI reads them from chain.

Architecture

┌─────────────────────────────────────────────────────────────┐
│  Chain (source of truth)                                     │
│  MultisigValidator: propose / approve / revoke / execute     │
│  SuperSafeAccount (ERC-7579): modular validators + hooks     │
└─────────────────────────────────────────────────────────────┘
         ▲ authoritative reads & writes
         │
┌─────────────────────────────────────────────────────────────┐
│  Web app (Next.js + wagmi)                                   │
│  Deploy accounts, propose txs, approve/execute from wallet   │
└─────────────────────────────────────────────────────────────┘
         ▲ convenience reads (lists, history)
         │
┌─────────────────────────────────────────────────────────────┐
│  Coordination service (Express + Postgres)                   │
│  Event indexer + deliberation threads (context only)         │
└─────────────────────────────────────────────────────────────┘

Packages

Path	Description
contracts/	Foundry — SuperSafeAccount, MultisigValidator, governance hooks, factory
sdk/	TypeScript SDK (@supersafe/account) — ABIs, clients, types
coordination/	Indexer + REST API for accounts, proposals, deliberation threads
web/	Next.js dashboard — deploy, accounts, proposals, auth
docs/	Security review, frontend product plan

Features

On-chain (contracts)

• ERC-7579 modular account with CREATE2 factory
• Multisig validator with weighted owners, propose/approve/revoke/execute/cancel
• Governance hooks: Policy, SpendLimit, Allowlist, Blocklist, Timelock, FourEyes
• Additional validators: Role, SessionKey, Recovery
• ERC-1271 compatibility fallback

Web app

• Wallet-connected deploy wizard
• Account list and detail pages with live on-chain approval counts
• Proposal wizard with templates (Send ETH/ERC-20, module config, custom calldata)
• Approve / revoke / execute / cancel from the UI

Coordination service

• Indexes Proposed, Approved, Revoked, Executed, Cancelled events
• Deliberation API: threads + comments to discuss transaction intent (non-binding)
• Webhook subscriptions for account events

Prerequisites

• Node.js 20+
• Foundry (for contracts)
• Docker (optional, for Postgres/Redis/coordination)
• WalletConnect project ID (cloud.walletconnect.com)

Quick start

1. Clone and install

git clone https://github.com/0xhexbyte/superSafe.git
cd superSafe
npm install

2. Environment

cp .env.example .env
# Edit .env — set NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID at minimum

3. Contracts

./scripts/setup-contracts.sh   # installs forge deps, builds, runs tests

Or manually:

cd contracts
forge install foundry-rs/forge-std@v1 --no-commit
forge install OpenZeppelin/openzeppelin-contracts@v5.0.0 --no-commit
forge test

4. Coordination service (optional)

Start Postgres and Redis:

docker compose up postgres redis -d

Push the database schema and run the indexer:

npm run db:push -w coordination
npm run dev -w coordination

5. Web app

npm run dev

Open http://localhost:3000.

Docker (all services)

docker compose up --build

Web: http://localhost:3000 · Coordination API: http://localhost:3001/api/v1/health

Development

npm run typecheck    # TypeScript across all packages
npm run build        # Build sdk, coordination, web
npm run test         # SDK + coordination unit tests
cd contracts && forge test   # Solidity tests (incl. invariant fuzzing)

Deploy contracts (Sepolia / local)

Set in .env:

DEPLOYER_PRIVATE_KEY=0x...
ENTRY_POINT=0x...   # ERC-4337 entry point for your chain

cd contracts
forge script script/Deploy.s.sol:DeployScript --rpc-url $RPC_URL --broadcast

Update FACTORY_ADDRESS in .env and the web chain config after deploy.

Transaction lifecycle

1. Propose — An owner submits { to, value, data, operation, expiration } on-chain.
2. Deliberate (optional) — Team discusses intent in a coordination thread (does not authorize).
3. Approve — Other owners send on-chain approve(proposalId) transactions.
4. Execute — Anyone triggers execute(proposalId) once threshold is met; the account executes the call and governance hooks run.

Approval counts and signer status in the UI are read directly from chain, not trusted from the indexer for enabling actions.

Documentation

• docs/security-review.md — Findings, resolved issues, gap tracker
• docs/frontend-product-plan.md — UI architecture and rollout phases

License

MIT

Disclaimer

This software is provided for research and development. It has not been audited. Use at your own risk.