merge release/20250308 into main

.doc/content.md

@@ -0,0 +1,14 @@
+# Content
+
+## Technical Overview
+
+* [Contracts Overview](./technical-overview/overview.md)
+* [Contracts Details](./technical-overview/contracts-details.md)
+
+## Development
+
+* [Development Guidelines](./development/development-guidelines.md)
+
+## Deployment
+
+* [Deploy Guidelines](./deployment/deployment-guidelines.md)

.doc/deployment/deployment-guidelines.md

@@ -0,0 +1,56 @@
+# Deployment Guidelines
+
+## Contracts Deployment
+
+Find contract deployment addresses by network at these links:
+
+- USDT 0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9 
+- USDC (Circle): [Circle Contracts Addresses](https://www.circle.com/blog/usdc-on-arbitrum-now-available)
+- WETH:  [Arbitrum Contract Addresses](https://docs.arbitrum.io/build-decentralized-apps/reference/contract-addresses)
+- Uniswap Swap Router: [Uniswap Contract Deployments](https://docs.uniswap.org/contracts/v3/reference/deployments/polygon-deployments) 
+- EntryPoint: [eth Infinitism - Account Abstraction](https://github.com/eth-infinitism/account-abstraction/releases/tag/v0.6.0)
+
+
+## Paymaster Deployment
+
+### Post-Deployment
+
+After deploying a new Paymaster contract, you **MUST** perform the staking process to deposit ETH into the StakeManager of the EntryPoint. This step is essential for security purposes and is validated by the bundler to ensure the proper operation of the Paymaster contract. 🛡️
+
+This is a critical step that you **cannot skip** after deployment. Failure to stake the required ETH will result in the bundler failing to validate the contract, and your transactions may not work correctly! 🚨
+
+#### **How to Stake:**
+
+1. **Run the following command to stake ETH in the Paymaster contract:**
+
+```sh
+cast send paymaster_contract_address "addStake(uint32)" 100000 --value 100000000000000000 --from backend_signer_wallet_address --rpc-url https://arb-sepolia.g.alchemy.com/v2/API_KEY_ALCHEMY --private-key _backend_signer_wallet_private_key
+```
+
+   - `100000` represents the amount of seconds of unstake time.
+   - `100000000000000000` equals **0.1 ETH** to be staked.
+
+   **Important Notes:**
+   - Make sure you have enough ETH in the backend signer wallet to cover the stake.
+   - The staking process is required for security validation and interaction with the EntryPoint.
+
+2. **To check the balance and verify the stake:**
+
+```sh
+cast call entrypoint_contract_address "getDepositInfo(address)(uint112,bool,uint112,uint32,uint48)" paymaster_contract_address --rpc-url https://arb-sepolia.g.alchemy.com/v2/API_KEY_ALCHEMY
+```
+
+   This will return the deposit information, including the amount of staked ETH and other relevant details.
+
+#### **Why Is This Important?**
+
+- **Security:** The bundler validates this stake to ensure that the Paymaster contract can be used safely and securely within the ecosystem. 🛡️
+- **Smooth Operations:** Without this staking, the contract will not pass bundler validation and operations will fail. ⚠️
+
+#### **Additional Notes on StakeManager & Bundler**
+
+The **StakeManager** within the EntryPoint is responsible for managing the ETH deposits that cover gas costs for Paymaster operations. By staking ETH in the StakeManager, you are essentially providing a guarantee that there are sufficient funds to pay for transaction fees. This step is critical for the bundler to validate and process transactions that the Paymaster is handling.
+
+The **bundler** is a service that aggregates multiple transactions and ensures that gas is paid in an efficient manner. Without proper staking, the bundler will not validate the transactions, and the system will fail to function as intended.
+
+Make sure you complete this step right after the Paymaster deployment, as it is a necessary part of the contract initialization. ✅

.doc/development/coding-guidelines.md

@@ -0,0 +1,48 @@
+# Coding guidelines
+
+## Configuring Git's line ending handling
+
+This cofniguration converts LF to CRLF when checking out in Windows systems and CRLF to LF when committing.
+
+```sh
+# Global Configuration: Applies the settings to all repositories on your system.
+git config --global core.autocrlf true
+```
+
+```sh
+# Local Configuration: Applies the settings only to the current repository.
+git config core.autocrlf true
+```
+
+
+## Commit changes
+
+It is recommended to use a linter for commit messages, which should be specified in the following format:
+
+```sh
+- [type] message
+- [type] :icono: message
+```
+
+Example:
+
+```sh
+- commit -m [chore] add commitlinter
+- commit -m [chore] :sparkles: add commitlinter (to commit with an icon, you can use [gitmoji](https://gitmoji.dev/))
+```
+
+The allowed standard types are:
+
+```sh
+- feat: A new feature for the user.
+- fix: Fixes a bug that affects the user.
+- perf: Changes that improve site performance.
+- build: Changes in the build system, deployment tasks, or installation.
+- ci: Changes in continuous integration.
+- docs: Changes in documentation.
+- refactor: Code refactoring such as variable or function name changes.
+- style: Changes in formatting, tabs, spaces, or semicolons, etc.; do not affect the user.
+- test: Adds tests or refactors an existing one.
+- chore: Other changes that don't modify src or test files.
+- revert: Reverts a previous commit.
+```

.doc/technical-overview/contracts-details.md

@@ -0,0 +1,146 @@
+# ChatterPay Contracts Details
+
+## 1. [**ChatterPay.sol**](../../src/ChatterPay.sol)
+
+### **High-Level Overview**:
+The `ChatterPay` contract serves as the core of the ChatterPay ecosystem, acting as a smart wallet implementation that supports ERC-4337 account abstraction. It facilitates token transfers, fee management, Uniswap-based token swaps, and integration with price oracles for real-time token valuation.
+
+### **Key Features**:
+- **ERC-4337 Account Abstraction**: Supports user operations via the EntryPoint contract, enabling decentralized transaction validation.
+- **Fee Management**: Implements a fee structure in USD cents, with customizable pool fees and slippage for token swaps.
+- **Uniswap V3 Integration**: Executes token swaps with single-hop or multi-hop routes and customizable price tolerances.
+- **Token Whitelisting and Price Feeds**: Allows only whitelisted tokens to be used, with price feeds from Chainlink oracles.
+- **Batch Transfers**: Supports multiple token transfers in a single transaction.
+- **Upgradeable**: Built using `UUPSUpgradeable` for future enhancements.
+
+### **Relations with Other ChatterPay Contracts**:
+- **ChatterPayPaymaster**: Works alongside the Paymaster to manage fees and user operations.
+- **ChatterPayVault**: Can interact with the vault for secure asset storage and retrieval.
+- **ChatterPayWalletFactory**: Deployed wallets are created and managed by the factory contract.
+
+### **External Contract Interactions**:
+- **Uniswap V3 Router**: Interacts with the swap router for token exchanges.
+- **Chainlink Oracles**: Retrieves token prices to calculate fees and ensure transaction accuracy.
+
+---
+
+## 2. [**ChatterPayNFT.sol**](../../src/ChatterPayNFT.sol)
+
+### **High-Level Overview**:
+The `ChatterPayNFT` contract enables the minting and management of both original NFTs and their limited copies. It incorporates robust features for URI management, copy limits, and upgradeability.
+
+### **Key Features**:
+- **ERC721 NFTs**: Implements the ERC721 standard for unique digital assets.
+- **Original and Copy NFTs**: Allows the creation of original NFTs and associated copies with defined limits.
+- **Base URI Management**: Supports dynamic updates to the base URI by the contract owner.
+- **Upgradeable**: Built using `UUPSUpgradeable` for seamless updates.
+
+### **Relations with Other ChatterPay Contracts**:
+- **ChatterPay**: NFTs can be linked to wallet activities for rewards or asset tracking.
+- **ChatterPayVault**: Original and copy NFTs may serve as collateral or proof of ownership within the vault.
+
+### **External Contract Interactions**:
+- **ERC721URIStorage**: Provides extended functionality for metadata management.
+
+---
+
+## 3. [**ChatterPayPaymaster.sol**](../../src/ChatterPayPaymaster.sol)
+
+### **High-Level Overview**:
+The `ChatterPayPaymaster` contract validates and manages user operations in collaboration with the EntryPoint contract. It uses signature-based authentication to ensure secure and authorized transactions.
+
+### **Key Features**:
+- **Paymaster Role**: Acts as a trusted intermediary to sponsor transaction costs for users.
+- **Signature Validation**: Ensures operations are authorized via backend-signed messages.
+- **Fee Management**: Integrates seamlessly with the `ChatterPay` wallet for fee processing.
+- **Upgradeable**: Can be enhanced with new functionalities over time.
+
+### **Relations with Other ChatterPay Contracts**:
+- **ChatterPay**: Handles operation validation and fee sponsorship for the wallet contract.
+
+### **External Contract Interactions**:
+- **EntryPoint**: Collaborates with the EntryPoint contract for operation validation.
+
+---
+
+## 4. [**ChatterPayVault.sol**](../../src/ChatterPayVault.sol)
+
+### **High-Level Overview**:
+The `ChatterPayVault` contract serves as a secure storage mechanism for password-protected commitments. It supports the reservation, redemption, and cancellation of payments.
+
+### **Key Features**:
+- **Password-Protected Payments**: Uses hashed passwords for added security in transactions.
+- **Commitment Expiration**: Ensures timely redemption or cancellation of commitments.
+- **ERC20 Integration**: Handles token-based payments securely.
+
+### **Relations with Other ChatterPay Contracts**:
+- **ChatterPay**: Interacts with the main wallet for secure payment and asset management.
+- **ChatterPayNFT**: Supports NFTs as collateral or proof of ownership.
+
+### **External Contract Interactions**:
+- **ERC20**: Facilitates secure token transfers within the vault.
+
+---
+
+## 5. [**ChatterPayWalletFactory.sol**](../../src/ChatterPayWalletFactory.sol)
+
+### **High-Level Overview**:
+The `ChatterPayWalletFactory` contract is responsible for deploying and managing wallet proxies for users. It leverages deterministic address computation for predictable wallet creation.
+
+### **Key Features**:
+- **Wallet Proxy Creation**: Deploys upgradeable wallet proxies using the ERC1967 standard.
+- **Proxy Tracking**: Maintains a record of all deployed wallet proxies.
+- **Upgradeable**: Built to support future enhancements.
+
+### **Relations with Other ChatterPay Contracts**:
+- **ChatterPayWalletProxy**: Deploys and manages proxies for the core wallet.
+
+---
+
+## 6. [**ChatterPayWalletProxy.sol**](../../src/ChatterPayWalletProxy.sol)
+
+### **High-Level Overview**:
+The `ChatterPayWalletProxy` contract provides upgradeable functionality for wallets using the ERC1967 Proxy standard. It ensures that wallets can be updated without changing their addresses.
+
+### **Key Features**:
+- **Upgradeable Wallets**: Supports upgrades to wallet implementations while preserving state.
+- **ERC1967 Standard**: Provides a reliable mechanism for proxy upgrades.
+
+### **Relations with Other ChatterPay Contracts**:
+- **ChatterPayWalletFactory**: Proxies are deployed and managed by the factory.
+- **ChatterPay**: Proxies delegate calls to the main wallet implementation.
+
+---
+
+## 7. [**AggregatorV3Interface.sol**](../../src/interfaces/AggregatorV3Interface.sol)
+
+### **High-Level Overview**:
+The `AggregatorV3Interface` defines the interface for Chainlink price feeds. It enables the retrieval of real-time token prices and metadata.
+
+### **Key Features**:
+- **Price Feeds**: Provides real-time token prices from decentralized oracles.
+- **Metadata Access**: Retrieves additional information like price feed descriptions and versions.
+
+### **Relations with Other ChatterPay Contracts**:
+- **ChatterPay**: Utilizes price feeds to calculate transaction fees and validate swaps.
+
+### **External Contract Interactions**:
+- **Chainlink Oracles**: Fetches price data for supported tokens.
+
+---
+
+## 8. [**ISwapRouter.sol**](../../src/interfaces/ISwapRouter.sol)
+
+### **High-Level Overview**:
+The `ISwapRouter` interface facilitates token swaps using the Uniswap V3 protocol. It supports both single-hop and multi-hop swaps with fine-grained control over slippage and fees.
+
+### **Key Features**:
+- **Token Swapping**: Enables efficient token exchanges within the ecosystem.
+- **Customizable Parameters**: Supports exact input/output swaps with defined slippage tolerances.
+
+### **Relations with Other ChatterPay Contracts**:
+- **ChatterPay**: Executes swaps for supported tokens using the router.
+
+### **External Contract Interactions**:
+- **Uniswap V3**: Provides the infrastructure for token swaps.
+

.doc/technical-overview/overview.md

@@ -0,0 +1,52 @@
+# ChatterPay Contracts Overview
+
+## Summary
+
+These smart contracts collectively create a robust ecosystem for wallet management, token price feeds, and NFT handling. They provide flexibility, upgradeability, and security by implementing key features like account abstraction, secure wallet deployment, NFT minting, and real-time price data management. The system allows for efficient wallet creation, management of user operations, and the minting of original and copy NFTs, all while ensuring that transaction fees and external data feeds are properly handled.
+
+## Contracts List:
+
+1. [**ChatterPay.sol**](../../src/ChatterPay.sol)  
+Core wallet contract for ChatterPay, handling user operations, token transfers, and transaction fee management.
+
+# ChatterPay Contracts Overview
+
+## Summary
+
+These smart contracts collectively form a powerful ecosystem for wallet management, token price feeds, NFT handling, and transaction facilitation. They offer flexibility, upgradeability, and security by implementing advanced features like account abstraction, Uniswap V3 integration, secure wallet deployment, NFT minting, password-protected vaults, and real-time price feed management. The system enables efficient wallet creation, user operations management, token swaps, and NFT minting with robust mechanisms to handle fees, slippage, and external data feeds.
+
+## Contracts List:
+
+1. [**ChatterPay.sol**](../../src/ChatterPay.sol)  
+   Core wallet contract for ChatterPay, supporting ERC-4337 account abstraction, Uniswap integration, transaction fee management, and token whitelisting.
+
+2. [**ChatterPayNFT.sol**](../../src/ChatterPayNFT.sol)  
+   Manages the minting of original NFTs and their limited copies. Includes functionality for copy limits, metadata updates, and ownership management, using an upgradeable proxy structure.
+
+3. [**ChatterPayPaymaster.sol**](../../src/ChatterPayPaymaster.sol)  
+   Paymaster contract that validates and manages user operations with signature-based authentication and fee handling, integrated with the EntryPoint contract.
+
+4. [**ChatterPayVault.sol**](../../src/ChatterPayVault.sol)  
+   A vault contract that handles password-protected payments, commitments, and secure asset storage with mechanisms for reservation, redemption, and cancellation.
+
+5. [**ChatterPayWalletFactory.sol**](../../src/ChatterPayWalletFactory.sol)  
+   Factory contract for deploying and managing ChatterPay wallet proxies. Provides deterministic address computation, proxy tracking, and upgradeability.
+
+6. [**ChatterPayWalletProxy.sol**](../../src/ChatterPayWalletProxy.sol)  
+   An upgradeable proxy contract for ChatterPay wallets, leveraging the ERC-1967 Proxy standard to enable wallet upgrades and version control.
+
+7. [**AggregatorV3Interface.sol**](../../src/interfaces/AggregatorV3Interface.sol)  
+   Interface for interacting with Chainlink price feed aggregators, providing methods to fetch price data and metadata for token feeds.
+
+8. [**ISwapRouter.sol**](../../src/interfaces/ISwapRouter.sol)  
+   Interface for the Uniswap V3 swap router, enabling precise control over token swaps, slippage, and multi-hop routing.
+
+---
+
+Representation of Chatterpay's Smart Contracts Flow:
+
+
+![ChatterPay Smart Contracts Flow](./images/chatterpay-contracts-flow.png)
+
+
+[Here](./contracts-details.md) you can see a detailed breakdown of the provided smart contracts used for ChatterPay. 

.github/workflows/slither.yml

@@ -0,0 +1,37 @@
+name: Smart Contract Security Analysis
+on:
+  push:
+    branches:
+    - '*'
+  pull_request:
+    branches:
+      - develop
+      - main
+
+jobs:
+  analyze:
+    name: Smart Contract Static Analysis
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Set up Node.js and Yarn
+      uses: actions/setup-node@v3
+      with:
+        node-version: '20.15.0'
+        cache: 'yarn'
+
+    - name: Install dependencies with Yarn
+      run: |
+        yarn install
+
+    - name: Run Slither
+      uses: crytic/[email protected]
+      id: slither
+      with:
+        fail-on: none
+      continue-on-error: true