Description
We have a few minting related RPC calls with poor documentation
MintAsset says "MintAsset will attempt to mint the set of assets (async by default to ensure proper batching) specified in the request. The pending batch is returned that shows the other pending assets that are part of the next batch. This call will block until the operation succeeds (asset is staged in the batch) or fails.".
Here, I think we should make it clear when the asset_id and group_key are defined. I don't think they come out of this command, even if external_group_key is not set, but I'm not sure. Also, as part of the description for external_group_key, we should mention that if this is used, we must manually run FundBatch and SealBatch before FinalizeBatch. The other thing about this command this misleading is the word "Mint". Why do we call it minting if there is no asset_id or group_key yet? Like what has been uniquely created by this command? I feel like "minting" implies something unique has been generated but it is unclear to me what is uniquely done by this call (related: lightninglabs/docs.lightning.engineering#732).
====================================
FundBatch says "tapcli assets mint fund FundBatch will attempt to fund the current pending batch with a genesis input, or create a new funded batch if no batch exists yet. This RPC is only needed if a custom witness is needed to finalize the batch. Otherwise, FinalizeBatch can be called directly."
However, I'm confused why I would want to fund a batch that does not exist yet? Am I able to fund a batch before minting and then add minted assets to that batch after funding it? I was under the impression that I had to mint all assets before calling FundBatch.
We also should say more explicitly that this is RPC is mostly targeted for offline minting of a grouped asset using an external signer.
We should also make some mention that the genesis input is a UTXO that must be consumed when minting the asset. I'm not sure though, how that UTXO is reserved in the wallet before running FinalizeBatch so that some other user of the wallet does not consume the UTXO first.
=====================================
SealBatch says "tapcli assets mint seal SealBatch will attempt to seal the current pending batch by creating and validating asset group witness for all assets in the batch. If a witness is not provided, a signature will be derived to serve as the witness. This RPC is only needed if any assets in the batch have a custom asset group key that require an external signer. Otherwise, FinalizeBatch can be called directly."
Here I'm a bit confused because in practice, I thought this RPC was for supplying a witness/signature from an external signer. However, when I read the documentation, it is very confusing. "SealBatch will attempt to seal the current pending batch by creating and validating asset group witness for all assets in the batch." leads me to believe the RPC is creating the witness. The next sentence, "If a witness is not provided, a signature will be derived to serve as the witness." acts like it may not be creating the witness, but you've never told me that an external witness can be provided. Finally, "This RPC is only needed if any assets in the batch have a custom asset group key that require an external signer. Otherwise, FinalizeBatch can be called directly." leads me to believe that the RPC is only used with an external signer, but if I'm only using an external signer, where are the signatures coming from that this RPC can create? Generally the order of sentences and wording of the sentences needs to be improved.
=====================================
FinalizeBatch has a very brief description: "FinalizeBatch will attempt to finalize the current pending batch.".
I really have no idea what this means. In practice, I think it signs the transaction that consumes the UTXO that is the genesis point and then broadcast that transaction, but I'm not really sure.
=====================================
CancelBatch just says "CancelBatch will attempt to cancel the current pending batch.".
However, I'm not sure what all that does. Was there a UTXO reserved by FundBatch that is released back to the wallet when I do this? Also, this RPC returns a batch_key which is "The internal public key of the batch.", but I have no idea what that batch_key is for or why I need to know it when I cancel a batch.