[TOC]

# Introduction

This document presents the completion of the second and final milestone for the Safe Anonymous Mail Module (SAMM) grant from Aztec, detailing the development of key components: the user interface (UI) and the Relayer backend. Our efforts this phase focused on integrating these components with the existing on-chain SAMM components to deliver a functional MVP that aligns with the proposed technical specifications and grant requirements.

## Demonstration
{%youtube ImHRWitgoE0 %}

Here is a video demonstration showcasing the complete workflow of the SAMM module, from its creation and configuration to its usage by members. The live UI demo is accessible at [https://samm-demo.oxor.io](https://samm-demo.oxor.io).

## Project Progress Report

Milestone 2 focused on the development and integration of two key system components:

- [Relayer Backend](https://github.com/oxor-io/samm-backend): The backend infrastructure responsible for handling emails, verifying DKIM signatures, generating ZK proofs, and interacting with the blockchain.
- [User Interface](https://github.com/oxor-io/samm-frontend): A user-friendly interface for module creation and monitoring of SAMM activities, ensuring smooth interaction with the system.

Details about each section and their implementations are described further in this document. Additionally, significant progress was made in finalizing the technical and user documentation to support the system’s deployment and usability.

All smart contracts, circuits, and relayer backend code has been successfully audited by Nethermind and OpenZeppelin teams. For more details, refer to the [Audit](#audit) section.

With the successful completion of these components, the SAMM project has reached the stage of a MVP, providing a functional and integrated solution ready for further testing and refinement.

## References

- [Project Proposal](https://github.com/orgs/noir-lang/discussions/5813)
- [SAMM Technical Documentation](https://www.notion.so/SAMM-technical-requirements-7c42604654ba408ea68176fb609cf04b?pvs=21)
- [SAMM User Guide](https://www.notion.so/SAMM-User-Guide-77d45b365c8f4766b9c4b241f388772a?pvs=21)
- [Milestone 1 Report](https://www.notion.so/Safe-Anonymous-Mail-Module-Grant-Milestone-1-Report-12d429d24bc4809c8dfdfed3c5e5d995?pvs=21)
- [Live UI Demo](https://samm-demo.oxor.io)

Repositories:
- [SAMM Smart Contracts](https://github.com/oxor-io/samm-contracts)
- [SAMM Circuits](https://github.com/oxor-io/samm-circuits)
- [SAMM Relayer Backend](https://github.com/oxor-io/samm-backend)
- [SAMM UI](https://github.com/oxor-io/samm-frontend)

Audit Reports:
- [OpenZeppelin Audit Report](https://github.com/oxor-io/samm-contracts/blob/master/audits/OpenZeppelin-Audit-Report-07-03-2025.pdf)
- [Nethermind Audit Report](https://github.com/oxor-io/samm-contracts/blob/master/audits/Nethermind-Security-Review-Report-20-03-2025.pdf)

---

# Relayer Backend Infrastructure

An [open-source solution](https://github.com/zkemail/email-wallet/tree/main/packages/relayer) by ZK Email is used as the basis for our off-chain relayer infrastructure. We have adapted this solution for our project.


It consists of the following main components:

- **IMAP Server**: The entry point for emails, which the Relayer monitors for incoming messages that trigger blockchain transactions.
- **Relayer**: The core service that listens for emails from the IMAP server, communicates with the Prover to create proofs, and then sends the validated transactions to the blockchain.
- **Prover**: A separate process that the Relayer relies on to create zk proofs.
- **Database**: A database to store the relayer's state, including lists of wallets, emails, transactions, proofs, and so on.
- **API Service**: This service is designed to transfer transaction information from the database to the user interface.

It's important to highlight the privacy assumptions of all Relayer infrastructure. In fact, all these off-chain components handle privacy data about members' approvals. It is assumed that no external parties have access to this infrastructure. And it should be considered that if a third-party Relayer infrastructure is used, privacy data is accessible to the provider of this infrastructure.

## IMAP Server

The IMAP server manages email storage and retrieval.

The Relayer service connects to the IMAP server to fetch incoming emails from members. If there are no new messages, it waits passively for notifications from the IMAP server.

The project supports Gmail, using Google’s IMAP server. To connect, an OAuth2 `access_token` is required. Detailed instructions are available in [Google's official documentation](https://developers.google.com/identity/protocols/oauth2/web-server#python_1).

If you prefer using a different email provider, you need to adjust the IMAP server credentials in environment variables and configure the authentication process by modifying the following functions:

- `relayer/imap_client.py::authenticate_oauth_token`
- `relayer/imap_client.py::fetch_access_token`

## Relayer

The Relayer is the backend’s core component. It manages IMAP server interactions, email processing, Prover subprocess execution, transaction data storage, and member notifications.

Emails retrieved from the IMAP server fall into two categories:

- **Initial Message:** Initiates a new transaction. The email body contains transaction details.
- **Approval Message:** Confirms an existing transaction. The email body is irrelevant.

Both types must include the transaction hash in the subject line.

If the hash from the incoming email is unknown, the Relayer treats it as an `Initial Message`, extracting transaction data from the email body. If the hash already exists in the database, the Relayer processes it as an `Approval Message`, registering the sender's approval.

The sender of an `Initial Message` also implicitly approves the created transaction. The Relayer generates a zk-proof for every approval, stores the result, and processes the transaction if the approval count surpasses the threshold.

> Note: To execute the transaction on the blockchain, the Relayer’s address must hold enough funds to cover gas fees.
>

Once email processing concludes, the Relayer notifies SAMM members:

- About new transactions for `Initial Messages`
- About completed transactions if the approval threshold is reached.

## Prover

The Prover generates zk-proofs for transaction confirmations by running subprocesses.

Depending on the DKIM signature size, the Prover uses one of the following circuit files:

- `relayer/target/samm_1024.json`
- `relayer/target/samm_2048.json`

The Prover follows two main steps:

1. **Generating `witness.gz`:** Based on member data and the circuit file, the Prover runs the script `relayer/scripts/generateWitness.js` in a subprocess.
2. **Calculating the zk-proof:** Using the generated `witness.gz`, the Prover runs the command:

bb prove_ultra_keccak_honk -b ./target/samm_2048.json -w ./target/witness.gz -o -

The generated proof is then saved to the database by the Relayer.

## Database

The SAMM system uses PostgreSQL as its database to manage data for the Relayer and API services. It stores information on SAMM modules, members, transactions, and approvals, ensuring seamless backend functionality. The database supports essential operations such as tracking transaction status, managing module configurations, and verifying user roles.

To ensure scalability and security, the database integrates directly with the Relayer for processing transactions and with the API service for exposing relevant data to the user interface.

## API Service

The API service is built with the FastAPI framework. Available endpoints are listed at `/docs`.

Authentication follows the OAuth2 protocol with JWT support.

Two roles exist: `member` and `owner`.

### Becoming an Owner

To gain `owner` status, a user must send a signed message using the wallet that owns the safe wallet associated with SAMM creation.

### Owner Permissions

- Create and manage SAMMs
- Edit member lists

When new members are added, the service creates accounts and sends passwords to them, granting them `member` roles.

### Member Permissions

- View personal transactions, approvals, and connected SAMMs.

---

# Module User Interface

The UI is implemented as a Safe React App built on the Safe App SDK. This application can be [added as a custom app](https://help.safe.global/en/articles/40859-add-a-custom-safe-app) in the standard Safe wallet UI. You can access the deployed version by following this [link](https://samm-demo.oxor.io/).

The UI is available only to SAMM members' emails or Safe(connected to SAMM) owners and allows them to:

- Monitor the status of each SAMM transaction.
- Generate tx data for the Initiation email.
- Generate tx data for changing SAMM parameters (these transactions will be executed through the classic Safe Wallet UI on behalf of associated Safe owners).


## Types of Users

The application provides **two distinct user interfaces** based on the role of the user: **Members** and **Safe Owners**. Both interfaces are served from the same repository and domain, but their functionality and integration vary:

### Member Interface

This is a simple webpage accessible to SAMM members via email-based authentication.

- **Functionality**:
- **Tx Helper**: Generate message data for transactions.
- **Pending Transactions**: View and approve transactions awaiting confirmation.
- **Confirmed Transactions**: View completed transactions with their success or failure status.
- **Technical Details**:
- Members access the application via a public-facing URL (https://samm-demo.oxor.io/).
- Member-specific UI and functionality are rendered based on the absence of Safe-specific configurations in the user environment.

### Safe Owner Interface

This is a custom app embedded within the Safe Wallet as custom app. It allows Safe Owners to manage the SAMM module directly inside the Safe Wallet environment.

- **Functionality**:
- Create and manage SAMM modules.
- Manage settings, such as module parameters and permissions.
- Add or remove members.
- Access all member functionalities, except the ability to approve the transaction by clicking on the button
- **Technical Details**:
To integrate with the Safe Wallet:
- A `manifest.json` file is included in the `public` folder. This file specifies the app metadata.
- Special headers are added in the `next.config.js` file to allow embedding the app in the Safe Wallet's iframe.
- App is wrapped into `SafeProvider`component from the Safe SDK to interact with Safe-specific APIs and verify the environment.
- The app detects the user type using `SafeSDK`. A hook (`useSafeInfo`) checks if the app is running inside the Safe Wallet and sets a state variable accordingly:

## Authorization

The authorization mechanism differs between Members and Safe Owners:

### For Safe Owners

- **Process**:
1. Owners sign a message using their wallet.
2. The signed data is sent to the backend, where it is validated and an authorization token is issued.
3. This token allows interaction with protected endpoints in the API.
- **Implementation**:
- The signature is generated using EIP-712 typed data.
- The backend verifies the signature using the parameters of the signed message passed to it: chainId, sammAddress, signerAddress and timestamp.

### For Members

- **Process**:
1. Members log in by submitting their **email** and **password** through a form.
2. The backend verifies the credentials and issues an authorization token.
3. This token is used to interact with protected endpoints in the API.
- **Implementation**:
- Simple form submission on the frontend sends data to the backend for validation.

## Transaction Helper

The **Transaction Helper** is a critical feature for generating transaction data and message hashes required to interact with the SAMM module.

### Nonce Retrieval

The nonce is retrieved directly from the SAMM smart contract using the `getNonce` function.

### Message Hash Generation

The message hash ensures the integrity of transaction data and serves as a unique identifier.

The hash is computed using `keccak256`:

const encodedMsg = encoder.encode(
    ['address', 'uint256', 'bytes32', 'uint8', 'uint256', 'uint256', 'address', 'uint256'],
    [to, value, calldataHash, operation, nonce, deadline, sammAddress, chainId]);
return keccak256(encodedMsg);

**Parameters Used**:

- `to`: Target contract address.
- `value`: Ether value to transfer.
- `calldata`: Encoded data of the function to be called.
- `operation`: Operation type (`0` for CALL, `1` for DELEGATECALL).
- `nonce`: Transaction nonce retrieved from the contract.
- `deadline`: Expiration time for the transaction.
- `sammAddress`: Address of the SAMM contract.
- `chainId`: ID of the blockchain network.

The final message hash is encoded into Base64 for further usage.

---

# Security Audits

Our implementations of Noir circuits and smart-contracts has successfully passed two comprehensive security audits by OpenZeppelin and Nethermind. Conducted as part of the grant and with the support of Aztec, these audits provided invaluable insights that enabled us to address all concerns, ensuring our system is secure and fully compliant with industry best practices. With these audits complete, our code is now ready for further deployment on the testnet, paving the way for our continued development.

## OpenZeppelin's Audit

The OpenZeppelin team conducted a comprehensive security audit of the Oxorio SAMM Module, reviewing the smart contracts and circuits implementations. Their assessment identified 3 high, 1 medium and several low-severity issues, covering aspects such as security vulnerabilities, anonymity risks, and code optimizations. The most critical findings involve unconstrained DKIM signatures, potentially unprovable valid emails, and front-running risks that could lead to a DoS attack on multisig wallets.

Following the audit, our team worked diligently to address the identified concerns, ensuring that all issues were either fully resolved or formally acknowledged. These improvements have strengthened the security and reliability of our system, bringing it in line with best practices and ensuring a higher level of protection for users.

You can find the final audit report here: [OpenZeppelin Audit Report](https://github.com/oxor-io/samm-contracts/blob/master/audits/OpenZeppelin-Audit-Report-07-03-2025.pdf)

## Nethermind's Audit

The Nethermind team conducted an in-depth review of both our Noir circuits and Solidity smart contracts. They audited our implementation with a focus on aspects critical to safeguarding user funds and ensuring transaction integrity. Notably, they identified a critical issue with the proof verification process — specifically, a flaw that could cause the function to revert when handling multiple proofs — as well as concerns regarding the specification of operation types and the validation of secrets, which are essential for maintaining secure and anonymous transactions.

Working closely with the Nethermind team, we addressed every concern by either fully resolving them or formally acknowledging the issues. As a result, our code is now significantly more secure, ensuring the highest level of protection for our users and their funds.

The final audit report is available here: [Nethermind Audit Report](https://github.com/oxor-io/samm-contracts/blob/master/audits/Nethermind-Security-Review-Report-20-03-2025.pdf)

# Challenges

During the development and integration phases of Milestone 2, the team encountered several challenges that impacted the timeline and required additional resources to resolve:

## Additional Authorization Flow for SAMM Owners

During the development of the SAMM User Interface, we recognized the need for a dual-layered authorization approach to accommodate different user roles within the system. Initially, SAMM members were authenticated using a standard login/password mechanism. However, this method proved inadequate for SAMM owners, who require access to the system prior to the module’s creation. To resolve this, we introduced a key-based authorization system, allowing owners to authenticate by signing a request. This enhancement ensures that owners can interact with the UI and perform necessary actions from the outset, adding a layer of flexibility and security that aligns with the governance structure of multisig operations. This adjustment introduced additional complexity to the authorization flow, requiring extensive development and testing to implement a secure, user-friendly solution that maintains our strict privacy standards.

## DKIM Signature Verification Issues

The verification of DKIM signatures emerged as a major blocker, with emails consistently failing validation despite signatures and public keys matching what the relayer received. After in-depth debugging, the issue was traced to specific formatting requirements in the email header for the `verify_dkim_signature` function. Adjustments to the header construction resolved the issue, allowing smooth integration of DKIM verification into the relayer and proof generation workflows.

## Debugging Proof Generation and Deployment

Considerable time was spent troubleshooting the proof generation process using Barretenberg calls from Python, particularly when deploying this setup on a separate server within a Docker container. Ensuring reliable performance and seamless integration with the overall system proved to be a significant challenge.

A key obstacle was the need to construct the witness and generate zk proofs on the backend. While using JS libraries for both tasks would have been ideal, we discovered that `@noir-lang/backend_barretenberg 0.35.0` does not support generating proofs for smart contract verification (keccak proofs). This limitation required us to adapt our approach by installing the `bb cli` within our Docker container and leveraging the `bb prove_ultra_keccak_honk` command to generate keccak proofs, ensuring compatibility with our verification pipeline.

Despite these challenges, the team has made substantial progress, resolving key blockers and improving the robustness of the SAMM system. These efforts have not only ensured a stable proof generation pipeline but also provided valuable insights into optimizing the overall integration process. Moving forward, we aim to refine deployment workflows, enhance system observability, and improve automation around proof generation to further streamline development and ensure long-term maintainability.

# Future Steps

Having successfully completed all milestones under this grant, we have demonstrated the viability and operational functionality of the SAMM principles. Moving forward, our focus will be on refining and enhancing the existing prototype to achieve a polished, fully integrated product suitable for the Safe Apps catalog. Collaborating closely with SafeDAO, we aim to make the SAMM a staple application within their ecosystem, ensuring seamless integration and enhanced usability.

We are also planning to establish a developer community around SAMM. This community will help test and refine the module, focusing on security enhancements and usability improvements. A key part of our community engagement strategy involves collaborating with the Safe Builders community. By involving them, we hope to gather critical feedback and assistance in evolving our prototype into a fully developed product. This collaborative approach will ensure that SAMM is robust, secure, and aligned with user needs in the Safe ecosystem.

# Conclusion

The completion of all SAMM grant milestones represents a key advancement in the development of secure and private multisig wallet management solutions. This report demonstrates the successful implementation of the final components — an intuitive user interface and a robust Relayer backend—which together form a fully operational MVP. These developments fulfill all grant deliverables and align with the project’s technical and functional objectives.

Through the SAMM MVP, we have showcased the practicality and functionality of using zero-knowledge proofs and secure email communications for multisig wallet operations. These achievements lay a solid foundation for future refinements and broader adoption within the Safe ecosystem, emphasizing our commitment to enhancing privacy, security, and usability for blockchain users.

For any questions or further collaboration inquiries, feel free to contact us at [[e-mail]](mailto:[e-mail]).