Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions api-server/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@ All notable changes to the API server will be documented in this file.

The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## [Unreleased]

### Fixed
- The scanner's fast catch-up mode no longer leaves the address and token transaction history permanently incomplete: a backfill pass now rebuilds the deferred history rows from the locally stored blocks after catching up, without touching balances or UTXOs. Databases written by builds predating the history watermark are seeded at startup so their history is rebuilt too.

## [1.4.5] - 2026-11-10

### Fixed
Expand Down
33 changes: 33 additions & 0 deletions api-server/api-server-common/src/storage/impls/in_memory/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,7 @@ struct ApiServerInMemoryStorage {
genesis_block: Arc<WithId<Genesis>>,
number_of_coin_decimals: u8,
storage_version: u32,
secondary_indexed_height: Option<BlockHeight>,
// kept so that order/pool identifiers can be encoded exactly like the postgres
// backend does (bech32 address strings), keeping tie-break orders identical
chain_config: ChainConfig,
Expand Down Expand Up @@ -131,6 +132,7 @@ impl ApiServerInMemoryStorage {
genesis_block: chain_config.genesis_block().clone(),
number_of_coin_decimals: chain_config.coin_decimals(),
storage_version: CURRENT_STORAGE_VERSION,
secondary_indexed_height: None,
chain_config: chain_config.clone(),
}
}
Expand Down Expand Up @@ -406,6 +408,37 @@ impl ApiServerInMemoryStorage {
Ok(version_table_handle)
}

fn secondary_indexed_height(&self) -> Result<Option<BlockHeight>, ApiServerStorageError> {
Ok(self.secondary_indexed_height)
}

fn get_block_transaction_indices(
&self,
block_height: BlockHeight,
) -> Result<Vec<(Id<Transaction>, u64)>, ApiServerStorageError> {
let Some(block_id) = self.main_chain_blocks_table.get(&block_height) else {
return Ok(Vec::new());
};
Ok(self
.ordered_transaction_table
.iter()
.filter(|(_, tx_id)| {
self.transaction_table
.get(*tx_id)
.is_some_and(|(owning_block_id, _)| owning_block_id == block_id)
})
.map(|(index, tx_id)| (*tx_id, *index))
.collect())
}

fn set_secondary_indexed_height(
&mut self,
block_height: BlockHeight,
) -> Result<(), ApiServerStorageError> {
self.secondary_indexed_height = Some(block_height);
Ok(())
}

