@sudobility/contracts 1.16.5 → 1.17.11

package/contracts/MockUSDC.sol

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+/**
+ * @title MockUSDC
+ * @notice Mock USDC token for testing Mailer contracts
+ * @dev ERC20-compatible token with 6 decimals to match real USDC
+ * @author Mailer Team
+ */
+contract MockUSDC {
+    /// @notice Balance tracking for each address
+    mapping(address => uint256) public balanceOf;
+
+    /// @notice Allowance tracking for delegated transfers
+    mapping(address => mapping(address => uint256)) public allowance;
+
+    /// @notice Token name following ERC20 standard
+    string public name = "Mock USDC";
+
+    /// @notice Token symbol following ERC20 standard
+    string public symbol = "USDC";
+
+    /// @notice Token decimals matching real USDC (6 decimals)
+    uint8 public decimals = 6;
+
+    /// @notice Total token supply (1M USDC with 6 decimals)
+    uint256 public totalSupply = 1000000 * 10**6;
+
+    /// @notice Contract owner who can mint new tokens
+    address public immutable owner;
+
+    /// @notice Thrown when non-owner attempts owner-only functions
+    error OnlyOwner();
+
+    /// @notice Thrown when transfer amount exceeds sender's balance
+    error InsufficientBalance();
+
+    /// @notice Thrown when transferFrom amount exceeds allowance
+    error InsufficientAllowance();
+
+    /// @notice Restricts function access to contract owner only
+    modifier onlyOwner() {
+        if (msg.sender != owner) {
+            revert OnlyOwner();
+        }
+        _;
+    }
+
+    /// @notice Initializes the mock USDC token
+    /// @dev Sets deployer as owner and gives them the initial supply
+    constructor() {
+        owner = msg.sender;
+        balanceOf[msg.sender] = totalSupply;
+    }
+    
+    /// @notice Transfer tokens to another address
+    /// @param to Recipient address
+    /// @param amount Amount to transfer (in 6-decimal USDC units)
+    /// @return success True if transfer succeeded
+    function transfer(address to, uint256 amount) external returns (bool) {
+        if (balanceOf[msg.sender] < amount) {
+            revert InsufficientBalance();
+        }
+        balanceOf[msg.sender] -= amount;
+        balanceOf[to] += amount;
+        return true;
+    }
+    
+    /// @notice Transfer tokens from one address to another using allowance
+    /// @param from Source address
+    /// @param to Recipient address  
+    /// @param amount Amount to transfer (in 6-decimal USDC units)
+    /// @return success True if transfer succeeded
+    function transferFrom(address from, address to, uint256 amount) external returns (bool) {
+        if (balanceOf[from] < amount) {
+            revert InsufficientBalance();
+        }
+        if (allowance[from][msg.sender] < amount) {
+            revert InsufficientAllowance();
+        }
+        
+        balanceOf[from] -= amount;
+        balanceOf[to] += amount;
+        allowance[from][msg.sender] -= amount;
+        
+        return true;
+    }
+    
+    /// @notice Approve another address to spend tokens on your behalf
+    /// @param spender Address authorized to spend tokens
+    /// @param amount Amount they can spend (in 6-decimal USDC units)
+    /// @return success True if approval succeeded
+    function approve(address spender, uint256 amount) external returns (bool) {
+        allowance[msg.sender][spender] = amount;
+        return true;
+    }
+    
+    /// @notice Mint new tokens to an address (owner only)
+    /// @dev Used for testing to fund accounts with USDC
+    /// @param to Address to receive the newly minted tokens
+    /// @param amount Amount to mint (in 6-decimal USDC units)
+    function mint(address to, uint256 amount) external onlyOwner {
+        balanceOf[to] += amount;
+        totalSupply += amount;
+    }
+}

package/contracts/examples/MailerIntegrationExample.sol

