Lux Docs
Lux Skills Reference

Lux Safe

Multisig Smart Accounts + Wallet UI

Overview

Lux Safe is a multisig smart account platform combining Safe v1.5.0 contracts (fork of safe-global/safe-smart-account) with a legacy React wallet UI and a Next.js static docs/landing site. Supports ERC-4337 account abstraction, EIP-7702 delegation detection, and secp256r1 signature verification via EIP-7951/RIP-7212 precompiles.

Quick Reference

ItemValue
Repogithub.com/luxfi/safe
Package@luxfi/safe
Versionv0.0.7
Contract VersionSafe v1.5.0
Solidity>=0.7.0 <0.9.0
FrameworkHardhat 2.27+ / hardhat-deploy
Compilersolc 0.7.6 (default)
Upstreamsafe-global/safe-smart-account
LicenseBSD-3-Clause

Repository Structure

safe/
  contracts/           # Solidity source (Safe v1.5.0)
  src/
    app/               # Next.js 15 landing/docs site (static export)
    deploy/            # Hardhat deployment scripts (7 scripts)
    tasks/             # Custom Hardhat tasks
    utils/             # TypeScript utilities
  react/               # Legacy Safe React wallet UI (v3.32.1, React 17)
  app/                 # Legacy CRA app shell (service worker, mocks)
  test/                # Hardhat test suite (10 categories)
  benchmark/           # Gas benchmarks (6 specs)
  certora/             # Certora formal verification (14 specs)
  modules/             # Safe module stubs (dutchx_seller, recurring_transfers)
  modules-deployments/ # Module deployment artifacts
  docs/                # Audit reports (PDFs), docs site (Next.js/MDX)
  types/               # TypeScript type definitions

Contracts

Core

ContractFilePurpose
SafeSafe.solCore multisig (1487 LOC). EIP-712 typed data signing, M-of-N threshold, gas refund, module/guard system. Inherits EIP7951 for secp256r1
SafeL2SafeL2.solL2-optimized variant that emits events for indexing (mainnet Safe does not emit for gas savings)
SafeProxyproxies/SafeProxy.solMinimal proxy (EIP-1167 style) delegating to singleton
SafeProxyFactoryproxies/SafeProxyFactory.solDeterministic proxy deployment via CREATE2

Base Modules

ContractPurpose
ExecutorLow-level CALL/DELEGATECALL execution
FallbackManagerConfigurable fallback handler routing
GuardManagerPre/post transaction guard hooks
ModuleManagerModule registration and execution (linked list)
OwnerManagerOwner add/remove/swap with threshold management

EIP Support

ContractStandardPurpose
EIP7702EIP-7702Detects EOA delegation context via EXTCODECOPY (0xef0100 prefix)
EIP7951EIP-7951/RIP-7212secp256r1 (P-256) signature verification via precompile at 0x100

Handlers

ContractPurpose
CompatibilityFallbackHandlerERC-1271 signature validation + ERC-721/ERC-1155 token receiver
ExtensibleFallbackHandlerFully extensible fallback with pluggable sub-handlers
TokenCallbackHandlerERC-721 + ERC-1155 receiver callbacks
HandlerContextProvides msg.sender context for fallback handler calls

Extensible Handler System

ContractPurpose
ERC165HandlerERC-165 interface detection with per-Safe overrides
FallbackHandlerCustom method routing per Safe
SignatureVerifierMuxerDomain-specific ERC-1271 signature verification
TokenCallbacksToken receive hooks
MarshalLibABI encoding utilities for handler data

Libraries

ContractPurpose
CreateCallCREATE/CREATE2 from Safe context
MultiSendBatch multiple transactions in one call
MultiSendCallOnlyBatch CALL-only transactions (no DELEGATECALL)
SafeMigrationSingleton upgrade with optional fallback handler update
SafeStorageStorage slot layout (singleton at slot 0)
SafeToL2SetupSetup helper for L2 Safe initialization
SignMessageLibEIP-191/EIP-712 message signing from Safe
SimulateTxAccessorSimulate transaction for gas estimation

Guards (Examples)

GuardPurpose
DebugTransactionGuardLogs all transaction details for debugging
DelegateCallTransactionGuardBlocks DELEGATECALL operations
OnlyOwnersGuardRestricts execution to Safe owners only
ReentrancyTransactionGuardPrevents reentrancy during execution

Deployment Scripts

7 Hardhat deploy scripts in src/deploy/:

ScriptTagsDeploys
deploy_safe_singleton.tssingleton, main-suiteSafe implementation
deploy_safe_l2.tsl2, main-suiteSafeL2 implementation
deploy_factories.tsfactory, main-suiteSafeProxyFactory
deploy_handlers.tshandlers, main-suiteFallback handlers
deploy_libraries.tslibraries, main-suiteMultiSend, CreateCall, etc.
deploy_accessors.tsaccessors, main-suiteSimulateTxAccessor
deploy_migrations.tsmigrations, main-suiteSafeMigration

All deployments use deterministic deployment (safe-singleton-factory) for identical addresses cross-chain.

