README
¶
🔌 Preconfirmations
Preconfirmation protocol allowing users to get sub-second transaction confirmations on Ethereum.
This is experimental software and is provided on an "as is" and "as available" basis. We do not give any warranties and will not be liable for any losses incurred through any use of this code base.
🌱 Background
Ethereum preconfirmations, or "preconfs" for short, are a proposed mechanism to enable faster transaction confirmation and improve the user experience on Ethereum, and subsequently, layer 2 rollups and validiums. The key idea is to have Ethereum block proposers, known as "preconfers," issue signed promises to users guaranteeing that their transactions will be included and executed within a certain timeframe. Users pay a tip to preconfers for this service. By acquiring preconf promises from upcoming block proposers, users can get assurance of speedy execution, with latencies as low as 100ms.
This project leverages EigenLayer as the key piece of infrastructure to secure preconfer guarantees via a slashing mechanism. Operators that run the AVS software (preconf-operator) on top of EigenLayer must be block proposers that can include preconfirmation transactions. If preconfirmation promises by operators are not fulfilled, they are subject to on-chain slashing with proofs, verified with Relic Protocol.
In order to match users with preconfers, the preconf-share middleware acts as a matchmaker, receiving user requests with hints that are gossiped to operators. Operators can decide to promise a preconfirmation or not based on hints and tip. Promises are ranked by preconf-share according to the user's validation preferences (desired block, etc).
As preconf-share requires users to pass arguments and extra parameters, rpc is a JSON-RPC wrapper that simplifies this interaction for usage on wallets (like Metamask).
Read more here.
🧱 Structure
preconf-share — "Matchmaker middleware that connects user requests with block proposers"
├─ preconshare — "Main backend to receive requests, gossip hints, rank preconfirmations, and publish signed preconfirmations"
preconf-operator — "AVS (Actively Validated Services) infrastructure that receives and reponds to preconfirmation requests"
├─ core — "Configuration and utilities to interact with on-chain smart contracts"
├─ receiverapi — "Endpoint for preconf-share callback to receive and include raw transactions"
rpc — "JSON-RPC wrapper on top of preconf-share for wallets"
├─ cmd — "Launcher of components to run the RPC server and decode transactions"
├─ server — "Logic for request handlers, processors, and forwarders"
contracts
├─ PreconfChallengeManager — "Manager that allows to raise and resolves challenges for signed preconfirmations"
├─ PreconfServiceManager — "Primary entrypoint for procuring services for preconfirmations"
👷 Setup
Requires Go 1.18+, Docker and Foundry.
git clone https://github.com/cairoeth/preconfirmations.git
cd preconfirmations
make build-all
🔧 Usage
To run the protocol, you must start the following components:
anvil: Local network with EigenLayer and preconfirmation contracts.preconf-share: Middleware software. Requires network.preconf-operator: AVS software. Requires network andpreconf-share.rpc: JSON-RPC wrapper (optional). Requirespreconf-share.
You can run all the protocol components concurrently with:
make run-all
Alternatively, you can run each component individually:
Anvil
Anvil (part of Foundry), creates a local testnet node for deploying and testing smart contracts. You can start it with the state that already contains the required contracts, or manually deploy them using the script.
To run with the pre-defined state:
make run-anvil
Preconf-Share
Preconf-Share is the middleware that connects users with block proposers. It receives user requests, gossips hints, ranks preconfirmations, and publishes signed preconfirmations. You can read more here.
make run-share
Preconf-Operator
Preconf-Operator is the AVS infrastructure that receives and responds to preconfirmation requests. It interacts with on-chain smart contracts to provide preconfirmation services. You can read more here.
make run-operator
RPC
RPC is a JSON-RPC wrapper on top of Preconf-Share for wallets. It simplifies the interaction for users to pass arguments and extra parameters.
make run-rpc
🧪 Test
After running all the components, make sure to wait around 10 seconds for the AVS sofware to register the operator. Once everything is ready, you can test the protocol with the JSON-RPC wrapper, or by running the Python example. You must have Python installed:
# Install dependencies
pip install -r requirements.txt
python test_tx.py
This example generates a random transaction that transfers Ether to itself. Check the protocol logs to see how the transaction is preconfirmed and included in the next block.
🙏🏼 Acknowledgements
This repository is inspired by or directly modified from many sources, primarily:
- rpc-endpoint:
rpcis a fork of Flashbot's RPC endpoint. - mev-share-node:
preconf-shareis a fork of Flashbot's MEV-Share node. - Based preconfirmations
- Analyzing BFT & Proposer-Promised Preconfirmations
🫡 Contributing
Check out the Contribution Guidelines!
Directories
¶
| Path | Synopsis |
|---|---|
|
contracts
|
|
|
Package operator AVS operator logic.
|
Package operator AVS operator logic. |
|
core/chainio
Package chainio contains the logic to interact with the AVS contracts onchain.
|
Package chainio contains the logic to interact with the AVS contracts onchain. |
|
core/config
Package config contains the config types.
|
Package config contains the config types. |
|
receiverapi
Package receiverapi contains the logic to receive preconfirmation callbacks.
|
Package receiverapi contains the logic to receive preconfirmation callbacks. |
|
sse
Package sse is the SSE Client for preconf-share
|
Package sse is the SSE Client for preconf-share |
|
types
Package types contains the types used in the AVS JSON-RPC communication.
|
Package types contains the types used in the AVS JSON-RPC communication. |
|
preconf-share
|
|
|
jsonrpcserver
Package jsonrpcserver allows exposing functions like: func Foo(context, int) (int, error) as a JSON RPC methods
|
Package jsonrpcserver allows exposing functions like: func Foo(context, int) (int, error) as a JSON RPC methods |
|
metrics
Package metrics contains all application-logic metrics
|
Package metrics contains all application-logic metrics |
|
preconshare
Package preconshare implements preconf-share node Here is a full flow of data through the node:
|
Package preconshare implements preconf-share node Here is a full flow of data through the node: |
|
simqueue
Package simqueue is a queue implementation that uses redis as a backend.
|
Package simqueue is a queue implementation that uses redis as a backend. |
|
spike
Package spike provides a primitive to handle spike-like load on retrieving external resources
|
Package spike provides a primitive to handle spike-like load on retrieving external resources |
|
rpc
|
|
|
adapters/webfile
Package webfile contains the fetcher logic
|
Package webfile contains the fetcher logic |
|
application
Package application contains the logic to start the builder info service.
|
Package application contains the logic to start the builder info service. |
|
database
Package database contains the types used in the database.
|
Package database contains the types used in the database. |
|
testutils
Package testutils Dummy RPC backend for both Ethereum node and Flashbots Relay.
|
Package testutils Dummy RPC backend for both Ethereum node and Flashbots Relay. |
|
types
Package types contains the types used in the JSON-RPC requests and responses.
|
Package types contains the types used in the JSON-RPC requests and responses. |
|
Package tests contains the utilities for tests.
|
Package tests contains the utilities for tests. |