@@ -0,0 +1,189 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import "../interfaces/IMailer.sol";
+import "../interfaces/IERC20.sol";
+
+/**
+ * @title MailerIntegrationExample
+ * @notice Example contract showing how to integrate Mailer messaging into your smart contract
+ * @dev Demonstrates various patterns for sending messages through the Mailer contract
+ * @author Mailer Team
+ */
+contract MailerIntegrationExample {
+    IMailer public immutable mailer;
+    IERC20 public immutable usdcToken;
+    address public owner;
+
+    event NotificationSent(address indexed recipient, string message);
+    event EmailNotificationSent(string indexed email, string message);
+
+    modifier onlyOwner() {
+        require(msg.sender == owner, "Not owner");
+        _;
+    }
+
+    constructor(address _mailerAddress, address _usdcAddress) {
+        require(_mailerAddress != address(0), "Invalid mailer address");
+        require(_usdcAddress != address(0), "Invalid USDC address");
+
+        mailer = IMailer(_mailerAddress);
+        usdcToken = IERC20(_usdcAddress);
+        owner = msg.sender;
+    }
+
+    /**
+     * @notice Example 1: Send a simple notification to a user
+     * @dev Uses standard fee (0.01 USDC) with no revenue sharing
+     * @param recipient User's wallet address
+     * @param message Notification message
+     */
+    function sendNotification(address recipient, string calldata message) external {
+        // Ensure this contract has USDC approved for Mailer
+        // In production, you'd handle approval management
+
+        mailer.send(
+            recipient,
+            "Notification",
+            message,
+            msg.sender,          // User pays the fee
+            false,               // No revenue sharing (standard fee)
+            true                 // Resolve sender to name
+        );
+
+        emit NotificationSent(recipient, message);
+    }
+
+    /**
+     * @notice Example 2: Send a notification with the contract paying the fee
+     * @dev Contract holds USDC and pays fees on behalf of users
+     * @param recipient User's wallet address
+     * @param message Notification message
+     */
+    function sendNotificationContractPays(address recipient, string calldata message) external {
+        // Contract must first authorize itself with the Mailer
+        // Call: mailer.setPermission(address(this))
+
+        mailer.send(
+            recipient,
+            "System Notification",
+            message,
+            address(this),       // Contract pays the fee
+            false,               // No revenue sharing
+            false                // Don't resolve (contract sender)
+        );
+
+        emit NotificationSent(recipient, message);
+    }
+
+    /**
+     * @notice Example 3: Send a priority message with revenue sharing
+     * @dev Charges full fee (0.1 USDC), recipient can claim 90% back
+     * @param recipient User's wallet address
+     * @param subject Message subject
+     * @param body Message body
+     */
+    function sendPriorityMessage(
+        address recipient,
+        string calldata subject,
+        string calldata body
+    ) external {
+        mailer.send(
+            recipient,
+            subject,
+            body,
+            msg.sender,          // User pays the fee
+            true,                // Enable revenue sharing
+            true                 // Resolve sender to name
+        );
+    }
+
+    /**
+     * @notice Example 4: Send to email address (when wallet is unknown)
+     * @dev Always uses standard fee, no revenue sharing possible
+     * @param email Recipient's email address
+     * @param subject Message subject
+     * @param body Message body
+     */
+    function sendEmailNotification(
+        string calldata email,
+        string calldata subject,
+        string calldata body
+    ) external {
+        mailer.sendToEmailAddress(
+            email,
+            subject,
+            body,
+            msg.sender           // User pays the fee
+        );
+
+        emit EmailNotificationSent(email, body);
+    }
+
+    /**
+     * @notice Example 5: Send using pre-prepared content (gas efficient)
+     * @dev Store large content off-chain, reference by ID
+     * @param recipient User's wallet address
+     * @param mailId Reference to pre-prepared content
+     */
+    function sendPreparedContent(
+        address recipient,
+        string calldata mailId
+    ) external {
+        mailer.sendPrepared(
+            recipient,
+            mailId,
+            msg.sender,          // User pays the fee
+            false,               // No revenue sharing
+            true                 // Resolve sender to name
+        );
+    }
+
+    /**
+     * @notice Example 6: Send through webhook for custom delivery
+     * @dev Useful for integration with external notification systems
+     * @param recipient User's wallet address
+     * @param webhookId Webhook identifier
+     */
+    function sendViaWebhook(
+        address recipient,
+        string calldata webhookId
+    ) external {
+        mailer.sendThroughWebhook(
+            recipient,
+            webhookId,
+            msg.sender,          // User pays the fee
+            false,               // No revenue sharing
+            true                 // Resolve sender to name
+        );
+    }
+
+    /**
+     * @notice Authorize this contract to pay fees on behalf of users
+     * @dev Must be called before using contract-pays patterns
+     */
+    function authorizeWithMailer() external onlyOwner {
+        // This would need to be called on the Mailer contract
+        // mailer.setPermission(address(this));
+        // Note: This requires the Mailer to expose setPermission publicly
+    }
+
+    /**
+     * @notice Approve USDC spending for the Mailer contract
+     * @dev Required before sending any messages
+     * @param amount USDC amount to approve (in 6 decimals)
+     */
+    function approveUSDCForMailer(uint256 amount) external onlyOwner {
+        usdcToken.approve(address(mailer), amount);
+    }
+
+    /**
+     * @notice Withdraw any USDC held by this contract
+     * @dev Emergency function to recover funds
+     */
+    function withdrawUSDC() external onlyOwner {
+        uint256 balance = usdcToken.balanceOf(address(this));
+        require(balance > 0, "No USDC to withdraw");
+        usdcToken.transfer(owner, balance);
+    }
+}

