Use indexation cache to satisfy "coins to spend" queries #2463

rafal-ch · 2024-11-28T13:43:02Z

Closes #2391

This PR includes all changes from the Part 1 PR, making it deprecated.

Description

Changes in this PR:

The new `CoinsToSpend` index

This is the database that stores all coins to spend sorted by the amounts (i.e. largest-by-value coins first)
The key consists of several parts
- Retryable flag - to distinguish between retryable messages and other coins
- Address (owner)
- AssetID
- Amount - as "big-endian" bytes to leverage the RocksDB key sorting capabilities
- Foreign Key - this are bytes of the key from either the Messages or Coins on-chain databases
  - for messages this is a 32-bytes Nonce
  - for coins this is a 34-bytes UtxoId
The value is an instance of IndexedCoinType enum, so we know which on-chain database to query when returning the actual coins
This index is updated when executor events are processed
When querying for "coins to spend" the following algorithm is applied:
- First, we get as many "big" coins as required to satisfy double the amount from the query (respecting max and excluded params)
- If we have enough coins, but there are still some "slots" in the query left (because we selected less coins than max) we fill the remaining slots with a random number of "dust" coins
- If it happens that the value of selected "dust coins" is able to cover the value of some of the already selected "big coins", we remove the latter from the response
- If at any step we encounter a problem (reading from database, integer conversions, etc.) we bail with an appropriate error

Changes to `CoinsQueryError` type

The MaxCoinsReached variant has been removed because in the new algorithm we never query for more coins than the specified max, hence, without additional effort, we are not able to tell whether the query could be satisfied if user provided bigger max
The InsufficientCoins has been renamed to InsufficientCoinsForTheMax and it now contains the additional max field

Off-chain database metadata

The metadata for off-chain database now contain the additional IndexationKind - CoinsToSpend

Refactoring

The indexation.rs module was split into separate files, each per indexation type + errors + some utils.

Other

