Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Reclaiming unspent stamps

See Fromboxes for what stamps are and why prepayment is required. This page covers the sithbit frombox reclaim command.

sithbit frombox reclaim <to_address> \
  [--keypair <keypair>] \
  [--skip-preflight]

reclaim takes back the postage you prepaid into someone else’s frombox and never spent. It is the sender’s counterpart to frombox close, which is the recipient’s sweep of the same account: close hands the whole balance to the recipient, reclaim returns only the unspent postage to the sender.

The frombox itself survives. Only the balance above the account’s rent-exemption reserve moves, so the account stays open at the price the recipient set — reclaiming is not a way to reset your standing with them, just a way to get idle postage out of escrow.

Only works for a wallet-address sender

A frombox is keyed on the blake3 hash of the sender’s “from” address, and this command works by reproducing that derivation from your signature: the program hashes your wallet’s address bytes and checks that the result names the frombox you passed. Reproducing the derivation is therefore the whole authorization — no separate ownership field exists, and no stranger can reach your frombox.

The flip side is that it only works when the “from” is a wallet address. A frombox keyed on an email string ([email protected]) hashes text that no wallet key can reproduce, so those stay recipient-managed: the recipient’s frombox close remains the only way their balance comes back out. If you expect to reclaim, buy postage against your wallet address.

Arguments

  • <to_address> — the recipient whose frombox holds your postage. Accepts a wallet address or an alias, which is resolved to its wallet.
  • --keypair <keypair> (short -k) — the sender’s keypair. This is the wallet the frombox is keyed on and the wallet the postage is returned to; defaults to the CLI’s configured key.
  • --skip-preflight (short -s) — skip the RPC pre-flight simulation.

Examples

Reclaim your unspent postage from the frombox a recipient holds for you:

sithbit frombox reclaim 7cVfgArCheMR6Cs29HXTFrpMg2XwYFhrCtdz3EgKPfHM

Reclaim as a specific wallet, naming the recipient by alias:

sithbit frombox reclaim jane_doe -k ~/.config/solana/id.json

Confirm the result — the stamp count reads zero and the balance is down to the account’s rent:

sithbit frombox get <your-wallet-address> jane_doe

On-chain effect

The ReclaimFromboxStamps instruction zeroes the frombox’s stamp count and moves everything above the rent-exemption reserve back to the signer. It carries no instruction data at all — the accounts and your signature say everything the program needs.

Reclaiming is not the only way that balance can come back out. The recipient’s frombox close still sweeps whatever residual a sender leaves behind, so this is the sender’s proactive recovery path rather than an exclusive claim on the escrow — see frombox custody in the threat model for why custody is arranged that way.

  • Add stamps — the purchase this reverses, including the slippage guard that keeps a purchase from overpaying in the first place.
  • Looking up a frombox — check the stamp count and balance before and after.
  • Closing accounts — the recipient’s side: closing the frombox and reclaiming its rent along with any residual.