cairoeth / emily

🔒💬 A protocol for credible commitments on Ethereum.

🪄 Emily: A Protocol for Credible Commitments

Emily is a specialized protocol designed to facilitate and manage credible commitments on Ethereum. This document provides an in-depth overview of Emily's architecture, functionalities, and integration methods.

Introduction

In the evolving landscape of blockchain technology, ensuring credible commitments is paramount. Emily addresses this need by offering a structured and efficient way to create and manage these commitments on Ethereum. This protocol not only enhances the reliability of commitments but also integrates seamlessly with existing Ethereum standards.

For a hands-on experience, explore the PBS commitment sample.

Key Features

1. Commitment Manager

A central smart contract that:

• Enables EVM addresses to make new commitments.
• Validates if a provided value satisfies some user's commitments.

2. Commitment Structure

Each commitment comprises:

• Target: Defines the commitment's subject, akin to 'scope' in constraint satisfaction problems.
• Indicator Function: A function that yields '1' if a commitment is satisfied by a specific value, and '0' otherwise.

struct Commitment {
    uint256 timestamp;
    function (bytes memory) external view returns (uint256) indicatorFunction;
}

The indicator function delineates the values that fulfill the commitment.

3. Commitment Library (CommitmentsLib)

A library equipped with methods to:

• Evaluate if a value satisfies to an array of commitments.
• Determine the finalization status of a commitment.

library CommitmentsLib {
    function areCommitmentsSatisfiedByValue(Commitment[] memory commitments, bytes calldata value) public view returns (bool);
    function isFinalized(Commitment memory commitments) public view returns (bool finalized);
}

Commitments are currently considered finalized based on a time criterion post-inclusion. A more robust approach might involve the protocol checking a proof for the commitment's finalization.

4. Resource Management

Given the gas-based operation of the EVM, resource management is crucial. Emily assigns a predetermined gas amount for evaluating any user's commitment array, ensuring a cap on computational resources and safeguarding verifiers from gas-griefing attacks.

Integration Guide

Incorporating Emily in Smart Contracts

To enforce commitments, smart contracts should inherit from Screener.sol and use the Screen modifier. This ensures user actions align with their commitments. When a function importing Screen is invoked, the Screen modifier activates, prompting the Commitment Manager to verify the user's commitments. The Commitment Manager then collaborates with the Commitment Library to assess the commitments. If they are met, the function proceeds; otherwise, it reverts.

sequenceDiagram
		participant Screener
		participant CommitmentManager
		participant CommitmentsLib
		participant SampleCommitment

		note over Screener: Screen modifier is called
		critical
		Screener->>CommitmentManager: areAccountCommitmentsSatisfied
		CommitmentManager->CommitmentManager: get account's commitments for target
		note over CommitmentManager: gas usage limit set for checking commitments
		CommitmentManager->>CommitmentsLib: areCommitmentsSatisfiedByValue

		loop For each commitment
				alt Commitment is finalized
						critical
								CommitmentsLib->>SampleCommitment: call commitment's indicator fun
						option Commitment is satisfied
								SampleCommitment->>CommitmentsLib: return 1
						option Commitment is not satisfied
								SampleCommitment->>CommitmentsLib: return 0
						end
				else Commitment is not finalized
						CommitmentsLib-->CommitmentsLib: ignore commitment
				end
		end
		option All commitments returned 1
				note left of CommitmentsLib: all commitments are satisfied
				CommitmentsLib->>Screener: return true
		option A commitment returned 0
				note left of CommitmentsLib: not all commitments are satisfied
				CommitmentsLib->>Screener: return false
				Screener-->Screener: revert
		end

Account Abstraction (ERC4337)

Emily can be integrated into ERC4337 accounts to screen user operations, ensuring they meet the sender's commitments. The sample below showcases the integration process, emphasizing the Screen modifier's role.

/**
* validate signature of a single userOp
* This method is called after EntryPoint.simulateValidation() returns an aggregator.
* First it validates the signature over the userOp. then it return data to be used when creating the handleOps:
* @param userOp the userOperation received from the user.
* @return sigForUserOp the value to put into the signature field of the userOp when calling handleOps.
*    (usually empty, unless account and aggregator support some kind of "multisig"
*/

function validateUserOpSignature(UserOperation calldata userOp)
    external
    view
    Screen(userOp.sender, this.validateUserOpSignature.selector, abi.encode(userOp))
    returns (bytes memory sigForUserOp)
{
    uint256[2] memory signature = abi.decode(userOp.signature, (uint256[2]));
    uint256[4] memory pubkey = getUserOpPublicKey(userOp);
    uint256[2] memory message = _userOpToMessage(userOp, _getPublicKeyHash(pubkey));

    require(BLSOpen.verifySingle(signature, pubkey, message), "BLS: wrong sig");
    return "";
}

Token Bound Accounts (ERC6551)

Emily's commitment-enforcing logic can be applied to token-bound accounts. The modification in the executeCall function ensures that any executed call by the account meets its commitments.

/// @dev executes a low-level call against an account if the caller is authorized to make calls
function executeCall(address to, uint256 value, bytes calldata data)
    external
    payable
    onlyAuthorized
    onlyUnlocked
    Screen(address(this), this.executeCall.selector, abi.encode(to, value, data))
    returns (bytes memory)
{
    emit TransactionExecuted(to, value, data);

    _incrementNonce();

    return _call(to, value, data);
}

Contribute & Feedback

Your insights can shape the future of this initiative. Feel free to raise an issue, suggest a feature, or even fork the repository for personal tweaks. If you'd like to contribute, please fork the repository and make changes as you'd like. Pull requests are warmly welcome. Things below are highly desired:

• Support the creation of commitments without gas costs through EIP712 signatures.
• Allow bundling of multiple commitments for simultaneous submission.

For questions and feedback, you can also reach out via Twitter.