base · AdekunleBamz · Jan 10, 2026
diff --git a/.gitmodules b/.gitmodules
@@ -1,3 +1,15 @@
 [submodule "lib/forge-std"]
 	path = lib/forge-std
 	url = https://github.com/foundry-rs/forge-std
+[submodule "lib/openzeppelin-contracts"]
+	path = lib/openzeppelin-contracts
+	url = https://github.com/OpenZeppelin/openzeppelin-contracts
+[submodule "lib/solady"]
+	path = lib/solady
+	url = https://github.com/vectorized/solady
+[submodule "lib/smart-wallet"]
+	path = lib/smart-wallet
+	url = https://github.com/coinbase/smart-wallet
+[submodule "lib/magicspend"]
+	path = lib/magicspend
+	url = https://github.com/coinbase/magicspend
diff --git a/README.md b/README.md
@@ -1,66 +1,191 @@
-## Foundry
+# Account Permissions
 
-**Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.**
+A modular, wallet-agnostic permission management system for EVM smart accounts. This protocol enables secure delegation of account actions through installable policies, allowing fine-grained control over what authorized parties can do on behalf of smart wallet users.
 
-Foundry consists of:
+## Overview
 
-- **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools).
-- **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data.
-- **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network.
-- **Chisel**: Fast, utilitarian, and verbose solidity REPL.
+The Account Permissions protocol provides a framework for:
 
-## Documentation
+- **Policy-based permissions**: Install policies that define specific actions an authority can execute on behalf of a smart wallet
+- **Flexible authorization**: Support for both signature-based and direct-call policy installation/revocation
+- **Composable design**: Modular policies and adapters for different use cases (spending, swaps, lending)
+- **ERC-6492 support**: Compatible with signatures that include deployment side effects
 
-https://book.getfoundry.sh/
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         PermissionManager                               │
+│  - Install/revoke policies via signature or direct call                 │
+│  - Execute policy-authorized actions on behalf of accounts              │
+│  - EIP-712 typed data signing for secure authorization                  │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+                    ┌───────────────┼───────────────┐
+                    ▼               ▼               ▼
+            ┌───────────┐   ┌───────────┐   ┌───────────┐
+            │  Policy   │   │  Policy   │   │  Policy   │
+            │ (Spend)   │   │  (Swap)   │   │ (Lending) │
+            └───────────┘   └───────────┘   └───────────┘
+                                                    │
+                                            ┌───────┴───────┐
+                                            ▼               ▼
+                                    ┌───────────┐   ┌───────────┐
+                                    │  Adapter  │   │  Adapter  │
+                                    │ (Aave V3) │   │  (Other)  │
+                                    └───────────┘   └───────────┘
+```
+
+## Contracts
+
+### Core
+
+| Contract | Description |
+|----------|-------------|
+| `PermissionManager.sol` | Central hub for installing, revoking, and executing policies |
+| `PermissionTypes.sol` | Shared type definitions for the permission system |
+| `PublicERC6492Validator.sol` | ERC-6492 signature validation with side effects support |
+
+### Policies
+
+| Contract | Description |
+|----------|-------------|
+| `SpendPolicy.sol` | Token spending permissions with allowances, periods, and hooks |
+| `CoinbaseSmartWalletSwapPolicy.sol` | Constrained token swap execution with slippage protection |
+| `CoinbaseSmartWalletSingleCallPolicy.sol` | Simple ETH transfer policy with value limits |
+| `LendingPolicy.sol` | DeFi lending operations with health factor enforcement |
+
+### Adapters
+
+| Contract | Description |
+|----------|-------------|
+| `AaveV3Adapter.sol` | Aave V3 protocol adapter for lending operations |
+| `ILendingAdapter.sol` | Interface for lending protocol adapters |
+
+### Spend Hooks
+
+| Contract | Description |
+|----------|-------------|
+| `SpendHook.sol` | Interface for spend permission preparation hooks |
+| `ERC20SpendHook.sol` | ERC20 approval preparation for spending |
+| `NativeTokenSpendHook.sol` | Native ETH transfer preparation |
+| `MagicSpendSpendHook.sol` | Integration with MagicSpend paymaster |
+| `SubAccountSpendHook.sol` | Sub-account token transfer handling |
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/AdekunleBamz/account-permissions.git
+cd account-permissions
+
+# Install dependencies (including submodules)
+git submodule update --init --recursive
+
+# Build
+forge build
+```
 
 ## Usage
 
 ### Build
 
