feat: caching of recently used coins

[MujkicA]

Checklist

• I have linked to any relevant issues.
• I have updated the documentation.
• I have added tests that prove my fix is effective or that my feature works.
• I have added necessary labels.
• I have done my best to ensure that my PR adheres to the Fuel Labs Code Review Standards.
• I have requested a review from the relevant team or maintainers.

Adds a cache to the Provider for recently used coins. The cache is behind an optional feature flag coin-cache.

The cache holds a map with entries of (Bech32Address, AssetId) -> HashSet<CoinTypeId> where CoinTypeId is either a utxo or a nonce and Bech32Address is the address of the account that owns the coins.

Whenever a tx is submitted, every CoinTypeId is added to the cache entry corresponding to it's owner and asset.
When an account requests spendable_coins of a specific asset, the node is queried with recently used coins from the cache as a filtering condition.
The cache specifies a TTL for the items, once it expires the corresponding entries will be ignored and evicted the next time active entries are retrieved.

CoinCacheItem is a wrapper for a CoinTypeId that is stored in the cache. It includes the creation time so it can be verified against the TTL. It implements the Hash and PartialEq traits so that inserting them into the Set only compares against the id and not the creation time. This means that if a coin somehow is used again before it was evicted, the corresponding entry will just be updated with a new timestamp.
Tests make use of tokio::time to advance time manually instead of using sleep().

Other changes:
The strategy for adding fee coins is changed from completly recomputing the
base asset input set to just adding an amount of base asset that will cover the fee.
While this might lead to a bit more dust it gives us more flexibility and we can allow the user to specify base asset inputs at will.

[iqdecay]

only have some minor remarks

[MujkicA]

I didn't review the full PR, but from a quick read of the PR description it seems like we should maybe try to invalidate cached UTXOs in the event a transaction is unsuccessful. Otherwise users may need to wait for the TTL before being able to try again. This would only work if the user submits_and_awaits so that the sdk can check the response.

Alternatively, a short TTL such as 5 * block_time_ms might be good enough in most cases (since we currently use 1s blocks).

I thought about it but decided against it because it works only partially, i.e. when they use send_and_await. I imagine using send_and_await is more likely in local tests then out in the wild or if it is used on a live network, I think it's unlikely they will encounter the problem of using the same inputs since they wait for completion anyways.
It doesn't seem like a big win, but it would add a bit more complexity. Let me know if my assumptions are wrong @Voxelot.

On the other hand, we could probably benefit from invalidating at places where we call submit_and_await internally like contract calls. So maybe it's worth it.

[MujkicA]

Update

I've adjusted it to invalidate on failed txs during submit_and_await and included a test. I've also fixed the general test for caching.

Do we still want to shorten the TTL and is there a way to retrieve the block-time from the network? @Voxelot

[MujkicA]

Great work. Clean overall. Two notes: One is regarding the CI. It might be that the feature isn't being tested by the CI due to us choosing features manually to avoid the rocksdb feature:

          - cargo_command: nextest
            args: run --all-targets --features "default fuel-core-lib test-type-paths" --workspace
            download_sway_artifacts: sway-examples-w-type-paths

And another note: I have a suggestion for the Provider.

Rather than riddle it with cfg compile-time conditional code why not separate the logic into a strategy? It would concern itself with allowing or disallowing resources. Something like this:

#[async_trait::async_trait]
pub trait ResourcePicker {
    async fn register_used_resources(
        &self,
        coin_ids: impl IntoIterator<Item = (CoinCacheKey, Vec<CoinTypeId>)> + Send + Sync,
    );

    async fn modify_filter(&self, filter: &mut ResourceFilter);
}

And have two implementations, choose the correct one over in the provider:

    #[cfg(not(feature = "coin-cache"))]
    resource_picker: NoRestrictions,
    #[cfg(feature = "coin-cache")]
    resource_picker: ReusageAvoider,

NoRestrictions would just be a No-op impl of the trait. ReusageAvoider can house the logic now present in the provider:

#[derive(Default, Clone, Debug)]
pub struct ReusageAvoider {
    cache: Arc<Mutex<CoinsCache>>,
}

#[async_trait::async_trait]
impl ResourcePicker for ReusageAvoider {
    async fn register_used_resources(
        &self,
        coin_ids: impl IntoIterator<Item = (CoinCacheKey, Vec<CoinTypeId>)> + Send + Sync,
    ) {
        self.cache.lock().await.insert_multiple(coin_ids);
    }

    async fn modify_filter(&self, filter: &mut ResourceFilter) {
        let mut cache = self.cache.lock().await;
        let used_coins = cache.get_active(&(filter.from.clone(), filter.asset_id));

        let excluded_utxos = used_coins
            .iter()
            .filter_map(|coin_id| match coin_id {
                CoinTypeId::UtxoId(utxo_id) => Some(utxo_id),
                _ => None,
            })
            .cloned()
            .collect::<Vec<_>>();

        let excluded_message_nonces = used_coins
            .iter()
            .filter_map(|coin_id| match coin_id {
                CoinTypeId::Nonce(nonce) => Some(nonce),
                _ => None,
            })
            .cloned()
            .collect::<Vec<_>>();

        filter.excluded_utxos.extend(excluded_utxos);
        filter
            .excluded_message_nonces
            .extend(excluded_message_nonces);
    }
}

Since the choice is a compile-time one, we should feel very little if any impact when using the noop implementation (after optimizations).

I agree it would make it cleaner, but I'd rather we do that in a separate PR since updating this with the master branch is getting cumbersome.

[digorithm]

I did a first pass, and it's looking solid. I'll do another pass once the CI is green (I believe this is test-related so it shouldn't change much).

[iqdecay]

looking good, a non-blocking question on naming.

[hal3e]

🚀