Multi-Level Sequential Approval System

ERC-4337 compatible multi-level sequential approval system for institutional blockchain accounts with amount-based routing, dynamic quorum, time-locked progression, and veto capability.

Features

• ERC-4337 Compatibility: Standard transaction format via EntryPoint
• Amount-Based Routing: Different approval paths based on transaction amount
• Dynamic Quorum: Per-level quorum requirements based on amount
• Time-Locked Progression: Configurable timelocks between approval levels
• Veto Capability: Any signer can deny a transaction at any level
• Privacy-Preserving: Signers only see their level, not other levels
• TypeScript SDK: Full-featured SDK for easy integration
• Comprehensive Tests: Unit, integration, security, and ERC-4337 tests

Project Structure

implementation/
├── contracts/          # Smart contracts
│   ├── core/          # Main contracts
│   ├── interfaces/    # Contract interfaces
│   └── libraries/     # Utility libraries
├── test/              # Test suite
│   ├── unit/          # Unit tests
│   ├── integration/   # Integration tests
│   ├── 4337/          # ERC-4337 tests
│   ├── security/      # Security tests
│   └── helpers/       # Test utilities
├── sdk/               # TypeScript SDK
└── scripts/           # Deployment scripts

Prerequisites

• Node.js 18.x or higher
• npm

Installation

cd implementation
npm install

Contributor Quickstart

1. Create a local env file (don’t commit secrets):

cd implementation
cp env.example .env

2. Compile:

npm run compile

3. Run tests:

# Most tests
npm test

# Skip bundler-related setup/tests (fastest)
SKIP_BUNDLER=1 npm test

Bundler test setup details:

• test/README_BUNDLER.md
• test/helpers/BUNDLER_SETUP.md

Usage

Compile Contracts

npm run compile

Run Tests

# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:4337
npm run test:security

Generate Coverage Report

npm run coverage

This generates a comprehensive coverage report for all Solidity contracts. The report includes:

• Line coverage
• Branch coverage
• Function coverage
• Statement coverage

Reports are generated in the coverage/ directory. Open coverage/index.html in a browser to view the detailed report.

Coverage Targets:

• Line Coverage: 95%+
• Branch Coverage: 90%+
• Function Coverage: 100%
• Critical Paths: 100%

Deploy Contracts

# Start a local chain (separate terminal)
npx hardhat node

# Deploy to local network (separate terminal)
npm run deploy:local

# Deploy to Sepolia testnet
npm run deploy:sepolia

For script-by-script usage and required env vars, see scripts/README.md.

Development

This project uses:

• Hardhat for development environment
• TypeScript for type safety
• Ethers.js v6 (via Hardhat) for deployment scripts/tests
• viem + permissionless in the SDK
• OpenZeppelin Contracts v5 for security
• @account-abstraction/contracts for ERC-4337 support

SDK

A TypeScript SDK is included in the sdk/ directory. See SDK README for details.

Testing

# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:4337
npm run test:security

# Generate coverage report
npm run coverage

Deployment

See Deployment Guide for detailed instructions on deploying to local, testnet, and mainnet networks.

# Deploy to local network
npm run deploy:local

# Deploy to Sepolia testnet
npm run deploy:sepolia

Support & Troubleshooting

See Troubleshooting Guide for solutions to common issues.

Documentation

Contracts

• Contracts README - Contract overview and features
• Contract Architecture - System architecture and design
• Contract API Reference - Complete API documentation

SDK

• SDK README - SDK overview and quick start
• SDK Architecture - SDK design and patterns
• SDK API Documentation - SDK API reference
• SDK Integration Guide - Complete integration guide
• SDK Examples - Usage examples

Scripts

• Scripts README - Deploy/config/verify scripts and env vars

Testing

• Testing Overview - Test suite structure and overview
• Testing Guide - Complete testing guide
• Test Helpers - Test utilities documentation

Other

• Implementation Plan - Complete technical specification

License

MIT