Startale Smart Account Contracts 🚀

A modular smart account implementation compliant with ERC-4337 and ERC-7579 standards, built with Foundry.

📚 Table of Contents

• Features
• Getting Started
  • Prerequisites
  • Installation
• Core Components
• Development
  • Build
  • Testing
  • Coverage
• Deployment
• Architecture
• Security
• License

Features

ERC-4337 & ERC-7579 Compliance

Full implementation of account abstraction standards with modular architecture.

Modular Design

Support for validators, executors, hooks, and fallback modules with easy extensibility.

Factory Pattern

Deterministic deployment of smart accounts with customizable initialization.

Advanced Testing

Comprehensive test suite including unit, integration, and property-based fuzzing tests.

Gas Optimization

Optimized for gas efficiency with support for both standard and IR-based compilation.

Security Features

Built-in security patterns including access control, module validation, and upgrade safety.

Getting Started

Prerequisites

• Foundry (latest version)
• Node.js (v18.x or later) preferred: >= v23.7.0
• Yarn (or npm)

Installation

1. Clone the repository:

git clone https://github.com/startale/scs-aa-account-contracts.git
cd scs-aa-account-contracts

2. Install dependencies:

yarn install
git submodule update --init --recursive

3. Copy and configure environment variables:

cp .env.example .env

Core Components

• BaseAccount: Core implementation of ERC-4337 account abstraction
• StartaleSmartAccount: Main smart account implementation with ERC-7579 compliance
• ModuleManager: Handles module installation, removal, and validation
• Factory Contracts:
  • StartaleAccountFactory: Generic factory for custom deployments
  • EOAOnboardingFactory: Specialized factory for EOA-based accounts

Development

Build

Standard build:

yarn build

Optimized build (via IR):

yarn build:optimized

Testing

Run all tests:

yarn test

Run specific test suites:

yarn test:unit        # Unit tests
yarn test:integration # Integration tests
yarn test:unit:deep   # Deep fuzzing tests

Coverage

Generate coverage report:

yarn coverage

Deployment

Setup

1. Configure environment variables:

source .env

Deploy

forge script script/DeployStartaleAccountFactoryCreate3.s.sol:DeployStartaleAccountFactoryCreate3 --rpc-url <RPC_URL> --broadcast --private-key <PRIVATE_KEY>
( and so on for other contracts)

### Deployed addresses

| Contract Name                   | Address                                      |
|---------------------------------|----------------------------------------------|
| Startale Account Implementation | `0x000000b8f5f723a680d3d7ee624fe0bc84a6e05a` |
| Startale Account Factory        | `0x0000003B3E7b530b4f981aE80d9350392Defef90` |
| Bootstrap                       | `0x000000552A5fAe3Db7a8F3917C435448F49BA6a9` |
| ECDSA Validator                 | `0x00000072F286204Bb934eD49D8969E86F7dEC7b1` |```


## Architecture

The smart account implementation follows a modular architecture:

1. **Core Layer**
   - Base account abstraction
   - Module management
   - Storage management

2. **Module Layer**
   - Validators (e.g., ECDSA)
   - Executors
   - Hooks
   - Fallback handlers

3. **Factory Layer**
   - Deterministic deployment
   - Custom initialization
   - EOA onboarding

## Security

- ERC-7201 namespaced storage
- UUPS upgrade pattern
- Module validation and isolation
- Access control mechanisms

## License

This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.

## Reference 

<img src="https://raw.githubusercontent.com/defi-wonderland/brand/v1.0.0/external/solidity-foundry-boilerplate-banner.png" alt="wonderland banner" align="center" />
<br />

<div align="center"><strong>Start your next Solidity project with Foundry in seconds</strong></div>
<div align="center">A highly scalable foundation focused on DX and best practices</div>

<br />

## Export And Publish

Export TypeScript interfaces from Solidity contracts and interfaces providing compatibility with TypeChain. Publish the exported packages to NPM.

To enable this feature, make sure you've set the `NPM_TOKEN` on your org's secrets. Then set the job's conditional to `true`:

```yaml
jobs:
  export:
    name: Generate Interfaces And Contracts
    # Remove the following line if you wish to export your Solidity contracts and interfaces and publish them to NPM
    if: true
    ...

Also, remember to update the package_name param to your package name:

- name: Export Solidity - ${{ matrix.export_type }}
  uses: defi-wonderland/solidity-exporter-action@1dbf5371c260add4a354e7a8d3467e5d3b9580b8
  with:
    # Update package_name with your package name
    package_name: "my-cool-project"
    ...


- name: Publish to NPM - ${{ matrix.export_type }}
  # Update `my-cool-project` with your package name
  run: cd export/my-cool-project-${{ matrix.export_type }} && npm publish --access public
  ...

You can take a look at our solidity-exporter-action repository for more information and usage examples.