{"id":15642003,"url":"https://github.com/0xfuturistic/emily","last_synced_at":"2025-04-19T13:48:02.827Z","repository":{"id":184965680,"uuid":"672763624","full_name":"0xfuturistic/emily","owner":"0xfuturistic","description":"🔒💬 A protocol for credible commitments.","archived":false,"fork":false,"pushed_at":"2024-02-02T11:59:22.000Z","size":6735,"stargazers_count":75,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-29T08:22:36.622Z","etag":null,"topics":["commitments","ethereum","pepc","smart-contracts"],"latest_commit_sha":null,"homepage":"","language":"Solidity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xfuturistic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-31T05:43:45.000Z","updated_at":"2025-03-22T07:24:59.000Z","dependencies_parsed_at":"2024-02-02T12:30:24.810Z","dependency_job_id":"3e29040b-3d59-48c8-a8df-cfb65c255985","html_url":"https://github.com/0xfuturistic/emily","commit_stats":null,"previous_names":["0xfuturistic/cautious-goggles","0xfuturistic/emily"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xfuturistic%2Femily","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xfuturistic%2Femily/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xfuturistic%2Femily/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xfuturistic%2Femily/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xfuturistic","download_url":"https://codeload.github.com/0xfuturistic/emily/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249706878,"owners_count":21313711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["commitments","ethereum","pepc","smart-contracts"],"created_at":"2024-10-03T11:53:22.401Z","updated_at":"2025-04-19T13:48:02.802Z","avatar_url":"https://github.com/0xfuturistic.png","language":"Solidity","funding_links":[],"categories":[],"sub_categories":[],"readme":"# :magic_wand: Emily: A Protocol for Credible Commitments\n\nEmily 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.\n\n![Alt Text](cover.png)\n\n## **Introduction**\n\nIn 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.\n\nFor a hands-on experience, explore the [PBS commitment sample](src/samples/CommitmentPBS.sol).\n\n## **Key Features**\n\n### **1. Commitment Manager**\nA central smart contract that:\n- Enables EVM addresses to make new commitments.\n- Validates if a provided value satisfies some user's commitments.\n\n### **2. Commitment Structure**\nEach commitment comprises:\n- **Target**: Defines the commitment's subject, akin to 'scope' in constraint satisfaction problems.\n- **Indicator Function**: A function that yields '1' if a commitment is satisfied by a specific value, and '0' otherwise.\n```solidity\nstruct Commitment {\n    uint256 timestamp;\n    function (bytes memory) external view returns (uint256) indicatorFunction;\n}\n```\nThe indicator function delineates the values that fulfill the commitment.\n\n### **3. Commitment Library (CommitmentsLib)**\nA library equipped with methods to:\n- Evaluate if a value satisfies to an array of commitments.\n- Determine the finalization status of a commitment.\n```solidity\nlibrary CommitmentsLib {\n    function areCommitmentsSatisfiedByValue(Commitment[] memory commitments, bytes calldata value) public view returns (bool);\n    function isFinalized(Commitment memory commitments) public view returns (bool finalized);\n}\n```\nCommitments 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.\n\n### **4. Resource Management**\nGiven 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.\n\n## **Integration Guide**\n\n### **Incorporating Emily in Smart Contracts**\nTo 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.\n\n```mermaid\nsequenceDiagram\n\t\tparticipant Screener\n\t\tparticipant CommitmentManager\n\t\tparticipant CommitmentsLib\n\t\tparticipant SampleCommitment\n\n\t\tnote over Screener: Screen modifier is called\n\t\tcritical\n\t\tScreener-\u003e\u003eCommitmentManager: areAccountCommitmentsSatisfied\n\t\tCommitmentManager-\u003eCommitmentManager: get account's commitments for target\n\t\tnote over CommitmentManager: gas usage limit set for checking commitments\n\t\tCommitmentManager-\u003e\u003eCommitmentsLib: areCommitmentsSatisfiedByValue\n\n\t\tloop For each commitment\n\t\t\t\talt Commitment is finalized\n\t\t\t\t\t\tcritical\n\t\t\t\t\t\t\t\tCommitmentsLib-\u003e\u003eSampleCommitment: call commitment's indicator fun\n\t\t\t\t\t\toption Commitment is satisfied\n\t\t\t\t\t\t\t\tSampleCommitment-\u003e\u003eCommitmentsLib: return 1\n\t\t\t\t\t\toption Commitment is not satisfied\n\t\t\t\t\t\t\t\tSampleCommitment-\u003e\u003eCommitmentsLib: return 0\n\t\t\t\t\t\tend\n\t\t\t\telse Commitment is not finalized\n\t\t\t\t\t\tCommitmentsLib--\u003eCommitmentsLib: ignore commitment\n\t\t\t\tend\n\t\tend\n\t\toption All commitments returned 1\n\t\t\t\tnote left of CommitmentsLib: all commitments are satisfied\n\t\t\t\tCommitmentsLib-\u003e\u003eScreener: return true\n\t\toption A commitment returned 0\n\t\t\t\tnote left of CommitmentsLib: not all commitments are satisfied\n\t\t\t\tCommitmentsLib-\u003e\u003eScreener: return false\n\t\t\t\tScreener--\u003eScreener: revert\n\t\tend\n```\n\n### **Account Abstraction (ERC4337)**\nEmily 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.\n```solidity\n/**\n* validate signature of a single userOp\n* This method is called after EntryPoint.simulateValidation() returns an aggregator.\n* First it validates the signature over the userOp. then it return data to be used when creating the handleOps:\n* @param userOp the userOperation received from the user.\n* @return sigForUserOp the value to put into the signature field of the userOp when calling handleOps.\n*    (usually empty, unless account and aggregator support some kind of \"multisig\"\n*/\n\nfunction validateUserOpSignature(UserOperation calldata userOp)\n    external\n    view\n    Screen(userOp.sender, this.validateUserOpSignature.selector, abi.encode(userOp))\n    returns (bytes memory sigForUserOp)\n{\n    uint256[2] memory signature = abi.decode(userOp.signature, (uint256[2]));\n    uint256[4] memory pubkey = getUserOpPublicKey(userOp);\n    uint256[2] memory message = _userOpToMessage(userOp, _getPublicKeyHash(pubkey));\n\n    require(BLSOpen.verifySingle(signature, pubkey, message), \"BLS: wrong sig\");\n    return \"\";\n}\n```\n\n### **Token Bound Accounts (ERC6551)**\nEmily'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.\n```solidity\n/// @dev executes a low-level call against an account if the caller is authorized to make calls\nfunction executeCall(address to, uint256 value, bytes calldata data)\n    external\n    payable\n    onlyAuthorized\n    onlyUnlocked\n    Screen(address(this), this.executeCall.selector, abi.encode(to, value, data))\n    returns (bytes memory)\n{\n    emit TransactionExecuted(to, value, data);\n\n    _incrementNonce();\n\n    return _call(to, value, data);\n}\n```\n\n## Contribute \u0026 Feedback\nYour 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:\n- Support the creation of commitments without gas costs through EIP712 signatures.\n- Allow bundling of multiple commitments for simultaneous submission.\n\nFor questions and feedback, you can also reach out via [Twitter](https://twitter.com/0xfuturistic).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xfuturistic%2Femily","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xfuturistic%2Femily","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xfuturistic%2Femily/lists"}