Seamless 2FA Wallet

A Starknet account abstraction contract that enforces two-factor authentication through a configurable asynchronous multisig mechanism.

What Problem Does This Solve?

Standard Starknet wallets use a single key. If that key is compromised, everything is lost. Hardware wallets are secure but painful for daily use.

This wallet gives you both: fast single-signature transactions for safe, pre-approved operations, and mandatory multi-party approval for everything else. Your cold wallet only needs to act when something unusual happens.

How It Works

The contract holds your funds and enforces a policy on every outgoing transaction:

1. You send a transaction. The contract validates your signature and checks the transaction against a configurable whitelist.

2. If the transaction is whitelisted (e.g. transferring to a known address, calling a trusted contract), it executes immediately with just your signature.

3. If the transaction is not whitelisted, the contract checks whether enough signers have approved it. If not, it stores your signature and emits an event with the full transaction details.

4. A second signer (e.g. your cold wallet) sees the event, reviews the transaction, and sends the exact same transaction. The contract now has enough signatures and executes.

There is no separate "approve" function — every signer sends the same transaction through the same code path. The contract simply counts valid signatures per transaction hash.

Two Policy Modes

Chosen at deployment time:

• Threshold Mode — Whitelisted transactions need one signature from the whitelist-signers list. Non-whitelisted transactions accumulate signatures asynchronously until a threshold is met.

• Role-Based Mode — "Easy signers" can only execute whitelisted transactions. "Hard signers" (cold wallets) can execute anything. No pending state needed — just a strict permission split.

Documentation

Document	Description
Architecture	Full technical design — storage, transaction flow, components, diagrams
Design Decisions	Decision log — what was decided, what's still open, and why
agents.md	Agent-facing design doc — for AI and automation tooling working on this repo

Project Structure

src/
  lib.cairo           # Module declarations
  whitelist.cairo     # WhitelistRule struct and matching logic
  account.cairo       # (planned) Core account contract
tests/
  test_contract.cairo # (planned) snforge tests
docs/
  architecture.md     # Technical architecture
  decisions.md        # Design decision log

Tech Stack

• Language: Cairo (2.13.1)
• Target: Starknet
• Build: Scarb 2.13.1
• Test: Starknet Foundry (snforge 0.56.0)
• Dependencies: OpenZeppelin Cairo Contracts (account, utils, introspection)

Getting Started

# Build
scarb build

# Test
scarb test

Status

Design phase. The architecture is documented, core scaffolding exists, but the account contract is not yet implemented. See the implementation plan for what's next.