-```shell
-$ forge build
+```bash
+forge build
 ```
 
 ### Test
 
-```shell
-$ forge test
+```bash
+forge test
 ```
 
 ### Format
 
-```shell
-$ forge fmt
+```bash
+forge fmt
 ```
 
 ### Gas Snapshots
 
-```shell
-$ forge snapshot
+```bash
+forge snapshot
 ```
 
-### Anvil
+## Key Concepts
 
-```shell
-$ anvil
-```
+### Policy Installation
 
-### Deploy
+Policies are installed by the account owner through either:
+1. **Signature-based**: Sign an EIP-712 typed message authorizing the policy
+2. **Direct call**: Call `installPolicy` directly from the smart wallet
 
-```shell
-$ forge script script/Counter.s.sol:CounterScript --rpc-url <your_rpc_url> --private-key <your_private_key>
+```solidity
+struct Install {
+    address account;       // The smart wallet address
+    address policy;        // The policy contract to install
+    bytes32 policyConfigHash; // Hash of policy-specific configuration
+    uint48 validAfter;     // Policy activation timestamp
+    uint48 validUntil;     // Policy expiration timestamp
+    uint256 salt;          // Unique identifier for the policy instance
+}
 ```
 
-### Cast
+### Policy Execution
 
-```shell
-$ cast <subcommand>
+Once installed, an authority (defined by the policy) can execute actions:
+
+```solidity
+function execute(
+    PermissionTypes.Install calldata install,
+    bytes calldata policyConfig,
+    bytes calldata policyData,
+    uint256 execNonce,
+    uint48 deadline,
+    bytes calldata authoritySig
+) external;
 ```
 
-### Help
+### Spend Permissions
+
+The `SpendPolicy` enables recurring spending allowances:
+
+- **Allowance**: Maximum amount spendable per period
+- **Period**: Time window for allowance reset (e.g., daily, weekly)
+- **Start/End**: Permission validity window
+- **Hooks**: Customizable preparation logic for different token types
+
+## Security Considerations
+
+- Policies should be carefully audited before installation
+- Authority keys should be secured appropriately for their permission scope
+- Health factor checks in lending policies provide liquidation protection
+- Signature replay is prevented through nonces and deadline enforcement
+
+## Dependencies
+
+This project uses the following dependencies:
+
+- [OpenZeppelin Contracts](https://github.com/OpenZeppelin/openzeppelin-contracts) - Security utilities and token standards
+- [Solady](https://github.com/vectorized/solady) - Gas-optimized Solidity utilities
+- [Coinbase Smart Wallet](https://github.com/coinbase/smart-wallet) - Smart wallet implementation
+- [MagicSpend](https://github.com/coinbase/magicspend) - Paymaster integration
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Please ensure all tests pass and code is formatted before submitting PRs.
+
+```bash
+# Run tests
+forge test
+
+# Format code
+forge fmt
 
-```shell
-$ forge --help
-$ anvil --help
-$ cast --help
+# Check for issues
+forge build --force
 ```
diff --git a/foundry.toml b/foundry.toml
@@ -2,6 +2,28 @@
 src = "src"
 out = "out"
 libs = ["lib"]
-remappings = ["forge-std/=lib/forge-std/src/"]
+remappings = [
+    "forge-std/=lib/forge-std/src/",
+    "openzeppelin-contracts/=lib/openzeppelin-contracts/",
+    "solady/=lib/solady/src/",
+    "smart-wallet/=lib/smart-wallet/src/",
+    "magicspend/=lib/magicspend/src/",
+]
+
+# Compile for EVM version that supports transient storage
+evm_version = "cancun"
+
+[fuzz]
+runs = 256
+
+[fmt]
+line_length = 120
+tab_width = 4
+bracket_spacing = false
+int_types = "long"
+multiline_func_header = "all"
+quote_style = "double"
+number_underscore = "thousands"
+single_line_statement_blocks = "preserve"
 
 # See more config options https://github.com/foundry-rs/foundry/blob/master/crates/config/README.md#all-options
diff --git a/lib/magicspend b/lib/magicspend
diff --git a/lib/openzeppelin-contracts b/lib/openzeppelin-contracts
diff --git a/lib/smart-wallet b/lib/smart-wallet
diff --git a/lib/solady b/lib/solady
diff --git a/script/Counter.s.sol b/script/Counter.s.sol
diff --git a/test/Counter.t.sol b/test/Counter.t.sol