Integration tests have to be updated to not expect the exact number of coins to spend in the response (currently, due to randomness, we're not deterministic in this regard)
The number of excluded ids in the coinsToSpend GraphQL query is now limited to the maximum number of inputs allowed in transaction.

Before requesting review

I have reviewed the code myself
I have created follow-up issues caused by this PR and linked them here

Follow-up issues

…to_spend_cache_part_2

netrome

Nice stuff so far. I have only done a relatively shallow sweep and will get back again during the week for a deeper look. I have a few nits and suggestions so far, but nothing major.

I'm not a fan of the lack of explicit error handling in crates/fuel-core/src/graphql_api/storage/coins.rs but other than that I think the code looks generally really well-written.

crates/fuel-core/src/coins_query.rs

crates/fuel-core/src/graphql_api.rs

crates/fuel-core/src/graphql_api/indexation/balances.rs

crates/fuel-core/src/graphql_api/storage/coins.rs

…to_spend_cache_part_2

Closes #2474 ## Description This PR changes the following: 1. Adds new test in `tests/tests/relayer.rs` - to ensure that only **non**-retryable messages contribute to the balance returned from `balance()`, `balances()` and `coins_to_spend()`[^1] endpoints 2. Modifies the `balance()` test in `tests/tests/balances.rs` to also include some retryable message which is expected **not** to contribute to the total balance. * for `balances()` and `coins_to_spend()` it was already the case 1<sup>st</sup> test checks the behavior of the actual blockchain operations while the 2<sup>nd</sup> tests the proper initialization of the balances index at genesis. ## Checklist - [X] Breaking changes are clearly marked as such in the PR description and changelog - [X] New behavior is reflected in tests ### Before requesting review - [X] I have reviewed the code myself [^1]: currently, `coins_to_spend()` is not using indexation, this will change when [this PR](#2463) is merged. --------- Co-authored-by: Green Baneling <[email protected]>

crates/fuel-core/src/coins_query.rs

crates/fuel-core/src/graphql_api/indexation/coins_to_spend.rs

netrome

Apologies for taking longer than expected. While most of this looks good to me, I have a few questions of some things that puzzle me. Moreover, there are two concrete things I'd like to see updated before approving:

First, we should update the description and name of the random_improve function. Second, I'd like to see an integration test that shows how this algorithm behaves end to end.

crates/fuel-core/src/coins_query.rs

crates/fuel-core/src/graphql_api/indexation/coins_to_spend.rs

tests/tests/coins.rs

…to_spend_cache_part_2

netrome

Thanks for updating. I would like to see the "random_improve" function renamed, perhaps just to "random" but I can live with the old name as well.

…to_spend_cache_part_2

rafal-ch · 2025-01-09T11:19:59Z

Thanks for updating. I would like to see the "random_improve" function renamed, perhaps just to "random" but I can live with the old name as well.

My understanding was that the "random improve" is actually the name of the algorithm. The linked article literally mentions this name. Cardano seems to be using the exact same name as well.

AurelienFT · 2025-01-10T13:05:52Z

crates/fuel-core/src/coins_query.rs

+    // We aim to reduce dust creation by targeting twice the required amount for selection,
+    // inspired by the random-improve approach. This increases the likelihood of generating
+    // useful change outputs for future transactions, minimizing unusable dust outputs.
+    // See also "let upper_target = target.saturating_mul(2);" in "fn random_improve()".


Very interesting !

AurelienFT · 2025-01-10T13:16:19Z

crates/fuel-core/src/graphql_api/indexation/coins_to_spend.rs

+    let storage = block_st_transaction.storage::<CoinsToSpendIndex>();
+    let maybe_old_value = storage.replace(&key, &IndexedCoinType::Coin)?;
+    if maybe_old_value.is_some() {
+        return Err(IndexationError::CoinToSpendAlreadyIndexed {


If we return an error here the coin will still be inserted in the transaction and not revert. If we drop the transaction in an outer function it might not be an issue but maybe the dev of the outer function isn't aware of this. Same for add_messages

rafal-ch added 30 commits October 17, 2024 11:03

DB metadata can track multiple indexation progresses

f246cd0

into_genesis() attemt

7472db7

Add some TODOs with ideas for the future

b4d2e0f

Use double_key! macro to define the balances key

d38fdb3

Add basic_storage_tests! for Balances

292acab

Merge remote-tracking branch 'upstream/master' into 1965_balances

651bcc8

Balances DB stores separate information for coins and messages

8342c8f

Fix the recursive call

9a9f120

Init indexation progresses with 0 upon metadata migration

6aa9325

Remove debug prints

b153db4

Store incoming balance in the new Balances DB

512a8a3

Read balance from the new Balances database

adf9e2a

Update coin balance, don't overwrite

344ca90

Use more detailed IndexationStatus, not just block height

f73dbed

Add processing of MessageImported

80da09b

Simplify processing of coins and message amounts

ad5216d

Extract increase_balance()

c784e44

Store coin and message balances separately

5762665

Clean up column naming

5595985

Add test for coin balances

38dd8d6

Support both coins and messages in the new balance system

530bcaf

Merge remote-tracking branch 'upstream/master' into 1965_balances

5604f30

update comment

562c087

Remove the database migration hack

82f7a16

Remove code related to handling base asset id

7d0b014

Clean-up of the balance update code

1fe3bba

Remove unused tests

fe60c98

Handle overflow in balance query

adef78e

Clippy and formatting

9409d52

Update db tests after reverting changes to metadata

13b6db9

Mention follow-up issue

03a0662

rafal-ch mentioned this pull request Dec 13, 2024

The OffChainDatabase::coins_to_spend_index() function should return error if indexation is not available #2499

Open

Mention follow-up issue

1049fea

rafal-ch requested a review from xgreenx December 13, 2024 12:54

Merge remote-tracking branch 'upstream/master' into rafal_2391_coins_…

9c87c8d

…to_spend_cache_part_2

netrome self-requested a review December 16, 2024 15:14

netrome reviewed Dec 16, 2024

View reviewed changes

rafal-ch added 5 commits December 17, 2024 15:43

Mention follow-up issue in the comment

65f701d

Replace as u128 with u128::from() where applicable

5eb9bb0

Getters on CoinsToSpendIndexKey will no longer panic

792dc33

Remove comment which is no longer relevant

4cc75bf

Merge remote-tracking branch 'upstream/master' into rafal_2391_coins_…

f776cb4

…to_spend_cache_part_2

xgreenx mentioned this pull request Jan 2, 2025

Use own codec for CoinsToSpendIndexKey #2529

Open

1 task

xgreenx reviewed Jan 2, 2025

View reviewed changes

crates/fuel-core/src/coins_query.rs Show resolved Hide resolved

crates/fuel-core/src/graphql_api/indexation/coins_to_spend.rs Show resolved Hide resolved

netrome requested changes Jan 6, 2025

View reviewed changes

rafal-ch added 4 commits January 8, 2025 08:33

Merge remote-tracking branch 'upstream/master' into rafal_2391_coins_…

8b4f86c

…to_spend_cache_part_2

Fixes after the merge

3ae1806

Add explanatory comment in coin selection algorithm

d9d024b

Remove outdated 'TODO' for fn random_improve()

2b3c4de

netrome previously approved these changes Jan 8, 2025

View reviewed changes

rafal-ch mentioned this pull request Jan 9, 2025

Create new index for tracking Asset metadata #2445

Open

3 tasks

Merge remote-tracking branch 'upstream/master' into rafal_2391_coins_…

56dbb69

…to_spend_cache_part_2

rafal-ch added 3 commits January 9, 2025 13:48

Update message assert in tests

905d91d

Satisfy Clippy

5cb246d

Fix typo

1a2ffa6

rafal-ch dismissed netrome’s stale review via 1a2ffa6 January 9, 2025 13:04

rafal-ch added the release label Jan 10, 2025

AurelienFT reviewed Jan 10, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use indexation cache to satisfy "coins to spend" queries #2463

Use indexation cache to satisfy "coins to spend" queries #2463

rafal-ch commented Nov 28, 2024 •

edited

Loading

netrome left a comment •

edited

Loading

netrome left a comment

netrome left a comment

rafal-ch commented Jan 9, 2025

AurelienFT Jan 10, 2025

AurelienFT Jan 10, 2025

Use indexation cache to satisfy "coins to spend" queries #2463

Are you sure you want to change the base?

Use indexation cache to satisfy "coins to spend" queries #2463

Conversation

rafal-ch commented Nov 28, 2024 • edited Loading

Description

The new CoinsToSpend index

Changes to CoinsQueryError type

Off-chain database metadata

Refactoring

Other

Before requesting review

Follow-up issues

netrome left a comment • edited Loading

Choose a reason for hiding this comment

netrome left a comment

Choose a reason for hiding this comment

netrome left a comment

Choose a reason for hiding this comment

rafal-ch commented Jan 9, 2025

AurelienFT Jan 10, 2025

Choose a reason for hiding this comment

AurelienFT Jan 10, 2025

Choose a reason for hiding this comment

rafal-ch commented Nov 28, 2024 •

edited

Loading

The new `CoinsToSpend` index

Changes to `CoinsQueryError` type

netrome left a comment •

edited

Loading