fn get_best_block(&self) -> Result<BlockAuxData, ApiServerStorageError> {
let result = self.main_chain_blocks_table.last_key_value().map_or_else(
|| {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -215,6 +215,17 @@ impl ApiServerStorageRead for ApiServerInMemoryStorageTransactionalRo<'_> {
self.transaction.get_best_block()
}

async fn secondary_indexed_height(&self) -> Result<Option<BlockHeight>, ApiServerStorageError> {
self.transaction.secondary_indexed_height()
}

async fn get_block_transaction_indices(
&self,
block_height: BlockHeight,
) -> Result<Vec<(Id<Transaction>, u64)>, ApiServerStorageError> {
self.transaction.get_block_transaction_indices(block_height)
}

async fn get_block_aux_data(
&self,
block_id: Id<Block>,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,13 @@ use super::ApiServerInMemoryStorageTransactionalRw;

#[async_trait::async_trait]
impl ApiServerStorageWrite for ApiServerInMemoryStorageTransactionalRw<'_> {
async fn set_secondary_indexed_height(
&mut self,
block_height: BlockHeight,
) -> Result<(), ApiServerStorageError> {
self.transaction.set_secondary_indexed_height(block_height)
}

async fn reinitialize_storage(
&mut self,
chain_config: &ChainConfig,
Expand Down Expand Up @@ -381,6 +388,17 @@ impl ApiServerStorageRead for ApiServerInMemoryStorageTransactionalRw<'_> {
self.transaction.get_best_block()
}

async fn secondary_indexed_height(&self) -> Result<Option<BlockHeight>, ApiServerStorageError> {
self.transaction.secondary_indexed_height()
}

async fn get_block_transaction_indices(
&self,
block_height: BlockHeight,
) -> Result<Vec<(Id<Transaction>, u64)>, ApiServerStorageError> {
self.transaction.get_block_transaction_indices(block_height)
}

async fn get_block(
&self,
block_id: Id<Block>,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1651,6 +1651,92 @@ impl<'a, 'b> QueryFromConnection<'a, 'b> {
Ok(())
}

/// The height through which the secondary history tables are complete;
/// `None` when no fast catch-up has deferred them. See the scanner-lib
/// backfill pass.
pub async fn secondary_indexed_height(
&mut self,
) -> Result<Option<BlockHeight>, ApiServerStorageError> {
let row = self
.tx
.query_opt(
"SELECT value FROM ml.misc_data WHERE name = 'secondary_indexed_height';",
&[],
)
.await
.map_err(|e| ApiServerStorageError::LowLevelStorageError(e.to_string()))?;

let Some(bytes) = row.map(|row| row.get::<_, Vec<u8>>(0)) else {
return Ok(None);
};
let bytes: [u8; 8] = bytes.try_into().map_err(|_| {
ApiServerStorageError::DeserializationError(
"Invalid secondary indexed height stored in the database".to_owned(),
)
})?;
Ok(Some(BlockHeight::new(u64::from_be_bytes(bytes))))
}

/// Records the height through which the secondary history tables are
/// complete.
pub async fn set_secondary_indexed_height(
&mut self,
block_height: BlockHeight,
) -> Result<(), ApiServerStorageError> {
let bytes = u64::to_be_bytes(block_height.into_int()).to_vec();
self.tx
.execute(
"INSERT INTO ml.misc_data (name, value) VALUES ('secondary_indexed_height', $1)
ON CONFLICT (name) DO UPDATE SET value = EXCLUDED.value;",
Comment on lines +1689 to +1690

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

bug · medium
Both backends (this upsert and the in-memory setter) write the watermark unconditionally with no monotonic guard. If the value is ever written out of order (e.g. a re-processed/lower block during replay or a concurrent writer), the watermark regresses and the backfill pass will re-index blocks — or worse, if a stale value is written after a newer one within different transactions, secondary tables newer than the watermark could be treated as not yet indexed and skipped on the next catch-up. Consider guarding the update, e.g. ... DO UPDATE SET value = EXCLUDED.value WHERE ... with a comparison on the decoded height, or an application-level monotonic check.

Suggestion:

Suggested change
"INSERT INTO ml.misc_data (name, value) VALUES ('secondary_indexed_height', $1)
ON CONFLICT (name) DO UPDATE SET value = EXCLUDED.value;",
"INSERT INTO ml.misc_data (name, value) VALUES ('secondary_indexed_height', $1)
ON CONFLICT (name) DO UPDATE SET value = EXCLUDED.value
WHERE decode_u64(ml.misc_data.value) < decode_u64(EXCLUDED.value);"

&[&bytes],
)
.await
.map_err(|e| ApiServerStorageError::LowLevelStorageError(e.to_string()))?;
Ok(())
}

/// The `(transaction id, global index)` pairs of all transactions owned by
/// the main-chain block at `block_height`, ascending by index.
pub async fn get_block_transaction_indices(
&mut self,
block_height: BlockHeight,
) -> Result<Vec<(Id<Transaction>, u64)>, ApiServerStorageError> {
let height = Self::block_height_to_postgres_friendly(block_height);
let rows = self
.tx
.query(
"SELECT t.transaction_id, t.tx_global_index
FROM ml.transactions t
JOIN ml.blocks b ON t.owning_block_id = b.block_id
WHERE b.block_height = $1
ORDER BY t.tx_global_index ASC;",
Comment on lines +1708 to +1712

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

performance · medium
This query joins ml.transactions on owning_block_id, but the schema only creates indexes on ml.blocks (block_height) and ml.transactions (tx_global_index DESC) — there is no index on transactions.owning_block_id. During backfill this is called per block, and the planner will likely fall back to scanning ml.transactions (which grows to cover the whole chain) for every invocation. Consider adding an index on ml.transactions (owning_block_id) alongside the new watermark logic.

Suggestion:

Suggested change
"SELECT t.transaction_id, t.tx_global_index
FROM ml.transactions t
JOIN ml.blocks b ON t.owning_block_id = b.block_id
WHERE b.block_height = $1
ORDER BY t.tx_global_index ASC;",
self.just_execute(
"CREATE INDEX transactions_owning_block_id ON ml.transactions (owning_block_id);",
)

&[&height],
)
.await
.map_err(|e| ApiServerStorageError::LowLevelStorageError(e.to_string()))?;

let mut result = Vec::with_capacity(rows.len());
for row in rows {
let tx_id_bytes: Vec<u8> = row.get(0);
let index: i64 = row.get(1);
let tx_id =
Id::<Transaction>::decode_all(&mut tx_id_bytes.as_slice()).map_err(|_| {
ApiServerStorageError::DeserializationError(
"Invalid transaction id in transactions table".to_owned(),
)
})?;
result.push((
tx_id,
u64::try_from(index).map_err(|_| {
ApiServerStorageError::DeserializationError(
"Invalid transaction global index".to_owned(),
)
})?,
));
}
Ok(result)
}

pub async fn initialize_database(
&mut self,
chain_config: &ChainConfig,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@

use common::{
chain::{
DelegationId, Destination, OrderId, PoolId, block::timestamp::BlockTimestamp,
DelegationId, Destination, OrderId, PoolId, Transaction, block::timestamp::BlockTimestamp,
tokens::TokenId,
},
primitives::{Amount, BlockHeight, CoinOrTokenId, Id},
Expand Down Expand Up @@ -143,6 +143,25 @@ impl ApiServerStorageRead for ApiServerPostgresTransactionalRo<'_> {
Ok(res)
}

async fn secondary_indexed_height(&self) -> Result<Option<BlockHeight>, ApiServerStorageError> {
let mut conn =
QueryFromConnection::new(self.connection.as_ref().expect(CONN_ERR), &self.statements);
let res = conn.secondary_indexed_height().await?;

Ok(res)
}

async fn get_block_transaction_indices(
&self,
block_height: BlockHeight,
) -> Result<Vec<(Id<Transaction>, u64)>, ApiServerStorageError> {
let mut conn =
QueryFromConnection::new(self.connection.as_ref().expect(CONN_ERR), &self.statements);
let res = conn.get_block_transaction_indices(block_height).await?;

Ok(res)
}

async fn get_block(
&self,
block_id: Id<common::chain::Block>,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,15 @@ use super::{ApiServerPostgresTransactionalRw, CONN_ERR};

#[async_trait::async_trait]
impl ApiServerStorageWrite for ApiServerPostgresTransactionalRw<'_> {
async fn set_secondary_indexed_height(
&mut self,
block_height: BlockHeight,
) -> Result<(), ApiServerStorageError> {
let mut conn =
QueryFromConnection::new(self.connection.as_ref().expect(CONN_ERR), &self.statements);
conn.set_secondary_indexed_height(block_height).await
}

async fn reinitialize_storage(
&mut self,
chain_config: &ChainConfig,
Expand Down Expand Up @@ -578,6 +587,25 @@ impl ApiServerStorageRead for ApiServerPostgresTransactionalRw<'_> {
Ok(res)
}

async fn secondary_indexed_height(&self) -> Result<Option<BlockHeight>, ApiServerStorageError> {
let mut conn =
QueryFromConnection::new(self.connection.as_ref().expect(CONN_ERR), &self.statements);
let res = conn.secondary_indexed_height().await?;

Ok(res)
}

async fn get_block_transaction_indices(
&self,
block_height: BlockHeight,
) -> Result<Vec<(Id<Transaction>, u64)>, ApiServerStorageError> {
let mut conn =
QueryFromConnection::new(self.connection.as_ref().expect(CONN_ERR), &self.statements);
let res = conn.get_block_transaction_indices(block_height).await?;

Ok(res)
}

async fn get_block(
&self,
block_id: Id<Block>,
Expand Down
24 changes: 24 additions & 0 deletions api-server/api-server-common/src/storage/storage_api/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -666,6 +666,21 @@ pub trait ApiServerStorageRead: Sync {

async fn get_best_block(&self) -> Result<BlockAuxData, ApiServerStorageError>;

/// The height through which the secondary history tables (address and
/// token transaction listings) are known to be complete. `None` means no
/// scan has deferred them, i.e. they are complete wherever they exist.
/// See `set_secondary_indexed_height`.
async fn secondary_indexed_height(&self) -> Result<Option<BlockHeight>, ApiServerStorageError>;

/// The transaction global indices of all transactions whose owning block
/// is the main-chain block at `block_height`, in ascending index order.
/// Used by the secondary-index backfill to stamp token transaction rows
/// with the same indices the live scan assigned.
async fn get_block_transaction_indices(
&self,
block_height: BlockHeight,
) -> Result<Vec<(Id<Transaction>, u64)>, ApiServerStorageError>;

async fn get_latest_blocktimestamps(
&self,
) -> Result<Vec<BlockTimestamp>, ApiServerStorageError>;
Expand Down Expand Up @@ -949,6 +964,15 @@ pub trait ApiServerStorageWrite: ApiServerStorageRead {
block_height: BlockHeight,
) -> Result<(), ApiServerStorageError>;

/// Records that the secondary history tables are complete through
/// `block_height` inclusive. Maintained by the scan (lagging while fast
/// catch-up defers history rows) and by the backfill pass; rolled back on
/// reorg disconnects together with the rows it describes.
async fn set_secondary_indexed_height(
&mut self,
block_height: BlockHeight,
) -> Result<(), ApiServerStorageError>;

/// Stores the balance under the string encoding carried by the given address:
/// scanning constructs addresses via `Address::new`, so the stored encoding is
/// the canonical one, which the byte-ordered tie-break comparison of the
Expand Down
Loading
Loading