add API to return the number of allocation slots

[nicbus]

RGB assets are allocated to colorable UTXOs. One UTXO can support more than one allocation, depending on the value of max_allocations_per_utxo (in WalletData) provided at wallet instantiation time.

It would be useful to be able to query how many available allocations slots the wallet has. An example use case would be to know if new colorable UTXOs need to be created, in advance rather in response to an error when e.g. calling blind_receive.

• name: allocations
• parameters: none
• response: a new Allocations struct containing
  • total_available: the number of total available allocations
  • map: a map of UTXOs and the respective allocations (given the current value of max_allocations_per_utxo)
    • key: utxo
    • value:
      • used: the number of currently used allocations
      • available: the number of currently available allocations

With this data, the user can easily know:

• if there is at least one available allocation
• the total number of possible new allocations, before having to create more UTXOs
• the number of UTXOs that can support a new allocation

Notes:

• the number of used allocations can be obtained via get_rgb_allocations
• the number of available allocations corresponds to the value of max_allocations_per_utxo minus the currently used allocations

[marionautica]

"Hi everyone from Plan ₿ Tech School, I'm interested in working on this problem. I plan to implement the allocations structure described in the problem. Are there any preferences on how to structure the data or UTXO mapping?"

I'm planning a test that verifies that after calling create_utxos on a new wallet, the allocations API returns the number of UTXOs created multiplied by max_allocations_per_utxo.

Thanks in advance for any feedback!

[zoedberg]

"Hi everyone from Plan ₿ Tech School, I'm interested in working on this problem. I plan to implement the allocations structure described in the problem. Are there any preferences on how to structure the data or UTXO mapping?"

I'm not sure what you're asking, the issue already describes the structure the API response should have.

I'm planning a test that verifies that after calling create_utxos on a new wallet, the allocations API returns the number of UTXOs created multiplied by max_allocations_per_utxo.

This is a good idea!