feat(solana-indexer): PR 2 — add `types` module scaffolding by tilacog · Pull Request #4506 · cowprotocol/services

tilacog · 2026-06-08T20:46:59Z

Description

Adds the type definitions for the types/ module listed in the crate-layout spec.

This is PR 2 in the sequence; later PRs (traits (PR 3), then component structs (PR 4)) consume these types.

Changes

Added crates/solana-indexer/src/types/ with one file per module from the spec:
- wire.rs: wire-format types, for the Yellowstone gRPC protobuf types
- channel.rs: payload types for messages exchanged between the Ingester and Decoder component
- events.rs: domain event taxonomy
- commitment.rs: types for tracking Solana commitment levels
- dead_letter.rs: dead-letter primitives
- recovery.rs: recovery state
- errors.rs: error types for this crate
- tx.rs: transaction context
Declared pub mod types; in lib.rs so the module compiles.

How to test

cargo check -p solana-indexer
cargo +nightly fmt --all -- --check
cargo clippy --locked --workspace --all-features --all-targets -- -D warnings

No unit tests are included: the modules contain only type definitions, with no logic to exercise until the traits in PR 3 are introduced.

gemini-code-assist

Code Review

This pull request introduces the solana-indexer crate, which defines domain types for a Solana settlement indexer, including channel messages, commitment tracking, dead-letter handling, errors, events, metrics, recovery flows, and transaction helpers. A high-severity issue was identified in channel.rs where the PartialEvent struct is missing the half: PartialHalf field described in its documentation, which is required for the watchdog to reconstruct events. Adding this field also means PartialEvent must derive Clone instead of Copy due to heap-allocated types in PartialHalf.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

gemini-code-assist · 2026-06-08T20:48:36Z

+#[derive(Debug, Clone, Copy)]
+pub struct PartialEvent {
+    /// Slot the partial was observed at.
+    pub slot: u64,
+    /// Transaction signature the partial corresponds to.
+    pub signature: Signature,
+}


The doc comment for PartialEvent states that "each delivery carries the half that just landed," but the struct definition is missing the half: PartialHalf field. Without this field, the watchdog cannot receive or hold the actual data halves to match and reconstruct the full event. Additionally, since PartialHalf contains heap-allocated Box types, PartialEvent cannot derive Copy and should only derive Debug, Clone.

Suggested change

#[derive(Debug, Clone, Copy)]

pub struct PartialEvent {

/// Slot the partial was observed at.

pub slot: u64,

/// Transaction signature the partial corresponds to.

pub signature: Signature,

}

#[derive(Debug, Clone)]

pub struct PartialEvent {

/// Slot the partial was observed at.

pub slot: u64,

/// Transaction signature the partial corresponds to.

pub signature: Signature,

/// The half that just landed.

pub half: PartialHalf,

}

Local tombi was 0.9.0; CI uses 1.1.0 which produces different output.

github-actions · 2026-06-16T00:43:42Z

This pull request has been marked as stale because it has been inactive a while. Please update this pull request or it will be automatically closed.

jmg-duarte · 2026-06-16T12:17:04Z

+    #[error("replay window exceeded")]
+    ReplayWindowExceeded {
+        /// The slot the subscriber attempted to resume from.
+        attempted_slot: u64,
+        /// The earliest slot the provider can still serve.
+        earliest_replayable_slot: u64,
+    },


aren't you losing the slot u64's here?

Thanks, I was so focused on the types that I completely forgot to include the fields in the error message. Fixed in bfb4dcf.

jmg-duarte · 2026-06-16T12:17:25Z

+    /// String label used in `solana.dead_letter.reason`.
+    pub fn as_str(self) -> &'static str {


this would be more accurate, i see "as_str" like a "const to_string" and I'd expect it to return the same as the label itself e.g. DecoderError -> "DecoderError"

Suggested change

/// String label used in `solana.dead_letter.reason`.

pub fn as_str(self) -> &'static str {

/// String label used in `solana.dead_letter.reason`.

pub fn as_label(self) -> &'static str {

Renamed in 6e1f41e

jmg-duarte · 2026-06-16T12:18:31Z

+    /// String label used in `solana.*` `commitment` columns.
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Confirmed => "confirmed",
+            Self::Finalized => "finalized",
+            Self::RolledBack => "rolled_back",
+        }
+    }


Suggested change

/// String label used in `solana.*` `commitment` columns.

