change(rpc): Update getaddressbalance RPC to return received field

[arya2]

Motivation

Updates the getaddressbalance RPC to accept either a single address string or a list of them to match zcashd, and adds the received field on the method's response.

This PR is still a draft as it will need an acceptance test.

Depends-On: #9263

Will close #8452.

Solution

• Bumps db format version for address balances to include a received field, and adds an in-place format upgrade,
• Parses single address strings passed to RPC methods accepting AddressStrings as a Vec with one item, and
• Adds the received field to the getaddressbalance RPC output.

Tests

This PR still needs an acceptance test for the db format upgrade.
The changes to the RPC should be covered by existing snapshot tests.

PR Checklist

• The PR name is suitable for the release notes.
• The solution is tested.
• The documentation is up to date.
• The PR has a priority label.
• If the PR shouldn't be in the release notes, it has the
  C-exclude-from-changelog label.

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🔴 ⛓️ Depends-On Requirements

This rule is failing.

Requirement based on the presence of Depends-On in the body of the pull request

• depends-on = ZcashFoundation/zebra#9263 [⛓️ change(state): Refactor format upgrades into trait #9263]

[conradoplg]

I haven't fully reviewed this yet, but one thing I'm not sure about: don't we need to jump through hoops to make sure everything works during a database upgrade? Won't this code break trying to read values in the old format, or am I missing something?

[arya2]

Won't this code break trying to read values in the old format, or am I missing something?

The FromDisk impl for AddressBalanceLocation uses received_bytes.try_into().unwrap_or_default() to read the received bytes or default to 0 if it's in the old format.

(Unfortunately I don't think there's a good way to make the old code work with the new data format)

[arya2]

This condition is checking if the state contains only the genesis block, not if it's entirely empty.

Suggested change

	// Return early if there are no blocks in the state and the database is empty.
	// Note: The caller should (and as of this writing, does) return early if the database is empty anyway.
	if initial_tip_height.is_min() {
	return Ok(());
	}