Modular Account Libs

A set of libraries to help build modular smart contract accounts and modules.

Installation

As a Git Submodule in Foundry

forge install erc6900/modular-account-libs@v0.8.0-rc.2

Recommended remappings setup:

modular-account-libs/=lib/modular-account-libs/src/

As an NPM package

pnpm add github:erc6900/modular-account-libs#v0.8.0-rc.2

Any package manager with NPM support can handle this installation, including npm,yarn,pnpm, and bun.

Recommended remappings setup:

modular-account-libs/=node_modules/modular-account-libs/src/

Overview

Libraries

LinkedListSetLib and variants

LinkedListSetLib implements a “linked list set”, in which elements are held in a mapping from one element to the next. This allows for O(1) add, remove, and contains operations, while keeping the set values enumerable onchain. This setup requires that the set prevent the addition of duplicate values, prevent addition of a zero value, and maintain a special value designated as the “sentinel” that identifies the start and end of the list. To achieve this, the data size available to the user is reduced to a maximum of a bytes30.

In addition to supporting these efficient operations, the library also supports a less-efficient remove operation without knowledge of a predecessor, which traverses the linked list to find the element to remove.

Additionally, entries also support “flags”. These can be thought of as additional values attached to entries, much like a sub-mapping for each element within the set. 14 bits are available for flag values, the lowest two bits are reserved for the sentinel implementation and a list traversal optimization.

AssociatedLinkedListSetLib implements a linked list set almost identically to LinkedListSetLib, except its entries are held in account-associated storage. This library is intended to be used by modules, which must hold values in account-associated storage if they wish to access or update them during ERC-4337 validation.

CountableLinkedListSetLib extends LinkedListSetLib to allow adding a value more than once. It uses the upper byte (8 bits) of the 14 available flag bits for an entry to track this, and supports adding an entry up to 256 times. There does not yet exist a version of this library that is held in associated storage.

The common types and constants used by these libraries are defined in Constants.sol.

Building and Testing

To build and test the modular-account-libs repo, use the following commands.

# Build options
forge build
FOUNDRY_PROFILE=lite forge build

# Lint
pnpm lint

# Test Options
forge test -vvv
FOUNDRY_PROFILE=lite forge test -vvv

Acknowledgements

The libraries and stub contracts were originally developed in alchemyplatform/modular-account, and are contributed to the ERC-6900 community here. The original library versions, and audits covering the original library versions, can be found in the linked repository.