package/contracts/interfaces/IERC20.sol

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+/**
+ * @title IERC20
+ * @notice Interface for ERC20 token standard
+ * @dev Minimal interface for USDC token interactions
+ */
+interface IERC20 {
+    /// @notice Transfer tokens from one address to another using allowance
+    /// @param from Source address
+    /// @param to Destination address
+    /// @param amount Amount to transfer
+    /// @return success True if transfer succeeded
+    function transferFrom(address from, address to, uint256 amount) external returns (bool);
+    
+    /// @notice Transfer tokens to another address
+    /// @param to Destination address
+    /// @param amount Amount to transfer
+    /// @return success True if transfer succeeded
+    function transfer(address to, uint256 amount) external returns (bool);
+    
+    /// @notice Approve another address to spend tokens on your behalf
+    /// @param spender Address authorized to spend
+    /// @param amount Amount they can spend
+    /// @return success True if approval succeeded
+    function approve(address spender, uint256 amount) external returns (bool);
+    
+    /// @notice Get the balance of an address
+    /// @param account Address to check balance for
+    /// @return balance Token balance
+    function balanceOf(address account) external view returns (uint256);
+}

package/contracts/interfaces/IMailer.sol

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+/**
+ * @title IMailer
+ * @notice Interface for the Mailer contract messaging functions
+ * @dev Use this interface to integrate Mailer messaging into your smart contracts
+ * @author Mailer Team
+ */
+interface IMailer {
+    /**
+     * @notice Send a message to a wallet address
+     * @param to Recipient wallet address
+     * @param subject Message subject line
+     * @param body Message body content
+     * @param payer Address that will pay the USDC fee
+     * @param revenueShareToReceiver If true, receiver gets 90% revenue share; if false, no revenue share
+     * @param resolveSenderToName If true, resolve sender address to name via off-chain service
+     */
+    function send(
+        address to,
+        string calldata subject,
+        string calldata body,
+        address payer,
+        bool revenueShareToReceiver,
+        bool resolveSenderToName
+    ) external;
+
+    /**
+     * @notice Send a message using pre-prepared content (referenced by mailId)
+     * @param to Recipient wallet address
+     * @param mailId Reference ID to pre-prepared message content
+     * @param payer Address that will pay the USDC fee
+     * @param revenueShareToReceiver If true, receiver gets 90% revenue share; if false, no revenue share
+     * @param resolveSenderToName If true, resolve sender address to name via off-chain service
+     */
+    function sendPrepared(
+        address to,
+        string calldata mailId,
+        address payer,
+        bool revenueShareToReceiver,
+        bool resolveSenderToName
+    ) external;
+
+    /**
+     * @notice Send a message to an email address (no wallet address)
+     * @param toEmail Email address of the recipient
+     * @param subject Message subject line
+     * @param body Message body content
+     * @param payer Address that will pay the USDC fee
+     */
+    function sendToEmailAddress(
+        string calldata toEmail,
+        string calldata subject,
+        string calldata body,
+        address payer
+    ) external;
+
+    /**
+     * @notice Send a pre-prepared message to an email address
+     * @param toEmail Email address of the recipient
+     * @param mailId Reference ID to pre-prepared message content
+     * @param payer Address that will pay the USDC fee
+     */
+    function sendPreparedToEmailAddress(
+        string calldata toEmail,
+        string calldata mailId,
+        address payer
+    ) external;
+
+    /**
+     * @notice Send a message through a webhook
+     * @param to Recipient wallet address
+     * @param webhookId Webhook identifier for delivery
+     * @param payer Address that will pay the USDC fee
+     * @param revenueShareToReceiver If true, receiver gets 90% revenue share; if false, no revenue share
+     * @param resolveSenderToName If true, resolve sender address to name via off-chain service
+     */
+    function sendThroughWebhook(
+        address to,
+        string calldata webhookId,
+        address payer,
+        bool revenueShareToReceiver,
+        bool resolveSenderToName
+    ) external;
+}