API Overview

Sova API is designed to enable MEV searchers to interact with the TON blockchain’s mempool and message inclusion process. Searcher API is declared and available at https://github.com/sova-network/sova-grpc-proto/blob/main/proto/searcher.proto. It provides several core functionalities:

Mempool and Message Handling

• Mempool Messages:

  • MempoolExternalMessage: Encapsulates individual external messages with details like hash, workchain and shard identifiers, gas spent, and related outgoing messages.

  • MempoolPacket: Aggregates external messages along with a server timestamp and an expiration time. This helps in tracking and emulating the mempool state.

• Message Bundles:

  • ExternalMessage: A generic container for encoded external message data.

  • Bundle: Group messages for batch processing. It is used to ensure messages are processed together before they expire.

Subscription Mechanisms

The API supports fine-grained subscriptions to monitor different parts of the mempool:

• Address-Based Subscription: Allows subscribers to monitor messages related to specific addresses.

• Workchain and Shard Subscriptions: Enable filtering messages by workchain or even by specific shards within a workchain.

• Opcode-Based Subscription: Provides subscriptions for both external outgoing and internal messages that match a specific opcode.

• These are encapsulated within the MempoolSubscription message using a oneof field to ensure only one type is selected per subscription.

Bundle Result Tracking

To handle the outcomes of message bundle submissions (often related to auctions or processing steps), several result types are defined:

• Auction Outcomes:

  • BundleResultAuctionWin and BundleResultAuctionLoose indicate whether a bundle succeeded or failed in an auction.

• Partial Processing or Expiration:

  • BundleResultPartiallyProcessed and BundleResultPartiallyExpired provide details when only parts of a bundle are processed or expire.

• Interruption and Failures:

  • BundleResultInterrupted captures cases where processing is interrupted.

  • BundleResultAuctionFailedEstimate and BundleResultInternalError detail failures due to estimate errors or internal errors.

Service Methods

The SearcherService encapsulates the main interactions:

• SubscribeBundleResults:

  • Clients can receive a stream of bundle result events, keeping them informed about the status of their bundle submissions.

• SubscribeMempool:

  • Allows real-time streaming of mempool packets filtered by the subscription criteria (address, workchain, shard, or opcode).

• SendBundle:

  • Enables clients to submit a bundle of messages for processing. The response includes a bundle ID.

• GetTipAddresses:

  • Retrieves the list of tip addresses required for bundle submissions, ensuring that each bundle includes the mandatory TON transfer to one of these addresses for auction eligibility.