Skip to content

key-wallet: reserve a specific address in AddressPool #1252

Open

Description

@romchornyi

Expected Behavior

key-wallet owns every AddressPool state transition, including Available -> Reserved for an address the caller has already chosen. Callers reserve and release a specific address through the pool, or through ManagedCoreFundsAccount, without writing AddressState themselves.

Current Behavior

AddressPool reserves only the next unused address (next_unused_and_reserve) and releases by index (release_reservation):

pub fn next_unused_and_reserve(&mut self, key_source: &KeySource, now: u64) -> Result<Address> {
for i in 0..=self.highest_generated.unwrap_or(0) {
if let Some(info) = self.addresses.get_mut(&i) {
if info.is_available() {
info.state = AddressState::Reserved {
at: now,
};
return Ok(info.address.clone());
}
}
}
if matches!(key_source, KeySource::NoKeySource) {
return Err(Error::NoKeySource);
}
let next_index = self.highest_generated.map(|h| h + 1).unwrap_or(0);
let address = self.generate_address_at_index(next_index, key_source, true)?;
// `generate_address_at_index` with `add_to_state = true` always inserts
// at `next_index`. If `highest_generated` ever drifts out of sync with
// `addresses` a silent lookup miss would return an unreserved address,
// reintroducing the hand-out race this method exists to close, so report
// the broken invariant as an error rather than fail open.
let info = self.addresses.get_mut(&next_index).ok_or_else(|| {
Error::InvalidState(format!(
"next_unused_and_reserve: generate_address_at_index({}) succeeded but \
the entry was not stored; pool invariant broken",
next_index
))
})?;
debug_assert!(info.is_available());
info.state = AddressState::Reserved {
at: now,
};
Ok(address)
}
/// Release a reservation, returning the address to the available pool.
///
/// Idempotent: returns `false` when the index is not currently reserved
/// (never reserved, already released, already used, or unknown index), and
/// `true` when a reservation was actually cleared.
pub fn release_reservation(&mut self, index: u32) -> bool {
if let Some(info) = self.addresses.get_mut(&index) {
if info.is_reserved() {
info.state = AddressState::Available;
return true;
}
}
false
}
/// Reclaim reservations older than `ttl`, returning their addresses to the

A caller that needs to reserve one particular address has to look up its AddressInfo and set AddressState::Reserved itself. The DashPay contact payment in platform-wallet does this: it pays the contact's next DIP-15 address, picked earlier at prepare time, and reserves exactly that one at send time.

https://github.com/dashpay/platform/blob/dfbeb7da9c9daf4a18fd55dfa00a72fd51d91fe3/packages/rs-platform-wallet/src/wallet/identity/network/prepared_payment.rs#L781-L795

Possible Solution

  • Add AddressPool::reserve_address(&mut self, address: &Address, now: u64) -> bool. It reserves the address only if it is available, never downgrading a used one, and returns whether it reserved it. It is the counterpart of release_reservation and stamps now the way next_unused_and_reserve does.
  • Expose reserve and release of a given address on ManagedCoreFundsAccount, covering whichever of the account's pools holds the address.
  • Tests: reserving an available address, refusing a used or already-reserved one, an unknown address, and a release after a reserve.

platform-wallet then calls this API from its helpers, after a dependency bump. The decisions stay in DashPay: when to reserve, which address, generation checks, persistence and settlement after the broadcast.

Steps to Reproduce

Not a runtime defect. This is a layering follow-up raised in review of dashpay/platform#5465.

Context

Suggested by a maintainer in dashpay/platform#5465 (contact payment prepare → send). It does not block that PR.

Your Environment

rust-dashcore @ aca0202 (the revision platform v5.1-dev pins).

🤖 Generated with Claude Code

Activity

  1. added a commit that references this issue on Nov 11, 2026
    0458fdd
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions