The highest tagged major version is
Documentation
¶
Overview ¶
Package mev implements MEV protection via commit-reveal scheme. This prevents frontrunning and sandwich attacks by requiring a two-phase order submission process:
1. COMMIT: User submits hash(order || salt) - commitment is recorded 2. REVEAL: User reveals order and salt - verified against commitment 3. EXECUTE: Order is only executed if reveal matches commit within deadline
The commitment hash hides order details until reveal, preventing validators/block producers from extracting MEV.
Index ¶
- Constants
- Variables
- func ComputeCommitment(orderBytes []byte, salt [SaltLength]byte) ids.ID
- func SerializeOrderForCommitment(symbol string, side, orderType uint8, price, quantity uint64, ...) []byte
- func VerifyCommitment(commitmentHash ids.ID, orderBytes []byte, salt [SaltLength]byte) bool
- type Commitment
- type CommitmentConfig
- type CommitmentStats
- type CommitmentStore
- func (cs *CommitmentStore) AddCommitment(commitmentHash ids.ID, sender ids.ShortID, blockHeight uint64, ...) error
- func (cs *CommitmentStore) CleanupExpired(currentTime time.Time) int
- func (cs *CommitmentStore) GetCommitment(commitmentHash ids.ID) (interface{}, bool)
- func (cs *CommitmentStore) GetSenderCommitments(sender ids.ShortID) []interface{}
- func (cs *CommitmentStore) Reveal(commitmentHash ids.ID, orderBytes []byte, salt [SaltLength]byte, ...) (*Commitment, error)
- func (cs *CommitmentStore) Statistics() interface{}
- type OrderCommitment
- type OrderReveal
Constants ¶
const ( // SaltLength is the required length of the salt (32 bytes). SaltLength = 32 // DefaultMinRevealDelay is the minimum time between commit and reveal. // This ensures the commitment is included in a block before reveal. DefaultMinRevealDelay = 2 * time.Second // DefaultMaxRevealDelay is the maximum time allowed for reveal after commit. // After this, the commitment expires and order cannot be placed. DefaultMaxRevealDelay = 5 * time.Minute // DefaultCommitmentGracePeriod is how long to keep expired commitments // for audit purposes before garbage collection. DefaultCommitmentGracePeriod = 1 * time.Hour )
Variables ¶
var ( ErrCommitmentNotFound = errors.New("commitment not found") ErrCommitmentExpired = errors.New("commitment expired") ErrCommitmentAlreadyUsed = errors.New("commitment already revealed") ErrCommitmentMismatch = errors.New("reveal does not match commitment") ErrCommitmentTooEarly = errors.New("reveal too early - minimum delay not met") ErrInvalidSalt = errors.New("invalid salt length") ErrDuplicateCommitment = errors.New("duplicate commitment") )
Functions ¶
func ComputeCommitment ¶
func ComputeCommitment(orderBytes []byte, salt [SaltLength]byte) ids.ID
ComputeCommitment computes the commitment hash for order bytes and salt. commitment = SHA256(order_bytes || salt)
func SerializeOrderForCommitment ¶
func SerializeOrderForCommitment( symbol string, side, orderType uint8, price, quantity uint64, timeInForce string, ) []byte
SerializeOrderForCommitment serializes order fields for commitment hash. Format: symbol_len(2) || symbol || side(1) || type(1) || price(8) || qty(8) || tif_len(2) || tif
func VerifyCommitment ¶
VerifyCommitment checks if the revealed order matches the commitment.
Types ¶
type Commitment ¶
type Commitment struct {
// Hash is the commitment hash: SHA256(order_bytes || salt)
Hash ids.ID
// Sender is the address that made the commitment
Sender ids.ShortID
// BlockHeight is the block where commitment was recorded
BlockHeight uint64
// BlockTime is the block timestamp when committed
BlockTime time.Time
// ExpiresAt is when this commitment can no longer be revealed
ExpiresAt time.Time
// Revealed indicates if this commitment has been revealed
Revealed bool
// RevealedAt is when the commitment was revealed (if revealed)
RevealedAt time.Time
}
Commitment represents a pending order commitment.
type CommitmentConfig ¶
type CommitmentConfig struct {
MinRevealDelay time.Duration
MaxRevealDelay time.Duration
CommitmentGrace time.Duration
}
CommitmentConfig allows custom configuration.
type CommitmentStats ¶
type CommitmentStats struct {
TotalCommits uint64 `json:"totalCommits"`
TotalReveals uint64 `json:"totalReveals"`
TotalExpired uint64 `json:"totalExpired"`
TotalMismatch uint64 `json:"totalMismatch"`
PendingCommitments int `json:"pendingCommitments"`
}
Statistics returns commit-reveal statistics.
type CommitmentStore ¶
type CommitmentStore struct {
// contains filtered or unexported fields
}
CommitmentStore tracks pending commitments.
func NewCommitmentStore ¶
func NewCommitmentStore() *CommitmentStore
NewCommitmentStore creates a new commitment store with default config.
func NewCommitmentStoreWithConfig ¶
func NewCommitmentStoreWithConfig(cfg CommitmentConfig) *CommitmentStore
NewCommitmentStoreWithConfig creates a commitment store with custom config.
func (*CommitmentStore) AddCommitment ¶
func (cs *CommitmentStore) AddCommitment( commitmentHash ids.ID, sender ids.ShortID, blockHeight uint64, blockTime time.Time, ) error
AddCommitment records a new commitment. Returns error if duplicate or sender has too many pending commitments.
func (*CommitmentStore) CleanupExpired ¶
func (cs *CommitmentStore) CleanupExpired(currentTime time.Time) int
CleanupExpired removes expired commitments that are past the grace period. Should be called periodically (e.g., once per block).
func (*CommitmentStore) GetCommitment ¶
func (cs *CommitmentStore) GetCommitment(commitmentHash ids.ID) (interface{}, bool)
GetCommitment retrieves a commitment by hash. Returns interface{} for API compatibility.
func (*CommitmentStore) GetSenderCommitments ¶
func (cs *CommitmentStore) GetSenderCommitments(sender ids.ShortID) []interface{}
GetSenderCommitments returns all active commitments for a sender as interface{} slice.
func (*CommitmentStore) Reveal ¶
func (cs *CommitmentStore) Reveal( commitmentHash ids.ID, orderBytes []byte, salt [SaltLength]byte, sender ids.ShortID, blockTime time.Time, ) (*Commitment, error)
Reveal verifies and marks a commitment as revealed. Returns the original commitment if successful.
func (*CommitmentStore) Statistics ¶
func (cs *CommitmentStore) Statistics() interface{}
Statistics returns commit-reveal statistics as interface{} for API compatibility.
type OrderCommitment ¶
type OrderCommitment struct {
// CommitmentHash is the hash submitted in commit phase
CommitmentHash ids.ID `json:"commitmentHash"`
// Sender is the order sender
Sender ids.ShortID `json:"sender"`
// Symbol is the trading pair (revealed after reveal)
Symbol string `json:"symbol,omitempty"`
}
OrderCommitment represents a committed order waiting for reveal.
type OrderReveal ¶
type OrderReveal struct {
// CommitmentHash links to the original commitment
CommitmentHash ids.ID `json:"commitmentHash"`
// Salt is the 32-byte random salt used in commitment
Salt [SaltLength]byte `json:"salt"`
// Order is the actual order being placed
Symbol string `json:"symbol"`
Side uint8 `json:"side"`
OrderType uint8 `json:"orderType"`
Price uint64 `json:"price"`
Quantity uint64 `json:"quantity"`
TimeInForce string `json:"timeInForce"`
}
OrderReveal represents the revealed order data.
Source Files