Hardhat Tasks

TaskPurpose
deploy_contractsDeploy all contracts to a network
local_verifyVerify contract source on local explorer
show_codesizeDisplay contract bytecode sizes

Test Suite

Tests organized in test/ with 10+ categories:

DirectoryCoverage
core/Execution, signatures, storage, setup, owner/module/guard/fallback management
factory/Proxy creation, deterministic deployment
guards/Guard hook behavior
handlers/Fallback handler routing, extensible handlers
integration/End-to-end workflows
l2/SafeL2 event emission
libraries/MultiSend, CreateCall, migration
migration/Singleton upgrade paths
json/ABI/JSON compatibility
utils/Test utilities

Benchmark specs in benchmark/: Creation, ERC1155, ERC20, Ether, MultiSend, Proxy.

Test commands:

npm run test:hardhat    # All Hardhat tests
npm run test:L1         # L1-specific tests (chainId=1)
npm run test:L2         # L2 tests (SafeL2)
npm run test:secp256r1  # EIP-7951 P-256 precompile tests
npm run benchmark       # Gas benchmarks
npm run coverage        # Coverage report

Formal Verification (Certora)

14 CVL specs in certora/specs/:

SpecVerifies
Execute.specTransaction execution invariants
Signatures.specSignature validation correctness
Setup.specInitialization safety
Safe.specCore Safe properties
SafeMigration.specMigration correctness
OwnerReach.specOwner linked list reachability
ModuleReach.specModule linked list reachability
Guards.specGuard hook execution
Fallback.specFallback routing
Hash.specEIP-712 hash computation
NativeTokenRefund.specGas refund in native token
SafeToL2Setup.specL2 setup correctness
Extensible.specExtensible handler properties

Audit History

Audit reports in docs/ covering versions 1.0.0 through 1.5.0:

VersionAuditorType
1.0.0G0 GroupSecurity audit
1.0.0Runtime VerificationFormal verification
1.1.0G0 GroupSecurity audit
1.1.1G0 GroupSecurity audit
1.2.0G0 GroupSecurity audit
1.3.0G0 GroupSecurity audit (initial + final)
1.4.0CertoraFormal verification
1.4.1Ackee BlockchainLibrary contracts
1.5.0Ackee BlockchainSecurity audit
1.5.0CertoraFormal verification

React Wallet UI (Legacy)

Located in react/, version 3.32.1. React 17 + Redux + Material-UI application.

ItemValue
FrameworkCRA (rescripts)
StateRedux + redux-thunk
Web3web3.js 1.7, @gnosis.pm/safe-core-sdk
UIMaterial-UI v4
TestingJest, Cypress
Node16 (.nvmrc)

Next.js Landing/Docs Site

Located in src/app/, uses Next.js with static export (output: 'export').

ItemValue
FrameworkNext.js 15, React 18
StylingTailwind CSS
Dependencies@luxfi/ui, @luxfi/data, @luxfi/menu-icons, @hanzo/auth, @hanzo/commerce
DeploymentGitHub Pages (static)

Hardhat Network Configuration

NetworkURL
hardhatLocal (chainId configurable via HARDHAT_CHAIN_ID, default 31337)
mainnetInfura (requires INFURA_KEY)
sepoliaInfura (requires INFURA_KEY)
gnosisrpc.gnosischain.com
zksyncmainnet.era.zksync.io
customAny URL via NODE_URL env var

RIP-7212 precompile enabled via HARDHAT_SECP256R1_PRECOMPILE=1.

Development

git clone https://github.com/luxfi/safe.git
cd safe
npm install
npx hardhat compile         # Compile contracts
npx hardhat test            # Run all tests
npm run test:secp256r1      # Test P-256 verification
npm run coverage            # Coverage report
npm run codesize            # Check bytecode sizes
npm run deploy-all custom   # Deploy to custom network (NODE_URL)

Key Interfaces

InterfacePurpose
ISafeFull Safe API (setup, execTransaction, checkSignatures, approveHash, nonce)
IModuleManagerModule enable/disable/execute
IOwnerManagerOwner add/remove/swap, threshold
IGuardManagerGuard set/get
IFallbackManagerFallback handler set
ISignatureValidatorERC-1271 isValidSignature
  • lux/lux-wallet.md -- Wallet integration with Safe
  • lux/lux-crypto.md -- Cryptographic primitives
  • lux/lux-governance.md -- DAO treasury management via Safe

Lux Ringtail - Post-Quantum Threshold Signatures

Ringtail is the post-quantum signature primitive for Lux consensus. It enables t-of-n threshold signing without relying on classical assumptions R...

Lux EVM Precompiled Contracts

Custom Stateful Precompiles

On this page

OverviewQuick ReferenceRepository StructureContractsCoreBase ModulesEIP SupportHandlersExtensible Handler SystemLibrariesGuards (Examples)Deployment ScriptsHardhat TasksTest SuiteFormal Verification (Certora)Audit HistoryReact Wallet UI (Legacy)Next.js Landing/Docs SiteHardhat Network ConfigurationDevelopmentKey InterfacesRelated Skills