`stellar contract restore`: tell users whether a restore fits in one transaction, and how many it needs

[oceans404]

What problem does your feature solve?

If you hold a large set of archived entries, there is no way to find out whether restoring them fits in a single transaction. stellar contract restore puts every requested key into one RestoreFootprint footprint and submits it. If that exceeds per-transaction resource limits, the user finds out from a failure and then splits the key set by hand until it works.

This is the part of "can I get this state back, and how" that a user cannot work out on their own. Fee and resource display is already tracked in #2401.

What would you like to see?

A dry-run mode on stellar contract restore that simulates instead of submitting, and answers two questions:

1. Does this restore fit within per-transaction resource limits?
2. If not, what is the minimum number of restore transactions required, and which keys go in each one?

Something like:

Restore plan (testnet): 3 transactions, 60 entries

Exceeds per-transaction limits:
  Disk read entries    60 > 40
  Write bytes     124,800 > 66,560

  tx 1   24 entries
  tx 2   24 entries
  tx 3   12 entries

Exact flag, output shape, and approach are up to whoever picks this up. Two requirements: limits come from network config rather than hardcoded values, and the plan has to respect all resource limits at once, not just the first one that trips.

Out of scope

• Rendering resource usage and fees. stellar tx simulate should show expected resources usage and fees #2401 covers that for tx simulate across every operation type. This issue should build on it, not duplicate it.
• Submitting the split sequence. Reporting a plan is the deliverable. Executing it can follow.

Context

The transaction building and simulation plumbing already exists. contract/restore.rs builds the RestoreFootprint transaction and already separates building from submitting via --build-only, and simulate_and_assemble_transaction returns the assembled resources.

Two things to know going in:

• Simulation returns footprint totals, not per-entry sizes, so grouping keys into transactions needs sizes per key from somewhere else.
• restore.rs carries the comment // We only support restoring a single entry via this command (which we should fix separately, but). This feature is about large key sets, so that limitation likely needs fixing first.

The limit comparison and a plain fits / does-not-fit answer is a small self-contained first change. The grouping math can follow.

Open question

Nobody currently owns the total XLM cost of an N-transaction restore plan. #2401 gives cost per transaction, and a single simulation cannot give the total for a plan. If users want one number for "what does restoring this key set cost me," it belongs here.

Related

• stellar tx simulate should show expected resources usage and fees #2401 stellar tx simulate should show expected resources usage and fees
• stellar contract restore: if an entry is already restored as of the simulation, we should not submit the tx to the network #2201 stellar contract restore: if an entry is already restored as of the simulation, we should not submit the tx to the network
• Return simulation budget information even in case of error #1019 Return simulation budget information even in case of error