{"id":31923974,"url":"https://github.com/chainsafe/delorean-protocol","last_synced_at":"2025-10-13T23:59:27.217Z","repository":{"id":242297810,"uuid":"808930874","full_name":"ChainSafe/Delorean-Protocol","owner":"ChainSafe","description":"IPC subnet for programmable encryption to the future. Our entry for HackFS 2024","archived":false,"fork":false,"pushed_at":"2024-09-11T04:33:43.000Z","size":9171,"stargazers_count":131,"open_issues_count":3,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-02T02:53:26.036Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ChainSafe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","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":"2024-06-01T07:34:44.000Z","updated_at":"2025-09-02T10:33:51.000Z","dependencies_parsed_at":"2024-11-28T22:33:47.206Z","dependency_job_id":"0d9bb4b5-9b75-4f31-a411-a6bdcdb1fce9","html_url":"https://github.com/ChainSafe/Delorean-Protocol","commit_stats":null,"previous_names":["badboilabs/delorean-protocol","chainsafe/delorean-protocol"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ChainSafe/Delorean-Protocol","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChainSafe%2FDelorean-Protocol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChainSafe%2FDelorean-Protocol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChainSafe%2FDelorean-Protocol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChainSafe%2FDelorean-Protocol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChainSafe","download_url":"https://codeload.github.com/ChainSafe/Delorean-Protocol/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChainSafe%2FDelorean-Protocol/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279017175,"owners_count":26086019,"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","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-10-13T23:59:03.605Z","updated_at":"2025-10-13T23:59:27.203Z","avatar_url":"https://github.com/ChainSafe.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](./Delorean-Docs/assets/banner.png)\n\n![Static Badge](https://img.shields.io/badge/build_for-HackFS_2024-green)\n![GitHub License](https://img.shields.io/github/license/BadBoiLabs/Delorean-Protocol)\n\n\nAn IPC subnet for programmable encryption to-the-future.\n\nOur entry for the EthGlobal HackFS 2024 Hackathon\n\n## Overview\n\nPractical encryption to the future can be done using a blockchain in combination with witness encryption. A plaintext can is encrypted such that the decryption key is produced when a threshold of validators sign a chosen message. This is used by protocols such as tlock[^tlock] and McFLY[^mcfly].\n\nIn these protocols the message is chosen to be a block height in the future. With particular blockchains such as [DRAND](https://drand.love) it is guaranteed that the validators will sign every block height and the decryption key will be automatically generated and made public. The limitation of this is it only supports encryption to the future. No additional constraints can be placed on key generation.\n\nDelorean protocol extends this idea to allow programmable conditions for decryption key release while maintaining the same (and in some cases better) security guarantees. Users can deploy Solidity smart contracts that encode the conditions under which the network operators must generate a decryption key. \n\nSome examples might be:\n\n- Fund Raising\n    - Key is released once the contract raises some amount of funds\n- Hush Money\n    - Key is released if the contract does not receive a periodic payment\n- Dead Man Switch\n    - Key is released the contract it doesn't receive a 'heartbeat' transaction from a preauthrized account for a number of blocks\n- Encrypted Transactions / Encrypted Mempool\n- Filecoin Deal integration\n    - Key is released once a particular Filecoin deal is discontinued\n- Price Oracle integration\n    - Key is released if some asset reaches a given price\n\nBeing an IPC subnet Delorean is a fully fledged EVM chain that can also message other subnets in the wider network. This means conditions could be encoded that rely on other chains (e.g Filecoin deals).\n\nWe also developed a CLI that makes it easy to encrypt and decrypt files with keys tied to deployed condition contracts. Encryption and decryption takes place fully off-chain and does not require communication with the validators.\n\n## Architecture / How it's made\n\nDelorean is implemented as an [IPC Subnet](https://docs.ipc.space/) allowing it to be easily bootstrapped and have access to assets from parent chains (e.g. FIL). It uses CometBFT for consensus and a modified version of the FVM for execution which communicates with the consensus layer via ABCI.\n\n![](./Delorean-Docs/diagrams/arch.excalidraw.svg)\n\nThe feature of CometBFT that makes the protocol possible is the [vote extension](https://docs.cosmos.network/main/build/abci/vote-extensions) feature added in ABCI v0.38. In CometBFT validators vote on blocks to be finalized. Vote extensions allow the execution layer to enforce additional data to be included for votes to be valid. In Delorean the additional data is a BLS signature over the next tag in the queue (more detail on this later). If this signature is not included then the vote is invalid and cannot be used to finalize the block. The result is that the liveness of the chain becomes coupled to the release of these signed tags and inherits the same guarantees.\n\n### Delorean Actor\n\nDeloran adds a new actor to the FVM that stores the queue of tags and allows contracts in the FEVM to pay gas to enqueue new tags. Once a tag is added to the queue the validators MUST include a signature over it in their next vote or else they are committing a consensus violation. The block proposer combines all of the signatures from the votes into an aggregate and includes an additional transaction which writes it back to the actor state. This aggregate signature is a valid decryption key for data encrypted to this tag!\n\nA tag is defined as:\n\n```\ntag = SHA256(contractAddress || arbitaryData)\n```\n\nIt is defined this way so someone else cannot write another contract which causes your key to be released. The tag (and hence decryption key itself) is tied to the address of the contract that manages it.\n\n### Cryptography\n\nWe use the threshold BLS Identify Based Encryption algorithm of [Gailly, Melissaris and Yolan Romailler (2023)](^tlock) for encryption and decryption.\n\nEncryption is done using the tag used in combination with the validator public keys. This takes place fully-offchain and without any communication with the validators as follows:\n\n```\nciphertext = encrypt(message, aggValidatorKey, tag)\n```\n\nA decryption key is derived from a tag as:\n\n```\nkey = aggregate([sign(tag, key) for key in validatorKeys])\n```\n\nand this is what the Delorean protocol produces after the contract triggers the call to release the key.\n\n\u003e [!NOTE]  \n\u003e We are using the non-threshold variant of the algorithm for this prototype so all validators must sign. A threshold version could be implemented by having the validators perform a key generation ceremony or by using a modified protocol such as the one used in [McFLY -  Döttling et al (2023)](mcfly)\n\n## Judging Considerations\n\nDelorean builds upon the IPC subnet boilerplace provided by Protocol Labs\n\nThe work conducted during the hackathon can be viewed in [this diff](https://github.com/BadBoiLabs/Delorean-Protocol/compare/72a51df1dc5ee06474772406171ebcabdc205b69..main)\n\nThis includes:\n\n- Updating the runtime to support ABCI v0.38\n- [Developing a custom FVM actor (Delorean actor)](https://github.com/BadBoiLabs/Delorean-Protocol/blob/main/fendermint/actors/cetf/src/actor.rs)\n- [Solidity contracts to interface with actor](https://github.com/BadBoiLabs/Delorean-Protocol/blob/main/contracts/src/delorean/DeloreanAPI.sol)\n- [Modifications to runtime to implement the Delorean protocol](https://github.com/BadBoiLabs/Delorean-Protocol/blob/main/fendermint/app/src/app.rs)\n    - Extend CometBFT votes with signatures\n    - Ensure votes have valid signatures\n    - Have block producer commit aggregate signature to actor state\n- [Delorean CLI](https://github.com/BadBoiLabs/Delorean-Protocol/tree/main/fendermint/testing/delorean-cli)\n    - encrypt/decrypt\n\n## Usage Flow\n\nCreating conditionally decryptable data with Delorean can be done as follows:\n\n1. Create the Solidity contract encoding the key release conditions. This should call `DeloreanAPI.enqueueTag(\u003ctag\u003e)` only when the conditions are met.\n\n2. Deploy this contract to the Delorean subnet chain and obtain its contract address\n\n3. Encrypt the data locally using the Delorean CLI\n\n```shell\necho \"secret message\" | delorean encrypt \u003ccontract-address\u003e -o encrypted.txt\n```\n\nUnder the hood this retrieves the tag from the contract and validator aggregate BLS public keys by making RPC calls to the Delorean client\n\n4. (optional) Upload the data to a public network such as IPFS or Filecoin\n\n5. To attempt to decrypt data run the following\n\n```shell\ncat ./encrypted.txt | delorean decrypt \u003ccontract-address\u003e -o decrypted.txt\n```\n\nThis will look in the state and see if the decryption key for this data has been released. If so it will decrypt it otherwise it will error.\n\n## Running the Demo\n\n### Prerequisites\n\nOn Linux (links and instructions for Ubuntu):\n\n- Install system packages: `sudo apt install build-essential clang cmake pkg-config libssl-dev protobuf-compiler git curl`.\n- Install Rust. See [instructions](https://www.rust-lang.org/tools/install).\n- Install cargo-make: `cargo install --force cargo-make`.\n- Install Docker. See [instructions](https://docs.docker.com/engine/install/ubuntu/).\n- Install Foundry. See [instructions](https://book.getfoundry.sh/getting-started/installation).\n\nOn MacOS:\n\n- Install Xcode from App Store or terminal: xcode-select --install\n- Install Homebrew: https://brew.sh/\n- Install dependencies: brew install jq\n- Install Rust: https://www.rust-lang.org/tools/install (if you have homebrew installed rust, you may need to uninstall that if you get errors in the build)\n- Install Cargo make: cargo install --force cargo-make\n- Install docker: https://docs.docker.com/desktop/install/mac-install/\n- Install foundry: https://book.getfoundry.sh/getting-started/installation\n\nRun `make` in the root of the repo before proceeding\n\n### Steps\n\nThe demo runs against a standalone network (not a subnet) with 4 validators.\n\nTo start the testnet run the following:\n\n```shell\ncd fendermint/testing/delorean-cli/\ncargo make setup-cetf \u0026\u0026 cargo make node-1-setup \u0026\u0026 cargo make node-2-setup  \u0026\u0026 cargo make node-3-setup\n```\n\n\u003e ![INFO]\n\u003eIf you want to add the network to MetaMask the RPC is `http://localhost:8545` and the Chain ID is `2555887744985227`\n\nWait a few minutes to build the node docker images and to set up the network. It is comprised of a number of docker containers which can be viewed in the docker desktop application or by running `docker ps`\n\nView the logs of one of the validator nodes by running\n\n```shell\ncargo make follow-logs\n```\n\nin a separate shell\n\n---\n\nInstall the CLI with\n\n```shell\ncargo install --path .\n```\n\nThen setup our demo with the following:\n\n```shell\ncargo make register-bls-keys  \ncargo make deploy-demo-contract\n```\n\nSet env vars for the deployed contract address to use in future commands\n\n```shell\nexport CONTRACT_ADDRESS=\"0x.....\"\nexport DELORIAN_SECRET_KEY=\"./test-data/keys/volvo.sk\"\n```\n\n### Encrypt\n\nThe encrypt command takes a stream on std-in and encrypts it. Lets pipe a message to have it encrypted\n\n```shell\necho 'Where we are going, we dont need centralized key registries!' | delorean-cli encrypt $CONTRACT_ADDRESS -o encrypted.txt \n```\n\nTake a look at the encrypted output by running `cat encrypted.txt`. It uses the [age](https://github.com/FiloSottile/age) encryption specification to encrypt large plaintexts.\n\n### Trigger Key Generation\n\nNow to trigger the decryption key generation.\n\nDeposit at least 88 FIL to the contract to enable the key release conditions\n\n```shell\n```\n\nThen call the `releaseKey` method \n\n```shell\ndelorean-cli call-release-keys $CONTRACT_ADDRESS\n```\n\n### Decrypt\n\nThe decrypt command can now be used to retrieve the generated key from the store and decrypt our data\n\n```shell\ncat ./encrypted.txt | delorean-cli decrypt $CONTRACT_ADDRESS\n```\n\n## Security Considerations\n\nThe security of the protocol relies on the following. Where possible these are compared with DRAND/tlock\n\n- The 2/3 of the network validators have not colluded to produce decryption keys in secret\n    - This is the same assumption as tlock although here it is slightly better. In tlock because the tags are block heights and hence predictable if the operators ever collude they can derive all possible future keys. In Delorean they can only derive all keys for known tags.\n\n- The protocol depends on the underlying security of the Threshold BLS encryption scheme of [^tlock]\n\n- Liveness of the key release inherits the same liveness guarantees as CometBFT. That is less than 1/3 of the total weight of the validator set is malicious or faulty\n\n## Comparisons with existing protocols\n\n#### tlock + DRAND\n\nThis scheme only supports encryption-to-the-future without programmable conditions. The underlying cryptography used is the same and inherits the same limitations (e.g. to support a threshold of signers these signers must collaborate to produce a threshold key)\n\n#### McFLY\n\nAs described in the paper this scheme also only supports non-programmable encryption-to-the-future. This protocol has the benefit that the signers need never communicate and encryption to a threshold signature can still be done by providing all signing keys at encryption time. This is much more flexible and allows validators to enter and leave the network. \n\nWe intend to move to using this cryptography once an implementation is complete (which we are working on)\n\n#### LIT Protocol\n\nLIT is the most similarly featured existing protocol. It supports programmable encryption with conditions defined as Javascript code that is run by the signers of the network. This supports fetching data from supported blockchains and oracles.\n\nDelorean differs from LIT by being an open network with a permissionless validator set, and by having decryption conditions defined in the blockchain runtime itself rather than relying on external block data providers.\n\n## Future Work\n\nDelorean becomes particularly powerful when paired with ZKPs. This would allow the published ciphertext to have accompanying proofs about its content (e.g. that it will decrypt to a private key corresponding to a public key).\n\nThat way you could be certain if the keys are released after some funding goal is met that the data will actually decrypt. Even more useful would be if this can be extended to arbitrary ZK proofs about the encrypted data itself. This would allow all kinds of interesting applications (e.g. encrypted transactions).\n\n## References\n\n- [^tlock]: [tlock: Practical Timelock Encryption from Threshold BLS](https://eprint.iacr.org/2023/189)\n- [^mcfly]: [McFly: Verifiable Encryption to the Future Made Practical](https://eprint.iacr.org/2022/433)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchainsafe%2Fdelorean-protocol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchainsafe%2Fdelorean-protocol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchainsafe%2Fdelorean-protocol/lists"}