pub fn as_str(self) -> &'static str {

match self {

Self::Confirmed => "confirmed",

Self::Finalized => "finalized",

Self::RolledBack => "rolled_back",

}

}

/// String label used in `solana.*` `commitment` columns.

pub fn as_label(self) -> &'static str {

match self {

Self::Confirmed => "confirmed",

Self::Finalized => "finalized",

Self::RolledBack => "rolled_back",

}

}

Renamed in 6e1f41e

jmg-duarte · 2026-06-16T12:19:14Z

+use {crate::types::Signature, solana_sdk::pubkey::Pubkey};
+
+/// On-chain commitment of a transaction or row.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]


Do we actually need all these now? IMO we should just start with debug + clone (and maybe copy i guess) but the eq's will make more sense when actually used

You're right, they were added "just in case," but future PRs only use this type in match expressions, so the derives aren't needed.

Removed in 0fef0ed

jmg-duarte · 2026-06-16T12:20:09Z

+pub enum PartialHalf {
+    /// Transaction-update half.
+    Tx(Box<SubscribeUpdateTransactionInfo>),
+    /// Account-update half.
+    Account(Box<SubscribeUpdateAccountInfo>),
+}


why do these need to be boxed?

They are big types, and clippy caught that in its large_enum_variant lint.

SubscribeUpdateAccountInfo: 128 bytes

SubscribeUpdateTransactionInfo: 520 bytes (determines the enum size)

Mind that those values are in the hot path, so we expect them to be moved/copied a lot.

MartinquaXD · 2026-06-23T10:15:38Z

+/// at. The org file names the channel payload "Event"; the spec defines that
+/// type as `StreamUpdate`, and that is what this crate uses.


Please update those comments. AI always writes doc comments which reference context that is not present in the PR or the final code base.

Thanks for catching that, it shouldn't have been in there.
Removed in f57158f.

I do want to move the spec into the repo eventually, but I haven't landed on the right format yet.

MartinquaXD · 2026-06-23T10:17:04Z

+    /// An account-update slot message.
+    Account {
+        /// Slot the message was observed at.
+        slot: u64,


Is slots solana lingo for blocks?

Precisely.
A slot can be seen as a spot reserved for a block, for which the validator can include a block, or not.

More details here.

MartinquaXD · 2026-06-23T10:19:49Z

+//! Commitment-tracking types: confirmation state, signature status, and the row
+//! shapes consumed by the finalization worker.


Maybe an explainer on what a commitment is in this context is more helpful.

I've expanded the module docs in 399c2ec to give more context.

MartinquaXD · 2026-06-23T10:22:14Z

+
+use {crate::types::Signature, solana_sdk::pubkey::Pubkey};
+
+/// On-chain commitment of a transaction or row.


Does "row" mean a DB row here? In that case it seems like this should maybe not live in the fundamental "types" directory.

Yeah, it's a DB row.

I figured it was fine to keep this type here since it's only meant for the finalization worker component.

It will be used only to bump the commitment level on most rows in the database (every solana.* row comes from a transaction).

MartinquaXD · 2026-06-23T10:24:30Z

+
+/// On-chain commitment of a transaction or row.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Commitment {


commitment needs a better explanation here. It sounds like this is just the outcome of a tx but it's impossible to tell based on the existing information.

I've expanded the comments in 72146c4 to explain a bit about each commitment level

MartinquaXD · 2026-06-23T10:37:16Z

+        /// Transaction signature.
+        tx_signature: Signature,
+        /// Slot the settlement was observed at.
+        slot: u64,


This code could be more self explanatory with Slot(u64) and observed_at: Slot.

Agreed.
Introduced the Slot type in 57b5c76

MartinquaXD · 2026-06-23T10:40:06Z

+        /// Transaction signature.
+        tx_signature: Signature,
+        /// Index of the instruction within the transaction.
+        ix_index: u8,


Is the tx index used often enough that a new type would make sense for this?

I don't think so.
That info is mostly useful for auditing.

The SolverInteraction variant is still something we want to keep track of and index, but we don't really have a way to interpret it since it's basically an arbitrary instruction.

The upside is that, if we ever decide to try to retroactively decode a subset of those, we can refer to this info.

MartinquaXD · 2026-06-23T10:40:56Z

+        /// Real owner of the order.
+        real_owner: Pubkey,
+        /// Order UID.
+        order_uid: [u8; 32],


GIven that intent hash and order uid have the same data "shape" they should definitely get their own separate types.

I've introduced a new OrderUid type in c7936f4 to represent both intent_hash and order_uid fields, since they represent the same concept.

MartinquaXD · 2026-06-23T10:41:58Z

+    OrderEnabled {
+        /// Custodial PDA.
+        custodial_pda: Pubkey,
+        /// Address that enabled the order.


What does "enabled" here mean? Is this a contract that calls a function to activate the order or perhaps an account that pays for the gas or something else entirely?

I've expanded the doc-comments in 271539d to clarify those roles.

You intuition is correct, the enabler is an unprivileged actor that subsidizes the the order creation.

MartinquaXD · 2026-06-23T10:42:52Z

+#[metric(subsystem = "solana_indexer")]
+pub struct Metrics {
+    /// Slots between the chain tip and the indexed watermark.
+    pub indexer_lag_slots: GenericGauge<AtomicI64>,


Does it make sense that a lag gets a signed integer gauge?
Same applies to other metrics which all seem to work just fine with unsigned ints.

That's true, it was an oversight from my part.

After considering this other review comment, I decided to not include the metrics in this PR, but I'll keep the signing in mind when reintroducing them.

…r message

socket-security · 2026-06-23T17:55:07Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	yellowstone-grpc-proto@12.4.0
	solana-sdk@4.0.1

View full report

… DeadLetterReason

No usage site compares Commitment values with == — all code uses match.

…mment

squadgazzz

LGTM in overall. Any discrepancies can be adjusted in further PRs.

squadgazzz · 2026-06-24T09:58:50Z

+/// Prometheus metrics for the solana-indexer.
+#[derive(prometheus_metric_storage::MetricStorage)]
+#[metric(subsystem = "solana_indexer")]
+pub struct Metrics {


Not sure if metrics need to be a part of this PR. Maybe it makes sense to introduce them only when actually used? Right now, it is hard to judge whether the types and labels are correctly chosen.

That's a fair point. I've removed them in 6b2e8a1.
We'll add them in the follow up PRs, as needed.

squadgazzz · 2026-06-24T10:00:19Z

+        /// Transaction signature.
+        tx_signature: Signature,
+        /// Index of the instruction within the transaction.
+        ix_index: u8,


According to the docs, it should be u16. Which one should be used?

Thanks, let's go w/ u16.
Fixed in 47f8edf
I don't think we'll ever go beyond 256 instructions, but I don't want to be caught by surprise here.

squadgazzz · 2026-06-24T10:01:05Z

+#[derive(Debug, Clone)]
+pub struct PdaSnapshot {
+    /// Order UID.
+    pub order_uid: [u8; 32],


As @MartinquaXD already suggested for other types, maybe we need an OrderUid type here as well.

I've introduced a new OrderUid type in c7936f4 to represent both intent_hash and order_uid fields, since they represent the same concept.

Switches raw/serialized byte fields from Vec<u8> to bytes::Bytes so cheap clones are available from the start. Fields changed: AccountInfo.data, DeadLetterEntry.raw_bytes, ResolvedInstruction.data. ResolvedInstruction.accounts stays Vec<u8> because it stores account indices, not opaque bytes.

Introduces `types::Slot`, a thin newtype wrapper around `u64`, and replaces the bare `u64` slot fields in the event, channel, transaction, commitment, and dead-letter types with it.

…fiers Add a single `OrderUid(pub [u8; 32])` newtype in `types/mod.rs` and use it in place of raw `[u8; 32]` for every order-identifier field across `TradeDelta`, the settlement-program lifecycle events, the SolFlow custody events, and `PdaSnapshot`.

…rred

- Change all domain types from pub to pub(crate) — these are internal implementation details that shouldn't leak into the public API - Add #![expect(dead_code)] to each types module file to suppress warnings during bootstrap phase when not all types are wired up yet - Add #[allow(clippy::enum_variant_names)] on SolFlowEvent to suppress false positive from semantically correct variant names

…dules Move Slot to types/slot.rs and OrderUid to types/order.rs, leaving types/mod.rs as pure module declarations + the Signature re-export. Consistent with the crate's one-concept-per-file pattern.

squadgazzz

LGTM

Spec §9 Domain event taxonomy types SolverInteraction.ix_index as u16. Bump both the event field (events.rs) and the upstream decoder view (ResolvedInstruction.ix_index) to u16 for consistent typing through the pipeline; the single downcast from the grpc u32 lands at the future construction site.

feat(solana-indexer): add types module scaffolding

5b9b6a5

tilacog requested a review from a team as a code owner June 8, 2026 20:47

gemini-code-assist Bot reviewed Jun 8, 2026

View reviewed changes

tilacog changed the title ~~feat(solana-indexer): add types module scaffolding~~ feat(solana-indexer): add types module scaffolding Jun 8, 2026

tilacog added 2 commits June 8, 2026 18:06

toml fmt

a938616

fix(ci): reformat TOML files with tombi 1.1.0

c7b2dbc

Local tombi was 0.9.0; CI uses 1.1.0 which produces different output.

github-actions Bot added the stale label Jun 16, 2026

jmg-duarte reviewed Jun 16, 2026

View reviewed changes

MartinquaXD reviewed Jun 23, 2026

View reviewed changes

tilacog changed the title ~~feat(solana-indexer): add types module scaffolding~~ feat(solana-indexer) PR 2: add types module scaffolding Jun 23, 2026

tilacog changed the title ~~feat(solana-indexer) PR 2: add types module scaffolding~~ feat(solana-indexer): PR 2 — add types module scaffolding Jun 23, 2026

tilacog mentioned this pull request Jun 23, 2026

feat(solana-indexer): PR 3 — add traits module #4508

Open

fix(solana-indexer): include slot fields in ReplayWindowExceeded erro…

bfb4dcf

…r message

tilacog added 5 commits June 23, 2026 14:57

refactor(solana-indexer): rename as_str to as_label on Commitment and…

6e1f41e

… DeadLetterReason

refactor(solana-indexer): drop unused PartialEq+Eq from Commitment

0fef0ed

No usage site compares Commitment values with == — all code uses match.

docs(solana-indexer): remove org/spec references from StreamUpdate co…

f57158f

…mment

Concise commitment-level doc comments in solana-indexer

72146c4

docs: tighten commitment module doc-comment, name each type's role

399c2ec

github-actions Bot removed the stale label Jun 24, 2026

squadgazzz approved these changes Jun 24, 2026

View reviewed changes

tilacog added 8 commits June 24, 2026 11:41

Add Slot newtype for Solana ledger slots

57b5c76

Introduces `types::Slot`, a thin newtype wrapper around `u64`, and replaces the bare `u64` slot fields in the event, channel, transaction, commitment, and dead-letter types with it.

fix(toml): alphabetize bytes/derive_more in solana-indexer/Cargo.toml

3d65b11

Use u64 for auction_id in solana SettlementFinalized domain type

f6f7cb8

docs(solana-indexer): clarify that TradeDelta.order_fulfilled is infe…

64166cb

…rred

nit: fmt comments

fe154a4

docs(solana-indexer): clarify SolFlowEvent::OrderEnabled doc comment

271539d

tilacog added 3 commits June 24, 2026 14:28

chore(solana-indexer): Remove metrics module

6b2e8a1

refactor(solana-indexer): extract Slot and OrderUid into dedicated mo…

dfc1272

…dules Move Slot to types/slot.rs and OrderUid to types/order.rs, leaving types/mod.rs as pure module declarations + the Signature re-export. Consistent with the crate's one-concept-per-file pattern.

tilacog requested review from MartinquaXD, jmg-duarte and squadgazzz June 24, 2026 18:03

squadgazzz approved these changes Jun 25, 2026

View reviewed changes

tilacog and others added 3 commits June 25, 2026 09:43

Merge branch 'main' into solana-indexer/PR2-bootstrap

135042e

Update cargo.lock

5092df3

		/// String label used in `solana.dead_letter.reason`.
		pub fn as_str(self) -> &'static str {

		/// at. The org file names the channel payload "Event"; the spec defines that
		/// type as `StreamUpdate`, and that is what this crate uses.

		//! Commitment-tracking types: confirmation state, signature status, and the row
		//! shapes consumed by the finalization worker.


		use {crate::types::Signature, solana_sdk::pubkey::Pubkey};

		/// On-chain commitment of a transaction or row.

Uh oh!

Conversation

tilacog commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

How to test

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jun 16, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tilacog Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

socket-security Bot commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

tilacog commented Jun 8, 2026 •

edited

Loading

tilacog Jun 23, 2026 •

edited

Loading

socket-security Bot commented Jun 23, 2026 •

edited

Loading

tilacog Jun 24, 2026 •

edited

Loading